idnits 2.17.1 draft-ietf-oauth-spop-00.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 (August 25, 2014) is 3532 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 324, 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: February 26, 2015 Independent 6 N. Agarwal 7 Google 8 August 25, 2014 10 Symmetric Proof of Possession for the OAuth Authorization Code Grant 11 draft-ietf-oauth-spop-00 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 February 26, 2015. 42 Copyright Notice 44 Copyright (c) 2014 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 . . . . . . . . . . . . 3 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 . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . . . . . . . . . . . . 7 80 8.1. Normative References . . . . . . . . . . . . . . . . . . 7 81 8.2. Informative References . . . . . . . . . . . . . . . . . 7 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 84 1. Introduction 86 Public clients in OAuth 2.0 [RFC6749] is susceptible to the "code" 87 interception attack. The "code" interception attack is an attack 88 that a malicious client intercepts the "code" returned from the 89 authorization endpoint and uses it to obtain the access token. This 90 is possible on a public client as there is no client secret 91 associated for it to be sent to the token endpoint. This is 92 especially true on some smartphone platform in which the "code" is 93 returned to a redirect URI with a custom scheme as there can be 94 multiple apps that can register the same scheme.Under this scenario, 95 the mitigation strategy stated in section 4.4.1 of [RFC6819] does not 96 work as they rely on per-client instance secret or per client 97 instance redirect uri. 99 To mitigate this attack, this extension utilizes dynamically created 100 cryptographically random key called 'code verifier'. The code 101 verifier is created for every authorization request and its 102 transformed value called code challenge is sent to the authorization 103 server to obtain the authorization code. The "code" obtained is then 104 sent to the token endpoint with the code verifier and the server 105 compares it with the previously received request code so that it can 106 perform the proof of possession of the code verifier by the client. 107 This works as the mitigation since the attacker would not know the 108 one-time key. 110 2. Terminology 112 In addition to the terms defined in OAuth 2.0 [RFC6749], this 113 specification defines the following terms. 115 2.1. code verifier 117 cryptographically random string with big enough entropy that is used 118 to correlate the authorization request to the token request 120 2.2. code challenge 122 either the code verifier itself or some transformation of it that is 123 sent from the client to the server in the authorization request 125 NOTE 1: The client and the server MAY use mutually agreed pre- 126 negotiated algorithm such as base64url encoding of the left most 127 128bit of SHA256 hash. 129 NOTE 2: If no algorithm has been negotiated, it is treated as the 130 code verifier itself. 132 3. Protocol 134 3.1. Client checks the server support 136 Before starting the authorization process, the client MUST make sure 137 that the server supports this specification. It may be obtained out- 138 of-band or through some other mechanisms such as the discovery 139 document in OpenID Connect Discovery [OpenID.Discovery]. The exact 140 mechanism on how the client obtains this information is out of scope 141 of this specification. 143 The client that wishes to use this specification MUST stop proceeding 144 if the server does not support this extension. 146 3.2. (optional) Client registers its desired code challenge algorithm 148 In this specification, the client sends the transformation of the 149 code verifier to the authorization server in the front channel. The 150 default transformation is not doing transformation at all. If the 151 the server supports, the client MAY register its desired 152 transformation algorithm to the server. If the algorithm is 153 registered, the server MUST reject any request that does not conform 154 to the algorithm. 156 How does this client registers the algorithm is out of scope for this 157 specification. 159 Also, this specification does not define any transformation other 160 than the default transformation. 162 3.3. Client creates a code verifier 164 The client then creates a code verifier, "code_verifier", in the 165 following manner. 167 code_verifier = high entropy cryptographic random string of length 168 less than 128 bytes 170 NOTE: code verifier MUST have high enough entropy to make it 171 inpractical to guess the value. 173 3.4. Client sends the code challenge with the authorization request 175 Then, the client creates a code challenge, "code_challenge", by 176 applying the pre-negotiated algorithm between the client and the 177 server. The default behaviour is no transformation, i.e., 178 "code_challenge" == "code_verifier". The authorization server MUST 179 support this 'no transformation' algorithm. 181 The client sends the code challenge with the following parameter with 182 the OAuth 2.0 [RFC6749] Authorization Request: 184 code_challenge REQUIRED. code challenge. 186 3.5. Server returns the code 188 When the server issues a "code", it MUST associate the 189 "code_challenge" value with the "code" so that it can be used later. 191 Typically, the "code_challenge" value is stored in encrypted form in 192 the "code", but it could as well be just stored in the server in 193 association with the code. The server MUST NOT include the 194 "code_challenge" value in the form that any entity but itself can 195 extract it. 197 3.6. Client sends the code and the secret to the token endpoint 199 Upon receipt of the "code", the client sends the request to the token 200 endpoint. In addition to the parameters defined in OAuth 2.0 201 [RFC6749], it sends the following parameter: 203 code_verifier REQUIRED. code verifier 205 3.7. Server verifies code_verifier before returning the tokens 207 Upon receipt of the request at the token endpoint, the server 208 verifies it by calculating the code challenge from "code_verifier" 209 value and comparing it with the previously associated 210 "code_challenge". If they are equal, then the successful response 211 SHOULD be returned. If the values are not equal, an error response 212 indicating "invalid_grant" as described in section 5.2 of OAuth 2.0 213 [RFC6749] SHOULD be returned. 215 4. IANA Considerations 217 This specification makes a registration request as follows: 219 4.1. OAuth Parameters Registry 221 This specification registers the following parameters in the IANA 222 OAuth Parameters registry defined in OAuth 2.0 [RFC6749]. 224 o Parameter name: code_verifier 226 o Parameter usage location: Access Token Request 228 o Change controller: OpenID Foundation Artifact Binding Working 229 Group - openid-specs-ab@lists.openid.net 231 o Specification document(s): this document 233 o Related information: None 235 o Parameter name: code_challenge 237 o Parameter usage location: Authorization Request 238 o Change controller: OpenID Foundation Artifact Binding Working 239 Group - openid-specs-ab@lists.openid.net 241 o Specification document(s): this document 243 o Related information: None 245 5. Security Considerations 247 The security model relies on the fact that the code verifier is not 248 learned or guessed by the attacker. It is vitally important to 249 adhere to this principle. As such, the code verifier has to be 250 created in such a manner that it is cryptographically random and has 251 high entropy that it is not practical for the attacker to guess, and 252 if it is to be returned inside "code", it has to be encrypted in such 253 a manner that only the server can decrypt and extract it. 255 If the no transformation algorithm, which is the default algorithm, 256 is used, the client MUST make sure that the request channel is 257 adequately protected. On a platform that it is not possible, the 258 client and the server SHOULD utilize a transformation algorithm that 259 makes it reasonably hard to recalculate the code verifier from the 260 code challenge. 262 All the OAuth security analysis presented in [RFC6819] applies so 263 readers SHOULD carefully follow it. 265 6. Acknowledgements 267 The initial draft of this specification was created by the OpenID AB/ 268 Connect Working Group of the OpenID Foundation, by most notably of 269 the following people: 271 o Naveen Agarwal, Google 273 o Dirk Balfanz, Google 275 o Sergey Beryozkin 277 o John Bradley, Ping Identity 279 o Brian Campbell, Ping Identity 281 o Phil Hunt, Oracle 283 o Ryo Ito, mixi 285 o Michael B. Jones, Microsoft 286 o Torsten Lodderstedt, Deutsche Telekom 288 o Breno de Madeiros, Google 290 o Prateek Mishra, Oracle 292 o Anthony Nadalin, Microsoft 294 o Axel Nenker, Deutsche Telekom 296 o Nat Sakimura, Nomura Research Institute 298 7. Revision History 300 -00 302 o Initial version. 304 8. References 306 8.1. Normative References 308 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 309 Requirement Levels", BCP 14, RFC 2119, March 1997. 311 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 312 6749, October 2012. 314 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 315 Threat Model and Security Considerations", RFC 6819, 316 January 2013. 318 8.2. Informative References 320 [OpenID.Discovery] 321 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 322 Connect Discovery 1.0", February 2014. 324 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 325 4949, August 2007. 327 Authors' Addresses 328 Nat Sakimura (editor) 329 Nomura Research Institute 330 1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg. 331 Chiyoda-ku, Tokyo 100-0005 332 Japan 334 Phone: +81-3-5533-2111 335 Email: n-sakimura@nri.co.jp 336 URI: http://nat.sakimura.org/ 338 John Bradley 339 Independent 340 Casilla 177, Sucursal Talagante 341 Talagante, RM 342 Chile 344 Phone: +44 20 8133 3718 345 Email: ve7jtb@ve7jtb.com 346 URI: http://www.thread-safe.com/ 348 Naveen Agarwal 349 Google 351 Email: naa@google.com