[OAUTH-WG] Editorial comments for draft-ietf-oauth-v2-bearer-09

Hannes Tschofenig <hannes.tschofenig@gmx.net> Wed, 19 October 2011 00:22 UTC

Return-Path: <hannes.tschofenig@gmx.net>
X-Original-To: oauth@ietfa.amsl.com
Delivered-To: oauth@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 21E2321F8634 for <oauth@ietfa.amsl.com>; Tue, 18 Oct 2011 17:22:02 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -102.599
X-Spam-Level:
X-Spam-Status: No, score=-102.599 tagged_above=-999 required=5 tests=[BAYES_00=-2.599, USER_IN_WHITELIST=-100]
Received: from mail.ietf.org ([12.22.58.30]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id as9apUHxqGWA for <oauth@ietfa.amsl.com>; Tue, 18 Oct 2011 17:22:01 -0700 (PDT)
Received: from mailout-de.gmx.net (mailout-de.gmx.net [213.165.64.23]) by ietfa.amsl.com (Postfix) with SMTP id 338A521F8511 for <oauth@ietf.org>; Tue, 18 Oct 2011 17:22:00 -0700 (PDT)
Received: (qmail invoked by alias); 19 Oct 2011 00:21:59 -0000
Received: from unknown (EHLO [10.2.2.99]) [64.9.249.121] by mail.gmx.net (mp007) with SMTP; 19 Oct 2011 02:21:59 +0200
X-Authenticated: #29516787
X-Provags-ID: V01U2FsdGVkX1+SpW8dct+SocDHjvQQ8IQTFNExX8AfjcmH6/ukTp 5LkSgR5cPVruV2
From: Hannes Tschofenig <hannes.tschofenig@gmx.net>
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Date: Tue, 18 Oct 2011 17:21:56 -0700
Message-Id: <0190D8E8-FC04-4645-A142-995CF56F7384@gmx.net>
To: OAuth WG <oauth@ietf.org>, Mike Jones <Michael.Jones@microsoft.com>
Mime-Version: 1.0 (Apple Message framework v1084)
X-Mailer: Apple Mail (2.1084)
X-Y-GMX-Trusted: 0
Subject: [OAUTH-WG] Editorial comments for draft-ietf-oauth-v2-bearer-09
X-BeenThere: oauth@ietf.org
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: OAUTH WG <oauth.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/oauth>, <mailto:oauth-request@ietf.org?subject=unsubscribe>
List-Archive: <http://www.ietf.org/mail-archive/web/oauth>
List-Post: <mailto:oauth@ietf.org>
List-Help: <mailto:oauth-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/oauth>, <mailto:oauth-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 19 Oct 2011 00:22:02 -0000

Hi Mike, 

based on our discussion I suggest to make the following minor editorial changes to the specification. Let me provide specific text proposals. 

I recommend to extend the abstract a little bit. The current text does not tell the reader a lot and the RFC editor will require more text (because it is too short)

FROM: 

"
Abstract

   This specification describes how to use bearer tokens in HTTP
   requests to access OAuth 2.0 protected resources.
"

TO:

"
Abstract

   This specification describes how to use bearer tokens in HTTP
   requests to access OAuth 2.0 protected resources.  A bearer token has the 
   property that any party in possession of it (a "bearer") can use it to get 
   access to a resource granted (without demonstrating  
   possession of a cryptographic key).  To prevent misuse, the bearer token 
   has to be protected in storage and in transport. 
"


To make the introduction of Section 2 more readable I suggest the following modified text (that replaces the existing text). 

-----

  2. Authenticated Requests

   To access a protected resource the client needs to present the bearer token 
   to the resource server. This document defines three ways to encode the token 
   into a request, namely 
   
   1) Authorization Request Headers (described in Section 2.1)
   2) Form-Encoded Body Parameter (described in Section 2.2)  
   3) URI Query Parameter (described in Section 2.3)
   
   The usage of the authorization request headers is the preferred mechanism. 
   Resource servers MUST implement the authorization request header mechanism 
   and MAY implement other methods.

   Form-Encoded Body Parameter and URI Query Parameter are fall-back solutions 
   for environments where authorization request headers cannot be used. They 
   are therefore NOT RECOMMENDED for usage due to security deficiencies, as 
   documented in Section 4. They are nevertheless included in this specification 
   to describe existing deployments.
   
   Clients MUST NOT use more than one method to transmit the token in a single 
   request.

------ 


I also suggest to Section 2.4 into Section 3. The security consideration section then becomes Section 4. 

Ciao
Hannes