HTTP Message Signatures

If the value of an HTTP field is known by the application to be a structured field type (as defined in [STRUCTURED-FIELDS] or its extensions or updates), and the expected type of the structured field is known, the signer MAY include the sf parameter in the component identifier. If this parameter is included with a component identifier, the HTTP field value MUST be serialized using the formal serialization rules specified in Section 4 of [STRUCTURED-FIELDS] (or the applicable formal serialization section of its extensions or updates) applicable to the type of the HTTP field. Note that this process will replace any optional internal whitespace with a single space character, among other potential transformations of the value.¶

If multiple field values occur within a message, these values MUST be combined into a single List or Dictionary structure before serialization.¶

If the application does not know the type of the field, or the application does not know how to serialize the type of the field, the use of this flag will produce an error. As a consequence, the signer can only reliably sign fields using this flag when the verifier's system knows the type as well.¶

The resulting string is used as the component value in Section 2.1.¶

If a given field is known by the application to be a Dictionary structured field, an individual member in the value of that Dictionary is identified by using the parameter key and the Dictionary member key as a String value.¶

If multiple field values occur within a message, these values MUST be combined into a single Dictionary structure before serialization.¶

An individual member value of a Dictionary Structured Field is canonicalized by applying the serialization algorithm described in Section 4.1.2 of [STRUCTURED-FIELDS] on the member_value and its parameters, not including the dictionary key itself. Specifically, the value is serialized as an Item or Inner List (the two possible values of a Dictionary member), with all parameters and possible sub-fields serialized using the strict serialization rules defined in Section 4 of [STRUCTURED-FIELDS] (or the applicable section of its extensions or updates).¶

Each parameterized key for a given field MUST NOT appear more than once in the signature base. Parameterized keys MAY appear in any order in the signature base, regardless of the order they occur in the source Dictionary.¶

If a Dictionary key is named as a covered component but it does not occur in the Dictionary, this MUST cause an error in the signature base generation.¶

Note that the value for key="c" has been re-serialized according to the strict member_value algorithm, and the value for key="d" has been serialized as a Boolean value.¶

If the value of the the HTTP field in question is known by the application to cause problems with serialization, particularly with the combination of multiple values into a single line as discussed in Section 7.5.6, the signer SHOULD include the bs parameter in a component identifier to indicate the values of the fields need to be wrapped as binary structures before being combined.¶

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:
   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 will be a no-op in a compliant implementation.
   2. Remove any obsolete line-folding within the line and replace it with a single space (" "), as discussed in Section 5.2 of [HTTP1]. Note that this behavior is specific to [HTTP1] and does not apply to other versions of the HTTP specification.
   3. Encode the bytes of the resulting field value's ASCII representation as a Byte Sequence.
   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.

This component value is distinct from the multiple-instance field above, preventing a collision which could potentially be exploited.¶

If the signer wants to include a trailer field in the signature, the signer MUST include the tr boolean parameter to indicate the value MUST be taken from the trailer fields and not from the header fields.¶

If a field is available as both a header and trailer in a message, both values MAY be signed, but the values MUST be signed separately. The values of header fields and trailer fields of the same name MUST NOT be combined for purposes of the signature.¶

Since trailer fields could be merged into the header fields or dropped entirely by intermediaries as per Section 6.5.1 of [HTTP], it is NOT RECOMMENDED to include trailers in the signature unless the signer knows that the verifier will have access to the values of the trailers as sent.¶

The @method derived component refers to the HTTP method of a request message. The component value is canonicalized by taking the value of the method as a string. Note that the method name is case-sensitive as per [HTTP], Section 9.1. While conventionally standardized method names are uppercase US-ASCII, no transformation to the input method value's case is performed.¶

The @target-uri derived component refers to the target URI of a request message. The component value is the full absolute target URI of the request, potentially assembled from all available parts including the authority and request target as described in [HTTP], Section 7.1.¶

The @authority derived component refers to the authority component of the target URI of the HTTP request message, as defined in [HTTP], Section 7.2. In HTTP/1.1, this is usually conveyed using the Host header, while in HTTP/2 and HTTP/3 it is conveyed using the :authority pseudo-header. The value is the fully-qualified authority component of the request, comprised of the host and, optionally, port of the request target, as a string. The component value MUST be normalized according to the rules in [HTTP], Section 4.2.3. Namely, the host name is normalized to lowercase and the default port is omitted.¶

The @authority derived component SHOULD be used instead of signing the Host header directly, see Section 7.2.4.¶

The @scheme derived component refers to the scheme of the target URL of the HTTP request message. The component value is the scheme as a lowercase string as defined in [HTTP], Section 4.2. While the scheme itself is case-insensitive, it MUST be normalized to lowercase for inclusion in the signature base.¶

The @request-target derived component refers to the full request target of the HTTP request message, as defined in [HTTP], Section 7.1. The component value of the request target can take different forms, depending on the type of request, as described below.¶

For HTTP/1.1, the component value is equivalent to the request target portion of the request line. However, this value is more difficult to reliably construct in other versions of HTTP. Therefore, it is NOT RECOMMENDED that this component be used when versions of HTTP other than 1.1 might be in use.¶

The @path derived component refers to the target path of the HTTP request message. The component value is the absolute path of the request target defined by [URI], with no query component and no trailing ? character. The value is normalized according to the rules in [HTTP], Section 4.2.3. Namely, an empty path string is normalized as a single slash / character. Path components are represented by their values before decoding any percent-encoded octets, as described in the simple string comparison rules in Section 6.2.1 of [URI].¶

The @query derived component refers to the query component of the HTTP request message. The component value is the entire normalized query string defined by [URI], including the leading ? character. The value is read using the simple string comparison rules in Section 6.2.1 of [URI]. Namely, percent-encoded octets are not decoded.¶

If a request target URI uses HTML form parameters in the query string as defined in the "application/x-www-form-urlencoded" section of [HTMLURL], the @query-param derived component allows addressing of individual query parameters. The query parameters MUST be parsed according to the "application/x-www-form-urlencoded parsing" section of [HTMLURL], resulting in a list of (nameString, valueString) tuples. The REQUIRED name parameter of each component identifier contains the nameString of a single query parameter as a String value. Several different named query parameters MAY be included in the covered components. Single named parameters MAY occur in any order in the covered components.¶

The component value of a single named parameter is the valueString of the named query parameter defined by "application/x-www-form-urlencoded parsing" section of [HTMLURL], which is the value after percent-encoded octets are decoded. Note that this value does not include any leading ? characters, equals sign =, or separating & characters. Named query parameters with an empty valueString are included with an empty string as the component value.¶

If a query parameter is named as a covered component but it does not occur in the query parameters, this MUST cause an error in the signature base generation.¶

baz: batman ¶

qux: an empty string¶

param: value ¶

If a parameter name occurs multiple times in a request, all parameter values of that name MUST be included in separate signature base lines in the order in which the parameters occur in the target URI. Note that in some implementations, the order of parsed query parameters is not stable, and this situation could lead to unexpected results. If multiple parameters are common within an application, it is RECOMMENDED to sign the entire query string using the @query component identifier defined in Section 2.2.7.¶

The @status derived component refers to the three-digit numeric HTTP status code of a response message as defined in [HTTP], Section 15. The component value is the serialized three-digit integer of the HTTP status code, with no descriptive text.¶

The @status component identifier MUST NOT be used in a request message.¶

The verification requirements specified in this document are intended as a baseline set of restrictions that are generally applicable to all use cases. Applications using HTTP Message Signatures MAY impose requirements above and beyond those specified by this document, as appropriate for their use case.¶

• Requiring a specific set of header fields to be signed (e.g., Authorization, Digest).
• Enforcing a maximum signature age from the time of the created time stamp.
• Rejection of signatures past the expiration time in the expires time stamp. 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.
• Prohibition of 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.

Application-specific requirements are expected and encouraged. When an application defines additional requirements, it MUST enforce them during the signature verification process, and signature verification MUST fail if the signature does not conform to the application's requirements.¶

Applications MUST enforce the requirements defined in this document. Regardless of use case, applications MUST NOT accept signatures that do not conform to these requirements.¶

To sign using this algorithm, the signer applies the RSASSA-PSS-SIGN (K, M) function defined in [RFC8017] with the signer's private signing key (K) and the signature base (M) (Section 2.5). The mask generation function is MGF1 as specified in [RFC8017] with a hash function of SHA-512 [RFC6234]. The salt length (sLen) is 64 bytes. The hash function (Hash) SHA-512 [RFC6234] is applied to the signature base to create the digest content to which the digital signature is applied. The resulting signed content byte array (S) is the HTTP message signature output used in Section 3.1.¶

To verify using this algorithm, the verifier applies the RSASSA-PSS-VERIFY ((n, e), M, S) function [RFC8017] using the public key portion of the verification key material ((n, e)) and the signature base (M) re-created as described in Section 3.2. The mask generation function is MGF1 as specified in [RFC8017] with a hash function of SHA-512 [RFC6234]. The salt length (sLen) is 64 bytes. The hash function (Hash) SHA-512 [RFC6234] is applied to the signature base to create the digest content to which the verification function is applied. The verifier extracts the HTTP message signature to be verified (S) as described in Section 3.2. The results of the verification function indicate if the signature presented is valid.¶

Note that the output of RSA PSS algorithms are non-deterministic, and therefore it is not correct to re-calculate a new signature on the signature base and compare the results to an existing signature. Instead, the verification algorithm defined here needs to be used. See Section 7.3.5.¶

Use of this algorithm can be indicated at runtime using the rsa-pss-sha512 value for the alg signature parameter.¶

To sign using this algorithm, the signer applies the RSASSA-PKCS1-V1_5-SIGN (K, M) function defined in [RFC8017] with the signer's private signing key (K) and the signature base (M) (Section 2.5). The hash SHA-256 [RFC6234] is applied to the signature base to create the digest content to which the digital signature is applied. The resulting signed content byte array (S) is the HTTP message signature output used in Section 3.1.¶

To verify using this algorithm, the verifier applies the RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, S) function [RFC8017] using the public key portion of the verification key material ((n, e)) and the signature base (M) re-created as described in Section 3.2. The hash function SHA-256 [RFC6234] is applied to the signature base to create the digest content to which the verification function is applied. The verifier extracts the HTTP message signature to be verified (S) as described in Section 3.2. The results of the verification function indicate if the signature presented is valid.¶

Use of this algorithm can be indicated at runtime using the rsa-v1_5-sha256 value for the alg signature parameter.¶

To sign and verify using this algorithm, the signer applies the HMAC function [RFC2104] with the shared signing key (K) and the signature base (text) (Section 2.5). The hash function SHA-256 [RFC6234] is applied to the signature base to create the digest content to which the HMAC is applied, giving the signature result.¶

For signing, the resulting value is the HTTP message signature output used in Section 3.1.¶

For verification, the verifier extracts the HTTP message signature to be verified (S) as described in Section 3.2. The output of the HMAC function is compared bytewise to the value of the HTTP message signature, and the results of the comparison determine the validity of the signature presented.¶

Use of this algorithm can be indicated at runtime using the hmac-sha256 value for the alg signature parameter.¶

To sign using this algorithm, the signer applies the ECDSA algorithm defined in [FIPS186-4] using curve P-256 with the signer's private signing key and the signature base (Section 2.5). The hash SHA-256 [RFC6234] is applied to the signature base to create the digest content to which the digital signature is applied, (M). The signature algorithm returns two integer values, r and s. These are both encoded as big-endian unsigned integers, zero-padded to 32-octets each. These encoded values are concatenated into a single 64-octet array consisting of the encoded value of r followed by the encoded value of s. The resulting concatenation of (r, s) is byte array of the HTTP message signature output used in Section 3.1.¶

To verify using this algorithm, the verifier applies the ECDSA algorithm defined in [FIPS186-4] using the public key portion of the verification key material and the signature base re-created as described in Section 3.2. The hash function SHA-256 [RFC6234] is applied to the signature base to create the digest content to which the signature verification function is applied, (M). The verifier extracts the HTTP message signature to be verified (S) as described in Section 3.2. This value is a 64-octet array consisting of the encoded values of r and s concatenated in order. These are both encoded in big-endian unsigned integers, zero-padded to 32-octets each. The resulting signature value (r, s) is used as input to the signature verification function. The results of the verification function indicate if the signature presented is valid.¶

Note that the output of ECDSA algorithms are non-deterministic, and therefore it is not correct to re-calculate a new signature on the signature base and compare the results to an existing signature. Instead, the verification algorithm defined here needs to be used. See Section 7.3.5.¶

Use of this algorithm can be indicated at runtime using the ecdsa-p256-sha256 value for the alg signature parameter.¶

To sign using this algorithm, the signer applies the ECDSA algorithm defined in [FIPS186-4] using curve P-384 with the signer's private signing key and the signature base (Section 2.5). The hash SHA-384 [RFC6234] is applied to the signature base to create the digest content to which the digital signature is applied, (M). The signature algorithm returns two integer values, r and s. These are both encoded as big-endian unsigned integers, zero-padded to 48-octets each. These encoded values are concatenated into a single 96-octet array consisting of the encoded value of r followed by the encoded value of s. The resulting concatenation of (r, s) is byte array of the HTTP message signature output used in Section 3.1.¶

To verify using this algorithm, the verifier applies the ECDSA algorithm defined in [FIPS186-4] using the public key portion of the verification key material and the signature base re-created as described in Section 3.2. The hash function SHA-384 [RFC6234] is applied to the signature base to create the digest content to which the signature verification function is applied, (M). The verifier extracts the HTTP message signature to be verified (S) as described in Section 3.2. This value is a 96-octet array consisting of the encoded values of r and s concatenated in order. These are both encoded in big-endian unsigned integers, zero-padded to 48-octets each. The resulting signature value (r, s) is used as input to the signature verification function. The results of the verification function indicate if the signature presented is valid.¶

Note that the output of ECDSA algorithms are non-deterministic, and therefore it is not correct to re-calculate a new signature on the signature base and compare the results to an existing signature. Instead, the verification algorithm defined here needs to be used. See Section 7.3.5.¶

Use of this algorithm can be indicated at runtime using the ecdsa-p384-sha384 value for the alg signature parameter.¶

To sign using this algorithm, the signer applies the Ed25519 algorithm defined in Section 5.1.6 of [RFC8032] with the signer's private signing key and the signature base (Section 2.5). The signature base is taken as the input message (M) with no pre-hash function. The signature is a 64-octet concatenation of R and S as specified in Section 5.1.6 of [RFC8032], and this is taken as a byte array for the HTTP message signature output used in Section 3.1.¶

To verify using this algorithm, the signer applies the Ed25519 algorithm defined in Section 5.1.7 of [RFC8032] using the public key portion of the verification key material (A) and the signature base re-created as described in Section 3.2. The signature base is taken as the input message (M) with no pre-hash function. The signature to be verified is processed as the 64-octet concatenation of R and S as specified in Section 5.1.7 of [RFC8032]. The results of the verification function indicate if the signature presented is valid.¶

Use of this algorithm can be indicated at runtime using the ed25519 value for the alg signature parameter.¶

If the signing algorithm is a JOSE signing algorithm from the JSON Web Signature and Encryption Algorithms Registry established by [RFC7518], the JWS algorithm definition determines the signature and hashing algorithms to apply for both signing and verification.¶

For both signing and verification, the HTTP messages signature base (Section 2.5) is used as the entire "JWS Signing Input". The JOSE Header defined in [RFC7517] is not used, and the signature base is not first encoded in Base64 before applying the algorithm. The output of the JWS signature is taken as a byte array prior to the Base64url encoding used in JOSE.¶

The JWS algorithm MUST NOT be none and MUST NOT be any algorithm with a JOSE Implementation Requirement of Prohibited.¶

JWA algorithm values from the JSON Web Signature and Encryption Algorithms Registry are not included as signature parameters. Typically, the JWS algorithm can be signaled using JSON Web Keys or other mechanisms common to JOSE implementations. In fact, JWA algorithm values are not registered in the HTTP Signature Algorithms registry (Section 6.2), and so the explicit alg signature parameter is not used at all when using JOSE signing algorithms.¶

Algorithm Name:

An identifier for the HTTP Signature Algorithm. The name MUST be an ASCII string consisting only of lower-case characters ("a" - "z"), digits ("0" - "9"), and hyphens ("-"), 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:

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 signature algorithm is no longer recommended for use and might be insecure or unsafe in practice.

Specification document(s):

Reference to the document(s) 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.

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.

Specification document(s):

Reference to the document(s) 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.

The table below contains the initial contents of the HTTP Signature Metadata Parameters Registry. Each row in the table represents a distinct entry in the registry.¶

Name:

A name for the HTTP derived component. The name MUST begin with the "@" character followed by an ASCII string consisting only of lower-case 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 are defined in Section 2.2.

Specification document(s):

Reference to the document(s) 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.

The table below contains the initial contents of the HTTP Signature Derived Component Names Registry.¶

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.

Specification document(s):

Reference to the document(s) 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.

The table below contains the initial contents of the HTTP Signature Derived Component Names Registry.¶

HTTP Message Signatures only provide security if the signature is verified by the verifier. Since the message to which the signature is attached remains a valid HTTP message without the signature fields, it is possible for a verifier to ignore the output of the verification function and still process the message. Common reasons for this could be relaxed requirements in a development environment or a temporary suspension of enforcing verification during debugging an overall system. Such temporary suspensions are difficult to detect under positive-example testing since a good signature will always trigger a valid response whether or not it has been checked.¶

To detect this, verifiers should be tested using both valid and invalid signatures, ensuring that the invalid signature fails as expected.¶

The use of HTTP Message Signatures does not negate the need for TLS or its equivalent to protect information in transit. Message signatures provide message integrity over the covered message components but do not provide any confidentiality for the communication between parties.¶

TLS provides such confidentiality between the TLS endpoints. As part of this, TLS also protects the signature data itself from being captured by an attacker, which is an important step in preventing signature replay (Section 7.2.2).¶

When TLS is used, it needs to be deployed according to the recommendations in [BCP195].¶

Any portions of the message not covered by the signature are susceptible to modification by an attacker without affecting the signature. An attacker can take advantage of this by introducing or modifying a header field or other message component that will change the processing of the message but will not be covered by the signature. Such an altered message would still pass signature verification, but when the verifier processes the message as a whole, the unsigned content injected by the attacker would subvert the trust conveyed by the valid signature and change the outcome of processing the message.¶

To combat this, an application of this specification should require as much of the message as possible to be signed, within the limits of the application and deployment. The verifier should only trust message components that have been signed. Verifiers could also strip out any sensitive unsigned portions of the message before processing of the message continues.¶

Since HTTP Message Signatures allows sub-portions of the HTTP message to be signed, it is possible for two different HTTP messages to validate against the same signature. The most extreme form of this would be a signature over no message components. If such a signature were intercepted, it could be replayed at will by an attacker, attached to any HTTP message. Even with sufficient component coverage, a given signature could be applied to two similar HTTP messages, allowing a message to be replayed by an attacker with the signature intact.¶

To counteract these kinds of attacks, it's first important for the signer to cover sufficient portions of the message to differentiate it from other messages. In addition, the signature can use the nonce signature parameter to provide a per-message unique value to allow the verifier to detect replay of the signature itself if a nonce value is repeated. Furthermore, the signer can provide a timestamp for when the signature was created and a time at which the signer considers the signature to be expired, limiting the utility of a captured signature value.¶

If a verifier wants to trigger a new signature from a signer, it can send the Accept-Signature header field with a new nonce parameter. An attacker that is simply replaying a signature would not be able to generate a new signature with the chosen nonce value.¶

Applications of HTTP Message Signatures need to decide which message components will be covered by the signature. Depending on the application, some components could be expected to be changed by intermediaries prior to the signature's verification. If these components are covered, such changes would, by design, break the signature.¶

However, the HTTP Message Signature standard allows for flexibility in determining which components are signed precisely so that a given application can choose the appropriate portions of the message that need to be signed, avoiding problematic components. For example, a web application framework that relies on rewriting query parameters might avoid use of the @query derived component in favor of sub-indexing the query value using @query-param derived components instead.¶

Some components are expected to be changed by intermediaries and ought not to be signed under most circumstance. The Via and Forwarded header fields, for example, are expected to be manipulated by proxies and other middle-boxes, including replacing or entirely dropping existing values. These fields should not be covered by the signature except in very limited and tightly-coupled scenarios.¶

Additional considerations for choosing signature aspects are discussed in Section 1.4.¶

"date"

The "date" 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 Section 7.2.2 and Section 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.

HTTP Message Signature values are identified in the Signature and Signature-Input field values by unique labels. These labels are chosen only when attaching the signature values to the message and are not accounted for in the signing process. An intermediary is allowed to re-label an existing signature when processing the message.¶

Therefore, applications should not rely on specific labels being present, and applications should not put semantic meaning on the labels themselves. Instead, additional signature parameters can be used to convey whatever additional meaning is required to be attached to and covered by the signature. In particular, the tag parameter can be used to define an application-specific value as described in Section 7.2.7.¶

Since multiple signatures can be applied to one message (Section 4.3), it is possible for an attacker to attach their own signature to a captured message without modifying existing signatures. This new signature could be completely valid based on the attacker's key, or it could be an invalid signature for any number of reasons. Each of these situations need to be accounted for.¶

A verifier processing a set of valid signatures needs to account for all of the signers, identified by the signing keys. Only signatures from expected signers should be accepted, regardless of the cryptographic validity of the signature itself.¶

A verifier processing a set of signatures on a message also needs to determine what to do when one or more of the signatures are not valid. If a message is accepted when at least one signature is valid, then a verifier could drop all invalid signatures from the request before processing the message further. Alternatively, if the verifier rejects a message for a single invalid signature, an attacker could use this to deny service to otherwise valid messages by injecting invalid signatures alongside the valid ones.¶

Multiple applications and protocols could apply HTTP signatures on the same message simultaneously. In fact, this is a desired feature in many circumstances as described in Section 4.3. A naive verifier could become confused in processing multiple signatures, either accepting or rejecting a message based on an unrelated or irrelevant signature. In order to help an application select which signatures apply to its own processing, the application can declare a specific value for the tag signature parameter as defined in Section 2.3. For example, a signature targeting an application gateway could require tag="app-gateway" as part of the signature parameters for that application.¶

The use of the tag parameter does not prevent an attacker from also using the same value as a target application, since the parameter's value is public and otherwise unrestricted. As a consequence, a verifier should only use value of the tag parameter to limit which signatures to check. Each signature still needs to be examined by the verifier to ensure that sufficient coverage is provided, as discussed in Section 7.2.1.¶

On its own, this specification does not provide coverage for the content of an HTTP message under the signature, either in request or response. However, [DIGEST] defines a set of fields that allow a cryptographic digest of the content to be represented in a field. Once this field is created, it can be included just like any other field as defined in Section 2.1.¶

From here, the signing process proceeds as usual.¶

Upon verification, it is important that the verifier validate not only the signature but also the value of the Content-Digest field itself against the actual received content. Unless the verifier performs this step, it would be possible for an attacker to substitute the message content but leave the Content-Digest field value untouched to pass the signature. Since only the field value is covered by the signature directly, checking only the signature is not sufficient protection against such a substitution attack.¶

As discussed in [DIGEST], the value of the Content-Digest field is dependent on the content encoding of the message. If an intermediary changes the content encoding, the resulting Content-Digest value would change, which would in turn invalidate the signature. Any intermediary performing such an action would need to apply a new signature with the updated Content-Digest field value, similar to the reverse proxy use case discussed in Section 4.3.¶

The HTTP Message Signatures specification does not define any of its own cryptographic primitives, and instead relies on other specifications to define such elements. If the signature algorithm or key used to process the signature base is vulnerable to any attacks, the resulting signature will also be susceptible to these same attacks.¶

A common attack against signature systems is to force a signature collision, where the same signature value successfully verifies against multiple different inputs. Since this specification relies on reconstruction of the signature base from an HTTP message, and the list of components signed is fixed in the signature, it is difficult but not impossible for an attacker to effect such a collision. An attacker would need to manipulate the HTTP message and its covered message components in order to make the collision effective.¶

To counter this, only vetted keys and signature algorithms should be used to sign HTTP messages. The HTTP Message Signatures Algorithm Registry is one source of trusted signature algorithms for applications to apply to their messages.¶

While it is possible for an attacker to substitute the signature parameters value or the signature value separately, the signature base generation algorithm (Section 2.5) always covers the signature parameters as the final value in the signature base using a deterministic serialization method. This step strongly binds the signature base with the signature value in a way that makes it much more difficult for an attacker to perform a partial substitution on the signature bases.¶

A foundational assumption of signature-based cryptographic systems is that the signing key is not compromised by an attacker. If the keys used to sign the message are exfiltrated or stolen, the attacker will be able to generate their own signatures using those keys. As a consequence, signers have to protect any signing key material from exfiltration, capture, and use by an attacker.¶

To combat this, signers can rotate keys over time to limit the amount of time stolen keys are useful. Signers can also use key escrow and storage systems to limit the attack surface against keys. Furthermore, the use of asymmetric signing algorithms exposes key material less than the use of symmetric signing algorithms (Section 7.3.3).¶

The HTTP Message Signatures specification allows for both asymmetric and symmetric cryptography to be applied to HTTP messages. By its nature, symmetric cryptographic methods require the same key material to be known by both the signer and verifier. This effectively means that a verifier is capable of generating a valid signature, since they have access to the same key material. An attacker that is able to compromise a verifier would be able to then impersonate a signer.¶

Where possible, asymmetric methods or secure key agreement mechanisms should be used in order to avoid this type of attack. When symmetric methods are used, distribution of the key material needs to be protected by the overall system. One technique for this is the use of separate cryptographic modules that separate the verification process (and therefore the key material) from other code, minimizing the vulnerable attack surface. Another technique is the use of key derivation functions that allow the signer and verifier to agree on unique keys for each message without having to share the key values directly.¶

Additionally, if symmetric algorithms are allowed within a system, special care must be taken to avoid key downgrade attacks (Section 7.3.6).¶

The existence of a valid signature on an HTTP message is not sufficient to prove that the message has been signed by the appropriate party. It is up to the verifier to ensure that a given key and algorithm are appropriate for the message in question. If the verifier does not perform such a step, an attacker could substitute their own signature using their own key on a message and force a verifier to accept and process it. To combat this, the verifier needs to ensure that not only does the signature validate for a message, but that the key and algorithm used are appropriate.¶

Some cryptographic primitives such as RSA PSS and ECDSA have non-deterministic outputs, which include some amount of entropy within the algorithm. For such algorithms, multiple signatures generated in succession will not match. A lazy implementation of a verifier could ignore this distinction and simply check for the same value being created by re-signing the signature base. Such an implementation would work for deterministic algorithms such as HMAC and EdDSA but fail to verify valid signatures made using non-deterministic algorithms. It is therefore important that a verifier always use the correctly-defined verification function for the algorithm in question and not do a simple comparison.¶

Applications of this specification need to protect against key specification downgrade attacks. For example, the same RSA key can be used for both RSA-PSS and RSA v1.5 signatures. If an application expects a key to only be used with RSA-PSS, it needs to reject signatures for that key using the weaker RSA 1.5 specification.¶

Another example of a downgrade attack occurs when an asymmetric algorithm is expected, such as RSA-PSS, but an attacker substitutes a signature using symmetric algorithm, such as HMAC. A naive verifier implementation could use the value of the public RSA key as the input to the HMAC verification function. Since the public key is known to the attacker, this would allow the attacker to create a valid HMAC signature against this known key. To prevent this, the verifier needs to ensure that both the key material and the algorithm are appropriate for the usage in question. Additionally, while this specification does allow runtime specification of the algorithm using the alg signature parameter, applications are encouraged to use other mechanisms such as static configuration or higher protocol-level algorithm specification instead, preventing an attacker from substituting the algorithm specified.¶

An attacker could effectively deny a service by modifying an otherwise benign signature parameter or signed message component. While rejecting a modified message is the desired behavior, consistently failing signatures could lead to the verifier turning off signature checking in order to make systems work again (see Section 7.1.1), or to the application minimizing the signed component requirements.¶

If such failures are common within an application, the signer and verifier should compare their generated signature bases with each other to determine which part of the message is being modified. If an expected modification is found, the signer and verifier can agree on an alternative set of requirements that will pass. However, the signer and verifier should not remove the requirement to sign the modified component when it is suspected an attacker is modifying the component.¶

The verifier needs to make sure that the signed message components match those in the message itself. For example, the @method derived component requires that the value within the signature base be the same as the HTTP method used when presenting this message. This specification encourages this by requiring the verifier to derive the signature base from the message, but lazy cacheing or conveyance of a raw signature base to a processing subsystem could lead to downstream verifiers accepting a message that does not match the presented signature.¶

To counter this, the component that generates the signature base needs to be trusted by both the signer and verifier within a system.¶

The signature context for deriving message component values includes the target HTTP Message itself, any associated messages (such as the request that triggered a response), and additional information that the signer or verifier has access to. Both signers and verifiers need to carefully consider the source of all information when creating component values for the signature base and take care not to take information from untrusted sources. Otherwise, an attacker could leverage such a loosely-defined message context to inject their own values into the signature base string, overriding or corrupting the intended values.¶

For example, in most situations, the target URI of the message is defined in [HTTP], Section 7.1. However, let's say that there is an application that requires signing of the @authority of the incoming request, but the application doing the processing is behind a reverse proxy. Such an application would expect a change in the @authority value, and it could be configured to know the external target URI as seen by the client on the other side of the proxy. This application would use this configured value as its target URI for the purposes of deriving message component values such as @authority instead of using the target URI of the incoming message.¶

This approach is not without problems, as a misconfigured system could accept signed requests intended for different components in the system. For this scenario, an intermediary could instead add its own signature to be verified by the application directly, as demonstrated in Section 4.3. This alternative approach requires a more active intermediary but relies less on the target application knowing external configuration values.¶

For another example, Section 2.4 defines a method for signing response messages but including portions of the request message that triggered the response. In this case, the context for component value calculation is the combination of the response and request message, not just the single message to which the signature is applied. For this feature, the req flag allows both signer to explicitly signal which part of the context is being sourced for a component identifier's value. Implementations need to ensure that only the intended message is being referred to for each component, otherwise an attacker could attempt to subvert a signature by manipulating one side or the other.¶

It is possible that the context for deriving message component values could be distinct for each signature present within a single message. This is particularly the case when proxies mutate messages and include signatures over the mutated values, in addition to any existing signatures. For example, a reverse proxy can replace a public hostname in a request to a service with the hostname for the individual service host that it is forwarding the request on to. If both the client and the reverse proxy add signatures covering @authority, the service host will see two signatures on the request, each signing different values for the @authority message component, reflecting the change to that component as the message made its way from the client to the service host.¶

In such a case, it's common for the internal service to verify only one of the signatures or to use externally-configured information, as discussed in Section 7.4.3. However, a verifier processing both signatures has to use a different message component context for each signature, since the component value for the @authority component will be different for each signature. Verifiers like this need to be aware of both the reverse proxy's context for incoming messages as well as the target service's context for the message coming from the reverse proxy. The verifier needs to take particular care to apply the correct context to the correct signature, otherwise an attacker could use knowledge of this complex setup to confuse the inputs to the verifier.¶

Such verifiers also need to ensure that any differences in message component contexts between signatures are expected and permitted. For example, in the above scenario, the reverse proxy could include the original hostname in a Forwarded header field, and sign @authority, forwarded, and the client's entry in the signature field. The verifier can use the hostname from the Forwarded header field to confirm that the hostname was transformed as expected.¶

The definition of HTTP field names does not allow for the use of the @ character anywhere in the name. As such, since all derived component names start with the @ character, these namespaces should be completely separate. However, some HTTP implementations are not sufficiently strict about the characters accepted in HTTP field names. In such implementations, a sender (or attacker) could inject a header field starting with an @ character and have it passed through to the application code. These invalid header fields could be used to override a portion of the derived message content and substitute an arbitrary value, providing a potential place for an attacker to mount a signature collision (Section 7.3.1) attack or other functional substitution attack (such as using the signature from a GET request on a crafted POST request).¶

To combat this, when selecting values for a message component, if the component name starts with the @ character, it needs to be processed as a derived component and never taken as a fields. Only if the component name does not start with the @ character can it be taken from the fields of the message. The algorithm discussed in Section 2.5 provides a safe order of operations.¶

The signature base generation algorithm (Section 2.5) uses the value of an HTTP field as its component value. In the common case, this amounts to taking the actual bytes of the field value as the component value for both the signer and verifier. However, some field values allow for transformation of the values in semantically equivalent ways that alter the bytes used in the value itself. For example, a field definition can declare some or all of its value to be case-insensitive, or to have special handling of internal whitespace characters. Other fields have expected transformations from intermediaries, such as the removal of comments in the Via header field. In such cases, a verifier could be tripped up by using the equivalent transformed field value, which would differ from the byte value used by the signer. The verifier would have a difficult time finding this class of errors since the value of the field is still acceptable for the application, but the actual bytes required by the signature base would not match.¶

When processing such fields, the signer and verifier have to agree how to handle such transformations, if at all. One option is to not sign problematic fields, but care must be taken to ensure that there is still sufficient signature coverage (Section 7.2.1) for the application. Another option is to define an application-specific canonicalization value for the field before it is added to the HTTP message, such as to always remove internal comments before signing, or to always transform values to lowercase. Since these transformations are applied prior to the field being used as input to the signature base generation algorithm, the signature base will still simply contain the byte value of the field as it appears within the message. If the transformations were to be applied after the value is extracted from the message but before it is added to the signature base, different attack surfaces such as value substitution attacks could be launched against the application. All application-specific additional rules are outside the scope of this specification, and by their very nature these transformations would harm interoperability of the implementation outside of this specific application. It is recommended that applications avoid the use of such additional rules wherever possible.¶

Several parts of this specification rely on the parsing of structured field values [STRUCTURED-FIELDS]. In particular, normalization of HTTP structured field values (Section 2.1.1), referencing members of a dictionary structured field (Section 2.1.2), and processing the @signature-input value when verifying a signature (Section 3.2). While structured field values are designed to be relatively simple to parse, a naive or broken implementation of such a parser could lead to subtle attack surfaces being exposed in the implementation.¶

For example, if a buggy parser of the @signature-input value does not enforce proper closing of quotes around string values within the list of component identifiers, an attacker could take advantage of this and inject additional content into the signature base through manipulating the Signature-Input field value on a message.¶

To counteract this, implementations should use fully compliant and trusted parsers for all structured field processing, both on the signer and verifier side.¶

Some message components are expressed in different ways across HTTP versions. For example, the authority of the request target is sent using the Host header field in HTTP/1.1 but with the :authority pseudo-header in HTTP/2. If a signer sends an HTTP/1.1 message and signs the Host field, but the message is translated to HTTP/2 before it reaches the verifier, the signature will not validate as the Host header field could be dropped.¶

It is for this reason that HTTP Message Signatures defines a set of derived components that define a single way to get value in question, such as the @authority derived component (Section 2.2.3) in lieu of the Host header field. Applications should therefore prefer derived components for such options where possible.¶

Any ambiguity in the generation of the signature base could provide an attacker with leverage to substitute or break a signature on a message. Some message component values, particularly HTTP field values, are potentially susceptible to broken implementations that could lead to unexpected and insecure behavior. Naive implementations of this specification might implement HTTP field processing by taking the single value of a field and using it as the direct component value without processing it appropriately.¶

For example, if the handling of obs-fold field values does not remove the internal line folding and whitespace, additional newlines could be introduced into the signature base by the signer, providing a potential place for an attacker to mount a signature collision (Section 7.3.1) attack. Alternatively, if header fields that appear multiple times are not joined into a single string value, as is required by this specification, similar attacks can be mounted as a signed component value would show up in the signature base more than once and could be substituted or otherwise attacked in this way.¶

To counter this, the entire field value processing algorithm needs to be implemented by all implementations of signers and verifiers.¶

When an HTTP field occurs multiple times in a single message, these values need to be combined into a single one-line string value to be included in the HTTP signature base, as described in Section 2.5. Not all HTTP fields can be combined into a single value in this way and still be a valid value for the field. For the purposes of generating the signature base, the message component value is never meant to be read back out of the signature base string or used in the application. Therefore it is considered best practice to treat the signature base generation algorithm separately from processing the field values by the application, particularly for fields that are known to have this property. If the field values that are being signed do not validate, the signed message should also be rejected.¶

Since two semantically distinct inputs can create the same output in the signature base, special care has to be taken when handling such values.¶

Specifically, the Set-Cookie field [COOKIE] defines an internal syntax that does not conform to the List syntax in [STRUCTURED-FIELDS]. In particular some portions allow unquoted commas, and the field is typically sent as multiple separate field lines with distinct values when sending multiple cookies. When multiple Set-Cookie fields are sent in the same message, it is not generally possible to combine these into a single line and be able to parse and use the results, as discussed in [HTTP], Section 5.3. Therefore, all the cookies need to be processed from their separate header values, without being combined, while the signature base needs to be processed from the special combined value generated solely for this purpose. If the cookie value is invalid, the signed message ought to be rejected as this is a possible padding attack as described in Section 7.5.7.¶

To deal with this, an application can choose to limit signing of problematic fields like Set-Cookie, such as including the field in a signature only when a single field value is present and the results would be unambiguous. Similar caution needs to be taken with all fields that could have non-deterministic mappings into the signature base. Signers can also make use of the bs parameter to armor such fields, as described in Section 2.1.3.¶

Since HTTP field values need to be combined in a single string value to be included in the HTTP signature base, as described in Section 2.5, it is possible for an attacker to inject an additional value for a given field and add this to the signature base of the verifier.¶

In most circumstances, this causes the signature validation to fail as expected, since the new signature base value will not match the one used by the signer to create the signature. However, it is theoretically possible for the attacker to inject both a garbage value to a field and a desired value to another field in order to force a particular input. This is a variation of the collision attack described in Section 7.3.1, where the attacker accomplishes their change in the message by adding to existing field values.¶

To counter this, an application needs to validate the content of the fields covered in the signature in addition to ensuring that the signature itself validates. With such protections, the attacker's padding attack would be rejected by the field value processor, even in the case where the attacker could force a signature collision.¶

The following key is a 2048-bit RSA public and private key pair, referred to in this document as test-key-rsa. This key is encoded in PEM Format, with no encryption.¶

The following key is a 2048-bit RSA public and private key pair, referred to in this document as test-key-rsa-pss. This key is PCKS#8 encoded in PEM format, with no encryption.¶

The following key is a public and private elliptical curve key pair over the curve P-256, referred to in this document as `test-key-ecc-p256. This key is encoded in PEM format, with no encryption.¶

The following key is an elliptical curve key over the Edwards curve ed25519, referred to in this document as test-key-ed25519. This key is PCKS#8 encoded in PEM format, with no encryption.¶

The following shared secret is 64 randomly-generated bytes encoded in Base64, referred to in this document as test-shared-secret.¶

This example presents a minimal signature using the rsa-pss-sha512 algorithm over test-request, covering none of the components of the HTTP message, but providing a timestamped signature proof of possession of the key with a signer-provided nonce.¶

Note that since the covered components list is empty, this signature could be applied by an attacker to an unrelated HTTP message. In this example, the nonce parameter is included to prevent the same signature from being replayed more than once, but if an attacker intercepts the signature and prevents its delivery to the verifier, the attacker could apply this signature to another message. Therefore, use of an empty covered components set is discouraged. See Section 7.2.1 for more discussion.¶

Note that the RSA PSS algorithm in use here is non-deterministic, meaning a different signature value will be created every time the algorithm is run. The signature value provided here can be validated against the given keys, but newly-generated signature values are not expected to match the example. See Section 7.3.5.¶

This example covers additional components (the authority, the Content-Digest header field, and a single named query parameter) in test-request using the rsa-pss-sha512 algorithm. This example also adds a tag parameter with the application-specific value of header-example.¶

Note that the RSA PSS algorithm in use here is non-deterministic, meaning a different signature value will be created every time the algorithm is run. The signature value provided here can be validated against the given keys, but newly-generated signature values are not expected to match the example. See Section 7.3.5.¶

This example covers all applicable message components in test-request (including the content type and length) plus many derived components, again using the rsa-pss-sha512 algorithm. Note that the Host header field is not covered because the @authority derived component is included instead.¶

Note in this example that the value of the Date header and the value of the created signature parameter need not be the same. This is due to the fact that the Date header is added when creating the HTTP Message and the created parameter is populated when creating the signature over that message, and these two times could vary. If the Date header is covered by the signature, it is up to the verifier to determine whether its value has to match that of the created parameter or not. See Section 7.2.4 for more discussion.¶

Note that the RSA PSS algorithm in use here is non-deterministic, meaning a different signature value will be created every time the algorithm is run. The signature value provided here can be validated against the given keys, but newly-generated signature values are not expected to match the example. See Section 7.3.5.¶

This example covers portions of the test-response response message using the ecdsa-p256-sha256 algorithm and the key test-key-ecc-p256.¶

Note that the ECDSA algorithm in use here is non-deterministic, meaning a different signature value will be created every time the algorithm is run. The signature value provided here can be validated against the given keys, but newly-generated signature values are not expected to match the example. See Section 7.3.5.¶

This example covers portions of the test-request using the hmac-sha256 algorithm and the secret test-shared-secret.¶

Before using symmetric signatures in practice, see the discussion of the security tradeoffs in Section 7.3.3.¶

This example covers portions of the test-request using the ed25519 algorithm and the key test-key-ed25519.¶