idnits 2.17.1 draft-ietf-oauth-v2-http-mac-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document 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 11, 2011) is 4705 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 1063, but no explicit reference was found in the text == Unused Reference: 'RFC5849' is defined on line 1085, 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, Ed. 3 Internet-Draft Yahoo! 4 Intended status: Standards Track A. Barth 5 Expires: November 12, 2011 Google 6 B. Adida 7 Mozilla 8 May 11, 2011 10 HTTP Authentication: MAC Access Authentication 11 draft-ietf-oauth-v2-http-mac-00 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 12, 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. Design Constraints . . . . . . . . . . . . . . . . . . . . 4 58 1.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 1.3. Notational Conventions . . . . . . . . . . . . . . . . . . 6 60 2. Issuing MAC Credentials . . . . . . . . . . . . . . . . . . . 6 61 3. Making Requests . . . . . . . . . . . . . . . . . . . . . . . 7 62 3.1. The "Authorization" Request Header . . . . . . . . . . . . 8 63 3.2. Body Hash . . . . . . . . . . . . . . . . . . . . . . . . 9 64 3.3. Request MAC . . . . . . . . . . . . . . . . . . . . . . . 10 65 3.3.1. Normalized Request String . . . . . . . . . . . . . . 11 66 3.3.2. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . . 12 67 3.3.3. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . . 12 68 4. Verifying Requests . . . . . . . . . . . . . . . . . . . . . . 13 69 4.1. The "WWW-Authenticate" Response Header Field . . . . . . . 14 70 5. Use with OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . 14 71 5.1. Issuing MAC-Type Access Tokens . . . . . . . . . . . . . . 15 72 6. Use with Set-Cookie . . . . . . . . . . . . . . . . . . . . . 16 73 6.1. User Agent Requirements . . . . . . . . . . . . . . . . . 16 74 6.1.1. The Set-Cookie Header . . . . . . . . . . . . . . . . 16 75 6.1.2. Storage Model . . . . . . . . . . . . . . . . . . . . 17 76 6.1.3. The Authorization Header . . . . . . . . . . . . . . . 17 77 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 78 7.1. MAC Keys Transmission . . . . . . . . . . . . . . . . . . 18 79 7.2. Confidentiality of Requests . . . . . . . . . . . . . . . 18 80 7.3. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 19 81 7.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 19 82 7.5. Entropy of MAC Keys . . . . . . . . . . . . . . . . . . . 19 83 7.6. Denial of Service / Resource Exhaustion Attacks . . . . . 20 84 7.7. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 20 85 7.8. CSRF Attacks . . . . . . . . . . . . . . . . . . . . . . . 20 86 7.9. Coverage Limitations . . . . . . . . . . . . . . . . . . . 21 87 7.10. Version Rollback Attack . . . . . . . . . . . . . . . . . 21 88 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 89 8.1. The HTTP MAC Authentication Scheme Algorithm Registry . . 21 90 8.1.1. Registration Template . . . . . . . . . . . . . . . . 22 91 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 22 92 8.2. OAuth Access Token Type Registration . . . . . . . . . . . 23 93 8.2.1. The "mac" OAuth Access Token Type . . . . . . . . . . 23 94 8.3. OAuth Parameters Registration . . . . . . . . . . . . . . 23 95 8.3.1. The "mac_key" OAuth Parameter . . . . . . . . . . . . 23 96 8.3.2. The "mac_algorithm" OAuth Parameter . . . . . . . . . 23 97 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 98 Appendix A. Document History . . . . . . . . . . . . . . . . . . 24 99 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 100 10.1. Normative References . . . . . . . . . . . . . . . . . . . 24 101 10.2. Informative References . . . . . . . . . . . . . . . . . . 25 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 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 The MAC scheme requires the establishment of a shared symmetric key 118 between the client and the server. This is often accomplished 119 through a manual process such as client registration. This 120 specification offers two methods for issuing a set of MAC credentials 121 to the client using: 123 o OAuth 2.0 in the form of a MAC-type access token, using any 124 supported OAuth grant type. 125 o The HTTP "Set-Cookie" response header field via an extension 126 attribute. 128 1.1. Design Constraints 130 The primary design goal of this mechanism is to improve HTTP state 131 management for services that are unwilling or unable to employ TLS 132 for every request. In particular, this mechanism leverage an initial 133 TLS setup phase (e.g., when the server receives the user's primary 134 credentials, such as a TLS client certificate or a password) to 135 establish a shared secret between the client and the server. The 136 shared secret is then used over an insecure channel to provide 137 protection against a passive network attacker. 139 In particular, when a server uses this mechanism, a passive network 140 attacker will be unable to "steal" the user's session token, as is 141 possible today with cookies and other bearer tokens. In addition, 142 this mechanism helps secure the session token against leakage when 143 sent over a secure channel to the wrong server (e.g., when the client 144 uses some form of dynamic configuration to determine where to send an 145 authenticated request). 147 Unlike the HTTP Digest authentication scheme, this mechanism does not 148 require interacting with the server to prevent replay attacks. 149 Instead, the client provides both a nonce and a timestamp, which the 150 server can use to prevent replay attacks using a bounded amount of 151 storage. Also unlike Digest, this mechanism is not intended to 152 protect the user's password itself because the client and server both 153 have access to the key material in the clear. Instead, servers 154 should issue a short-lived derivative credential for this mechanism 155 during the initial TLS setup phase. 157 1.2. Example 159 The client attempts to access a protected resource without 160 authentication, making the following HTTP request to the resource 161 server: 163 GET /resource/1?b=1&a=2 HTTP/1.1 164 Host: example.com 166 The resource server returns the following authentication challenge: 168 HTTP/1.1 401 Unauthorized 169 WWW-Authenticate: MAC 171 The client has previously obtained a set of MAC credentials for 172 accessing resources on the "http://example.com/" server. The MAC 173 credentials issued to the client include the following attributes: 175 MAC key identifier: h480djs93hd8 176 MAC key: 489dks293j39 177 MAC algorithm: hmac-sha-1 178 Issue time: Thu, 02 Dec 2010 21:39:45 GMT 180 The client constructs the authentication header by calculating the 181 credentials' age (number of seconds since the credentials were 182 issued) and generating a random string used to construct a nonce: 184 Age: 264095 185 Random string: dj83hs9s 186 Nonce: 264095:dj83hs9s 188 The client constructs the normalized request string (the new line 189 separator character is represented by "\n" for display purposes only; 190 the two trailing new line separators signify that no body hash or 191 extension value are included with the request, explained below): 193 264095:dj83hs9s\n 194 GET\n 195 /resource/1?b=1&a=2\n 196 example.com\n 197 80\n 198 \n 199 \n 201 The request MAC is calculated using the specified MAC algorithm 202 "hmac-sha-1" and the MAC key over the normalized request string. The 203 result is base64-encoded to produce the request MAC: 205 SLDJd4mg43cjQfElUs3Qub4L6xE= 207 The client includes the MAC key identifier, nonce, and request MAC 208 with the request using the "Authorization" request header field: 210 GET /resource/1?b=1&a=2 HTTP/1.1 211 Host: example.com 212 Authorization: MAC id="h480djs93hd8", 213 nonce="264095:dj83hs9s", 214 mac="SLDJd4mg43cjQfElUs3Qub4L6xE=" 216 The server validates the request by calculating the request MAC again 217 based on the request received and verifies the validity and scope of 218 the MAC credentials. If valid, the server responds with the 219 requested resource representation. 221 1.3. Notational Conventions 223 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 224 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 225 specification are to be interpreted as described in [RFC2119]. 227 This specification uses the Augmented Backus-Naur Form (ABNF) 228 notation of [I-D.ietf-httpbis-p1-messaging]. Additionally, the 229 following rules are included from [RFC2617]: auth-param. 231 2. Issuing MAC Credentials 233 This specification defines two method for issuing MAC credentials 234 using OAuth 2.0 as described in Section 5 and using the HTTP 235 "Set-Cookie" response header field as described in Section 6. 237 This specification does not mandate servers to support any particular 238 method for issuing MAC credentials, and other methods MAY be defined 239 and used. Whenever MAC credentials are issued, the credentials MUST 240 include the following attributes: 242 MAC key identifier 243 A string identifying the MAC key used to calculate the request 244 MAC. The string is usually opaque to the client. The server 245 typically assigns a specific scope and lifetime to each set of 246 MAC credentials. The identifier MAY denote a unique value used 247 to retrieve the authorization information (e.g. from a 248 database), or self-contain the authorization information in a 249 verifiable manner (i.e. a string consisting of some data and a 250 signature). 251 MAC key 252 A shared symmetric secret used as the MAC algorithm key. The 253 server MUST NOT issue the same MAC key and MAC key identifier 254 combination. 255 MAC algorithm 256 A MAC algorithm used to calculate the request MAC. Value MUST 257 be one of "hmac-sha-1", "hmac-sha-256", or a registered 258 extension algorithm name as described in Section 8.1. 259 Algorithm names are case-sensitive. If the MAC algorithm is 260 not understood by the client, the client MUST NOT use the MAC 261 credentials and continue as if no MAC credentials were issued. 262 Issue time 263 The time when the credentials were issued, used to calculate 264 the credentials age when making requests. If the MAC 265 credentials were obtained via an HTTP response, the time of 266 issue is the time the response was received by the client. 268 The MAC key identifier, MAC key, MAC algorithm strings MUST NOT 269 include characters other than: 271 %x20-21 / %x23-5B / %x5D-7E 272 ; Any printable ASCII character except for <"> and <\> 274 3. Making Requests 276 To make authenticated requests, the client must be in the possession 277 of a valid set of MAC credentials accepted by the server. The client 278 constructs the request by calculating a set of attributes, and adding 279 them to the HTTP request using the "Authorization" request header 280 field as described in Section 3.1. 282 3.1. The "Authorization" Request Header 284 The "Authorization" request header field uses the framework defined 285 by [RFC2617] as follows: 287 credentials = "MAC" [ RWS 1#param ] 289 param = id / 290 nonce / 291 body-hash / 292 ext / 293 mac 295 id = "id" "=" <"> plain-string <"> 296 nonce = "nonce" "=" <"> 1*DIGIT ":" plain-string <"> 297 body-hash = "bodyhash" "=" <"> plain-string <"> 298 ext = "ext" "=" <"> plain-string <"> 299 mac = "mac" "=" <"> plain-string <"> 301 plain-string = 1*( %x20-21 / %x23-5B / %x5D-7E ) 303 The header attributes are set as follows: 305 id 306 REQUIRED. The MAC key identifier. 307 nonce 308 REQUIRED. A unique string generated by the client to allow the 309 server to verify that a request has never been made before and 310 helps prevent replay attacks when requests are made over an 311 insecure channel. The nonce value MUST be unique across all 312 requests with the same MAC key identifier. 313 The nonce value MUST consist of the age of the MAC credentials 314 expressed as the number of seconds since the credentials were 315 issued to the client, a colon character (%x25), and a unique 316 string (typically random). The age value MUST be a positive 317 integer and MUST NOT include leading zeros (e.g. 318 "000137131200"). For example: "273156:di3hvdf8". 319 To avoid the need to retain an infinite number of nonce values 320 for future checks, the server MAY choose to restrict the time 321 period after which a request with an old age is rejected. If 322 such a restriction is enforced, the server SHOULD allow for a 323 sufficiently large window to accommodate network delays which 324 will affect the credentials issue time used by the client to 325 calculate the credentials' age. 327 bodyhash 328 OPTIONAL. The HTTP request payload body hash as described in 329 Section 3.2. 330 ext 331 OPTIONAL. A string used to include additional information 332 which is covered by the request MAC. The content and format of 333 the string is beyond the scope of this specification. 334 mac 335 REQUIRED. The HTTP request MAC as described in Section 3.3. 337 Attributes MUST NOT appear more than once. Attribute values are 338 limited to a subset of ASCII, which does not require escaping, as 339 defined by the plain-string ABNF. 341 3.2. Body Hash 343 [[ Need to figure out exactly when body-hash is required ]] 345 The body hash is used to provide integrity verification of the HTTP 346 request payload body. The body hash value is calculated using a hash 347 algorithm over the entire HTTP request payload body. 349 The client MAY include the body hash with any request. The server 350 SHOULD require the calculation and inclusion of the body hash with 351 any request containing an payload body, or when the presence (or lack 352 of) of an payload body is of significance. 354 The body hash algorithm is determined by the MAC algorithm. The 355 SHA-1 hash algorithm as defined by [NIST FIPS-180-3] is used with the 356 "hmac-sha-1" MAC algorithm. The SHA-256 hash algorithm as defined by 357 [NIST FIPS-180-3] is used with the "hmac-sha-256" MAC algorithm. 358 Additional MAC algorithms MUST specify the corresponding body hash 359 algorithm. 361 The body hash is calculated as follows: 363 bodyhash = BASE64 ( HASH (text) ) 365 Where: 367 HASH 368 is the hash algorithm function, 370 text 371 is the HTTP request payload body, 372 BASE64 373 is the base64-encoding function per [RFC2045] section 6.8, 374 applied to the hash result octet string, and 375 bodyhash 376 is the value used in the normalized request string and to set 377 the "bodyhash" attribute of the "Authorization" request header 378 field. 380 The body hash is calculated before the normalized request string is 381 constructed and the request MAC is calculated. 383 For example, the HTTP request: 385 POST /request HTTP/1.1 386 Host: example.net 387 Content-Type: application/x-www-form-urlencoded 389 hello=world%21 391 using MAC key identifier "jd93dh9dh39D", nonce "273156:di3hvdf8", MAC 392 algorithm "hmac-sha-1", and MAC key "8yfrufh348h", is transmitted as 393 (line breaks are for display purposes only): 395 POST /request HTTP/1.1 396 Host: example.com 397 Content-Type: application/x-www-form-urlencoded 398 Authorization: MAC id="jd93dh9dh39D", 399 nonce="273156:di3hvdf8", 400 bodyhash="k9kbtCIy0CkI3/FEfpS/oIDjk6k=", 401 mac="W7bdMZbv9UWOTadASIQHagZyirA=" 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 nonce value generated for the request. 425 2. The HTTP request method in upper case. For example: "HEAD", 426 "GET", "POST", etc. 427 3. The HTTP request-URI as defined by [RFC2616] section 5.1.2. 428 4. The hostname included in the HTTP request using the "Host" 429 request header field in lower case. 430 5. The port as included in the HTTP request using the "Host" request 431 header field. If the header field does not include a port, the 432 default value for the scheme MUST be used (e.g. 80 for HTTP and 433 443 for HTTPS). 434 6. The request payload body hash as described in Section 3.2 if one 435 was calculated and included in the request, otherwise, an empty 436 string. Note that the body hash of an empty payload body is not 437 an empty string. 438 7. The value of the "ext" "Authorization" request header field 439 attribute if one was included in the request, otherwise, an empty 440 string. 442 Each element is followed by a new line character (%x0A) including the 443 last element and even when an element value is an empty string. 445 For example, the HTTP request: 447 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1 448 Host: example.com 450 Hello World! 452 using nonce "264095:7d8f3e4a", body hash 453 "Lve95gjOVATpfV8EL5X4nxwjKHE=", and extension string "a,b,c" is 454 normalized into the following string (the new line separator 455 character is represented by "\n" for display purposes only): 457 264095:7d8f3e4a\n 458 POST\n 459 /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q\n 460 example.com\n 461 80\n 462 Lve95gjOVATpfV8EL5X4nxwjKHE=\n 463 a,b,c\n 465 3.3.2. hmac-sha-1 467 "hmac-sha-1" uses the HMAC-SHA1 algorithm as defined in [RFC2104]: 469 mac = HMAC-SHA1 (key, text) 471 Where: 473 text 474 is set to the value of the normalized request string as 475 described in Section 3.3.1, 476 key 477 is set to the MAC key provided by the server, and 478 mac 479 is used to set the value of the "mac" attribute, after the 480 result octet string is base64-encoded per [RFC2045] section 481 6.8. 483 The SHA-1 hash algorithm as defined by [NIST FIPS-180-3] is used for 484 generating the body hash attribute described in Section 3.2 when 485 using MAC credentials with the "hmac-sha-1" MAC algorithm. 487 3.3.3. hmac-sha-256 489 "hmac-sha-256" uses the HMAC algorithm as defined in [RFC2104] 490 together with the SHA-256 hash function defined in [NIST FIPS-180-3]: 492 mac = HMAC-SHA256 (key, text) 494 Where: 496 text 497 is set to the value of the normalize request string as 498 described in Section 3.3.1, 499 key 500 is set to the MAC key provided by the server, and 501 mac 502 is used to set the value of the "mac" attribute, after the 503 result octet string is base64-encoded per [RFC2045] section 504 6.8. 506 The SHA-256 hash algorithm as defined by [NIST FIPS-180-3] is used 507 for generating the body hash attribute described in Section 3.2 when 508 using MAC credentials with the "hmac-sha-256" MAC algorithm. 510 4. Verifying Requests 512 A server receiving an authenticated request validates it by 513 performing the following REQUIRED steps: 515 1. Recalculate the request body hash (if included in the request) as 516 described in Section 3.2 and request MAC as described in 517 Section 3.3 and compare the request MAC to the value received 518 from the client via the "mac" attribute. 519 2. Ensure that the combination of nonce and MAC key identifier 520 received from the client has not been used before in a previous 521 request (the server MAY reject requests with stale timestamps; 522 the determination of staleness is left up to the server to 523 define). 524 3. Verify the scope and validity of the MAC credentials. 526 If the request fails verification, the server response includes the 527 "WWW-Authenticate" response header field as described in Section 4.1 528 and SHOULD include one of the following HTTP status codes: 530 401 (Unauthorized) 531 The "Authorization" request header field is not included, 532 missing a required parameter, includes an unsupported parameter 533 or parameter value, repeats the same parameter, or is otherwise 534 malformed. The MAC credentials provided are expired, revoked, 535 malformed, or invalid. The body hash or request MAC provided 536 do not match the values calculated by the server, or a body 537 hash is required but missing. 538 307 (Temporary Redirect) 539 Same as 401, with the exception that a human intervention at 540 the destination URI (identified by the "Location" response 541 header field) MAY resolve the issue (e.g. provide a login page 542 which upon a successful authentication will issue the user- 543 agent a new set of MAC credentials using the "Set-Cookie" 544 response header field as described in Section 6. 546 4.1. The "WWW-Authenticate" Response Header Field 548 If the protected resource request does not include authentication 549 credentials, contains an invalid MAC key identifier, or is malformed, 550 the server SHOULD include the HTTP "WWW-Authenticate" response header 551 field. 553 For example: 555 HTTP/1.1 401 Unauthorized 556 WWW-Authenticate: MAC 558 The "WWW-Authenticate" request header field uses the framework 559 defined by [RFC2617] as follows: 561 challenge = "MAC" [ RWS 1#param ] 562 param = error / auth-param 563 error = "error" "=" quoted-string 565 Each attribute MUST NOT appear more than once. 567 If the protected resource request included a MAC "Authorization" 568 request header field and failed authentication, the server MAY 569 include the "error" attribute to provide the client with a human- 570 readable explanation why the access request was declined. 572 For example: 574 HTTP/1.1 401 Unauthorized 575 WWW-Authenticate: MAC error="The MAC credentials expired" 577 5. Use with OAuth 2.0 579 OAuth 2.0 ([I-D.ietf-oauth-v2]) defines a token-based authentication 580 framework in which third-party applications (clients) access 581 protected resources using access tokens. Access tokens are obtained 582 via the resource owners' authorization from an authorization server. 583 This specification defines the OAuth 2.0 MAC token type, as well as 584 type-specific token attributes. 586 This specification does not define methods for the client to 587 specifically request a MAC-type token from the authorization server. 588 Additionally, it does not include any discovery facilities for 589 identifying which HMAC algorithms are supported by a resource server, 590 or how the client may go about obtaining MAC access tokens for any 591 given protected resource. 593 The authorization server MUST require the use of a transport-layer 594 security mechanism when sending requests to the token endpoint to 595 obtain a MAC token. 597 5.1. Issuing MAC-Type Access Tokens 599 Authorization servers issuing MAC-type access tokens MUST include the 600 following parameters whenever a response includes the "access_token" 601 parameter: 603 access_token 604 REQUIRED. The MAC key identifier. 605 mac_key 606 REQUIRED. The MAC key. 607 mac_algorithm 608 REQUIRED. The MAC algorithm used to calculate the request MAC. 609 Value MUST be one of "hmac-sha-1", "hmac-sha-256", or a 610 registered extension algorithm name as described in 611 Section 8.1. 613 For example: 615 HTTP/1.1 200 OK 616 Content-Type: application/json 617 Cache-Control: no-store 619 { 620 "access_token":"SlAV32hkKG", 621 "token_type":"mac", 622 "expires_in":3600, 623 "refresh_token":"8xLOxBtZp8", 624 "mac_key":"adijq39jdlaska9asud", 625 "mac_algorithm":"hmac-sha-256" 626 } 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 server MUST only include the "MAC-Key" attribute in response to 643 requests made using a transport-layer security mechanism such as TLS 644 1.2 as defined in [RFC5246]. Clients MUST discard any MAC 645 credentials received over an insecure channel. 647 For example, after a successful end-user authentication, the server 648 includes the following response header field (line breaks are for 649 display purposes only): 651 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com; 652 MAC-Key=8yfrufh348h; MAC-Algorithm=hmac-sha-1 654 which provides the client with the necessary MAC credentials. The 655 cookie name "SID" is used as the MAC key identifier together with the 656 other MAC-specific attributes. The user-agent uses the MAC 657 credentials for subsequent HTTP requests that match the scope of the 658 cookie, in this case for "example.com" and all subdomains. 660 6.1. User Agent Requirements 662 This section updates [RFC6265], adding the ability to issue MAC 663 credentials using the "Set-Cookie " response header field. 665 6.1.1. The Set-Cookie Header 667 Add the following two subsections to the end of Section 5.2 (The Set- 668 Cookie Header) in [RFC6265]. These sections instruct the user-agent 669 how to parse the "MAC-Key" attribute and "MAC-Algorithm" attribute, 670 respectively. 672 6.1.1.1. The MAC-Key attribute 674 If the attribute-name case-insensitively matches the string 675 "MAC-Key", the user-agent MUST append an attribute to the cookie- 676 attribute-list with an attribute name of "MAC-Key" and a attribute- 677 value equal to the attribute-value. 679 6.1.1.2. The MAC-Algorithm attribute 681 If the attribute-name case-insensitively matches the string 682 "MAC-Algorithm", and if the attribute-value is either "hmac-sha-1", 683 "hmac-sha-256", or a registered extension value, the user-agent MUST 684 append an attribute to the cookie-attribute-list with an attribute 685 name of "MAC-Algorithm" and an attribute-value equal to the 686 attribute-value. 688 6.1.2. Storage Model 690 The storage model for cookies is extended with two additional fields: 691 "mac-key" and "mac-algorithm", all of which default to the empty 692 string. 694 The user-agent MUST perform the follow steps after Step 10 of the 695 algorithm in Section 5.3 of [RFC6265]: 697 1. If the cookie-attribute-list contains an attribute with an 698 attribute-name of "MAC-Key", set the cookie's "mac-key" field to 699 the attribute-value of the last such attribute. 700 2. If the cookie-attribute-list contains an attribute with an 701 attribute-name of "Mac-Algorithm", set the cookie's 702 "mac-algorithm" field to the attribute-value of the last such 703 attribute. 705 When the user agent removes excess cookies from the cookie store 706 because there are more than a predetermined number of cookies that 707 share a domain field, or the combined length of cookies sharing a 708 single domain field or being sent in a single request have exceeded a 709 predetermined length, the user agent MUST evict cookies with an empty 710 mac-key or an empty mac-algorithm field before cookies with both a 711 non-empty mac-key and a non-empty mac-algorithm field. 713 6.1.3. The Authorization Header 715 In addition to being sent to the server in the "Cookie" request 716 header field, cookies with "MAC-Key" and "MAC-Algorithm" attributes 717 are also used to compute the "Authorization" request header field as 718 described in Section 3.1. 720 The user-agent MAY ignore cookies for the purpose of generating the 721 "Authorization" request header field. For example, the user-agent 722 might wish to ignore cookies when issuing "third-party" requests or 723 use MAC credentials obtained via other means. 725 When issuing an HTTP request, let cookie-list be the set of cookies 726 defined in Section 5.4 of [RFC6265]. Further, let mac-cookie-list be 727 those cookies in the cookie-list that contain both a non-empty 728 "mac-key" and "mac-algorithm" fields. 730 Let the operative-cookie be the first cookie in the mac-cookie-list. 732 Include an "Authorization" request header field in the HTTP request 733 as described in Section 3.1 using the cookie's MAC credentials where: 735 MAC key identifier 736 is equal to the operative-cookie's name, 737 MAC key 738 is equal to the operative-cookie's "mac-key", 739 MAC algorithm 740 is equal to the operative-cookie's "mac-algorithm", and 741 Issue time 742 is equal to the operative-cookie's "creation-time". 744 7. Security Considerations 746 As stated in [RFC2617], the greatest sources of risks are usually 747 found not in the core protocol itself but in policies and procedures 748 surrounding its use. Implementers are strongly encouraged to assess 749 how this protocol addresses their security requirements. 751 7.1. MAC Keys Transmission 753 This specification describes two mechanism for obtaining or 754 transmitting MAC keys, both require the use of a transport-layer 755 security mechanism when sending MAC keys to the client. Additional 756 methods used to obtain MAC credentials must ensure that these 757 transmissions are protected using transport-layer mechanisms such as 758 TLS or SSL. 760 7.2. Confidentiality of Requests 762 While this protocol provides a mechanism for verifying the integrity 763 of requests, it provides no guarantee of request confidentiality. 764 Unless further precautions are taken, eavesdroppers will have full 765 access to request content. Servers should carefully consider the 766 kinds of data likely to be sent as part of such requests, and should 767 employ transport-layer security mechanisms to protect sensitive 768 resources. 770 7.3. Spoofing by Counterfeit Servers 772 This protocol makes no attempt to verify the authenticity of the 773 server. A hostile party could take advantage of this by intercepting 774 the client's requests and returning misleading or otherwise incorrect 775 responses. Service providers should consider such attacks when 776 developing services using this protocol, and should require 777 transport-layer security for any requests where the authenticity of 778 the resource server or of request responses is an issue. 780 7.4. Plaintext Storage of Credentials 782 The MAC key functions the same way passwords do in traditional 783 authentication systems. In order to compute the request MAC, the 784 server must have access to the MAC key in plaintext form. This is in 785 contrast, for example, to modern operating systems, which store only 786 a one-way hash of user credentials. 788 If an attacker were to gain access to these MAC keys - or worse, to 789 the server's database of all such MAC keys - he or she would be able 790 to perform any action on behalf of any resource owner. Accordingly, 791 it is critical that servers protect these MAC keys from unauthorized 792 access. 794 7.5. Entropy of MAC Keys 796 Unless a transport-layer security protocol is used, eavesdroppers 797 will have full access to authenticated requests and request MAC 798 values, and will thus be able to mount offline brute-force attacks to 799 recover the MAC key used. Servers should be careful to assign MAC 800 keys which are long enough, and random enough, to resist such attacks 801 for at least the length of time that the MAC credentials are valid. 803 For example, if the MAC credentials are valid for two weeks, servers 804 should ensure that it is not possible to mount a brute force attack 805 that recovers the MAC key in less than two weeks. Of course, servers 806 are urged to err on the side of caution, and use the longest MAC key 807 reasonable. 809 It is equally important that the pseudo-random number generator 810 (PRNG) used to generate these MAC keys be of sufficiently high 811 quality. Many PRNG implementations generate number sequences that 812 may appear to be random, but which nevertheless exhibit patterns or 813 other weaknesses which make cryptanalysis or brute force attacks 814 easier. Implementers should be careful to use cryptographically 815 secure PRNGs to avoid these problems. 817 7.6. Denial of Service / Resource Exhaustion Attacks 819 This specification includes a number of features which may make 820 resource exhaustion attacks against servers possible. For example, 821 this protocol requires servers to track used nonces. If an attacker 822 is able to use many nonces quickly, the resources required to track 823 them may exhaust available capacity. And again, this protocol can 824 require servers to perform potentially expensive computations in 825 order to verify the request MAC on incoming requests. An attacker 826 may exploit this to perform a denial of service attack by sending a 827 large number of invalid requests to the server. 829 Resource Exhaustion attacks are by no means specific to this 830 specification. However, implementers should be careful to consider 831 the additional avenues of attack that this protocol exposes, and 832 design their implementations accordingly. For example, entropy 833 starvation typically results in either a complete denial of service 834 while the system waits for new entropy or else in weak (easily 835 guessable) MAC keys. When implementing this protocol, servers should 836 consider which of these presents a more serious risk for their 837 application and design accordingly. 839 7.7. Timing Attacks 841 This specification makes use of HMACs, for which a signature 842 verification involves comparing the received MAC string to the 843 expected one. If the string comparison operator operates in 844 observably different times depending on inputs, e.g. because it 845 compares the strings character by character and returns a negative 846 result as soon as two characters fail to match, then it may be 847 possible to use this timing information to determine the expected 848 MAC, character by character. 850 Service implementers are encouraged to use fixed-time string 851 comparators for MAC verification. 853 7.8. CSRF Attacks 855 A Cross-Site Request Forgery attack occurs when a site, evil.com, 856 initiates within the victim's browser the loading of a URL from or 857 the posting of a form to a web site where a side-effect will occur, 858 e.g. transfer of money, change of status message, etc. To prevent 859 this kind of attack, web sites may use various techniques to 860 determine that the originator of the request is indeed the site 861 itself, rather than a third party. The classic approach is to 862 include, in the set of URL parameters or form content, a nonce 863 generated by the server and tied to the user's session, which 864 indicates that only the server could have triggered the action. 866 Recently, the Origin HTTP header has been proposed and deployed in 867 some browsers. This header indicates the scheme, host, and port of 868 the originator of a request. Some web applications may use this 869 Origin header as a defense against CSRF. 871 To keep this specification simple, HTTP headers are not part of the 872 string to be MAC'ed. As a result, MAC authentication cannot defend 873 against header spoofing, and a web site that uses the Host header to 874 defend against CSRF attacks cannot use MAC authentication to defend 875 against active network attackers. Sites that want the full 876 protection of MAC Authentication should use traditional, cookie-tied 877 CSRF defenses. 879 7.9. Coverage Limitations 881 The normalized request string has been designed to support the 882 authentication methods defined in this specification. Those 883 designing additional methods, should evaluated the compatibility of 884 the normalized request string with their security requirements. 885 Since the normalized request string does not cover the entire HTTP 886 request, servers should employ additional mechanisms to protect such 887 elements. 889 The request MAC does not cover entity-header fields which can often 890 affect how the request body is interpreted by the server (i.e. 891 Content-Type). If the server behavior is influenced by the presence 892 or value of such header fields, an attacker can manipulate the 893 request header without being detected. This will alter the request 894 even when using the body hash attribute. 896 7.10. Version Rollback Attack 898 [[ TODO ]] 900 8. IANA Considerations 902 8.1. The HTTP MAC Authentication Scheme Algorithm Registry 904 This specification establishes the HTTP MAC authentication scheme 905 algorithm registry. 907 Additional MAC algorithms are registered on the advice of one or more 908 Designated Experts (appointed by the IESG or their delegate), with a 909 Specification Required (using terminology from [RFC5226]). However, 910 to allow for the allocation of values prior to publication, the 911 Designated Expert(s) may approve registration once they are satisfied 912 that such a specification will be published. 914 Registration requests should be sent to the [TBD]@ietf.org mailing 915 list for review and comment, with an appropriate subject (e.g., 916 "Request for MAC Algorithm: example"). [[ Note to RFC-EDITOR: The 917 name of the mailing list should be determined in consultation with 918 the IESG and IANA. Suggested name: http-mac-ext-review. ]] 920 Within at most 14 days of the request, the Designated Expert(s) will 921 either approve or deny the registration request, communicating this 922 decision to the review list and IANA. Denials should include an 923 explanation and, if applicable, suggestions as to how to make the 924 request successful. 926 Decisions (or lack thereof) made by the Designated Expert can be 927 first appealed to Application Area Directors (contactable using 928 app-ads@tools.ietf.org email address or directly by looking up their 929 email addresses on http://www.iesg.org/ website) and, if the 930 appellant is not satisfied with the response, to the full IESG (using 931 the iesg@iesg.org mailing list). 933 IANA should only accept registry updates from the Designated 934 Expert(s), and should direct all requests for registration to the 935 review mailing list. 937 8.1.1. Registration Template 939 Algorithm name: 940 The name requested (e.g., "example"). 941 Body hash algorithm: 942 The corresponding algorithm used to calculate the payload body 943 hash. 944 Change controller: 945 For standards-track RFCs, state "IETF". For others, give the name 946 of the responsible party. Other details (e.g., postal address, 947 e-mail address, home page URI) may also be included. 948 Specification document(s): 949 Reference to document that specifies the algorithm, preferably 950 including a URI that can be used to retrieve a copy of the 951 document. An indication of the relevant sections may also be 952 included, but is not required. 954 8.1.2. Initial Registry Contents 956 The HTTP MAC authentication scheme algorithm registry's initial 957 contents are: 959 o Algorithm name: hmac-sha-1 960 o Body hash algorithm: sha-1 961 o Change controller: IETF 962 o Specification document(s): [[ this document ]] 964 o Algorithm name: hmac-sha-256 965 o Body hash algorithm: sha-256 966 o Change controller: IETF 967 o Specification document(s): [[ this document ]] 969 8.2. OAuth Access Token Type Registration 971 This specification registers the following access token type in the 972 OAuth Access Token Type Registry. 974 8.2.1. The "mac" OAuth Access Token Type 976 Type name: 977 mac 978 Additional Token Endpoint Response Parameters: 979 secret, algorithm 980 HTTP Authentication Scheme(s): 981 MAC 982 Change controller: 983 IETF 984 Specification document(s): 985 [[ this document ]] 987 8.3. OAuth Parameters Registration 989 This specification registers the following parameters in the OAuth 990 Parameters Registry established by [I-D.ietf-oauth-v2]. 992 8.3.1. The "mac_key" OAuth Parameter 994 Parameter name: mac_key 995 Parameter usage location: authorization response, token response 996 Change controller: IETF 997 Specification document(s): [[ this document ]] 998 Related information: None 1000 8.3.2. The "mac_algorithm" OAuth Parameter 1002 Parameter name: mac_algorithm 1003 Parameter usage location: authorization response, token response 1004 Change controller: IETF 1005 Specification document(s): [[ this document ]] 1006 Related information: None 1008 9. Acknowledgments 1010 The authors would like to thank Rasmus Lerdorf, James Manger, Scott 1011 Renfro, Toby White, Peter Wolanin, and Skylar Woodward for their 1012 suggestions and feedback. 1014 Appendix A. Document History 1016 [[ To be removed by the RFC editor before publication as an RFC. ]] 1018 -00 1020 o Initial working group document based on 1021 draft-hammer-oauth-v2-mac-token-05. 1023 10. References 1025 10.1. Normative References 1027 [I-D.ietf-httpbis-p1-messaging] 1028 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 1029 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 1030 "HTTP/1.1, part 1: URIs, Connections, and Message 1031 Parsing", draft-ietf-httpbis-p1-messaging-13 (work in 1032 progress), March 2011. 1034 [I-D.ietf-oauth-v2] 1035 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 1036 2.0 Authorization Protocol", draft-ietf-oauth-v2-15 (work 1037 in progress), April 2011. 1039 [NIST FIPS-180-3] 1040 National Institute of Standards and Technology, "Secure 1041 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 1043 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1044 Extensions (MIME) Part One: Format of Internet Message 1045 Bodies", RFC 2045, November 1996. 1047 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1048 Hashing for Message Authentication", RFC 2104, 1049 February 1997. 1051 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1052 Requirement Levels", BCP 14, RFC 2119, March 1997. 1054 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1055 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1056 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1058 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1059 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1060 Authentication: Basic and Digest Access Authentication", 1061 RFC 2617, June 1999. 1063 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1064 Resource Identifier (URI): Generic Syntax", STD 66, 1065 RFC 3986, January 2005. 1067 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1068 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1069 May 2008. 1071 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1072 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1074 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1075 April 2011. 1077 [W3C.REC-html401-19991224] 1078 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 1079 Specification", World Wide Web Consortium 1080 Recommendation REC-html401-19991224, December 1999, 1081 . 1083 10.2. Informative References 1085 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 1086 April 2010. 1088 Authors' Addresses 1090 Eran Hammer-Lahav (editor) 1091 Yahoo! 1093 Email: eran@hueniverse.com 1094 URI: http://hueniverse.com 1096 Adam Barth 1097 Google 1099 Email: ietf@adambarth.com 1100 URI: http://www.adambarth.com 1102 Ben Adida 1103 Mozilla 1105 Email: ben@adida.net 1106 URI: http://ben.adida.net