Document that the payload must be UTF8 encoded

[edmorley]

We're using hawkrest server-side and are migrating users of our API to it from our legacy oauth credentials. As part of the transition one of our submitters was getting intermittent failures submitting to our API, which were showing in our API logs as:

[2015-11-02 12:57:02,796] WARNING [hawkrest:81] access denied: MacMismatch: MACs do not match; ours: REDACTED theirs: REDACTED
(which comes from mohawk: https://github.com/kumar303/mohawk/blob/0.3.0/mohawk/base.py#L50)

It turned out that these were due to them not UTF8 encoding the payload passed to hawk.client.header().

This isn't mentioned anywhere in the README, only in passing here:
https://github.com/hueniverse/hawk/blob/v3.1.0/lib/client.js#L36

Would it be possible to make this clearer in the readme? Perhaps it's worth having a troubleshooting section?

Thanks :-)

[hueniverse]

I'll take a PR.

[edmorley]

I'll take a PR.

Sure, happy to open one - there just seems to be a difference between documented spec, Hawk source and downstream mohawk implementation - and I'm not sure which is correct.

ie the Hawk docs say:

### Payload Validation
**Hawk** provides optional payload validation. When generating the authentication header, the client calculates a payload hash
using the specified hash algorithm. The hash is calculated over the concatenated value of (each followed by a newline character):
* ...
* ...
* the request payload prior to any content encoding (the exact representation requirements should be specified by the server for payloads other than simple single-part ascii to ensure interoperability)

Whereas the Hawk source comments:

payload: '{"some":"payload"}',  // UTF-8 encoded string for body hash generation (ignored if hash provided)

And mohawk assumes the client has UTF8 encoded the payload before hashing:

# Make sure we are about to hash binary strings.
if not isinstance(p, six.binary_type):
    p = p.encode('utf8')

Should I:

1. Fix the README comments to say that UTF8 encoding must be performed when not dealing with straight ascii
2. Mention it depends on the server, but state that if using mohawk, UTF8 is expected
3. Something else?

Many thanks :-)

[hueniverse]

The payload needs to be hashed based on it raw HTTP representation which is 7bit ascii and before any HTTP content encoding is applied (gzip, etc.).

[lock]

This thread has been automatically locked due to inactivity. Please open a new issue for related bugs or questions following the new issue template instructions.