idnits 2.17.1 draft-ietf-oauth-v2-http-mac-05.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (January 15, 2014) is 3752 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) == Missing Reference: 'FWS' is mentioned on line 412, but not defined == Unused Reference: 'RFC2616' is defined on line 1059, but no explicit reference was found in the text == Unused Reference: 'RFC3986' is defined on line 1068, but no explicit reference was found in the text == Unused Reference: 'RFC6265' is defined on line 1079, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-25 == Outdated reference: A later version (-40) exists of draft-ietf-jose-json-web-encryption-19 == Outdated reference: A later version (-32) exists of draft-ietf-oauth-json-web-token-14 == Outdated reference: A later version (-06) exists of draft-richer-oauth-introspection-04 -- Possible downref: Normative reference to a draft: ref. 'I-D.tschofenig-oauth-audience' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-03) exists of draft-tschofenig-oauth-hotk-02 -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) -- Obsolete informational reference (is this intentional?): RFC 6125 (Obsoleted by RFC 9525) Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth J. Richer 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track W. Mills 5 Expires: July 19, 2014 Yahoo! Inc. 6 H. Tschofenig, Ed. 8 P. Hunt 9 Oracle Corporation 10 January 15, 2014 12 OAuth 2.0 Message Authentication Code (MAC) Tokens 13 draft-ietf-oauth-v2-http-mac-05.txt 15 Abstract 17 This specification describes how to use MAC Tokens in HTTP requests 18 to access OAuth 2.0 protected resources. An OAuth client willing to 19 access a protected resource needs to demonstrate possession of a 20 cryptographic key by using it with a keyed message digest function to 21 the request. 23 The document also defines a key distribution protocol for obtaining a 24 fresh session key. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on July 19, 2014. 43 Copyright Notice 45 Copyright (c) 2014 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4 63 4. Key Distribution . . . . . . . . . . . . . . . . . . . . . . 6 64 4.1. Session Key Transport to Client . . . . . . . . . . . . . 6 65 4.2. Session Key Transport to Resource Server . . . . . . . . 8 66 5. The Authenticator . . . . . . . . . . . . . . . . . . . . . . 9 67 5.1. The Authenticator . . . . . . . . . . . . . . . . . . . . 9 68 5.2. MAC Input String . . . . . . . . . . . . . . . . . . . . 12 69 5.3. Keyed Message Digest Algorithms . . . . . . . . . . . . . 13 70 5.3.1. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . 13 71 5.3.2. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . 14 72 6. Verifying the Authenticator . . . . . . . . . . . . . . . . . 14 73 6.1. Timestamp Verification . . . . . . . . . . . . . . . . . 15 74 6.2. Error Handling . . . . . . . . . . . . . . . . . . . . . 15 75 7. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 76 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 77 8.1. Key Distribution . . . . . . . . . . . . . . . . . . . . 16 78 8.2. Offering Confidentiality Protection for Access to 79 Protected Resources . . . . . . . . . . . . . . . . . . . 16 80 8.3. Authentication of Resource Servers . . . . . . . . . . . 17 81 8.4. Plaintext Storage of Credentials . . . . . . . . . . . . 17 82 8.5. Entropy of Session Keys . . . . . . . . . . . . . . . . . 17 83 8.6. Denial of Service / Resource Exhaustion Attacks . . . . . 18 84 8.7. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 18 85 8.8. CSRF Attacks . . . . . . . . . . . . . . . . . . . . . . 19 86 8.9. Protecting HTTP Header Fields . . . . . . . . . . . . . . 19 87 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 88 9.1. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 19 89 9.2. MAC Token Algorithm Registry . . . . . . . . . . . . . . 20 90 9.2.1. Registration Template . . . . . . . . . . . . . . . . 20 91 9.2.2. Initial Registry Contents . . . . . . . . . . . . . . 21 92 9.3. OAuth Access Token Type Registration . . . . . . . . . . 21 93 9.3.1. The "mac" OAuth Access Token Type . . . . . . . . . . 21 94 9.4. OAuth Parameters Registration . . . . . . . . . . . . . . 22 95 9.4.1. The "mac_key" OAuth Parameter . . . . . . . . . . . . 22 96 9.4.2. The "mac_algorithm" OAuth Parameter . . . . . . . . . 22 97 9.4.3. The "kid" OAuth Parameter . . . . . . . . . . . . . . 22 98 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 99 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 100 11.1. Normative References . . . . . . . . . . . . . . . . . . 23 101 11.2. Informative References . . . . . . . . . . . . . . . . . 25 102 Appendix A. Background Information . . . . . . . . . . . . . . . 26 103 A.1. Security and Privacy Threats . . . . . . . . . . . . . . 26 104 A.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 27 105 A.2.1. Confidentiality Protection . . . . . . . . . . . . . 28 106 A.2.2. Sender Constraint . . . . . . . . . . . . . . . . . . 28 107 A.2.3. Key Confirmation . . . . . . . . . . . . . . . . . . 29 108 A.2.4. Summary . . . . . . . . . . . . . . . . . . . . . . . 30 109 A.3. Requirements . . . . . . . . . . . . . . . . . . . . . . 31 110 A.4. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 35 111 A.4.1. Access to an 'Unprotected' Resource . . . . . . . . . 35 112 A.4.2. Offering Application Layer End-to-End Security . . . 36 113 A.4.3. Preventing Access Token Re-Use by the Resource Server 36 114 A.4.4. TLS Channel Binding Support . . . . . . . . . . . . . 36 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 117 1. Introduction 119 This specification describes how to use MAC Tokens in HTTP requests 120 and responses to access protected resources via the OAuth 2.0 121 protocol [RFC6749]. An OAuth client willing to access a protected 122 resource needs to demonstrate possession of a symmetric key by using 123 it with a keyed message digest function to the request. The keyed 124 message digest function is computed over a flexible set of parameters 125 from the HTTP message. 127 The MAC Token mechanism requires the establishment of a shared 128 symmetric key between the client and the resource server. This 129 specification defines a three party key distribution protocol to 130 dynamically distribute this session key from the authorization server 131 to the client and the resource server. 133 The design goal for this mechanism is to support the requirements 134 outlined in Appendix A. In particular, when a server uses this 135 mechanism, a passive attacker will be unable to use an eavesdropped 136 access token exchanged between the client and the resource server. 137 In addition, this mechanism helps secure the access token against 138 leakage when sent over a secure channel to the wrong resource server 139 if the client provided information about the resource server it wants 140 to interact with in the request to the authorization server. 142 Since a keyed message digest only provides integrity protection and 143 data-origin authentication confidentiality protection can only be 144 added by the usage of Transport Layer Security (TLS). This 145 specification provides a mechanism for channel binding is included to 146 ensure that a TLS channel is not terminated prematurely and indeed 147 covers the entire end-to-end communication. 149 2. Terminology 151 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 152 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 153 specification are to be interpreted as described in [RFC2119]. 155 This specification uses the Augmented Backus-Naur Form (ABNF) 156 notation of [I-D.ietf-httpbis-p1-messaging]. Additionally, the 157 following rules are included from [RFC2617]: auth-param. 159 Session Key: 161 The terms mac key, session key, and symmetric key are used 162 interchangeably and refer to the cryptographic keying material 163 established between the client and the resource server. This 164 temporary key used between the client and the resource server, 165 with a lifetime limited to the lifetime of the access token. This 166 session key is generated by the authorization server. 168 Authenticator: 170 A record containing information that can be shown to have been 171 recently generated using the session key known only by the client 172 and the resource server. 174 Message Authentication Code (MAC): 176 Message authentication codes (MACs) are hash functions that take 177 two distinct inputs, a message and a secret key, and produce a 178 fixed-size output. The design goal is that it is 179 practically infeasible to produce the same output without 180 knowledge of the key. The terms keyed message digest functions 181 and MACs are used interchangeably. 183 3. Architecture 185 The architecture of the proposal described in this document assumes 186 that the authorization server acts as a trusted third party that 187 provides session keys to clients and to resource servers. These 188 session keys are used by the client and the resource server as input 189 to a MAC. In order to obtain the session key the client interacts 190 with the authorization server as part of the a normal grant exchange. 191 This is shown in an abstract way in Figure 1. Together with the 192 access token the authorization server returns a session key (in the 193 mac_key parameter) and several other parameters. The resource server 194 obtains the session key via the access token. Both of these two key 195 distribution steps are described in more detail in Section 4. 197 +---------------+ 198 ^| | AS-RS Key 199 // | Authorization |<******* 200 / | Server | * 201 // | | * 202 / | | * 203 (I) // /+---------------+ * 204 Access / // * 205 Token / / * 206 Request// // (II) Access Token * 207 / / +Session Key (SK) * 208 // // * 209 / v v 210 +-----------+ +------------+ 211 | | | | 212 | | | Resource | 213 | Client | | Server | 214 | | | | 215 | | | | 216 +-----------+ +------------+ 218 ****: Out-of-Band Long-Term Key Establishment 219 ----: Dynamic Session Key Distribution 221 Figure 1: Architecture: Interaction between the Client and the 222 Authorization Server. 224 Once the client has obtained the necessary access token and the 225 session key (including parameters) it can start to interact with the 226 resource server. To demonstrate possession of the session key it 227 computes a MAC and adds various fields to the outgoing request 228 message. We call this structure the "Authenticator". The server 229 evaluates the request, includes an Authenticator and returns a 230 response back to the client. Since the access token is valid for a 231 period of time the resource server may decide to cache it so that it 232 does not need to be provided in every request from the client. This 233 interaction is shown in Figure 2. 235 +---------------+ 236 | | 237 | Authorization | 238 | Server | 239 | | 240 | | 241 +---------------+ 243 +-----------+ Authenticator (a) +------------+ 244 | |---------------------->| | 245 | | [+Access Token] | Resource | 246 | Client | | Server | 247 | | Authenticator (b) | | 248 | |<----------------------| | 249 +-----------+ +------------+ 251 ^ ^ 252 | | 253 | | 254 SK SK 255 +param +param 257 Figure 2: Architecture: Interaction between the Client and the 258 Resource Server. 260 4. Key Distribution 262 For this scheme to function a session key must be available to the 263 client and the resource server, which is then used as a parameter in 264 the keyed message digest function. This document describes the key 265 distribution mechanism that uses the authorization server as a 266 trusted third party, which ensures that the session key is 267 transported from the authorization server to the client and the 268 resource server. 270 4.1. Session Key Transport to Client 272 Authorization servers issue MAC Tokens based on requests from 273 clients. The request MUST include the audience parameter defined in 274 [I-D.tschofenig-oauth-audience], which indicates the resource server 275 the client wants to interact with. This specification assumes use of 276 the 'Authorization Code' grant. If the request is processed 277 successfully by the authorization server it MUST return at least the 278 following parameters to the client: 280 kid 282 The name of the key (key id), which is an identifier generated 283 by the resource server. It is RECOMMENDED that the 284 authorization server generates this key id by computing a hash 285 over the access_token, for example using SHA-1, and to encode 286 it in a base64 format. 288 access_token 290 The OAuth 2.0 access token. 292 mac_key 294 The session key generated by the authorization server. Note 295 that the lifetime of the session key is equal to the lifetime 296 of the access token. 298 mac_algorithm 300 The MAC algorithm used to calculate the request MAC. The value 301 MUST be one of "hmac-sha-1", "hmac-sha-256", or a registered 302 extension algorithm name as described in Section 9.2. The 303 authorization server is assumed to know the set of algorithms 304 supported by the client and the resource server. It selects an 305 algorithm that meets the security policies and is supported by 306 both nodes. 308 For example: 310 HTTP/1.1 200 OK 311 Content-Type: application/json 312 Cache-Control: no-store 314 { 315 "access_token": 316 "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0. 317 pwaFh7yJPivLjjPkzC-GeAyHuy7AinGcS51AZ7TXnwkC80Ow1aW47kcT_UV54ubo 318 nONbeArwOVuR7shveXnwPmucwrk_3OCcHrCbE1HR-Jfme2mF_WR3zUMcwqmU0RlH 319 kwx9txo_sKRasjlXc8RYP-evLCmT1XRXKjtY5l44Gnh0A84hGvVfMxMfCWXh38hi 320 2h8JMjQHGQ3mivVui5lbf-zzb3qXXxNO1ZYoWgs5tP1-T54QYc9Bi9wodFPWNPKB 321 kY-BgewG-Vmc59JqFeprk1O08qhKQeOGCWc0WPC_n_LIpGWH6spRm7KGuYdgDMkQ 322 bd4uuB0uPPLx_euVCdrVrA. 323 AxY8DCtDaGlsbGljb3RoZQ. 324 7MI2lRCaoyYx1HclVXkr8DhmDoikTmOp3IdEmm4qgBThFkqFqOs3ivXLJTku4M0f 325 laMAbGG_X6K8_B-0E-7ak-Olm_-_V03oBUUGTAc-F0A. 326 OwWNxnC-BMEie-GkFHzVWiNiaV3zUHf6fCOGTwbRckU", 327 "token_type":"mac", 328 "expires_in":3600, 329 "refresh_token":"8xLOxBtZp8", 330 "kid":"22BIjxU93h/IgwEb4zCRu5WF37s=", 331 "mac_key":"adijq39jdlaska9asud", 332 "mac_algorithm":"hmac-sha-256" 333 } 335 4.2. Session Key Transport to Resource Server 337 The transport of the mac_key from the authorization server to the 338 resource server is accomplished by conveying the encrypting mac_key 339 inside the access token. At the time of writing only one 340 standardized format for carrying the access token is defined: the 341 JSON Web Token (JWT) [I-D.ietf-oauth-json-web-token]. Note that the 342 header of the JSON Web Encryption (JWE) structure 343 [I-D.ietf-jose-json-web-encryption], which is a JWT with encrypted 344 content, MUST contain a key id (kid) in the header to allow the 345 resource server to select the appropriate keying material for 346 decryption. This keying material is a symmetric or an asymmetric 347 long-term key established between the resource server and the 348 authorization server, as shown in Figure 1 as AS-RS key. The 349 establishment of this long-term key is outside the scope of this 350 specification. 352 This document defines two new claims to be carried in the JWT: 353 mac_key, kid. These two parameters match the content of the mac_key 354 and the kid conveyed to the client, as shown in Section 4.1. 356 kid 357 The name of the key (key id), which is an identifier generated 358 by the resource server. 360 mac_key 362 The session key generated by the authorization server. 364 This example shows a JWT claim set without header and without 365 encryption: 367 {"iss":"authorization-server.example.com", 368 "exp":1300819380, 369 "kid":"22BIjxU93h/IgwEb4zCRu5WF37s=", 370 "mac_key":"adijq39jdlaska9asud", 371 "aud":"apps.example.com" 372 } 374 QUESTIONS: An alternative to the use of a JWT to convey the access 375 token with the encrypted mac_key is use the token introspect 376 [I-D.richer-oauth-introspection]. What mechanism should be 377 described? What should be mandatory to implement? 379 QUESTIONS: The above description assumes that the entire access 380 token is encrypted but it would be possible to only encrypt the 381 session key and to only apply integrity protection to other 382 fields. Is this desirable? 384 5. The Authenticator 386 To access a protected resource the client must be in the possession 387 of a valid set of session key provided by the authorization server. 388 The client constructs the authenticator, as described in Section 5.1. 390 5.1. The Authenticator 392 The client constructs the authenticator and adds the resulting fields 393 to the HTTP request using the "Authorization" request header field. 394 The "Authorization" request header field uses the framework defined 395 by [RFC2617]. To include the authenticator in a subsequent response 396 from the authorization server to the client the WWW-Authenticate 397 header is used. For further exchanges a new, yet-to-be-defined 398 header will be used. 400 authenticator = "MAC" 1*SP #params 402 params = id / ts / seq-nr / access_token / mac / h / cb 404 kid = "kid" "=" string-value 405 ts = "ts" "=" ( <"> timestamp <"> ) / timestamp 406 seq-nr = "seq-nr" "=" string-value 407 access_token = "access_token" "=" b64token 408 mac = "mac" "=" string-value 409 cb = "cb" "=" token 410 h = "h" "=" h-tag 411 h-tag = %x68 [FWS] "=" [FWS] hdr-name 412 *( [FWS] ":" [FWS] hdr-name ) 413 hdr-name = token 415 timestamp = 1*DIGIT 416 string-value = ( <"> plain-string <"> ) / plain-string 417 plain-string = 1*( %x20-21 / %x23-5B / %x5D-7E ) 419 b64token = 1*( ALPHA / DIGIT / 420 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 422 The header attributes are set as follows: 424 kid 426 REQUIRED. The key identifier. 428 ts 430 REQUIRED. The timestamp. The value MUST be a positive integer 431 set by the client when making each request to the number of 432 milliseconds since 1 January 1970. 434 The JavaScript getTime() function or the Java 435 System.currentTimeMillis() function, for example, produce such 436 a timestamp. 438 seq-nr 440 OPTIONAL. This optional field includes the initial sequence 441 number to be used by the messages exchange between the client 442 and the server when the replay protection provided by the 443 timestamp is not sufficient enough replay protection. This 444 field specifies the initial sequence number for messages from 445 the client to the server. When included in the response 446 message, the initial sequence number is that for messages from 447 the server to the client. Sequence numbers fall in the range 0 448 through 2^64 - 1 and wrap to zero following the value 2^64 - 1. 450 The initial sequence number SHOULD be random and uniformly 451 distributed across the full space of possible sequence numbers, 452 so that it cannot be guessed by an attacker and so that it and 453 the successive sequence numbers do not repeat other sequences. 454 In the event that more than 2^64 messages are to be generated 455 in a series of messages, rekeying MUST be performed before 456 sequence numbers are reused. Rekeying requires a new access 457 token to be requested. 459 access_token 461 CONDITIONAL. The access_token MUST be included in the first 462 request from the client to the server but MUST NOT be included 463 in a subsequent response and in a further protocol exchange. 465 mac 467 REQUIRED. The result of the keyed message digest computation, 468 as described in Section 5.3. 470 cb 472 OPTIONAL. This field carries the channel binding value from 473 RFC 5929 [RFC5929] in the following format: cb= channel- 474 binding-type ":" channel-binding-content. RFC 5929 offers two 475 types of channel bindings for TLS. First, there is the 'tls- 476 server-end-point' channel binding, which uses a hash of the TLS 477 server's certificate as it appears, octet for octet, in the 478 server's Certificate message. The second channel binding is 479 'tls-unique', which uses the first TLS Finished message sent 480 (note: the Finished struct, not the TLS record layer message 481 containing it) in the most recent TLS handshake of the TLS 482 connection being bound to. As an example, the cb field may 483 contain cb=tls-unique:9382c93673d814579ed1610d3 485 h 487 OPTIONAL. This field contains a colon-separated list of header 488 field names that identify the header fields presented to the 489 keyed message digest algorithm. If the 'h' header field is 490 absent then the following value is set by default: h="host". 491 The field MUST contain the complete list of header fields in 492 the order presented to the keyed message digest algorithm. The 493 field MAY contain names of header fields that do not exist at 494 the time of computing the keyed message digest; nonexistent 495 header fields do not contribute to the keyed message digest 496 computation (that is, they are treated as the null input, 497 including the header field name, the separating colon, the 498 header field value, and any CRLF terminator). By including 499 header fields that do not actually exist in the keyed message 500 digest computation, the client can allow the resource server to 501 detect insertion of those header fields by intermediaries. 502 However, since the client cannot possibly know what header 503 fields might be defined in the future, this mechanism cannot be 504 used to prevent the addition of any possible unknown header 505 fields. The field MAY contain multiple instances of a header 506 field name, meaning multiple occurrences of the corresponding 507 header field are included in the header hash. The field MUST 508 NOT include the mac header field. Folding whitespace (FWS) MAY 509 be included on either side of the colon separator. Header 510 field names MUST be compared against actual header field names 511 in a case-insensitive manner. This list MUST NOT be empty. 512 See Section 8 for a discussion of choosing header fields. 514 Attributes MUST NOT appear more than once. Attribute values are 515 limited to a subset of ASCII, which does not require escaping, as 516 defined by the plain-string ABNF. 518 5.2. MAC Input String 520 An HTTP message can either be a request from client to server or a 521 response from server to client. Syntactically, the two types of 522 message differ only in the start-line, which is either a request-line 523 (for requests) or a status-line (for responses). 525 Two parameters serve as input to a keyed message digest function: a 526 key and an input string. Depending on the communication direction 527 either the request-line or the status-line is used as the first value 528 followed by the HTTP header fields listed in the 'h' parameter. 529 Then, the timestamp field and the seq-nr field (if present) is 530 concatenated. 532 As an example, consider the HTTP request with the new line separator 533 character represented by "\n" for editorial purposes only. The h 534 parameter is set to h=host, the kid is 314906b0-7c55, and the 535 timstamp is 1361471629. 537 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1 538 Host: example.com 540 Hello World! 542 The resulting string is: 544 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1\n 545 1361471629\n 546 example.com\n 548 5.3. Keyed Message Digest Algorithms 550 The client uses a cryptographic algorithm together with a session key 551 to calculate a keyed message digest. This specification defines two 552 algorithms: "hmac-sha-1" and "hmac-sha-256", and provides an 553 extension registry for additional algorithms. 555 5.3.1. hmac-sha-1 557 "hmac-sha-1" uses the HMAC-SHA1 algorithm, as defined in [RFC2104]: 559 mac = HMAC-SHA1 (key, text) 561 Where: 563 text 565 is set to the value of the input string as described in 566 Section 5.2, 568 key 570 is set to the session key provided by the authorization server, 571 and 573 mac 574 is used to set the value of the "mac" attribute, after the 575 result string is base64-encoded per Section 6.8 of [RFC2045]. 577 5.3.2. hmac-sha-256 579 "hmac-sha-256" uses the HMAC algorithm, as defined in [RFC2104], with 580 the SHA-256 hash function, defined in [NIST-FIPS-180-3]: 582 mac = HMAC-SHA256 (key, text) 584 Where: 586 text 588 is set to the value of the input string as described in 589 Section 5.2, 591 key 593 is set to the session key provided by the authorization server, 594 and 596 mac 598 is used to set the value of the "mac" attribute, after the 599 result string is base64-encoded per Section 6.8 of [RFC2045]. 601 6. Verifying the Authenticator 603 When receiving a message with an authenticator the following steps 604 are performed: 606 1. When the authorization server receives a message with a new 607 access token (and consequently a new session key) then it obtains 608 the session key by retrieving the content of the access token 609 (which requires decryption of the session key contained inside 610 the token). The content of the access token, in particular the 611 audience field and the scope, MUST be verified as described in 612 Alternatively, the kid parameter is used to look-up a cached 613 session key from a previous exchange. 615 2. Recalculate the keyed message digest, as described in 616 Section 5.3, and compare the request MAC to the value received 617 from the client via the "mac" attribute. 619 3. Verify that no replay took place by comparing the value of the ts 620 (timestamp) header with the local time. The processing of 621 authenticators with stale timestamps is described in Section 6.1. 623 Error handling is described in Section 6.2. 625 6.1. Timestamp Verification 627 The timestamp field enables the server to detect replay attacks. 628 Without replay protection, an attacker can use an eavesdropped 629 request to gain access to a protected resource. The following 630 procedure is used to detect replays: 632 o At the time the first request is received from the client for each 633 key identifier, calculate the difference (in seconds) between the 634 request timestamp and the local clock. The difference is stored 635 locally for later use. 637 o For each subsequent request, apply the request time delta to the 638 timestamp included in the message to calculate the adjusted 639 request time. 641 o Verify that the adjusted request time is within the allowed time 642 period defined by the authorization server. If the local time and 643 the calculated time based in the request differ by more than the 644 allowable clock skew (e.g., 5 minutes) a replay has to be assumed. 646 6.2. Error Handling 648 If the protected resource request does not include an access token, 649 lacks the keyed message digest, contains an invalid key identifier, 650 or is malformed, the server SHOULD return a 401 (Unauthorized) HTTP 651 status code. 653 For example: 655 HTTP/1.1 401 Unauthorized 656 WWW-Authenticate: MAC 658 The "WWW-Authenticate" request header field uses the framework 659 defined by [RFC2617] as follows: 661 challenge = "MAC" [ 1*SP #param ] 662 param = error / auth-param 663 error = "error" "=" ( token / quoted-string) 665 Each attribute MUST NOT appear more than once. 667 If the protected resource request included a MAC "Authorization" 668 request header field and failed authentication, the server MAY 669 include the "error" attribute to provide the client with a human- 670 readable explanation why the access request was declined to assist 671 the client developer in identifying the problem. 673 For example: 675 HTTP/1.1 401 Unauthorized 676 WWW-Authenticate: MAC error="The MAC credentials expired" 678 7. Example 680 [Editor's Note: Full example goes in here.] 682 8. Security Considerations 684 As stated in [RFC2617], the greatest sources of risks are usually 685 found not in the core protocol itself but in policies and procedures 686 surrounding its use. Implementers are strongly encouraged to assess 687 how this protocol addresses their security requirements and the 688 security threats they want to mitigate. 690 8.1. Key Distribution 692 This specification describes a key distribution mechanism for 693 providing the session key (and parameters) from the authorization 694 server to the client. The interaction between the client and the 695 authorization server requires Transport Layer Security (TLS) with a 696 ciphersuite offering confidentiality protection. The session key 697 MUST NOT be transmitted in clear since this would completely destroy 698 the security benefits of the proposed scheme. Furthermore, the 699 obtained session key MUST be stored so that only the client instance 700 has access to it. Storing the session key, for example, in a cookie 701 allows other parties to gain access to this confidential information 702 and compromises the security of the protocol. 704 8.2. Offering Confidentiality Protection for Access to Protected 705 Resources 707 This specification can be used with and without Transport Layer 708 Security (TLS). 710 Without TLS this protocol provides a mechanism for verifying the 711 integrity of requests and responses, it provides no confidentiality 712 protection. Consequently, eavesdroppers will have full access to 713 request content and further messages exchanged between the client and 714 the resource server. This could be problematic when data is 715 exchanged that requires care, such as personal data. 717 When TLS is used then confidentiality can be ensured and with the use 718 of the TLS channel binding feature it ensures that the TLS channel is 719 cryptographically bound to the used MAC token. TLS in combination 720 with channel bindings bound to the MAC token provide security 721 superior to the OAuth Bearer Token. 723 The use of TLS in combination with the MAC token is highly 724 recommended to ensure the confidentiality of the user's data. 726 8.3. Authentication of Resource Servers 728 This protocol allows clients to verify the authenticity of resource 729 servers in two ways: 731 1. The resource server demonstrates possession of the session key by 732 computing a keyed message digest function over a number of HTTP 733 fields in the response to the request from the client. 735 2. When TLS is used the resource server is authenticated as part of 736 the TLS handshake. 738 8.4. Plaintext Storage of Credentials 740 The MAC key works in the same way passwords do in traditional 741 authentication systems. In order to compute the keyed message 742 digest, the client and the resource server must have access to the 743 MAC key in plaintext form. 745 If an attacker were to gain access to these MAC keys - or worse, to 746 the resource server's or the authorization server's database of all 747 such MAC keys - he or she would be able to perform any action on 748 behalf of any client. 750 It is therefore paramount to the security of the protocol that these 751 session keys are protected from unauthorized access. 753 8.5. Entropy of Session Keys 754 Unless TLS is used between the client and the resource server, 755 eavesdroppers will have full access to requests sent by the client. 756 They will thus be able to mount off-line brute-force attacks to 757 recover the session key used to compute the keyed message digest. 758 Authorization servers should be careful to generate fresh and unique 759 session keys with sufficient entropy to resist such attacks for at 760 least the length of time that the session keys are valid. 762 For example, if a session key is valid for one day, authorization 763 servers must ensure that it is not possible to mount a brute force 764 attack that recovers the session key in less than one day. Of 765 course, servers are urged to err on the side of caution, and use the 766 longest session key reasonable. 768 It is equally important that the pseudo-random number generator 769 (PRNG) used to generate these session keys be of sufficiently high 770 quality. Many PRNG implementations generate number sequences that 771 may appear to be random, but which nevertheless exhibit patterns, 772 which make cryptanalysis easier. Implementers are advised to follow 773 the guidance on random number generation in [RFC4086]. 775 8.6. Denial of Service / Resource Exhaustion Attacks 777 This specification includes a number of features which may make 778 resource exhaustion attacks against resource servers possible. For 779 example, a resource server may need to need to consult back-end 780 databases and the authorization server to verify an incoming request 781 including an access token before granting access to the protected 782 resource. 784 An attacker may exploit this to perform a denial of service attack by 785 sending a large number of invalid requests to the server. The 786 computational overhead of verifying the keyed message digest alone 787 is, however, not sufficient to mount a denial of service attack since 788 keyed message digest functions belong to the computationally fastest 789 cryptographic algorithms. The usage of TLS does, however, require 790 additional computational capabity to perform the asymmetric 791 cryptographic operations. For a brief discussion about denial of 792 service vulnerabilities of TLS please consult Appendix F.5 of RFC 793 5246 [RFC5246]. 795 8.7. Timing Attacks 797 This specification makes use of HMACs, for which a signature 798 verification involves comparing the received MAC string to the 799 expected one. If the string comparison operator operates in 800 observably different times depending on inputs, e.g. because it 801 compares the strings character by character and returns a negative 802 result as soon as two characters fail to match, then it may be 803 possible to use this timing information to determine the expected 804 MAC, character by character. 806 Implementers are encouraged to use fixed-time string comparators for 807 MAC verification. This means that the comparison operation is not 808 terminated once a mismatch is found. 810 8.8. CSRF Attacks 812 A Cross-Site Request Forgery attack occurs when a site, evil.com, 813 initiates within the victim's browser the loading of a URL from or 814 the posting of a form to a web site where a side-effect will occur, 815 e.g. transfer of money, change of status message, etc. To prevent 816 this kind of attack, web sites may use various techniques to 817 determine that the originator of the request is indeed the site 818 itself, rather than a third party. The classic approach is to 819 include, in the set of URL parameters or form content, a nonce 820 generated by the server and tied to the user's session, which 821 indicates that only the server could have triggered the action. 823 Recently, the Origin HTTP header has been proposed and deployed in 824 some browsers. This header indicates the scheme, host, and port of 825 the originator of a request. Some web applications may use this 826 Origin header as a defense against CSRF. 828 To keep this specification simple, HTTP headers are not part of the 829 string to be MACed. As a result, MAC authentication cannot defend 830 against header spoofing, and a web site that uses the Host header to 831 defend against CSRF attacks cannot use MAC authentication to defend 832 against active network attackers. Sites that want the full 833 protection of MAC Authentication should use traditional, cookie-tied 834 CSRF defenses. 836 8.9. Protecting HTTP Header Fields 838 This specification provides flexibility for selectively protecting 839 header fields and even the body of the message. At a minimum the 840 following fields are included in the keyed message digest. 842 9. IANA Considerations 844 9.1. JSON Web Token Claims 846 This document adds the following claims to the JSON Web Token Claims 847 registry established with [I-D.ietf-oauth-json-web-token]: 849 o Claim Name: "kid" 850 o Change Controller: IETF 852 o Specification Document(s): [[ this document ]] 854 o Claim Name: "mac_key" 856 o Change Controller: IETF 858 o Specification Document(s): [[ this document ]] 860 9.2. MAC Token Algorithm Registry 862 This specification establishes the MAC Token Algorithm registry. 864 Additional keyed message digest algorithms are registered on the 865 advice of one or more Designated Experts (appointed by the IESG or 866 their delegate), with a Specification Required (using terminology 867 from [RFC5226]). However, to allow for the allocation of values 868 prior to publication, the Designated Expert(s) may approve 869 registration once they are satisfied that such a specification will 870 be published. 872 Registration requests should be sent to the [TBD]@ietf.org mailing 873 list for review and comment, with an appropriate subject (e.g., 874 "Request for MAC Algorithm: example"). [[ Note to RFC-EDITOR: The 875 name of the mailing list should be determined in consultation with 876 the IESG and IANA. Suggested name: http-mac-ext-review. ]] 878 Within at most 14 days of the request, the Designated Expert(s) will 879 either approve or deny the registration request, communicating this 880 decision to the review list and IANA. Denials should include an 881 explanation and, if applicable, suggestions as to how to make the 882 request successful. 884 Decisions (or lack thereof) made by the Designated Expert can be 885 first appealed to Application Area Directors (contactable using app- 886 ads@tools.ietf.org email address or directly by looking up their 887 email addresses on http://www.iesg.org/ website) and, if the 888 appellant is not satisfied with the response, to the full IESG (using 889 the iesg@iesg.org mailing list). 891 IANA should only accept registry updates from the Designated 892 Expert(s), and should direct all requests for registration to the 893 review mailing list. 895 9.2.1. Registration Template 897 Algorithm name: 899 The name requested (e.g., "example"). 901 Change controller: 903 For standards-track RFCs, state "IETF". For others, give the name 904 of the responsible party. Other details (e.g., postal address, 905 e-mail address, home page URI) may also be included. 907 Specification document(s): 909 Reference to document that specifies the algorithm, preferably 910 including a URI that can be used to retrieve a copy of the 911 document. An indication of the relevant sections may also be 912 included, but is not required. 914 9.2.2. Initial Registry Contents 916 The HTTP MAC authentication scheme algorithm registry's initial 917 contents are: 919 o Algorithm name: hmac-sha-1 921 o Change controller: IETF 923 o Specification document(s): [[ this document ]] 925 o Algorithm name: hmac-sha-256 927 o Change controller: IETF 929 o Specification document(s): [[ this document ]] 931 9.3. OAuth Access Token Type Registration 933 This specification registers the following access token type in the 934 OAuth Access Token Type Registry. 936 9.3.1. The "mac" OAuth Access Token Type 938 Type name: 940 mac 942 Additional Token Endpoint Response Parameters: 944 secret, algorithm 946 HTTP Authentication Scheme(s): 948 MAC 950 Change controller: 952 IETF 954 Specification document(s): 956 [[ this document ]] 958 9.4. OAuth Parameters Registration 960 This specification registers the following parameters in the OAuth 961 Parameters Registry established by [RFC6749]. 963 9.4.1. The "mac_key" OAuth Parameter 965 Parameter name: mac_key 967 Parameter usage location: authorization response, token response 969 Change controller: IETF 971 Specification document(s): [[ this document ]] 973 Related information: None 975 9.4.2. The "mac_algorithm" OAuth Parameter 977 Parameter name: mac_algorithm 979 Parameter usage location: authorization response, token response 981 Change controller: IETF 983 Specification document(s): [[ this document ]] 985 Related information: None 987 9.4.3. The "kid" OAuth Parameter 989 Parameter name: kid 991 Parameter usage location: authorization response, token response 993 Change controller: IETF 995 Specification document(s): [[ this document ]] 996 Related information: None 998 10. Acknowledgments 1000 This document is based on OAuth 1.0 and we would like to thank Eran 1001 Hammer-Lahav for his work on incorporating the ideas into OAuth 2.0. 1002 As part of this initial work the following persons provided feedback: 1003 Ben Adida, Adam Barth, Rasmus Lerdorf, James Manger, William Mills, 1004 Scott Renfro, Justin Richer, Toby White, Peter Wolanin, and Skylar 1005 Woodward 1007 Further work in this document was done as part of OAuth working group 1008 conference calls late 2012/early 2013 and in design team conference 1009 calls February 2013. The following persons (in addition to the OAuth 1010 WG chairs, Hannes Tschofenig, and Derek Atkins) provided their input 1011 during these calls: Bill Mills, Justin Richer, Phil Hunt, Prateek 1012 Mishra, Mike Jones, George Fletcher, Leif Johansson, Lucy Lynch, John 1013 Bradley, Tony Nadalin, Klaas Wierenga, Thomas Hardjono, Brian 1014 Campbell 1016 In the appendix of this document we re-use content from [RFC4962] and 1017 the authors would like thank Russ Housely and Bernard Aboba for their 1018 work on RFC 4962. 1020 11. References 1022 11.1. Normative References 1024 [I-D.ietf-httpbis-p1-messaging] 1025 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1026 (HTTP/1.1): Message Syntax and Routing", draft-ietf- 1027 httpbis-p1-messaging-25 (work in progress), November 2013. 1029 [I-D.ietf-jose-json-web-encryption] 1030 Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 1031 Encryption (JWE)", draft-ietf-jose-json-web-encryption-19 1032 (work in progress), December 2013. 1034 [I-D.ietf-oauth-json-web-token] 1035 Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1036 (JWT)", draft-ietf-oauth-json-web-token-14 (work in 1037 progress), December 2013. 1039 [I-D.richer-oauth-introspection] 1040 Richer, J., "OAuth Token Introspection", draft-richer- 1041 oauth-introspection-04 (work in progress), May 2013. 1043 [I-D.tschofenig-oauth-audience] 1044 Tschofenig, H., "OAuth 2.0: Audience Information", draft- 1045 tschofenig-oauth-audience-00 (work in progress), February 1046 2013. 1048 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1049 Extensions (MIME) Part One: Format of Internet Message 1050 Bodies", RFC 2045, November 1996. 1052 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1053 Hashing for Message Authentication", RFC 2104, February 1054 1997. 1056 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1057 Requirement Levels", BCP 14, RFC 2119, March 1997. 1059 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1060 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1061 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1063 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1064 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1065 Authentication: Basic and Digest Access Authentication", 1066 RFC 2617, June 1999. 1068 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1069 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1070 3986, January 2005. 1072 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1073 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1074 May 2008. 1076 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1077 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1079 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1080 April 2011. 1082 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 1083 6749, October 2012. 1085 [W3C.REC-html401-19991224] 1086 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 1087 Specification", World Wide Web Consortium Recommendation 1088 REC-html401-19991224, December 1999, 1089 . 1091 11.2. Informative References 1093 [I-D.hardjono-oauth-kerberos] 1094 Hardjono, T., "OAuth 2.0 support for the Kerberos V5 1095 Authentication Protocol", draft-hardjono-oauth-kerberos-01 1096 (work in progress), December 2010. 1098 [I-D.tschofenig-oauth-hotk] 1099 Bradley, J., Hunt, P., Nadalin, A., and H. Tschofenig, 1100 "The OAuth 2.0 Authorization Framework: Holder-of-the-Key 1101 Token Usage", draft-tschofenig-oauth-hotk-02 (work in 1102 progress), February 2013. 1104 [NIST-FIPS-180-3] 1105 National Institute of Standards and Technology, "Secure 1106 Hash Standard (SHS). FIPS PUB 180-3, October 2008", 1107 October 2008. 1109 [NIST800-63] 1110 Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., 1111 and E. Nabbus, "NIST Special Publication 800-63-1, 1112 INFORMATION SECURITY", December 2008. 1114 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1115 Requirements for Security", BCP 106, RFC 4086, June 2005. 1117 [RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The 1118 Kerberos Network Authentication Service (V5)", RFC 4120, 1119 July 2005. 1121 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 1122 for Transport Layer Security (TLS)", RFC 4279, December 1123 2005. 1125 [RFC4962] Housley, R. and B. Aboba, "Guidance for Authentication, 1126 Authorization, and Accounting (AAA) Key Management", BCP 1127 132, RFC 4962, July 2007. 1129 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 1130 Channels", RFC 5056, November 2007. 1132 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 1133 April 2010. 1135 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 1136 for TLS", RFC 5929, July 2010. 1138 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1139 Verification of Domain-Based Application Service Identity 1140 within Internet Public Key Infrastructure Using X.509 1141 (PKIX) Certificates in the Context of Transport Layer 1142 Security (TLS)", RFC 6125, March 2011. 1144 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1145 Framework: Bearer Token Usage", RFC 6750, October 2012. 1147 Appendix A. Background Information 1149 With the desire to define a security mechanism in addition to bearer 1150 tokens a design team was formed to collect threats, explore different 1151 threat mitigation techniques, describe use cases, and to derive 1152 requirements for the MAC token based security mechanism defined in 1153 the body of this document. This appendix provides information about 1154 this thought process that should help to motivate design decision. 1156 A.1. Security and Privacy Threats 1158 The following list presents several common threats against protocols 1159 utilizing some form of tokens. This list of threats is based on NIST 1160 Special Publication 800-63 [NIST800-63]. We exclude a discussion of 1161 threats related to any form of identity proofing and authentication 1162 of the Resource Owner to the Authorization Server since these 1163 procedures are not part of the OAuth 2.0 protocol specification 1164 itself. 1166 Token manufacture/modification: 1168 An attacker may generate a bogus tokens or modify the token 1169 content (such as authentication or attribute statements) of an 1170 existing token, causing Resource Server to grant inappropriate 1171 access to the Client. For example, an attacker may modify the 1172 token to extend the validity period. A Client may modify the 1173 token to have access to information that they should not be able 1174 to view. 1176 Token disclosure: Tokens may contain personal data, such as real 1177 name, age or birthday, payment information, etc. 1179 Token redirect: 1181 An attacker uses the token generated for consumption by the 1182 Resource Server to obtain access to another Resource Server. 1184 Token reuse: 1186 An attacker attempts to use a token that has already been used 1187 once with a Resource Server. The attacker may be an eavesdropper 1188 who observes the communication exchange or, worse, one of the 1189 communication end points. A Client may, for example, leak access 1190 tokens because it cannot keep secrets confidential. A Client may 1191 also re-use access tokens for some other Resource Servers. 1192 Finally, a Resource Server may use a token it had obtained from a 1193 Client and use it with another Resource Server that the Client 1194 interacts with. A Resource Server, offering relatively 1195 unimportant application services, may attempt to use an access 1196 token obtained from a Client to access a high-value service, such 1197 as a payment service, on behalf of the Client using the same 1198 access token. 1200 We excluded one threat from the list, namely 'token repudiation'. 1201 Token repudiation refers to a property whereby a Resource Server is 1202 given an assurance that the Authorization Server cannot deny to have 1203 created a token for the Client. We believe that such a property is 1204 interesting but most deployments prefer to deal with the violation of 1205 this security property through business actions rather than by using 1206 cryptography. 1208 A.2. Threat Mitigation 1210 A large range of threats can be mitigated by protecting the content 1211 of the token, using a digital signature or a keyed message digest. 1212 Alternatively, the content of the token could be passed by reference 1213 rather than by value (requiring a separate message exchange to 1214 resolve the reference to the token content). To simplify the 1215 subsequent description we assume that the token itself is digitally 1216 signed by the Authorization Server and therefore cannot be modified. 1218 To deal with token redirect it is important for the Authorization 1219 Server to include the identifier of the intended recipient - the 1220 Resource Server. A Resource Server must not be allowed to accept 1221 access tokens that are not meant for its consumption. 1223 To provide protection against token disclosure two approaches are 1224 possible, namely (a) not to include sensitive information inside the 1225 token or (b) to ensure confidentiality protection. The latter 1226 approach requires at least the communication interaction between the 1227 Client and the Authorization Server as well as the interaction 1228 between the Client and the Resource Server to experience 1229 confidentiality protection. As an example, Transport Layer Security 1230 with a ciphersuite that offers confidentiality protection has to be 1231 applied. Encrypting the token content itself is another alternative. 1232 In our scenario the Authorization Server would, for example, encrypt 1233 the token content with a symmetric key shared with the Resource 1234 Server. 1236 To deal with token reuse more choices are available. 1238 A.2.1. Confidentiality Protection 1240 In this approach confidentiality protection of the exchange is 1241 provided on the communication interfaces between the Client and the 1242 Resource Server, and between the Client and the Authorization Server. 1243 No eavesdropper on the wire is able to observe the token exchange. 1244 Consequently, a replay by a third party is not possible. An 1245 Authorization Server wants to ensure that it only hands out tokens to 1246 Clients it has authenticated first and who are authorized. For this 1247 purpose, authentication of the Client to the Authorization Server 1248 will be a requirement to ensure adequate protection against a range 1249 of attacks. This is, however, true for the description in 1250 Appendix A.2.2 and Appendix A.2.3 as well. Furthermore, the Client 1251 has to make sure it does not distribute the access token to entities 1252 other than the intended the Resource Server. For that purpose the 1253 Client will have to authenticate the Resource Server before 1254 transmitting the access token. 1256 A.2.2. Sender Constraint 1258 Instead of providing confidentiality protection the Authorization 1259 Server could also put the identifier of the Client into the protected 1260 token with the following semantic: 'This token is only valid when 1261 presented by a Client with the following identifier.' When the 1262 access token is then presented to the Resource Server how does it 1263 know that it was provided by the Client? It has to authenticate the 1264 Client! There are many choices for authenticating the Client to the 1265 Resource Server, for example by using client certificates in TLS 1266 [RFC5246], or pre-shared secrets within TLS [RFC4279]. The choice of 1267 the preferred authentication mechanism and credential type may depend 1268 on a number of factors, including 1270 o security properties 1271 o available infrastructure 1273 o library support 1275 o credential cost (financial) 1277 o performance 1279 o integration into the existing IT infrastructure 1281 o operational overhead for configuration and distribution of 1282 credentials 1284 This long list hints to the challenge of selecting at least one 1285 mandatory-to-implement Client authentication mechanism. 1287 A.2.3. Key Confirmation 1289 A variation of the mechanism of sender authentication described in 1290 Appendix A.2.2 is to replace authentication with the proof-of- 1291 possession of a specific (session) key, i.e., key confirmation. In 1292 this model the Resource Server would not authenticate the Client 1293 itself but would rather verify whether the Client knows the session 1294 key associated with a specific access token. Examples of this 1295 approach can be found with the OAuth 1.0 MAC token [RFC5849], 1296 Kerberos [RFC4120] when utilizing the AP_REQ/AP_REP exchange (see 1297 also [I-D.hardjono-oauth-kerberos] for a comparison between Kerberos 1298 and OAuth), the Holder-of-the-Key approach 1299 [I-D.tschofenig-oauth-hotk], and also the MAC token approach defined 1300 in this document. 1302 To illustrate key confirmation the first examples borrow from 1303 Kerberos and use symmetric key cryptography. Assume that the 1304 Authorization Server shares a long-term secret with the Resource 1305 Server, called K(Authorization Server-Resource Server). This secret 1306 would be established between them in an initial registration phase. 1307 When the Client requests an access token the Authorization Server 1308 creates a fresh and unique session key Ks and places it into the 1309 token encrypted with the long term key K(Authorization Server- 1310 Resource Server). Additionally, the Authorization Server attaches Ks 1311 to the response message to the Client (in addition to the access 1312 token itself) over a confidentiality protected channel. When the 1313 Client sends a request to the Resource Server it has to use Ks to 1314 compute a keyed message digest for the request (in whatever form or 1315 whatever layer). The Resource Server, when receiving the message, 1316 retrieves the access token, verifies it and extracts K(Authorization 1317 Server-Resource Server) to obtain Ks. This key Ks is then used to 1318 verify the keyed message digest of the request message. 1320 Note that in this example one could imagine that the mechanism to 1321 protect the token itself is based on a symmetric key based mechanism 1322 to avoid any form of public key infrastructure but this aspect is not 1323 further elaborated in the scenario. 1325 A similar mechanism can also be designed using asymmetric 1326 cryptography. When the Client requests an access token the 1327 Authorization Server creates an ephemeral public / privacy key pair 1328 (PK/SK) and places the public key PK into the protected token. When 1329 the Authorization Server returns the access token to the Client it 1330 also provides the PK/SK key pair over a confidentiality protected 1331 channel. When the Client sends a request to the Resource Server it 1332 has to use the privacy key SK to sign the request. The Resource 1333 Server, when receiving the message, retrieves the access token, 1334 verifies it and extracts the public key PK. It uses this ephemeral 1335 public key to verify the attached signature. 1337 A.2.4. Summary 1339 As a high level message, there are various ways how the threats can 1340 be mitigated and while the details of each solution is somewhat 1341 different they all ultimately accomplish the goal. 1343 The three approaches are: 1345 Confidentiality Protection: 1347 The weak point with this approach, which is briefly described in 1348 Appendix A.2.1, is that the Client has to be careful to whom it 1349 discloses the access token. What can be done with the token 1350 entirely depends on what rights the token entitles the presenter 1351 and what constraints it contains. A token could encode the 1352 identifier of the Client but there are scenarios where the Client 1353 is not authenticated to the Resource Server or where the 1354 identifier of the Client rather represents an application class 1355 rather than a single application instance. As such, it is 1356 possible that certain deployments choose a rather liberal approach 1357 to security and that everyone who is in possession of the access 1358 token is granted access to the data. 1360 Sender Constraint: 1362 The weak point with this approach, which is briefly described in 1363 Appendix A.2.2, is to setup the authentication infrastructure such 1364 that Clients can be authenticated towards Resource Servers. 1365 Additionally, Authorization Server must encode the identifier of 1366 the Client in the token for later verification by the Resource 1367 Server. Depending on the chosen layer for providing Client-side 1368 authentication there may be additional challenges due Web server 1369 load balancing, lack of API access to identity information, etc. 1371 Key Confirmation: 1373 The weak point with this approach, see Appendix A.2.3, is the 1374 increased complexity: a complete key distribution protocol has to 1375 be defined. 1377 In all cases above it has to be ensured that the Client is able to 1378 keep the credentials secret. 1380 A.3. Requirements 1382 In an attempt to address the threats described in Appendix A.1 the 1383 Bearer Token, which corresponds to the description in Appendix A.2.1, 1384 was standardized and the work on a JSON-based token format has been 1385 started [I-D.ietf-oauth-json-web-token]. The required capability to 1386 protected the content of a JSON token using integrity and 1387 confidentiality mechanisms is work in progress at the time of 1388 writing. 1390 Consequently, the purpose of the remaining document is to provide 1391 security that goes beyond the Bearer Token offered security 1392 protection. 1394 RFC 4962 [RFC4962] gives useful guidelines for designers of 1395 authentication and key management protocols. While RFC 4962 was 1396 written with the AAA framework used for network access authentication 1397 in mind the offered suggestions are useful for the design of other 1398 key management systems as well. The following requirements list 1399 applies OAuth 2.0 terminology to the requirements outlined in RFC 1400 4962. 1402 These requirements include 1404 Cryptographic Algorithm Independent: 1406 The key management protocol MUST be cryptographic algorithm 1407 independent. 1409 Strong, fresh session keys: 1411 Session keys MUST be strong and fresh. Each session deserves an 1412 independent session key, i.e., one that is generated specifically 1413 for the intended use. In context of OAuth this means that keying 1414 material is created in such a way that can only be used by the 1415 combination of a Client instance, protected resource, and 1416 authorization scope. 1418 Limit Key Scope: 1420 Following the principle of least privilege, parties MUST NOT have 1421 access to keying material that is not needed to perform their 1422 role. Any protocol that is used to establish session keys MUST 1423 specify the scope for session keys, clearly identifying the 1424 parties to whom the session key is available. 1426 Replay Detection Mechanism: 1428 The key management protocol exchanges MUST be replay protected. 1429 Replay protection allows a protocol message recipient to discard 1430 any message that was recorded during a previous legitimate 1431 dialogue and presented as though it belonged to the current 1432 dialogue. 1434 Authenticate All Parties: 1436 Each party in the key management protocol MUST be authenticated to 1437 the other parties with whom they communicate. Authentication 1438 mechanisms MUST maintain the confidentiality of any secret values 1439 used in the authentication process. Secrets MUST NOT be sent to 1440 another party without confidentiality protection. 1442 Authorization: 1444 Client and Resource Server authorization MUST be performed. These 1445 entities MUST demonstrate possession of the appropriate keying 1446 material, without disclosing it. Authorization is REQUIRED 1447 whenever a Client interacts with an Authorization Server. The 1448 authorization checking prevents an elevation of privilege attack, 1449 and it ensures that an unauthorized authorized is detected. 1451 Keying Material Confidentiality and Integrity: 1453 While preserving algorithm independence, confidentiality and 1454 integrity of all keying material MUST be maintained. 1456 Confirm Cryptographic Algorithm Selection: 1458 The selection of the "best" cryptographic algorithms SHOULD be 1459 securely confirmed. The mechanism SHOULD detect attempted roll- 1460 back attacks. 1462 Uniquely Named Keys: 1464 Key management proposals require a robust key naming scheme, 1465 particularly where key caching is supported. The key name 1466 provides a way to refer to a key in a protocol so that it is clear 1467 to all parties which key is being referenced. Objects that cannot 1468 be named cannot be managed. All keys MUST be uniquely named, and 1469 the key name MUST NOT directly or indirectly disclose the keying 1470 material. 1472 Prevent the Domino Effect: 1474 Compromise of a single Client MUST NOT compromise keying material 1475 held by any other Client within the system, including session keys 1476 and long-term keys. Likewise, compromise of a single Resource 1477 Server MUST NOT compromise keying material held by any other 1478 Resource Server within the system. In the context of a key 1479 hierarchy, this means that the compromise of one node in the key 1480 hierarchy must not disclose the information necessary to 1481 compromise other branches in the key hierarchy. Obviously, the 1482 compromise of the root of the key hierarchy will compromise all of 1483 the keys; however, a compromise in one branch MUST NOT result in 1484 the compromise of other branches. There are many implications of 1485 this requirement; however, two implications deserve highlighting. 1486 First, the scope of the keying material must be defined and 1487 understood by all parties that communicate with a party that holds 1488 that keying material. Second, a party that holds keying material 1489 in a key hierarchy must not share that keying material with 1490 parties that are associated with other branches in the key 1491 hierarchy. 1493 Bind Key to its Context: 1495 Keying material MUST be bound to the appropriate context. The 1496 context includes the following. 1498 * The manner in which the keying material is expected to be used. 1500 * The other parties that are expected to have access to the 1501 keying material. 1503 * The expected lifetime of the keying material. Lifetime of a 1504 child key SHOULD NOT be greater than the lifetime of its parent 1505 in the key hierarchy. 1507 Any party with legitimate access to keying material can determine 1508 its context. In addition, the protocol MUST ensure that all 1509 parties with legitimate access to keying material have the same 1510 context for the keying material. This requires that the parties 1511 are properly identified and authenticated, so that all of the 1512 parties that have access to the keying material can be determined. 1513 The context will include the Client and the Resource Server 1514 identities in more than one form. 1516 Authorization Restriction: 1518 If Client authorization is restricted, then the Client SHOULD be 1519 made aware of the restriction. 1521 Client Identity Confidentiality: 1523 A Client has identity confidentiality when any party other than 1524 the Resource Server and the Authorization Server cannot 1525 sufficiently identify the Client within the anonymity set. In 1526 comparison to anonymity and pseudonymity, identity confidentiality 1527 is concerned with eavesdroppers and intermediaries. A key 1528 management protocol SHOULD provide this property. 1530 Resource Owner Identity Confidentiality: 1532 Resource servers SHOULD be prevented from knowing the real or 1533 pseudonymous identity of the Resource Owner, since the 1534 Authorization Server is the only entity involved in verifying the 1535 Resource Owner's identity. 1537 Collusion: 1539 Resource Servers that collude can be prevented from using 1540 information related to the Resource Owner to track the individual. 1541 That is, two different Resource Servers can be prevented from 1542 determining that the same Resource Owner has authenticated to both 1543 of them. This requires that each Authorization Server obtains 1544 different keying material as well as different access tokens with 1545 content that does not allow identification of the Resource Owner. 1547 AS-to-RS Relationship Anonymity: 1549 This MAC Token security does not provide AAS-to-RS Relationship 1550 Anonymity since the Client has to inform the resource server about 1551 the Resource Server it wants to talk to. The Authorization Server 1552 needs to know how to encrypt the session key the Client and the 1553 Resource Server will be using. 1555 As an additional requirement a solution MUST enable support for 1556 channel bindings. The concept of channel binding, as defined in 1557 [RFC5056], allows applications to establish that the two end-points 1558 of a secure channel at one network layer are the same as at a higher 1559 layer by binding authentication at the higher layer to the channel at 1560 the lower layer. 1562 Furthermore, there are performance concerns specifically with the 1563 usage of asymmetric cryptography. As such, the requirement can be 1564 phrases as 'faster is better'. [QUESTION: How are we trading the 1565 benefits of asymmetric cryptography against the performance impact?] 1567 Finally, there are threats that relate to the experience of the 1568 software developer as well as operational policies. Verifying the 1569 servers identity in TLS is discussed at length in [RFC6125]. 1571 A.4. Use Cases 1573 This section lists use cases that provide additional requirements and 1574 constrain the solution space. 1576 A.4.1. Access to an 'Unprotected' Resource 1578 This use case is for a web client that needs to access a resource 1579 where no integrity and confidentiality protection is provided for the 1580 exchange of data using TLS following the OAuth-based request. In 1581 accessing the resource, the request, which includes the access token, 1582 must be protected against replay, and modification. 1584 While it is possible to utilize bearer tokens in this scenario, as 1585 described in [RFC6750], with TLS protection when the request to the 1586 protected resource is made there may be the desire to avoid using TLS 1587 between the client and the resource server at all. In such a case 1588 the bearer token approach is not possible since it relies on TLS for 1589 ensuring integrity and confidentiality protection of the access token 1590 exchange since otherwise replay attacks are possible: First, an 1591 eavesdropper may steal an access token and represent it at a 1592 different resource server. Second, an eavesdropper may steal an 1593 access token and replay it against the same resource server at a 1594 later point in time. In both cases, if the attack is successful, the 1595 adversary gets access to the resource owners data or may perform an 1596 operation selected by the adversary (e.g., sending a message). Note 1597 that the adversary may obtain the access token (if the 1598 recommendations in [RFC6749] and [RFC6750] are not followed) using a 1599 number of ways, including eavesdropping the communication on the 1600 wireless link. 1602 Consequently, the important assumption in this use case is that a 1603 resource server does not have TLS support and the security solution 1604 should work in such a scenario. Furthermore, it may not be necessary 1605 to provide authentication of the resource server towards the client. 1607 A.4.2. Offering Application Layer End-to-End Security 1609 In Web deployments resource servers are often placed behind load 1610 balancers. Note that the load balancers are deployed by the same 1611 organization that operates the resource servers. These load 1612 balancers may terminate Transport Layer Security (TLS) and the 1613 resulting HTTP traffic may be transmitted in clear from the load 1614 balancer to the resource server. With application layer security 1615 independent of the underlying TLS security it is possible to allow 1616 application servers to perform cryptographic verification on an end- 1617 to-end basis. 1619 The key aspect in this use case is therefore to offer end-to-end 1620 security in the presence of load balancers via application layer 1621 security. 1623 A.4.3. Preventing Access Token Re-Use by the Resource Server 1625 Imagine a scenario where a resource server that receives a valid 1626 access token re-uses it with other resource server. The reason for 1627 re-use may be malicious or may well be legitimate. In a legitimate 1628 use case consider a case where the resource server needs to consult 1629 third party resource servers to complete the requested operation. In 1630 both cases it may be assumed that the scope of the access token is 1631 sufficiently large that it allows such a re-use. For example, 1632 imagine a case where a company operates email services as well as 1633 picture sharing services and that company had decided to issue access 1634 tokens with a scope that allows access to both services. 1636 With this use case the desire is to prevent such access token re-use. 1637 This also implies that the legitimate use cases require additional 1638 enhancements for request chaining. 1640 A.4.4. TLS Channel Binding Support 1642 In this use case we consider the scenario where an OAuth 2.0 request 1643 to a protected resource is secured using TLS but the client and the 1644 resource server demand that the underlying TLS exchange is bound to 1645 additional application layer security to prevent cases where the TLS 1646 connection is terminated at a load balancer or a TLS proxy is used 1647 that splits the TLS connection into two separate connections. 1649 In this use case additional information is conveyed to the resource 1650 server to ensure that no entity entity has tampered with the TLS 1651 connection. 1653 Authors' Addresses 1655 Justin Richer 1656 The MITRE Corporation 1658 Email: jricher@mitre.org 1660 William Mills 1661 Yahoo! Inc. 1663 Email: wmills@yahoo-inc.com 1665 Hannes Tschofenig (editor) 1666 Austria 1668 Email: Hannes.Tschofenig@gmx.net 1669 URI: http://www.tschofenig.priv.at 1671 Phil Hunt 1672 Oracle Corporation 1674 Email: phil.hunt@yahoo.com