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