{"id":551,"date":"2015-02-05T08:42:31","date_gmt":"2015-02-05T08:42:31","guid":{"rendered":"http:\/\/blog.mozilla.org\/services\/?p=551"},"modified":"2018-02-14T23:18:09","modified_gmt":"2018-02-14T23:18:09","slug":"whats-hawk-and-how-to-use-it","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/services\/2015\/02\/05\/whats-hawk-and-how-to-use-it\/","title":{"rendered":"What’s Hawk authentication and how to use it?"},"content":{"rendered":"

At Mozilla, we recently had to implement the Hawk authentication scheme<\/a> for a number of projects, and we came up creating two libraries to ease integration into Pyramid<\/a> and Node.js<\/a> apps.<\/p>\n

But maybe you don’t know Hawk?<\/p>\n

Hawk is a relatively new technology, crafted by one of the original OAuth<\/a> specification authors, that intends to replace the 2-legged OAuth authentication scheme using a simpler approach.<\/p>\n

It is an authentication scheme for HTTP, built around HMAC digests<\/a> of requests and responses.<\/p>\n

Every authenticated client request has an Authorization header containing a MAC (Message Authentication Code) and some additional metadata, then each server response to authenticated requests contains a Server-Authorization header thatauthenticates the response, so the client is sure it comes from the right server.<\/p>\n

Exchange of the hawk id and hawk key<\/h2>\n

To sign the requests, a client needs to retrieve a token id and a token key from the server.<\/p>\n

The excellent team behind Firefox Accounts<\/a> put together a scheme to do that, if you are not interested in the details, jump directly to the next section.<\/p>\n

When your server application needs to send you the credentials, it will return it inside a specific Hawk-Session-Token<\/cite> header. This token can be derived to split this string in two values (hawk id and hawk key) that you will use to sign your next requests.<\/p>\n

In order to get the hawk credentials, you’ll need to:<\/p>\n

First, do an HKDF derivation<\/a> on the given session token. You’ll need to use the following parameters:<\/p>\n

key_material = HKDF(hawk_session, \"\", 'identity.mozilla.com\/picl\/v1\/sessionToken', 32*2)\r\n<\/pre>\n
The identity.mozilla.com\/picl\/v1\/sessionToken<\/tt> is a reference to this way of
\nderiving the credentials, not an actual URL.<\/p>\n
Then, the key material you’ll get out of the HKDF need to be separated into two parts, the first 32 hex caracters are the hawk id, and the next 32 ones are the hawk key.<\/p>\n