oauth.h

00001 /**
00002  *  @brief OAuth.net implementation in POSIX-C.
00003  *  @file oauth.h
00004  *  @author Robin Gareus <robin@gareus.org>
00005  *
00006  * Copyright 2007-2010 Robin Gareus <robin@gareus.org>
00007  *
00008  * Permission is hereby granted, free of charge, to any person obtaining a copy
00009  * of this software and associated documentation files (the "Software"), to deal
00010  * in the Software without restriction, including without limitation the rights
00011  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00012  * copies of the Software, and to permit persons to whom the Software is
00013  * furnished to do so, subject to the following conditions:
00014  * 
00015  * The above copyright notice and this permission notice shall be included in
00016  * all copies or substantial portions of the Software.
00017  * 
00018  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00019  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00020  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00021  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00022  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00023  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00024  * THE SOFTWARE.
00025  *
00026  */
00027 #ifndef _OAUTH_H
00028 #define _OAUTH_H      1 
00029 
00030 #include <vector>
00031 #include <string>
00032 
00033 #ifndef DOXYGEN_IGNORE
00034 // liboauth version
00035 #define LIBOAUTH_VERSION "0.8.9"
00036 #define LIBOAUTH_VERSION_MAJOR  0
00037 #define LIBOAUTH_VERSION_MINOR  8
00038 #define LIBOAUTH_VERSION_MICRO  9
00039 
00040 //interface revision number
00041 //http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
00042 #define LIBOAUTH_CUR  7
00043 #define LIBOAUTH_REV  0
00044 #define LIBOAUTH_AGE  7
00045 #endif
00046 
00047 #ifdef __GNUC__
00048 #    define OA_GCC_VERSION_AT_LEAST(x,y) (__GNUC__ > x || __GNUC__ == x && __GNUC_MINOR__ >= y)
00049 #else
00050 #    define OA_GCC_VERSION_AT_LEAST(x,y) 0
00051 #endif
00052 
00053 #ifndef attribute_deprecated
00054 #if OA_GCC_VERSION_AT_LEAST(3,1)
00055 #    define attribute_deprecated __attribute__((deprecated))
00056 #else
00057 #    define attribute_deprecated
00058 #endif
00059 #endif
00060 
00061 /** \enum OAuthMethod
00062  * signature method to used for signing the request.
00063  */ 
00064 typedef enum { 
00065     OA_HMAC=0, ///< use HMAC-SHA1 request signing method
00066     OA_RSA, ///< use RSA signature 
00067     OA_PLAINTEXT ///< use plain text signature (for testing only)
00068   } OAuthMethod;
00069 
00070 /**
00071  * Base64 encode and return size data in 'src'. The caller must free the
00072  * returned string.
00073  *
00074  * @param size The size of the data in src
00075  * @param src The data to be base64 encode
00076  * @return encoded string otherwise NULL
00077  */
00078 std::string oauth_encode_base64(const unsigned char *src, int size);
00079 
00080 /**
00081  * Decode the base64 encoded string 'src' into the memory pointed to by
00082  * 'dest'. 
00083  *
00084  * @param dest Pointer to memory for holding the decoded string.
00085  * Must be large enough to receive the decoded string.
00086  * @param src A base64 encoded string.
00087  * @return the length of the decoded string if decode
00088  * succeeded otherwise 0.
00089  */
00090 std::string oauth_decode_base64(const char *src);
00091 
00092 /**
00093  * Escape 'string' according to RFC3986 and
00094  * http://oauth.net/core/1.0/#encoding_parameters.
00095  *
00096  * @param string The data to be encoded
00097  * @return encoded string otherwise NULL
00098  * The caller must free the returned string.
00099  */
00100 std::string oauth_url_escape(const char *string);
00101 
00102 /**
00103  * Parse RFC3986 encoded 'string' back to  unescaped version.
00104  *
00105  * @param string The data to be unescaped
00106  * @param olen unless NULL the length of the returned string is stored there.
00107  * @return decoded string or NULL
00108  * The caller must free the returned string.
00109  */
00110 std::string oauth_url_unescape(const char *string);
00111  
00112 
00113 /**
00114  * returns base64 encoded HMAC-SHA1 signature for
00115  * given message and key.
00116  * both data and key need to be urlencoded.
00117  *
00118  * the returned string needs to be freed by the caller
00119  *
00120  * @param m message to be signed
00121  * @param k key used for signing
00122  * @return signature string.
00123  */
00124 std::string oauth_sign_hmac_sha1 (const char *m, const char *k);
00125 
00126 /**
00127  * same as \ref oauth_sign_hmac_sha1 but allows
00128  * to specify length of message and key (in case they contain null chars).
00129  *
00130  * @param m message to be signed
00131  * @param ml length of message
00132  * @param k key used for signing
00133  * @param kl length of key
00134  * @return signature string.
00135  */
00136 std::string oauth_sign_hmac_sha1_raw(const char *m, const size_t ml, const char *k, const size_t kl);
00137 
00138 /**
00139  * returns plaintext signature for the given key.
00140  *
00141  * the returned string needs to be freed by the caller
00142  *
00143  * @param m message to be signed
00144  * @param k key used for signing
00145  * @return signature string
00146  */
00147 std::string oauth_sign_plaintext(const char *m, const char *k);
00148 
00149 /**
00150  * returns RSA-SHA1 signature for given data.
00151  * the returned signature needs to be freed by the caller.
00152  *
00153  * @param m message to be signed
00154  * @param k private-key PKCS and Base64-encoded 
00155  * @return base64 encoded signature string.
00156  */
00157 //std::string oauth_sign_rsa_sha1 (const char *m, const char *k);
00158 
00159 /**
00160  * verify RSA-SHA1 signature.
00161  *
00162  * returns the output of EVP_VerifyFinal() for a given message,
00163  * cert/pubkey and signature.
00164  *
00165  * @param m message to be verified
00166  * @param c public-key or x509 certificate
00167  * @param s base64 encoded signature
00168  * @return 1 for a correct signature, 0 for failure and -1 if some other error occurred
00169  */
00170 int oauth_verify_rsa_sha1(const char *m, const char *c, const char *s);
00171 
00172 /**
00173  * url-escape strings and concatenate with '&' separator.
00174  * The number of strings to be concatenated must be
00175  * given as first argument.
00176  * all arguments thereafter must be of type (char *) 
00177  *
00178  * @param len the number of arguments to follow this parameter
00179  *
00180  * @return pointer to memory holding the concatenated 
00181  * strings - needs to be free(d) by the caller. or NULL
00182  * in case we ran out of memory.
00183  */
00184 std::string oauth_catenc(int len, ...);
00185 
00186 /**
00187  * splits the given url into a parameter array. 
00188  * (see \ref oauth_serialize_url and \ref oauth_serialize_url_parameters for the reverse)
00189  * (see \ref oauth_split_post_paramters for a more generic version)
00190  *
00191  * @param url the url or query-string to parse; may be NULL
00192  * @param argv pointer to a (char *) array where the results are stored.
00193  *  The array is re-allocated to match the number of parameters and each 
00194  *  parameter-string is allocated with strdup. - The memory needs to be freed
00195  *  by the caller.
00196  * 
00197  * @return number of parameter(s) in array.
00198  */
00199 void oauth_split_url_parameters(const char *url, std::vector<std::string> *argv);
00200 
00201 /**
00202  * splits the given url into a parameter array. 
00203  * (see \ref oauth_serialize_url and \ref oauth_serialize_url_parameters for the reverse)
00204  *
00205  * @param url the url or query-string to parse. 
00206  * @param argv pointer to a (char *) array where the results are stored.
00207  *  The array is re-allocated to match the number of parameters and each 
00208  *  parameter-string is allocated with strdup. - The memory needs to be freed
00209  *  by the caller.
00210  * @param qesc use query parameter escape (vs post-param-escape) - if set
00211  *        to 1 all '+' are treated as spaces ' '
00212  * 
00213  * @return number of parameter(s) in array.
00214  */
00215 void oauth_split_post_paramters(const char *url, std::vector<std::string> *argv, short qesc);
00216 
00217 /**
00218  * build a url query string from an array.
00219  *
00220  * @param argc the total number of elements in the array
00221  * @param start element in the array at which to start concatenating.
00222  * @param argv parameter-array to concatenate.
00223  * @return url string needs to be freed by the caller.
00224  *
00225  */
00226 std::string oauth_serialize_url (std::vector<std::string> const &argv, int start);
00227 
00228 /**
00229  * encode query parameters from an array.
00230  *
00231  * @param argc the total number of elements in the array
00232  * @param start element in the array at which to start concatenating.
00233  * @param argv parameter-array to concatenate.
00234  * @param sep separator for parameters (usually "&") 
00235  * @param mod - bitwise modifiers: 
00236  *   1: skip all values that start with "oauth_"
00237  *   2: skip all values that don't start with "oauth_"
00238  *   4: double quotation marks are added around values (use with sep ", " for HTTP Authorization header).
00239  * @return url string needs to be freed by the caller.
00240  */
00241 std::string oauth_serialize_url_sep (std::vector<std::string> const &argv, int start, char const *sep, int mod);
00242 
00243 /**
00244  * build a query parameter string from an array.
00245  *
00246  * This function is a shortcut for \ref oauth_serialize_url (argc, 1, argv). 
00247  * It strips the leading host/path, which is usually the first 
00248  * element when using oauth_split_url_parameters on an URL.
00249  *
00250  * @param argc the total number of elements in the array
00251  * @param argv parameter-array to concatenate.
00252  * @return url string needs to be freed by the caller.
00253  */
00254 std::string oauth_serialize_url_parameters (std::vector<std::string> const &argv);
00255  
00256 /**
00257  * generate a random string between 15 and 32 chars length
00258  * and return a pointer to it. The value needs to be freed by the
00259  * caller
00260  *
00261  * @return zero terminated random string.
00262  */
00263 std::string oauth_gen_nonce();
00264 
00265 /**
00266  * string compare function for oauth parameters.
00267  *
00268  * used with qsort. needed to normalize request parameters.
00269  * see http://oauth.net/core/1.0/#anchor14
00270  */
00271 int oauth_cmpstringp(const void *p1, const void *p2);
00272 
00273 
00274 /**
00275  * search array for parameter key.
00276  * @param argv length of array to search
00277  * @param argc parameter array to search
00278  * @param key key of parameter to check.
00279  *
00280  * @return FALSE (0) if array does not contain a parameter with given key, TRUE (1) otherwise.
00281  */
00282 bool oauth_param_exists(std::vector<std::string> const &argv, char const *key);
00283 
00284 /**
00285  * free array args
00286  *
00287  * @param argcp pointer to array length int
00288  * @param argvp pointer to array values to be free()d
00289  */
00290 void oauth_free_array(int *argcp, std::vector<std::string> *argvp);
00291 
00292 /**
00293  * calculate OAuth-signature for a given HTTP request URL, parameters and oauth-tokens.
00294  *
00295  * if 'postargs' is NULL a "GET" request is signed and the 
00296  * signed URL is returned. Else this fn will modify 'postargs' 
00297  * to point to memory that contains the signed POST-variables 
00298  * and returns the base URL.
00299  *
00300  * both, the return value and (if given) 'postargs' need to be freed
00301  * by the caller.
00302  *
00303  * @param url The request URL to be signed. append all GET or POST 
00304  * query-parameters separated by either '?' or '&' to this parameter.
00305  *
00306  * @param postargs This parameter points to an area where the return value
00307  * is stored. If 'postargs' is NULL, no value is stored.
00308  *
00309  * @param method specify the signature method to use. It is of type 
00310  * \ref OAuthMethod and most likely \ref OA_HMAC.
00311  *
00312  * @param http_method The HTTP request method to use (ie "GET", "PUT",..)
00313  * If NULL is given as 'http_method' this defaults to "GET" when 
00314  * 'postargs' is also NULL and when postargs is not NULL "POST" is used.
00315  *
00316  * @param c_key consumer key
00317  * @param c_sec consumer secret
00318  * @param t_key token key
00319  * @param t_sec token secret
00320  *
00321  * @return the signed url or NULL if an error occurred.
00322  *
00323  */
00324 std::string oauth_sign_url2 (const char *url, std::string *postargs, 
00325   OAuthMethod method, 
00326   const char *http_method, //< HTTP request method
00327   const char *c_key, //< consumer key - posted plain text
00328   const char *c_sec, //< consumer secret - used as 1st part of secret-key 
00329   const char *t_key, //< token key - posted plain text in URL
00330   const char *t_sec //< token secret - used as 2st part of secret-key
00331   );
00332 
00333 /**
00334  * @deprecated Use oauth_sign_url2() instead.
00335  */
00336 std::string oauth_sign_url (const char *url, std::string *postargs, 
00337   OAuthMethod method, 
00338   const char *c_key, //< consumer key - posted plain text
00339   const char *c_sec, //< consumer secret - used as 1st part of secret-key 
00340   const char *t_key, //< token key - posted plain text in URL
00341   const char *t_sec //< token secret - used as 2st part of secret-key
00342   ) attribute_deprecated;
00343 
00344 
00345 /**
00346  * the back-end behind by /ref oauth_sign_array2.
00347  * however it does not serialize the signed URL again.
00348  * The user needs to call /ref oauth_serialize_url (oA)
00349  * and /ref oauth_free_array to do so.
00350  *
00351  * This allows to split parts of the URL to be used for
00352  * OAuth HTTP Authorization header:
00353  * see http://oauth.net/core/1.0a/#consumer_req_param
00354  * the oauthtest2 example code does so.
00355  * 
00356  *
00357  * @param argcp pointer to array length int
00358  * @param argvp pointer to array values  
00359  * (argv[0]="http://example.org:80/" argv[1]="first=QueryParamater" ..
00360  *  the array is modified: fi. oauth_ parameters are added)
00361  *  These arrays can be generated with /ref oauth_split_url_parameters
00362  *  or /ref oauth_split_post_paramters.
00363  *
00364  * @param postargs This parameter points to an area where the return value
00365  * is stored. If 'postargs' is NULL, no value is stored.
00366  *
00367  * @param method specify the signature method to use. It is of type 
00368  * \ref OAuthMethod and most likely \ref OA_HMAC.
00369  *
00370  * @param http_method The HTTP request method to use (ie "GET", "PUT",..)
00371  * If NULL is given as 'http_method' this defaults to "GET" when 
00372  * 'postargs' is also NULL and when postargs is not NULL "POST" is used.
00373  *
00374  * @param c_key consumer key
00375  * @param c_sec consumer secret
00376  * @param t_key token key
00377  * @param t_sec token secret
00378  *
00379  * @return void
00380  *
00381  */
00382 void oauth_sign_array2_process (std::vector<std::string> *argvp,
00383   std::string *postargs,
00384   OAuthMethod method, 
00385   const char *http_method, //< HTTP request method
00386   const char *c_key, //< consumer key - posted plain text
00387   const char *c_sec, //< consumer secret - used as 1st part of secret-key 
00388   const char *t_key, //< token key - posted plain text in URL
00389   const char *t_sec //< token secret - used as 2st part of secret-key
00390   );
00391 
00392 /**
00393  * same as /ref oauth_sign_url
00394  * with the url already split into parameter array 
00395  *
00396  * @param argcp pointer to array length int
00397  * @param argvp pointer to array values  
00398  * (argv[0]="http://example.org:80/" argv[1]="first=QueryParamater" ..
00399  *  the array is modified: fi. oauth_ parameters are added)
00400  *  These arrays can be generated with /ref oauth_split_url_parameters
00401  *  or /ref oauth_split_post_paramters.
00402  *
00403  * @param postargs This parameter points to an area where the return value
00404  * is stored. If 'postargs' is NULL, no value is stored.
00405  *
00406  * @param method specify the signature method to use. It is of type 
00407  * \ref OAuthMethod and most likely \ref OA_HMAC.
00408  *
00409  * @param http_method The HTTP request method to use (ie "GET", "PUT",..)
00410  * If NULL is given as 'http_method' this defaults to "GET" when 
00411  * 'postargs' is also NULL and when postargs is not NULL "POST" is used.
00412  *
00413  * @param c_key consumer key
00414  * @param c_sec consumer secret
00415  * @param t_key token key
00416  * @param t_sec token secret
00417  *
00418  * @return the signed url or NULL if an error occurred.
00419  */
00420 std::string oauth_sign_array2 (std::vector<std::string> *argvp,
00421   std::string *postargs,
00422   OAuthMethod method, 
00423   const char *http_method, //< HTTP request method
00424   const char *c_key, //< consumer key - posted plain text
00425   const char *c_sec, //< consumer secret - used as 1st part of secret-key 
00426   const char *t_key, //< token key - posted plain text in URL
00427   const char *t_sec //< token secret - used as 2st part of secret-key
00428   );
00429 
00430 /**
00431  * @deprecated Use oauth_sign_array2() instead.
00432  */
00433 char *oauth_sign_array (
00434     std::vector<std::string> *argvp,
00435     char **postargs,
00436     OAuthMethod method, 
00437     const char *c_key, //< consumer key - posted plain text
00438     const char *c_sec, //< consumer secret - used as 1st part of secret-key 
00439     const char *t_key, //< token key - posted plain text in URL
00440     const char *t_sec //< token secret - used as 2st part of secret-key
00441     ) attribute_deprecated;
00442 
00443 /**
00444  * do a HTTP GET request, wait for it to finish 
00445  * and return the content of the reply.
00446  * (requires libcurl or a command-line HTTP client)
00447  *
00448  * If compiled <b>without</b> libcurl this function calls
00449  * a command-line executable defined in the environment variable
00450  * OAUTH_HTTP_GET_CMD - it defaults to 
00451  * <tt>curl -sA 'liboauth-agent/0.1' '%%u'</tt>
00452  * where %%u is replaced with the URL and query parameters.
00453  *
00454  * bash & wget example:
00455  * <tt>export OAUTH_HTTP_CMD="wget -q -U 'liboauth-agent/0.1' '%u' "</tt>
00456  *
00457  * WARNING: this is a tentative function. it's convenient and handy for testing
00458  * or developing OAuth code. But don't rely on this function
00459  * to become a stable part of this API. It does not do 
00460  * much error checking or handling for one thing..
00461  *
00462  * NOTE: \a u and \a q are just concatenated with a '?' in between,
00463  * unless \a q is NULL. in which case only \a u will be used.
00464  *
00465  * @param u base url to get
00466  * @param q query string to send along with the HTTP request or NULL.
00467  * @return  In case of an error NULL is returned; otherwise a pointer to the
00468  * replied content from HTTP server. latter needs to be freed by caller.
00469  */
00470 std::string oauth_http_get_(const char *u, const char *q);
00471 
00472 /**
00473  * do a HTTP POST request, wait for it to finish 
00474  * and return the content of the reply.
00475  * (requires libcurl or a command-line HTTP client)
00476  *
00477  * If compiled <b>without</b> libcurl this function calls
00478  * a command-line executable defined in the environment variable
00479  * OAUTH_HTTP_CMD - it defaults to 
00480  * <tt>curl -sA 'liboauth-agent/0.1' -d '%%p' '%%u'</tt>
00481  * where %%p is replaced with the postargs and %%u is replaced with 
00482  * the URL. 
00483  *
00484  * bash & wget example:
00485  * <tt>export OAUTH_HTTP_CMD="wget -q -U 'liboauth-agent/0.1' --post-data='%p' '%u' "</tt>
00486  *
00487  * NOTE: This function uses the curl's default HTTP-POST Content-Type:
00488  * application/x-www-form-urlencoded which is the only option allowed
00489  * by oauth core 1.0 spec. Experimental code can use the Environment variable
00490  * to transmit custom HTTP headers or parameters.
00491  *
00492  * WARNING: this is a tentative function. it's convenient and handy for testing
00493  * or developing OAuth code. But don't rely on this function
00494  * to become a stable part of this API. It does not do 
00495  * much error checking for one thing..
00496  *
00497  * @param u url to query
00498  * @param p postargs to send along with the HTTP request.
00499  * @return replied content from HTTP server. needs to be freed by caller.
00500  */
00501 std::string oauth_http_post_(const char *u, const char *p);
00502 
00503 #endif