cid 5668294d9b96d3c992917a0233f63814698f4e184cbb0f84c047732170c18263 · original · open access · via rfc
Title: rfc:7636
Authors:
Venue: rfc
Year: 2015
Canonical: rfc:7636
URL: https://www.rfc-editor.org/rfc/rfc7636.txt
Collector: rfc
OA: true
ABSTRACT
Abstract OAuth 2.0 public clients utilizing the Authorization Code Grant are susceptible to the authorization code interception attack. This specification describes the attack as well as a technique to mitigate against the threat through the use of Proof Key for Code Exchange (PKCE, pronounced "pixy"). Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7636. Copyright Notice Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction ....................................................3 1.1. Protocol Flow ..............................................5 2. Notational Conventions ..........................................6 3. Terminology .....................................................7 3.1. Abbreviations ..............................................7 4. Protocol ........................................................8 4.1. Client Creates a Code Verifier .............................8 4.2. Client Creates the Code Challenge ..........................8 4.3. Client Sends the Code Challenge with the Authorization Request ......................................9 4.4. Server Returns the Code ....................................9 4.4.1. Error Response ......................................9 4.5. Client Sends the Authorization Code and the Code Verifier to the Token Endpoint ............................10 4.6. Server Verifies code_verifier before Returning the Tokens ....................................................10 5. Compatibility ..................................................11 6. IANA Considerations ............................................11 6.1. OAuth Parameters Registry .................................11 6.2. PKCE Code Challenge Method Registry .......................11 6.2.1. Registration Template ..............................12 6.2.2. Initial Registry Contents ..........................13 7. Security Considerations ........................................13 7.1. Entropy of the code_verifier ..............................13 7.2. Protection against Eavesdroppers ..........................13 7.3. Salting the code_challenge ................................14 7.4. OAuth Security Considerations .............................14 7.5. TLS Security Considerations ...............................15 8. References .....................................................15 8.1. Normative References ......................................15 8.2. Informative References ....................................16 Appendix A. Notes on Implementing Base64url Encoding without Padding .............................................17 Appendix B. Example for the S256 code_challenge_method ...........17 Acknowledgements ..................................................19 Authors' Addresses ................................................20 1. Introduction OAuth 2.0 [RFC6749] public clients are susceptible to the authorization code interception attack. In this attack, the attacker intercepts the authorization code returned from the authorization endpoint within a communication path not protected by Transport Layer Security (TLS), such as inter- application communication within the client's operating system. Once the attacker has gained access to the authorization code, it can use it to obtain the access token. Figure 1 shows the attack graphically. In step (1), the native application running on the end device, such as a smartphone, issues an OAuth 2.0 Authorization Request via the browser/operating system. The Redirection Endpoint URI in this case typically uses a custom URI scheme. Step (1) happens through a secure API that cannot be intercepted, though it may potentially be observed in advanced attack scenarios. The request then gets forwarded to the OAuth 2.0 authorization server in step (2). Because OAuth requires the use of TLS, this communication is protected by TLS and cannot be intercepted. The authorization server returns the authorization code in step (3). In step (4), the Authorization Code is returned to the requester via the Redirection Endpoint URI that was provided in step (1). Note that it is possible for a malicious app to register itself as a handler for the custom scheme in addition to the legitimate OAuth 2.0 app. Once it does so, the malicious app is now able to intercept the authorization code in step (4). This allows the attacker to request and obtain an access token in steps (5) and (6), respectively. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ | End Device (e.g., Smartphone) | | | | +-------------+ +----------+ | (6) Access Token +----------+ | |Legitimate | | Malicious|| | | +-------------+ +----------+ | (5) Authorization | | | | ^ ^ | Grant | | | | \ | | | | | | \ (4) | | | | | (1) | \ Authz| | | | | Authz| \ Code | | | Authz | | Request| \ | | | Server | | | \ | | | | | | \ | | | | | v \ | | | | | +----------------------------+ | | | | | | | (3) Authz Code | | | | Operating System/ || | | | | | (2) Authz Request | | | +----------------------------+ | +----------+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ Figure 1: Authorization Code Interception Attack A number of pre-conditions need to hold for this attack to work: 1. The attacker manages to register a malicious application on the client device and registers a custom URI scheme that is also used by another application. The operating systems must allow a custom URI scheme to be registered by multiple applications. 2. The OAuth 2.0 authorization code grant is used. 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-instances use the same "client_id". Secrets provisioned in client binary applications cannot be considered confidential. 4. Either one of the following condition is met: 4a. The attacker (via the installed application) is able to observe only the responses from the authorization endpoint. When "code_challenge_method" value is "plain", only this attack is mitigated. 4b. A more sophisticated attack scenario allows the attacker to 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 was caused by leaking http log information in the OS. To mitigate this, "code_challenge_method" value must be set either to "S256" or a value defined by a cryptographically secure "code_challenge_method" extension. 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 deployments. While the OAuth 2.0 threat model (Section 4.4.1 of [RFC6819]) describes mitigation techniques, they are, unfortunately, not applicable since they rely on a per-client instance secret or a per-client instance redirect URI. To mitigate this attack, this extension utilizes a dynamically created cryptographically random key called "code verifier". A unique code verifier is created for every authorization request, and its transformed value, called "code challenge", is sent to the authorization server to obtain the authorization code. The authorization code obtained is then sent to the token endpoint with the "code verifier", and the server compares it with the previously received request code so that it can perform the proof of possession of the "code verifier" by the client. This works as the mitigation since the attacker would not know this one-time key, since it is sent over TLS and cannot be intercepted. 1.1. Protocol Flow +-------------------+ | Authz Server | +--------+ | +---------------+ | | |--(A)- Authorization Request ----| | | | | + t(code_verifier), t_m | | Authorization | | | | | | Endpoint | | | || | | | | + code_verifier | | Token | | | | | | Endpoint | | | |. [RFC20] Cerf, V., "ASCII format for network interchange", STD 80, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, . [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI 10.17487/RFC5226, May 2008, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)", RFC 6234, DOI 10.17487/RFC6234, May 2011, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", . 8.2. Informative References [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, DOI 10.17487/RFC6819, January 2013, . Appendix A. Notes on Implementing Base64url Encoding without Padding This appendix describes how to implement a base64url-encoding function without padding, based upon the standard base64-encoding function that uses padding. To be concrete, example C# code implementing these functions is shown below. Similar code could be used in other languages. static string base64urlencode(byte [] arg) { string s = Convert.ToBase64String(arg); // Regular base64 encoder s = s.Split('=')[0]; // Remove any trailing '='s s = s.Replace('+', '-'); // 62nd char of encoding s = s.Replace('/', '_'); // 63rd char of encoding return s; } An example correspondence between unencoded and encoded values follows. The octet sequence below encodes into the string below, which when decoded, reproduces the octet sequence. 3 236 255 224 193 A-z_4ME Appendix B. Example for the S256 code_challenge_method The client uses output of a suitable random number generator to create a 32-octet sequence. The octets representing the value in this example (using JSON array notation) are: [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 132, 141, 121] Encoding this octet sequence as base64url provides the value of the code_verifier: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk The code_verifier is then hashed via the SHA256 hash function to produce: [19, 211, 30, 150, 26, 26, 216, 236, 47, 22, 177, 12, 76, 152, 46, 8, 118, 168, 120, 173, 109, 241, 68, 86, 110, 225, 137, 74, 203, 112, 249, 195] Encoding this octet sequence as base64url provides the value of the code_challenge: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM The authorization request includes: code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256 The authorization server then records the code_challenge and code_challenge_method along with the code that is granted to the client. In the request to the token_endpoint, the client includes the code received in the authorization response as well as the additional parameter: code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk The authorization server retrieves the information for the code grant. Based on the recorded code_challenge_method being S256, it then hashes and base64url-encodes the value of code_verifier: BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) The calculated value is then compared with the value of "code_challenge": BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge If the two values are equal, then the authorization server can provide the tokens as long as there are no other errors in the request. If the values are not equal, then the request must be rejected, and an error returned. Acknowledgements The initial draft version of this specification was created by the OpenID AB/Connect Working Group of the OpenID Foundation. This specification is the work of the OAuth Working Group, which includes dozens of active and dedicated participants. In particular, the following individuals contributed ideas, feedback, and wording that shaped and formed the final specification: Anthony Nadalin, Microsoft Axel Nenker, Deutsche Telekom Breno de Medeiros, Google Brian Campbell, Ping Identity Chuck Mortimore, Salesforce Dirk Balfanz, Google Eduardo Gueiros, Jive Communications Hannes Tschonfenig, ARM James Manger, Telstra Justin Richer, MIT Kerberos Josh Mandel, Boston Children's Hospital Lewis Adam, Motorola Solutions Madjid Nakhjiri, Samsung Michael B. Jones, Microsoft Paul Madsen, Ping Identity Phil Hunt, Oracle Prateek Mishra, Oracle Ryo Ito, mixi Scott Tomilson, Ping Identity Sergey Beryozkin Takamichi Saito Torsten Lodderstedt, Deutsche Telekom William Denniss, Google Authors' Addresses Nat Sakimura (editor) Nomura Research Institute 1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg. Chiyoda-ku, Tokyo 100-0005 Japan Phone: +81-3-5533-2111 Email: n-sakimura@nri.co.jp URI: http://nat.sakimura.org/ John Bradley Ping Identity Casilla 177, Sucursal Talagante Talagante, RM Chile Phone: +44 20 8133 3718 Email: ve7jtb@ve7jtb.com URI: http://www.thread-safe.com/ Naveen Agarwal Google 1600 Amphitheatre Parkway Mountain View, CA 94043 United States Phone: +1 650-253-0000 Email: naa@google.com URI: http://google.com/