idnits 2.17.1 draft-ietf-oauth-v2-http-mac-03.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 (February 25, 2013) is 4077 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 398, but not defined == Unused Reference: 'RFC2616' is defined on line 1009, but no explicit reference was found in the text == Unused Reference: 'RFC3986' is defined on line 1018, but no explicit reference was found in the text == Unused Reference: 'RFC6265' is defined on line 1035, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-22 == Outdated reference: A later version (-40) exists of draft-ietf-jose-json-web-encryption-08 == Outdated reference: A later version (-32) exists of draft-ietf-oauth-json-web-token-06 == Outdated reference: A later version (-06) exists of draft-richer-oauth-introspection-03 -- Possible downref: Normative reference to a draft: ref. 'I-D.tschofenig-oauth-audience' -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST-FIPS-180-3' ** 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) Summary: 5 errors (**), 0 flaws (~~), 10 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Richer 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track W. Mills 5 Expires: August 29, 2013 Yahoo! Inc. 6 H. Tschofenig, Ed. 7 Nokia Siemens Networks 8 February 25, 2013 10 OAuth 2.0 Message Authentication Code (MAC) Tokens 11 draft-ietf-oauth-v2-http-mac-03 13 Abstract 15 This specification describes how to use MAC Tokens in HTTP requests 16 to access OAuth 2.0 protected resources. An OAuth client willing to 17 access a protected resource needs to demonstrate possession of a 18 crytographic key by using it with a keyed message digest function to 19 the request. 21 The document also defines a key distribution protocol for obtaining a 22 fresh session key. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on August 29, 2013. 41 Copyright Notice 43 Copyright (c) 2013 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 4. Key Distribution . . . . . . . . . . . . . . . . . . . . . . . 7 62 4.1. Session Key Transport to Client . . . . . . . . . . . . . 7 63 4.2. Session Key Transport to Resource Server . . . . . . . . . 9 64 5. The Authenticator . . . . . . . . . . . . . . . . . . . . . . 10 65 5.1. The Authenticator . . . . . . . . . . . . . . . . . . . . 10 66 5.2. MAC Input String . . . . . . . . . . . . . . . . . . . . . 13 67 5.3. Keyed Message Digest Algorithms . . . . . . . . . . . . . 14 68 5.3.1. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . . 14 69 5.3.2. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . . 14 70 6. Verifying the Authenticator . . . . . . . . . . . . . . . . . 15 71 6.1. Timestamp Verification . . . . . . . . . . . . . . . . . . 15 72 6.2. Error Handling . . . . . . . . . . . . . . . . . . . . . . 16 73 7. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 17 75 8.1. Key Distribution . . . . . . . . . . . . . . . . . . . . . 17 76 8.2. Offering Confidentiality Protection for Access to 77 Protected Resources . . . . . . . . . . . . . . . . . . . 17 78 8.3. Authentication of Resource Servers . . . . . . . . . . . . 18 79 8.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 18 80 8.5. Entropy of Session Keys . . . . . . . . . . . . . . . . . 18 81 8.6. Denial of Service / Resource Exhaustion Attacks . . . . . 19 82 8.7. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 19 83 8.8. CSRF Attacks . . . . . . . . . . . . . . . . . . . . . . . 19 84 8.9. Protecting HTTP Header Fields . . . . . . . . . . . . . . 20 85 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 86 9.1. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 20 87 9.2. MAC Token Algorithm Registry . . . . . . . . . . . . . . . 20 88 9.2.1. Registration Template . . . . . . . . . . . . . . . . 21 89 9.2.2. Initial Registry Contents . . . . . . . . . . . . . . 21 90 9.3. OAuth Access Token Type Registration . . . . . . . . . . . 22 91 9.3.1. The "mac" OAuth Access Token Type . . . . . . . . . . 22 92 9.4. OAuth Parameters Registration . . . . . . . . . . . . . . 22 93 9.4.1. The "mac_key" OAuth Parameter . . . . . . . . . . . . 22 94 9.4.2. The "mac_algorithm" OAuth Parameter . . . . . . . . . 22 95 9.4.3. The "kid" OAuth Parameter . . . . . . . . . . . . . . 23 96 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 97 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 98 11.1. Normative References . . . . . . . . . . . . . . . . . . . 23 99 11.2. Informative References . . . . . . . . . . . . . . . . . . 25 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 102 1. Introduction 104 This specification describes how to use MAC Tokens in HTTP requests 105 and responses to access protected resources via the OAuth 2.0 106 protocol [RFC6749]. An OAuth client willing to access a protected 107 resource needs to demonstrate possession of a symmetric key by using 108 it with a keyed message digest function to the request. The keyed 109 message digest function is computed over a flexible set of parameters 110 from the HTTP message. 112 The MAC Token mechanism requires the establishment of a shared 113 symmetric key between the client and the resource server. This 114 specification defines a three party key distribution protocol to 115 dynamically distribute this session key from the authorization server 116 to the client and the resource server. 118 The design goal for this mechanism is to support the requirements 119 outlined in [I-D.tschofenig-oauth-security]. In particular, when a 120 server uses this mechanism, a passive attacker will be unable to use 121 an eavesdropped access token exchanged between the client and the 122 resource server. In addition, this mechanism helps secure the access 123 token against leakage when sent over a secure channel to the wrong 124 resource server if the client provided information about the resource 125 server it wants to interact with in the request to the authorization 126 server. 128 Since a keyed message digest only provides integrity protection and 129 data-origin authentication confidentiality protection can only be 130 added by the usage of Transport Layer Security (TLS). This 131 specification provides a mechanism for channel binding is included to 132 ensure that a TLS channel is not terminated prematurely and indeed 133 covers the entire end-to-end communication. 135 2. Terminology 137 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 138 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 139 specification are to be interpreted as described in [RFC2119]. 141 This specification uses the Augmented Backus-Naur Form (ABNF) 142 notation of [I-D.ietf-httpbis-p1-messaging]. Additionally, the 143 following rules are included from [RFC2617]: auth-param. 145 Session Key: 147 The terms mac key, session key, and symmetric key are used 148 interchangably and refer to the cryptographic keying material 149 established between the client and the resource server. This 150 temporary key used between the client and the resource server, 151 with a lifetime limited to the lifetime of the access token. This 152 session key is generated by the authorization server. 154 Authenticator: 156 A record containing information that can be shown to have been 157 recently generated using the session key known only by the client 158 and the resource server. 160 Message Authentication Code (MAC): 162 Message authentication codes (MACs) are hash functions that take 163 two distinct inputs, a message and a secret key, and produce a 164 fixed-size output. The design goal is that it is 165 practically infeasible to produce the same output without 166 knowledge of the key. The terms keyed message digest functions 167 and MACs are used interchangably. 169 3. Architecture 171 The architecture of the proposal described in this document assumes 172 that the authorization server acts as a trusted third party that 173 provides session keys to clients and to resource servers. These 174 session keys are used by the client and the resource server as input 175 to a MAC. In order to obtain the session key the client interacts 176 with the authorization server as part of the a normal grant exchange. 177 This is shown in an abstract way in Figure 1. Together with the 178 access token the authorization server returns a session key (in the 179 mac_key parameter) and several other parameters. The resource server 180 obtains the session key via the access token. Both of these two key 181 distribution steps are described in more detail in Section 4. 183 +---------------+ 184 ^| | AS-RS Key 185 // | Authorization |<******* 186 / | Server | * 187 // | | * 188 / | | * 189 (I) // /+---------------+ * 190 Access / // * 191 Token / / * 192 Request// // (II) Access Token * 193 / / +Session Key (SK) * 194 // // * 195 / v v 196 +-----------+ +------------+ 197 | | | | 198 | | | Resource | 199 | Client | | Server | 200 | | | | 201 | | | | 202 +-----------+ +------------+ 204 ****: Out-of-Band Long-Term Key Establishment 205 ----: Dynamic Session Key Distribution 207 Figure 1: Architecture: Interaction between the Client and the 208 Authorization Server. 210 Once the client has obtained the necessary access token and the 211 session key (including parameters) it can start to interact with the 212 resource server. To demonstrate possession of the session key it 213 computes a MAC and adds various fields to the outgoing request 214 message. We call this structure the "Authenticator". The server 215 evaluates the request, includes an Authenticator and returns a 216 response back to the client. Since the access token is valid for a 217 period of time the resource server may decide to cache it so that it 218 does not need to be provided in every request from the client. This 219 interaction is shown in Figure 2. 221 +---------------+ 222 | | 223 | Authorization | 224 | Server | 225 | | 226 | | 227 +---------------+ 229 +-----------+ Authenticator (a) +------------+ 230 | |---------------------->| | 231 | | [+Access Token] | Resource | 232 | Client | | Server | 233 | | Authenticator (b) | | 234 | |<----------------------| | 235 +-----------+ +------------+ 237 ^ ^ 238 | | 239 | | 240 SK SK 241 +param +param 243 Figure 2: Architecture: Interaction between the Client and the 244 Resource Server. 246 4. Key Distribution 248 For this scheme to function a session key must be available to the 249 client and the resource server, which is then used as a parameter in 250 the keyed message digest function. This document describes the key 251 distribution mechanism that uses the authorization server as a 252 trusted third party, which ensures that the session key is 253 transported from the authorization server to the client and the 254 resource server. 256 4.1. Session Key Transport to Client 258 Authorization servers issue MAC Tokens based on requests from 259 clients. The request MUST include the audience parameter defined in 260 [I-D.tschofenig-oauth-audience], which indicates the resource server 261 the client wants to interact with. This specification assumes use of 262 the 'Authorization Code' grant. If the request is processed 263 successfully by the authorization server it MUST return at least the 264 following parameters to the client: 266 kid 268 The name of the key (key id), which is an identifier generated 269 by the resource server. It is RECOMMENDED that the 270 authorization server generates this key id by computing a hash 271 over the access_token, for example using SHA-1, and to encode 272 it in a base64 format. 274 access_token 276 The OAuth 2.0 access token. 278 mac_key 280 The session key generated by the authorization server. Note 281 that the lifetime of the session key is equal to the lifetime 282 of the access token. 284 mac_algorithm 286 The MAC algorithm used to calculate the request MAC. The value 287 MUST be one of "hmac-sha-1", "hmac-sha-256", or a registered 288 extension algorithm name as described in Section 9.2. The 289 authorization server is assumed to know the set of algorithms 290 supported by the client and the resource server. It selects an 291 algorithm that meets the security policies and is supported by 292 both nodes. 294 For example: 296 HTTP/1.1 200 OK 297 Content-Type: application/json 298 Cache-Control: no-store 300 { 301 "access_token": 302 "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0. 303 pwaFh7yJPivLjjPkzC-GeAyHuy7AinGcS51AZ7TXnwkC80Ow1aW47kcT_UV54ubo 304 nONbeArwOVuR7shveXnwPmucwrk_3OCcHrCbE1HR-Jfme2mF_WR3zUMcwqmU0RlH 305 kwx9txo_sKRasjlXc8RYP-evLCmT1XRXKjtY5l44Gnh0A84hGvVfMxMfCWXh38hi 306 2h8JMjQHGQ3mivVui5lbf-zzb3qXXxNO1ZYoWgs5tP1-T54QYc9Bi9wodFPWNPKB 307 kY-BgewG-Vmc59JqFeprk1O08qhKQeOGCWc0WPC_n_LIpGWH6spRm7KGuYdgDMkQ 308 bd4uuB0uPPLx_euVCdrVrA. 309 AxY8DCtDaGlsbGljb3RoZQ. 310 7MI2lRCaoyYx1HclVXkr8DhmDoikTmOp3IdEmm4qgBThFkqFqOs3ivXLJTku4M0f 311 laMAbGG_X6K8_B-0E-7ak-Olm_-_V03oBUUGTAc-F0A. 312 OwWNxnC-BMEie-GkFHzVWiNiaV3zUHf6fCOGTwbRckU", 313 "token_type":"mac", 314 "expires_in":3600, 315 "refresh_token":"8xLOxBtZp8", 316 "kid":"22BIjxU93h/IgwEb4zCRu5WF37s=", 317 "mac_key":"adijq39jdlaska9asud", 318 "mac_algorithm":"hmac-sha-256" 319 } 321 4.2. Session Key Transport to Resource Server 323 The transport of the mac_key from the authorization server to the 324 resource server is accomplished by conveying the encrypting mac_key 325 inside the access token. At the time of writing only one 326 standardized format for carrying the access token is defined: the 327 JSON Web Token (JWT) [I-D.ietf-oauth-json-web-token]. Note that the 328 header of the JSON Web Encryption (JWE) structure 329 [I-D.ietf-jose-json-web-encryption], which is a JWT with encrypted 330 content, MUST contain a key id (kid) in the header to allow the 331 resource server to select the appropriate keying material for 332 decryption. This keying material is a symmetric or an asymmetric 333 long-term key established between the resource server and the 334 authorization server, as shown in Figure 1 as AS-RS key. The 335 establishment of this long-term key is outside the scope of this 336 specification. 338 This document defines two new claims to be carried in the JWT: 339 mac_key, kid. These two parameters match the content of the mac_key 340 and the kid conveyed to the client, as shown in Section 4.1. 342 kid 344 The name of the key (key id), which is an identifier generated 345 by the resource server. 347 mac_key 349 The session key generated by the authorization server. 351 This example shows a JWT claim set without header and without 352 encryption: 354 {"iss":"authorization-server.example.com", 355 "exp":1300819380, 356 "kid":"22BIjxU93h/IgwEb4zCRu5WF37s=", 357 "mac_key":"adijq39jdlaska9asud", 358 "aud":"apps.example.com" 359 } 361 QUESTIONS: An alternative to the use of a JWT to convey the access 362 token with the encrypted mac_key is use the token introspect 363 [I-D.richer-oauth-introspection]. What mechanism should be 364 described? What should be mandatory to implement? 365 QUESTIONS: The above description assumes that the entire access 366 token is encrypted but it would be possible to only encrypt the 367 session key and to only apply integrity protection to other 368 fields. Is this desireable? 370 5. The Authenticator 372 To access a protected resource the client must be in the possession 373 of a valid set of session key provided by the authorization server. 374 The client constructs the authenticator, as described in Section 5.1. 376 5.1. The Authenticator 378 The client constructs the authenticator and adds the resulting fields 379 to the HTTP request using the "Authorization" request header field. 380 The "Authorization" request header field uses the framework defined 381 by [RFC2617]. To include the authenticator in a subsequent response 382 from the authorization server to the client the WWW-Authenticate 383 header is used. For further exchanges a new, yet-to-be-defined 384 header will be used. 386 authenticator = "MAC" 1*SP #params 388 params = id / ts / seq-nr / access_token / mac / h / cb 390 kid = "kid" "=" string-value 391 ts = "ts" "=" ( <"> timestamp <"> ) / timestamp 392 seq-nr = "seq-nr" "=" string-value 393 access_token = "access_token" "=" b64token 394 mac = "mac" "=" string-value 395 cb = "cb" "=" token 396 h = "h" "=" h-tag 397 h-tag = %x68 [FWS] "=" [FWS] hdr-name 398 *( [FWS] ":" [FWS] hdr-name ) 399 hdr-name = token 401 timestamp = 1*DIGIT 402 string-value = ( <"> plain-string <"> ) / plain-string 403 plain-string = 1*( %x20-21 / %x23-5B / %x5D-7E ) 405 b64token = 1*( ALPHA / DIGIT / 406 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 408 The header attributes are set as follows: 410 kid 412 REQUIRED. The key identifier. 414 ts 416 REQUIRED. The timestamp. The value MUST be a positive integer 417 set by the client when making each request to the number of 418 milliseconds since 1 January 1970. 420 The JavaScript getTime() function or the Java 421 System.currentTimeMillis() function, for example, produce such 422 a timestamp. 424 seq-nr 426 OPTIONAL. This optional field includes the initial sequence 427 number to be used by the messages exchange between the client 428 and the server when the replay protection provided by the 429 timestamp is not sufficient enough replay protection. This 430 field specifies the initial sequence number for messages from 431 the client to the server. When included in the response 432 message, the initial sequence number is that for messages from 433 the server to the client. Sequence numbers fall in the range 0 434 through 2^64 - 1 and wrap to zero following the value 2^64 - 1. 436 The initial sequence number SHOULD be random and uniformly 437 distributed across the full space of possible sequence numbers, 438 so that it cannot be guessed by an attacker and so that it and 439 the successive sequence numbers do not repeat other sequences. 440 In the event that more than 2^64 messages are to be generated 441 in a series of messages, rekeying MUST be performed before 442 sequence numbers are reused. Rekeying requires a new access 443 token to be requested. 445 access_token 447 CONDITIONAL. The access_token MUST be included in the first 448 request from the client to the server but MUST NOT be included 449 in a subsequent response and in a further protocol exchange. 451 mac 453 REQUIRED. The result of the keyed message digest computation, 454 as described in Section 5.3. 456 cb 458 OPTIONAL. This field carries the channel binding value from 459 RFC 5929 [RFC5929] in the following format: cb= channel- 460 binding-type ":" channel-binding-content. RFC 5929 offers two 461 types of channel bindings for TLS. First, there is the 'tls- 462 server-end-point' channel binding, which uses a hash of the TLS 463 server's certificate as it appears, octet for octet, in the 464 server's Certificate message. The second channel binding is 465 'tls-unique', which uses the first TLS Finished message sent 466 (note: the Finished struct, not the TLS record layer message 467 containing it) in the most recent TLS handshake of the TLS 468 connection being bound to. As an example, the cb field may 469 contain cb=tls-unique:9382c93673d814579ed1610d3 470 h 472 OPTIONAL. This field contains a colon-separated list of header 473 field names that identify the header fields presented to the 474 keyed message digest algorithm. If the 'h' header field is 475 absent then the following value is set by default: h="host". 476 The field MUST contain the complete list of header fields in 477 the order presented to the keyed message digest algorithm. The 478 field MAY contain names of header fields that do not exist at 479 the time of computing the keyed message digest; nonexistent 480 header fields do not contribute to the keyed message digest 481 computation (that is, they are treated as the null input, 482 including the header field name, the separating colon, the 483 header field value, and any CRLF terminator). By including 484 header fields that do not actually exist in the keyed message 485 digest computation, the client can allow the resource server to 486 detect insertion of those header fields by intermediaries. 487 However, since the client cannot possibly know what header 488 fields might be defined in the future, this mechanism cannot be 489 used to prevent the addition of any possible unknown header 490 fields. The field MAY contain multiple instances of a header 491 field name, meaning multiple occurrences of the corresponding 492 header field are included in the header hash. The field MUST 493 NOT include the mac header field. Folding whitespace (FWS) MAY 494 be included on either side of the colon separator. Header 495 field names MUST be compared against actual header field names 496 in a case-insensitive manner. This list MUST NOT be empty. 497 See Section 8 for a discussion of choosing header fields. 499 Attributes MUST NOT appear more than once. Attribute values are 500 limited to a subset of ASCII, which does not require escaping, as 501 defined by the plain-string ABNF. 503 5.2. MAC Input String 505 An HTTP message can either be a request from client to server or a 506 response from server to client. Syntactically, the two types of 507 message differ only in the start-line, which is either a request-line 508 (for requests) or a status-line (for responses). 510 Two parameters serve as input to a keyed message digest function: a 511 key and an input string. Depending on the communication direction 512 either the request-line or the status-line is used as the first value 513 followed by the HTTP header fields listed in the 'h' parameter. 514 Then, the timestamp field and the seq-nr field (if present) is 515 concatenated. 517 As an example, consider the HTTP request with the new line separator 518 character represented by "\n" for editorial purposes only. The h 519 parameter is set to h=host, the kid is 314906b0-7c55, and the 520 timstamp is 1361471629. 522 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1 523 Host: example.com 524 Hello World! 526 The resulting string is: 528 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1\n 529 1361471629\n 530 example.com\n 532 5.3. Keyed Message Digest Algorithms 534 The client uses a cryptographic algorithm together with a session key 535 to calculate a keyed message digest. This specification defines two 536 algorithms: "hmac-sha-1" and "hmac-sha-256", and provides an 537 extension registry for additional algorithms. 539 5.3.1. hmac-sha-1 541 "hmac-sha-1" uses the HMAC-SHA1 algorithm, as defined in [RFC2104]: 543 mac = HMAC-SHA1 (key, text) 545 Where: 547 text 549 is set to the value of the input string as described in 550 Section 5.2, 551 key 553 is set to the session key provided by the authorization server, 554 and 555 mac 557 is used to set the value of the "mac" attribute, after the 558 result string is base64-encoded per Section 6.8 of [RFC2045]. 560 5.3.2. hmac-sha-256 562 "hmac-sha-256" uses the HMAC algorithm, as defined in [RFC2104], with 563 the SHA-256 hash function, defined in [NIST-FIPS-180-3]: 565 mac = HMAC-SHA256 (key, text) 567 Where: 569 text 571 is set to the value of the input string as described in 572 Section 5.2, 573 key 575 is set to the session key provided by the authorization server, 576 and 577 mac 579 is used to set the value of the "mac" attribute, after the 580 result string is base64-encoded per Section 6.8 of [RFC2045]. 582 6. Verifying the Authenticator 584 When receiving a message with an authenticator the following steps 585 are performed: 587 1. When the authorization server receives a message with a new 588 access token (and consequently a new session key) then it obtains 589 the session key by retrieving the content of the access token 590 (which requires decryption of the session key contained inside 591 the token). The content of the access token, in particular the 592 audience field and the scope, MUST be verified as described in 593 Alternatively, the kid parameter is used to look-up a cached 594 session key from a previous exchange. 595 2. Recalculate the keyed message digest, as described in 596 Section 5.3, and compare the request MAC to the value received 597 from the client via the "mac" attribute. 598 3. Verify that no replay took place by comparing the value of the ts 599 (timestamp) header with the local time. The processing of 600 authenticators with stale timestamps is described in Section 6.1. 602 Error handling is described in Section 6.2. 604 6.1. Timestamp Verification 606 The timestamp field enables the server to detect replay attacks. 607 Without replay protection, an attacker can use an eavesdropped 608 request to gain access to a protected resource. The following 609 procedure is used to detect replays: 611 o At the time the first request is received from the client for each 612 key identifier, calculate the difference (in seconds) between the 613 request timestamp and the local clock. The difference is stored 614 locally for later use. 615 o For each subsequent request, apply the request time delta to the 616 timestamp included in the message to calculate the adjusted 617 request time. 618 o Verify that the adjusted request time is within the allowed time 619 period defined by the authorization server. If the local time and 620 the calculated time based in the request differ by more than the 621 allowable clock skew (e.g., 5 minutes) a replay has to be assumed. 623 6.2. Error Handling 625 If the protected resource request does not include an access token, 626 lacks the keyed message digest, contains an invalid key identifier, 627 or is malformed, the server SHOULD return a 401 (Unauthorized) HTTP 628 status code. 630 For example: 632 HTTP/1.1 401 Unauthorized 633 WWW-Authenticate: MAC 635 The "WWW-Authenticate" request header field uses the framework 636 defined by [RFC2617] as follows: 638 challenge = "MAC" [ 1*SP #param ] 639 param = error / auth-param 640 error = "error" "=" ( token / quoted-string) 642 Each attribute MUST NOT appear more than once. 644 If the protected resource request included a MAC "Authorization" 645 request header field and failed authentication, the server MAY 646 include the "error" attribute to provide the client with a human- 647 readable explanation why the access request was declined to assist 648 the client developer in identifying the problem. 650 For example: 652 HTTP/1.1 401 Unauthorized 653 WWW-Authenticate: MAC error="The MAC credentials expired" 655 7. Example 657 [Editor's Note: Full example goes in here.] 659 8. Security Considerations 661 As stated in [RFC2617], the greatest sources of risks are usually 662 found not in the core protocol itself but in policies and procedures 663 surrounding its use. Implementers are strongly encouraged to assess 664 how this protocol addresses their security requirements and the 665 security threats they want to mitigate. 667 8.1. Key Distribution 669 This specification describes a key distribution mechanism for 670 providing the session key (and parameters) from the authorization 671 server to the client. The interaction between the client and the 672 authorization server requires Transport Layer Security (TLS) with a 673 ciphersuite offering confidentiality protection. The session key 674 MUST NOT be transmitted in clear since this would completely destroy 675 the security benefits of the proposed scheme. Furthermore, the 676 obtained session key MUST be stored so that only the client instance 677 has access to it. Storing the session key, for example, in a cookie 678 allows other parties to gain access to this confidential information 679 and compromises the security of the protocol. 681 8.2. Offering Confidentiality Protection for Access to Protected 682 Resources 684 This specification can be used with and without Transport Layer 685 Security (TLS). 687 Without TLS this protocol provides a mechanism for verifying the 688 integrity of requests and responses, it provides no confidentiality 689 protection. Consequently, eavesdroppers will have full access to 690 request content and further messages exchanged between the client and 691 the resource server. This could be problematic when data is 692 exchanged that requires care, such as personal data. 694 When TLS is used then confidentiality can be ensured and with the use 695 of the TLS channel binding feature it ensures that the TLS channel is 696 cryptographically bound to the used MAC token. TLS in combination 697 with channel bindings bound to the MAC token provide security 698 superiour to the OAuth Bearer Token. 700 The use of TLS in combination with the MAC token is highly 701 recommended to ensure the confidentiality of the user's data. 703 8.3. Authentication of Resource Servers 705 This protocol allows clients to verify the authenticity of resource 706 servers in two ways: 707 1. The resource server demonstrates possession of the session key by 708 computing a keyed message digest function over a number of HTTP 709 fields in the response to the request from the client. 710 2. When TLS is used the resource server is authenticated as part of 711 the TLS handshake. 713 8.4. Plaintext Storage of Credentials 715 The MAC key works in the same way passwords do in traditional 716 authentication systems. In order to compute the keyed message 717 digest, the client and the resource server must have access to the 718 MAC key in plaintext form. 720 If an attacker were to gain access to these MAC keys - or worse, to 721 the resource server's or the authorization server's database of all 722 such MAC keys - he or she would be able to perform any action on 723 behalf of any client. 725 It is therefore paramount to the security of the protocol that these 726 session keys are protected from unauthorized access. 728 8.5. Entropy of Session Keys 730 Unless TLS is used between the client and the resource server, 731 eavesdroppers will have full access to requests sent by the client. 732 They will thus be able to mount offline brute-force attacks to 733 recover the session key used to compute the keyed message digest. 734 Authorization servers should be careful to generate fresh and unique 735 session keys with sufficient entrophy to resist such attacks for at 736 least the length of time that the session keys are valid. 738 For example, if a session key is valid for one day, authorization 739 servers must ensure that it is not possible to mount a brute force 740 attack that recovers the session key in less than one day. Of 741 course, servers are urged to err on the side of caution, and use the 742 longest session key reasonable. 744 It is equally important that the pseudo-random number generator 745 (PRNG) used to generate these session keys be of sufficiently high 746 quality. Many PRNG implementations generate number sequences that 747 may appear to be random, but which nevertheless exhibit patterns, 748 which make cryptanalysis easier. Implementers are advised to follow 749 the guidance on random number generation in [RFC4086]. 751 8.6. Denial of Service / Resource Exhaustion Attacks 753 This specification includes a number of features which may make 754 resource exhaustion attacks against resource servers possible. For 755 example, a resource server may need to need to consult backend 756 databases and the authorization server to verify an incoming request 757 including an access token before granting access to the protected 758 resource. 760 An attacker may exploit this to perform a denial of service attack by 761 sending a large number of invalid requests to the server. The 762 computational overhead of verifying the keyed message digest alone 763 is, however, not sufficient to mount a denial of service attack since 764 keyed message digest functions belong to the computationally fastest 765 cryptographic algorithms. The usage of TLS does, however, require 766 additional computational capabity to perform the asymmetric 767 cryptographic operations. For a brief discussion about denial of 768 service vulnerabilities of TLS please consult Appendix F.5 of RFC 769 5246 [RFC5246]. 771 8.7. Timing Attacks 773 This specification makes use of HMACs, for which a signature 774 verification involves comparing the received MAC string to the 775 expected one. If the string comparison operator operates in 776 observably different times depending on inputs, e.g. because it 777 compares the strings character by character and returns a negative 778 result as soon as two characters fail to match, then it may be 779 possible to use this timing information to determine the expected 780 MAC, character by character. 782 Implementers are encouraged to use fixed-time string comparators for 783 MAC verification. This means that the comparison operation is not 784 terminated once a mismatch is found. 786 8.8. CSRF Attacks 788 A Cross-Site Request Forgery attack occurs when a site, evil.com, 789 initiates within the victim's browser the loading of a URL from or 790 the posting of a form to a web site where a side-effect will occur, 791 e.g. transfer of money, change of status message, etc. To prevent 792 this kind of attack, web sites may use various techniques to 793 determine that the originator of the request is indeed the site 794 itself, rather than a third party. The classic approach is to 795 include, in the set of URL parameters or form content, a nonce 796 generated by the server and tied to the user's session, which 797 indicates that only the server could have triggered the action. 799 Recently, the Origin HTTP header has been proposed and deployed in 800 some browsers. This header indicates the scheme, host, and port of 801 the originator of a request. Some web applications may use this 802 Origin header as a defense against CSRF. 804 To keep this specification simple, HTTP headers are not part of the 805 string to be MAC'ed. As a result, MAC authentication cannot defend 806 against header spoofing, and a web site that uses the Host header to 807 defend against CSRF attacks cannot use MAC authentication to defend 808 against active network attackers. Sites that want the full 809 protection of MAC Authentication should use traditional, cookie-tied 810 CSRF defenses. 812 8.9. Protecting HTTP Header Fields 814 This specification provides flexibility for selectively protecting 815 header fields and even the body of the message. At a minimum the 816 following fields are included in the keyed message digest. 818 9. IANA Considerations 820 9.1. JSON Web Token Claims 822 This document adds the following claims to the JSON Web Token Claims 823 registry established with [I-D.ietf-oauth-json-web-token]: 824 o Claim Name: "kid" 825 o Change Controller: IETF 826 o Specification Document(s): [[ this document ]] 827 o Claim Name: "mac_key" 828 o Change Controller: IETF 829 o Specification Document(s): [[ this document ]] 831 9.2. MAC Token Algorithm Registry 833 This specification establishes the MAC Token Algorithm registry. 835 Additional keyed message digest algorithms are registered on the 836 advice of one or more Designated Experts (appointed by the IESG or 837 their delegate), with a Specification Required (using terminology 838 from [RFC5226]). However, to allow for the allocation of values 839 prior to publication, the Designated Expert(s) may approve 840 registration once they are satisfied that such a specification will 841 be published. 843 Registration requests should be sent to the [TBD]@ietf.org mailing 844 list for review and comment, with an appropriate subject (e.g., 845 "Request for MAC Algorithm: example"). [[ Note to RFC-EDITOR: The 846 name of the mailing list should be determined in consultation with 847 the IESG and IANA. Suggested name: http-mac-ext-review. ]] 849 Within at most 14 days of the request, the Designated Expert(s) will 850 either approve or deny the registration request, communicating this 851 decision to the review list and IANA. Denials should include an 852 explanation and, if applicable, suggestions as to how to make the 853 request successful. 855 Decisions (or lack thereof) made by the Designated Expert can be 856 first appealed to Application Area Directors (contactable using 857 app-ads@tools.ietf.org email address or directly by looking up their 858 email addresses on http://www.iesg.org/ website) and, if the 859 appellant is not satisfied with the response, to the full IESG (using 860 the iesg@iesg.org mailing list). 862 IANA should only accept registry updates from the Designated 863 Expert(s), and should direct all requests for registration to the 864 review mailing list. 866 9.2.1. Registration Template 868 Algorithm name: 870 The name requested (e.g., "example"). 871 Change controller: 873 For standards-track RFCs, state "IETF". For others, give the name 874 of the responsible party. Other details (e.g., postal address, 875 e-mail address, home page URI) may also be included. 876 Specification document(s): 878 Reference to document that specifies the algorithm, preferably 879 including a URI that can be used to retrieve a copy of the 880 document. An indication of the relevant sections may also be 881 included, but is not required. 883 9.2.2. Initial Registry Contents 885 The HTTP MAC authentication scheme algorithm registry's initial 886 contents are: 888 o Algorithm name: hmac-sha-1 889 o Change controller: IETF 890 o Specification document(s): [[ this document ]] 891 o Algorithm name: hmac-sha-256 892 o Change controller: IETF 893 o Specification document(s): [[ this document ]] 895 9.3. OAuth Access Token Type Registration 897 This specification registers the following access token type in the 898 OAuth Access Token Type Registry. 900 9.3.1. The "mac" OAuth Access Token Type 902 Type name: 904 mac 905 Additional Token Endpoint Response Parameters: 907 secret, algorithm 908 HTTP Authentication Scheme(s): 910 MAC 911 Change controller: 913 IETF 914 Specification document(s): 916 [[ this document ]] 918 9.4. OAuth Parameters Registration 920 This specification registers the following parameters in the OAuth 921 Parameters Registry established by [RFC6749]. 923 9.4.1. The "mac_key" OAuth Parameter 925 Parameter name: mac_key 926 Parameter usage location: authorization response, token response 927 Change controller: IETF 928 Specification document(s): [[ this document ]] 929 Related information: None 931 9.4.2. The "mac_algorithm" OAuth Parameter 933 Parameter name: mac_algorithm 934 Parameter usage location: authorization response, token response 935 Change controller: IETF 936 Specification document(s): [[ this document ]] 937 Related information: None 939 9.4.3. The "kid" OAuth Parameter 941 Parameter name: kid 942 Parameter usage location: authorization response, token response 943 Change controller: IETF 944 Specification document(s): [[ this document ]] 945 Related information: None 947 10. Acknowledgments 949 This document is based on OAuth 1.0 and we would like to thank Eran 950 Hammer-Lahav for his work on incorporating the ideas into OAuth 2.0. 951 As part of this initial work the following persons provided feedback: 952 Ben Adida, Adam Barth, Phil Hunt, Rasmus Lerdorf, James Manger, 953 William Mills, Scott Renfro, Justin Richer, Toby White, Peter 954 Wolanin, and Skylar Woodward 956 Further work in this document was done as part of OAuth working group 957 conference calls late 2012/early 2013 and in design team conference 958 calls February 2013. The following persons (in addition to the OAuth 959 WG chairs, Hannes Tschofenig, and Derek Atkins) provided their input 960 during these calls: Bill Mills, Justin Richer, Phil Hunt, Prateek 961 Mishra, Mike Jones, George Fletcher, John Bradley, Tony Nadalin, 962 Thomas Hardjono, Brian Campbell 964 11. References 966 11.1. Normative References 968 [I-D.ietf-httpbis-p1-messaging] 969 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 970 (HTTP/1.1): Message Syntax and Routing", 971 draft-ietf-httpbis-p1-messaging-22 (work in progress), 972 February 2013. 974 [I-D.ietf-jose-json-web-encryption] 975 Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 976 Encryption (JWE)", draft-ietf-jose-json-web-encryption-08 977 (work in progress), December 2012. 979 [I-D.ietf-oauth-json-web-token] 980 Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 981 (JWT)", draft-ietf-oauth-json-web-token-06 (work in 982 progress), December 2012. 984 [I-D.richer-oauth-introspection] 985 Richer, J., "OAuth Token Introspection", 986 draft-richer-oauth-introspection-03 (work in progress), 987 February 2013. 989 [I-D.tschofenig-oauth-audience] 990 Tschofenig, H., "OAuth 2.0: Audience Information", 991 draft-tschofenig-oauth-audience-00 (work in progress), 992 February 2013. 994 [NIST-FIPS-180-3] 995 National Institute of Standards and Technology, "Secure 996 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 998 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 999 Extensions (MIME) Part One: Format of Internet Message 1000 Bodies", RFC 2045, November 1996. 1002 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1003 Hashing for Message Authentication", RFC 2104, 1004 February 1997. 1006 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1007 Requirement Levels", BCP 14, RFC 2119, March 1997. 1009 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1010 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1011 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1013 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1014 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1015 Authentication: Basic and Digest Access Authentication", 1016 RFC 2617, June 1999. 1018 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1019 Resource Identifier (URI): Generic Syntax", STD 66, 1020 RFC 3986, January 2005. 1022 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1023 Requirements for Security", BCP 106, RFC 4086, June 2005. 1025 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1026 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1027 May 2008. 1029 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1030 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1032 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 1033 for TLS", RFC 5929, July 2010. 1035 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1036 April 2011. 1038 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 1039 RFC 6749, October 2012. 1041 [W3C.REC-html401-19991224] 1042 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 1043 Specification", World Wide Web Consortium 1044 Recommendation REC-html401-19991224, December 1999, 1045 . 1047 11.2. Informative References 1049 [I-D.tschofenig-oauth-security] 1050 Tschofenig, H. and P. Hunt, "OAuth 2.0 Security: Going 1051 Beyond Bearer Tokens", draft-tschofenig-oauth-security-01 1052 (work in progress), December 2012. 1054 Authors' Addresses 1056 Justin Richer 1057 The MITRE Corporation 1059 Email: jricher@mitre.org 1061 William Mills 1062 Yahoo! Inc. 1064 Phone: 1065 Email: wmills@yahoo-inc.com 1066 Hannes Tschofenig (editor) 1067 Nokia Siemens Networks 1068 Linnoitustie 6 1069 Espoo 02600 1070 Finland 1072 Phone: +358 (50) 4871445 1073 Email: Hannes.Tschofenig@gmx.net 1074 URI: http://www.tschofenig.priv.at