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

From: Peter Saint-Andre <[email-masked]>
Date: Tue, 10 Nov 2009 07:14:22 +0900

<hat type='individual'/>

On the flight to Japan for IETF 76, I finally got a chance to finish
reviewing draft-hammer-oauth-03, the informational documentation of
what's known as "OAUth Core 1.0 Revision A" in the community. Many of my
comments are purely editorial, so I will send those directly to the
document editor. Here are a few slightly more substantive issues...

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.

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.)"

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.

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).

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).

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".

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.

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).

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).

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?

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.

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.

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.

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).

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.

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?

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.

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.

Overall the spec looks very good, and IMHO is a big improvement over the
community edition!

Peter

- --
Peter Saint-Andre
https://stpeter.im/

---

From: "Moore, Jonathan (CIM)" <[email-masked]>
Date: Mon, 9 Nov 2009 23:36:48 -0500

> mention in the Security Considerations.

RFC2119 says "MUST" should be reserved for cases where it is required for interoperability (which I think isn't the case here) or where it might cause harm (maybe this is true here?), and that an implementer may only ignore a "SHOULD" at his/her peril (which is for sure the case here).

I agree this is worth calling out the specific risks of ignoring this if we leave it as a SHOULD, though. 

Maybe we can say "REALLY REALLY SHOULD (NO I MEAN IT)"? :)

Jon
........
Jon Moore
Comcast Interactive Media

-----Original Message-----
From: [email-masked] on behalf of Peter Saint-Andre
Sent: Mon 11/9/2009 5:14 PM
To: OAuth WG
Subject: [OAUTH-WG] comments on draft-hammer-oauth-03

<hat type='individual'/>

16. Section 6.15 says:

Peter

- --
Peter Saint-Andre
https://stpeter.im/

_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Sun, 15 Nov 2009 15:29:27 -0700

Thanks Peter. This is very helpful.

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

> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Peter Saint-Andre
> Sent: Monday, November 09, 2009 2:14 PM

>   appropriate for publication on the standards track.

Added with minor changes.

>   "(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"

> that our usage of key terms like "authorization" is consistent with

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

> overall protocol flow (similar to Section 6 of the community edition).

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

> 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).

> 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.

> client to sync its clock with the server's clock are out of scope for

Done.

> that's where we talk about the properties of various methods).

Done.

> recent discussion on the community list).

Entire section rewritten. Review requested.

> listed conditions need to be met, or any one of the conditions?

Done.

> included (if found in the request). Let's be explicit about that.

Please check new language.

> mention in the Security Considerations.

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

> 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.

> 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.

> 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.

> 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...

> that "methods for doing so are out of scope for this specification" is

Done.

> 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

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 18 Nov 2009 14:32:36 -0700

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

Thanks for the fast turnaround! A few comments inline.

>> -----Original Message----- From: [email-masked]
>> [mailto:[email-masked]] On Behalf Of Peter Saint-Andre 
>> 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.
> 

I think this is more important for OAuth 1.1 so let's fold it into that
effort. In any case I don't think it's a lot of work.

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

I think that does it, yes.

>> 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).
> 
> "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).

That's better, thanks.

>> 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.

+1

>> 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).
> 

That's clearer now.

> Please check new language.

Works for me.

>> 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.
> 

OK.

>> 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.

Now it's clear that these rules apply to the signature base string. I
think that it would be even clearer as follows:

   This specification defines the following method for percent-
   encoding of parameter values that are used as input to construction
   of the signature base string:

(I say this because it's not 100% clear which strings are meant in the
current text -- i.e., does the method apply only to the values in the
name/value pairs?)

>> 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).
> 

OK.

>>  important and the nature of the session fixation attach that it
>> helps to prevent.
> 

Perhaps we could borrow and adjust some text from your blog post at
http://hueniverse.com/2009/04/explaining-the-oauth-session-fixation-attack/
:)

>>  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...

Again, I must be missing something. Just because I use Thunderbird or
Pidgin or some other free software doesn't mean you can hack into my
email or IM password. How is the case any different here?

>> 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.
> 

OK. Not a big deal either way.

Done.

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Ethan Jewett <[email-masked]>
Date: Wed, 18 Nov 2009 17:11:19 -0500

On Wed, Nov 18, 2009 at 4:32 PM, Peter Saint-Andre
> email or IM password. How is the case any different here?

I think in the original email "freely" was not meant in terms of free
as in beer *or* free as in speech, but rather any software distributed
in such a way that an attacker can get his/her hands on a copy of the
executable. OAuth in normal installed software must embed the client
secret into the executable, and in this case the secret is only as
secret as the executable file.

This is why OAuth providers that allow installed applications to
authenticate against them may want to just forget about the client
secret entirely.

Ethan

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 18 Nov 2009 15:38:17 -0700

> authenticate against them may want to just forget about the client

Aha, I see. I misunderstood the meaning of "freely downloadable
application".

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 18 Nov 2009 16:03:29 -0700

> From: Peter Saint-Andre [mailto:[email-masked]]
> Sent: Wednesday, November 18, 2009 1:33 PM

> current text -- i.e., does the method apply only to the values in the

I'll take a look. The problem is we "accidently" applied the encoding method to the authorization header... This means this specific way of encoding leaked out of the signature base string scope. This makes it a bit hard to be so specific about its context. I can try to be more specific by saying it is for the SBS and header, but does not apply to parameter encoding in the query or body... Not sure how much that will help though.

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

Still on my list pending more items.

> http://hueniverse.com/2009/04/explaining-the-oauth-session-fixation-

Go for it... :-) It is one thing for me to write blog posts (with the review of Brian and Dirk), but another to write it for the spec.

> email or IM password. How is the case any different here?

No no. *You* can hack those applications and find their client credentials (not token credentials).

Thanks,

EHL

---

From: Peter Saint-Andre <[email-masked]>
Date: Thu, 19 Nov 2009 16:30:55 -0700

On 11/18/09 4:03 PM, Eran Hammer-Lahav wrote:
> 
>> -----Original Message----- From: Peter Saint-Andre
>> [mailto:[email-masked]] Sent: Wednesday, November 18, 2009 1:33
>> PM
> 
>>>> 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.
>> Now it's clear that these rules apply to the signature base string.
>> I think that it would be even clearer as follows:
>> 
>> (I say this because it's not 100% clear which strings are meant in
>> the current text -- i.e., does the method apply only to the values
>> in the name/value pairs?)
> 
> I'll take a look. The problem is we "accidently" applied the encoding
> method to the authorization header... This means this specific way of
> encoding leaked out of the signature base string scope. This makes it
> a bit hard to be so specific about its context. I can try to be more
> specific by saying it is for the SBS and header, but does not apply
> to parameter encoding in the query or body... Not sure how much that
> will help though.

That's not a disaster, I just thought it would be good to clarify the
context to forestall confusion. But I don't know if this is a source of
confusion at present.

>>>> 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).

IMHO this is nice but not necessary. Perhaps it's an item for the WG
items and not the informational spec.

>>>> 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.
>> http://hueniverse.com/2009/04/explaining-the-oauth-session-fixation-
>>  attack/ :)
> 
> Go for it... :-) It is one thing for me to write blog posts (with the
> review of Brian and Dirk), but another to write it for the spec.

I'll see what I can come up with.

>>>> 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...
>> Again, I must be missing something. Just because I use Thunderbird
>> or Pidgin or some other free software doesn't mean you can hack
>> into my email or IM password. How is the case any different here?
> 

Yes, I figured that out now. :)

Peter

-- 
Peter Saint-Andre
https://stpeter.im/