Using Mohawk

There are two parties involved in Hawk communication: a sender and a receiver. They use a shared secret to sign and verify each other’s messages.

A client who wants to access a Hawk-protected resource. The client will sign their request and upon receiving a response will also verify the response signature.
A server that uses Hawk to protect its resources. The server will check the signature of an incoming request before accepting it. It also signs its response using the same shared secret.

What are some good use cases for Hawk? This library was built for the case of securing API connections between two back-end servers. Hawk is a good fit for this because you can keep the shared secret safe on each machine. Hawk may not be a good fit for scenarios where you can’t protect the shared secret.

After getting familiar with usage, you may want to consult the Security Considerations section.

Sending a request

Let’s say you want to make an HTTP request like this:

>>> url = ''
>>> method = 'POST'
>>> content = 'one=1&two=2'
>>> content_type = 'application/x-www-form-urlencoded'

Set up your Hawk request by creating a mohawk.Sender object with all the elements of the request that you need to sign:

>>> from mohawk import Sender
>>> sender = Sender({'id': 'some-sender',
...                  'key': 'a long, complicated secret',
...                  'algorithm': 'sha256'},
...                 url,
...                 method,
...                 content=content,
...                 content_type=content_type)

This provides you with a Hawk Authorization header to send along with your request:

>>> sender.request_header
'Hawk mac="...", hash="...", id="some-sender", ts="...", nonce="..."'

Using the requests library just as an example, you would send your POST like this:

>>>, data=content,
...               headers={'Authorization': sender.request_header,
...                        'Content-Type': content_type})

Notice how both the content and content-type values were signed by the Sender. In the case of a GET request you’ll probably need to sign empty strings like Sender(..., 'GET', content='', content_type=''), that is, if your request library doesn’t automatically set a content-type for GET requests.

If you only intend to work with mohawk.Sender, skip down to Verifying a response.

Receiving a request

On the receiving end, such as a web server, you’ll need to set up a mohawk.Receiver object to accept and respond to mohawk.Sender requests.

First, you need to give the receiver a callable that it can use to look up sender credentials:

>>> def lookup_credentials(sender_id):
...     if sender_id in allowed_senders:
...         # Return a credentials dictionary formatted like the sender example.
...         return allowed_senders[sender_id]
...     else:
...         raise LookupError('unknown sender')

An incoming request will probably arrive in an object like this, depending on your web server framework:

>>> request = {'headers': {'Authorization': sender.request_header,
...                        'Content-Type': content_type},
...            'url': url,
...            'method': method,
...            'content': content}

Create a mohawk.Receiver using values from the incoming request:

>>> from mohawk import Receiver
>>> receiver = Receiver(lookup_credentials,
...                     request['headers']['Authorization'],
...                     request['url'],
...                     request['method'],
...                     content=request['content'],
...                     content_type=request['headers']['Content-Type'])

If this constructor does not raise any Exceptions then the signature of the request is correct and you can proceed.


The server running mohawk.Receiver code should synchronize its clock with something like TLSdate to make sure it compares timestamps correctly.

Responding to a request

It’s optional per the Hawk spec but a mohawk.Receiver should sign its response back to the client to prevent certain attacks.

The receiver starts by building a message it wants to respond with:

>>> response_content = '{"msg": "Hello, dear friend"}'
>>> response_content_type = 'application/json'
>>> header = receiver.respond(content=response_content,
...                           content_type=response_content_type)

This provides you with a similar Hawk header to use in the response:

>>> receiver.response_header
'Hawk mac="...", hash="...="'

Using your web server’s framework, respond with a Server-Authorization header. For example:

>>> response = {
...     'headers': {'Server-Authorization': receiver.response_header,
...                 'Content-Type': response_content_type},
...     'content': response_content
... }

Verifying a response

When the mohawk.Sender receives a response it should verify the signature to make sure nothing has been tampered with:

>>> sender.accept_response(response['headers']['Server-Authorization'],
...                        content=response['content'],
...                        content_type=response['headers']['Content-Type'])

If this method does not raise any Exceptions then the signature of the response is correct and you can proceed.

Allowing senders to adjust their timestamps

The easiest way to avoid timestamp problems is to synchronize your server clock using something like TLSdate.

If a sender’s clock is out of sync with the receiver, its message might expire prematurely. In this case the receiver should respond with a header the sender can use to adjust its timestamp.

When receiving a request you might get a mohawk.exc.TokenExpired exception. You can access the www_authenticate property on the exception object to respond correctly like this:

>>> from mohawk.exc import TokenExpired
>>> try:
...     receiver = Receiver(lookup_credentials,
...                         request['headers']['Authorization'],
...                         request['url'],
...                         request['method'],
...                         content=request['content'],
...                         content_type=request['headers']['Content-Type'])
... except TokenExpired as expiry:
...     response['headers']['WWW-Authenticate'] = expiry.www_authenticate
...     print(expiry.www_authenticate)
Hawk ts="...", tsm="...", error="token with UTC timestamp...has expired..."

A compliant client can look for this response header and parse the ts property (the server’s “now” timestamp) and the tsm property (a MAC calculation of ts). It can then recalculate the MAC using its own credentials and if the MACs both match it can trust that this is the real server’s timestamp. This allows the sender to retry the request with an adjusted timestamp.

Using a nonce to prevent replay attacks

A replay attack is when someone copies a Hawk authorized message and re-sends the message without altering it. Because the Hawk signature would still be valid, the receiver may accept the message. This could have unintended side effects such as increasing the quantity of an item just purchased if it were a commerce API that had an increment-item service.

Hawk protects against replay attacks in a couple ways. First, a receiver checks the timestamp of the message which may result in a mohawk.exc.TokenExpired exception. Second, every message includes a cryptographic nonce which is a unique identifier. In combination with the sender’s id and the request’s timestamp, a receiver can use the nonce to know if it has already received the request. If so, the mohawk.exc.AlreadyProcessed exception is raised.

By default, Mohawk doesn’t know how to check nonce values; this is something your application needs to do.


If you don’t configure nonce checking, your application could be susceptible to replay attacks.

Make a callable that returns True if a sender’s nonce plus its timestamp has been seen already. Here is an example using something like memcache:

>>> def seen_nonce(sender_id, nonce, timestamp):
...     key = '{id}:{nonce}:{ts}'.format(id=sender_id, nonce=nonce,
...                                      ts=timestamp)
...     if memcache.get(key):
...         # We have already processed this nonce + timestamp.
...         return True
...     else:
...         # Save this nonce + timestamp for later.
...         memcache.set(key, True)
...         return False

Because messages will expire after a short time you don’t need to store nonces for much longer than that timeout. See mohawk.Receiver for the default timeout.

Pass your callable as a seen_nonce argument to mohawk.Receiver:

>>> receiver = Receiver(lookup_credentials,
...                     request['headers']['Authorization'],
...                     request['url'],
...                     request['method'],
...                     content=request['content'],
...                     content_type=request['headers']['Content-Type'],
...                     seen_nonce=seen_nonce)

If seen_nonce() returns True, mohawk.exc.AlreadyProcessed will be raised.

When a sender calls mohawk.Sender.accept_response(), it will receive a Hawk message but the nonce will be that of the original request. In other words, the nonce received is the same nonce that the sender generated and signed when initiating the request. This generally means you don’t have to worry about response replay attacks. However, if you expose your mohawk.Sender.accept_response() call somewhere publicly over HTTP then you may need to protect against response replay attacks. You can do so by constructing a mohawk.Sender with the same seen_nonce keyword:

>>> sender = Sender({'id': 'some-sender',
...                  'key': 'a long, complicated secret',
...                  'algorithm': 'sha256'},
...                 url,
...                 method,
...                 content=content,
...                 content_type=content_type,
...                 seen_nonce=seen_nonce)

Skipping content checks

In some cases you may not be able to hash request/response content. For example, the content could be too large. If you run into this, Hawk might not be the best fit for you but Hawk does allow you to accept content without a declared hash if you wish.


By allowing content without a declared hash, both the sender and receiver are susceptible to content tampering.

You can send a request without signing the content by passing this keyword argument to a mohawk.Sender:

>>> sender = Sender(credentials, url, method, always_hash_content=False)

This says to skip hashing of the content and content_type values if they are both mohawk.base.EmptyValue.

Now you’ll get an Authorization header without a hash attribute:

>>> sender.request_header
'Hawk mac="...", id="some-sender", ts="...", nonce="..."'

The mohawk.Receiver must also be constructed to accept content without a declared hash using accept_untrusted_content=True:

>>> receiver = Receiver(lookup_credentials,
...                     sender.request_header,
...                     request['url'],
...                     request['method'],
...                     content=request['content'],
...                     content_type=request['headers']['Content-Type'],
...                     accept_untrusted_content=True)

This will skip checking the hash of content and content_type only if the Authorization header omits the hash attribute. If the hash attribute is present, it will be checked as normal.

Empty requests

For requests whose content (and by extension content_type) is None or an empty string, it is acceptable for the sender to omit the declared hash, regardless of the accept_untrusted_content value provided to the mohawk.Receiver. For example, a GET request typically has empty content and some libraries may or may not hash the content.

If the hash attribute is present, a None value for either content or content_type will be coerced to an empty string prior to hashing.

Generating protected URLs

Hawk lets you protect a URL with a token derived from a secret key. After a period of time, access to the URL will expire. As an example, you could use this to deliver a URL for purchased media, such a zip file of MP3s. The user could access the URL for a short period of time but after that, the same URL would not be accessible.

In the Hawk spec, this is referred to as Single URI Authorization, or bewit.

Here’s an example of protecting access to this URL with Mohawk:

>>> url = ''

Let’s say you want to allow access for 5 minutes:

>>> from mohawk.util import utc_now
>>> url_expires_at = utc_now() + (60 * 5)

Set up Hawk credentials like in previous examples:

>>> credentials = {
...     'id': 'some-recipient',
...     'key': 'a long, complicated secret',
...     'algorithm': 'sha256'
... }

Define the resource that you want to protect:

>>> from mohawk.base import Resource
>>> resource = Resource(
...     credentials=credentials,
...     url=url,
...     method='GET',
...     nonce='',
...     timestamp=url_expires_at,
... )

Generate a bewit token:

>>> from mohawk.bewit import get_bewit
>>> bewit = get_bewit(resource)

Add that token as a bewit query string parameter back to the same URL:

>>> protected_url = '{url}?bewit={bewit}'.format(url=url, bewit=bewit)
>>> protected_url

Now you can deliver this bewit protected URL to the recipient.

Serving protected URLs

When handling a request for a bewit protected URL on the server, you can begin by checking the bewit to make sure it’s valid. If True, the server can respond with access to the resource. The check_bewit function returns True or False and will also raise an exception for invalid bewit values.

>>> allowed_recipients = {}
>>> allowed_recipients['some-recipient'] = credentials
>>> def lookup_credentials(recipient_id):
...     if recipient_id in allowed_recipients:
...         # Return a credentials dictionary
...         return allowed_recipients[recipient_id]
...     else:
...         raise LookupError('unknown recipient_id')
>>> from mohawk.bewit import check_bewit
>>> check_bewit(protected_url, credential_lookup=lookup_credentials)


Well, that was complicated! At a future time, get_bewit and check_bewit will be complimented with a higher level function that is easier to work with. See


All internal logging channels stem from mohawk. For example, the mohawk.receiver channel will just contain receiver messages. These channels correspond to the submodules within mohawk.

To debug mohawk.exc.MacMismatch Exceptions and other authorization errors, set the mohawk channel to DEBUG.

Going further

Well, hey, that about summarizes the concepts and basic usage of Mohawk. Check out the API for details. Also make sure you are familiar with Security Considerations.