mirror of
https://github.com/curl/curl
synced 2026-08-25 12:32:35 -04:00
c4013cdb85
- 'null-terminate', sync casing. - add an `#endif` comment. - avoid a few instances of 'will'. - configure: 'aws' -> 'aws-sigv4', where missing. - unfold/fold lines. - update memzero/strzero comments. - uppercase 'CRLF'. Closes #22443
107 lines
3.1 KiB
Markdown
107 lines
3.1 KiB
Markdown
---
|
|
c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
SPDX-License-Identifier: curl
|
|
Title: CURLOPT_HTTPSIG_HEADERS
|
|
Section: 3
|
|
Source: libcurl
|
|
See-also:
|
|
- CURLOPT_HTTPSIG_ALGORITHM (3)
|
|
- CURLOPT_HTTPSIG_KEY (3)
|
|
- CURLOPT_HTTPSIG_KEYID (3)
|
|
Protocol:
|
|
- HTTP
|
|
Added-in: 8.22.0
|
|
---
|
|
|
|
# NAME
|
|
|
|
CURLOPT_HTTPSIG_HEADERS - components to sign for HTTP Message Signatures
|
|
|
|
# SYNOPSIS
|
|
|
|
~~~c
|
|
#include <curl/curl.h>
|
|
|
|
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPSIG_HEADERS,
|
|
char *components);
|
|
~~~
|
|
|
|
# DESCRIPTION
|
|
|
|
This feature is **experimental** and may change before it is considered
|
|
stable. We advise against using it in production.
|
|
|
|
Pass a space-separated list of component identifiers to include in the
|
|
RFC 9421 HTTP Message Signature.
|
|
|
|
Derived components are given as bare names:
|
|
|
|
- **method** - the HTTP method (GET, POST, etc.)
|
|
- **authority** - the host and optional port
|
|
- **path** - the request path
|
|
- **query** - the query string including the leading `?`
|
|
|
|
HTTP header fields are given with a trailing colon, for example `content-type:`
|
|
or `content-digest:`. This mirrors how a header looks and keeps a leading `@`
|
|
free for its usual curl meaning (read the value from a file).
|
|
|
|
If this option is not set, the default components are **method**, **authority**,
|
|
**path** (plus **query** when a query string is present).
|
|
|
|
## Signing request headers
|
|
|
|
Header components are resolved from the list set with CURLOPT_HTTPHEADER(3)
|
|
only. Headers that libcurl adds later (such as the default `User-Agent`) are
|
|
**not** visible to the signer unless the application supplies them explicitly.
|
|
|
|
To sign `User-Agent`, supply it via CURLOPT_HTTPHEADER(3) together with this
|
|
option before the transfer; see EXAMPLE.
|
|
|
|
Each component identifier may appear at most once (RFC 9421 Section 2).
|
|
Listing the same component twice returns `CURLE_BAD_FUNCTION_ARGUMENT`.
|
|
|
|
At most 16 components are accepted; supplying more returns
|
|
`CURLE_BAD_FUNCTION_ARGUMENT`.
|
|
|
|
The application does not have to keep the string around after setting this
|
|
option.
|
|
|
|
# DEFAULT
|
|
|
|
NULL (uses the default component set)
|
|
|
|
# %PROTOCOLS%
|
|
|
|
# EXAMPLE
|
|
|
|
~~~c
|
|
int main(void)
|
|
{
|
|
CURL *curl = curl_easy_init();
|
|
struct curl_slist *headers = NULL;
|
|
|
|
if(curl) {
|
|
headers = curl_slist_append(headers, "User-Agent: MyApp/1.0");
|
|
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
|
|
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/api");
|
|
curl_easy_setopt(curl, CURLOPT_HTTPSIG_ALGORITHM, CURLHTTPSIG_ED25519);
|
|
curl_easy_setopt(curl, CURLOPT_HTTPSIG_KEY,
|
|
"9f8362f87a484a954e6e740c5b4c0e84"
|
|
"229139a20aa8ab56ff66586f6a7d29c5");
|
|
curl_easy_setopt(curl, CURLOPT_HTTPSIG_KEYID, "my-key-id");
|
|
curl_easy_setopt(curl, CURLOPT_HTTPSIG_HEADERS,
|
|
"method authority path content-type: user-agent:");
|
|
curl_easy_perform(curl);
|
|
curl_slist_free_all(headers);
|
|
}
|
|
}
|
|
~~~
|
|
|
|
# %AVAILABILITY%
|
|
|
|
# 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).
|