Subject: [OAUTH-WG] MAC: comments on draft-hammer-oauth-v2-mac-token-00

From: "Manger, James H" <[email-masked]>
Date: Tue, 11 Jan 2011 17:04:30 +1100

Comments on draft-hammer-oauth-v2-mac-token-00
<http://tools.ietf.org/html/draft-hammer-oauth-v2-mac-token-00>

1. The connection of this MAC scheme to OAuth is secondary. The primary function of the MAC scheme is to secure the authenticity of parts of an HTTP request using a shared secret. Section 2 "Issuing MAC-Type Access Tokens" would be better at the end, ideally as an Annex, along with most of the OAuth talk from the introduction (and title).

2. Include a \n after the final query string parameter.
It makes the format simply lines of text, instead of making the last line special (and only special if there are query params). It is awkward to manually edit sample files, debug files etc without a final newline character. Adding a final \n would just make it more consistent.

3. The Authorization header example in 1.1 uses single quotes around values. It should use double quotes. The ABNF in 3.1 for timestamp, for instance, explicitly uses <">.

4. The quoted-string production only supports a subset of ASCII. Better add a sentence stating that the 'token' is assumed to only use this subset so no escaping is defined. May be worth adding that only double-quote and backslash need escaping in quoted-string, but neither of those are allowed in any of this specs parameters so no escaping in quoted-string values shall occur.

5. Don't list the new line characters as separate numbered items in section 3.2.1 "Normalized Request String". Better to say it is a line-based format. Each line ends with a single new line character (U+000A). Then list the 7 lines (as points 1 to 7), followed by point 8 saying there is 1 extra line for each query string parameter.

6. I18N. Is the Normalised Request String UTF-8, or does it happen to be just ASCII? Host, path, and query strings can contain non-ASCII characters -- but I guess that the ASCII-only escaping used to create an HTTP Host header and URI are assumed to have occurred before this spec uses these values. Would be worth an explicit statement, and definitely an example.

7. I suggest swapping steps 2 (sort) & 3 (combine escaped name and value) in section 3.2.1.1. "Parameters Normalization".
The current 2-layer sort is not ideal (sort on %-escaped name, then on %-escaped value if the names are equal). It needs a special comparator function etc, instead of using a programming language's standard sort-a-list-of-strings function. It is tempting to concatenate %-escaped name=value pairs and sort those -- but it doesn't always give the same result. Eg a1=X and a11=Y should sort in that order according to the spec, but "1" < "=" in an ASCII string comparison of the pairs.
A programmer probably has a map/dictionary/assoc-array of unescaped names to values. The normalisation rules require a separate map of escaped names to escaped values plus a custom comparator that considers names and values.
A nicer alternative would be to construct escaped name=value pairs then sort that list (not map).
It would be worth adding another parameter to the example (eg a22=A) to illustrate this (regardless of whether or not the steps are swapped).

8. HMAC operates on bytes, not strings. The 'text' and 'key' HMAC inputs (in 3.2.2 and 3.2.3) should be specified as the UTF-8-encoding of the Normalized Request String and access token shared secret respectively. Might be able to say ASCII-encoding, but only if we are sure that an OAuth token response (which might be a UTF-8 JSON blob) can never return non-ASCII chars in a 'secret' field.

9. The 'secret' parameter is registered twice (7.1 & 7.2). I guess one of these should be registering the 'algorithm' parameter instead.

10. I would like a "WWW-Authenticate: MAC algorithm=..." response header defined. It would provide a nice illustration of how a complete HTTP auth scheme is mapped to OAuth2. That is, how the scheme name "MAC" and parameters from the "WWW-Authenticate: MAC ..." response header can be mapped to fields in an OAuth2 token response (where they are accompanied by an actual secret key).

--
James Manger