Skip to main content

1.4. Application of HTTP Message Signatures

1.4. Application of HTTP Message Signatures​

HTTP message signatures are designed to be a general-purpose tool applicable in a wide variety of circumstances and applications. In order to properly and safely apply HTTP message signatures, an application or profile of this specification MUST specify, at a minimum, all of the following items:

  • The set of component identifiers (Section 2) and signature parameters (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 [RFC7807] [RFC9457], such as an indicator that the wrong key material was used.

When choosing these parameters, an application of HTTP message signatures has to ensure that the verifier will have access to all required information needed to recreate the signature base. For example, a server behind a reverse proxy would need to know the original request URI to make use of the derived component @target- uri, even though the apparent target URI would be changed by the reverse proxy (see also Section 7.4.3). Additionally, an application using signatures in responses would need to ensure that clients receiving signed responses have access to all the signed portions of the message, including any portions of the request that were signed by the server using the req ("request-response") parameter (Section 2.4).

Details regarding this kind of profiling are within the purview of the application and outside the scope of this specification; however, some additional considerations are discussed in Section 7. In particular, when choosing the required set of component identifiers, care has to be taken to make sure that the coverage is sufficient for the application, as discussed in Sections 7.2.1 and 7.2.8. This specification defines only part of a full security system for an application. When building a complete security system based on this tool, it is important to perform a security analysis of the entire system, of which HTTP message signatures is a part. Historical systems, such as AWS Signature Version 4 [AWS-SIGv4], can provide inspiration and examples of how to apply similar mechanisms to an application, though review of such historical systems does not negate the need for a security analysis of an application of HTTP message signatures.

Last updated on