idnits 2.17.1 draft-hammer-oauth-v2-mac-token-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 732 has weird spacing: '... Issuer is eq...' == 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 (April 28, 2011) is 4739 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 1081, but no explicit reference was found in the text == Unused Reference: 'RFC5849' is defined on line 1103, 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 (~~), 7 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: October 30, 2011 Google 6 B. Adida 7 Mozilla 8 April 28, 2011 10 HTTP Authentication: MAC Access Authentication 11 draft-hammer-oauth-v2-mac-token-03 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 October 30, 2011. 39 Copyright Notice 41 Copyright (c) 2011 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 6 59 2. Issuing MAC Credentials . . . . . . . . . . . . . . . . . . . 6 60 3. Making Requests . . . . . . . . . . . . . . . . . . . . . . . 7 61 3.1. The "Authorization" Request Header . . . . . . . . . . . . 7 62 3.2. Body Hash . . . . . . . . . . . . . . . . . . . . . . . . 9 63 3.3. Request MAC . . . . . . . . . . . . . . . . . . . . . . . 10 64 3.3.1. Normalized Request String . . . . . . . . . . . . . . 10 65 3.3.2. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . . 12 66 3.3.3. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . . 12 67 4. Verifying Requests . . . . . . . . . . . . . . . . . . . . . . 13 68 4.1. The "WWW-Authenticate" Response Header Field . . . . . . . 14 69 5. Use with OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . 15 70 5.1. Issuing MAC-Type Access Tokens . . . . . . . . . . . . . . 15 71 6. Use with Set-Cookie . . . . . . . . . . . . . . . . . . . . . 15 72 6.1. User Agent Requirements . . . . . . . . . . . . . . . . . 16 73 6.1.1. The Set-Cookie Header . . . . . . . . . . . . . . . . 16 74 6.1.2. Storage Model . . . . . . . . . . . . . . . . . . . . 17 75 6.1.3. The Authorization Header . . . . . . . . . . . . . . . 18 76 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 77 7.1. MAC Keys Transmission . . . . . . . . . . . . . . . . . . 18 78 7.2. Confidentiality of Requests . . . . . . . . . . . . . . . 19 79 7.3. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 19 80 7.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 19 81 7.5. Entropy of MAC Keys . . . . . . . . . . . . . . . . . . . 19 82 7.6. Denial of Service / Resource Exhaustion Attacks . . . . . 20 83 7.7. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 20 84 7.8. CSRF Attacks . . . . . . . . . . . . . . . . . . . . . . . 20 85 7.9. Coverage Limitations . . . . . . . . . . . . . . . . . . . 21 86 7.10. Version Rollback Attack . . . . . . . . . . . . . . . . . 21 87 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 88 8.1. The HTTP MAC Authentication Scheme Algorithm Registry . . 22 89 8.1.1. Registration Template . . . . . . . . . . . . . . . . 22 90 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 23 91 8.2. OAuth Access Token Type Registration . . . . . . . . . . . 23 92 8.2.1. The "mac" OAuth Access Token Type . . . . . . . . . . 23 93 8.3. OAuth Parameters Registration . . . . . . . . . . . . . . 23 94 8.3.1. The "secret" OAuth Parameter . . . . . . . . . . . . . 23 95 8.3.2. The "algorithm" OAuth Parameter . . . . . . . . . . . 24 97 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 98 Appendix A. Document History . . . . . . . . . . . . . . . . . . 24 99 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 100 10.1. Normative References . . . . . . . . . . . . . . . . . . . 25 101 10.2. Informative References . . . . . . . . . . . . . . . . . . 26 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 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 defines two methods for issuing a set of MAC 125 credentials 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 148 Date: Thu, 02 Dec 2010 21:39:45 GMT 150 The client has previously obtained a set of MAC credentials for 151 accessing resources on the "http://example.com/" server. The MAC 152 credentials issued to the client include the following attributes: 154 MAC key identifier: h480djs93hd8 155 MAC key: 489dks293j39 156 MAC algorithm: hmac-sha-1 157 Issuer: login.example.net:443 159 The client constructs the authentication header by calculating the 160 current timestamp and generating a nonce. The nonce is unique to the 161 timestamp used, typically a random string: 163 Timestamp: 137131200 164 Nonce: dj83hs9s 166 The client normalizes the request and constructs the normalized 167 request string (the new line separator character is represented by 168 "\n" for display purposes only): 170 login.example.net:443\n 171 137131200\n 172 dj83hs9s\n 173 GET\n 174 /resource/1?b=1&a=2\n 175 example.com\n 176 80\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 JDS+y7WYyrHaNGq5lVgK+Y9ogKI= 185 The client includes the MAC key identifier, issuer, timestamp, nonce, 186 and request MAC with the request using the "Authorization" request 187 header field: 189 GET /resource/1 HTTP/1.1 190 Host: example.com 191 Authorization: MAC id="h480djs93hd8", 192 issuer="login.example.net:443", 193 timestamp="137131200", 194 nonce="dj83hs9s", 195 mac="JDS+y7WYyrHaNGq5lVgK+Y9ogKI=" 197 The server validates the request by calculating the request MAC again 198 based on the request received and verifies the validity and scope of 199 the MAC credentials. If valid, the server responds with the 200 requested representation. 202 1.2. Notational Conventions 204 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 205 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 206 specification are to be interpreted as described in [RFC2119]. 208 This specification uses the Augmented Backus-Naur Form (ABNF) 209 notation of [I-D.ietf-httpbis-p1-messaging]. Additionally, the 210 following rules are included from [RFC2617]: auth-param. 212 2. Issuing MAC Credentials 214 This specification defines two method for issuing MAC credentials 215 using OAuth 2.0 as described in Section 5 and using the HTTP 216 "Set-Cookie" response header field as described in Section 6. 218 This specification does not mandate servers to support any particular 219 method for issuing MAC credentials, and other methods can be defined. 220 Whenever MAC credentials are issued, the credentials MUST include the 221 following attributes: 223 MAC key identifier 224 A string identifying the MAC key used to calculate the request 225 MAC. The string is usually opaque to the client. The server 226 typically assigns a specific scope and lifetime to each set of 227 MAC credentials. The identifier MAY denote a unique value used 228 to retrieve the authorization information (e.g. from a 229 database), or self-contain the authorization information in a 230 verifiable manner (i.e. a string consisting of some data and a 231 signature). 233 MAC key 234 A shared symmetric secret used as the MAC algorithm key. 235 MAC algorithm 236 A MAC algorithm used to calculate the request MAC. Value MUST 237 be one of "hmac-sha-1", "hmac-sha-256", or a registered 238 extension algorithm name as described in Section 8.1. 239 Issuer 240 A string identifying the entity issuing the credentials. The 241 content and format of the issuer attribute depends on the 242 method used to obtain the credentials. 244 The MAC key identifier, MAC key, MAC algorithm, and issuer strings 245 MUST NOT include characters other than: 247 DIGIT / ALPHA / %x20-21 / %x23-5B / %x5D-7E 248 ; Any printable ASCII character except for <"> and <\> 250 3. Making Requests 252 To make authenticated requests, the client must be in the possession 253 of a valid set of MAC credentials accepted by the server. The client 254 constructs the request by calculating a set of attributes, and adding 255 them to the HTTP request using the "Authorization" request header 256 field as described in Section 3.1. 258 3.1. The "Authorization" Request Header 260 The "Authorization" request header field uses the framework defined 261 by [RFC2617] as follows: 263 credentials = 'MAC' [ RWS 1#param ] 265 param = id / 266 issuer / 267 timestamp / 268 nonce / 269 body-hash / 270 mac 272 id = 'id' '=' <"> plain-string <"> 273 issuer = 'issuer' '=' <"> plain-string <"> 274 timestamp = 'timestamp' '=' <"> 1*DIGIT <"> 275 nonce = 'nonce' '=' <"> plain-string <"> 276 body-hash = 'bodyhash' '=' <"> plain-string <"> 277 mac = 'mac' '=' <"> plain-string <"> 279 plain-string = 1*( DIGIT / ALPHA / %x20-21 / %x23-5B / %x5D-7E ) 281 The header attributes are set as follows: 283 id 284 REQUIRED. The MAC key identifier. 285 issuer 286 REQUIRED. The identifier of the entity who issued the MAC 287 credentials. 288 timestamp 289 REQUIRED. The current time expressed in the number of seconds 290 since January 1, 1970 00:00:00 GMT, and MUST be a positive 291 integer. The timestamp value MUST NOT include leading zeros 292 (e.g. "000137131200"). 293 nonce 294 REQUIRED. A random string, uniquely generated by the client to 295 allow the server to verify that a request has never been made 296 before and helps prevent replay attacks when requests are made 297 over an insecure channel. The nonce value MUST be unique 298 across all requests with the same timestamp and MAC key 299 identifier combination. 300 To avoid the need to retain an infinite number of nonce values 301 for future checks, servers MAY choose to restrict the time 302 period after which a request with an old timestamp is rejected. 303 Such a restriction implies a level of synchronization between 304 the client's and server's clocks. The client MAY use the 305 "Date" response header field to synchronize its clock after a 306 failed request. 308 bodyhash 309 OPTIONAL. The HTTP request payload body hash as described in 310 Section 3.2. 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 352 bodyhash 353 is the value used in the normalized request string and to set 354 the "bodyhash" attribute of the "Authorization" request header 355 field. 357 The body hash is calculated before the normalized request string is 358 constructed and the request MAC is calculated. 360 For example, the HTTP request: 362 POST /request HTTP/1.1 363 Host: example.com 364 Content-Type: application/x-www-form-urlencoded 366 hello=world%21 368 using MAC key identifier "h480djs93hd8", issuer 369 "login.example.com:443", timestamp "137131200", nonce "dj83hs9s", MAC 370 algorithm "hmac-sha-1", and MAC key "8yfrufh348h", is transmitted as 371 (line breaks are for display purposes only): 373 POST /request HTTP/1.1 374 Host: example.com 375 Content-Type: application/x-www-form-urlencoded 376 Authorization: MAC id="h480djs93hd8", 377 issuer="login.example.com:443", 378 timestamp="137131200", 379 nonce="dj83hs9s", 380 bodyhash="k9kbtCIy0CkI3/FEfpS/oIDjk6k=", 381 mac="CAGsmhyPtRFdN662zethhZLztEc=" 383 hello=world%21 385 3.3. Request MAC 387 The client uses the MAC algorithm and the MAC key to calculate the 388 request MAC. This specification defines two algorithms: "hmac-sha-1" 389 and "hmac-sha-256", and provides an extension registry for additional 390 algorithms. 392 3.3.1. Normalized Request String 394 The normalized request string is a consistent, reproducible 395 concatenation of several of the HTTP request elements into a single 396 string. By normalizing the request into a reproducible string, the 397 client and server can both calculate the request MAC over the exact 398 same value. 400 The string is constructed by concatenating together, in order, the 401 following HTTP request elements, each followed by a new line 402 character (%x0A): 404 1. The MAC credentials issuer identifier exactly as included with 405 the request using the "issuer" attribute. 406 2. The timestamp value calculated for the request. 407 3. The nonce value generated for the request. 408 4. The HTTP request method in upper case. For example: "HEAD", 409 "GET", "POST", etc. 410 5. The HTTP request-URI as defined by [RFC2616] section 5.1.2. 411 6. The hostname included in the HTTP request using the "Host" 412 request header field in lower case. 413 7. The port as included in the HTTP request using the "Host" request 414 header field. If the header field does not include a port, the 415 default value for the scheme MUST be used (e.g. 80 for HTTP and 416 443 for HTTPS). 417 8. The request payload body hash as described in Section 3.2 if one 418 was calculated and included in the request, otherwise, an empty 419 string. Note that the body hash of an empty payload body is not 420 an empty string. 422 Each element is followed by a new line character (%x0A) regardless of 423 its position in the list, or if its value is an empty string. 425 For example, the HTTP request: 427 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1 428 Host: example.com 430 Hello World! 432 using MAC key identifier "kkk9d7dh3k39sjv7", issuer 433 "login.example.com:443", timestamp "137131201", nonce "7d8f3e4a", and 434 body hash "Lve95gjOVATpfV8EL5X4nxwjKHE=" is normalized into the 435 following string (the new line separator character is represented by 436 "\n" for display purposes only): 438 kkk9d7dh3k39sjv7\n 439 login.example.com:443\n 440 137131201\n 441 7d8f3e4a\n 442 POST\n 443 /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q\n 444 example.com\n 445 80\n 446 Lve95gjOVATpfV8EL5X4nxwjKHE=\n 448 3.3.2. hmac-sha-1 450 "hmac-sha-1" uses the HMAC-SHA1 algorithm as defined in [RFC2104]: 452 mac = HMAC-SHA1 (key, text) 454 Where: 456 text 457 is set to the value of the normalized request string as 458 described in Section 3.3.1, 459 key 460 is set to the MAC key provided by the server, and 461 mac 462 is used to set the value of the "mac" attribute, after the 463 result octet string is base64-encoded per [RFC2045] section 464 6.8. 466 The SHA-1 hash algorithm as defined by [NIST FIPS-180-3] is used for 467 generating the body hash attribute described in Section 3.2 when 468 using MAC credentials with the "hmac-sha-1" MAC algorithm. 470 3.3.3. hmac-sha-256 472 "hmac-sha-256" uses the HMAC algorithm as defined in [RFC2104] 473 together with the SHA-256 hash function defined in [NIST FIPS-180-3]: 475 mac = HMAC-SHA256 (key, text) 477 Where: 479 text 480 is set to the value of the normalize request string as 481 described in Section 3.3.1, 482 key 483 is set to the MAC key provided by the server, and 484 mac 485 is used to set the value of the "mac" attribute, after the 486 result octet string is base64-encoded per [RFC2045] section 487 6.8. 489 The SHA-256 hash algorithm as defined by [NIST FIPS-180-3] is used 490 for generating the body hash attribute described in Section 3.2 when 491 using MAC credentials with the "hmac-sha-256" MAC algorithm. 493 4. Verifying Requests 495 A server receiving an authenticated request validates it by 496 performing the following REQUIRED steps: 498 1. Recalculate the request body hash (if included in the request) as 499 described in Section 3.2 and request MAC as described in 500 Section 3.3 and compare the request MAC to the value received 501 from the client via the "mac" attribute. 502 2. Ensure that the combination of nonce, timestamp, and MAC key 503 identifier received from the client has not been used before in a 504 previous request (the server MAY reject requests with stale 505 timestamps; the determination of staleness is left up to the 506 server to define). 507 3. Verify the scope and validity of the MAC credentials. 509 If the request fails verification, the server response includes the 510 "WWW-Authenticate" response header field as described in Section 4.1 511 and SHOULD include one of the following HTTP status codes: 513 401 (Unauthorized) 514 The "Authorization" request header field is not included, 515 missing a required parameter, includes an unsupported parameter 516 or parameter value, repeats the same parameter, or is otherwise 517 malformed. The MAC credentials provided are expired, revoked, 518 malformed, or invalid. The body hash or request MAC provided 519 do not match the values calculated by the server, or a body 520 hash is required but missing. 521 307 (Temporary Redirect) 522 Same as 401, with the exception that a human intervention at 523 the destination URI (identified by the "Location" response 524 header field) MAY resolve the issue (e.g. provide a login page 525 which upon a successful authentication will issue the user- 526 agent a new set of MAC credentials using the "Set-Cookie" 527 response header field as described in Section 6. 528 403 (Forbidden) 529 The "Authorization" request header field is valid, but the 530 request requires higher privileges than provided by the MAC 531 credentials. 533 4.1. The "WWW-Authenticate" Response Header Field 535 If the protected resource request does not include authentication 536 credentials, contains an invalid MAC key identifier, or is malformed, 537 the server SHOULD include the HTTP "WWW-Authenticate" response header 538 field. 540 For example: 542 HTTP/1.1 401 Unauthorized 543 WWW-Authenticate: MAC 545 The "WWW-Authenticate" request header field uses the framework 546 defined by [RFC2617] as follows: 548 challenge = "MAC" [ RWS 1#param ] 549 param = error / auth-param 550 error = "error" "=" quoted-string 552 Each attribute MUST NOT appear more than once. 554 If the protected resource request included a MAC "Authorization" 555 request header field and failed authentication, the server MAY 556 include the "error" attribute to provide the client with a human- 557 readable explanation why the access request was declined. 559 For example: 561 HTTP/1.1 401 Unauthorized 562 WWW-Authenticate: MAC error="The MAC credentials expired" 564 5. Use with OAuth 2.0 566 OAuth 2.0 ([I-D.ietf-oauth-v2]) defines a token-based authentication 567 framework in which third-party applications (clients) access 568 protected resources using access tokens. Access tokens are obtained 569 via the resource owners' authorization from an authorization server. 570 This specification defines the OAuth 2.0 MAC token type, as well as 571 type-specific token attributes. 573 This specification does not define methods for the client to 574 specifically request a MAC-type token from the authorization server. 575 Additionally, it does not include any discovery facilities for 576 identifying which HMAC algorithms are supported by a resource server, 577 or how the client may go about obtaining MAC access tokens for any 578 given protected resource. 580 The authorization server MUST require the use of a transport-layer 581 security mechanism when sending requests to the token endpoint to 582 obtain a MAC token. 584 5.1. Issuing MAC-Type Access Tokens 586 Authorization servers issuing MAC-type access tokens MUST include the 587 following parameters whenever a response includes the "access_token" 588 parameter: 590 access_token 591 REQUIRED. The MAC key identifier. 592 secret 593 REQUIRED. The MAC key. 594 algorithm 595 REQUIRED. The MAC algorithm used to calculate the request MAC. 596 Value MUST be one of "hmac-sha-1", "hmac-sha-256", or a 597 registered extension algorithm name as described in 598 Section 8.1. 600 The issuer attribute MUST be determined by the client alone, and set 601 to the host and port of the token endpoint used to make the HTTP 602 request to obtain the credentials, separated by a colon character 603 (%x3A). For example, 'auth.example.com:443'. If the client followed 604 any redirections before receiving the credentials, it MUST use the 605 host and port of the final request (the request resulting in the 606 transmission of the MAC credential). 608 6. Use with Set-Cookie 610 The HTTP "Set-Cookie " response header field defined in [RFC6265] 611 enables the server to set persistent information which the client 612 repeats back on follow-up requests. Each cookie includes a name- 613 value pair which is sent back to the server, and a set of attributes 614 which inform the client when to include the cookie in follow-up 615 requests. The attributes are never sent back to the server. 617 This specification defines the "MAC-Key" and "MAC-Algorithm" cookie 618 attributes, which are used by the server, together with the cookie 619 name which includes the MAC key identifier, to issue the client a set 620 of MAC credentials. 622 The issuer attribute MUST be determined by the client alone, and set 623 to the host and port of the token endpoint used to make the HTTP 624 request to obtain the credentials, separated by a colon character 625 (%x3A). For example, 'auth.example.com:443'. If the client followed 626 any redirections before receiving the credentials, it MUST use the 627 host and port of the final request (the request resulting in the 628 transmission of the credential). 630 The server MUST only include the "MAC-Key" attribute in response to 631 requests made using a transport-layer security mechanism such as TLS 632 1.2 as defined in [RFC5246]. Clients MUST discard any MAC 633 credentials received over an insecure channel. 635 For example, after a successful end-user authentication, the server 636 includes the following response header field (line breaks are for 637 display purposes only): 639 Set-Cookie: SID=31d4d96e407aad42; Path=/; Domain=example.com; 640 MAC-Key=8yfrufh348h; MAC-Algorithm=hmac-sha-1 642 which provides the client with the necessary MAC credentials. The 643 cookie name "SID" is used as the MAC key identifier together with the 644 other MAC-specific attributes. The user-agent uses the MAC 645 credentials for subsequent HTTP requests that match the scope of the 646 cookie, in this case for "example.com" and all subdomains. 648 6.1. User Agent Requirements 650 This section updates [RFC6265], adding the ability to issue MAC 651 credentials using the "Set-Cookie " response header field. 653 6.1.1. The Set-Cookie Header 655 Add the following two subsections to the end of Section 5.2 (The Set- 656 Cookie Header) in [RFC6265]. These sections instruct the user-agent 657 how to parse the "MAC-Key" attribute and "MAC-Algorithm" attribute, 658 respectively. 660 6.1.1.1. The MAC-Key attribute 662 If the attribute-name case-insensitively matches the string 663 "MAC-Key", the user-agent MUST append an attribute to the cookie- 664 attribute-list with an attribute name of "MAC-Key" and a attribute- 665 value equal to the attribute-value. 667 6.1.1.2. The MAC-Algorithm attribute 669 If the attribute-name case-insensitively matches the string 670 "MAC-Algorithm", and if the attribute-value is either "hmac-sha-1", 671 "hmac-sha-256", or a registered extension value, the user-agent MUST 672 append an attribute to the cookie-attribute-list with an attribute 673 name of "MAC-Algorithm" and an attribute-value equal to the 674 attribute-value. 676 6.1.2. Storage Model 678 The storage model for cookies is extended with three additional 679 fields: "mac-key", "mac-algorithm", and "issuer", all of which 680 default to the empty string. 682 The user-agent MUST perform the follow steps after Step 10 of the 683 algorithm in Section 5.3 of [RFC6265]: 685 1. If the cookie-attribute-list contains an attribute with an 686 attribute-name of "MAC-Key", set the cookie's "mac-key" field to 687 the attribute-value of the last such attribute. 688 2. If the cookie-attribute-list contains an attribute with an 689 attribute-name of "Mac-Algorithm", set the cookie's 690 "mac-alogrithm" field to the attribute-value of the last such 691 attribute. 692 3. Set the "issuer" field to the canonicalized request-host, as 693 defined in [RFC6265] followed by a colon character (%x3A), and 694 the port number of the request-uri (as defined in Section 5.1.2 695 of [RFC2616]). 697 When the user agent removes excess cookies from the cookie store 698 because there are more than a predetermined number of cookies that 699 share a domain field, or the combined length of cookies sharing a 700 single domain field or being sent in a single request have exceeded a 701 predetermined length, the user agent MUST evict cookies with an empty 702 mac-key or an empty mac-algorithm field before cookies with both a 703 non-empty mac-key and a non-empty mac-algorithm field. 705 6.1.3. The Authorization Header 707 In addition to being sent to the server in the "Cookie" request 708 header field, cookies with "MAC-Key" and "MAC-Algorithm" attributes 709 are also used to compute the "Authorization" request header field as 710 described in Section 3.1. 712 The user-agent MAY ignore cookies for the purpose of generating the 713 "Authorization" request header field. For example, the user-agent 714 might wish to ignore cookies when issuing "third-party" requests or 715 use MAC credentials obtained via other means. 717 When issuing an HTTP request, let cookie-list be the set of cookies 718 defined in Section 5.4 of [RFC6265]. Further, let mac-cookie-list be 719 those cookies in the cookie-list that contain both a non-empty 720 "mac-key" and "mac-algorithm" fields. 722 For each cookie in the mac-cookie-list: include an "Authorization" 723 request header field in the HTTP request as described in Section 3.1 724 using the cookie MAC credentials where: 726 MAC key identifier 727 is equal to the cookie's name, 728 MAC key 729 is equal to the cookie's "mac-key", 730 MAC algorithm 731 is equal to the cookie's "mac-algorithm", and 732 Issuer is equal to the cookie's "issuer". 734 7. Security Considerations 736 As stated in [RFC2617], the greatest sources of risks are usually 737 found not in the core protocol itself but in policies and procedures 738 surrounding its use. Implementers are strongly encouraged to assess 739 how this protocol addresses their security requirements. 741 7.1. MAC Keys Transmission 743 This specification describes two mechanism for obtaining or 744 transmitting MAC keys, both require the use of a transport-layer 745 security mechanism when sending MAC keys to the client. Additional 746 methods used to obtain MAC credentials must ensure that these 747 transmissions are protected using transport-layer mechanisms such as 748 TLS or SSL. 750 7.2. Confidentiality of Requests 752 While this protocol provides a mechanism for verifying the integrity 753 of requests, it provides no guarantee of request confidentiality. 754 Unless further precautions are taken, eavesdroppers will have full 755 access to request content. Servers should carefully consider the 756 kinds of data likely to be sent as part of such requests, and should 757 employ transport-layer security mechanisms to protect sensitive 758 resources. 760 7.3. Spoofing by Counterfeit Servers 762 This protocol makes no attempt to verify the authenticity of the 763 server. A hostile party could take advantage of this by intercepting 764 the client's requests and returning misleading or otherwise incorrect 765 responses. Service providers should consider such attacks when 766 developing services using this protocol, and should require 767 transport-layer security for any requests where the authenticity of 768 the resource server or of request responses is an issue. 770 7.4. Plaintext Storage of Credentials 772 The MAC key functions the same way passwords do in traditional 773 authentication systems. In order to compute the request MAC, the 774 server must have access to the MAC key in plaintext form. This is in 775 contrast, for example, to modern operating systems, which store only 776 a one-way hash of user credentials. 778 If an attacker were to gain access to these MAC keys - or worse, to 779 the server's database of all such MAC keys - he or she would be able 780 to perform any action on behalf of any resource owner. Accordingly, 781 it is critical that servers protect these MAC keys from unauthorized 782 access. 784 7.5. Entropy of MAC Keys 786 Unless a transport-layer security protocol is used, eavesdroppers 787 will have full access to authenticated requests and request MAC 788 values, and will thus be able to mount offline brute-force attacks to 789 recover the MAC key used. Servers should be careful to assign MAC 790 keys which are long enough, and random enough, to resist such attacks 791 for at least the length of time that the MAC credentials are valid. 793 For example, if the MAC credentials are valid for two weeks, servers 794 should ensure that it is not possible to mount a brute force attack 795 that recovers the MAC key in less than two weeks. Of course, servers 796 are urged to err on the side of caution, and use the longest MAC key 797 reasonable. 799 It is equally important that the pseudo-random number generator 800 (PRNG) used to generate these MAC keys be of sufficiently high 801 quality. Many PRNG implementations generate number sequences that 802 may appear to be random, but which nevertheless exhibit patterns or 803 other weaknesses which make cryptanalysis or brute force attacks 804 easier. Implementers should be careful to use cryptographically 805 secure PRNGs to avoid these problems. 807 7.6. Denial of Service / Resource Exhaustion Attacks 809 This specification includes a number of features which may make 810 resource exhaustion attacks against servers possible. For example, 811 this protocol requires servers to track used nonces. If an attacker 812 is able to use many nonces quickly, the resources required to track 813 them may exhaust available capacity. And again, this protocol can 814 require servers to perform potentially expensive computations in 815 order to verify the request MAC on incoming requests. An attacker 816 may exploit this to perform a denial of service attack by sending a 817 large number of invalid requests to the server. 819 Resource Exhaustion attacks are by no means specific to this 820 specification. However, implementers should be careful to consider 821 the additional avenues of attack that this protocol exposes, and 822 design their implementations accordingly. For example, entropy 823 starvation typically results in either a complete denial of service 824 while the system waits for new entropy or else in weak (easily 825 guessable) MAC keys. When implementing this protocol, servers should 826 consider which of these presents a more serious risk for their 827 application and design accordingly. 829 7.7. Timing Attacks 831 This specification makes use of HMACs, for which a signature 832 verification involves comparing the received MAC string to the 833 expected one. If the string comparison operator operates in 834 observably different times depending on inputs, e.g. because it 835 compares the strings character by character and returns a negative 836 result as soon as two characters fail to match, then it may be 837 possible to use this timing information to determine the expected 838 MAC, character by character. 840 Service implementors are encouraged to use fixed-time string 841 comparators for MAC verification. 843 7.8. CSRF Attacks 845 A Cross-Site Request Forgery attack occurs when a site, evil.com, 846 initiates within the victim's browser the loading of a URL from or 847 the posting of a form to a web site where a side-effect will occur, 848 e.g. transfer of money, change of status message, etc. To prevent 849 this kind of attack, web sites may use various techniques to 850 determine that the originator of the request is indeed the site 851 itself, rather than a third party. The classic approach is to 852 include, in the set of URL parameters or form content, a nonce 853 generated by the server and tied to the user's session, which 854 indicates that only the server could have triggered the action. 856 Recently, the Origin HTTP header has been proposed and deployed in 857 some browsers. This header indicates the scheme, host, and port of 858 the originator of a request. Some web applications may use this 859 Origin header as a defense against CSRF. 861 To keep this specification simple, HTTP headers are not part of the 862 string to be MAC'ed. As a result, MAC authentication cannot defend 863 against header spoofing, and a web site that uses the Host header to 864 defend against CSRF attacks cannot use MAC authentication to defend 865 against active network attackers. Sites that want the full 866 protection of MAC Authentication should use traditional, cookie-tied 867 CSRF defenses. 869 7.9. Coverage Limitations 871 The normalized request string has been designed to support the 872 authentication methods defined in this specification. Those 873 designing additional methods, should evaluated the compatibility of 874 the normalized request string with their security requirements. 875 Since the normalized request string does not cover the entire HTTP 876 request, servers should employ additional mechanisms to protect such 877 elements. 879 The request MAC does not cover entity-header fields which can often 880 affect how the request body is interpreted by the server (i.e. 881 Content-Type). If the server behavior is influenced by the presence 882 or value of such header fields, an attacker can manipulate the 883 request header without being detected. This will alter the request 884 even when using the body hash attribute. 886 7.10. Version Rollback Attack 888 [[ TODO ]] 890 8. IANA Considerations 891 8.1. The HTTP MAC Authentication Scheme Algorithm Registry 893 This specification establishes the HTTP MAC authentication scheme 894 algorithm registry. 896 Additional MAC algorithms are registered on the advice of one or more 897 Designated Experts (appointed by the IESG or their delegate), with a 898 Specification Required (using terminology from [RFC5226]). However, 899 to allow for the allocation of values prior to publication, the 900 Designated Expert(s) may approve registration once they are satisfied 901 that such a specification will be published. 903 Registration requests should be sent to the [TBD]@ietf.org mailing 904 list for review and comment, with an appropriate subject (e.g., 905 "Request for MAC Algorithm: example"). [[ Note to RFC-EDITOR: The 906 name of the mailing list should be determined in consultation with 907 the IESG and IANA. Suggested name: http-mac-ext-review. ]] 909 Within at most 14 days of the request, the Designated Expert(s) will 910 either approve or deny the registration request, communicating this 911 decision to the review list and IANA. Denials should include an 912 explanation and, if applicable, suggestions as to how to make the 913 request successful. 915 Decisions (or lack thereof) made by the Designated Expert can be 916 first appealed to Application Area Directors (contactable using 917 app-ads@tools.ietf.org email address or directly by looking up their 918 email addresses on http://www.iesg.org/ website) and, if the 919 appellant is not satisfied with the response, to the full IESG (using 920 the iesg@iesg.org mailing list). 922 IANA should only accept registry updates from the Designated 923 Expert(s), and should direct all requests for registration to the 924 review mailing list. 926 8.1.1. Registration Template 928 Algorithm name: 929 The name requested (e.g., "example"). 930 Body hash algorithm: 931 The corresponding algorithm used to calculate the payload body 932 hash. 933 Change controller: 934 For standards-track RFCs, state "IETF". For others, give the name 935 of the responsible party. Other details (e.g., postal address, 936 e-mail address, home page URI) may also be included. 938 Specification document(s): 939 Reference to document that specifies the algorithm, preferably 940 including a URI that can be used to retrieve a copy of the 941 document. An indication of the relevant sections may also be 942 included, but is not required. 944 8.1.2. Initial Registry Contents 946 The HTTP MAC authentication scheme algorithm registry's initial 947 contents are: 949 o Algorithm name: hmac-sha-1 950 o Body hash algorithm: sha-1 951 o Change controller: IETF 952 o Specification document(s): [[ this document ]] 954 o Algorithm name: hmac-sha-256 955 o Body hash algorithm: sha-256 956 o Change controller: IETF 957 o Specification document(s): [[ this document ]] 959 8.2. OAuth Access Token Type Registration 961 This specification registers the following access token type in the 962 OAuth Access Token Type Registry. 964 8.2.1. The "mac" OAuth Access Token Type 966 Type name: 967 mac 968 Additional Token Endpoint Response Parameters: 969 secret, algorithm 970 HTTP Authentication Scheme(s): 971 MAC 972 Change controller: 973 IETF 974 Specification document(s): 975 [[ this document ]] 977 8.3. OAuth Parameters Registration 979 This specification registers the following parameters in the OAuth 980 Parameters Registry established by [I-D.ietf-oauth-v2]. 982 8.3.1. The "secret" OAuth Parameter 983 Parameter name: secret 984 Parameter usage location: authorization response, token response 985 Change controller: IETF 986 Specification document(s): [[ this document ]] 987 Related information: None 989 8.3.2. The "algorithm" OAuth Parameter 991 Parameter name: algorithm 992 Parameter usage location: authorization response, token response 993 Change controller: IETF 994 Specification document(s): [[ this document ]] 995 Related information: None 997 9. Acknowledgments 999 The authors would like to thank Rasmus Lerdorf, James Manger, Scott 1000 Renfro, Toby White, Peter Wolanin, and Skylar Woodward for their 1001 suggestions and feedback. 1003 Appendix A. Document History 1005 [[ To be removed by the RFC editor before publication as an RFC. ]] 1007 -03 1009 o Changed access token terminology to MAC key identifier and access 1010 token secret to MAC key. Changed corresponding parameter name 1011 from 'token' to 'id'. 1012 o Changed signature terminology to request MAC. Changed 1013 corresponding parameter name from 'signature' to 'mac'. 1014 o Added new 'Set-Cookie' header extension. 1015 o Added new 'issuer' attribute. 1016 o Defined algorithm registry. 1017 o Dropped request URI query normalization. Changed order of string 1018 components. 1020 -02 1022 o Added body-hash support. 1023 o Updated OAuth 2.0 reference and added token type registration 1024 template. 1025 o Removed error codes and error URI. 1027 -01 1028 o Changed parameters sorting to come after name=value string 1029 construction. 1030 o Added new line at the end of the normalized request string. 1031 o Moved OAuth2 references to separate section. 1032 o Added 'WWW-Authenticate' header definition. 1033 o Fixed example header use of single quote. 1034 o Restricted strings to ASCII subset (printable, no double-quotes or 1035 back-slash). 1037 -00 1039 o Initial draft. 1041 10. References 1043 10.1. Normative References 1045 [I-D.ietf-httpbis-p1-messaging] 1046 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 1047 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 1048 "HTTP/1.1, part 1: URIs, Connections, and Message 1049 Parsing", draft-ietf-httpbis-p1-messaging-13 (work in 1050 progress), March 2011. 1052 [I-D.ietf-oauth-v2] 1053 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 1054 2.0 Authorization Protocol", draft-ietf-oauth-v2-15 (work 1055 in progress), April 2011. 1057 [NIST FIPS-180-3] 1058 National Institute of Standards and Technology, "Secure 1059 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 1061 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1062 Extensions (MIME) Part One: Format of Internet Message 1063 Bodies", RFC 2045, November 1996. 1065 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1066 Hashing for Message Authentication", RFC 2104, 1067 February 1997. 1069 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1070 Requirement Levels", BCP 14, RFC 2119, March 1997. 1072 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1073 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1074 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1076 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1077 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1078 Authentication: Basic and Digest Access Authentication", 1079 RFC 2617, June 1999. 1081 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1082 Resource Identifier (URI): Generic Syntax", STD 66, 1083 RFC 3986, January 2005. 1085 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1086 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1087 May 2008. 1089 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1090 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1092 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1093 April 2011. 1095 [W3C.REC-html401-19991224] 1096 Hors, A., Jacobs, I., and D. Raggett, "HTML 4.01 1097 Specification", World Wide Web Consortium 1098 Recommendation REC-html401-19991224, December 1999, 1099 . 1101 10.2. Informative References 1103 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 1104 April 2010. 1106 URIs 1108 [1] 1110 Authors' Addresses 1112 Eran Hammer-Lahav 1113 Yahoo! 1115 Email: eran@hueniverse.com 1116 URI: http://hueniverse.com 1117 Adam Barth 1118 Google 1120 Email: ietf@adambarth.com 1121 URI: http://www.adambarth.com 1123 Ben Adida 1124 Mozilla 1126 Email: ben@adida.net 1127 URI: http://ben.adida.net