====== OAuth ======

[[http://oauth.net|OAuth]] is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.

**liboauth** provides functionality to encode URLs and sign requests according to the [[http://oauth.net|OAuth]] standard, implemented in compatible POSIX-C.

**oauth-utils** is //a collection//((so far there's only ''oauthsign'', ''oauthverify'' and an example shell script. other utils eg. ''oauthrawpost'' are in the making. see also [[http://trac.mediamatic.nl/picnic/browser/tools/anymeta|mediamatic-picnic OAuth tools]])) of command-line tools implementing an OAuth consumer. 

===== Documentation =====
  * [[http://gareus.org/dox/oauth/|liboauth doxygen]] - Source Code Documentation
  * oauth-tools has a built-in ''--help''
 
//man//ual pages are available for both 

===== Download =====
<note r9>liboauth is now maintained at http://liboauth.sf.net/ - Thanks to sourceforge.\\ and http://oauth.googlecode.com/svn/code/c/liboauth/ - Thanks to google.</note>

**Source**
  * [[http://gareus.org/gitweb/?p=liboauth.git;a=summary|liboauth]] browse git repository
  * [[http://gareus.org/gitweb/?p=oauth-utils.git;a=summary|oauth-utils]] browse git repository
  * {{:oss:oauth:oauth-utils-0.3.2.tar.gz|oauth-utils-0.3.2.tar.gz}} oauth-utils source (incl. ''configure'' script, without ''debian'' folder)
  * [[http://gareus.org/gitweb/?p=oauth-utils.git;a=snapshot;h=HEAD|devel snapshot]] latest version of oauth-utils source (including ''debian'', requires autotools)

**Build debian packages**
  git clone git://gareus.org/liboauth
  cd liboauth
  git branch upstream 
  #make maintainer-clean
  git-buildpackage
  #make check
  cd .. && sudo dpkg -i liboauth*.deb
  
  git clone git://gareus.org/oauth-utils
  cd oauth-utils
  git branch upstream
  #make maintainer-clean
  git-buildpackage
  #make check # connects to http://term.ie/oauth/example !
  cd .. && sudo dpkg -i oauth-utils*.deb

===== oauthsign usage and example =====

Both //oauthsign// and //oauthverify// are documented in un*x manual pages. You may want to <del>consult</del> proof-read ''man oauth-utils'' as well.
\\
\\
** usage examples **\\
perform requests with fixed tokens
  oauthsign -c consumer-key -C "" -t access-token -T token-secret 'http://example.org/?do=admin'
  oauthsign -X -d "do=requesttoken" 'http://example.org/' consumer-key ""

//debug oAuth parameters// - print oauth base-string:
  oauthsign -b -c consumer-key -C "" -t access-token -T token-secret 'http://example.org/?do=admin'
\\
\\
** test server walk-through **\\
see also ''example.sh'' below.

Get a request-token for the consumer ''key'' with consumer-secret ''secret'' from the server and save it to ''/tmp/test.oaf'':
  oauthsign -X -f /tmp/test.oaf -w -e -c key -C secret http://term.ie/oauth/example/request_token.php
\\
Exchange this request-token for an access token and replace the token+secret in ''/tmp/test.oaf'':
  oauthsign -X -f /tmp/test.oaf -w http://term.ie/oauth/example/access_token.php
\\
Perform some requests with the consumer and access token/secrets in same file:
  oauthsign -x -f /tmp/test.oaf "http://term.ie/oauth/example/echo_api.php?method=foo%20bar&bar=baz"
  oauthsign -x -f /tmp/test.oaf -d method=foo%20bar -d "bar=baz &test%" --post http://term.ie/oauth/example/echo_api.php
\\
\\
**output of oauthsign --help **\\
<code>
oauthsign - command line utilities for oauth
Usage: ./src/oauthsign [OPTION]... URL [CKey] [CSec] [TKey] [Tsec]
Options:
  -h, --help                  display this help and exit
  -V, --version               output version information and exit
  -q, --quiet, --silent       inhibit usual output
  -v, --verbose               print more information
  --no-warn                   dont print any warnings.
  
  -b, --base-string           print OAuth base-string and exit
  -B, --base-url              print OAuth base-URL and exit
  -r, --request <type>        HTTP request type (HEAD, PUT, POST, GET [default],..)
  -p, --post                  same as -r POST
  -d, --data <key>[=<val>]    add url query parameters.
  -m, --signature-method <m>  oauth signature method (PLAINTEXT,
                              RSA-SHA1, HMAC-SHA1 [default])
  
  -c, --CK, --consumer-key    <text> 
  -C, --CS, --consumer-secret <text> 
  -t, --TK, --token-key       <text> 
  -T, --TS, --token-secret    <text> 
    
  -a, --callback <url>        specify oauth_callback url (or 'oob') // 1.0 Rev A
  -A, --verifier <text>       specify oauth_verifier // 1.0 Rev A

  -f, --file <filename>       read tokens and secrets from config-file
  -w                          write tokens to config-file
  -F <filename>               set config-file name w/o reading the file.
  -x                          make HTTP request and return the replied content
  -X                          make HTTP request and parse the reply for tokens
                              use '-X -w' to request and store tokens.
  --dry-run                   take no real actions (with -x, -w or -X)
  -e, --erase-tokens          clear [access|request] tokens.
  -E, --erase-all             wipe all tokens and reset method to HMAC-SHA1.
  --erase-consumer-key        unset consumer-key
  --erase-consumer-secret     unset consumer-secret
  --erase-token-key           unset token-key
  --erase-token-secret        unset token-secret
  
  The position of parameters -d, -f, -F, -e, -E and all tokens matters!
  
  Tokens are read from file at the moment the -f option is parsed overriding 
  the current value(s). Optional trailing key/secret params are parsed last.
  eg.
    '-f config.txt -e -C secret -F out.txt -w' reads the settings from file,
  then deletes the access/request tokens and finally overrides the consumer-
  secret. Only the consumer-key is left from config.txt and will be saved 
  to out.txt along with the new secret. If -X is given and the HTTP request
  succeeds, the received token and secret will be stored as well.
  
  The request URL is constructed by first parsing all query-parameters from
  the URL; then -d parameters are added, and finally oauth_XYZ params 
  appended.
</code>

<code|h doc/example.sh from oauth-utils|h>
extern>http://gareus.org/gitweb/?p=oauth-utils.git;a=blob_plain;f=doc/example.sh;hb=HEAD
</code>

Note: As shown in above example RSA-keys can currently be given instead of a consumer-secret (public-key for ''oauthsign'', private-key for ''oauthverify''). This is going to change. Future versions may use ''--rsa-private'', ''--rsa-public'' and also provide for reading the key from file.

===== oauthverify usage and example =====

//oauthverify// is the counter-part and very similar to //oauthsign//: It parses all request-parameters (those appended to the URL after a '?' and the ones given to //oauthverify// with ''-d'' command line option) one of which must be the oauth_signature to verify. 

To recalculate the signature the consumer (and token) **secrets** must be specified (fi. ''-C'' and ''-T'') or read from file.  If a consumer-**key**, token-**key** or signature-method is set (eg. ''-c'' or ''-t'', ''-m''), they're required to match the ones in the parsed request-parameters. You can use ''--erase-consumer-key'' etc. to relax such a requirement when reading tokens along with the secrets from a file.

If the signature is correct and if the consumer/token key matches the given parameters (if any) oauthverify exits with a status code indicating success and prints the parsed request-parameters formatted as POST parameters (more output options to come: ''--print0'' or ''-0'', JSON is the contender)

Note that //oauthverify// does **not** keep track of consumers, token-mappings, timestamps and nonce (never more than once) identifiers. If the signature matches it prints them for others to use.
 
  oauthverify -C secret `oauthsign -c key -C secret http://example.org`

====== Resources ======

  * [[wiki:dokuoauth]] - DokuWiki OAuth plugin
  * [[http://tools.ietf.org/html/rfc5849|RFC 5849]] -- OAuth specs 
  * http://www.marcworrell.com/article-2943-en.html - OAuth URI encoding
  * <del>http://oauth-sandbox.mediamatic.nl/ - testsandbox</del>
  * http://term.ie/oauth/example/ - test server
  * How to [[osx-static|statically link liboauth]] with your app.

{{tag>FLOSS WWW}}