idnits 2.17.1 draft-ietf-oauth-v2-http-mac-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (February 8, 2012) is 4453 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 818, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 826, but no explicit reference was found in the text == Unused Reference: 'RFC6265' is defined on line 829, but no explicit reference was found in the text == Unused Reference: 'RFC5849' is defined on line 840, 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 (~~), 8 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Hammer-Lahav, Ed. 3 Internet-Draft February 8, 2012 4 Intended status: Standards Track 5 Expires: August 11, 2012 7 HTTP Authentication: MAC Access Authentication 8 draft-ietf-oauth-v2-http-mac-01 10 Abstract 12 This document specifies the HTTP MAC access authentication scheme, an 13 HTTP authentication method using a message authentication code (MAC) 14 algorithm to provide cryptographic verification of portions of HTTP 15 requests. The document also defines an OAuth 2.0 binding for use as 16 an access-token type. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on August 11, 2012. 35 Copyright Notice 37 Copyright (c) 2012 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 5 55 2. Issuing MAC Credentials . . . . . . . . . . . . . . . . . . . 5 56 3. Making Requests . . . . . . . . . . . . . . . . . . . . . . . 6 57 3.1. The "Authorization" Request Header . . . . . . . . . . . . 6 58 3.2. Request MAC . . . . . . . . . . . . . . . . . . . . . . . 7 59 3.2.1. Normalized Request String . . . . . . . . . . . . . . 8 60 3.2.2. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . . 9 61 3.2.3. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . . 9 62 4. Verifying Requests . . . . . . . . . . . . . . . . . . . . . . 10 63 4.1. Timestamp Verification . . . . . . . . . . . . . . . . . . 10 64 4.2. The "WWW-Authenticate" Response Header Field . . . . . . . 11 65 5. Use with OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . 12 66 5.1. Issuing MAC-Type Access Tokens . . . . . . . . . . . . . . 12 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 68 6.1. MAC Keys Transmission . . . . . . . . . . . . . . . . . . 13 69 6.2. Confidentiality of Requests . . . . . . . . . . . . . . . 13 70 6.3. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 13 71 6.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 13 72 6.5. Entropy of MAC Keys . . . . . . . . . . . . . . . . . . . 14 73 6.6. Denial of Service / Resource Exhaustion Attacks . . . . . 14 74 6.7. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 15 75 6.8. CSRF Attacks . . . . . . . . . . . . . . . . . . . . . . . 15 76 6.9. Coverage Limitations . . . . . . . . . . . . . . . . . . . 15 77 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 78 7.1. The HTTP MAC Authentication Scheme Algorithm Registry . . 16 79 7.1.1. Registration Template . . . . . . . . . . . . . . . . 17 80 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17 81 7.2. OAuth Access Token Type Registration . . . . . . . . . . . 17 82 7.2.1. The "mac" OAuth Access Token Type . . . . . . . . . . 17 83 7.3. OAuth Parameters Registration . . . . . . . . . . . . . . 18 84 7.3.1. The "mac_key" OAuth Parameter . . . . . . . . . . . . 18 85 7.3.2. The "mac_algorithm" OAuth Parameter . . . . . . . . . 18 86 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 87 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 88 9.1. Normative References . . . . . . . . . . . . . . . . . . . 18 89 9.2. Informative References . . . . . . . . . . . . . . . . . . 19 90 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 92 1. Introduction 94 This specification defines the HTTP MAC access authentication scheme, 95 providing a method for making authenticated HTTP requests with 96 partial cryptographic verification of the request, covering the HTTP 97 method, request URI, and host. 99 Similar to the HTTP Basic access authentication scheme [RFC2617], the 100 MAC scheme utilizes a set of client credentials which include an 101 identifier and key. However, in contrast with the Basic scheme, the 102 key is never included in authenticated requests but is used to 103 calculate the request MAC value which is included instead. 105 The MAC scheme requires the establishment of a shared symmetric key 106 between the client and the server. This specification offers one 107 such method for issuing a set of MAC credentials to the client using 108 OAuth 2.0 in the form of a MAC-type access token. 110 The primary design goal of this mechanism is to simplify and improve 111 HTTP authentication for services that are unwilling or unable to 112 employ TLS for every request. In particular, this mechanism leverage 113 an initial TLS setup phase to establish a shared secret between the 114 client and the server. The shared secret is then used over an 115 insecure channel to provide protection against a passive network 116 attacker. 118 In particular, when a server uses this mechanism, a passive network 119 attacker will be unable to "steal" the user's session token, as is 120 possible today with cookies and other bearer tokens. In addition, 121 this mechanism helps secure the session token against leakage when 122 sent over a secure channel to the wrong server. For example, when 123 the client uses some form of dynamic configuration to determine where 124 to send an authenticated request, or when the client fails to 125 properly validate the server's identity as part of its TLS handshake. 127 Unlike the HTTP Digest authentication scheme, this mechanism does not 128 require interacting with the server to prevent replay attacks. 129 Instead, the client provides both a nonce and a timestamp, which the 130 server can use to prevent replay attacks using a bounded amount of 131 storage. Also unlike Digest, this mechanism is not intended to 132 protect the user's password itself because the client and server both 133 have access to the key material in the clear. Instead, servers 134 should issue a short-lived derivative credential for this mechanism 135 during the initial TLS setup phase. 137 1.1. Example 139 The client attempts to access a protected resource without 140 authentication, making the following HTTP request to the resource 141 server: 143 GET /resource/1?b=1&a=2 HTTP/1.1 144 Host: example.com 146 The resource server returns the following authentication challenge: 148 HTTP/1.1 401 Unauthorized 149 WWW-Authenticate: MAC 151 The client has previously obtained a set of MAC credentials for 152 accessing resources on the "http://example.com/" server. The MAC 153 credentials issued to the client include the following attributes: 155 MAC key identifier: h480djs93hd8 156 MAC key: 489dks293j39 157 MAC algorithm: hmac-sha-1 159 The client constructs the authentication header by calculating a 160 timestamp (e.g. the number of seconds since January 1, 1970 00:00:00 161 GMT) and generating a random string used as a nonce: 163 Timestamp: 1336363200 164 Nonce: 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 trailing new line separator signify that no extension value is 169 included with the request, explained below): 171 1336363200\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 bhCQXTVyfj5cmA9uKkPFx1zeOXM= 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 ts="1336363200", 192 nonce="dj83hs9s", 193 mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM=" 195 The server validates the request by calculating the request MAC again 196 based on the request received and verifies the validity and scope of 197 the MAC credentials. If valid, the server responds with the 198 requested resource representation. 200 1.2. Notational Conventions 202 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 203 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 204 specification are to be interpreted as described in [RFC2119]. 206 This specification uses the Augmented Backus-Naur Form (ABNF) 207 notation of [I-D.ietf-httpbis-p1-messaging]. Additionally, the 208 following rules are included from [RFC2617]: auth-param. 210 2. Issuing MAC Credentials 212 This specification provides one method for issuing MAC credentials 213 using OAuth 2.0 as described in Section 5. This specification does 214 not mandate servers to support any particular method for issuing MAC 215 credentials, and other methods MAY be defined and used. Whenever MAC 216 credentials are issued, the credentials MUST include the following 217 attributes: 219 MAC key identifier 220 A string identifying the MAC key used to calculate the request 221 MAC. The string is usually opaque to the client. The server 222 typically assigns a specific scope and lifetime to each set of 223 MAC credentials. The identifier MAY denote a unique value used 224 to retrieve the authorization information (e.g. from a 225 database), or self-contain the authorization information in a 226 verifiable manner (i.e. a string consisting of some data and a 227 signature). 228 MAC key 229 A shared symmetric secret used as the MAC algorithm key. The 230 server MUST NOT reissue a previously issued MAC key and MAC key 231 identifier combination. 232 MAC algorithm 233 A MAC algorithm used to calculate the request MAC. Value MUST 234 be one of "hmac-sha-1", "hmac-sha-256", or a registered 235 extension algorithm name as described in Section 7.1. 236 Algorithm names are case-sensitive. If the MAC algorithm is 237 not understood by the client, the client MUST NOT use the MAC 238 credentials and continue as if no MAC credentials were issued. 240 The MAC key identifier, MAC key, MAC algorithm strings MUST NOT 241 include characters other than: 243 %x20-21 / %x23-5B / %x5D-7E 244 ; Any printable ASCII character except for <"> and <\> 246 3. Making Requests 248 To make authenticated requests, the client must be in the possession 249 of a valid set of MAC credentials accepted by the server. The client 250 constructs the request by calculating a set of attributes, and adding 251 them to the HTTP request using the "Authorization" request header 252 field as described in Section 3.1. 254 3.1. The "Authorization" Request Header 256 The "Authorization" request header field uses the framework defined 257 by [RFC2617] as follows: 259 credentials = "MAC" 1*SP #params 261 params = id / ts / nonce / ext / mac 263 id = "id" "=" string-value 264 ts = "ts" "=" ( <"> timestamp <"> ) / timestamp 265 nonce = "nonce" "=" string-value 266 ext = "ext" "=" string-value 267 mac = "mac" "=" string-value 269 timestamp = 1*DIGIT 270 string-value = ( <"> plain-string <"> ) / plain-string 271 plain-string = 1*( %x20-21 / %x23-5B / %x5D-7E ) 273 The header attributes are set as follows: 275 id 276 REQUIRED. The MAC key identifier. 277 ts 278 REQUIRED. The request timestamp. The value MUST be a positive 279 integer set by the client when making each request to the 280 number of seconds elapsed from a fixed point in time (e.g. 281 January 1, 1970 00:00:00 GMT). The value MUST NOT include 282 leading zeros (e.g. "000273154346"). 283 nonce 284 REQUIRED. A unique string generated by the client. The value 285 MUST be unique across all requests with the same timestamp and 286 MAC key identifier combination. 287 ext 288 OPTIONAL. A string used to include additional information 289 which is covered by the request MAC. The content and format of 290 the string is beyond the scope of this specification. 291 mac 292 REQUIRED. The HTTP request MAC as described in Section 3.2. 294 Attributes MUST NOT appear more than once. Attribute values are 295 limited to a subset of ASCII, which does not require escaping, as 296 defined by the plain-string ABNF. 298 3.2. Request MAC 300 The client uses the MAC algorithm and the MAC key to calculate the 301 request MAC. This specification defines two algorithms: "hmac-sha-1" 302 and "hmac-sha-256", and provides an extension registry for additional 303 algorithms. 305 3.2.1. Normalized Request String 307 The normalized request string is a consistent, reproducible 308 concatenation of several of the HTTP request elements into a single 309 string. By normalizing the request into a reproducible string, the 310 client and server can both calculate the request MAC over the exact 311 same value. 313 The string is constructed by concatenating together, in order, the 314 following HTTP request elements, each followed by a new line 315 character (%x0A): 317 1. The timestamp value calculated for the request. 318 2. The nonce value generated for the request. 319 3. The HTTP request method in upper case. For example: "HEAD", 320 "GET", "POST", etc. 321 4. The HTTP request-URI as defined by [RFC2616] section 5.1.2. 322 5. The hostname included in the HTTP request using the "Host" 323 request header field in lower case. 324 6. The port as included in the HTTP request using the "Host" request 325 header field. If the header field does not include a port, the 326 default value for the scheme MUST be used (e.g. 80 for HTTP and 327 443 for HTTPS). 328 7. The value of the "ext" "Authorization" request header field 329 attribute if one was included in the request, otherwise, an empty 330 string. 332 Each element is followed by a new line character (%x0A) including the 333 last element and even when an element value is an empty string. 335 For example, the HTTP request: 337 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1 338 Host: example.com 340 Hello World! 342 using timestamp "264095:7d8f3e4a", nonce "7d8f3e4a", and extension 343 string "a,b,c" is normalized into the following string (the new line 344 separator character is represented by "\n" for display purposes 345 only): 347 264095\n 348 7d8f3e4a\n 349 POST\n 350 /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q\n 351 example.com\n 352 80\n 353 a,b,c\n 355 3.2.2. hmac-sha-1 357 "hmac-sha-1" uses the HMAC-SHA1 algorithm as defined in [RFC2104]: 359 mac = HMAC-SHA1 (key, text) 361 Where: 363 text 364 is set to the value of the normalized request string as 365 described in Section 3.2.1, 366 key 367 is set to the MAC key provided by the server, and 368 mac 369 is used to set the value of the "mac" attribute, after the 370 result octet string is base64-encoded per [RFC2045] section 371 6.8. 373 3.2.3. hmac-sha-256 375 "hmac-sha-256" uses the HMAC algorithm as defined in [RFC2104] 376 together with the SHA-256 hash function defined in [NIST FIPS-180-3]: 378 mac = HMAC-SHA256 (key, text) 380 Where: 382 text 383 is set to the value of the normalize request string as 384 described in Section 3.2.1, 385 key 386 is set to the MAC key provided by the server, and 388 mac 389 is used to set the value of the "mac" attribute, after the 390 result octet string is base64-encoded per [RFC2045] section 391 6.8. 393 4. Verifying Requests 395 A server receiving an authenticated request validates it by 396 performing the following REQUIRED steps: 398 1. Recalculate the request MAC as described in Section 3.2 and 399 compare the request MAC to the value received from the client via 400 the "mac" attribute. 401 2. Ensure that the combination of timestamp, nonce, and MAC key 402 identifier received from the client has not been received before 403 in a previous request. The server MAY reject requests with stale 404 timestamps as described in Section 4.1. 405 3. Verify the scope and validity of the MAC credentials. 407 If the request fails verification, the server SHOULD respond using 408 the 401 (Unauthorized) HTTP status code and include the 409 "WWW-Authenticate" response header field as described in Section 4.2. 411 4.1. Timestamp Verification 413 The timestamp, nonce, and MAC key identifier combination provide a 414 unique identifier which enables the server to prevent replay attacks. 415 Without replay protection, an attacker can use a compromised (but 416 otherwise valid and authenticated) request more than once, gaining 417 long term access to a protected resource. 419 Including a timestamp with the nonce removes the need to retain an 420 infinite number of nonce values for future checks, by enabling the 421 server to restrict the time period after which a request with an old 422 timestamp is rejected. If such a restriction is enforced, the server 423 MUST: 425 o At the time the first request is received from the client for each 426 MAC key identifier, calculate the difference (in seconds) between 427 the request timestamp and the server's clock. The difference - 428 the request time delta - MUST be kept as long as the MAC key 429 credentials are valid. 430 o For each subsequent client request, apply the request time delta 431 to request timestamp to calculate the adjusted request time - the 432 time when the request MAC has been generated by the client, 433 adjusted to the server's clock. 435 o Verify that the adjusted request time is within the allowed time 436 period defined by the server. The server SHOULD allow for a 437 sufficiently large window to accommodate network delays (between 438 the time the request has been generated by the client to the time 439 it is received by the server and processed). 441 4.2. The "WWW-Authenticate" Response Header Field 443 If the protected resource request does not include authentication 444 credentials, contains an invalid MAC key identifier, or is malformed, 445 the server SHOULD include the HTTP "WWW-Authenticate" response header 446 field. 448 For example: 450 HTTP/1.1 401 Unauthorized 451 WWW-Authenticate: MAC 453 The "WWW-Authenticate" request header field uses the framework 454 defined by [RFC2617] as follows: 456 challenge = "MAC" [ 1*SP #param ] 457 param = error / auth-param 458 error = "error" "=" ( token / quoted-string) 460 Each attribute MUST NOT appear more than once. 462 If the protected resource request included a MAC "Authorization" 463 request header field and failed authentication, the server MAY 464 include the "error" attribute to provide the client with a human- 465 readable explanation why the access request was declined to assist 466 the client developer in identifying the problem. 468 For example: 470 HTTP/1.1 401 Unauthorized 471 WWW-Authenticate: MAC error="The MAC credentials expired" 473 5. Use with OAuth 2.0 475 OAuth 2.0 ([I-D.ietf-oauth-v2]) defines an extensible token-based 476 authentication framework. The MAC authentication scheme can be used 477 to make OAuth-based requests by issuing MAC-type access tokens. 479 This specification does not define methods for the client to 480 specifically request a MAC-type token from the authorization server. 481 Additionally, it does not include any discovery facilities for 482 identifying which HMAC algorithms are supported by a resource server, 483 or how the client may go about obtaining MAC access tokens for any 484 given protected resource. 486 5.1. Issuing MAC-Type Access Tokens 488 Authorization servers issuing MAC-type access tokens MUST include the 489 following parameters whenever a response includes the "access_token" 490 parameter: 492 access_token 493 REQUIRED. The MAC key identifier. 494 mac_key 495 REQUIRED. The MAC key. 496 mac_algorithm 497 REQUIRED. The MAC algorithm used to calculate the request MAC. 498 Value MUST be one of "hmac-sha-1", "hmac-sha-256", or a 499 registered extension algorithm name as described in 500 Section 7.1. 502 For example: 504 HTTP/1.1 200 OK 505 Content-Type: application/json 506 Cache-Control: no-store 508 { 509 "access_token":"SlAV32hkKG", 510 "token_type":"mac", 511 "expires_in":3600, 512 "refresh_token":"8xLOxBtZp8", 513 "mac_key":"adijq39jdlaska9asud", 514 "mac_algorithm":"hmac-sha-256" 515 } 517 6. Security Considerations 519 As stated in [RFC2617], the greatest sources of risks are usually 520 found not in the core protocol itself but in policies and procedures 521 surrounding its use. Implementers are strongly encouraged to assess 522 how this protocol addresses their security requirements. 524 6.1. MAC Keys Transmission 526 This specification describes two mechanism for obtaining or 527 transmitting MAC keys, both require the use of a transport-layer 528 security mechanism when sending MAC keys to the client. Additional 529 methods used to obtain MAC credentials must ensure that these 530 transmissions are protected using transport-layer mechanisms such as 531 TLS or SSL. 533 6.2. Confidentiality of Requests 535 While this protocol provides a mechanism for verifying the integrity 536 of requests, it provides no guarantee of request confidentiality. 537 Unless further precautions are taken, eavesdroppers will have full 538 access to request content. Servers should carefully consider the 539 kinds of data likely to be sent as part of such requests, and should 540 employ transport-layer security mechanisms to protect sensitive 541 resources. 543 6.3. Spoofing by Counterfeit Servers 545 This protocol makes no attempt to verify the authenticity of the 546 server. A hostile party could take advantage of this by intercepting 547 the client's requests and returning misleading or otherwise incorrect 548 responses. Service providers should consider such attacks when 549 developing services using this protocol, and should require 550 transport-layer security for any requests where the authenticity of 551 the resource server or of request responses is an issue. 553 6.4. Plaintext Storage of Credentials 555 The MAC key functions the same way passwords do in traditional 556 authentication systems. In order to compute the request MAC, the 557 server must have access to the MAC key in plaintext form. This is in 558 contrast, for example, to modern operating systems, which store only 559 a one-way hash of user credentials. 561 If an attacker were to gain access to these MAC keys - or worse, to 562 the server's database of all such MAC keys - he or she would be able 563 to perform any action on behalf of any resource owner. Accordingly, 564 it is critical that servers protect these MAC keys from unauthorized 565 access. 567 6.5. Entropy of MAC Keys 569 Unless a transport-layer security protocol is used, eavesdroppers 570 will have full access to authenticated requests and request MAC 571 values, and will thus be able to mount offline brute-force attacks to 572 recover the MAC key used. Servers should be careful to assign MAC 573 keys which are long enough, and random enough, to resist such attacks 574 for at least the length of time that the MAC credentials are valid. 576 For example, if the MAC credentials are valid for two weeks, servers 577 should ensure that it is not possible to mount a brute force attack 578 that recovers the MAC key in less than two weeks. Of course, servers 579 are urged to err on the side of caution, and use the longest MAC key 580 reasonable. 582 It is equally important that the pseudo-random number generator 583 (PRNG) used to generate these MAC keys be of sufficiently high 584 quality. Many PRNG implementations generate number sequences that 585 may appear to be random, but which nevertheless exhibit patterns or 586 other weaknesses which make cryptanalysis or brute force attacks 587 easier. Implementers should be careful to use cryptographically 588 secure PRNGs to avoid these problems. 590 6.6. Denial of Service / Resource Exhaustion Attacks 592 This specification includes a number of features which may make 593 resource exhaustion attacks against servers possible. For example, 594 this protocol requires servers to track used nonces. If an attacker 595 is able to use many nonces quickly, the resources required to track 596 them may exhaust available capacity. And again, this protocol can 597 require servers to perform potentially expensive computations in 598 order to verify the request MAC on incoming requests. An attacker 599 may exploit this to perform a denial of service attack by sending a 600 large number of invalid requests to the server. 602 Resource Exhaustion attacks are by no means specific to this 603 specification. However, implementers should be careful to consider 604 the additional avenues of attack that this protocol exposes, and 605 design their implementations accordingly. For example, entropy 606 starvation typically results in either a complete denial of service 607 while the system waits for new entropy or else in weak (easily 608 guessable) MAC keys. When implementing this protocol, servers should 609 consider which of these presents a more serious risk for their 610 application and design accordingly. 612 6.7. Timing Attacks 614 This specification makes use of HMACs, for which a signature 615 verification involves comparing the received MAC string to the 616 expected one. If the string comparison operator operates in 617 observably different times depending on inputs, e.g. because it 618 compares the strings character by character and returns a negative 619 result as soon as two characters fail to match, then it may be 620 possible to use this timing information to determine the expected 621 MAC, character by character. 623 Service implementers are encouraged to use fixed-time string 624 comparators for MAC verification. 626 6.8. CSRF Attacks 628 A Cross-Site Request Forgery attack occurs when a site, evil.com, 629 initiates within the victim's browser the loading of a URL from or 630 the posting of a form to a web site where a side-effect will occur, 631 e.g. transfer of money, change of status message, etc. To prevent 632 this kind of attack, web sites may use various techniques to 633 determine that the originator of the request is indeed the site 634 itself, rather than a third party. The classic approach is to 635 include, in the set of URL parameters or form content, a nonce 636 generated by the server and tied to the user's session, which 637 indicates that only the server could have triggered the action. 639 Recently, the Origin HTTP header has been proposed and deployed in 640 some browsers. This header indicates the scheme, host, and port of 641 the originator of a request. Some web applications may use this 642 Origin header as a defense against CSRF. 644 To keep this specification simple, HTTP headers are not part of the 645 string to be MAC'ed. As a result, MAC authentication cannot defend 646 against header spoofing, and a web site that uses the Host header to 647 defend against CSRF attacks cannot use MAC authentication to defend 648 against active network attackers. Sites that want the full 649 protection of MAC Authentication should use traditional, cookie-tied 650 CSRF defenses. 652 6.9. Coverage Limitations 654 The normalized request string has been designed to support the 655 authentication methods defined in this specification. Those 656 designing additional methods, should evaluated the compatibility of 657 the normalized request string with their security requirements. 658 Since the normalized request string does not cover the entire HTTP 659 request, servers should employ additional mechanisms to protect such 660 elements. 662 The request MAC does not cover entity-header fields which can often 663 affect how the request body is interpreted by the server (i.e. 664 Content-Type). If the server behavior is influenced by the presence 665 or value of such header fields, an attacker can manipulate the 666 request header without being detected. 668 7. IANA Considerations 670 7.1. The HTTP MAC Authentication Scheme Algorithm Registry 672 This specification establishes the HTTP MAC authentication scheme 673 algorithm registry. 675 Additional MAC algorithms are registered on the advice of one or more 676 Designated Experts (appointed by the IESG or their delegate), with a 677 Specification Required (using terminology from [RFC5226]). However, 678 to allow for the allocation of values prior to publication, the 679 Designated Expert(s) may approve registration once they are satisfied 680 that such a specification will be published. 682 Registration requests should be sent to the [TBD]@ietf.org mailing 683 list for review and comment, with an appropriate subject (e.g., 684 "Request for MAC Algorithm: example"). [[ Note to RFC-EDITOR: The 685 name of the mailing list should be determined in consultation with 686 the IESG and IANA. Suggested name: http-mac-ext-review. ]] 688 Within at most 14 days of the request, the Designated Expert(s) will 689 either approve or deny the registration request, communicating this 690 decision to the review list and IANA. Denials should include an 691 explanation and, if applicable, suggestions as to how to make the 692 request successful. 694 Decisions (or lack thereof) made by the Designated Expert can be 695 first appealed to Application Area Directors (contactable using 696 app-ads@tools.ietf.org email address or directly by looking up their 697 email addresses on http://www.iesg.org/ website) and, if the 698 appellant is not satisfied with the response, to the full IESG (using 699 the iesg@iesg.org mailing list). 701 IANA should only accept registry updates from the Designated 702 Expert(s), and should direct all requests for registration to the 703 review mailing list. 705 7.1.1. Registration Template 707 Algorithm name: 708 The name requested (e.g., "example"). 709 Change controller: 710 For standards-track RFCs, state "IETF". For others, give the name 711 of the responsible party. Other details (e.g., postal address, 712 e-mail address, home page URI) may also be included. 713 Specification document(s): 714 Reference to document that specifies the algorithm, preferably 715 including a URI that can be used to retrieve a copy of the 716 document. An indication of the relevant sections may also be 717 included, but is not required. 719 7.1.2. Initial Registry Contents 721 The HTTP MAC authentication scheme algorithm registry's initial 722 contents are: 724 o Algorithm name: hmac-sha-1 725 o Change controller: IETF 726 o Specification document(s): [[ this document ]] 728 o Algorithm name: hmac-sha-256 729 o Change controller: IETF 730 o Specification document(s): [[ this document ]] 732 7.2. OAuth Access Token Type Registration 734 This specification registers the following access token type in the 735 OAuth Access Token Type Registry. 737 7.2.1. The "mac" OAuth Access Token Type 739 Type name: 740 mac 741 Additional Token Endpoint Response Parameters: 742 secret, algorithm 743 HTTP Authentication Scheme(s): 744 MAC 745 Change controller: 746 IETF 747 Specification document(s): 748 [[ this document ]] 750 7.3. OAuth Parameters Registration 752 This specification registers the following parameters in the OAuth 753 Parameters Registry established by [I-D.ietf-oauth-v2]. 755 7.3.1. The "mac_key" OAuth Parameter 757 Parameter name: mac_key 758 Parameter usage location: authorization response, token response 759 Change controller: IETF 760 Specification document(s): [[ this document ]] 761 Related information: None 763 7.3.2. The "mac_algorithm" OAuth Parameter 765 Parameter name: mac_algorithm 766 Parameter usage location: authorization response, token response 767 Change controller: IETF 768 Specification document(s): [[ this document ]] 769 Related information: None 771 8. Acknowledgments 773 The author would like to thank Ben Adida, Adam Barth, Phil Hunt, 774 Rasmus Lerdorf, James Manger, William Mills, Scott Renfro, Justin 775 Richer, Toby White, Peter Wolanin, and Skylar Woodward for their 776 contributions, suggestions, and feedback. 778 9. References 780 9.1. Normative References 782 [I-D.ietf-httpbis-p1-messaging] 783 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 784 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 785 "HTTP/1.1, part 1: URIs, Connections, and Message 786 Parsing", draft-ietf-httpbis-p1-messaging-13 (work in 787 progress), March 2011. 789 [I-D.ietf-oauth-v2] 790 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 791 2.0 Authorization Protocol", draft-ietf-oauth-v2-15 (work 792 in progress), April 2011. 794 [NIST FIPS-180-3] 795 National Institute of Standards and Technology, "Secure 796 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 798 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 799 Extensions (MIME) Part One: Format of Internet Message 800 Bodies", RFC 2045, November 1996. 802 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 803 Hashing for Message Authentication", RFC 2104, 804 February 1997. 806 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 807 Requirement Levels", BCP 14, RFC 2119, March 1997. 809 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 810 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 811 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 813 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 814 Leach, P., Luotonen, A., and L. Stewart, "HTTP 815 Authentication: Basic and Digest Access Authentication", 816 RFC 2617, June 1999. 818 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 819 Resource Identifier (URI): Generic Syntax", STD 66, 820 RFC 3986, January 2005. 822 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 823 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 824 May 2008. 826 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 827 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 829 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 830 April 2011. 832 [W3C.REC-html401-19991224] 833 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 834 Specification", World Wide Web Consortium 835 Recommendation REC-html401-19991224, December 1999, 836 . 838 9.2. Informative References 840 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 841 April 2010. 843 Author's Address 845 Eran Hammer-Lahav (editor) 847 Email: eran@hueniverse.com 848 URI: http://hueniverse.com