idnits 2.17.1 draft-sakimura-oauth-tcse-01.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 (July 30, 2013) is 3913 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: 'RFC4627' is defined on line 253, but no explicit reference was found in the text == Unused Reference: 'RFC6570' is defined on line 256, but no explicit reference was found in the text == Unused Reference: 'RFC4949' is defined on line 268, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 1 error (**), 0 flaws (~~), 4 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: January 31, 2014 Ping Identity 6 N. Agarwal 7 Google 8 July 30, 2013 10 OAuth Transient Client Secret Extension for Public Clients 11 draft-sakimura-oauth-tcse-01 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 January 31, 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. transient client secret . . . . . . . . . . . . . . . . . 3 62 2.2. transient client secret hash . . . . . . . . . . . . . . 3 63 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 3.1. Client checks the server support . . . . . . . . . . . . 3 65 3.2. Client creates a transient client secret . . . . . . . . 3 66 3.3. Client sends the left hash with the authorization request 3 67 3.4. Server returns the code . . . . . . . . . . . . . . . . . 4 68 3.5. Client sends the code and the secret to the token 69 endpoint . . . . . . . . . . . . . . . . . . . . . . . . 4 70 3.6. Server verifies tcs before returning the tokens . . . . . 4 71 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 72 4.1. OAuth Parameters Registry . . . . . . . . . . . . . . . . 4 73 5. Security Considerations . . . . . . . . . . . . . . . . . . . 5 74 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 75 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 76 7.1. Normative References . . . . . . . . . . . . . . . . . . 6 77 7.2. Informative References . . . . . . . . . . . . . . . . . 6 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 80 1. Introduction 82 Public clients in OAuth 2.0 [RFC6749] is suseptible to the "code" 83 interception attack. The "code" interception attack is an attack 84 that a malicious client intercepts the "code" returned from the 85 authorization endpoint and uses it to obtain the access token. This 86 is possible on a public client as there is no client secret 87 associated for it to be sent to the token endpoint. This is 88 especially true on some smartphone platform in which the "code" is 89 returned to a redirect URI with a custom scheme as there can be 90 multiple apps that can register the same scheme. 92 To mitigate this attack, this extension utilizes dynamically created 93 client secret called transient client secret whose left hash is sent 94 as a new authorization request parameter. The "code" obtained is 95 then sent to the token endpoint with the transient client secret and 96 the server compairs it with the previously received left hash of it 97 so that it can perfom the proof of posession by the client. 99 2. Terminology 101 In addition to the terms defined in OAuth 2.0 [RFC6749], this 102 specification defines the following terms. 104 2.1. transient client secret 106 a cryptographically random string with big enough entropy that is 107 used to correlate the authorization request to the token request 109 2.2. transient client secret hash 111 base64url encoding of the left most 128bit of SHA256 hash of 112 transient client secret 114 3. Protocol 116 3.1. Client checks the server support 118 Before starting the authorization process, the client MUST make sure 119 that the server supports this specification. It may be obtained out- 120 of-band or through some other mechanisms such as the discovery 121 document in OpenID Connect Discovery [OpenID.Discovery]. The exact 122 mechanism on how the client obtains this information is out of scope 123 of this specification. 125 The client that wishes to use this specification MUST stop proceeding 126 if the server does not support this extension. 128 3.2. Client creates a transient client secret 130 The client then creates a transient client secret, "tcs", in the 131 following manner. 133 tcs = high entropy cryptographic random string 135 NOTE: transient client secret MUST have high enough entropy to make 136 it inpractical to guess the value. 138 3.3. Client sends the left hash with the authorization request 139 Then, the client calculates a transient client secret hash, "tcsh", 140 the left hash of the "tcs" as follows where L is a function that 141 calcualtes the base64url encoded left-most 128 bits of the binary 142 input, and H is a SHA256 function. 144 tcsh = L (H (tcs)) 146 The client sends the transient client secret hash with the following 147 parameter with the OAuth 2.0 [RFC6749] Authorization Request: 149 tcsh REQUIRED. transient client secret hash 151 3.4. Server returns the code 153 When the server issues a "code", it MUST associate the "tcsh" value 154 with the "code" so that it can be used later. 156 Typically, the "tcsh" value is stored in encrypted form in the 157 "code", but it could as well be just stored in the server in 158 association with the code. The server MUST NOT include the "tcsh" 159 value in the form that any entity but itself can extract it. 161 3.5. Client sends the code and the secret to the token endpoint 163 Upon receipt of the "code", the client sends the request to the token 164 endpoint. In addition to the parameters defined in OAuth 2.0 165 [RFC6749], it sends the following parameter: 167 tcs REQUIRED. transient client secret 169 3.6. Server verifies tcs before returning the tokens 171 Upon receipt of the request at the token endpoint, the server 172 verifies it by calculating the transient client secret hash from 173 "tcs" value and comparing it with the previously associated "tcsh". 174 If they are equal, then the successful response SHOULD be returned. 175 If the values are not equal, an error response indicating 176 "invalid_grant" as described in section 5.2 of OAuth 2.0 [RFC6749] 177 SHOULD be returned. 179 4. IANA Considerations 181 This specification makes a registration request as follows: 183 4.1. OAuth Parameters Registry 185 This specification registers the following parameters in the IANA 186 OAuth Parameters registry defined in OAuth 2.0 [RFC6749]. 188 o Parameter name: tcs 190 o Parameter usage location: Access Token Request 192 o Change controller: OpenID Foundation Artifact Binding Working 193 Group - openid-specs-ab@lists.openid.net 195 o Specification document(s): this document 197 o Related information: None 199 o Parameter name: tcsh 201 o Parameter usage location: Authorization Request 203 o Change controller: OpenID Foundation Artifact Binding Working 204 Group - openid-specs-ab@lists.openid.net 206 o Specification document(s): this document 208 o Related information: None 210 5. Security Considerations 212 The security model relies on the fact that the transient client 213 secret is not being disclosed in the front channel. It is vitally 214 important to adhear to this principle. As such, the transient client 215 secret has to be created in such a manner that it is 216 cryptographically random and has high entropy that it is not 217 practical for the attacker to guess, and if it is to be returned 218 inside "code", it has to be encrypted in such a manner that only the 219 server can decrypt and extract it. 221 6. Acknowledgements 223 The initial draft of this specification was created by the OpenID AB/ 224 Connect Working Group of the OpenID Foundation, by most notably of 225 the following people: 227 o Naveen Agarwal, Google 229 o Dirk Belfanz, Google 231 o John Bradley, Ping Identity 233 o Brian Campbell, Ping Identity 235 o Ryo Ito, mixi 236 o Michael B. Jones, Microsoft 238 o Torsten Lodderstadt, Deutsche Telekom 240 o Breno de Madeiros, Google 242 o Anthony Nadalin, Microsoft 244 o Nat Sakimura, Nomura Research Institute 246 7. References 248 7.1. Normative References 250 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 251 Requirement Levels", BCP 14, RFC 2119, March 1997. 253 [RFC4627] Crockford, D., "The application/json Media Type for 254 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 256 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 257 and D. Orchard, "URI Template", RFC 6570, March 2012. 259 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 260 6749, October 2012. 262 7.2. Informative References 264 [OpenID.Discovery] 265 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 266 Connect Discovery 1.0", May 2013. 268 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 269 4949, August 2007. 271 Authors' Addresses 273 Nat Sakimura (editor) 274 Nomura Research Institute 276 Email: sakimura@gmail.com 278 John Bradley 279 Ping Identity 281 Email: jbradley@pingidentity.com 282 Naveen Agarwal 283 Google 285 Email: naa@google.com