draft-ietf-oauth-spop-12.txt   draft-ietf-oauth-spop-13.txt 
OAuth Working Group N. Sakimura, Ed. OAuth Working Group N. Sakimura, Ed.
Internet-Draft Nomura Research Institute Internet-Draft Nomura Research Institute
Intended status: Standards Track J. Bradley Intended status: Standards Track J. Bradley
Expires: December 8, 2015 Ping Identity Expires: January 6, 2016 Ping Identity
N. Agarwal N. Agarwal
Google Google
June 6, 2015 July 5, 2015
Proof Key for Code Exchange by OAuth Public Clients Proof Key for Code Exchange by OAuth Public Clients
draft-ietf-oauth-spop-12 draft-ietf-oauth-spop-13
Abstract Abstract
OAuth 2.0 public clients utilizing the Authorization Code Grant are OAuth 2.0 public clients utilizing the Authorization Code Grant are
susceptible to the authorization code interception attack. This susceptible to the authorization code interception attack. This
specification describes the attack as well as a technique to mitigate specification describes the attack as well as a technique to mitigate
against the threat. against the threat.
Status of This Memo Status of This Memo
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 8, 2015. This Internet-Draft will expire on January 6, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 18 skipping to change at page 2, line 18
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 4
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 5 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 5
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.1. Client creates a code verifier . . . . . . . . . . . . . 6 4.1. Client creates a code verifier . . . . . . . . . . . . . 6
4.2. Client creates the code challenge . . . . . . . . . . . . 7 4.2. Client creates the code challenge . . . . . . . . . . . . 7
4.3. Client sends the code challenge with the authorization 4.3. Client sends the code challenge with the authorization
request . . . . . . . . . . . . . . . . . . . . . . . . . 7 request . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.4. Server returns the code . . . . . . . . . . . . . . . . . 7 4.4. Server returns the code . . . . . . . . . . . . . . . . . 8
4.4.1. Error Response . . . . . . . . . . . . . . . . . . . 8 4.4.1. Error Response . . . . . . . . . . . . . . . . . . . 8
4.5. Client sends the code and the secret to the token 4.5. Client sends the code and the secret to the token
endpoint . . . . . . . . . . . . . . . . . . . . . . . . 8 endpoint . . . . . . . . . . . . . . . . . . . . . . . . 8
4.6. Server verifies code_verifier before returning the tokens 8 4.6. Server verifies code_verifier before returning the tokens 9
5. Compatibility . . . . . . . . . . . . . . . . . . . . . . . . 9 5. Compatibility . . . . . . . . . . . . . . . . . . . . . . . . 9
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
6.1. OAuth Parameters Registry . . . . . . . . . . . . . . . . 9 6.1. OAuth Parameters Registry . . . . . . . . . . . . . . . . 9
6.2. PKCE Code Challenge Method Registry . . . . . . . . . . . 10 6.2. PKCE Code Challenge Method Registry . . . . . . . . . . . 10
6.2.1. Registration Template . . . . . . . . . . . . . . . . 10 6.2.1. Registration Template . . . . . . . . . . . . . . . . 10
6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 11 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11
7.1. Entropy of the code_verifier . . . . . . . . . . . . . . 11 7.1. Entropy of the code_verifier . . . . . . . . . . . . . . 11
7.2. Protection against eavesdroppers . . . . . . . . . . . . 11 7.2. Protection against eavesdroppers . . . . . . . . . . . . 12
7.3. Salting the code_challenge . . . . . . . . . . . . . . . 12 7.3. Salting the code_challenge . . . . . . . . . . . . . . . 12
7.4. OAuth security considerations . . . . . . . . . . . . . . 12 7.4. OAuth security considerations . . . . . . . . . . . . . . 13
7.5. TLS security considerations . . . . . . . . . . . . . . . 12 7.5. TLS security considerations . . . . . . . . . . . . . . . 13
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13
9. Revision History . . . . . . . . . . . . . . . . . . . . . . 13 9. Revision History . . . . . . . . . . . . . . . . . . . . . . 14
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.1. Normative References . . . . . . . . . . . . . . . . . . 15 10.1. Normative References . . . . . . . . . . . . . . . . . . 16
10.2. Informative References . . . . . . . . . . . . . . . . . 16 10.2. Informative References . . . . . . . . . . . . . . . . . 16
Appendix A. Notes on implementing base64url encoding without Appendix A. Notes on implementing base64url encoding without
padding . . . . . . . . . . . . . . . . . . . . . . 16 padding . . . . . . . . . . . . . . . . . . . . . . 17
Appendix B. Example for the S256 code_challenge_method . . . . . 16 Appendix B. Example for the S256 code_challenge_method . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction 1. Introduction
OAuth 2.0 [RFC6749] public clients are susceptible to the OAuth 2.0 [RFC6749] public clients are susceptible to the
authorization "code" interception attack. authorization "code" interception attack.
The attacker thereby intercepts the authorization code returned from The attacker thereby intercepts the authorization code returned from
the authorization endpoint within communication path not protected by the authorization endpoint within communication path not protected by
TLS, such as inter-app communication within the operating system of TLS, such as inter-app communication within the operating system of
skipping to change at page 4, line 12 skipping to change at page 4, line 12
client device and registers a custom URI scheme that is also used client device and registers a custom URI scheme that is also used
by another application. by another application.
The operating systems must allow a custom URI schemes to be The operating systems must allow a custom URI schemes to be
registered by multiple applications. registered by multiple applications.
2) The OAuth 2.0 authorization code grant is used. 2) The OAuth 2.0 authorization code grant is used.
3) The attacker has access to the OAuth 2.0 [RFC6749] client_id and 3) The attacker has access to the OAuth 2.0 [RFC6749] client_id and
client_secret(if provisioned). All OAuth 2.0 native app client- client_secret(if provisioned). All OAuth 2.0 native app client-
instances use the same client_id. Secrets provisioned in client instances use the same client_id. Secrets provisioned in client
binary applications cannot be considered confidential. binary applications cannot be considered confidential.
4) The attacker (via the installed app) is able to observe responses 4a) The attacker (via the installed app) is able to observe only the
from the authorization endpoint. As a more sophisticated attack responses from the authorization endpoint. The plain
scenario the attacker is also able to observe requests (in code_challenge_method mitigates only this attack.
addition to responses) to the authorization endpoint. The 4b) A more sophisticated attack scenario allows the attacker to
attacker is, however, not able to act as a man-in-the-middle. observe requests (in addition to responses) to the authorization
endpoint. The attacker is, however, not able to act as a man-in-
the-middle. This has been caused by leaking http log information
in the OS. To mitigate this the S256 code_challenge_method or
cryptographically secure code_challenge_method extension must be
used.
While this is a long list of pre-conditions the described attack has While this is a long list of pre-conditions the described attack has
been observed in the wild and has to be considered in OAuth 2.0 been observed in the wild and has to be considered in OAuth 2.0
deployments. deployments.
While the OAuth 2.0 Threat Model Section 4.4.1 [RFC6819] describes While the OAuth 2.0 Threat Model Section 4.4.1 [RFC6819] describes
mitigation techniques they are, unfortunately, not applicable since mitigation techniques they are, unfortunately, not applicable since
they rely on a per-client instance secret or aper client instance they rely on a per-client instance secret or aper client instance
redirect URI. redirect URI.
To mitigate this attack, this extension utilizes a dynamically To mitigate this attack, this extension utilizes a dynamically
skipping to change at page 7, line 26 skipping to change at page 7, line 26
4.2. Client creates the code challenge 4.2. Client creates the code challenge
The client then creates a code challenge, "code_challenge", derived The client then creates a code challenge, "code_challenge", derived
from the "code_verifier" by using one of the following from the "code_verifier" by using one of the following
transformations on the "code_verifier": transformations on the "code_verifier":
plain "code_challenge" = "code_verifier" plain "code_challenge" = "code_verifier"
S256 "code_challenge" = BASE64URL- S256 "code_challenge" = BASE64URL-
ENCODE(SHA256(ASCII("code_verifier"))) ENCODE(SHA256(ASCII("code_verifier")))
It is RECOMMENDED to use the S256 transformation when possible. Clients SHOULD use the S256 transformation. The plain transformation
is for compatibility with existing deployments and for constrained
environments that can't use the S256 transformation.
ABNF for "code_challenge" is as follows. ABNF for "code_challenge" is as follows.
code-challenge = 43*128unreserved code-challenge = 43*128unreserved
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
ALPHA = %x41-5A / %x61-7A ALPHA = %x41-5A / %x61-7A
DIGIT = %x30-39 DIGIT = %x30-39
4.3. Client sends the code challenge with the authorization request 4.3. Client sends the code challenge with the authorization request
The client sends the code challenge as part of the OAuth 2.0 The client sends the code challenge as part of the OAuth 2.0
Authorization Request (Section 4.1.1 of [RFC6749].) using the Authorization Request (Section 4.1.1 of [RFC6749].) using the
following additional parameters: following additional parameters:
code_challenge REQUIRED. Code challenge. code_challenge REQUIRED. Code challenge.
code_challenge_method OPTIONAL, defaults to "plain". Code verifier code_challenge_method OPTIONAL, defaults to "plain" if not present
transformation method, "S256" or "plain". in the request. Code verifier transformation method, "S256" or
"plain".
4.4. Server returns the code 4.4. Server returns the code
When the server issues the "code" in the Authorization Response, it When the server issues the "code" in the Authorization Response, it
MUST associate the "code_challenge" and "code_challenge_method" MUST associate the "code_challenge" and "code_challenge_method"
values with the "code" so it can be verified later. values with the "code" so it can be verified later.
Typically, the "code_challenge" and "code_challenge_method" values Typically, the "code_challenge" and "code_challenge_method" values
are stored in encrypted form in the "code" itself, but could are stored in encrypted form in the "code" itself, but could
alternatively be stored on the server, associated with the code. The alternatively be stored on the server, associated with the code. The
skipping to change at page 8, line 44 skipping to change at page 8, line 50
4.5. Client sends the code and the secret to the token endpoint 4.5. Client sends the code and the secret to the token endpoint
Upon receipt of the "code", the client sends the Access Token Request Upon receipt of the "code", the client sends the Access Token Request
to the token endpoint. In addition to the parameters defined in the to the token endpoint. In addition to the parameters defined in the
OAuth 2.0 Access Token Request (Section 4.1.3 of [RFC6749]), it sends OAuth 2.0 Access Token Request (Section 4.1.3 of [RFC6749]), it sends
the following parameter: the following parameter:
code_verifier REQUIRED. Code verifier code_verifier REQUIRED. Code verifier
The code_challenge_method is bound to the code when the code is
issued. That is the method that the token endpoint MUST use to
verify the code_verifier.
4.6. Server verifies code_verifier before returning the tokens 4.6. Server verifies code_verifier before returning the tokens
Upon receipt of the request at the Access Token endpoint, the server Upon receipt of the request at the Access Token endpoint, the server
verifies it by calculating the code challenge from received verifies it by calculating the code challenge from received
"code_verifier" and comparing it with the previously associated "code_verifier" and comparing it with the previously associated
"code_challenge", after first transforming it according to the "code_challenge", after first transforming it according to the
"code_challenge_method" method specified by the client. "code_challenge_method" method specified by the client.
If the "code_challenge_method" from Section 4.2 was "S256", the If the "code_challenge_method" from Section 4.2 was "S256", the
received "code_verifier" is hashed by SHA-256, then base64url received "code_verifier" is hashed by SHA-256, then base64url
skipping to change at page 9, line 45 skipping to change at page 10, line 4
6. IANA Considerations 6. IANA Considerations
This specification makes a registration request as follows: This specification makes a registration request as follows:
6.1. OAuth Parameters Registry 6.1. OAuth Parameters Registry
This specification registers the following parameters in the IANA This specification registers the following parameters in the IANA
OAuth Parameters registry defined in OAuth 2.0 [RFC6749]. OAuth Parameters registry defined in OAuth 2.0 [RFC6749].
o Parameter name: code_verifier o Parameter name: code_verifier
o Parameter usage location: Access Token Request o Parameter usage location: token request
o Change controller: IESG o Change controller: IESG
o Specification document(s): this document o Specification document(s): this document
o Parameter name: code_challenge o Parameter name: code_challenge
o Parameter usage location: Authorization Request o Parameter usage location: authorization request
o Change controller: IESG o Change controller: IESG
o Specification document(s): this document o Specification document(s): this document
o Parameter name: code_challenge_method o Parameter name: code_challenge_method
o Parameter usage location: Authorization Request o Parameter usage location: authorization request
o Change controller: IESG o Change controller: IESG
o Specification document(s): this document o Specification document(s): this document
6.2. PKCE Code Challenge Method Registry 6.2. PKCE Code Challenge Method Registry
This specification establishes the PKCE Code Challenge Method This specification establishes the PKCE Code Challenge Method
registry. registry. The new registry should be a sub-registry of OAuth
Parameters registry.
Additional code_challenge_method types for use with the authorization Additional code_challenge_method types for use with the authorization
endpoint are registered with a Specification Required ([RFC5226]) endpoint are registered with a Specification Required ([RFC5226])
after a two-week review period on the oauth-ext-review@ietf.org after a two-week review period on the oauth-ext-review@ietf.org
mailing list, on the advice of one or more Designated Experts. mailing list, on the advice of one or more Designated Experts.
However, to allow for the allocation of values prior to publication, However, to allow for the allocation of values prior to publication,
the Designated Expert(s) may approve registration once they are the Designated Expert(s) may approve registration once they are
satisfied that such a specification will be published. satisfied that such a specification will be published.
Registration requests must be sent to the oauth-ext-review@ietf.org Registration requests must be sent to the oauth-ext-review@ietf.org
skipping to change at page 11, line 42 skipping to change at page 12, line 8
The client SHOULD create a code_verifier with a minimum of 256bits of The client SHOULD create a code_verifier with a minimum of 256bits of
entropy. This can be done by having a suitable random number entropy. This can be done by having a suitable random number
generator create a 32-octet sequence. The Octet sequence can then be generator create a 32-octet sequence. The Octet sequence can then be
base64url encoded to produce a 43-octet URL safe string to use as a base64url encoded to produce a 43-octet URL safe string to use as a
code_challenge that has the required entropy. code_challenge that has the required entropy.
7.2. Protection against eavesdroppers 7.2. Protection against eavesdroppers
Clients MUST NOT try down grading the algorithm after trying "S256" Clients MUST NOT try down grading the algorithm after trying "S256"
method. If the server is PKCE compliant, then "S256" method works. method. If the server is PKCE compliant, then "S256" method will
If the server does not support PKCE, it does not generate error. work. If the server does not support PKCE, it will not generate an
Only the time that the server returns that it does not support "S256" error. The only time that a server will return that it does not
is there is a MITM trying the algorithm downgrade attack. support "S256" is if there is a MITM trying the algorithm downgrade
attack.
"S256" method protects against eavesdroppers observing or "S256" method protects against eavesdroppers observing or
intercepting the "code_challenge". If the "plain" method is used, intercepting the "code_challenge". If the "plain" method is used,
there is a chance that it will be observed by the attacker on the there is a chance that "code_challenge" will be observed by the
device. The use of "S256" protects against it. attacker on the device, or in the http request. The use of "S256"
protects against disclosure of "code_verifier" value to an attacker.
If "code_challenge" is to be returned inside authorization "code" to The "S256" code_challenge_method or other cryptographically secure
achieve a stateless server, it has to be encrypted in such a manner code_challenge_method extension SHOULD be used. The plain
that only the server can decrypt and extract it. code_challenge_method relies on the operating system and transport
security not to disclose the request to an attacker.
If the code_challenge_method is plain, and the "code_challenge" is to
be returned inside authorization "code" to achieve a stateless
server, it MUST be encrypted in such a manner that only the server
can decrypt and extract it.
7.3. Salting the code_challenge 7.3. Salting the code_challenge
In order to reduce implementation complexity Salting is not used in In order to reduce implementation complexity Salting is not used in
the production of the code_challenge, as the code_verifier contains the production of the code_challenge, as the code_verifier contains
sufficient entropy to prevent brute force attacks. Concatenating a sufficient entropy to prevent brute force attacks. Concatenating a
publicly known value to a code_verifier (containing 256 bits of publicly known value to a code_verifier (containing 256 bits of
entropy) and then hashing it with SHA256 to produce a code_challenge entropy) and then hashing it with SHA256 to produce a code_challenge
would not increase the number of attempts necessary to brute force a would not increase the number of attempts necessary to brute force a
valid value for code_verifier. valid value for code_verifier.
skipping to change at page 13, line 32 skipping to change at page 14, line 7
Prateek Mishra, Oracle Prateek Mishra, Oracle
Ryo Ito, mixi Ryo Ito, mixi
Scott Tomilson, Ping Identity Scott Tomilson, Ping Identity
Sergey Beryozkin Sergey Beryozkin
Takamichi Saito Takamichi Saito
Torsten Lodderstedt, Deutsche Telekom Torsten Lodderstedt, Deutsche Telekom
William Denniss, Google William Denniss, Google
9. Revision History 9. Revision History
-13
o Fix the parameter usage locations for the OAuth Parameters
Registry per Hannes response.
o Clarify for IANA that the new registry is a sub-registry of OAuth
Parameters registry
o aded text on why the code_challenge_method is not sent to the
token endpoint.
-12 -12
o clarify that the client secret we are talking about in the o clarify that the client secret we are talking about in the
Introduction is a OAuth 2 client_secret. Introduction is a OAuth 2 client_secret.
o Update salting security consideration based on Ben's feedback o Update salting security consideration based on Ben's feedback
-11 -11
o add spanx for plain in sec 4.4 RE Kathleen's comment o add spanx for plain in sec 4.4 RE Kathleen's comment
o Add security consideration on TLS and reference BCP195 o Add security consideration on TLS and reference BCP195
o Update to make clearer that plain can only be used for backwards
compatibility and constrained environments
-10 -10
o re #33 specify lower limit to code_verifier in prose o re #33 specify lower limit to code_verifier in prose
o remove base64url decode from draft, all steps now use encode only o remove base64url decode from draft, all steps now use encode only
o Expanded MTI o Expanded MTI
o re #33 change length of 32 octet base64url encoded string back to o re #33 change length of 32 octet base64url encoded string back to
43 octets 43 octets
-09 -09
 End of changes. 23 change blocks. 
36 lines changed or deleted 69 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/