This is a short introduction to Hawk.

What is Hawk

Hawk is a lightweight HTTP authentication method.
“Lightweight” here is in comparison to authentication methods like OAuth / Digest.
Hawk primarily defends against man-in-the-middle attacks.
It’s based on a secret key shared by the server and client.
Built upon a timestamp, it encrypts the request
and generates matching signatures on both sides.

The benefit of Hawk is that the entire authentication process doesn’t require much computing power,
and what it uses is just the simple sha256 algorithm.
Plus it can authenticate just a single request,
so the application scenarios are very flexible.

In a typical Hawk application scenario,
the client first communicates with the server through some method
to obtain the secret key.
In subsequent HTTP requests,
the client applies Hawk encryption to the request,
and puts the basic info in the HTTP Header.
After the server receives the request,
it applies the same encryption method for comparison.
If both sides match,
it’s a legal request.
Otherwise it returns 401 Unauthorized.

Encryption Algorithm

The encryption method specified by the Hawk protocol is as follows:

This is a sample HTTP GET request:

GET https://example.com:8000/resource/1?b=1&a=2

To pass Hawk verification,
we concatenate the request features with newline characters into the following format,
then encrypt with HMAC sha256:

hawk.1.header
1353832234
j4h3g2
GET
/resource/1?b=1&a=2
example.com
8000

some-app-ext-data

Where hawk.1.header means using hawk version 1 to encrypt the header,
1353832234 is the unix timestamp,
j4h3g2 is a random string generated by the client,
GET is the request type,
/resource/1?b=1&a=2 is the request query,
example.com and 8000 are host and port respectively,
and some-app-ext-data is agreed-upon additional content to verify (can be empty).
The above string is case-sensitive, space-sensitive, and newline-sensitive.

Assuming our secret key is werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn,
then after HMAC sha256 encryption, the signature of the above sample request will be 6R4rV5iE+NPoym+WwjeHzjAGXUtLNIxmo1vpMofpLAE=

Finally we add the basic info into the HTTP Header,
and the request becomes like this:

GET https://example.com:8000/resource/1?b=1&a=2
Authorization: Hawk id="dh37fgj492je", ts="1353832234", nonce="j4h3g2", ext="some-app-ext-data", mac="6R4rV5iE+NPoym+WwjeHzjAGXUtLNIxmo1vpMofpLAE="

After the server gets HttpHeader.Authorization, it performs the encryption comparison.

Other Notes

  • Hawk provides Payload Validation. The encryption method specified in the protocol is sha256, which is different from the header’s encryption method HMAC sha256.
  • If the client’s and server’s Timestamp differ, the server should return its Timestamp, and the client should compute the time difference and request again.
  • In actual usage, you can appropriately tweak the Hawk request, such as adding verification for the id.