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