CURLOPT_AWS_SIGV4(3) Library Functions Manual CURLOPT_AWS_SIGV4(3)
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
curl_easy_setopt(3) returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non-zero means an error occurred,
see libcurl-errors(3).
SEE ALSO
CURLOPT_HEADEROPT(3), CURLOPT_HTTPAUTH(3), CURLOPT_HTTPHEADER(3),
CURLOPT_PROXYAUTH(3)
libcurl 2025-02-08 CURLOPT_AWS_SIGV4(3)
curl 8.12.0 - Generated Tue Feb 11 16:28:40 CST 2025