API

This is a detailed look at the Mohawk API. For general usage patterns see Using Mohawk.

Sender

class mohawk.Sender(credentials, url, method, content=EmptyValue, content_type=EmptyValue, always_hash_content=True, nonce=None, ext=None, app=None, dlg=None, seen_nonce=None, _timestamp=None)[source]

A Hawk authority that will emit requests and verify responses.

Parameters:
  • credentials (dict) – Dict of credentials with keys id, key, and algorithm. See Using Mohawk for an example.
  • url (str) – Absolute URL of the request.
  • method (str) – Method of the request. E.G. POST, GET
  • content=EmptyValue (str or file-like object) – Byte string of request body or a file-like object.
  • content_type=EmptyValue (str) – content-type header value for request.
  • always_hash_content=True (bool) – When True, content and content_type must be provided. Read Skipping content checks to learn more.
  • nonce=None (str) – A string that when coupled with the timestamp will uniquely identify this request to prevent replays. If None, a nonce will be generated for you.
  • ext=None (str) – An external Hawk string. If not None, this value will be signed so that the receiver can trust it.
  • app=None (str) – A Hawk application string. If not None, this value will be signed so that the receiver can trust it.
  • dlg=None (str) – A Hawk delegation string. If not None, this value will be signed so that the receiver can trust it.
  • seen_nonce=None (callable) – A callable that returns True if a nonce has been seen. See Using a nonce to prevent replay attacks for details.
accept_response(response_header, content=EmptyValue, content_type=EmptyValue, accept_untrusted_content=False, localtime_offset_in_seconds=0, timestamp_skew_in_seconds=60, **auth_kw)[source]

Accept a response to this request.

Parameters:
  • response_header (str) – A Hawk Server-Authorization header such as one created by mohawk.Receiver.
  • content=EmptyValue (str) – Byte string of the response body received.
  • content_type=EmptyValue (str) – Content-Type header value of the response received.
  • accept_untrusted_content=False (bool) – When True, allow responses that do not hash their content. Read Skipping content checks to learn more.
  • localtime_offset_in_seconds=0 (float) – Seconds to add to local time in case it’s out of sync.
  • timestamp_skew_in_seconds=60 (float) – Max seconds until a message expires. Upon expiry, mohawk.exc.TokenExpired is raised.
request_header = None

Value suitable for an Authorization header.

Receiver

class mohawk.Receiver(credentials_map, request_header, url, method, content=EmptyValue, content_type=EmptyValue, seen_nonce=None, localtime_offset_in_seconds=0, accept_untrusted_content=False, timestamp_skew_in_seconds=60, **auth_kw)[source]

A Hawk authority that will receive and respond to requests.

Parameters:
  • credentials_map (callable) – Callable to look up the credentials dict by sender ID. The credentials dict must have the keys: id, key, and algorithm. See Receiving a request for an example.
  • request_header (str) – A Hawk Authorization header such as one created by mohawk.Sender.
  • url (str) – Absolute URL of the request.
  • method (str) – Method of the request. E.G. POST, GET
  • content=EmptyValue (str) – Byte string of request body.
  • content_type=EmptyValue (str) – content-type header value for request.
  • accept_untrusted_content=False (bool) – When True, allow requests that do not hash their content. Read Skipping content checks to learn more.
  • localtime_offset_in_seconds=0 (float) – Seconds to add to local time in case it’s out of sync.
  • timestamp_skew_in_seconds=60 (float) – Max seconds until a message expires. Upon expiry, mohawk.exc.TokenExpired is raised.
respond(content=EmptyValue, content_type=EmptyValue, always_hash_content=True, ext=None)[source]

Respond to the request.

This generates the mohawk.Receiver.response_header attribute.

Parameters:
  • content=EmptyValue (str) – Byte string of response body that will be sent.
  • content_type=EmptyValue (str) – content-type header value for response.
  • always_hash_content=True (bool) – When True, content and content_type must be provided. Read Skipping content checks to learn more.
  • ext=None (str) – An external Hawk string. If not None, this value will be signed so that the sender can trust it.
response_header = None

Value suitable for a Server-Authorization header.

Exceptions

If you want to catch any exception that might be raised, catch mohawk.exc.HawkFail.

Important

Never expose an exception message publicly, say, in an HTTP response, as it may provide hints to an attacker.

exception mohawk.exc.AlreadyProcessed[source]

The message has already been processed and cannot be re-processed.

See Using a nonce to prevent replay attacks for details.

exception mohawk.exc.BadHeaderValue[source]

There was an error with an attribute or value when parsing or creating a Hawk header.

exception mohawk.exc.CredentialsLookupError[source]

A mohawk.Receiver could not look up the credentials for an incoming request.

exception mohawk.exc.HawkFail[source]

All Mohawk exceptions derive from this base.

exception mohawk.exc.InvalidBewit[source]

The bewit is invalid; e.g. it doesn’t contain the right number of parameters.

exception mohawk.exc.InvalidCredentials[source]

The specified Hawk credentials are invalid.

For example, the dict could be formatted incorrectly.

exception mohawk.exc.MacMismatch[source]

The locally calculated MAC did not match the MAC that was sent.

exception mohawk.exc.MisComputedContentHash[source]

The signature of the content did not match the actual content.

exception mohawk.exc.MissingAuthorization[source]

No authorization header was sent by the client.

exception mohawk.exc.MissingContent[source]

A payload’s content or content_type were not provided.

See Skipping content checks for details.

exception mohawk.exc.TokenExpired(*args, **kw)[source]

The timestamp on a message received has expired.

You may also receive this message if your server clock is out of sync. Consider synchronizing it with something like TLSdate.

If you are unable to synchronize your clock universally, The Hawk spec mentions how you can adjust your sender’s time to match that of the receiver in the case of unexpected expiration.

The www_authenticate attribute of this exception is a header that can be returned to the client. If the value is not None, it will include a timestamp HMAC’d with the sender’s credentials. This will allow the client to verify the value and safely apply an offset.

localtime_in_seconds = None

Current local time in seconds that was used to compare timestamps.

Base

class mohawk.base.Resource(**kw)[source]

Normalized request / response resource.

Parameters:
  • credentials – A dict of credentials; it must have the keys: id, key, and algorithm. See Sending a request for an example.
  • url (str) – Absolute URL of the request / response.
  • method (str) – Method of the request / response. E.G. POST, GET
  • content=EmptyValue (str) – Byte string of request / response body.
  • content_type=EmptyValue (str) – content-type header value for request / response.
  • always_hash_content=True (bool) – When True, content and content_type must be provided. Read Skipping content checks to learn more.
  • ext=None (str) – An external Hawk string. If not None, this value will be signed so that the sender can trust it.
  • app=None (str) – A Hawk string identifying an external application.
  • dlg=None (str) – A Hawk string identifying a “delegated by” value.
  • timestamp=utc_now() – A unix timestamp integer, in UTC
  • nonce=None (str) – A string that when coupled with the timestamp will uniquely identify this request / response.
  • seen_nonce=None (callable) – A callable that returns True if a nonce has been seen. See Using a nonce to prevent replay attacks for details.
mohawk.base.EmptyValue = EmptyValue

This represents an empty value but not None.

This is typically used as a placeholder of a default value so that internal code can differentiate it from None.