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