idnits 2.17.1 draft-sakimura-oauth-tcse-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 19, 2013) is 3842 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC4949' is defined on line 341, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 6819 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group N. Sakimura, Ed. 3 Internet-Draft Nomura Research Institute 4 Intended status: Standards Track J. Bradley 5 Expires: April 22, 2014 Ping Identity 6 N. Agarwal 7 Google 8 October 19, 2013 10 OAuth Symmetric Proof of Posession for Code Extension 11 draft-sakimura-oauth-tcse-02 13 Abstract 15 The OAuth 2.0 public client utilizing authorization code grant is 16 susceptible to the code interception attack. This specification 17 describe a mechanism that acts as a control against this threat. 19 Requirements Language 21 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 22 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 23 document are to be interpreted as described in RFC 2119 [RFC2119]. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on April 22, 2014. 42 Copyright Notice 44 Copyright (c) 2013 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2.1. code verifier . . . . . . . . . . . . . . . . . . . . . . 3 62 2.2. code challenge . . . . . . . . . . . . . . . . . . . . . 3 63 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 3.1. Client checks the server support . . . . . . . . . . . . 4 65 3.2. (optional) Client registers its desired code challenge 66 algorithm . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3.3. Client creates a code verifier . . . . . . . . . . . . . 4 68 3.4. Client sends the code challenge with the authorization 69 request . . . . . . . . . . . . . . . . . . . . . . . . . 4 70 3.5. Server returns the code . . . . . . . . . . . . . . . . . 5 71 3.6. Client sends the code and the secret to the token 72 endpoint . . . . . . . . . . . . . . . . . . . . . . . . 5 73 3.7. Server verifies code_verifier before returning the tokens 5 74 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 75 4.1. OAuth Parameters Registry . . . . . . . . . . . . . . . . 5 76 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 77 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 78 7. Revision History . . . . . . . . . . . . . . . . . . . . . . 7 79 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 80 8.1. Normative References . . . . . . . . . . . . . . . . . . 8 81 8.2. Informative References . . . . . . . . . . . . . . . . . 8 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 84 1. Introduction 85 Public clients in OAuth 2.0 [RFC6749] is suseptible to the "code" 86 interception attack. The "code" interception attack is an attack 87 that a malicious client intercepts the "code" returned from the 88 authorization endpoint and uses it to obtain the access token. This 89 is possible on a public client as there is no client secret 90 associated for it to be sent to the token endpoint. This is 91 especially true on some smartphone platform in which the "code" is 92 returned to a redirect URI with a custom scheme as there can be 93 multiple apps that can register the same scheme.Under this scenario, 94 the mitigation strategy stated in section 4.4.1 of [RFC6819] does not 95 work as they rely on per-client instance secret or per client 96 instance redirect uri. 98 To mitigate this attack, this extension utilizes dynamically created 99 cryptographically random key called 'code verifier'. The code 100 verifier is created for every authorization request and its 101 transformed value called code challenge is sent to the authorization 102 server to obtain the authorization code. The "code" obtained is then 103 sent to the token endpoint with the code verifier and the server 104 compairs it with the previously received reqeust code so that it can 105 perfom the proof of posession of the code verifier by the client. 106 This works as the mitigation since the attacker would not know the 107 one-time key. 109 2. Terminology 111 In addition to the terms defined in OAuth 2.0 [RFC6749], this 112 specification defines the following terms. 114 2.1. code verifier 116 a cryptographically random string with big enough entropy that is 117 used to correlate the authorization request to the token request 119 2.2. code challenge 121 either the code verifier itself or some transformation of it that is 122 sent from the client to the server in the authorization request 124 NOTE 1: The client and the server MAY use mutually agreed pre- 125 negotiated algorithm such as base64url encoding of the left most 126 128bit of SHA256 hash. 128 NOTE 2: If no algorithm has been negotiated, it is treated as the 129 code verifier itself. 131 3. Protocol 132 3.1. Client checks the server support 134 Before starting the authorization process, the client MUST make sure 135 that the server supports this specification. It may be obtained out- 136 of-band or through some other mechanisms such as the discovery 137 document in OpenID Connect Discovery [OpenID.Discovery]. The exact 138 mechanism on how the client obtains this information is out of scope 139 of this specification. 141 The client that wishes to use this specification MUST stop proceeding 142 if the server does not support this extension. 144 3.2. (optional) Client registers its desired code challenge algorithm 146 In this specification, the client sends the transformation of the 147 code verifier to the authorization server in the front channel. The 148 default transformation is not doing transformation at all. If the 149 the server supports, the client MAY register its desired 150 transformation algorithm to the server. If the algorithm is 151 registered, the server MUST reject any request that does not conform 152 to the algorithm. 154 How does this client registers the algorithm is out of scope for this 155 specification. 157 Also, this specification does not define any transformation other 158 than the default transformation. 160 3.3. Client creates a code verifier 162 The client then creates a code verifier, "code_verifier", in the 163 following manner. 165 code_verifier = high entropy cryptographic random string of length 166 less than 128 bytes 168 NOTE: code verifier MUST have high enough entropy to make it 169 inpractical to guess the value. 171 3.4. Client sends the code challenge with the authorization request 173 Then, the client creates a code challenge, "code_challenge", by 174 applying the pre-negotiated algorithm between the client and the 175 server. The default behavior is no transofrmation, i.e., 176 "code_challenge" == "code_verifier". The authorization server MUST 177 support this 'no transformation' algorithm. 179 The client sends the code challenge with the following parameter with 180 the OAuth 2.0 [RFC6749] Authorization Request: 182 code_challenge REQUIRED. code challenge. 184 3.5. Server returns the code 186 When the server issues a "code", it MUST associate the 187 "code_challenge" value with the "code" so that it can be used later. 189 Typically, the "code_challenge" value is stored in encrypted form in 190 the "code", but it could as well be just stored in the server in 191 association with the code. The server MUST NOT include the 192 "code_challenge" value in the form that any entity but itself can 193 extract it. 195 3.6. Client sends the code and the secret to the token endpoint 197 Upon receipt of the "code", the client sends the request to the token 198 endpoint. In addition to the parameters defined in OAuth 2.0 199 [RFC6749], it sends the following parameter: 201 code_verifier REQUIRED. code verifier 203 3.7. Server verifies code_verifier before returning the tokens 205 Upon receipt of the request at the token endpoint, the server 206 verifies it by calculating the code challenge from "code_verifier" 207 value and comparing it with the previously associated 208 "code_challenge". If they are equal, then the successful response 209 SHOULD be returned. If the values are not equal, an error response 210 indicating "invalid_grant" as described in section 5.2 of OAuth 2.0 211 [RFC6749] SHOULD be returned. 213 4. IANA Considerations 215 This specification makes a registration request as follows: 217 4.1. OAuth Parameters Registry 219 This specification registers the following parameters in the IANA 220 OAuth Parameters registry defined in OAuth 2.0 [RFC6749]. 222 o Parameter name: code_verifier 224 o Parameter usage location: Access Token Request 225 o Change controller: OpenID Foundation Artifact Binding Working 226 Group - openid-specs-ab@lists.openid.net 228 o Specification document(s): this document 230 o Related information: None 232 o Parameter name: code_challenge 234 o Parameter usage location: Authorization Request 236 o Change controller: OpenID Foundation Artifact Binding Working 237 Group - openid-specs-ab@lists.openid.net 239 o Specification document(s): this document 241 o Related information: None 243 5. Security Considerations 245 The security model relies on the fact that the code verifier is not 246 learned or guessed by the attacker. It is vitally important to 247 adhear to this principle. As such, the code verifier has to be 248 created in such a manner that it is cryptographically random and has 249 high entropy that it is not practical for the attacker to guess, and 250 if it is to be returned inside "code", it has to be encrypted in such 251 a manner that only the server can decrypt and extract it. 253 If the no transformation algorithm, which is the default algorithm, 254 is used, the client MUST make sure that the request channel is 255 adequately protected. On a platform that it is not possible, the 256 client and the server SHOULD utilize a transformation algorithm that 257 makes it reasonably hard to recalculate the code verifier from the 258 code challenge. 260 All the OAuth security analysis presented in [RFC6819] applies so 261 readers SHOULD carefully follow it. 263 6. Acknowledgements 265 The initial draft of this specification was created by the OpenID AB/ 266 Connect Working Group of the OpenID Foundation, by most notably of 267 the following people: 269 o Naveen Agarwal, Google 271 o Dirk Belfanz, Google 272 o Sergey Beryozkin 274 o John Bradley, Ping Identity 276 o Brian Campbell, Ping Identity 278 o Phill Hunt, Oracle 280 o Ryo Ito, mixi 282 o Michael B. Jones, Microsoft 284 o Torsten Lodderstadt, Deutsche Telekom 286 o Breno de Madeiros, Google 288 o Prateek Mishra, Oracle 290 o Anthony Nadalin, Microsoft 292 o Axel Nenker, Deutsche Telekom 294 o Nat Sakimura, Nomura Research Institute 296 7. Revision History 298 -02 300 o Changed title. 302 o Changed parameter names. 304 o Changed the default transformation algorithm and added crypto 305 agility. 307 o More text in the security consideration. 309 o Now references RFC 6819. 311 o Recorded more contributors. 313 -01 315 o Minor editorial changes. 317 -00 319 o Initial version. 321 8. References 323 8.1. Normative References 325 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 326 Requirement Levels", BCP 14, RFC 2119, March 1997. 328 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 329 6749, October 2012. 331 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 332 Threat Model and Security Considerations", RFC 6819, 333 January 2013. 335 8.2. Informative References 337 [OpenID.Discovery] 338 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 339 Connect Discovery 1.0", May 2013. 341 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 342 4949, August 2007. 344 Authors' Addresses 346 Nat Sakimura (editor) 347 Nomura Research Institute 349 Email: sakimura@gmail.com 350 URI: http://nat.sakimura.org/ 352 John Bradley 353 Ping Identity 355 Email: jbradley@pingidentity.com 357 Naveen Agarwal 358 Google 360 Email: naa@google.com