Re: [OAUTH-WG] comments on draft-hammer-oauth-03

[Eran Hammer-Lahav <[e-mail]>]

Thanks Peter. This is very helpful.

The following changes have been submitted as a -04 revision.

> -----Original Message-----
> From: [e-mail] [mailto:[e-mail]] On Behalf
> Of Peter Saint-Andre
> Sent: Monday, November 09, 2009 2:14 PM

> 1. I think it would be very helpful to provide a bit more context in
> the
> Introduction. Say, two or three sentences about the provenance of this
> technology, the community that developed it, and a link to oauth.net
> (along with something like the final paragraph of the current
> Introduction). Something like this:
> 
>   The OAuth protocol was originally created by a loose group of
>   technologists from a variety of websites and other Internet
>   services, who wanted to solve the common problem of enabling
>   delegated access to protected resources.  The resulting OAuth
>   protocol was stabilized at version 1.0 in October 2007 and
>   published at the oauth.net website.  This specification provides
>   informational documentation of OAuth Core 1.0 Revision A as
>   finalized in June 2009, incorporating several errata reported
>   since that time as well as numerous editorial clarifications.
>   It is not an item of the IETF's OAuth Working Group, which at
>   the time of writing is working on an OAuth version that can be
>   appropriate for publication on the standards track.

Added with minor changes.

> 2. In the Terminology section, I think it might be helpful to provide
> pointers to the old terminology, as in:
> 
>   "(In the community edition, a client was called a consumer.)"

Added:

"The original community specification used a somewhat different terminology which maps to this specifications as follows:

* consumer - client
* service provider - server
* user - resource owner
* consumer key and secret - client credentials
* request token and secret - temporary credentials
* access token and secret  - token credentials"

> We might also want to point to RFC 4949 regarding terminology and check
> that our usage of key terms like "authorization" is consistent with
> that
> document.

If someone wants to give it a try, I am open to it.

> 3. Before jumping right into authenticated requests in section 3, I
> think it would be helpful to provide a bit more context about the
> overall protocol flow (similar to Section 6 of the community edition).

I flipped between section 3 and 4. This might be enough.

> 4. In Section 3.1, we might want to say explicitly which parameters are
> required and which are not. For example, "Protocol parameters MUST NOT
> appear more than once per request. The following parameters are
> REQUIRED
> unless otherwise noted." Then say that, for example, oauth_version is
> RECOMMENDED instead of REQUIRED (or whatever).

In the new section 4.1 I added:

       Each of the protocol parameters listed in Section 4.3 except for
       "oauth_signature" is assigned a value based on its definition.
       All the parameters MUST be included, except for "oauth_version"
       which MAY be omitted, and "oauth_token" which MUST be omitted
       when making a temporary credentials request (Section 3.1).

> 5. In Section 3.2, it's not completely clear that the timestamp value
> must be numerical instead of, say, in ISO 8601 format. It's also not
> clear how the server would specify that the timestamp is something
> other
> than "the number of seconds since January 1, 1970 00:00:00 GMT".

I made a protocol change to this section, simplifying the text and remove the 'equal or greater' requirement (which is not really practical when used across multiple machines):

            The timestamp value MUST be a positive integer. Unless otherwise specified by the
            server's documentation, the timestamp is expressed in the number of seconds since
            January 1, 1970 00:00:00 GMT.

> 6. In Section 3.2, let's explicitly say that methods that enable the
> client to sync its clock with the server's clock are out of scope for
> OAuth.

Done.

> 7. In Section 3.3, let's refer to the Security Considerations from the
> paragraph about not mandating a particular signature method (since
> that's where we talk about the properties of various methods).

Done.

> 8. In Section 3.3.1.1, we might want to be more explicit about which
> parameters are included in the "specific set of request parameters"
> (see
> recent discussion on the community list).

Entire section rewritten. Review requested.

> 9. In Section 3.3.1.1 second bullet point, we say "The HTTP request
> entity-body, but only if..." -- does this mean that all of the three
> listed conditions need to be met, or any one of the conditions?

Done.

> 10. In Section 3.3.1.1, the sentence
> 
>     The "oauth_signature" parameter MUST be excluded if present.
> 
> might be taken to imply that all other oauth_* parameters MUST be
> included (if found in the request). Let's be explicit about that.

Please check new language.

> 11. In Section 3.3.4, we say that PLAINTEXT method SHOULD be used with
> SSL/TLS. Does that deserve to be a MUST? At least it might be worth a
> mention in the Security Considerations.

MUST is asking for too much. I added a pointer to the relevant security section.

> 12. In Section 3.6, we say that "Text values are first encoded as UTF-
> 8"
> but it's not fully clear to me which values this applies to or exactly
> where in the protocol the encoding rules are applied.

I added an introduction to the section. This has always been a sore point and underspecified. I am happy to consider clarifications.

> 13. In Section 4, I think that a brief flow diagram would be helpful to
> illustrate the authorization process (e.g., this would provide context
> for why the client obtains a set of temporary credentials, which might
> not otherwise be obivous to first-time readers of Section 4.1).

I am going to dig Jeff's diagrams and see if I can make them work for this.

> 14. In Section 4.2 (or in a security consideration pointed to from
> Section 4.2), it might be helpful to describe why oauth_callback is
> important and the nature of the session fixation attach that it helps
> to prevent.

If someone wants to offer text, I am happy to consider. I don't write security text.

> 15. In Section 6.8, I think there is a non-sequitur. Just because a
> client is a freely available desktop application does not mean that an
> attacker will be able to recover the client credentials. Perhaps one
> step in the chain of reasoning is not spelled out here?

If you have access to the client bits, you can reverse engineer it to get the secret. See DVD encryption key...

> 16. Section 6.15 says:
> 
>     Clients should prevent CSRF attacks on OAuth callback URIs
>     by verifying that the resource owner at the client site intended to
>     complete the OAuth negotiation with the server.
> 
> No guidance is provided on how the client might be able to do so.
> Saying
> that "methods for doing so are out of scope for this specification" is
> probably acceptable.

Done.

> 17. In Appendix A.1 the phrase "HTTPS POST" is used, but I think that's
> more accurately an HTTP POST to an SSL-protected host.

I think it is easier to read this way.

Thanks again. Please review -04.

EHL