Latest commit 3a48ff7
Oct 31, 2015
|Failed to load latest commit information.|
Curlicue ======== Curlicue is a small wrapper script that invokes curl with the necessary headers for OAuth. It should run on any POSIX-compatible shell. Keys, tokens, and secrets are stored in text files as form-encoded data. Usage ----- A Curlicue command looks like the equivalent curl command, with some extra options at the beginning: curlicue [-f FILE ...] [-p PARAMS] [-P] [-- CURL_OPTS] URL OAuth credentials are read from FILE(s). If you don't specify any FILEs with -f, Curlicue will try to read credentials from ~/.curlicue/HOST, where HOST is the hostname component of your URL. Extra OAuth parameters, if any, are specified with -p; these parameters should be URL-encoded and separated with &. Either -- or a URL (any argument starting with "http") ends processing of Curlicue parameters and passes all further options along to curl. These options will be checked for the -d/--data or -X/--request, since adding application/x-www-form-urlencoded POST parameters or otherwise changing the HTTP method will change the OAuth signature base string. If you are sending POST data with some other content-type, specify -P (before the options that are passed along to curl) to disable treating POST data as parameters. Installation ------------ Curlicue is now split up into several scripts, so you will need to install at least curlicue and curl-encode to a directory in your PATH. This can be done with: install curlicue curl-encode /usr/local/bin You may also want to include curlicue-setup and the scripts in contrib. Setup ----- To perform the initial OAuth "dance", run curlicue-setup with four arguments: the request token URL, the user authorization URL, the access token URL, and a file to output credentials to. Typically, this will look something like: curlicue-setup \ 'https://oauth.provider/request_token' \ 'https://oauth.provider/authorize?oauth_token=$oauth_token' \ 'https://oauth.provider/access_token' \ credentials In the user authorization URL (only), variables from the consumer information or request token can be interpolated using shell syntax. Your provider may need additional URL parameters for one or more of the steps; consult their documentation. You will be prompted for the consumer key and secret. For examples of how this works with several popular OAuth providers, refer to EXAMPLES. Included Scripts ---------------- The contrib directory contains some scripts that demonstrate what you can do with Curlicue: * twitpull - display data from a Twitter API endpoint as plain text, using jq. Supports using cursors to fetch things that don't fit in a single response. Walkthrough ----------- To demonstrate the authentication process in detail, let's work through what happens when you run curlicue-setup with Twitter as a previously registered application. Before creating any files (which will all contain secrets), we should set our umask so that no one else can read them: umask 077 The first step in OAuth is obtaining a request token. To make that request, we'll need a file containing the consumer key and secret (make sure that their values are URL-encoded): cat << EOF > consumer oauth_consumer_key=KEY&oauth_consumer_secret=SECRET EOF With that, let's get the token. We're not a web app, so we use the "out of band" callback method: curlicue -f consumer -p 'oauth_callback=oob' -- \ -X POST https://api.twitter.com/oauth/request_token > request_token The arguments passed along to curl are parsed to get the HTTP method and URL so that the request can be signed. Now we need to approve the app. We can build URLs with the -e option, which just echoes a string back to us (with parameters from the files read with -f filled in) instead of running curl. curlicue -f request_token -e \ 'https://api.twitter.com/oauth/authorize?oauth_token=$oauth_token' Visiting this URL in our browser and selecting "Allow" will give us a PIN, which we can in turn use to obtain an access token: curlicue -f consumer -f request_token -p 'oauth_verifier=PIN' -- \ -X POST https://api.twitter.com/oauth/access_token > access_token Note that we need to read in both the consumer and token information from here on. Now we can actually make an interesting request: curlicue -f consumer -f access_token \ https://api.twitter.com/1/statuses/home_timeline.xml In this case, we are not passing any options along to curl, so the -- can be omitted. Finally, to make our command line shorter, we can concatenate the consumer and token into one file: paste -d '&' consumer access_token > credentials And remove all the intermediate files (consumer, request_token, and access_token). Limitations ----------- --data-urlencode, --data-binary, and reading POST data from a file are not yet supported. Dependencies ------------ OpenSSL is used for HMAC-SHA1 signing and nonce generation. Thanks ------ To Alex Payne for suggesting the name. Legal ----- Copyright © 2010 Decklin Foster <firstname.lastname@example.org>. This program is distributed under the MIT license; see LICENSE for details.