Fetching latest commit…
Cannot retrieve the latest commit at this time.
|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] [-- CURL_OPTS] URL OAuth credentials are read from FILE(s). Extra OAuth parameters, if any, are specified with -p. Parameters in files or in the arugment to -p should be percent-encoded and separated with &. Either -- or a URL ends processing of Curlicue parameters and passes the rest along to curl. If you don't specify any FILEs, Curlicue will try to read credentials from ~/.curlicue/HOST, where HOST is the hostname component of your URL. 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 various Twitter API endpoints as plain text, using XMLStarlet. For endpoints that support it, handles using a cursor parameter to fetch the entirety of long lists with multiple requests. 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 percent-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' -- \ -d '' '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 req_token -p 'oauth_verifier=PIN' -- \ -d '' '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.