quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

CURLOPT_AWS_SIGV4.md (3645B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLOPT_AWS_SIGV4
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLOPT_HEADEROPT (3)
      9   - CURLOPT_HTTPAUTH (3)
     10   - CURLOPT_HTTPHEADER (3)
     11   - CURLOPT_PROXYAUTH (3)
     12 Protocol:
     13   - HTTP
     14 Added-in: 7.75.0
     15 ---
     16 
     17 # NAME
     18 
     19 CURLOPT_AWS_SIGV4 - V4 signature
     20 
     21 # SYNOPSIS
     22 
     23 ~~~c
     24 #include <curl/curl.h>
     25 
     26 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param);
     27 ~~~
     28 
     29 # DESCRIPTION
     30 
     31 Provides AWS V4 signature authentication on HTTP(S) header.
     32 
     33 Pass a char pointer that is the collection of specific arguments are used for
     34 creating outgoing authentication headers. The format of the *param* option
     35 is:
     36 
     37 ## provider1[:provider2[:region[:service]]]
     38 
     39 ## provider1, provider2
     40 
     41 The providers arguments are used for generating some authentication parameters
     42 such as "Algorithm", "date", "request type" and "signed headers".
     43 
     44 ## region
     45 
     46 The argument is a geographic area of a resources collection.
     47 It is extracted from the hostname specified in the URL if omitted.
     48 
     49 ## service
     50 
     51 The argument is a function provided by a cloud. It is extracted from the
     52 hostname specified in the URL if omitted.
     53 
     54 ##
     55 
     56 NOTE: This call set CURLOPT_HTTPAUTH(3) to CURLAUTH_AWS_SIGV4. Calling
     57 CURLOPT_HTTPAUTH(3) with CURLAUTH_AWS_SIGV4 is the same as calling this with
     58 **"aws:amz"** in parameter.
     59 
     60 Example with "Test:Try", when curl uses the algorithm, it generates
     61 **"TEST-HMAC-SHA256"** for "Algorithm", **"x-try-date"** and **"X-Try-Date"**
     62 for "date", **"test4_request"** for "request type",
     63 **"SignedHeaders=content-type;host;x-try-date"** for "signed headers"
     64 
     65 If you use just "test", instead of "test:try", test is used for every
     66 generated string.
     67 
     68 Setting CURLOPT_HTTPAUTH(3) with the CURLAUTH_AWS_SIGV4 bit set is the same as
     69 setting this option with a **"aws:amz"** parameter.
     70 
     71 The application does not have to keep the string around after setting this
     72 option.
     73 
     74 Using this option multiple times makes the last set string override the
     75 previous ones. Set it to NULL to disable its use again.
     76 
     77 # DEFAULT
     78 
     79 NULL
     80 
     81 # %PROTOCOLS%
     82 
     83 # EXAMPLE
     84 
     85 ~~~c
     86 int main(void)
     87 {
     88   CURL *curl = curl_easy_init();
     89 
     90   if(curl) {
     91     curl_easy_setopt(curl, CURLOPT_URL,
     92                     "https://service.region.example.com/uri");
     93     curl_easy_setopt(curl, CURLOPT_AWS_SIGV4, "provider1:provider2");
     94 
     95     /* service and region can also be set in CURLOPT_AWS_SIGV4 */
     96     curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/uri");
     97     curl_easy_setopt(curl, CURLOPT_AWS_SIGV4,
     98                      "provider1:provider2:region:service");
     99 
    100     curl_easy_setopt(curl, CURLOPT_USERPWD, "MY_ACCESS_KEY:MY_SECRET_KEY");
    101     curl_easy_perform(curl);
    102   }
    103 }
    104 ~~~
    105 
    106 # NOTES
    107 
    108 This option overrides the other auth types you might have set in
    109 CURLOPT_HTTPAUTH(3) which should be highlighted as this makes this auth method
    110 special. This method cannot be combined with other auth types.
    111 
    112 A sha256 checksum of the request payload is used as input to the signature
    113 calculation. For POST requests, this is a checksum of the provided
    114 CURLOPT_POSTFIELDS(3). Otherwise, it is the checksum of an empty buffer. For
    115 requests like PUT, you can provide your own checksum in an HTTP header named
    116 **x-provider2-content-sha256**.
    117 
    118 For **aws:s3**, a **x-amz-content-sha256** header is added to every request if
    119 not already present. For s3 requests with unknown payload, this header takes
    120 the special value "UNSIGNED-PAYLOAD".
    121 
    122 # %AVAILABILITY%
    123 
    124 # RETURN VALUE
    125 
    126 curl_easy_setopt(3) returns a CURLcode indicating success or error.
    127 
    128 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
    129 libcurl-errors(3).