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