idnits 2.17.1 draft-hammer-oauth-v2-mac-token-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 (May 9, 2011) is 4729 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC3986' is defined on line 1119, but no explicit reference was found in the text == Unused Reference: 'RFC5849' is defined on line 1141, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-13 == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-15 -- 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) -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 5 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Hammer-Lahav 3 Internet-Draft Yahoo! 4 Intended status: Standards Track A. Barth 5 Expires: November 10, 2011 Google 6 B. Adida 7 Mozilla 8 May 9, 2011 10 HTTP Authentication: MAC Access Authentication 11 draft-hammer-oauth-v2-mac-token-04 13 Abstract 15 This document specifies the HTTP MAC access authentication scheme, an 16 HTTP authentication method using a message authentication code (MAC) 17 algorithm to provide cryptographic verification of portions of HTTP 18 requests. The document also defines an OAuth 2.0 binding for use as 19 an access-token type, as well as an extension attribute to the HTTP 20 Set-Cookie response header field. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on November 10, 2011. 39 Copyright Notice 41 Copyright (c) 2011 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 6 59 2. Issuing MAC Credentials . . . . . . . . . . . . . . . . . . . 6 60 3. Making Requests . . . . . . . . . . . . . . . . . . . . . . . 7 61 3.1. The "Authorization" Request Header . . . . . . . . . . . . 7 62 3.2. Body Hash . . . . . . . . . . . . . . . . . . . . . . . . 9 63 3.3. Request MAC . . . . . . . . . . . . . . . . . . . . . . . 10 64 3.3.1. Normalized Request String . . . . . . . . . . . . . . 11 65 3.3.2. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . . 12 66 3.3.3. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . . 12 67 4. Verifying Requests . . . . . . . . . . . . . . . . . . . . . . 13 68 4.1. The "WWW-Authenticate" Response Header Field . . . . . . . 14 69 5. Use with OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . 15 70 5.1. Issuing MAC-Type Access Tokens . . . . . . . . . . . . . . 15 71 6. Use with Set-Cookie . . . . . . . . . . . . . . . . . . . . . 15 72 6.1. User Agent Requirements . . . . . . . . . . . . . . . . . 16 73 6.1.1. The Set-Cookie Header . . . . . . . . . . . . . . . . 16 74 6.1.2. Storage Model . . . . . . . . . . . . . . . . . . . . 17 75 6.1.3. The Authorization Header . . . . . . . . . . . . . . . 18 76 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 77 7.1. MAC Keys Transmission . . . . . . . . . . . . . . . . . . 18 78 7.2. Confidentiality of Requests . . . . . . . . . . . . . . . 19 79 7.3. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 19 80 7.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 19 81 7.5. Entropy of MAC Keys . . . . . . . . . . . . . . . . . . . 19 82 7.6. Denial of Service / Resource Exhaustion Attacks . . . . . 20 83 7.7. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 20 84 7.8. CSRF Attacks . . . . . . . . . . . . . . . . . . . . . . . 21 85 7.9. Coverage Limitations . . . . . . . . . . . . . . . . . . . 21 86 7.10. Version Rollback Attack . . . . . . . . . . . . . . . . . 21 87 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 88 8.1. The HTTP MAC Authentication Scheme Algorithm Registry . . 22 89 8.1.1. Registration Template . . . . . . . . . . . . . . . . 22 90 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 23 91 8.2. OAuth Access Token Type Registration . . . . . . . . . . . 23 92 8.2.1. The "mac" OAuth Access Token Type . . . . . . . . . . 23 93 8.3. OAuth Parameters Registration . . . . . . . . . . . . . . 23 94 8.3.1. The "secret" OAuth Parameter . . . . . . . . . . . . . 24 95 8.3.2. The "algorithm" OAuth Parameter . . . . . . . . . . . 24 97 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 98 Appendix A. Document History . . . . . . . . . . . . . . . . . . 24 99 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 100 10.1. Normative References . . . . . . . . . . . . . . . . . . . 25 101 10.2. Informative References . . . . . . . . . . . . . . . . . . 26 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 27 104 1. Introduction 106 This specification defines the HTTP MAC access authentication scheme, 107 providing a method for making authenticated HTTP requests with 108 partial cryptographic verification of the request, covering the HTTP 109 method, request URI, host, and in some cases the request body. 111 Similar to the HTTP Basic access authentication scheme [RFC2617], the 112 MAC scheme utilizes a set of client credentials which include an 113 identifier and key. However, in contrast with the Basic scheme, the 114 key is never included in authenticated requests but is used to 115 calculate the request MAC value which is included instead. 117 [[ Add note about design constraints (eg sign an HTTP request without 118 any interactivity with the server; suitable for shared secret keys, 119 but not for shared passwords) ]] 121 The MAC scheme requires the establishment of a shared symmetric key 122 between the client and the server. This is often accomplished 123 through a manual process such as client registration. This 124 specification offers two methods for issuing a set of MAC credentials 125 to the client using: 127 o OAuth 2.0 in the form of a MAC-type access token, using any 128 supported OAuth grant type. 129 o The HTTP "Set-Cookie" response header field via an extension 130 attribute. 132 [[ Please discuss this draft on the apps-discuss@ietf.org [1] mailing 133 list. ]] 135 1.1. Example 137 The client attempts to access a protected resource without 138 authentication, making the following HTTP request to the resource 139 server: 141 GET /resource/1?b=1&a=2 HTTP/1.1 142 Host: example.com 144 The resource server returns the following authentication challenge: 146 HTTP/1.1 401 Unauthorized 147 WWW-Authenticate: MAC 149 The client has previously obtained a set of MAC credentials for 150 accessing resources on the "http://example.com/" server. The MAC 151 credentials issued to the client include the following attributes: 153 MAC key identifier: h480djs93hd8 154 MAC key: 489dks293j39 155 MAC algorithm: hmac-sha-1 156 Issuer: login.example.net:443 157 Issue time: Date: Thu, 02 Dec 2010 21:39:45 GMT 159 The client constructs the authentication header by calculating the 160 credentials' age (number of seconds since the credentials were 161 issued) and generating a nonce. The nonce is unique to the age value 162 used, typically a random string: 164 Age: 264095 165 Nonce: dj83hs9s 167 The client normalizes the request and constructs the normalized 168 request string (the new line separator character is represented by 169 "\n" for display purposes only): 171 login.example.net:443\n 172 264095\n 173 dj83hs9s\n 174 GET\n 175 /resource/1?b=1&a=2\n 176 example.com\n 177 80\n 178 \n 179 \n 181 The two trailing new line separators signify that no body hash or 182 extension value are included with the request. 184 The request MAC is calculated using the specified MAC algorithm 185 "hmac-sha-1" and the MAC key over the normalized request string. The 186 result is base64-encoded to produce the request MAC: 188 TkrWtyTiys3Iw6MF/zI7gbVs5lA= 190 The client includes the MAC key identifier, issuer, age, nonce, and 191 request MAC with the request using the "Authorization" request header 192 field: 194 GET /resource/1?b=1&a=2 HTTP/1.1 195 Host: example.com 196 Authorization: MAC id="h480djs93hd8", 197 issuer="login.example.net:443", 198 age="264095", 199 nonce="dj83hs9s", 200 mac="TkrWtyTiys3Iw6MF/zI7gbVs5lA=" 202 The server validates the request by calculating the request MAC again 203 based on the request received and verifies the validity and scope of 204 the MAC credentials. If valid, the server responds with the 205 requested resource representation. 207 1.2. Notational Conventions 209 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 210 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 211 specification are to be interpreted as described in [RFC2119]. 213 This specification uses the Augmented Backus-Naur Form (ABNF) 214 notation of [I-D.ietf-httpbis-p1-messaging]. Additionally, the 215 following rules are included from [RFC2617]: auth-param. 217 2. Issuing MAC Credentials 219 This specification defines two method for issuing MAC credentials 220 using OAuth 2.0 as described in Section 5 and using the HTTP 221 "Set-Cookie" response header field as described in Section 6. 223 This specification does not mandate servers to support any particular 224 method for issuing MAC credentials, and other methods MAY be defined 225 and used. Whenever MAC credentials are issued, the credentials MUST 226 include the following attributes: 228 MAC key identifier 229 A string identifying the MAC key used to calculate the request 230 MAC. The string is usually opaque to the client. The server 231 typically assigns a specific scope and lifetime to each set of 232 MAC credentials. The identifier MAY denote a unique value used 233 to retrieve the authorization information (e.g. from a 234 database), or self-contain the authorization information in a 235 verifiable manner (i.e. a string consisting of some data and a 236 signature). 238 MAC key 239 A shared symmetric secret used as the MAC algorithm key. The 240 server MUST NOT issue the same MAC key and MAC key identifier 241 combination. 242 MAC algorithm 243 A MAC algorithm used to calculate the request MAC. Value MUST 244 be one of "hmac-sha-1", "hmac-sha-256", or a registered 245 extension algorithm name as described in Section 8.1. 246 Algorithm names are case-sensitive. If the MAC algorithm is 247 not understood by the client, the client MUST NOT use the MAC 248 credentials and continue as if no MAC credentials were issued. 249 Issuer 250 A string identifying the entity issuing the credentials. The 251 content and format of the issuer attribute depends on the 252 method used to obtain the credentials. 253 Issue time 254 The time when the credentials were issued, used to calculate 255 the credentials age when making requests. If the MAC 256 credentials were obtained via an HTTP response, the time of 257 issue is the time the response was received by the client. 259 The MAC key identifier, MAC key, MAC algorithm, and issuer strings 260 MUST NOT include characters other than: 262 %x20-21 / %x23-5B / %x5D-7E 263 ; Any printable ASCII character except for <"> and <\> 265 3. Making Requests 267 To make authenticated requests, the client must be in the possession 268 of a valid set of MAC credentials accepted by the server. The client 269 constructs the request by calculating a set of attributes, and adding 270 them to the HTTP request using the "Authorization" request header 271 field as described in Section 3.1. 273 3.1. The "Authorization" Request Header 275 The "Authorization" request header field uses the framework defined 276 by [RFC2617] as follows: 278 credentials = 'MAC' [ RWS 1#param ] 280 param = id / 281 issuer / 282 age / 283 nonce / 284 body-hash / 285 ext / 286 mac 288 id = 'id' '=' <"> plain-string <"> 289 issuer = 'issuer' '=' <"> plain-string <"> 290 age = 'age' '=' <"> 1*DIGIT <"> 291 nonce = 'nonce' '=' <"> plain-string <"> 292 body-hash = 'bodyhash' '=' <"> plain-string <"> 293 ext = 'ext' '=' <"> plain-string <"> 294 mac = 'mac' '=' <"> plain-string <"> 296 plain-string = 1*( %x20-21 / %x23-5B / %x5D-7E ) 298 The header attributes are set as follows: 300 id 301 REQUIRED. The MAC key identifier. 302 issuer 303 REQUIRED. The identifier of the entity who issued the MAC 304 credentials. 305 age 306 REQUIRED. The number of second since the MAC credentials were 307 issued to the client. The value MUST be a positive integer and 308 MUST NOT include leading zeros (e.g. "000137131200"). 309 nonce 310 REQUIRED. A random string, uniquely generated by the client to 311 allow the server to verify that a request has never been made 312 before and helps prevent replay attacks when requests are made 313 over an insecure channel. The nonce value MUST be unique 314 across all requests with the same "age" and MAC key identifier 315 combination. 316 To avoid the need to retain an infinite number of nonce values 317 for future checks, the server MAY choose to restrict the time 318 period after which a request with an old age is rejected. If 319 such a restriction is enforced, the server SHOULD allow for a 320 sufficiently large window to accommodate network delays which 321 will affect the credentials issue time used by the client to 322 calculate the credentials' age. 324 bodyhash 325 OPTIONAL. The HTTP request payload body hash as described in 326 Section 3.2. 327 ext 328 OPTIONAL. A string used to include additional information 329 which is covered by the request MAC. The content and format of 330 the string is beyond the scope of this specification. 331 mac 332 REQUIRED. The HTTP request MAC as described in Section 3.3. 334 Attributes MUST NOT appear more than once. Attribute values are 335 limited to a subset of ASCII, which does not require escaping, as 336 defined by the plain-string ABNF. 338 3.2. Body Hash 340 [[ Need to figure out exactly when body-hash is required ]] 342 The body hash is used to provide integrity verification of the HTTP 343 request payload body. The body hash value is calculated using a hash 344 algorithm over the entire HTTP request payload body. 346 The client MAY include the body hash with any request. The server 347 SHOULD require the calculation and inclusion of the body hash with 348 any request containing an payload body, or when the presence (or lack 349 of) of an payload body is of significance. 351 The body hash algorithm is determined by the MAC algorithm. The 352 SHA-1 hash algorithm as defined by [NIST FIPS-180-3] is used with the 353 "hmac-sha-1" MAC algorithm. The SHA-256 hash algorithm as defined by 354 [NIST FIPS-180-3] is used with the "hmac-sha-256" MAC algorithm. 355 Additional MAC algorithms MUST specify the corresponding body hash 356 algorithm. 358 The body hash is calculated as follows: 360 bodyhash = BASE64 ( HASH (text) ) 362 Where: 364 HASH 365 is the hash algorithm function, 367 text 368 is the HTTP request payload body, 369 BASE64 370 is the base64-encoding function per [RFC2045] section 6.8, 371 applied to the hash result octet string, and 372 bodyhash 373 is the value used in the normalized request string and to set 374 the "bodyhash" attribute of the "Authorization" request header 375 field. 377 The body hash is calculated before the normalized request string is 378 constructed and the request MAC is calculated. 380 For example, the HTTP request: 382 POST /request HTTP/1.1 383 Host: example.net 384 Content-Type: application/x-www-form-urlencoded 386 hello=world%21 388 using MAC key identifier "jd93dh9dh39D", issuer 389 "auth.example.net:443", age "273156", nonce "di3hvdf8", MAC algorithm 390 "hmac-sha-1", and MAC key "8yfrufh348h", is transmitted as (line 391 breaks are for display purposes only): 393 POST /request HTTP/1.1 394 Host: example.com 395 Content-Type: application/x-www-form-urlencoded 396 Authorization: MAC id="jd93dh9dh39D", 397 issuer="login.example.com:443", 398 age="273156", 399 nonce="di3hvdf8", 400 bodyhash="k9kbtCIy0CkI3/FEfpS/oIDjk6k=", 401 mac="+PrdikQm1erX2/0YIVhUPHl7yDc=" 403 hello=world%21 405 3.3. Request MAC 407 The client uses the MAC algorithm and the MAC key to calculate the 408 request MAC. This specification defines two algorithms: "hmac-sha-1" 409 and "hmac-sha-256", and provides an extension registry for additional 410 algorithms. 412 3.3.1. Normalized Request String 414 The normalized request string is a consistent, reproducible 415 concatenation of several of the HTTP request elements into a single 416 string. By normalizing the request into a reproducible string, the 417 client and server can both calculate the request MAC over the exact 418 same value. 420 The string is constructed by concatenating together, in order, the 421 following HTTP request elements, each followed by a new line 422 character (%x0A): 424 1. The MAC credentials issuer identifier exactly as included with 425 the request using the "issuer" attribute. 426 2. The age value calculated for the request. 427 3. The nonce value generated for the request. 428 4. The HTTP request method in upper case. For example: "HEAD", 429 "GET", "POST", etc. 430 5. The HTTP request-URI as defined by [RFC2616] section 5.1.2. 431 6. The hostname included in the HTTP request using the "Host" 432 request header field in lower case. 433 7. The port as included in the HTTP request using the "Host" request 434 header field. If the header field does not include a port, the 435 default value for the scheme MUST be used (e.g. 80 for HTTP and 436 443 for HTTPS). 437 8. The request payload body hash as described in Section 3.2 if one 438 was calculated and included in the request, otherwise, an empty 439 string. Note that the body hash of an empty payload body is not 440 an empty string. 441 9. The value of the "ext" "Authorization" request header field 442 attribute if one was included in the request, otherwise, an empty 443 string. 445 Each element is followed by a new line character (%x0A) including the 446 last element and even when an element value is an empty string. 448 For example, the HTTP request: 450 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1 451 Host: example.com 453 Hello World! 455 using issuer "login.example.com:443", age "264095", nonce "7d8f3e4a", 456 body hash "Lve95gjOVATpfV8EL5X4nxwjKHE=", and extension string 457 "a,b,c" is normalized into the following string (the new line 458 separator character is represented by "\n" for display purposes 459 only): 461 login.example.com:443\n 462 264095\n 463 7d8f3e4a\n 464 POST\n 465 /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q\n 466 example.com\n 467 80\n 468 Lve95gjOVATpfV8EL5X4nxwjKHE=\n 469 a,b,c\n 471 3.3.2. hmac-sha-1 473 "hmac-sha-1" uses the HMAC-SHA1 algorithm as defined in [RFC2104]: 475 mac = HMAC-SHA1 (key, text) 477 Where: 479 text 480 is set to the value of the normalized request string as 481 described in Section 3.3.1, 482 key 483 is set to the MAC key provided by the server, and 484 mac 485 is used to set the value of the "mac" attribute, after the 486 result octet string is base64-encoded per [RFC2045] section 487 6.8. 489 The SHA-1 hash algorithm as defined by [NIST FIPS-180-3] is used for 490 generating the body hash attribute described in Section 3.2 when 491 using MAC credentials with the "hmac-sha-1" MAC algorithm. 493 3.3.3. hmac-sha-256 495 "hmac-sha-256" uses the HMAC algorithm as defined in [RFC2104] 496 together with the SHA-256 hash function defined in [NIST FIPS-180-3]: 498 mac = HMAC-SHA256 (key, text) 500 Where: 502 text 503 is set to the value of the normalize request string as 504 described in Section 3.3.1, 505 key 506 is set to the MAC key provided by the server, and 507 mac 508 is used to set the value of the "mac" attribute, after the 509 result octet string is base64-encoded per [RFC2045] section 510 6.8. 512 The SHA-256 hash algorithm as defined by [NIST FIPS-180-3] is used 513 for generating the body hash attribute described in Section 3.2 when 514 using MAC credentials with the "hmac-sha-256" MAC algorithm. 516 4. Verifying Requests 518 A server receiving an authenticated request validates it by 519 performing the following REQUIRED steps: 521 1. Recalculate the request body hash (if included in the request) as 522 described in Section 3.2 and request MAC as described in 523 Section 3.3 and compare the request MAC to the value received 524 from the client via the "mac" attribute. 525 2. Ensure that the combination of nonce, age, and MAC key identifier 526 received from the client has not been used before in a previous 527 request (the server MAY reject requests with stale timestamps; 528 the determination of staleness is left up to the server to 529 define). 530 3. Verify the scope and validity of the MAC credentials. 532 If the request fails verification, the server response includes the 533 "WWW-Authenticate" response header field as described in Section 4.1 534 and SHOULD include one of the following HTTP status codes: 536 401 (Unauthorized) 537 The "Authorization" request header field is not included, 538 missing a required parameter, includes an unsupported parameter 539 or parameter value, repeats the same parameter, or is otherwise 540 malformed. The MAC credentials provided are expired, revoked, 541 malformed, or invalid. The body hash or request MAC provided 542 do not match the values calculated by the server, or a body 543 hash is required but missing. 545 307 (Temporary Redirect) 546 Same as 401, with the exception that a human intervention at 547 the destination URI (identified by the "Location" response 548 header field) MAY resolve the issue (e.g. provide a login page 549 which upon a successful authentication will issue the user- 550 agent a new set of MAC credentials using the "Set-Cookie" 551 response header field as described in Section 6. 553 4.1. The "WWW-Authenticate" Response Header Field 555 If the protected resource request does not include authentication 556 credentials, contains an invalid MAC key identifier, or is malformed, 557 the server SHOULD include the HTTP "WWW-Authenticate" response header 558 field. 560 For example: 562 HTTP/1.1 401 Unauthorized 563 WWW-Authenticate: MAC 565 The "WWW-Authenticate" request header field uses the framework 566 defined by [RFC2617] as follows: 568 challenge = "MAC" [ RWS 1#param ] 569 param = error / auth-param 570 error = "error" "=" quoted-string 572 Each attribute MUST NOT appear more than once. 574 If the protected resource request included a MAC "Authorization" 575 request header field and failed authentication, the server MAY 576 include the "error" attribute to provide the client with a human- 577 readable explanation why the access request was declined. 579 For example: 581 HTTP/1.1 401 Unauthorized 582 WWW-Authenticate: MAC error="The MAC credentials expired" 584 5. Use with OAuth 2.0 586 OAuth 2.0 ([I-D.ietf-oauth-v2]) defines a token-based authentication 587 framework in which third-party applications (clients) access 588 protected resources using access tokens. Access tokens are obtained 589 via the resource owners' authorization from an authorization server. 590 This specification defines the OAuth 2.0 MAC token type, as well as 591 type-specific token attributes. 593 This specification does not define methods for the client to 594 specifically request a MAC-type token from the authorization server. 595 Additionally, it does not include any discovery facilities for 596 identifying which HMAC algorithms are supported by a resource server, 597 or how the client may go about obtaining MAC access tokens for any 598 given protected resource. 600 The authorization server MUST require the use of a transport-layer 601 security mechanism when sending requests to the token endpoint to 602 obtain a MAC token. 604 5.1. Issuing MAC-Type Access Tokens 606 Authorization servers issuing MAC-type access tokens MUST include the 607 following parameters whenever a response includes the "access_token" 608 parameter: 610 access_token 611 REQUIRED. The MAC key identifier. 612 secret 613 REQUIRED. The MAC key. 614 algorithm 615 REQUIRED. The MAC algorithm used to calculate the request MAC. 616 Value MUST be one of "hmac-sha-1", "hmac-sha-256", or a 617 registered extension algorithm name as described in 618 Section 8.1. 620 The issuer attribute MUST be determined by the client alone, and set 621 to the host and port of the token endpoint used to make the HTTP 622 request to obtain the credentials, separated by a colon character 623 (%x3A). For example, 'auth.example.com:443'. If the client followed 624 any redirections before receiving the credentials, it MUST use the 625 host and port of the final request (the request resulting in the 626 transmission of the MAC credential). 628 6. Use with Set-Cookie 630 The HTTP "Set-Cookie " response header field defined in [RFC6265] 631 enables the server to set persistent information which the client 632 repeats back on follow-up requests. Each cookie includes a name- 633 value pair which is sent back to the server, and a set of attributes 634 which inform the client when to include the cookie in follow-up 635 requests. The attributes are never sent back to the server. 637 This specification defines the "MAC-Key" and "MAC-Algorithm" cookie 638 attributes, which are used by the server, together with the cookie 639 name which includes the MAC key identifier, to issue the client a set 640 of MAC credentials. 642 The issuer attribute MUST be determined by the client alone, and set 643 to the host and port of the token endpoint used to make the HTTP 644 request to obtain the credentials, separated by a colon character 645 (%x3A). For example, 'auth.example.com:443'. If the client followed 646 any redirections before receiving the credentials, it MUST use the 647 host and port of the final request (the request resulting in the 648 transmission of the credential). 650 The server MUST only include the "MAC-Key" attribute in response to 651 requests made using a transport-layer security mechanism such as TLS 652 1.2 as defined in [RFC5246]. Clients MUST discard any MAC 653 credentials received over an insecure channel. 655 For example, after a successful end-user authentication, the server 656 includes the following response header field (line breaks are for 657 display purposes only): 659 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com; 660 MAC-Key=8yfrufh348h; MAC-Algorithm=hmac-sha-1 662 which provides the client with the necessary MAC credentials. The 663 cookie name "SID" is used as the MAC key identifier together with the 664 other MAC-specific attributes. The user-agent uses the MAC 665 credentials for subsequent HTTP requests that match the scope of the 666 cookie, in this case for "example.com" and all subdomains. 668 6.1. User Agent Requirements 670 This section updates [RFC6265], adding the ability to issue MAC 671 credentials using the "Set-Cookie " response header field. 673 6.1.1. The Set-Cookie Header 675 Add the following two subsections to the end of Section 5.2 (The Set- 676 Cookie Header) in [RFC6265]. These sections instruct the user-agent 677 how to parse the "MAC-Key" attribute and "MAC-Algorithm" attribute, 678 respectively. 680 6.1.1.1. The MAC-Key attribute 682 If the attribute-name case-insensitively matches the string 683 "MAC-Key", the user-agent MUST append an attribute to the cookie- 684 attribute-list with an attribute name of "MAC-Key" and a attribute- 685 value equal to the attribute-value. 687 6.1.1.2. The MAC-Algorithm attribute 689 If the attribute-name case-insensitively matches the string 690 "MAC-Algorithm", and if the attribute-value is either "hmac-sha-1", 691 "hmac-sha-256", or a registered extension value, the user-agent MUST 692 append an attribute to the cookie-attribute-list with an attribute 693 name of "MAC-Algorithm" and an attribute-value equal to the 694 attribute-value. 696 6.1.2. Storage Model 698 The storage model for cookies is extended with three additional 699 fields: "mac-key", "mac-algorithm", and "issuer", all of which 700 default to the empty string. 702 The user-agent MUST perform the follow steps after Step 10 of the 703 algorithm in Section 5.3 of [RFC6265]: 705 1. If the cookie-attribute-list contains an attribute with an 706 attribute-name of "MAC-Key", set the cookie's "mac-key" field to 707 the attribute-value of the last such attribute. 708 2. If the cookie-attribute-list contains an attribute with an 709 attribute-name of "Mac-Algorithm", set the cookie's 710 "mac-algorithm" field to the attribute-value of the last such 711 attribute. 712 3. Set the "issuer" field to the canonicalized request-host, as 713 defined in [RFC6265] followed by a colon character (%x3A), and 714 the port number of the request-uri (as defined in Section 5.1.2 715 of [RFC2616]). 717 When the user agent removes excess cookies from the cookie store 718 because there are more than a predetermined number of cookies that 719 share a domain field, or the combined length of cookies sharing a 720 single domain field or being sent in a single request have exceeded a 721 predetermined length, the user agent MUST evict cookies with an empty 722 mac-key or an empty mac-algorithm field before cookies with both a 723 non-empty mac-key and a non-empty mac-algorithm field. 725 6.1.3. The Authorization Header 727 In addition to being sent to the server in the "Cookie" request 728 header field, cookies with "MAC-Key" and "MAC-Algorithm" attributes 729 are also used to compute the "Authorization" request header field as 730 described in Section 3.1. 732 The user-agent MAY ignore cookies for the purpose of generating the 733 "Authorization" request header field. For example, the user-agent 734 might wish to ignore cookies when issuing "third-party" requests or 735 use MAC credentials obtained via other means. 737 When issuing an HTTP request, let cookie-list be the set of cookies 738 defined in Section 5.4 of [RFC6265]. Further, let mac-cookie-list be 739 those cookies in the cookie-list that contain both a non-empty 740 "mac-key" and "mac-algorithm" fields. 742 Let the operative-cookie be the first cookie in the mac-cookie-list. 744 Include an "Authorization" request header field in the HTTP request 745 as described in Section 3.1 using the cookie's MAC credentials where: 747 MAC key identifier 748 is equal to the operative-cookie's name, 749 MAC key 750 is equal to the operative-cookie's "mac-key", 751 MAC algorithm 752 is equal to the operative-cookie's "mac-algorithm", and 753 Issuer 754 is equal to the operative-cookie's "issuer". 755 Issue time 756 is equal to the operative-cookie's "creation-time". 758 7. Security Considerations 760 As stated in [RFC2617], the greatest sources of risks are usually 761 found not in the core protocol itself but in policies and procedures 762 surrounding its use. Implementers are strongly encouraged to assess 763 how this protocol addresses their security requirements. 765 7.1. MAC Keys Transmission 767 This specification describes two mechanism for obtaining or 768 transmitting MAC keys, both require the use of a transport-layer 769 security mechanism when sending MAC keys to the client. Additional 770 methods used to obtain MAC credentials must ensure that these 771 transmissions are protected using transport-layer mechanisms such as 772 TLS or SSL. 774 7.2. Confidentiality of Requests 776 While this protocol provides a mechanism for verifying the integrity 777 of requests, it provides no guarantee of request confidentiality. 778 Unless further precautions are taken, eavesdroppers will have full 779 access to request content. Servers should carefully consider the 780 kinds of data likely to be sent as part of such requests, and should 781 employ transport-layer security mechanisms to protect sensitive 782 resources. 784 7.3. Spoofing by Counterfeit Servers 786 This protocol makes no attempt to verify the authenticity of the 787 server. A hostile party could take advantage of this by intercepting 788 the client's requests and returning misleading or otherwise incorrect 789 responses. Service providers should consider such attacks when 790 developing services using this protocol, and should require 791 transport-layer security for any requests where the authenticity of 792 the resource server or of request responses is an issue. 794 7.4. Plaintext Storage of Credentials 796 The MAC key functions the same way passwords do in traditional 797 authentication systems. In order to compute the request MAC, the 798 server must have access to the MAC key in plaintext form. This is in 799 contrast, for example, to modern operating systems, which store only 800 a one-way hash of user credentials. 802 If an attacker were to gain access to these MAC keys - or worse, to 803 the server's database of all such MAC keys - he or she would be able 804 to perform any action on behalf of any resource owner. Accordingly, 805 it is critical that servers protect these MAC keys from unauthorized 806 access. 808 7.5. Entropy of MAC Keys 810 Unless a transport-layer security protocol is used, eavesdroppers 811 will have full access to authenticated requests and request MAC 812 values, and will thus be able to mount offline brute-force attacks to 813 recover the MAC key used. Servers should be careful to assign MAC 814 keys which are long enough, and random enough, to resist such attacks 815 for at least the length of time that the MAC credentials are valid. 817 For example, if the MAC credentials are valid for two weeks, servers 818 should ensure that it is not possible to mount a brute force attack 819 that recovers the MAC key in less than two weeks. Of course, servers 820 are urged to err on the side of caution, and use the longest MAC key 821 reasonable. 823 It is equally important that the pseudo-random number generator 824 (PRNG) used to generate these MAC keys be of sufficiently high 825 quality. Many PRNG implementations generate number sequences that 826 may appear to be random, but which nevertheless exhibit patterns or 827 other weaknesses which make cryptanalysis or brute force attacks 828 easier. Implementers should be careful to use cryptographically 829 secure PRNGs to avoid these problems. 831 7.6. Denial of Service / Resource Exhaustion Attacks 833 This specification includes a number of features which may make 834 resource exhaustion attacks against servers possible. For example, 835 this protocol requires servers to track used nonces. If an attacker 836 is able to use many nonces quickly, the resources required to track 837 them may exhaust available capacity. And again, this protocol can 838 require servers to perform potentially expensive computations in 839 order to verify the request MAC on incoming requests. An attacker 840 may exploit this to perform a denial of service attack by sending a 841 large number of invalid requests to the server. 843 Resource Exhaustion attacks are by no means specific to this 844 specification. However, implementers should be careful to consider 845 the additional avenues of attack that this protocol exposes, and 846 design their implementations accordingly. For example, entropy 847 starvation typically results in either a complete denial of service 848 while the system waits for new entropy or else in weak (easily 849 guessable) MAC keys. When implementing this protocol, servers should 850 consider which of these presents a more serious risk for their 851 application and design accordingly. 853 7.7. Timing Attacks 855 This specification makes use of HMACs, for which a signature 856 verification involves comparing the received MAC string to the 857 expected one. If the string comparison operator operates in 858 observably different times depending on inputs, e.g. because it 859 compares the strings character by character and returns a negative 860 result as soon as two characters fail to match, then it may be 861 possible to use this timing information to determine the expected 862 MAC, character by character. 864 Service implementers are encouraged to use fixed-time string 865 comparators for MAC verification. 867 7.8. CSRF Attacks 869 A Cross-Site Request Forgery attack occurs when a site, evil.com, 870 initiates within the victim's browser the loading of a URL from or 871 the posting of a form to a web site where a side-effect will occur, 872 e.g. transfer of money, change of status message, etc. To prevent 873 this kind of attack, web sites may use various techniques to 874 determine that the originator of the request is indeed the site 875 itself, rather than a third party. The classic approach is to 876 include, in the set of URL parameters or form content, a nonce 877 generated by the server and tied to the user's session, which 878 indicates that only the server could have triggered the action. 880 Recently, the Origin HTTP header has been proposed and deployed in 881 some browsers. This header indicates the scheme, host, and port of 882 the originator of a request. Some web applications may use this 883 Origin header as a defense against CSRF. 885 To keep this specification simple, HTTP headers are not part of the 886 string to be MAC'ed. As a result, MAC authentication cannot defend 887 against header spoofing, and a web site that uses the Host header to 888 defend against CSRF attacks cannot use MAC authentication to defend 889 against active network attackers. Sites that want the full 890 protection of MAC Authentication should use traditional, cookie-tied 891 CSRF defenses. 893 7.9. Coverage Limitations 895 The normalized request string has been designed to support the 896 authentication methods defined in this specification. Those 897 designing additional methods, should evaluated the compatibility of 898 the normalized request string with their security requirements. 899 Since the normalized request string does not cover the entire HTTP 900 request, servers should employ additional mechanisms to protect such 901 elements. 903 The request MAC does not cover entity-header fields which can often 904 affect how the request body is interpreted by the server (i.e. 905 Content-Type). If the server behavior is influenced by the presence 906 or value of such header fields, an attacker can manipulate the 907 request header without being detected. This will alter the request 908 even when using the body hash attribute. 910 7.10. Version Rollback Attack 912 [[ TODO ]] 914 8. IANA Considerations 916 8.1. The HTTP MAC Authentication Scheme Algorithm Registry 918 This specification establishes the HTTP MAC authentication scheme 919 algorithm registry. 921 Additional MAC algorithms are registered on the advice of one or more 922 Designated Experts (appointed by the IESG or their delegate), with a 923 Specification Required (using terminology from [RFC5226]). However, 924 to allow for the allocation of values prior to publication, the 925 Designated Expert(s) may approve registration once they are satisfied 926 that such a specification will be published. 928 Registration requests should be sent to the [TBD]@ietf.org mailing 929 list for review and comment, with an appropriate subject (e.g., 930 "Request for MAC Algorithm: example"). [[ Note to RFC-EDITOR: The 931 name of the mailing list should be determined in consultation with 932 the IESG and IANA. Suggested name: http-mac-ext-review. ]] 934 Within at most 14 days of the request, the Designated Expert(s) will 935 either approve or deny the registration request, communicating this 936 decision to the review list and IANA. Denials should include an 937 explanation and, if applicable, suggestions as to how to make the 938 request successful. 940 Decisions (or lack thereof) made by the Designated Expert can be 941 first appealed to Application Area Directors (contactable using 942 app-ads@tools.ietf.org email address or directly by looking up their 943 email addresses on http://www.iesg.org/ website) and, if the 944 appellant is not satisfied with the response, to the full IESG (using 945 the iesg@iesg.org mailing list). 947 IANA should only accept registry updates from the Designated 948 Expert(s), and should direct all requests for registration to the 949 review mailing list. 951 8.1.1. Registration Template 953 Algorithm name: 954 The name requested (e.g., "example"). 955 Body hash algorithm: 956 The corresponding algorithm used to calculate the payload body 957 hash. 959 Change controller: 960 For standards-track RFCs, state "IETF". For others, give the name 961 of the responsible party. Other details (e.g., postal address, 962 e-mail address, home page URI) may also be included. 963 Specification document(s): 964 Reference to document that specifies the algorithm, preferably 965 including a URI that can be used to retrieve a copy of the 966 document. An indication of the relevant sections may also be 967 included, but is not required. 969 8.1.2. Initial Registry Contents 971 The HTTP MAC authentication scheme algorithm registry's initial 972 contents are: 974 o Algorithm name: hmac-sha-1 975 o Body hash algorithm: sha-1 976 o Change controller: IETF 977 o Specification document(s): [[ this document ]] 979 o Algorithm name: hmac-sha-256 980 o Body hash algorithm: sha-256 981 o Change controller: IETF 982 o Specification document(s): [[ this document ]] 984 8.2. OAuth Access Token Type Registration 986 This specification registers the following access token type in the 987 OAuth Access Token Type Registry. 989 8.2.1. The "mac" OAuth Access Token Type 991 Type name: 992 mac 993 Additional Token Endpoint Response Parameters: 994 secret, algorithm 995 HTTP Authentication Scheme(s): 996 MAC 997 Change controller: 998 IETF 999 Specification document(s): 1000 [[ this document ]] 1002 8.3. OAuth Parameters Registration 1004 This specification registers the following parameters in the OAuth 1005 Parameters Registry established by [I-D.ietf-oauth-v2]. 1007 8.3.1. The "secret" OAuth Parameter 1009 Parameter name: secret 1010 Parameter usage location: authorization response, token response 1011 Change controller: IETF 1012 Specification document(s): [[ this document ]] 1013 Related information: None 1015 8.3.2. The "algorithm" OAuth Parameter 1017 Parameter name: algorithm 1018 Parameter usage location: authorization response, token response 1019 Change controller: IETF 1020 Specification document(s): [[ this document ]] 1021 Related information: None 1023 9. Acknowledgments 1025 The authors would like to thank Rasmus Lerdorf, James Manger, Scott 1026 Renfro, Toby White, Peter Wolanin, and Skylar Woodward for their 1027 suggestions and feedback. 1029 Appendix A. Document History 1031 [[ To be removed by the RFC editor before publication as an RFC. ]] 1033 -04 1035 o Added new 'ext' request attribute. 1036 o Replaced 'timestamp' with 'age'. 1037 o Dropped key identifier from normalized string. 1038 o Clarified algorithm name and handling of unknown value. 1039 o Include a single authorization header even if multiple MAC cookies 1040 present. 1041 o Dropped explicit mention of 403. 1043 -03 1045 o Changed access token terminology to MAC key identifier and access 1046 token secret to MAC key. Changed corresponding parameter name 1047 from 'token' to 'id'. 1048 o Changed signature terminology to request MAC. Changed 1049 corresponding parameter name from 'signature' to 'mac'. 1050 o Added new 'Set-Cookie' header extension. 1052 o Added new 'issuer' attribute. 1053 o Defined algorithm registry. 1054 o Dropped request URI query normalization. Changed order of string 1055 components. 1057 -02 1059 o Added body-hash support. 1060 o Updated OAuth 2.0 reference and added token type registration 1061 template. 1062 o Removed error codes and error URI. 1064 -01 1066 o Changed parameters sorting to come after name=value string 1067 construction. 1068 o Added new line at the end of the normalized request string. 1069 o Moved OAuth2 references to separate section. 1070 o Added 'WWW-Authenticate' header definition. 1071 o Fixed example header use of single quote. 1072 o Restricted strings to ASCII subset (printable, no double-quotes or 1073 back-slash). 1075 -00 1077 o Initial draft. 1079 10. References 1081 10.1. Normative References 1083 [I-D.ietf-httpbis-p1-messaging] 1084 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 1085 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 1086 "HTTP/1.1, part 1: URIs, Connections, and Message 1087 Parsing", draft-ietf-httpbis-p1-messaging-13 (work in 1088 progress), March 2011. 1090 [I-D.ietf-oauth-v2] 1091 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 1092 2.0 Authorization Protocol", draft-ietf-oauth-v2-15 (work 1093 in progress), April 2011. 1095 [NIST FIPS-180-3] 1096 National Institute of Standards and Technology, "Secure 1097 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 1099 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1100 Extensions (MIME) Part One: Format of Internet Message 1101 Bodies", RFC 2045, November 1996. 1103 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1104 Hashing for Message Authentication", RFC 2104, 1105 February 1997. 1107 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1108 Requirement Levels", BCP 14, RFC 2119, March 1997. 1110 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1111 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1112 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1114 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1115 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1116 Authentication: Basic and Digest Access Authentication", 1117 RFC 2617, June 1999. 1119 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1120 Resource Identifier (URI): Generic Syntax", STD 66, 1121 RFC 3986, January 2005. 1123 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1124 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1125 May 2008. 1127 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1128 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1130 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1131 April 2011. 1133 [W3C.REC-html401-19991224] 1134 Hors, A., Jacobs, I., and D. Raggett, "HTML 4.01 1135 Specification", World Wide Web Consortium 1136 Recommendation REC-html401-19991224, December 1999, 1137 . 1139 10.2. Informative References 1141 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 1142 April 2010. 1144 URIs 1146 [1] 1148 Authors' Addresses 1150 Eran Hammer-Lahav 1151 Yahoo! 1153 Email: eran@hueniverse.com 1154 URI: http://hueniverse.com 1156 Adam Barth 1157 Google 1159 Email: ietf@adambarth.com 1160 URI: http://www.adambarth.com 1162 Ben Adida 1163 Mozilla 1165 Email: ben@adida.net 1166 URI: http://ben.adida.net