• A common nomenclature and canonicalization rule set for the different protocol elements and other components of HTTP messages, used to create the signature base (Section 2).
• Algorithms for generating and verifying signatures over HTTP message components using this signature base through the application of cryptographic primitives (Section 3).
• A mechanism for attaching a signature and related metadata to an HTTP message and for parsing attached signatures and metadata from HTTP messages. To facilitate this, this document defines the "Signature-Input" and "Signature" fields (Section 4).

HTTP Message Signature:

A digital signature or keyed MAC that covers one or more portions of an HTTP message. Note that a given HTTP message can contain multiple HTTP message signatures.

Signer:

The entity that is generating or has generated an HTTP message signature. Note that multiple entities can act as signers and apply separate HTTP message signatures to a given HTTP message.

Verifier:

An entity that is verifying or has verified an HTTP message signature against an HTTP message. Note that an HTTP message signature may be verified multiple times, potentially by different entities.

HTTP Message Component:

A portion of an HTTP message that is capable of being covered by an HTTP message signature.

Derived Component:

An HTTP message component derived from the HTTP message through the use of a specified algorithm or process. See Section 2.2.

HTTP Message Component Name:

A String that identifies an HTTP message component's source, such as a field name or derived component name.

HTTP Message Component Identifier:

The combination of an HTTP message component name and any parameters. This combination uniquely identifies a specific HTTP message component with respect to a particular HTTP message signature and the HTTP message it applies to.

HTTP Message Component Value:

The value associated with a given component identifier within the context of a particular HTTP message. Component values are derived from the HTTP message and are usually subject to a canonicalization process.

Covered Components:

An ordered set of HTTP message component identifiers for fields (Section 2.1) and derived components (Section 2.2) that indicates the set of message components covered by the signature, never including the @signature-params identifier itself. The order of this set is preserved and communicated between the signer and verifier to facilitate reconstruction of the signature base.

Signature Base:

The sequence of bytes generated by the signer and verifier using the covered components set and the HTTP message. The signature base is processed by the cryptographic algorithm to produce or verify the HTTP message signature.

HTTP Message Signature Algorithm:

A cryptographic algorithm that describes the signing and verification process for the signature, defined in terms of the HTTP_SIGN and HTTP_VERIFY primitives described in Section 3.3.

Key Material:

The key material required to create or verify the signature. The key material is often identified with an explicit key identifier, allowing the signer to indicate to the verifier which key was used.

Creation Time:

A timestamp representing the point in time that the signature was generated, as asserted by the signer.

Expiration Time:

A timestamp representing the point in time after which the signature should no longer be accepted by the verifier, as asserted by the signer.

Target Message:

The HTTP message to which an HTTP message signature is applied.

Signature Context:

The data source from which the HTTP message component values are drawn. The context includes the target message and any additional information the signer or verifier might have, such as the full target URI of a request or the related request message for a response.

• Reordering of fields with different field names (Section 5.3 of [HTTP]).
• Combination of fields with the same field name (Section 5.2 of [HTTP]).
• Removal of fields listed in the Connection header field (Section 7.6.1 of [HTTP]).
• Addition of fields that indicate control options (Section 7.6.1 of [HTTP]).
• Addition or removal of a transfer coding (Section 7.7 of [HTTP]).
• Addition of fields such as Via (Section 7.6.3 of [HTTP]) and Forwarded (Section 4 of RFC 7239).
• Conversion between different versions of HTTP (e.g., HTTP/1.x to HTTP/2, or vice versa).
• Changes in case (e.g., "Origin" to "origin") of any case-insensitive components such as field names, request URI scheme, or host.
• Changes to the request target and authority that, when applied together, do not result in a change to the message's target URI, as defined in Section 7.1 of [HTTP].

• Use, addition, or removal of leading or trailing whitespace in a field value.
• Use, addition, or removal of obs-fold in field values (Section 5.2 of [HTTP/1.1]).

• The set of Section 2 and Section 2.3 that are expected and required to be included in the covered components list. For example, an authorization protocol could mandate that the Authorization field be covered to protect the authorization credentials and mandate that the signature parameters contain a created parameter (Section 2.3), while an API expecting semantically relevant HTTP message content could require the Content-Digest field defined in [DIGEST] to be present and covered as well as mandate a value for the tag parameter (Section 2.3) that is specific to the API being protected.
• The expected Structured Field types [STRUCTURED-FIELDS] of any required or expected covered component fields or parameters.
• A means of retrieving the key material used to verify the signature. An application will usually use the keyid parameter of the signature parameters (Section 2.3) and define rules for resolving a key from there, though the appropriate key could be known from other means such as preregistration of a signer's key.
• The set of allowable signature algorithms to be used by signers and accepted by verifiers.
• A means of determining that the signature algorithm used to verify the signature is appropriate for the key material and context of the message. For example, the process could use the alg parameter of the signature parameters (Section 2.3) to state the algorithm explicitly, derive the algorithm from the key material, or use some preconfigured algorithm agreed upon by the signer and verifier.
• A means of determining that a given key and algorithm used for a signature are appropriate for the context of the message. For example, a server expecting only ECDSA signatures should know to reject any RSA signatures, or a server expecting asymmetric cryptography should know to reject any symmetric cryptography.
• A means of determining the context for derivation of message components from an HTTP message and its application context. While this is normally the target HTTP message itself, the context could include additional information known to the application through configuration, such as an external hostname.
• If binding between a request and response is needed using the mechanism provided in Section 2.4, all elements of the request message and the response message that would be required to provide properties of such a binding.
• The error messages and codes that are returned from the verifier to the signer when the signature is invalid, the key material is inappropriate, the validity time window is out of specification, a component value cannot be calculated, or any other errors occur during the signature verification process. For example, if a signature is being used as an authentication mechanism, an HTTP status code of 401 (Unauthorized) or 403 (Forbidden) could be appropriate. If the response is from an HTTP API, a response with an HTTP status code such as 400 (Bad Request) could include more details [RFC 7807] [RFC 9457], such as an indicator that the wrong key material was used.

1. Create an ordered list of the field values of each instance of the field in the message, in the order they occur (or will occur) in the message.
2. Strip leading and trailing whitespace from each item in the list. Note that since HTTP field values are not allowed to contain leading and trailing whitespace, this would be a no-op in a compliant implementation.
3. Remove any obsolete line folding within the line, and replace it with a single space (" "), as discussed in Section 5.2 of [HTTP/1.1]. Note that this behavior is specific to HTTP/1.1 and does not apply to other versions of the HTTP specification, which do not allow internal line folding.
4. Concatenate the list of values with a single comma (",") and a single space (" ") between each item.

Host: www.example.com
Date: Tue, 20 Apr 2021 02:07:56 GMT
X-OWS-Header:   Leading and trailing whitespace.
X-Obs-Fold-Header: Obsolete
    line folding.
Cache-Control: max-age=60
Cache-Control:    must-revalidate
Example-Dict:  a=1,    b=2;x=1;y=2,   c=(a   b   c)

"host": www.example.com
"date": Tue, 20 Apr 2021 02:07:56 GMT
"x-ows-header": Leading and trailing whitespace.
"x-obs-fold-header": Obsolete line folding.
"cache-control": max-age=60, must-revalidate
"example-dict": a=1,    b=2;x=1;y=2,   c=(a   b   c)

X-Empty-Header:(SP)

"x-empty-header":(SP)

sf

A Boolean flag indicating that the component value is serialized using strict encoding of the Structured Field value (Section 2.1.1).

key

A String parameter used to select a single member value from a Dictionary Structured Field (Section 2.1.2).

bs

A Boolean flag indicating that individual field values are encoded using Byte Sequence data structures before being combined into the component value (Section 2.1.3).

req

A Boolean flag for signed responses indicating that the component value is derived from the request that triggered this response message and not from the response message directly. Note that this parameter can also be applied to any derived component identifiers that target the request (Section 2.4).

tr

A Boolean flag indicating that the field value is taken from the trailers of the message as defined in Section 6.5 of [HTTP]. If this flag is absent, the field value is taken from the header fields of the message as defined in Section 6.3 of [HTTP] (Section 2.1.4).

1. Let the input be the ordered set of values for a field, in the order they appear in the message.
2. Create an empty List for accumulating processed field values.
3. For each field value in the set:

   3.1.

   Strip leading and trailing whitespace from the field value. Note that since HTTP field values are not allowed to contain leading and trailing whitespace, this would be a no-op in a compliant implementation.

   3.2.

   Remove any obsolete line folding within the line, and replace it with a single space (" "), as discussed in Section 5.2 of [HTTP/1.1]. Note that this behavior is specific to [HTTP/1.1] and does not apply to other versions of the HTTP specification.

   3.3.

   Encode the bytes of the resulting field value as a Byte Sequence. Note that most fields are restricted to ASCII characters, but other octets could be included in the value in some implementations.

   3.4.

   Add the Byte Sequence to the List accumulator.
4. The intermediate result is a List of Byte Sequence values.
5. Follow the strict serialization of a List as described in Section 4.1.1 of [STRUCTURED-FIELDS], and return this output.

Example-Header: value, with, lots
Example-Header: of, commas

Example-Header: value, with, lots, of, commas

"example-header": value, with, lots, of, commas

"example-header";bs: :dmFsdWUsIHdpdGgsIGxvdHM=:, :b2YsIGNvbW1hcw==:

"example-header";bs: :dmFsdWUsIHdpdGgsIGxvdHMsIG9mLCBjb21tYXM=:

@method

The method used for a request (Section 2.2.1).

@target-uri

The full target URI for a request (Section 2.2.2).

@authority

The authority of the target URI for a request (Section 2.2.3).

@scheme

The scheme of the target URI for a request (Section 2.2.4).

@request-target

The request target (Section 2.2.5).

@path

The absolute path portion of the target URI for a request (Section 2.2.6).

@query

The query portion of the target URI for a request (Section 2.2.7).

@query-param

A parsed and encoded query parameter of the target URI for a request (Section 2.2.8).

@status

The status code for a response (Section 2.2.9).

request:

Values derived from, and results applied to, an HTTP request message as described in Section 3.4 of [HTTP]. If the target message of the signature is a response, derived components that target request messages can be included by using the req parameter as defined in Section 2.4.

response:

Values derived from, and results applied to, an HTTP response message as described in Section 3.4 of [HTTP].

request, response:

Values derived from, and results applied to, either a request message or a response message.

1. Parse the nameString or valueString of the named query parameter defined by Section [HTMLURL] of [HTMLURL]; this is the value after percent-encoded octets are decoded.
2. Encode the nameString or valueString using the "percent-encode after encoding" process defined by Section [HTMLURL] of [HTMLURL]; this results in an ASCII string [ASCII].
3. Output the ASCII string.

GET /path?param=value&foo=bar&baz=batman&qux= HTTP/1.1
Host: www.example.com

"@query-param";name="baz": batman
"@query-param";name="qux":(SP)
"@query-param";name="param": value

NOTE: '\' line wrapping per RFC 8792

GET /parameters?var=this%20is%20a%20big%0Amultiline%20value&\
  bar=with+plus+whitespace&fa%C3%A7ade%22%3A%20=something HTTP/1.1
Host: www.example.com
Date: Tue, 20 Apr 2021 02:07:56 GMT

"@query-param";name="var": this%20is%20a%20big%0Amultiline%20value
"@query-param";name="bar": with%20plus%20whitespace
"@query-param";name="fa%C3%A7ade%22%3A%20": something

"@query-param";name="var": this is a big
multiline value
"@query-param";name="bar": with plus whitespace
"@query-param";name="façade\": ": something

created:

Creation time as a UNIX timestamp value of type Integer. Sub-second precision is not supported. The inclusion of this parameter is RECOMMENDED.

expires:

Expiration time as a UNIX timestamp value of type Integer. Sub-second precision is not supported.

nonce:

A random unique value generated for this signature as a String value.

alg:

The HTTP message signature algorithm from the "HTTP Signature Algorithms" registry, as a String value.

keyid:

The identifier for the key material as a String value.

tag:

An application-specific tag for the signature as a String value. This value is used by applications to help identify signatures relevant for specific applications or protocols.

1. Let the output be an empty string.
2. Determine an order for the component identifiers of the covered components, not including the @signature-params component identifier itself. Once this order is chosen, it cannot be changed. This order MUST be the same order as that used in creating the signature base (Section 2.5).
3. Serialize the component identifiers of the covered components, including all parameters, as an ordered Inner List of String values according to Section 4.1.1.1 of [STRUCTURED-FIELDS]; then, append this to the output. Note that the component identifiers can include their own parameters, and these parameters are ordered sets. Once an order is chosen for a component's parameters, the order cannot be changed.
4. Determine an order for any signature parameters. Once this order is chosen, it cannot be changed.
5. Append the parameters to the Inner List in order according to Section 4.1.1.2 of [STRUCTURED-FIELDS], skipping parameters that are not available or not used for this message signature.
6. The output contains the signature parameters component value.

NOTE: '\' line wrapping per RFC 8792

("@target-uri" "@authority" "date" "cache-control")\
  ;keyid="test-key-rsa-pss";alg="rsa-pss-sha512";\
  created=1618884475;expires=1618884775

req

A Boolean flag indicating that the component value is derived from the request that triggered this response message and not from the response message directly.

NOTE: '\' line wrapping per RFC 8792

POST /foo?param=Value&Pet=dog HTTP/1.1
Host: example.com
Date: Tue, 20 Apr 2021 02:07:55 GMT
Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\
  aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==:
Content-Type: application/json
Content-Length: 18

{"hello": "world"}

NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 503 Service Unavailable
Date: Tue, 20 Apr 2021 02:07:56 GMT
Content-Type: application/json
Content-Length: 62
Content-Digest: sha-512=:0Y6iCBzGg5rZtoXS95Ijz03mslf6KAMCloESHObfwn\
  HJDbkkWWQz6PhhU9kxsTbARtY2PTBOzq24uJFpHsMuAg==:

{"busy": true, "message": "Your call is very important to us"}

NOTE: '\' line wrapping per RFC 8792

"@status": 503
"content-digest": sha-512=:0Y6iCBzGg5rZtoXS95Ijz03mslf6KAMCloESHObf\
  wnHJDbkkWWQz6PhhU9kxsTbARtY2PTBOzq24uJFpHsMuAg==:
"content-type": application/json
"@authority";req: example.com
"@method";req: POST
"@path";req: /foo
"content-digest";req: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A\
  2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==:
"@signature-params": ("@status" "content-digest" "content-type" \
  "@authority";req "@method";req "@path";req "content-digest";req)\
  ;created=1618884479;keyid="test-key-ecc-p256"

NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 503 Service Unavailable
Date: Tue, 20 Apr 2021 02:07:56 GMT
Content-Type: application/json
Content-Length: 62
Content-Digest: sha-512=:0Y6iCBzGg5rZtoXS95Ijz03mslf6KAMCloESHObfwn\
  HJDbkkWWQz6PhhU9kxsTbARtY2PTBOzq24uJFpHsMuAg==:
Signature-Input: reqres=("@status" "content-digest" "content-type" \
  "@authority";req "@method";req "@path";req "content-digest";req)\
  ;created=1618884479;keyid="test-key-ecc-p256"
Signature: reqres=:dMT/A/76ehrdBTD/2Xx8QuKV6FoyzEP/I9hdzKN8LQJLNgzU\
  4W767HK05rx1i8meNQQgQPgQp8wq2ive3tV5Ag==:

{"busy": true, "message": "Your call is very important to us"}

NOTE: '\' line wrapping per RFC 8792

POST /foo?param=Value&Pet=dog HTTP/1.1
Host: example.com
Date: Tue, 20 Apr 2021 02:07:55 GMT
Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\
  aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==:
Content-Type: application/json
Content-Length: 18
Signature-Input: sig1=("@method" "@authority" "@path" "@query" \
  "content-digest" "content-type" "content-length")\
  ;created=1618884475;keyid="test-key-rsa-pss"
Signature: sig1=:e8UJ5wMiRaonlth5ERtE8GIiEH7Akcr493nQ07VPNo6y3qvjdK\
  t0fo8VHO8xXDjmtYoatGYBGJVlMfIp06eVMEyNW2I4vN7XDAz7m5v1108vGzaDljr\
  d0H8+SJ28g7bzn6h2xeL/8q+qUwahWA/JmC8aOC9iVnwbOKCc0WSrLgWQwTY6VLp4\
  2Qt7jjhYT5W7/wCvfK9A1VmHH1lJXsV873Z6hpxesd50PSmO+xaNeYvDLvVdZlhtw\
  5PCtUYzKjHqwmaQ6DEuM8udRjYsoNqp2xZKcuCO1nKc0V3RjpqMZLuuyVbHDAbCzr\
  0pg2d2VM/OC33JAU7meEjjaNz+d7LWPg==:

{"hello": "world"}

NOTE: '\' line wrapping per RFC 8792

"@status": 503
"content-digest": sha-512=:0Y6iCBzGg5rZtoXS95Ijz03mslf6KAMCloESHObf\
  wnHJDbkkWWQz6PhhU9kxsTbARtY2PTBOzq24uJFpHsMuAg==:
"content-type": application/json
"@authority";req: example.com
"@method";req: POST
"@path";req: /foo
"@query";req: ?param=Value&Pet=dog
"content-digest";req: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A\
  2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==:
"content-type";req: application/json
"content-length";req: 18
"@signature-params": ("@status" "content-digest" "content-type" \
  "@authority";req "@method";req "@path";req "@query";req \
  "content-digest";req "content-type";req "content-length";req)\
  ;created=1618884479;keyid="test-key-ecc-p256"

NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 503 Service Unavailable
Date: Tue, 20 Apr 2021 02:07:56 GMT
Content-Type: application/json
Content-Length: 62
Content-Digest: sha-512=:0Y6iCBzGg5rZtoXS95Ijz03mslf6KAMCloESHObfwn\
  HJDbkkWWQz6PhhU9kxsTbARtY2PTBOzq24uJFpHsMuAg==:
Signature-Input: reqres=("@status" "content-digest" "content-type" \
  "@authority";req "@method";req "@path";req "@query";req \
  "content-digest";req "content-type";req "content-length";req)\
  ;created=1618884479;keyid="test-key-ecc-p256"
Signature: reqres=:C73J41GVKc+TYXbSobvZf0CmNcptRiWN+NY1Or0A36ISg6ym\
  dRN6ZgR2QfrtopFNzqAyv+CeWrMsNbcV2Ojsgg==:

{"busy": true, "message": "Your call is very important to us"}

signature-base = *( signature-base-line LF ) signature-params-line
signature-base-line = component-identifier ":" SP
    ( derived-component-value / *field-content )
    ; no obs-fold nor obs-text
component-identifier = component-name parameters
component-name = sf-string
derived-component-value = *( VCHAR / SP )
signature-params-line = DQUOTE "@signature-params" DQUOTE
     ":" SP inner-list

1. Let the output be an empty string.
2. For each message component item in the covered components set (in order):

   2.1.

   If the component identifier (including its parameters) has already been added to the signature base, produce an error.

   2.2.

   Append the component identifier for the covered component serialized according to the component-identifier ABNF rule. Note that this serialization places the component name in double quotes and appends any parameters outside of the quotes.

   2.3.

   Append a single colon (:).

   2.4.

   Append a single space (" ").

   2.5.

   Determine the component value for the component identifier.

   • If the component identifier has a parameter that is not understood, produce an error.
   • If the component identifier has parameters that are mutually incompatible with one another, such as bs and sf, produce an error.
   • If the component identifier contains the req parameter and the target message is a request, produce an error.
   • If the component identifier contains the req parameter and the target message is a response, the context for the component value is the related request message of the target response message. Otherwise, the context for the component value is the target message.
   • If the component name starts with an "at" (@) character, derive the component's value from the message according to the specific rules defined for the derived component, as provided in Section 2.2, including processing of any known valid parameters. If the derived component name is unknown or the value cannot be derived, produce an error.
   • If the component name does not start with an "at" (@) character, canonicalize the HTTP field value as described in Section 2.1, including processing of any known valid parameters. If the field cannot be found in the message or the value cannot be obtained in the context, produce an error.

   2.6.

   Append the covered component's canonicalized component value.

   2.7.

   Append a single newline (\n).
3. Append the signature parameters component (Section 2.3) according to the signature-params-line rule as follows:

   3.1.

   Append the component identifier for the signature parameters serialized according to the component-identifier rule, i.e., the exact value "@signature-params" (including double quotes).

   3.2.

   Append a single colon (:).

   3.3.

   Append a single space (" ").

   3.4.

   Append the signature parameters' canonicalized component values as defined in Section 2.3, i.e., Inner List Structured Field values with parameters.
4. Produce an error if the output string contains any non-ASCII characters [ASCII].
5. Return the output string.

• The signer or verifier does not understand the derived component name.
• The component name identifies a field that is not present in the message or whose value is malformed.
• The component identifier includes a parameter that is unknown or does not apply to the component identifier to which it is attached.
• The component identifier indicates that a Structured Field serialization is used (via the sf parameter), but the field in question is known to not be a Structured Field or the type of Structured Field is not known to the implementation.
• The component identifier is a Dictionary member identifier that references a field that is not present in the message, that is not a Dictionary Structured Field, or whose value is malformed.
• The component identifier is a Dictionary member identifier or a named query parameter identifier that references a member that is not present in the component value or whose value is malformed. For example, the identifier is "example-dict";key="c", and the value of the Example-Dict header field is a=1, b=2, which does not have the c value.

NOTE: '\' line wrapping per RFC 8792

POST /foo?param=Value&Pet=dog HTTP/1.1
Host: example.com
Date: Tue, 20 Apr 2021 02:07:55 GMT
Content-Type: application/json
Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\
  aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==:
Content-Length: 18

{"hello": "world"}

NOTE: '\' line wrapping per RFC 8792

"@method": POST
"@authority": example.com
"@path": /foo
"content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\
  +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==:
"content-length": 18
"content-type": application/json
"@signature-params": ("@method" "@authority" "@path" \
  "content-digest" "content-length" "content-type")\
  ;created=1618884473;keyid="test-key-rsa-pss"

1. The signer chooses an HTTP signature algorithm and key material for signing from the set of potential signing algorithms. The set of potential algorithms is determined by the application and is out of scope for this document. The signer MUST choose key material that is appropriate for the signature's algorithm and that conforms to any requirements defined by the algorithm, such as key size or format. The mechanism by which the signer chooses the algorithm and key material is out of scope for this document.
2. The signer sets the signature's creation time to the current time.
3. If applicable, the signer sets the signature's expiration time property to the time at which the signature is to expire. The expiration is a hint to the verifier, expressing the time at which the signer is no longer willing to vouch for the signature. An appropriate expiration length, and the processing requirements of this parameter, are application specific.
4. The signer creates an ordered set of component identifiers representing the message components to be covered by the signature and attaches signature metadata parameters to this set. The serialized value of this set is later used as the value of the Signature-Input field as described in Section 4.1.
   • Once an order of covered components is chosen, the order MUST NOT change for the life of the signature.
   • Each covered component identifier MUST be either (1) an HTTP field (Section 2.1) in the signature context or (2) a derived component listed in Section 2.2 or in the "HTTP Signature Derived Component Names" registry.
   • Signers of a request SHOULD include some or all of the message control data in the covered components, such as the @method, @authority, @target-uri, or some combination thereof.
   • Signers SHOULD include the created signature metadata parameter to indicate when the signature was created.
   • The @signature-params derived component identifier MUST NOT be present in the list of covered component identifiers. The derived component is required to always be the last line in the signature base, ensuring that a signature always covers its own metadata and the metadata cannot be substituted.
   • Further guidance on what to include in this set and in what order is out of scope for this document.
5. The signer creates the signature base using these parameters and the signature base creation algorithm (Section 2.5).
6. The signer uses the HTTP_SIGN primitive function to sign the signature base with the chosen signing algorithm using the key material chosen by the signer. The HTTP_SIGN primitive and several concrete applications of signing algorithms are defined in Section 3.3.
7. The byte array output of the signature function is the HTTP message signature output value to be included in the Signature field as defined in Section 4.2.

NOTE: '\' line wrapping per RFC 8792

HIbjHC5rS0BYaa9v4QfD4193TORw7u9edguPh0AW3dMq9WImrlFrCGUDih47vAxi4L2\
YRZ3XMJc1uOKk/J0ZmZ+wcta4nKIgBkKq0rM9hs3CQyxXGxHLMCy8uqK488o+9jrptQ\
+xFPHK7a9sRL1IXNaagCNN3ZxJsYapFj+JXbmaI5rtAdSfSvzPuBCh+ARHBmWuNo1Uz\
VVdHXrl8ePL4cccqlazIJdC4QEjrF+Sn4IxBQzTZsL9y9TP5FsZYzHvDqbInkTNigBc\
E9cKOYNFCn4D/WM7F6TNuZO9EgtzepLWcjTymlHzK7aXq6Am6sfOrpIC49yXjj3ae6H\
RalVc/g==

1. Parse the Signature and Signature-Input fields as described in Sections [4.1] and [4.2], and extract the signatures to be verified and their labels.

   1.1.

   If there is more than one signature value present, determine which signature should be processed for this message based on the policy and configuration of the verifier. If an applicable signature is not found, produce an error.

   1.2.

   If the chosen Signature field value does not have a corresponding Signature-Input field value (i.e., one with the same label), produce an error.
2. Parse the values of the chosen Signature-Input field as a parameterized Inner List to get the ordered list of covered components and the signature parameters for the signature to be verified.
3. Parse the value of the corresponding Signature field to get the byte array value of the signature to be verified.
4. Examine the signature parameters to confirm that the signature meets the requirements described in this document, as well as any additional requirements defined by the application such as which message components are required to be covered by the signature (Section 3.2.1).
5. Determine the verification key material for this signature. If the key material is known through external means such as static configuration or external protocol negotiation, the verifier will use the applicable technique to obtain the key material from this external knowledge. If the key is identified in the signature parameters, the verifier will dereference the key identifier to appropriate key material to use with the signature. The verifier has to determine the trustworthiness of the key material for the context in which the signature is presented. If a key is identified that the verifier does not know or trust for this request or that does not match something preconfigured, the verification MUST fail.
6. Determine the algorithm to apply for verification:

   6.1.

   Start with the set of allowable algorithms known to the application. If any of the following steps select an algorithm that is not in this set, the signature validation fails.

   6.2.

   If the algorithm is known through external means such as static configuration or external protocol negotiation, the verifier will use that algorithm.

   6.3.

   If the algorithm can be determined from the keying material, such as through an algorithm field on the key value itself, the verifier will use that algorithm.

   6.4.

   If the algorithm is explicitly stated in the signature parameters using a value from the "HTTP Signature Algorithms" registry, the verifier will use the referenced algorithm.

   6.5.

   If the algorithm is specified in more than one location (e.g., a combination of static configuration, the algorithm signature parameter, and the key material itself), the resolved algorithms MUST be the same. If the algorithms are not the same, the verifier MUST fail the verification.
7. Use the received HTTP message and the parsed signature parameters to recreate the signature base, using the algorithm defined in Section 2.5. The value of the @signature-params input is the value of the Signature-Input field for this signature serialized according to the rules described in Section 2.3. Note that this does not include the signature's label from the Signature-Input field.
8. If the key material is appropriate for the algorithm, apply the appropriate HTTP_VERIFY cryptographic verification algorithm to the signature, recalculated signature base, key material, and signature value. The HTTP_VERIFY primitive and several concrete algorithms are defined in Section 3.3.
9. The results of the verification algorithm function are the final results of the cryptographic verification function.

NOTE: '\' line wrapping per RFC 8792

POST /foo?param=Value&Pet=dog HTTP/1.1
Host: example.com
Date: Tue, 20 Apr 2021 02:07:55 GMT
Content-Type: application/json
Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\
  aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==:
Content-Length: 18
Signature-Input: sig1=("@method" "@authority" "@path" \
  "content-digest" "content-length" "content-type")\
  ;created=1618884473;keyid="test-key-rsa-pss"
Signature: sig1=:HIbjHC5rS0BYaa9v4QfD4193TORw7u9edguPh0AW3dMq9WImrl\
  FrCGUDih47vAxi4L2YRZ3XMJc1uOKk/J0ZmZ+wcta4nKIgBkKq0rM9hs3CQyxXGxH\
  LMCy8uqK488o+9jrptQ+xFPHK7a9sRL1IXNaagCNN3ZxJsYapFj+JXbmaI5rtAdSf\
  SvzPuBCh+ARHBmWuNo1UzVVdHXrl8ePL4cccqlazIJdC4QEjrF+Sn4IxBQzTZsL9y\
  9TP5FsZYzHvDqbInkTNigBcE9cKOYNFCn4D/WM7F6TNuZO9EgtzepLWcjTymlHzK7\
  aXq6Am6sfOrpIC49yXjj3ae6HRalVc/g==:

{"hello": "world"}

• Requiring a specific set of header fields to be signed (e.g., Authorization, Content-Digest).
• Enforcing a maximum signature age from the time of the created timestamp.
• Rejecting signatures past the expiration time in the expires timestamp. Note that the expiration time is a hint from the signer and that a verifier can always reject a signature ahead of its expiration time.
• Prohibiting certain signature metadata parameters, such as runtime algorithm signaling with the alg parameter when the algorithm is determined from the key information.
• Ensuring successful dereferencing of the keyid parameter to valid and appropriate key material.
• Prohibiting the use of certain algorithms or mandating the use of a specific algorithm.
• Requiring keys to be of a certain size (e.g., 2048 bits vs. 1024 bits).
• Enforcing uniqueness of the nonce parameter.
• Requiring an application-specific value for the tag parameter.

NOTE: '\' line wrapping per RFC 8792

Accept-Signature: sig1=("@method" "@target-uri" "@authority" \
  "content-digest" "cache-control");\
  keyid="test-key-rsa-pss";created;tag="app-123"

created:

The signer is requested to generate and include a creation time. This parameter has no associated value when sent as a signature request.

expires:

The signer is requested to generate and include an expiration time. This parameter has no associated value when sent as a signature request.

nonce:

The signer is requested to include the value of this parameter as the signature nonce in the target signature.

alg:

The signer is requested to use the indicated signature algorithm from the "HTTP Signature Algorithms" registry to create the target signature.

keyid:

The signer is requested to use the indicated key material to create the target signature.

tag:

The signer is requested to include the value of this parameter as the signature tag in the target signature.

1. Parse the field value as a Dictionary.
2. For each member of the Dictionary:

   2.1.

   The key is taken as the label of the output signature as specified in Section 4.1.

   2.2.

   Parse the value of the member to obtain the set of covered component identifiers.

   2.3.

   Determine that the covered components are applicable to the target message. If not, the process fails and returns an error.

   2.4.

   Process the requested parameters, such as the signing algorithm and key material. If any requested parameters cannot be fulfilled or if the requested parameters conflict with those deemed appropriate to the target message, the process fails and returns an error.

   2.5.

   Select and generate any additional parameters necessary for completing the signature.

   2.6.

   Create the HTTP message signature over the target message.

   2.7.

   Create the Signature-Input and Signature field values, and associate them with the label.
3. Optionally create any additional Signature-Input and Signature field values, with unique labels not found in the Accept-Signature field.
4. Combine all labeled Signature-Input and Signature field values, and attach both fields to the target message.

• Ensure that the algorithms referenced by a registered algorithm identifier are fully defined with all parameters (e.g., salt, hash, required key length) fixed by the defining text.
• Ensure that the algorithm definition fully specifies the HTTP_SIGN and HTTP_VERIFY primitive functions, including how all defined inputs and outputs map to the underlying cryptographic algorithm.
• Reject any registrations that are aliases of existing registrations.
• Ensure that all registrations follow the template presented in Section 6.2.1; this includes ensuring that the length of the name is not excessive while still being unique and recognizable.

Algorithm Name:

An identifier for the HTTP signature algorithm. The name MUST be an ASCII string that conforms to the sf-string ABNF rule in Section 3.3.3 of [STRUCTURED-FIELDS] and SHOULD NOT exceed 20 characters in length. The identifier MUST be unique within the context of the registry.

Description:

A brief description of the algorithm used to sign the signature base.

Status:

The status of the algorithm. MUST start with one of the following values and MAY contain additional explanatory text. The options are:

"Active":

For algorithms without known problems. The signature algorithm is fully specified, and its security properties are understood.

"Provisional":

For unproven algorithms. The signature algorithm is fully specified, but its security properties are not known or proven.

"Deprecated":

For algorithms with known security issues. The signature algorithm is no longer recommended for general use and might be insecure or unsafe in some known circumstances.

Reference:

Reference to the document or documents that specify the algorithm, preferably including a URI that can be used to retrieve a copy of the document(s). An indication of the relevant sections may also be included but is not required.

• Ensure that the name follows the template presented in Section 6.3.1; this includes ensuring that the length of the name is not excessive while still being unique and recognizable for its defined function.
• Ensure that the defined functionality is clear and does not conflict with other registered parameters.
• Ensure that the definition of the metadata parameter includes its behavior when used as part of the normal signature process as well as when used in an Accept-Signature field.

Name:

An identifier for the HTTP signature metadata parameter. The name MUST be an ASCII string that conforms to the key ABNF rule defined in Section 3.1.2 of [STRUCTURED-FIELDS] and SHOULD NOT exceed 20 characters in length. The identifier MUST be unique within the context of the registry.

Description:

A brief description of the metadata parameter and what it represents.

Reference:

Reference to the document or documents that specify the parameter, preferably including a URI that can be used to retrieve a copy of the document(s). An indication of the relevant sections may also be included but is not required.

• Ensure that the name follows the template presented in Section 6.4.1; this includes ensuring that the length of the name is not excessive while still being unique and recognizable for its defined function.
• Ensure that the component value represented by the registration request can be deterministically derived from the target HTTP message.
• Ensure that any parameters defined for the registration request are clearly documented, along with their effects on the component value.

Name:

A name for the HTTP derived component. The name MUST begin with the "at" (@) character followed by an ASCII string consisting only of lowercase characters ("a"-"z"), digits ("0"-"9"), and hyphens ("-"), and SHOULD NOT exceed 20 characters in length. The name MUST be unique within the context of the registry.

Description:

A description of the derived component.

Status:

A brief text description of the status of the algorithm. The description MUST begin with one of "Active" or "Deprecated" and MAY provide further context or explanation as to the reason for the status. A value of "Deprecated" indicates that the derived component name is no longer recommended for use.

Target:

The valid message targets for the derived parameter. MUST be one of the values "Request", "Response", or "Request, Response". The semantics of these entries are defined in Section 2.2.

Reference:

Reference to the document or documents that specify the derived component, preferably including a URI that can be used to retrieve a copy of the document(s). An indication of the relevant sections may also be included but is not required.

• Ensure that the name follows the template presented in Section 6.5.1; this includes ensuring that the length of the name is not excessive while still being unique and recognizable for its defined function.
• Ensure that the definition of the field sufficiently defines any interactions or incompatibilities with other existing parameters known at the time of the registration request.
• Ensure that the component value defined by the component identifier with the parameter applied can be deterministically derived from the target HTTP message in cases where the parameter changes the component value.

Name:

A name for the parameter. The name MUST be an ASCII string that conforms to the key ABNF rule defined in Section 3.1.2 of [STRUCTURED-FIELDS] and SHOULD NOT exceed 20 characters in length. The name MUST be unique within the context of the registry.

Description:

A description of the parameter's function.

Reference:

Reference to the document or documents that specify the derived component, preferably including a URI that can be used to retrieve a copy of the document(s). An indication of the relevant sections may also be included but is not required.

• A signature is expected or allowed on the message by the verifier.
• The signature exists on the message.
• The signature is verified against the identified key material and algorithm.
• The key material and algorithm are appropriate for the context of the message.
• The signature is within expected time boundaries.
• The signature covers the expected content, including any critical components.
• The list of covered components is applicable to the context of the message.

"date"

The Date header field value represents the timestamp of the HTTP message. However, the creation time of the signature itself is encoded in the created signature parameter. These two values can be different, depending on how the signature and the HTTP message are created and serialized. Applications processing signatures for valid time windows should use the created signature parameter for such calculations. An application could also put limits on how much skew there is between the Date field and the created signature parameter, in order to limit the application of a generated signature to different HTTP messages. See also Sections [7.2.2] and [7.2.1].

"host"

The Host header field is specific to HTTP/1.1, and its functionality is subsumed by the @authority derived component, defined in Section 2.2.3. In order to preserve the value across different HTTP versions, applications should always use the @authority derived component. See also Section 7.5.4.

1. Alice creates a message Req_A and applies a signature Sig_A using her private key Key_A_Sign.
2. Alice believes she is sending Req_A to Bob.
3. Mallory intercepts Req_A and reads the value Sig_A from this message.
4. Mallory generates a different message Req_M to send to Bob instead.
5. Mallory crafts a signing key Key_M_Sign such that she can create a valid signature Sig_M over her request Req_M using this key, but the byte value of Sig_M exactly equals that of Sig_A.
6. Mallory sends Req_M with Sig_M to Bob.
7. Bob validates Sig_M against Mallory's verification key Key_M_Verify. At no time does Bob think that he's responding to Alice.
8. Bob responds with response message Res_B to Req_M and creates signature Sig_B over this message using his key Key_B_Sign. Bob includes the value of Sig_M under Sig_B's covered components but does not include anything else from the request message.
9. Mallory receives the response Res_B from Bob, including the signature Sig_B value. Mallory replays this response to Alice.
10. Alice reads Res_B from Mallory and verifies Sig_B using Bob's verification key Key_B_Verify. Alice includes the bytes of her original signature Sig_A in the signature base, and the signature verifies.
11. Alice is led to believe that Bob has responded to her message and believes she has cryptographic proof of this happening, but in fact Bob responded to Mallory's malicious request and Alice is none the wiser.

[ABNF]

D. Crocker, and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.

[ASCII]

V.G. Cerf, "ASCII format for network interchange", STD 80, RFC 20, DOI 10.17487/RFC0020, October 1969,
<https://www.rfc-editor.org/info/rfc20>.

[FIPS186-5]

NIST, "Digital Signature Standard (DSS)", DOI 10.6028/NIST.FIPS.186-5, February 2023,
<https://doi.org/10.6028/NIST.FIPS.186-5>.

[HTMLURL]

WHATWG, "URL (Living Standard)", January 2024,
<https://url.spec.whatwg.org/>.

[HTTP]

R. Fielding, M. Nottingham, and J. Reschke, "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>.

[HTTP/1.1]

R. Fielding, M. Nottingham, and J. Reschke, "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, June 2022,
<https://www.rfc-editor.org/info/rfc9112>.

[POSIX.1]

IEEE, "The Open Group Base Specifications Issue 7, 2018 edition", 2018,
<https://pubs.opengroup.org/onlinepubs/9699919799/>.

[RFC2104]

H. Krawczyk, M. Bellare, and R. Canetti, "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, DOI 10.17487/RFC2104, February 1997,
<https://www.rfc-editor.org/info/rfc2104>.

[RFC2119]

S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.

[RFC6234]

D. Eastlake 3rd, and T. Hansen, "US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)", RFC 6234, DOI 10.17487/RFC6234, May 2011,
<https://www.rfc-editor.org/info/rfc6234>.

[RFC7517]

M. Jones, "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015,
<https://www.rfc-editor.org/info/rfc7517>.

[RFC7518]

M. Jones, "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015,
<https://www.rfc-editor.org/info/rfc7518>.

[RFC8017]

K. Moriarty, B. Kaliski, J. Jonsson, and A. Rusch, "PKCS #1: RSA Cryptography Specifications Version 2.2", RFC 8017, DOI 10.17487/RFC8017, November 2016,
<https://www.rfc-editor.org/info/rfc8017>.

[RFC8032]

S. Josefsson, and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, January 2017,
<https://www.rfc-editor.org/info/rfc8032>.

[RFC8174]

B. Leiba, "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017,
<https://www.rfc-editor.org/info/rfc8174>.

[STRUCTURED-FIELDS]

M. Nottingham, and P-H. Kamp, "Structured Field Values for HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
<https://www.rfc-editor.org/info/rfc8941>.

[URI]

T. Berners-Lee, R. Fielding, and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.

[AWS-SIGv4]

Amazon Simple Storage Service, "Authenticating Requests (AWS Signature Version 4)", March 2006,
<https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html>.

[BCP195]

K. Moriarty, and S. Farrell, "Deprecating TLS 1.0 and TLS 1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, March 2021,
<https://www.rfc-editor.org/info/rfc8996>.

Y. Sheffer, P. Saint-Andre, and T. Fossati, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 9325, DOI 10.17487/RFC9325, November 2022,
<https://www.rfc-editor.org/info/rfc9325>.

[CLIENT-CERT]

B. Campbell, and M. Bishop, "Client-Cert HTTP Header Field", RFC 9440, DOI 10.17487/RFC9440, July 2023,
<https://www.rfc-editor.org/info/rfc9440>.

[COOKIE]

A. Barth, "HTTP State Management Mechanism", RFC 6265, DOI 10.17487/RFC6265, April 2011,
<https://www.rfc-editor.org/info/rfc6265>.

[DIGEST]

Cloudflare, R. Polli, and L. Pardue, "Digest Fields", RFC 9530, DOI 10.17487/RFC9530, February 2024,
<https://www.rfc-editor.org/info/rfc9530>.

[JACKSON2019]

Department of Computer Science, ETH Zurich, D. Jackson, C. Cremers, K. Cohn-Gordon, and R. Sasse, "Seems Legit: Automated Analysis of Subtle Attacks on Protocols that Use Signatures", DOI 10.1145/3319535.3339813, November 2019,
<https://dl.acm.org/doi/10.1145/3319535.3339813>.

[JWS]

M. Jones, J. Bradley, and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015,
<https://www.rfc-editor.org/info/rfc7515>.

[RFC7239]

A. Petersson, and M. Nilsson, "Forwarded HTTP Extension", RFC 7239, DOI 10.17487/RFC7239, June 2014,
<https://www.rfc-editor.org/info/rfc7239>.

[RFC7468]

S. Josefsson, and S. Leonard, "Textual Encodings of PKIX, PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, April 2015,
<https://www.rfc-editor.org/info/rfc7468>.

[RFC7807]

M. Nottingham, and E. Wilde, "Problem Details for HTTP APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
<https://www.rfc-editor.org/info/rfc7807>.

[RFC8126]

M. Cotton, B. Leiba, and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.

[RFC8792]

K. Watsen, E. Auerswald, A. Farrel, and Q. Wu, "Handling Long Lines in Content of Internet-Drafts and RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
<https://www.rfc-editor.org/info/rfc8792>.

[RFC9457]

M. Nottingham, E. Wilde, and S. Dalal, "Problem Details for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023,
<https://www.rfc-editor.org/info/rfc9457>.

[SIGNING-HTTP-MESSAGES]

Digital Bazaar, M. Cavage, and M. Sporny, "Signing HTTP Messages", Internet-Draft draft-cavage-http-signatures-12, October 2019,
<https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12>.

[SIGNING-HTTP-REQS-OAUTH]

ARM Limited, J. Richer, J. Bradley, and H. Tschofenig, "A Method for Signing HTTP Requests for OAuth", Internet-Draft draft-ietf-oauth-signed-http-request-03, August 2016,
<https://datatracker.ietf.org/doc/html/draft-ietf-oauth-signed-http-request-03>.

[TLS]

E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.

Annabelle Backman

Justin Richer

Manu Sporny