| .\" ************************************************************************** |
| .\" * _ _ ____ _ |
| .\" * Project ___| | | | _ \| | |
| .\" * / __| | | | |_) | | |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| .\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. |
| .\" * |
| .\" * This software is licensed as described in the file COPYING, which |
| .\" * you should have received as part of this distribution. The terms |
| .\" * are also available at https://curl.haxx.se/docs/copyright.html. |
| .\" * |
| .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| .\" * copies of the Software, and permit persons to whom the Software is |
| .\" * furnished to do so, under the terms of the COPYING file. |
| .\" * |
| .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| .\" * KIND, either express or implied. |
| .\" * |
| .\" * SPDX-License-Identifier: curl |
| .\" * |
| .\" ************************************************************************** |
| .\" |
| .TH CURLOPT_AWS_SIGV4 3 "03 Jun 2020" libcurl libcurl |
| .SH NAME |
| CURLOPT_AWS_SIGV4 \- V4 signature |
| .SH SYNOPSIS |
| .nf |
| #include <curl/curl.h> |
| |
| CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); |
| .fi |
| .SH DESCRIPTION |
| Provides AWS V4 signature authentication on HTTP(S) header. |
| .PP |
| Pass a char * that is the collection of specific arguments are used for |
| creating outgoing authentication headers. The format of the \fIparam\fP |
| option is: |
| .IP provider1[:provider2[:region[:service]]] |
| .IP provider1,\ provider2 |
| The providers arguments are used for generating some authentication parameters |
| such as "Algorithm", "date", "request type" and "signed headers". |
| .IP region |
| The argument is a geographic area of a resources collection. |
| It is extracted from the host name specified in the URL if omitted. |
| .IP service |
| The argument is a function provided by a cloud. |
| It is extracted from the host name specified in the URL if omitted. |
| .PP |
| NOTE: This call set \fICURLOPT_HTTPAUTH(3)\fP to CURLAUTH_AWS_SIGV4. |
| Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same |
| as calling this with \fB"aws:amz"\fP in parameter. |
| .PP |
| Example with "Test:Try", when curl will do the algorithm, it will generate |
| \fB"TEST-HMAC-SHA256"\fP for "Algorithm", \fB"x-try-date"\fP and |
| \fB"X-Try-Date"\fP for "date", \fB"test4_request"\fP for "request type", |
| \fB"SignedHeaders=content-type;host;x-try-date"\fP for "signed headers" |
| .PP |
| If you use just "test", instead of "test:try", |
| test will be use for every strings generated |
| .SH DEFAULT |
| By default, the value of this parameter is NULL. |
| Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same |
| as calling this with \fB"aws:amz"\fP in parameter. |
| .SH PROTOCOLS |
| HTTP |
| .SH EXAMPLE |
| .nf |
| CURL *curl = curl_easy_init(); |
| |
| struct curl_slist *list = NULL; |
| |
| if(curl) { |
| curl_easy_setopt(curl, CURLOPT_URL, |
| "https://service.region.example.com/uri"); |
| curl_easy_setopt(c, CURLOPT_AWS_SIGV4, "provider1:provider2"); |
| |
| /* service and region also could be set in CURLOPT_AWS_SIGV4 */ |
| /* |
| curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/uri"); |
| curl_easy_setopt(c, CURLOPT_AWS_SIGV4, |
| "provider1:provider2:region:service"); |
| */ |
| |
| curl_easy_setopt(c, CURLOPT_USERPWD, "MY_ACCESS_KEY:MY_SECRET_KEY"); |
| curl_easy_perform(curl); |
| } |
| .fi |
| .SH AVAILABILITY |
| Added in 7.75.0 |
| .SH RETURN VALUE |
| Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. |
| .SH NOTES |
| This option overrides the other auth types you might have set in |
| \fICURLOPT_HTTPAUTH(3)\fP which should be highlighted as this makes this auth |
| method special. This method cannot be combined with other auth types. |
| .PP |
| 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 |
| \fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it's the checksum of an empty buffer. |
| For requests like PUT, you can provide your own checksum in an HTTP header named |
| \fBx-provider2-content-sha256\fP. |
| .PP |
| For \fBaws:s3\fP, a \fBx-amz-content-sha256\fP header is added to every request |
| if not already present. For s3 requests with unknown payload, this header takes |
| the special value "UNSIGNED-PAYLOAD". |
| .SH "SEE ALSO" |
| .BR CURLOPT_HEADEROPT "(3), " CURLOPT_HTTPHEADER "(3), " |
