xref: /curl/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md (revision 24b66a1d) 
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
53##
54
55NOTE: This call set CURLOPT_HTTPAUTH(3) to CURLAUTH_AWS_SIGV4. Calling
56CURLOPT_HTTPAUTH(3) with CURLAUTH_AWS_SIGV4 is the same as calling this with
57**"aws:amz"** in parameter.
58
59Example with "Test:Try", when curl uses the algorithm, it generates
60**"TEST-HMAC-SHA256"** for "Algorithm", **"x-try-date"** and **"X-Try-Date"**
61for "date", **"test4_request"** for "request type",
62**"SignedHeaders=content-type;host;x-try-date"** for "signed headers"
63
64If you use just "test", instead of "test:try", test is used for every
65generated string.
66
67# DEFAULT
68
69By default, the value of this parameter is NULL.
70Calling CURLOPT_HTTPAUTH(3) with CURLAUTH_AWS_SIGV4 is the same
71as calling this with **"aws:amz"** in parameter.
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