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 14Added-in: 7.75.0 15--- 16 17# NAME 18 19CURLOPT_AWS_SIGV4 - V4 signature 20 21# SYNOPSIS 22 23~~~c 24#include <curl/curl.h> 25 26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); 27~~~ 28 29# DESCRIPTION 30 31Provides AWS V4 signature authentication on HTTP(S) header. 32 33Pass a char pointer that is the collection of specific arguments are used for 34creating outgoing authentication headers. The format of the *param* option 35is: 36 37## provider1[:provider2[:region[:service]]] 38 39## provider1, provider2 40 41The providers arguments are used for generating some authentication parameters 42such as "Algorithm", "date", "request type" and "signed headers". 43 44## region 45 46The argument is a geographic area of a resources collection. 47It is extracted from the hostname specified in the URL if omitted. 48 49## service 50 51The argument is a function provided by a cloud. It is extracted from the 52hostname specified in the URL if omitted. 53 54## 55 56NOTE: This call set CURLOPT_HTTPAUTH(3) to CURLAUTH_AWS_SIGV4. Calling 57CURLOPT_HTTPAUTH(3) with CURLAUTH_AWS_SIGV4 is the same as calling this with 58**"aws:amz"** in parameter. 59 60Example with "Test:Try", when curl uses the algorithm, it generates 61**"TEST-HMAC-SHA256"** for "Algorithm", **"x-try-date"** and **"X-Try-Date"** 62for "date", **"test4_request"** for "request type", 63**"SignedHeaders=content-type;host;x-try-date"** for "signed headers" 64 65If you use just "test", instead of "test:try", test is used for every 66generated string. 67 68Setting CURLOPT_HTTPAUTH(3) with the CURLAUTH_AWS_SIGV4 bit set is the same as 69setting this option with a **"aws:amz"** parameter. 70 71The application does not have to keep the string around after setting this 72option. 73 74Using this option multiple times makes the last set string override the 75previous ones. Set it to NULL to disable its use again. 76 77# DEFAULT 78 79NULL 80 81# %PROTOCOLS% 82 83# EXAMPLE 84 85~~~c 86int 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 108This option overrides the other auth types you might have set in 109CURLOPT_HTTPAUTH(3) which should be highlighted as this makes this auth method 110special. This method cannot be combined with other auth types. 111 112A sha256 checksum of the request payload is used as input to the signature 113calculation. For POST requests, this is a checksum of the provided 114CURLOPT_POSTFIELDS(3). Otherwise, it is the checksum of an empty buffer. For 115requests like PUT, you can provide your own checksum in an HTTP header named 116**x-provider2-content-sha256**. 117 118For **aws:s3**, a **x-amz-content-sha256** header is added to every request if 119not already present. For s3 requests with unknown payload, this header takes 120the special value "UNSIGNED-PAYLOAD". 121 122# %AVAILABILITY% 123 124# RETURN VALUE 125 126Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. 127
