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
, andalgorithm
. 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
andcontent_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 bymohawk.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.
- response_header (str) – A Hawk
-
request_header
= None¶ Value suitable for an
Authorization
header.
- credentials (dict) – Dict of credentials with keys
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
, andalgorithm
. See Receiving a request for an example. - request_header (str) – A Hawk
Authorization
header such as one created bymohawk.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
andcontent_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.
- credentials_map (callable) – Callable to look up the credentials dict by sender ID.
The credentials dict must have the keys:
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.
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.
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
, andalgorithm
. 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
andcontent_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.
- credentials – A dict of credentials; it must have the keys:
-
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
.