src/oauth.h

   1 /**
   2  *  @brief OAuth.net implementation in POSIX-C.
   3  *  @file oauth.h
   4  *  @author Robin Gareus <robin@gareus.org>
   5  *
   6  * Copyright 2007-2014 Robin Gareus <robin@gareus.org>
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a copy
   9  * of this software and associated documentation files (the "Software"), to deal
  10  * in the Software without restriction, including without limitation the rights
  11  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  12  * copies of the Software, and to permit persons to whom the Software is
  13  * furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  21  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  23  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  24  * THE SOFTWARE.
  25  *
  26  */
  27 #ifndef _OAUTH_H
  28 #define _OAUTH_H      1
  29
  30 #ifndef DOXYGEN_IGNORE
  31 // liboauth version
  32 #define LIBOAUTH_VERSION "1.0.3"
  33 #define LIBOAUTH_VERSION_MAJOR  1
  34 #define LIBOAUTH_VERSION_MINOR  0
  35 #define LIBOAUTH_VERSION_MICRO  3
  36
  37 //interface revision number
  38 //http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
  39 #define LIBOAUTH_CUR  8
  40 #define LIBOAUTH_REV  7
  41 #define LIBOAUTH_AGE  8
  42
  43 #ifdef __GNUC__
  44 #    define OA_GCC_VERSION_AT_LEAST(x,y) (__GNUC__ > x || __GNUC__ == x && __GNUC_MINOR__ >= y)
  45 #else
  46 #    define OA_GCC_VERSION_AT_LEAST(x,y) 0
  47 #endif
  48
  49 #ifndef attribute_deprecated
  50 #if OA_GCC_VERSION_AT_LEAST(3,1)
  51 #    define attribute_deprecated __attribute__((deprecated))
  52 #else
  53 #    define attribute_deprecated
  54 #endif
  55 #endif
  56
  57 #endif /* doxygen ignore */
  58
  59 #ifdef __cplusplus
  60 extern "C" {
  61 #endif
  62
  63 /** \enum OAuthMethod
  64  * signature method to used for signing the request.
  65  */
  66 typedef enum {
  67     OA_HMAC=0, ///< use HMAC-SHA1 request signing method
  68     OA_RSA, ///< use RSA signature
  69     OA_PLAINTEXT ///< use plain text signature (for testing only)
  70   } OAuthMethod;
  71
  72 /**
  73  * Base64 encode and return size data in 'src'. The caller must free the
  74  * returned string.
  75  *
  76  * @param size The size of the data in src
  77  * @param src The data to be base64 encode
  78  * @return encoded string otherwise NULL
  79  */
  80 char *oauth_encode_base64(int size, const unsigned char *src);
  81
  82 /**
  83  * Decode the base64 encoded string 'src' into the memory pointed to by
  84  * 'dest'.
  85  *
  86  * @param dest Pointer to memory for holding the decoded string.
  87  * Must be large enough to receive the decoded string.
  88  * @param src A base64 encoded string.
  89  * @return the length of the decoded string if decode
  90  * succeeded otherwise 0.
  91  */
  92 int oauth_decode_base64(unsigned char *dest, const char *src);
  93
  94 /**
  95  * Escape 'string' according to RFC3986 and
  96  * http://oauth.net/core/1.0/#encoding_parameters.
  97  *
  98  * @param string The data to be encoded
  99  * @return encoded string otherwise NULL
 100  * The caller must free the returned string.
 101  */
 102 char *oauth_url_escape(const char *string);
 103
 104 /**
 105  * Parse RFC3986 encoded 'string' back to  unescaped version.
 106  *
 107  * @param string The data to be unescaped
 108  * @param olen unless NULL the length of the returned string is stored there.
 109  * @return decoded string or NULL
 110  * The caller must free the returned string.
 111  */
 112 char *oauth_url_unescape(const char *string, size_t *olen);
 113
 114
 115 /**
 116  * returns base64 encoded HMAC-SHA1 signature for
 117  * given message and key.
 118  * both data and key need to be urlencoded.
 119  *
 120  * the returned string needs to be freed by the caller
 121  *
 122  * @param m message to be signed
 123  * @param k key used for signing
 124  * @return signature string.
 125  */
 126 char *oauth_sign_hmac_sha1 (const char *m, const char *k);
 127
 128 /**
 129  * same as \ref oauth_sign_hmac_sha1 but allows one
 130  * to specify length of message and key (in case they contain null chars).
 131  *
 132  * @param m message to be signed
 133  * @param ml length of message
 134  * @param k key used for signing
 135  * @param kl length of key
 136  * @return signature string.
 137  */
 138 char *oauth_sign_hmac_sha1_raw (const char *m, const size_t ml, const char *k, const size_t kl);
 139
 140 /**
 141  * returns plaintext signature for the given key.
 142  *
 143  * the returned string needs to be freed by the caller
 144  *
 145  * @param m message to be signed
 146  * @param k key used for signing
 147  * @return signature string
 148  */
 149 char *oauth_sign_plaintext (const char *m, const char *k);
 150
 151 /**
 152  * returns RSA-SHA1 signature for given data.
 153  * the returned signature needs to be freed by the caller.
 154  *
 155  * @param m message to be signed
 156  * @param k private-key PKCS and Base64-encoded
 157  * @return base64 encoded signature string.
 158  */
 159 char *oauth_sign_rsa_sha1 (const char *m, const char *k);
 160
 161 /**
 162  * verify RSA-SHA1 signature.
 163  *
 164  * returns the output of EVP_VerifyFinal() for a given message,
 165  * cert/pubkey and signature.
 166  *
 167  * @param m message to be verified
 168  * @param c public-key or x509 certificate
 169  * @param s base64 encoded signature
 170  * @return 1 for a correct signature, 0 for failure and -1 if some other error occurred
 171  */
 172 int oauth_verify_rsa_sha1 (const char *m, const char *c, const char *s);
 173
 174 /**
 175  * url-escape strings and concatenate with '&' separator.
 176  * The number of strings to be concatenated must be
 177  * given as first argument.
 178  * all arguments thereafter must be of type (char *)
 179  *
 180  * @param len the number of arguments to follow this parameter
 181  *
 182  * @return pointer to memory holding the concatenated
 183  * strings - needs to be xfree(d) by the caller. or NULL
 184  * in case we ran out of memory.
 185  */
 186 char *oauth_catenc(int len, ...);
 187
 188 /**
 189  * splits the given url into a parameter array.
 190  * (see \ref oauth_serialize_url and \ref oauth_serialize_url_parameters for the reverse)
 191  * (see \ref oauth_split_post_paramters for a more generic version)
 192  *
 193  * @param url the url or query-string to parse; may be NULL
 194  * @param argv pointer to a (char *) array where the results are stored.
 195  *  The array is re-allocated to match the number of parameters and each
 196  *  parameter-string is allocated with strdup. - The memory needs to be freed
 197  *  by the caller.
 198  *
 199  * @return number of parameter(s) in array.
 200  */
 201 int oauth_split_url_parameters(const char *url, char ***argv);
 202
 203 /**
 204  * splits the given url into a parameter array.
 205  * (see \ref oauth_serialize_url and \ref oauth_serialize_url_parameters for the reverse)
 206  *
 207  * @param url the url or query-string to parse.
 208  * @param argv pointer to a (char *) array where the results are stored.
 209  *  The array is re-allocated to match the number of parameters and each
 210  *  parameter-string is allocated with strdup. - The memory needs to be freed
 211  *  by the caller.
 212  * @param qesc  use query parameter escape (vs post-param-escape) - if set
 213  *        to 1 all '+' are treated as spaces ' '
 214  *
 215  * @return number of parameter(s) in array.
 216  */
 217 int oauth_split_post_paramters(const char *url, char ***argv, short qesc);
 218
 219 /**
 220  * build a url query string from an array.
 221  *
 222  * @param argc  the total number of elements in the array
 223  * @param start element in the array at which to start concatenating.
 224  * @param argv  parameter-array to concatenate.
 225  * @return url string needs to be freed by the caller.
 226  *
 227  */
 228 char *oauth_serialize_url (int argc, int start, char **argv);
 229
 230 /**
 231  * encode query parameters from an array.
 232  *
 233  * @param argc the total number of elements in the array
 234  * @param start element in the array at which to start concatenating.
 235  * @param argv parameter-array to concatenate.
 236  * @param sep separator for parameters (usually "&")
 237  * @param mod - bitwise modifiers:
 238  *   1: skip all values that start with "oauth_"
 239  *   2: skip all values that don't start with "oauth_"
 240  *   4: double quotation marks are added around values (use with sep ", " for HTTP Authorization header).
 241  * @return url string needs to be freed by the caller.
 242  */
 243 char *oauth_serialize_url_sep (int argc, int start, char **argv, char *sep, int mod);
 244
 245 /**
 246  * build a query parameter string from an array.
 247  *
 248  * This function is a shortcut for \ref oauth_serialize_url (argc, 1, argv).
 249  * It strips the leading host/path, which is usually the first
 250  * element when using oauth_split_url_parameters on an URL.
 251  *
 252  * @param argc the total number of elements in the array
 253  * @param argv parameter-array to concatenate.
 254  * @return url string needs to be freed by the caller.
 255  */
 256 char *oauth_serialize_url_parameters (int argc, char **argv);
 257
 258 /**
 259  * generate a random string between 15 and 32 chars length
 260  * and return a pointer to it. The value needs to be freed by the
 261  * caller
 262  *
 263  * @return zero terminated random string.
 264  */
 265 char *oauth_gen_nonce();
 266
 267 /**
 268  * string compare function for oauth parameters.
 269  *
 270  * used with qsort. needed to normalize request parameters.
 271  * see http://oauth.net/core/1.0/#anchor14
 272  */
 273 int oauth_cmpstringp(const void *p1, const void *p2);
 274
 275
 276 /**
 277  * search array for parameter key.
 278  * @param argv length of array to search
 279  * @param argc parameter array to search
 280  * @param key key of parameter to check.
 281  *
 282  * @return FALSE (0) if array does not contain a parameter with given key, TRUE (1) otherwise.
 283  */
 284 int oauth_param_exists(char **argv, int argc, char *key);
 285
 286 /**
 287  * add query parameter to array
 288  *
 289  * @param argcp pointer to array length int
 290  * @param argvp pointer to array values
 291  * @param addparam parameter to add (eg. "foo=bar")
 292  */
 293 void oauth_add_param_to_array(int *argcp, char ***argvp, const char *addparam);
 294
 295 /**
 296  * free array args
 297  *
 298  * @param argcp pointer to array length int
 299  * @param argvp pointer to array values to be xfree()d
 300  */
 301 void oauth_free_array(int *argcp, char ***argvp);
 302
 303 /**
 304  * compare two strings in constant-time (as to not let an
 305  * attacker guess how many leading chars are correct:
 306  * http://rdist.root.org/2010/01/07/timing-independent-array-comparison/ )
 307  *
 308  * @param a string to compare
 309  * @param b string to compare
 310  * @param len_a length of string a
 311  * @param len_b length of string b
 312  *
 313  * returns 0 (false) if strings are not equal, and 1 (true) if strings are equal.
 314  */
 315 int oauth_time_independent_equals_n(const char* a, const char* b, size_t len_a, size_t len_b);
 316
 317 /**
 318  * @deprecated Use oauth_time_independent_equals_n() instead.
 319  */
 320 int oauth_time_indepenent_equals_n(const char* a, const char* b, size_t len_a, size_t len_b) attribute_deprecated;
 321
 322 /**
 323  * compare two strings in constant-time.
 324  * wrapper to \ref oauth_time_independent_equals_n
 325  * which calls strlen() for each argument.
 326  *
 327  * @param a string to compare
 328  * @param b string to compare
 329  *
 330  * returns 0 (false) if strings are not equal, and 1 (true) if strings are equal.
 331  */
 332 int oauth_time_independent_equals(const char* a, const char* b);
 333
 334 /**
 335  * @deprecated Use oauth_time_independent_equals() instead.
 336  */
 337 int oauth_time_indepenent_equals(const char* a, const char* b) attribute_deprecated;
 338
 339 /**
 340  * calculate OAuth-signature for a given HTTP request URL, parameters and oauth-tokens.
 341  *
 342  * if 'postargs' is NULL a "GET" request is signed and the
 343  * signed URL is returned. Else this fn will modify 'postargs'
 344  * to point to memory that contains the signed POST-variables
 345  * and returns the base URL.
 346  *
 347  * both, the return value and (if given) 'postargs' need to be freed
 348  * by the caller.
 349  *
 350  * @param url The request URL to be signed. append all GET or POST
 351  * query-parameters separated by either '?' or '&' to this parameter.
 352  *
 353  * @param postargs This parameter points to an area where the return value
 354  * is stored. If 'postargs' is NULL, no value is stored.
 355  *
 356  * @param method specify the signature method to use. It is of type
 357  * \ref OAuthMethod and most likely \ref OA_HMAC.
 358  *
 359  * @param http_method The HTTP request method to use (ie "GET", "PUT",..)
 360  * If NULL is given as 'http_method' this defaults to "GET" when
 361  * 'postargs' is also NULL and when postargs is not NULL "POST" is used.
 362  *
 363  * @param c_key consumer key
 364  * @param c_secret consumer secret
 365  * @param t_key token key
 366  * @param t_secret token secret
 367  *
 368  * @return the signed url or NULL if an error occurred.
 369  *
 370  */
 371 char *oauth_sign_url2 (const char *url, char **postargs,
 372   OAuthMethod method,
 373   const char *http_method, //< HTTP request method
 374   const char *c_key, //< consumer key - posted plain text
 375   const char *c_secret, //< consumer secret - used as 1st part of secret-key
 376   const char *t_key, //< token key - posted plain text in URL
 377   const char *t_secret //< token secret - used as 2st part of secret-key
 378   );
 379
 380 /**
 381  * @deprecated Use oauth_sign_url2() instead.
 382  */
 383 char *oauth_sign_url (const char *url, char **postargs,
 384   OAuthMethod method,
 385   const char *c_key, //< consumer key - posted plain text
 386   const char *c_secret, //< consumer secret - used as 1st part of secret-key
 387   const char *t_key, //< token key - posted plain text in URL
 388   const char *t_secret //< token secret - used as 2st part of secret-key
 389   ) attribute_deprecated;
 390
 391
 392 /**
 393  * the back-end behind by /ref oauth_sign_array2.
 394  * however it does not serialize the signed URL again.
 395  * The user needs to call /ref oauth_serialize_url (oA)
 396  * and /ref oauth_free_array to do so.
 397  *
 398  * This allows one to split parts of the URL to be used for
 399  * OAuth HTTP Authorization header:
 400  * see http://oauth.net/core/1.0a/#consumer_req_param
 401  * the oauthtest2 example code does so.
 402  *
 403  *
 404  * @param argcp pointer to array length int
 405  * @param argvp pointer to array values
 406  * (argv[0]="http://example.org:80/" argv[1]="first=QueryParamater" ..
 407  *  the array is modified: fi. oauth_ parameters are added)
 408  *  These arrays can be generated with /ref oauth_split_url_parameters
 409  *  or /ref oauth_split_post_paramters.
 410  *
 411  * @param postargs This parameter points to an area where the return value
 412  * is stored. If 'postargs' is NULL, no value is stored.
 413  *
 414  * @param method specify the signature method to use. It is of type
 415  * \ref OAuthMethod and most likely \ref OA_HMAC.
 416  *
 417  * @param http_method The HTTP request method to use (ie "GET", "PUT",..)
 418  * If NULL is given as 'http_method' this defaults to "GET" when
 419  * 'postargs' is also NULL and when postargs is not NULL "POST" is used.
 420  *
 421  * @param c_key consumer key
 422  * @param c_secret consumer secret
 423  * @param t_key token key
 424  * @param t_secret token secret
 425  *
 426  * @return void
 427  *
 428  */
 429 void oauth_sign_array2_process (int *argcp, char***argvp,
 430   char **postargs,
 431   OAuthMethod method,
 432   const char *http_method, //< HTTP request method
 433   const char *c_key, //< consumer key - posted plain text
 434   const char *c_secret, //< consumer secret - used as 1st part of secret-key
 435   const char *t_key, //< token key - posted plain text in URL
 436   const char *t_secret //< token secret - used as 2st part of secret-key
 437   );
 438
 439 /**
 440  * same as /ref oauth_sign_url
 441  * with the url already split into parameter array
 442  *
 443  * @param argcp pointer to array length int
 444  * @param argvp pointer to array values
 445  * (argv[0]="http://example.org:80/" argv[1]="first=QueryParamater" ..
 446  *  the array is modified: fi. oauth_ parameters are added)
 447  *  These arrays can be generated with /ref oauth_split_url_parameters
 448  *  or /ref oauth_split_post_paramters.
 449  *
 450  * @param postargs This parameter points to an area where the return value
 451  * is stored. If 'postargs' is NULL, no value is stored.
 452  *
 453  * @param method specify the signature method to use. It is of type
 454  * \ref OAuthMethod and most likely \ref OA_HMAC.
 455  *
 456  * @param http_method The HTTP request method to use (ie "GET", "PUT",..)
 457  * If NULL is given as 'http_method' this defaults to "GET" when
 458  * 'postargs' is also NULL and when postargs is not NULL "POST" is used.
 459  *
 460  * @param c_key consumer key
 461  * @param c_secret consumer secret
 462  * @param t_key token key
 463  * @param t_secret token secret
 464  *
 465  * @return the signed url or NULL if an error occurred.
 466  */
 467 char *oauth_sign_array2 (int *argcp, char***argvp,
 468   char **postargs,
 469   OAuthMethod method,
 470   const char *http_method, //< HTTP request method
 471   const char *c_key, //< consumer key - posted plain text
 472   const char *c_secret, //< consumer secret - used as 1st part of secret-key
 473   const char *t_key, //< token key - posted plain text in URL
 474   const char *t_secret //< token secret - used as 2st part of secret-key
 475   );
 476
 477 /**
 478  * @deprecated Use oauth_sign_array2() instead.
 479  */
 480 char *oauth_sign_array (int *argcp, char***argvp,
 481   char **postargs,
 482   OAuthMethod method,
 483   const char *c_key, //< consumer key - posted plain text
 484   const char *c_secret, //< consumer secret - used as 1st part of secret-key
 485   const char *t_key, //< token key - posted plain text in URL
 486   const char *t_secret //< token secret - used as 2st part of secret-key
 487   ) attribute_deprecated;
 488
 489
 490 /**
 491  * calculate body hash (sha1sum) of given file and return
 492  * a oauth_body_hash=xxxx parameter to be added to the request.
 493  * The returned string needs to be freed by the calling function.
 494  *
 495  * see
 496  * http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html
 497  *
 498  * @param filename the filename to calculate the hash for
 499  *
 500  * @return URL oauth_body_hash parameter string
 501  */
 502 char *oauth_body_hash_file(char *filename);
 503
 504 /**
 505  * calculate body hash (sha1sum) of given data and return
 506  * a oauth_body_hash=xxxx parameter to be added to the request.
 507  * The returned string needs to be freed by the calling function.
 508  * The returned string is not yet url-escaped and suitable to be
 509  * passed as argument to \ref oauth_catenc.
 510  *
 511  * see
 512  * http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html
 513  *
 514  * @param length length of the data parameter in bytes
 515  * @param data to calculate the hash for
 516  *
 517  * @return URL oauth_body_hash parameter string
 518  */
 519 char *oauth_body_hash_data(size_t length, const char *data);
 520
 521 /**
 522  * base64 encode digest, free it and return a URL parameter
 523  * with the oauth_body_hash. The returned hash needs to be freed by the
 524  * calling function. The returned string is not yet url-escaped and
 525  * thus suitable to be passed to \ref oauth_catenc.
 526  *
 527  * @param len length of the digest to encode
 528  * @param digest hash value to encode
 529  *
 530  * @return URL oauth_body_hash parameter string
 531  */
 532 char *oauth_body_hash_encode(size_t len, unsigned char *digest);
 533
 534 /**
 535  * xep-0235 - TODO
 536  */
 537 char *oauth_sign_xmpp (const char *xml,
 538   OAuthMethod method,
 539   const char *c_secret, //< consumer secret - used as 1st part of secret-key
 540   const char *t_secret //< token secret - used as 2st part of secret-key
 541   );
 542
 543 /**
 544  * do a HTTP GET request, wait for it to finish
 545  * and return the content of the reply.
 546  * (requires libcurl or a command-line HTTP client)
 547  *
 548  * If compiled <b>without</b> libcurl this function calls
 549  * a command-line executable defined in the environment variable
 550  * OAUTH_HTTP_GET_CMD - it defaults to
 551  * <tt>curl -sA 'liboauth-agent/0.1' '%%u'</tt>
 552  * where %%u is replaced with the URL and query parameters.
 553  *
 554  * bash & wget example:
 555  * <tt>export OAUTH_HTTP_CMD="wget -q -U 'liboauth-agent/0.1' '%u' "</tt>
 556  *
 557  * WARNING: this is a tentative function. it's convenient and handy for testing
 558  * or developing OAuth code. But don't rely on this function
 559  * to become a stable part of this API. It does not do
 560  * much error checking or handling for one thing..
 561  *
 562  * NOTE: \a u and \a q are just concatenated with a '?' in between,
 563  * unless \a q is NULL. in which case only \a u will be used.
 564  *
 565  * @param u base url to get
 566  * @param q query string to send along with the HTTP request or NULL.
 567  * @return  In case of an error NULL is returned; otherwise a pointer to the
 568  * replied content from HTTP server. latter needs to be freed by caller.
 569  *
 570  * @deprecated use libcurl - http://curl.haxx.se/libcurl/c/
 571  */
 572 char *oauth_http_get (const char *u, const char *q) attribute_deprecated;
 573
 574 /**
 575  * do a HTTP GET request, wait for it to finish
 576  * and return the content of the reply.
 577  *
 578  * (requires libcurl)
 579  *
 580  * This is equivalent to /ref oauth_http_get but allows one
 581  * to specifiy a custom HTTP header andhas no support for commandline-curl.
 582  *
 583  * If liboauth is compiled <b>without</b> libcurl this function
 584  * always returns NULL.
 585  *
 586  * @param u base url to get
 587  * @param q query string to send along with the HTTP request or NULL.
 588  * @param customheader specify custom HTTP header (or NULL for none)
 589  * Multiple header elements can be passed separating them with "\r\n"
 590  * @return  In case of an error NULL is returned; otherwise a pointer to the
 591  * replied content from HTTP server. latter needs to be freed by caller.
 592  *
 593  * @deprecated use libcurl - http://curl.haxx.se/libcurl/c/
 594  */
 595 char *oauth_http_get2 (const char *u, const char *q, const char *customheader) attribute_deprecated;
 596
 597
 598 /**
 599  * do a HTTP POST request, wait for it to finish
 600  * and return the content of the reply.
 601  * (requires libcurl or a command-line HTTP client)
 602  *
 603  * If compiled <b>without</b> libcurl this function calls
 604  * a command-line executable defined in the environment variable
 605  * OAUTH_HTTP_CMD - it defaults to
 606  * <tt>curl -sA 'liboauth-agent/0.1' -d '%%p' '%%u'</tt>
 607  * where %%p is replaced with the postargs and %%u is replaced with
 608  * the URL.
 609  *
 610  * bash & wget example:
 611  * <tt>export OAUTH_HTTP_CMD="wget -q -U 'liboauth-agent/0.1' --post-data='%p' '%u' "</tt>
 612  *
 613  * NOTE: This function uses the curl's default HTTP-POST Content-Type:
 614  * application/x-www-form-urlencoded which is the only option allowed
 615  * by oauth core 1.0 spec. Experimental code can use the Environment variable
 616  * to transmit custom HTTP headers or parameters.
 617  *
 618  * WARNING: this is a tentative function. it's convenient and handy for testing
 619  * or developing OAuth code. But don't rely on this function
 620  * to become a stable part of this API. It does not do
 621  * much error checking for one thing..
 622  *
 623  * @param u url to query
 624  * @param p postargs to send along with the HTTP request.
 625  * @return replied content from HTTP server. needs to be freed by caller.
 626  *
 627  * @deprecated use libcurl - http://curl.haxx.se/libcurl/c/
 628  */
 629 char *oauth_http_post (const char *u, const char *p) attribute_deprecated;
 630
 631 /**
 632  * do a HTTP POST request, wait for it to finish
 633  * and return the content of the reply.
 634  * (requires libcurl)
 635  *
 636  * It's equivalent to /ref oauth_http_post, but offers
 637  * the possibility to specify a custom HTTP header and
 638  * has no support for commandline-curl.
 639  *
 640  * If liboauth is compiled <b>without</b> libcurl this function
 641  * always returns NULL.
 642  *
 643  * @param u url to query
 644  * @param p postargs to send along with the HTTP request.
 645  * @param customheader specify custom HTTP header (or NULL for none)
 646  * Multiple header elements can be passed separating them with "\r\n"
 647  * @return replied content from HTTP server. needs to be freed by caller.
 648  *
 649  * @deprecated use libcurl - http://curl.haxx.se/libcurl/c/
 650  */
 651 char *oauth_http_post2 (const char *u, const char *p, const char *customheader) attribute_deprecated;
 652
 653
 654 /**
 655  * http post raw data from file.
 656  * the returned string needs to be freed by the caller
 657  * (requires libcurl)
 658  *
 659  * see dislaimer: /ref oauth_http_post
 660  *
 661  * @param u url to retrieve
 662  * @param fn filename of the file to post along
 663  * @param len length of the file in bytes. set to '0' for autodetection
 664  * @param customheader specify custom HTTP header (or NULL for default).
 665  * Multiple header elements can be passed separating them with "\r\n"
 666  * @return returned HTTP reply or NULL on error
 667  *
 668  * @deprecated use libcurl - http://curl.haxx.se/libcurl/c/
 669  */
 670 char *oauth_post_file (const char *u, const char *fn, const size_t len, const char *customheader) attribute_deprecated;
 671
 672 /**
 673  * http post raw data
 674  * the returned string needs to be freed by the caller
 675  * (requires libcurl)
 676  *
 677  * see dislaimer: /ref oauth_http_post
 678  *
 679  * @param u url to retrieve
 680  * @param data data to post
 681  * @param len length of the data in bytes.
 682  * @param customheader specify custom HTTP header (or NULL for default)
 683  * Multiple header elements can be passed separating them with "\r\n"
 684  * @return returned HTTP reply or NULL on error
 685  *
 686  * @deprecated use libcurl - http://curl.haxx.se/libcurl/c/
 687  */
 688 char *oauth_post_data (const char *u, const char *data, size_t len, const char *customheader) attribute_deprecated;
 689
 690 /**
 691  * http post raw data, with callback.
 692  * the returned string needs to be freed by the caller
 693  * (requires libcurl)
 694  *
 695  * Invokes the callback - in no particular order - when HTTP-request status updates occur.
 696  * The callback is called with:
 697  *   void * callback_data: supplied on function call.
 698  *   int type: 0=data received, 1=data sent.
 699  *   size_t size: amount of data received or amount of data sent so far
 700  *   size_t totalsize: original amount of data to send, or amount of data received
 701  *
 702  * @param u url to retrieve
 703  * @param data data to post along
 704  * @param len length of the file in bytes. set to '0' for autodetection
 705  * @param customheader specify custom HTTP header (or NULL for default)
 706  * Multiple header elements can be passed separating them with "\r\n"
 707  * @param callback specify the callback function
 708  * @param callback_data specify data to pass to the callback function
 709  * @return returned HTTP reply or NULL on error
 710  *
 711  * @deprecated use libcurl - http://curl.haxx.se/libcurl/c/
 712  */
 713 char *oauth_post_data_with_callback      (const char *u,
 714                                           const char *data,
 715                                           size_t len,
 716                                           const char *customheader,
 717                                           void (*callback)(void*,int,size_t,size_t),
 718                                           void *callback_data) attribute_deprecated;
 719
 720 /**
 721  * http send raw data. similar to /ref oauth_http_post but provides
 722  * for specifying the HTTP request method.
 723  *
 724  * the returned string needs to be freed by the caller
 725  * (requires libcurl)
 726  *
 727  * see dislaimer: /ref oauth_http_post
 728  *
 729  * @param u url to retrieve
 730  * @param data data to post
 731  * @param len length of the data in bytes.
 732  * @param customheader specify custom HTTP header (or NULL for default)
 733  * Multiple header elements can be passed separating them with "\r\n"
 734  * @param httpMethod specify http verb ("GET"/"POST"/"PUT"/"DELETE") to be used. if httpMethod is NULL, a POST is executed.
 735  * @return returned HTTP reply or NULL on error
 736  *
 737  * @deprecated use libcurl - http://curl.haxx.se/libcurl/c/
 738  */
 739 char *oauth_send_data (const char *u,
 740                        const char *data,
 741                        size_t len,
 742                        const char *customheader,
 743                        const char *httpMethod) attribute_deprecated;
 744
 745 /**
 746  * http post raw data, with callback.
 747  * the returned string needs to be freed by the caller
 748  * (requires libcurl)
 749  *
 750  * Invokes the callback - in no particular order - when HTTP-request status updates occur.
 751  * The callback is called with:
 752  *   void * callback_data: supplied on function call.
 753  *   int type: 0=data received, 1=data sent.
 754  *   size_t size: amount of data received or amount of data sent so far
 755  *   size_t totalsize: original amount of data to send, or amount of data received
 756  *
 757  * @param u url to retrieve
 758  * @param data data to post along
 759  * @param len length of the file in bytes. set to '0' for autodetection
 760  * @param customheader specify custom HTTP header (or NULL for default)
 761  * Multiple header elements can be passed separating them with "\r\n"
 762  * @param callback specify the callback function
 763  * @param callback_data specify data to pass to the callback function
 764  * @param httpMethod specify http verb ("GET"/"POST"/"PUT"/"DELETE") to be used.
 765  * @return returned HTTP reply or NULL on error
 766  *
 767  * @deprecated use libcurl - http://curl.haxx.se/libcurl/c/
 768  */
 769 char *oauth_send_data_with_callback      (const char *u,
 770                                           const char *data,
 771                                           size_t len,
 772                                           const char *customheader,
 773                                           void (*callback)(void*,int,size_t,size_t),
 774                                           void *callback_data,
 775                                           const char *httpMethod) attribute_deprecated;
 776
 777 #ifdef __cplusplus
 778 }       /* extern "C" */
 779 #endif  /* __cplusplus */
 780
 781 #endif
 782 /* vi:set ts=8 sts=2 sw=2: */