.\" generated by cd2nroff 0.1 from CURLOPT_HTTPSIG_HEADERS.md
.TH CURLOPT_HTTPSIG_HEADERS 3 "2026-09-02" libcurl
.SH NAME
CURLOPT_HTTPSIG_HEADERS \- components to sign for HTTP Message Signatures
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPSIG_HEADERS,
                          char *components);
.fi
.SH DESCRIPTION
This feature is \fBexperimental\fP 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:

- \fBmethod\fP \- the HTTP method (GET, POST, etc.)
- \fBauthority\fP \- the host and optional port
- \fBpath\fP \- the request path
- \fBquery\fP \- the query string including the leading \fI?\fP

HTTP header fields are given with a trailing colon, for example \fIcontent\-type:\fP
or \fIcontent\-digest:\fP. This mirrors how a header looks and keeps a leading \fI@\fP
free for its usual curl meaning (read the value from a file).

If this option is not set, the default components are \fBmethod\fP, \fBauthority\fP,
\fBpath\fP (plus \fBquery\fP when a query string is present).
.IP "Signing request headers"
Header components are resolved from the list set with \fICURLOPT_HTTPHEADER(3)\fP
only. Headers that libcurl adds later (such as the default \fIUser\-Agent\fP) are
\fBnot\fP visible to the signer unless the application supplies them explicitly.

To sign \fIUser\-Agent\fP, supply it via \fICURLOPT_HTTPHEADER(3)\fP 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 \fICURLE_BAD_FUNCTION_ARGUMENT\fP.

At most 16 components are accepted; supplying more returns
\fICURLE_BAD_FUNCTION_ARGUMENT\fP.

The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL (uses the default component set)
.SH PROTOCOLS
This functionality affects http only
.SH EXAMPLE
.nf
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);
  }
}
.fi
.SH AVAILABILITY
Added in curl 8.22.0
.SH RETURN VALUE
\fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR CURLOPT_HTTPSIG_ALGORITHM (3),
.BR CURLOPT_HTTPSIG_KEY (3),
.BR CURLOPT_HTTPSIG_KEYID (3)