NAME

       CURLOPT_AWS_SIGV4 - V4 signature

SYNOPSIS

       #include <curl/curl.h>

       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param);

DESCRIPTION

       Provides AWS V4 signature authentication on HTTP(S) header.

       Pass  a  char  pointer  that is the collection of specific arguments are used for creating
       outgoing authentication headers. The format of the param option is:

       provider1[:provider2[:region[:service]]]

       provider1, provider2
              The providers arguments are used for generating some authentication parameters such
              as "Algorithm", "date", "request type" and "signed headers".

       region The  argument is a geographic area of a resources collection.  It is extracted from
              the hostname specified in the URL if omitted.

       service
              The argument is a function provided by a cloud. It is extracted from  the  hostname
              specified in the URL if omitted.

       NOTE: This call set CURLOPT_HTTPAUTH(3) to CURLAUTH_AWS_SIGV4. Calling CURLOPT_HTTPAUTH(3)
       with CURLAUTH_AWS_SIGV4 is the same as calling this with "aws:amz" in parameter.

       Example with "Test:Try", when curl uses the algorithm, it generates "TEST-HMAC-SHA256" for
       "Algorithm", "x-try-date" and "X-Try-Date" for "date", "test4_request" for "request type",
       "SignedHeaders=content-type;host;x-try-date" for "signed headers"

       If you use just "test", instead of "test:try", test is used for every generated string.

       Setting CURLOPT_HTTPAUTH(3) with the CURLAUTH_AWS_SIGV4 bit set is  the  same  as  setting
       this option with a "aws:amz" parameter.

       The application does not have to keep the string around after setting this option.

       Using this option multiple times makes the last set string override the previous ones. Set
       it to NULL to disable its use again.

DEFAULT

       NULL

PROTOCOLS

       This functionality affects http only

EXAMPLE

       int main(void)
       {
         CURL *curl = curl_easy_init();

         if(curl) {
           curl_easy_setopt(curl, CURLOPT_URL,
                           "https://service.region.example.com/uri");
           curl_easy_setopt(curl, CURLOPT_AWS_SIGV4, "provider1:provider2");

           /* service and region can also be set in CURLOPT_AWS_SIGV4 */
           curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/uri");
           curl_easy_setopt(curl, CURLOPT_AWS_SIGV4,
                            "provider1:provider2:region:service");

           curl_easy_setopt(curl, CURLOPT_USERPWD, "MY_ACCESS_KEY:MY_SECRET_KEY");
           curl_easy_perform(curl);
         }
       }

NOTES

       This option overrides the other auth types you might have set in CURLOPT_HTTPAUTH(3) which
       should  be  highlighted  as  this  makes  this  auth method special. This method cannot be
       combined with other auth types.

       A sha256 checksum of the request payload is used as input to  the  signature  calculation.
       For POST requests, this is a checksum of the provided CURLOPT_POSTFIELDS(3). Otherwise, it
       is the checksum of an empty buffer. For requests  like  PUT,  you  can  provide  your  own
       checksum in an HTTP header named x-provider2-content-sha256.

       For  aws:s3,  a  x-amz-content-sha256  header  is  added  to  every request if not already
       present. For s3 requests with  unknown  payload,  this  header  takes  the  special  value
       "UNSIGNED-PAYLOAD".

AVAILABILITY

       Added in curl 7.75.0

RETURN VALUE

       Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.

SEE ALSO

       CURLOPT_HEADEROPT(3), CURLOPT_HTTPAUTH(3), CURLOPT_HTTPHEADER(3), CURLOPT_PROXYAUTH(3)