idnits 2.17.1 draft-hammer-oauth-v2-mac-token-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (May 10, 2011) is 4736 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 1072, but no explicit reference was found in the text == Unused Reference: 'RFC5849' is defined on line 1094, 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 11, 2011 Google 6 B. Adida 7 Mozilla 8 May 10, 2011 10 HTTP Authentication: MAC Access Authentication 11 draft-hammer-oauth-v2-mac-token-05 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 11, 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 . . . . . . . . . . . . . . . . . . . . . . . . 8 63 3.3. Request MAC . . . . . . . . . . . . . . . . . . . . . . . 10 64 3.3.1. Normalized Request String . . . . . . . . . . . . . . 10 65 3.3.2. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . . 11 66 3.3.3. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . . 12 67 4. Verifying Requests . . . . . . . . . . . . . . . . . . . . . . 12 68 4.1. The "WWW-Authenticate" Response Header Field . . . . . . . 13 69 5. Use with OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . 14 70 5.1. Issuing MAC-Type Access Tokens . . . . . . . . . . . . . . 14 71 6. Use with Set-Cookie . . . . . . . . . . . . . . . . . . . . . 15 72 6.1. User Agent Requirements . . . . . . . . . . . . . . . . . 15 73 6.1.1. The Set-Cookie Header . . . . . . . . . . . . . . . . 16 74 6.1.2. Storage Model . . . . . . . . . . . . . . . . . . . . 16 75 6.1.3. The Authorization Header . . . . . . . . . . . . . . . 17 76 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 77 7.1. MAC Keys Transmission . . . . . . . . . . . . . . . . . . 17 78 7.2. Confidentiality of Requests . . . . . . . . . . . . . . . 18 79 7.3. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 18 80 7.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 18 81 7.5. Entropy of MAC Keys . . . . . . . . . . . . . . . . . . . 18 82 7.6. Denial of Service / Resource Exhaustion Attacks . . . . . 19 83 7.7. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 19 84 7.8. CSRF Attacks . . . . . . . . . . . . . . . . . . . . . . . 19 85 7.9. Coverage Limitations . . . . . . . . . . . . . . . . . . . 20 86 7.10. Version Rollback Attack . . . . . . . . . . . . . . . . . 20 87 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 88 8.1. The HTTP MAC Authentication Scheme Algorithm Registry . . 21 89 8.1.1. Registration Template . . . . . . . . . . . . . . . . 21 90 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 22 91 8.2. OAuth Access Token Type Registration . . . . . . . . . . . 22 92 8.2.1. The "mac" OAuth Access Token Type . . . . . . . . . . 22 93 8.3. OAuth Parameters Registration . . . . . . . . . . . . . . 22 94 8.3.1. The "secret" OAuth Parameter . . . . . . . . . . . . . 22 95 8.3.2. The "algorithm" OAuth Parameter . . . . . . . . . . . 23 97 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 98 Appendix A. Document History . . . . . . . . . . . . . . . . . . 23 99 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 100 10.1. Normative References . . . . . . . . . . . . . . . . . . . 24 101 10.2. Informative References . . . . . . . . . . . . . . . . . . 25 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26 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 Issue time: Thu, 02 Dec 2010 21:39:45 GMT 158 The client constructs the authentication header by calculating the 159 credentials' age (number of seconds since the credentials were 160 issued) and generating a random string used to construct a nonce: 162 Age: 264095 163 Random string: dj83hs9s 164 Nonce: 264095:dj83hs9s 166 The client constructs the normalized request string (the new line 167 separator character is represented by "\n" for display purposes only; 168 the two trailing new line separators signify that no body hash or 169 extension value are included with the request, explained below): 171 264095:dj83hs9s\n 172 GET\n 173 /resource/1?b=1&a=2\n 174 example.com\n 175 80\n 176 \n 177 \n 179 The request MAC is calculated using the specified MAC algorithm 180 "hmac-sha-1" and the MAC key over the normalized request string. The 181 result is base64-encoded to produce the request MAC: 183 SLDJd4mg43cjQfElUs3Qub4L6xE= 185 The client includes the MAC key identifier, nonce, and request MAC 186 with the request using the "Authorization" request header field: 188 GET /resource/1?b=1&a=2 HTTP/1.1 189 Host: example.com 190 Authorization: MAC id="h480djs93hd8", 191 nonce="264095:dj83hs9s", 192 mac="SLDJd4mg43cjQfElUs3Qub4L6xE=" 194 The server validates the request by calculating the request MAC again 195 based on the request received and verifies the validity and scope of 196 the MAC credentials. If valid, the server responds with the 197 requested resource representation. 199 1.2. Notational Conventions 201 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 202 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 203 specification are to be interpreted as described in [RFC2119]. 205 This specification uses the Augmented Backus-Naur Form (ABNF) 206 notation of [I-D.ietf-httpbis-p1-messaging]. Additionally, the 207 following rules are included from [RFC2617]: auth-param. 209 2. Issuing MAC Credentials 211 This specification defines two method for issuing MAC credentials 212 using OAuth 2.0 as described in Section 5 and using the HTTP 213 "Set-Cookie" response header field as described in Section 6. 215 This specification does not mandate servers to support any particular 216 method for issuing MAC credentials, and other methods MAY be defined 217 and used. Whenever MAC credentials are issued, the credentials MUST 218 include the following attributes: 220 MAC key identifier 221 A string identifying the MAC key used to calculate the request 222 MAC. The string is usually opaque to the client. The server 223 typically assigns a specific scope and lifetime to each set of 224 MAC credentials. The identifier MAY denote a unique value used 225 to retrieve the authorization information (e.g. from a 226 database), or self-contain the authorization information in a 227 verifiable manner (i.e. a string consisting of some data and a 228 signature). 229 MAC key 230 A shared symmetric secret used as the MAC algorithm key. The 231 server MUST NOT issue the same MAC key and MAC key identifier 232 combination. 233 MAC algorithm 234 A MAC algorithm used to calculate the request MAC. Value MUST 235 be one of "hmac-sha-1", "hmac-sha-256", or a registered 236 extension algorithm name as described in Section 8.1. 237 Algorithm names are case-sensitive. If the MAC algorithm is 238 not understood by the client, the client MUST NOT use the MAC 239 credentials and continue as if no MAC credentials were issued. 240 Issue time 241 The time when the credentials were issued, used to calculate 242 the credentials age when making requests. If the MAC 243 credentials were obtained via an HTTP response, the time of 244 issue is the time the response was received by the client. 246 The MAC key identifier, MAC key, MAC algorithm strings MUST NOT 247 include characters other than: 249 %x20-21 / %x23-5B / %x5D-7E 250 ; Any printable ASCII character except for <"> and <\> 252 3. Making Requests 254 To make authenticated requests, the client must be in the possession 255 of a valid set of MAC credentials accepted by the server. The client 256 constructs the request by calculating a set of attributes, and adding 257 them to the HTTP request using the "Authorization" request header 258 field as described in Section 3.1. 260 3.1. The "Authorization" Request Header 262 The "Authorization" request header field uses the framework defined 263 by [RFC2617] as follows: 265 credentials = "MAC" [ RWS 1#param ] 267 param = id / 268 nonce / 269 body-hash / 270 ext / 271 mac 273 id = "id" "=" <"> plain-string <"> 274 nonce = "nonce" "=" <"> 1*DIGIT ":" plain-string <"> 275 body-hash = "bodyhash" "=" <"> plain-string <"> 276 ext = "ext" "=" <"> plain-string <"> 277 mac = "mac" "=" <"> plain-string <"> 279 plain-string = 1*( %x20-21 / %x23-5B / %x5D-7E ) 281 The header attributes are set as follows: 283 id 284 REQUIRED. The MAC key identifier. 285 nonce 286 REQUIRED. A unique string generated by the client to allow the 287 server to verify that a request has never been made before and 288 helps prevent replay attacks when requests are made over an 289 insecure channel. The nonce value MUST be unique across all 290 requests with the same MAC key identifier. 291 The nonce value MUST consist of the age of the MAC credentials 292 expressed as the number of seconds since the credentials were 293 issued to the client, a colon character (%x25), and a unique 294 string (typically random). The age value MUST be a positive 295 integer and MUST NOT include leading zeros (e.g. 296 "000137131200"). For example: "273156:di3hvdf8". 297 To avoid the need to retain an infinite number of nonce values 298 for future checks, the server MAY choose to restrict the time 299 period after which a request with an old age is rejected. If 300 such a restriction is enforced, the server SHOULD allow for a 301 sufficiently large window to accommodate network delays which 302 will affect the credentials issue time used by the client to 303 calculate the credentials' age. 304 bodyhash 305 OPTIONAL. The HTTP request payload body hash as described in 306 Section 3.2. 307 ext 308 OPTIONAL. A string used to include additional information 309 which is covered by the request MAC. The content and format of 310 the string is beyond the scope of this specification. 311 mac 312 REQUIRED. The HTTP request MAC as described in Section 3.3. 314 Attributes MUST NOT appear more than once. Attribute values are 315 limited to a subset of ASCII, which does not require escaping, as 316 defined by the plain-string ABNF. 318 3.2. Body Hash 320 [[ Need to figure out exactly when body-hash is required ]] 322 The body hash is used to provide integrity verification of the HTTP 323 request payload body. The body hash value is calculated using a hash 324 algorithm over the entire HTTP request payload body. 326 The client MAY include the body hash with any request. The server 327 SHOULD require the calculation and inclusion of the body hash with 328 any request containing an payload body, or when the presence (or lack 329 of) of an payload body is of significance. 331 The body hash algorithm is determined by the MAC algorithm. The 332 SHA-1 hash algorithm as defined by [NIST FIPS-180-3] is used with the 333 "hmac-sha-1" MAC algorithm. The SHA-256 hash algorithm as defined by 334 [NIST FIPS-180-3] is used with the "hmac-sha-256" MAC algorithm. 335 Additional MAC algorithms MUST specify the corresponding body hash 336 algorithm. 338 The body hash is calculated as follows: 340 bodyhash = BASE64 ( HASH (text) ) 342 Where: 344 HASH 345 is the hash algorithm function, 346 text 347 is the HTTP request payload body, 348 BASE64 349 is the base64-encoding function per [RFC2045] section 6.8, 350 applied to the hash result octet string, and 351 bodyhash 352 is the value used in the normalized request string and to set 353 the "bodyhash" attribute of the "Authorization" request header 354 field. 356 The body hash is calculated before the normalized request string is 357 constructed and the request MAC is calculated. 359 For example, the HTTP request: 361 POST /request HTTP/1.1 362 Host: example.net 363 Content-Type: application/x-www-form-urlencoded 365 hello=world%21 367 using MAC key identifier "jd93dh9dh39D", nonce "273156:di3hvdf8", MAC 368 algorithm "hmac-sha-1", and MAC key "8yfrufh348h", is transmitted as 369 (line breaks are for display purposes only): 371 POST /request HTTP/1.1 372 Host: example.com 373 Content-Type: application/x-www-form-urlencoded 374 Authorization: MAC id="jd93dh9dh39D", 375 nonce="273156:di3hvdf8", 376 bodyhash="k9kbtCIy0CkI3/FEfpS/oIDjk6k=", 377 mac="W7bdMZbv9UWOTadASIQHagZyirA=" 379 hello=world%21 381 3.3. Request MAC 383 The client uses the MAC algorithm and the MAC key to calculate the 384 request MAC. This specification defines two algorithms: "hmac-sha-1" 385 and "hmac-sha-256", and provides an extension registry for additional 386 algorithms. 388 3.3.1. Normalized Request String 390 The normalized request string is a consistent, reproducible 391 concatenation of several of the HTTP request elements into a single 392 string. By normalizing the request into a reproducible string, the 393 client and server can both calculate the request MAC over the exact 394 same value. 396 The string is constructed by concatenating together, in order, the 397 following HTTP request elements, each followed by a new line 398 character (%x0A): 400 1. The nonce value generated for the request. 401 2. The HTTP request method in upper case. For example: "HEAD", 402 "GET", "POST", etc. 403 3. The HTTP request-URI as defined by [RFC2616] section 5.1.2. 404 4. The hostname included in the HTTP request using the "Host" 405 request header field in lower case. 406 5. The port as included in the HTTP request using the "Host" request 407 header field. If the header field does not include a port, the 408 default value for the scheme MUST be used (e.g. 80 for HTTP and 409 443 for HTTPS). 410 6. The request payload body hash as described in Section 3.2 if one 411 was calculated and included in the request, otherwise, an empty 412 string. Note that the body hash of an empty payload body is not 413 an empty string. 414 7. The value of the "ext" "Authorization" request header field 415 attribute if one was included in the request, otherwise, an empty 416 string. 418 Each element is followed by a new line character (%x0A) including the 419 last element and even when an element value is an empty string. 421 For example, the HTTP request: 423 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1 424 Host: example.com 426 Hello World! 428 using nonce "264095:7d8f3e4a", body hash 429 "Lve95gjOVATpfV8EL5X4nxwjKHE=", and extension string "a,b,c" is 430 normalized into the following string (the new line separator 431 character is represented by "\n" for display purposes only): 433 264095:7d8f3e4a\n 434 POST\n 435 /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q\n 436 example.com\n 437 80\n 438 Lve95gjOVATpfV8EL5X4nxwjKHE=\n 439 a,b,c\n 441 3.3.2. hmac-sha-1 443 "hmac-sha-1" uses the HMAC-SHA1 algorithm as defined in [RFC2104]: 445 mac = HMAC-SHA1 (key, text) 447 Where: 449 text 450 is set to the value of the normalized request string as 451 described in Section 3.3.1, 453 key 454 is set to the MAC key provided by the server, and 455 mac 456 is used to set the value of the "mac" attribute, after the 457 result octet string is base64-encoded per [RFC2045] section 458 6.8. 460 The SHA-1 hash algorithm as defined by [NIST FIPS-180-3] is used for 461 generating the body hash attribute described in Section 3.2 when 462 using MAC credentials with the "hmac-sha-1" MAC algorithm. 464 3.3.3. hmac-sha-256 466 "hmac-sha-256" uses the HMAC algorithm as defined in [RFC2104] 467 together with the SHA-256 hash function defined in [NIST FIPS-180-3]: 469 mac = HMAC-SHA256 (key, text) 471 Where: 473 text 474 is set to the value of the normalize 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-256 hash algorithm as defined by [NIST FIPS-180-3] is used 484 for generating the body hash attribute described in Section 3.2 when 485 using MAC credentials with the "hmac-sha-256" MAC algorithm. 487 4. Verifying Requests 489 A server receiving an authenticated request validates it by 490 performing the following REQUIRED steps: 492 1. Recalculate the request body hash (if included in the request) as 493 described in Section 3.2 and request MAC as described in 494 Section 3.3 and compare the request MAC to the value received 495 from the client via the "mac" attribute. 497 2. Ensure that the combination of nonce and MAC key identifier 498 received from the client has not been used before in a previous 499 request (the server MAY reject requests with stale timestamps; 500 the determination of staleness is left up to the server to 501 define). 502 3. Verify the scope and validity of the MAC credentials. 504 If the request fails verification, the server response includes the 505 "WWW-Authenticate" response header field as described in Section 4.1 506 and SHOULD include one of the following HTTP status codes: 508 401 (Unauthorized) 509 The "Authorization" request header field is not included, 510 missing a required parameter, includes an unsupported parameter 511 or parameter value, repeats the same parameter, or is otherwise 512 malformed. The MAC credentials provided are expired, revoked, 513 malformed, or invalid. The body hash or request MAC provided 514 do not match the values calculated by the server, or a body 515 hash is required but missing. 516 307 (Temporary Redirect) 517 Same as 401, with the exception that a human intervention at 518 the destination URI (identified by the "Location" response 519 header field) MAY resolve the issue (e.g. provide a login page 520 which upon a successful authentication will issue the user- 521 agent a new set of MAC credentials using the "Set-Cookie" 522 response header field as described in Section 6. 524 4.1. The "WWW-Authenticate" Response Header Field 526 If the protected resource request does not include authentication 527 credentials, contains an invalid MAC key identifier, or is malformed, 528 the server SHOULD include the HTTP "WWW-Authenticate" response header 529 field. 531 For example: 533 HTTP/1.1 401 Unauthorized 534 WWW-Authenticate: MAC 536 The "WWW-Authenticate" request header field uses the framework 537 defined by [RFC2617] as follows: 539 challenge = "MAC" [ RWS 1#param ] 540 param = error / auth-param 541 error = "error" "=" quoted-string 543 Each attribute MUST NOT appear more than once. 545 If the protected resource request included a MAC "Authorization" 546 request header field and failed authentication, the server MAY 547 include the "error" attribute to provide the client with a human- 548 readable explanation why the access request was declined. 550 For example: 552 HTTP/1.1 401 Unauthorized 553 WWW-Authenticate: MAC error="The MAC credentials expired" 555 5. Use with OAuth 2.0 557 OAuth 2.0 ([I-D.ietf-oauth-v2]) defines a token-based authentication 558 framework in which third-party applications (clients) access 559 protected resources using access tokens. Access tokens are obtained 560 via the resource owners' authorization from an authorization server. 561 This specification defines the OAuth 2.0 MAC token type, as well as 562 type-specific token attributes. 564 This specification does not define methods for the client to 565 specifically request a MAC-type token from the authorization server. 566 Additionally, it does not include any discovery facilities for 567 identifying which HMAC algorithms are supported by a resource server, 568 or how the client may go about obtaining MAC access tokens for any 569 given protected resource. 571 The authorization server MUST require the use of a transport-layer 572 security mechanism when sending requests to the token endpoint to 573 obtain a MAC token. 575 5.1. Issuing MAC-Type Access Tokens 577 Authorization servers issuing MAC-type access tokens MUST include the 578 following parameters whenever a response includes the "access_token" 579 parameter: 581 access_token 582 REQUIRED. The MAC key identifier. 583 secret 584 REQUIRED. The MAC key. 586 algorithm 587 REQUIRED. The MAC algorithm used to calculate the request MAC. 588 Value MUST be one of "hmac-sha-1", "hmac-sha-256", or a 589 registered extension algorithm name as described in 590 Section 8.1. 592 6. Use with Set-Cookie 594 The HTTP "Set-Cookie " response header field defined in [RFC6265] 595 enables the server to set persistent information which the client 596 repeats back on follow-up requests. Each cookie includes a name- 597 value pair which is sent back to the server, and a set of attributes 598 which inform the client when to include the cookie in follow-up 599 requests. The attributes are never sent back to the server. 601 This specification defines the "MAC-Key" and "MAC-Algorithm" cookie 602 attributes, which are used by the server, together with the cookie 603 name which includes the MAC key identifier, to issue the client a set 604 of MAC credentials. 606 The server MUST only include the "MAC-Key" attribute in response to 607 requests made using a transport-layer security mechanism such as TLS 608 1.2 as defined in [RFC5246]. Clients MUST discard any MAC 609 credentials received over an insecure channel. 611 For example, after a successful end-user authentication, the server 612 includes the following response header field (line breaks are for 613 display purposes only): 615 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com; 616 MAC-Key=8yfrufh348h; MAC-Algorithm=hmac-sha-1 618 which provides the client with the necessary MAC credentials. The 619 cookie name "SID" is used as the MAC key identifier together with the 620 other MAC-specific attributes. The user-agent uses the MAC 621 credentials for subsequent HTTP requests that match the scope of the 622 cookie, in this case for "example.com" and all subdomains. 624 6.1. User Agent Requirements 626 This section updates [RFC6265], adding the ability to issue MAC 627 credentials using the "Set-Cookie " response header field. 629 6.1.1. The Set-Cookie Header 631 Add the following two subsections to the end of Section 5.2 (The Set- 632 Cookie Header) in [RFC6265]. These sections instruct the user-agent 633 how to parse the "MAC-Key" attribute and "MAC-Algorithm" attribute, 634 respectively. 636 6.1.1.1. The MAC-Key attribute 638 If the attribute-name case-insensitively matches the string 639 "MAC-Key", the user-agent MUST append an attribute to the cookie- 640 attribute-list with an attribute name of "MAC-Key" and a attribute- 641 value equal to the attribute-value. 643 6.1.1.2. The MAC-Algorithm attribute 645 If the attribute-name case-insensitively matches the string 646 "MAC-Algorithm", and if the attribute-value is either "hmac-sha-1", 647 "hmac-sha-256", or a registered extension value, the user-agent MUST 648 append an attribute to the cookie-attribute-list with an attribute 649 name of "MAC-Algorithm" and an attribute-value equal to the 650 attribute-value. 652 6.1.2. Storage Model 654 The storage model for cookies is extended with two additional fields: 655 "mac-key" and "mac-algorithm", all of which default to the empty 656 string. 658 The user-agent MUST perform the follow steps after Step 10 of the 659 algorithm in Section 5.3 of [RFC6265]: 661 1. If the cookie-attribute-list contains an attribute with an 662 attribute-name of "MAC-Key", set the cookie's "mac-key" field to 663 the attribute-value of the last such attribute. 664 2. If the cookie-attribute-list contains an attribute with an 665 attribute-name of "Mac-Algorithm", set the cookie's 666 "mac-algorithm" field to the attribute-value of the last such 667 attribute. 669 When the user agent removes excess cookies from the cookie store 670 because there are more than a predetermined number of cookies that 671 share a domain field, or the combined length of cookies sharing a 672 single domain field or being sent in a single request have exceeded a 673 predetermined length, the user agent MUST evict cookies with an empty 674 mac-key or an empty mac-algorithm field before cookies with both a 675 non-empty mac-key and a non-empty mac-algorithm field. 677 6.1.3. The Authorization Header 679 In addition to being sent to the server in the "Cookie" request 680 header field, cookies with "MAC-Key" and "MAC-Algorithm" attributes 681 are also used to compute the "Authorization" request header field as 682 described in Section 3.1. 684 The user-agent MAY ignore cookies for the purpose of generating the 685 "Authorization" request header field. For example, the user-agent 686 might wish to ignore cookies when issuing "third-party" requests or 687 use MAC credentials obtained via other means. 689 When issuing an HTTP request, let cookie-list be the set of cookies 690 defined in Section 5.4 of [RFC6265]. Further, let mac-cookie-list be 691 those cookies in the cookie-list that contain both a non-empty 692 "mac-key" and "mac-algorithm" fields. 694 Let the operative-cookie be the first cookie in the mac-cookie-list. 696 Include an "Authorization" request header field in the HTTP request 697 as described in Section 3.1 using the cookie's MAC credentials where: 699 MAC key identifier 700 is equal to the operative-cookie's name, 701 MAC key 702 is equal to the operative-cookie's "mac-key", 703 MAC algorithm 704 is equal to the operative-cookie's "mac-algorithm", and 705 Issue time 706 is equal to the operative-cookie's "creation-time". 708 7. Security Considerations 710 As stated in [RFC2617], the greatest sources of risks are usually 711 found not in the core protocol itself but in policies and procedures 712 surrounding its use. Implementers are strongly encouraged to assess 713 how this protocol addresses their security requirements. 715 7.1. MAC Keys Transmission 717 This specification describes two mechanism for obtaining or 718 transmitting MAC keys, both require the use of a transport-layer 719 security mechanism when sending MAC keys to the client. Additional 720 methods used to obtain MAC credentials must ensure that these 721 transmissions are protected using transport-layer mechanisms such as 722 TLS or SSL. 724 7.2. Confidentiality of Requests 726 While this protocol provides a mechanism for verifying the integrity 727 of requests, it provides no guarantee of request confidentiality. 728 Unless further precautions are taken, eavesdroppers will have full 729 access to request content. Servers should carefully consider the 730 kinds of data likely to be sent as part of such requests, and should 731 employ transport-layer security mechanisms to protect sensitive 732 resources. 734 7.3. Spoofing by Counterfeit Servers 736 This protocol makes no attempt to verify the authenticity of the 737 server. A hostile party could take advantage of this by intercepting 738 the client's requests and returning misleading or otherwise incorrect 739 responses. Service providers should consider such attacks when 740 developing services using this protocol, and should require 741 transport-layer security for any requests where the authenticity of 742 the resource server or of request responses is an issue. 744 7.4. Plaintext Storage of Credentials 746 The MAC key functions the same way passwords do in traditional 747 authentication systems. In order to compute the request MAC, the 748 server must have access to the MAC key in plaintext form. This is in 749 contrast, for example, to modern operating systems, which store only 750 a one-way hash of user credentials. 752 If an attacker were to gain access to these MAC keys - or worse, to 753 the server's database of all such MAC keys - he or she would be able 754 to perform any action on behalf of any resource owner. Accordingly, 755 it is critical that servers protect these MAC keys from unauthorized 756 access. 758 7.5. Entropy of MAC Keys 760 Unless a transport-layer security protocol is used, eavesdroppers 761 will have full access to authenticated requests and request MAC 762 values, and will thus be able to mount offline brute-force attacks to 763 recover the MAC key used. Servers should be careful to assign MAC 764 keys which are long enough, and random enough, to resist such attacks 765 for at least the length of time that the MAC credentials are valid. 767 For example, if the MAC credentials are valid for two weeks, servers 768 should ensure that it is not possible to mount a brute force attack 769 that recovers the MAC key in less than two weeks. Of course, servers 770 are urged to err on the side of caution, and use the longest MAC key 771 reasonable. 773 It is equally important that the pseudo-random number generator 774 (PRNG) used to generate these MAC keys be of sufficiently high 775 quality. Many PRNG implementations generate number sequences that 776 may appear to be random, but which nevertheless exhibit patterns or 777 other weaknesses which make cryptanalysis or brute force attacks 778 easier. Implementers should be careful to use cryptographically 779 secure PRNGs to avoid these problems. 781 7.6. Denial of Service / Resource Exhaustion Attacks 783 This specification includes a number of features which may make 784 resource exhaustion attacks against servers possible. For example, 785 this protocol requires servers to track used nonces. If an attacker 786 is able to use many nonces quickly, the resources required to track 787 them may exhaust available capacity. And again, this protocol can 788 require servers to perform potentially expensive computations in 789 order to verify the request MAC on incoming requests. An attacker 790 may exploit this to perform a denial of service attack by sending a 791 large number of invalid requests to the server. 793 Resource Exhaustion attacks are by no means specific to this 794 specification. However, implementers should be careful to consider 795 the additional avenues of attack that this protocol exposes, and 796 design their implementations accordingly. For example, entropy 797 starvation typically results in either a complete denial of service 798 while the system waits for new entropy or else in weak (easily 799 guessable) MAC keys. When implementing this protocol, servers should 800 consider which of these presents a more serious risk for their 801 application and design accordingly. 803 7.7. Timing Attacks 805 This specification makes use of HMACs, for which a signature 806 verification involves comparing the received MAC string to the 807 expected one. If the string comparison operator operates in 808 observably different times depending on inputs, e.g. because it 809 compares the strings character by character and returns a negative 810 result as soon as two characters fail to match, then it may be 811 possible to use this timing information to determine the expected 812 MAC, character by character. 814 Service implementers are encouraged to use fixed-time string 815 comparators for MAC verification. 817 7.8. CSRF Attacks 819 A Cross-Site Request Forgery attack occurs when a site, evil.com, 820 initiates within the victim's browser the loading of a URL from or 821 the posting of a form to a web site where a side-effect will occur, 822 e.g. transfer of money, change of status message, etc. To prevent 823 this kind of attack, web sites may use various techniques to 824 determine that the originator of the request is indeed the site 825 itself, rather than a third party. The classic approach is to 826 include, in the set of URL parameters or form content, a nonce 827 generated by the server and tied to the user's session, which 828 indicates that only the server could have triggered the action. 830 Recently, the Origin HTTP header has been proposed and deployed in 831 some browsers. This header indicates the scheme, host, and port of 832 the originator of a request. Some web applications may use this 833 Origin header as a defense against CSRF. 835 To keep this specification simple, HTTP headers are not part of the 836 string to be MAC'ed. As a result, MAC authentication cannot defend 837 against header spoofing, and a web site that uses the Host header to 838 defend against CSRF attacks cannot use MAC authentication to defend 839 against active network attackers. Sites that want the full 840 protection of MAC Authentication should use traditional, cookie-tied 841 CSRF defenses. 843 7.9. Coverage Limitations 845 The normalized request string has been designed to support the 846 authentication methods defined in this specification. Those 847 designing additional methods, should evaluated the compatibility of 848 the normalized request string with their security requirements. 849 Since the normalized request string does not cover the entire HTTP 850 request, servers should employ additional mechanisms to protect such 851 elements. 853 The request MAC does not cover entity-header fields which can often 854 affect how the request body is interpreted by the server (i.e. 855 Content-Type). If the server behavior is influenced by the presence 856 or value of such header fields, an attacker can manipulate the 857 request header without being detected. This will alter the request 858 even when using the body hash attribute. 860 7.10. Version Rollback Attack 862 [[ TODO ]] 864 8. IANA Considerations 865 8.1. The HTTP MAC Authentication Scheme Algorithm Registry 867 This specification establishes the HTTP MAC authentication scheme 868 algorithm registry. 870 Additional MAC algorithms are registered on the advice of one or more 871 Designated Experts (appointed by the IESG or their delegate), with a 872 Specification Required (using terminology from [RFC5226]). However, 873 to allow for the allocation of values prior to publication, the 874 Designated Expert(s) may approve registration once they are satisfied 875 that such a specification will be published. 877 Registration requests should be sent to the [TBD]@ietf.org mailing 878 list for review and comment, with an appropriate subject (e.g., 879 "Request for MAC Algorithm: example"). [[ Note to RFC-EDITOR: The 880 name of the mailing list should be determined in consultation with 881 the IESG and IANA. Suggested name: http-mac-ext-review. ]] 883 Within at most 14 days of the request, the Designated Expert(s) will 884 either approve or deny the registration request, communicating this 885 decision to the review list and IANA. Denials should include an 886 explanation and, if applicable, suggestions as to how to make the 887 request successful. 889 Decisions (or lack thereof) made by the Designated Expert can be 890 first appealed to Application Area Directors (contactable using 891 app-ads@tools.ietf.org email address or directly by looking up their 892 email addresses on http://www.iesg.org/ website) and, if the 893 appellant is not satisfied with the response, to the full IESG (using 894 the iesg@iesg.org mailing list). 896 IANA should only accept registry updates from the Designated 897 Expert(s), and should direct all requests for registration to the 898 review mailing list. 900 8.1.1. Registration Template 902 Algorithm name: 903 The name requested (e.g., "example"). 904 Body hash algorithm: 905 The corresponding algorithm used to calculate the payload body 906 hash. 907 Change controller: 908 For standards-track RFCs, state "IETF". For others, give the name 909 of the responsible party. Other details (e.g., postal address, 910 e-mail address, home page URI) may also be included. 912 Specification document(s): 913 Reference to document that specifies the algorithm, preferably 914 including a URI that can be used to retrieve a copy of the 915 document. An indication of the relevant sections may also be 916 included, but is not required. 918 8.1.2. Initial Registry Contents 920 The HTTP MAC authentication scheme algorithm registry's initial 921 contents are: 923 o Algorithm name: hmac-sha-1 924 o Body hash algorithm: sha-1 925 o Change controller: IETF 926 o Specification document(s): [[ this document ]] 928 o Algorithm name: hmac-sha-256 929 o Body hash algorithm: sha-256 930 o Change controller: IETF 931 o Specification document(s): [[ this document ]] 933 8.2. OAuth Access Token Type Registration 935 This specification registers the following access token type in the 936 OAuth Access Token Type Registry. 938 8.2.1. The "mac" OAuth Access Token Type 940 Type name: 941 mac 942 Additional Token Endpoint Response Parameters: 943 secret, algorithm 944 HTTP Authentication Scheme(s): 945 MAC 946 Change controller: 947 IETF 948 Specification document(s): 949 [[ this document ]] 951 8.3. OAuth Parameters Registration 953 This specification registers the following parameters in the OAuth 954 Parameters Registry established by [I-D.ietf-oauth-v2]. 956 8.3.1. The "secret" OAuth Parameter 957 Parameter name: secret 958 Parameter usage location: authorization response, token response 959 Change controller: IETF 960 Specification document(s): [[ this document ]] 961 Related information: None 963 8.3.2. The "algorithm" OAuth Parameter 965 Parameter name: algorithm 966 Parameter usage location: authorization response, token response 967 Change controller: IETF 968 Specification document(s): [[ this document ]] 969 Related information: None 971 9. Acknowledgments 973 The authors would like to thank Rasmus Lerdorf, James Manger, Scott 974 Renfro, Toby White, Peter Wolanin, and Skylar Woodward for their 975 suggestions and feedback. 977 Appendix A. Document History 979 [[ To be removed by the RFC editor before publication as an RFC. ]] 981 -05 983 o Dropped issuer. 984 o Merged 'age' and 'nonce' attributes into a single attribute. 986 -04 988 o Added new 'ext' request attribute. 989 o Replaced 'timestamp' with 'age'. 990 o Dropped key identifier from normalized string. 991 o Clarified algorithm name and handling of unknown value. 992 o Include a single authorization header even if multiple MAC cookies 993 present. 994 o Dropped explicit mention of 403. 996 -03 998 o Changed access token terminology to MAC key identifier and access 999 token secret to MAC key. Changed corresponding parameter name 1000 from 'token' to 'id'. 1002 o Changed signature terminology to request MAC. Changed 1003 corresponding parameter name from 'signature' to 'mac'. 1004 o Added new 'Set-Cookie' header extension. 1005 o Added new 'issuer' attribute. 1006 o Defined algorithm registry. 1007 o Dropped request URI query normalization. Changed order of string 1008 components. 1010 -02 1012 o Added body-hash support. 1013 o Updated OAuth 2.0 reference and added token type registration 1014 template. 1015 o Removed error codes and error URI. 1017 -01 1019 o Changed parameters sorting to come after name=value string 1020 construction. 1021 o Added new line at the end of the normalized request string. 1022 o Moved OAuth2 references to separate section. 1023 o Added 'WWW-Authenticate' header definition. 1024 o Fixed example header use of single quote. 1025 o Restricted strings to ASCII subset (printable, no double-quotes or 1026 back-slash). 1028 -00 1030 o Initial draft. 1032 10. References 1034 10.1. Normative References 1036 [I-D.ietf-httpbis-p1-messaging] 1037 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 1038 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 1039 "HTTP/1.1, part 1: URIs, Connections, and Message 1040 Parsing", draft-ietf-httpbis-p1-messaging-13 (work in 1041 progress), March 2011. 1043 [I-D.ietf-oauth-v2] 1044 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 1045 2.0 Authorization Protocol", draft-ietf-oauth-v2-15 (work 1046 in progress), April 2011. 1048 [NIST FIPS-180-3] 1049 National Institute of Standards and Technology, "Secure 1050 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 1052 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1053 Extensions (MIME) Part One: Format of Internet Message 1054 Bodies", RFC 2045, November 1996. 1056 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1057 Hashing for Message Authentication", RFC 2104, 1058 February 1997. 1060 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1061 Requirement Levels", BCP 14, RFC 2119, March 1997. 1063 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1064 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1065 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1067 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1068 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1069 Authentication: Basic and Digest Access Authentication", 1070 RFC 2617, June 1999. 1072 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1073 Resource Identifier (URI): Generic Syntax", STD 66, 1074 RFC 3986, January 2005. 1076 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1077 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1078 May 2008. 1080 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1081 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1083 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1084 April 2011. 1086 [W3C.REC-html401-19991224] 1087 Hors, A., Jacobs, I., and D. Raggett, "HTML 4.01 1088 Specification", World Wide Web Consortium 1089 Recommendation REC-html401-19991224, December 1999, 1090 . 1092 10.2. Informative References 1094 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 1095 April 2010. 1097 URIs 1099 [1] 1101 Authors' Addresses 1103 Eran Hammer-Lahav 1104 Yahoo! 1106 Email: eran@hueniverse.com 1107 URI: http://hueniverse.com 1109 Adam Barth 1110 Google 1112 Email: ietf@adambarth.com 1113 URI: http://www.adambarth.com 1115 Ben Adida 1116 Mozilla 1118 Email: ben@adida.net 1119 URI: http://ben.adida.net