The HTTP Signature¶
This section is based on the definitions and descriptions in Signing HTTP Messages IETF draft RFC version 10.
The Signature line is the component of a signature header that describes the parameters of how a message was signed as well as the actual digital signature.
These parameters together should provide any verifier with the information required to prove the validity of a signature against the HTTP message it accompanies.
The parameters of the Signature Line are described here
As desribed in the draft RFC,
keyId parameter is used by the verifier to look up the key that can
be used to verify the provided signature.
- In the HMAC case these are the same key - the shared secret.
- In the RSA or EC case, this is the public component of the key.
Note that the RFC is not specific about the meaning of the parameter’s value. This could be a fingerprint of the certificate containing the key, the e-mail address of the signer, or even no value at all if the verifier can determine which key to use by another means entirely e.g. if the key/certificate is provided in a dedicated header.
The value of
keyId must therefore be agreed before the message is
transmitted - either by agreeing an explicit value, or the format of the
value acceptable to the verifier if it not distinct.
This is typically found in the API documentation for the resource.
algorithm parameter informs the verifier which hash algorithm was used
to generate the hash signed by the signature (“hash” algorithm),
and which cryptographic algorithm was used to sign that resulting hash
The hash algorithm cannot be deduced simply by looking at the key and signature, so must be provided in this parameter.
However the verifier should not rely on the signature algorithm part
algorithm parameter alone to determine which signature algorithm to use.
Rather the “metadata” (e.g. which elliptic curve algorithm the key
is designed for) associated with the key should be relied on separate
from the signed message.
This arises as some types of keys can be used in multiple modes, and selecting the wrong mode for verification may introduce security issues.
In any case the signer and verifier should agree which hash and signature algorithms are acceptable for a given request/response.
headers parameter is a space-delimited list of the headers that are
included in the signature itself. These headers are specified in lowercase,
and let the verifier know which order to place the headers in when the
signature is verified - so this order cannot be altered.
The signer and verifier(s) need to agree on which headers should be included in any signature, especially if there are minimum headers that must be included and any that are forbidden.
If this parameter is missing from a provided signature line, then the default
date” is used to verify the signature.
signature parameter is simply a base64-encoded string representing
the raw digital signature (which is likely encoded with unprintable characters).
The verifier can use this string, along with the other parameters and headers in the HTTP message, to verify the contents of the message (specifically the message’s headers) have not been altered since the signer generated the signature.
Signature header is a new HTTP header proposed in
The value of the header is simply the Signature Line.
This header is more versatile than the
Authorization header as it can
- by both the client and server (HTTP request and HTTP respnse respectively)
- to prove the identity of the signer (similar to the
- in addition to an
Authorizationheader when needed
Digest header is a base64-encoded representation of the hash of
the message payload (aka body). It is defined in RFC 3230. Note that this
library has only rudimentary support for this specification e.g. can only
include a single digest value while the RFC requires support for multiple
Digest header in the
signature allows the integrity of the payload to be
included in the signature itself.
When the message has no payload - e.g. a GET request, or a reponse with code
202 - the digest is calculated on the empty string