idnits 2.17.1 draft-sakimura-oauth-tcse-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 (July 29, 2013) is 3923 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 254, but no explicit reference was found in the text == Unused Reference: 'RFC6570' is defined on line 257, but no explicit reference was found in the text == Unused Reference: 'RFC4949' is defined on line 269, 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 30, 2014 Ping Identity 6 N. Agarwal 7 Google 8 July 29, 2013 10 OAuth Transient Client Secret Extension for Public Clients 11 draft-sakimura-oauth-tcse-00 13 Abstract 15 The OAuth 2.0 public client utilizing code flow is susceptible to the 16 code interception attack. This specification describe a mechanism 17 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 30, 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 salted left hash with the authorization 67 request . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 3.4. Server returns the code . . . . . . . . . . . . . . . . . 4 69 3.5. Client sends the code and the secret to the token 70 endpoint . . . . . . . . . . . . . . . . . . . . . . . . 4 71 3.6. Server verifies tcs before returning the tokens . . . . . 4 72 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 73 4.1. OAuth Parameters Registry . . . . . . . . . . . . . . . . 4 74 5. Security Considerations . . . . . . . . . . . . . . . . . . . 5 75 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 76 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 77 7.1. Normative References . . . . . . . . . . . . . . . . . . 6 78 7.2. Informative References . . . . . . . . . . . . . . . . . 6 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 81 1. Introduction 83 Public clients in OAuth 2.0 [RFC6749] is suseptible to the "code" 84 interception attack. The "code" interception attack is an attack 85 that a malicious client intercepts the "code" returned from the 86 authorization endpoint and uses it to obtain the access token. This 87 is possible on a public client as there is no client secret 88 associated for it to be sent to the token endpoint. This is 89 especially true on some smartphone platform in which the "code" is 90 returned to a redirect URI with a custom scheme as there can be 91 multiple apps that can register the same scheme. 93 To mitigate this attack, this extension utilizes dynamically created 94 client secret called transient client secret whose left hash is sent 95 as a new authorization request parameter. The "code" obtained is 96 then sent to the token endpoint with the transient client secret and 97 the server compairs it with the previously received left hash of it 98 so that it can perfom the proof of posession by the client. 100 2. Terminology 102 In addition to the terms defined in OAuth 2.0 [RFC6749], this 103 specification defines the following terms. 105 2.1. transient client secret 107 a cryptographically random string with big enough entropy that is 108 used to correlate the authorization request to the token request 110 2.2. transient client secret hash 112 base64url encoding of the left most 128bit of SHA256 hash of 113 transient client secret 115 3. Protocol 117 3.1. Client checks the server support 119 Before starting the authorization process, the client MUST make sure 120 that the server supports this specification. It may be obtained out- 121 of-band or some other mechanisms such as the discovery document in 122 OpenID Connect Discovery [OpenID.Discovery]. The exact mechanism on 123 how the client obtains this information is out of scope of this 124 specification. 126 The client that wishes to use this specification MUST stop proceeding 127 if the server does not support this extension. 129 3.2. Client creates a transient client secret 131 The client then creates a transient client secret, "tcs", in the 132 following manner. 134 tcs = high entropy cryptographic random string 136 NOTE: transient client secret MUST have high enough entropy to make 137 it inpractical to guess the value. 139 3.3. Client sends the salted left hash with the authorization request 141 Then, the client calculates a transient client secret hash, "tcsh", 142 the salted left hash of the "tcs" as follows where L is a function 143 that calcualtes the base64url encoded left-most 128 bits of the 144 binary input, and H is a SHA256 function. 146 tcsh = L (H ( tcs) ) 148 The client sends the transient client secret hash with the following 149 parameter with the OAuth 2.0 [RFC6749] Authorization Request: 151 tcsh REQUIRED. transient client secret hash 153 3.4. Server returns the code 155 When the server issues "code", it MUST associate the "tcsh" value 156 with the "code" so that it can be used later. 158 Typically, the "tcsh" value is stored in encrypted form in the 159 "code", but it could as well be just stored in the server in 160 association with the code. The server MUST NOT include the "tcsh" 161 value in the form that any entity but itself can extract it. 163 3.5. Client sends the code and the secret to the token endpoint 165 Unpon receipt of the "code", the client sends the request to the 166 token endpoint. In addition to the parameters defined in OAuth 2.0 167 [RFC6749], it sends the following parameter: 169 tcs REQUIRED. transient client secret 171 3.6. Server verifies tcs before returning the tokens 173 Upon receipt of the request at the token endpoint, the server 174 verifies it by calculating the transient client secret hash from 175 "tcs" value and "tcsh" and comparing it with the previously 176 associated "tcsh". If they are equal, then the successful response 177 SHOULD be returned. If the values are not equal, an error response 178 indicating "invalid_grant" as described in section 5.2 of OAuth 2.0 179 [RFC6749] SHOULD be returned. 181 4. IANA Considerations 183 This specification makes a registration request as follows: 185 4.1. OAuth Parameters Registry 187 This specification registers the following parameters in the IANA 188 OAuth Parameters registry defined in OAuth 2.0 [RFC6749]. 190 o Parameter name: tcs 192 o Parameter usage location: Access Token Request 193 o Change controller: OpenID Foundation Artifact Binding Working 194 Group - openid-specs-ab@lists.openid.net 196 o Specification document(s): this document 198 o Related information: None 200 o Parameter name: tcsh 202 o Parameter usage location: Authorization Request 204 o Change controller: OpenID Foundation Artifact Binding Working 205 Group - openid-specs-ab@lists.openid.net 207 o Specification document(s): this document 209 o Related information: None 211 5. Security Considerations 213 The security model relies on the fact that the transient client 214 secret is not being disclosed in the front channel. It is vitally 215 important to adhear to this principle. As such, the transient client 216 secret has to be created in such a manner that it is 217 cryptographically random and has high entropy that it is not 218 practical for the attacker to guess, and if it is to be returned 219 inside "code", it has to be encrypted in such a manner that only the 220 server can decrypt and extract it. 222 6. Acknowledgements 224 The initial draft of this specification was created by the OpenID AB/ 225 Connect Working Group of the OpenID Foundation, by most notably of 226 the following people: 228 o Naveen Agarwal, Google 230 o Dirk Belfanz, Google 232 o John Bradley, Ping Identity 234 o Brian Campbell, Ping Identity 236 o Ryo Ito, mixi 238 o Michael B. Jones, Microsoft 240 o Torsten Lodderstadt, Deutsche Telekom 241 o Breno de Madeiros, Google 243 o Anthony Nadalin, Microsoft 245 o Nat Sakimura, Nomura Research Institute 247 7. References 249 7.1. Normative References 251 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 252 Requirement Levels", BCP 14, RFC 2119, March 1997. 254 [RFC4627] Crockford, D., "The application/json Media Type for 255 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 257 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 258 and D. Orchard, "URI Template", RFC 6570, March 2012. 260 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 261 6749, October 2012. 263 7.2. Informative References 265 [OpenID.Discovery] 266 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 267 Connect Discovery 1.0", May 2013. 269 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 270 4949, August 2007. 272 Authors' Addresses 274 Nat Sakimura (editor) 275 Nomura Research Institute 277 Email: sakimura@gmail.com 279 John Bradley 280 Ping Identity 282 Email: jbradley@pingidentity.com 283 Naveen Agarwal 284 Google 286 Email: naa@google.com