Hawk was originally proposed as the OAuth MAC Token specification. However, the OAuth working group in its consistent incompetence failed to produce a final, usable solution to address one of the most popular use cases of OAuth 1.0 - using it to authenticate simple client-server transactions (i.e. two-legged). As you can guess, the OAuth working group is still hard at work to produce more garbage.

Client supplies the nonce for the entire session.

Server verifies the timestamp. If the client gives a bad one, the error includes the server's current time for the client to use.

Hawk tokens

hawk.1.header

Each line ends with an ASCII newline.

The whole token is then hashed and HMAC'd with the secret key for this login. That MAC is then base64 encoded.

To use a Hawk token, include it in the Authorization header:

Authorization: Hawk id="dh37fgj492je", ts="1353832234", nonce="j4h3g2", ext="some-app-ext-data", mac="6R4rV5iE+NPoym+WwjeHzjAGXUtLNIxmo1vpMofpLAE="

Payload verification

The payload is wrapped in a container like so:

hawk.1.payload
text/plain
Thank you for flying Hawk

And hashed, HMAC'd and base64 encoded. The hash is placed in the section of the token and included in the authorization line.

Authorization: Hawk id="dh37fgj492je", ts="1353832234", nonce="j4h3g2", hash="Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=", ext="some-app-ext-data", mac="aSe1DERmZuRl3pI36/9BdZmnErTw3sNzOOAUlfeKjVw="

Server verification

Servers are allowed to seal their own responses with a payload key. This tells the client that a response comes from the server they think it should come from.

Consigning a capability

A "bewit" is a blob created with a key id, key, and algorithm, which is then assembled and handed to a third party.

The third party does not have the shared key. The bewit is created by a client who does and given to that third party. They can then use the bewit as proof access to a resource was granted.

Bewits expire; their validity timestamp is part of them.