This spec documents an HMAC message format for securing RESTful web APIs.
HMAC authentication is a shared-secret cryptography method where signatures are generated on the client side and validated by the server in order to authenticate the request. It is used by popular web services such as AWS and in protocols such as OAuth 1.0a to sign and authenticate API requests.
The pseudocode below illustrates construction of the HTTP "Authorization" header and signature:
Authorization = "Provider" + " " + ID + ":" + Signature;
Signature = Base64( Algorithm( SecretKey, Message ) );
Message =
HTTP-Verb + "\n" +
MD5( Request-Body ) + "\n" +
Content-Type + "\n" +
Date + "\n" +
Custom-Headers + "\n"
Resource
;
"\n"
denotes a Unix-style line feed (ASCII code 0x0A
).
The value of the Authorization
header contains the following parts:
Provider
: The provider, for example "Acquia", "MyCompany", etc.ID
: The API key's unique identifier, which is an arbitrary stringSignature
: The base64 encoded HMAC digest as described below
The signature is a base64 encoded binary HMAC digest generated from the following parts:
Algorithm
: The cryptographic algorithm, e.g. "sha1", "sha256", etc.SecretKey
: The API key's shared secretMessage
: The string being signed as described below
The message is a concatenated string generated from the following parts:
HTTP-Verb
: The uppercase HTTP request method e.g. "GET", "POST"Request-Body
: The raw body of the HTTP request- Note that in the message, the body is hashed using the MD5 algorithm
Content-Type
: The lowercase value of the "Content-type" headerDate
: The value of the "Date" header- The implementation may also read the timestamp from a custom header, e.g.
x-acquia-timestamp
- The implementation may also read the timestamp from a custom header, e.g.
Custom-Headers
: A canonicalized concatenation of optional custom headers- Each header is in
x-custom-header: value
format - Header names are lowercase
- Multiple values are separated by a comma and space, e.g.
value1, value2
- Each header is separated by a newline in the concatenated string
- Each header is in
Resource
: The HTTP request path + query string, e.g./resource?key=value
Refer to the wiki for frequently asked questions and a list of implementations in various languages.
The algorithm is modeled after Amazon Web Service's implementation and in part is derived from the HMAC authentication system developed for Acquia Search.