idnits 2.17.1 draft-ietf-oauth-v2-http-mac-02.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.tschofenig-oauth-hotk]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 227: '...nd other methods MAY be defined and us...' RFC 2119 keyword, line 228: '... the credentials MUST include the foll...' RFC 2119 keyword, line 235: '... The identifier MAY denote a unique v...' RFC 2119 keyword, line 243: '... server MUST NOT reissue a pre...' RFC 2119 keyword, line 247: '... calculate the request MAC. Value MUST...' (24 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 28, 2012) is 4160 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) -- Looks like a reference, but probably isn't: 'I-D.tschofenig-oauth-hotk' on line 22 -- Looks like a reference, but probably isn't: 'RFC2617' on line 550 -- Looks like a reference, but probably isn't: 'RFC2119' on line 217 -- Looks like a reference, but probably isn't: 'I-D.ietf-httpbis-p1-messaging' on line 219 -- Looks like a reference, but probably isn't: 'RFC2616' on line 342 -- Looks like a reference, but probably isn't: 'RFC2104' on line 401 -- Looks like a reference, but probably isn't: 'RFC2045' on line 417 -- Looks like a reference, but probably isn't: 'NIST-FIPS-180-3' on line 402 -- Looks like a reference, but probably isn't: 'RFC6749' on line 791 -- Looks like a reference, but probably isn't: 'RFC5226' on line 706 == Unused Reference: '10' is defined on line 833, but no explicit reference was found in the text == Unused Reference: '11' is defined on line 837, but no explicit reference was found in the text == Unused Reference: '12' is defined on line 840, but no explicit reference was found in the text == Unused Reference: '13' is defined on line 845, but no explicit reference was found in the text == Unused Reference: '1' is defined on line 884, but no explicit reference was found in the text == Unused Reference: '2' is defined on line 888, but no explicit reference was found in the text == Unused Reference: '3' is defined on line 893, but no explicit reference was found in the text == Unused Reference: '4' is defined on line 859, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 863, but no explicit reference was found in the text == Unused Reference: '6' is defined on line 868, but no explicit reference was found in the text == Unused Reference: '7' is defined on line 872, but no explicit reference was found in the text == Unused Reference: '8' is defined on line 876, but no explicit reference was found in the text == Unused Reference: '9' is defined on line 879, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-21 -- Possible downref: Non-RFC (?) normative reference: ref. '12' -- Possible downref: Non-RFC (?) normative reference: ref. '13' == Outdated reference: A later version (-01) exists of draft-tschofenig-oauth-security-00 ** Downref: Normative reference to an Informational draft: draft-tschofenig-oauth-security (ref. '1') == Outdated reference: A later version (-03) exists of draft-tschofenig-oauth-hotk-01 ** Obsolete normative reference: RFC 5849 (ref. '3') (Obsoleted by RFC 6749) ** Obsolete normative reference: RFC 2616 (ref. '4') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (ref. '5') (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 5226 (ref. '7') (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (ref. '8') (Obsoleted by RFC 8446) Summary: 8 errors (**), 0 flaws (~~), 17 warnings (==), 13 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth J. Richer, Ed. 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track W. Mills, Ed. 5 Expires: May 30, 2013 Yahoo! Inc. 6 H. Tschofenig, Ed. 7 Nokia Siemens Networks 8 November 28, 2012 10 OAuth 2.0 Message Authentication Code (MAC) Tokens 11 draft-ietf-oauth-v2-http-mac-02 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. 21 NOTE: This document (and other OAuth 2.0 security documents, such as 22 [I-D.tschofenig-oauth-hotk]) are still work in progress in the OAuth 23 working group. As such, the content of this document may change. 24 For a discussion about security requirements please consult [I-D 25 .tschofenig-oauth-security]. Your input on the detailed security 26 requirements is highly appreciated. 28 Status of this Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on May 30, 2013. 45 Copyright Notice 47 Copyright (c) 2012 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents (http://trustee.ietf.org/ 52 license-info) in effect on the date of publication of this document. 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. Code Components 55 extracted from this document must include Simplified BSD License text 56 as described in Section 4.e of the Trust Legal Provisions and are 57 provided without warranty as described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 5 64 2. Issuing MAC Credentials . . . . . . . . . . . . . . . . . . . 5 65 3. Making Requests . . . . . . . . . . . . . . . . . . . . . . . 6 66 3.1. The "Authorization" Request Header . . . . . . . . . . . . 6 67 3.2. Request MAC . . . . . . . . . . . . . . . . . . . . . . . 7 68 3.2.1. Normalized Request String . . . . . . . . . . . . . . 7 69 3.2.2. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . . 8 70 3.2.3. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . . 9 71 4. Verifying Requests . . . . . . . . . . . . . . . . . . . . . . 9 72 4.1. Timestamp Verification . . . . . . . . . . . . . . . . . . 9 73 4.2. The "WWW-Authenticate" Response Header Field . . . . . . . 10 74 5. Use with OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . 11 75 5.1. Issuing MAC-Type Access Tokens . . . . . . . . . . . . . . 11 76 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 77 6.1. MAC Keys Transmission . . . . . . . . . . . . . . . . . . 12 78 6.2. Confidentiality of Requests . . . . . . . . . . . . . . . 12 79 6.3. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 12 80 6.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 12 81 6.5. Entropy of MAC Keys . . . . . . . . . . . . . . . . . . . 13 82 6.6. Denial of Service / Resource Exhaustion Attacks . . . . . 13 83 6.7. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 14 84 6.8. CSRF Attacks . . . . . . . . . . . . . . . . . . . . . . . 14 85 6.9. Coverage Limitations . . . . . . . . . . . . . . . . . . . 14 86 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 87 7.1. The HTTP MAC Authentication Scheme Algorithm Registry . . 15 88 7.1.1. Registration Template . . . . . . . . . . . . . . . . 15 89 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 16 90 7.2. OAuth Access Token Type Registration . . . . . . . . . . . 16 91 7.2.1. The "mac" OAuth Access Token Type . . . . . . . . . . 16 92 7.3. OAuth Parameters Registration . . . . . . . . . . . . . . 17 93 7.3.1. The "mac_key" OAuth Parameter . . . . . . . . . . . . 17 94 7.3.2. The "mac_algorithm" OAuth Parameter . . . . . . . . . 17 95 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 17 96 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 97 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 98 10.1. Normative References . . . . . . . . . . . . . . . . . . 17 99 10.2. Informative References . . . . . . . . . . . . . . . . . 18 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19 102 1. Introduction 103 This specification defines the HTTP MAC access authentication scheme, 104 providing a method for making authenticated HTTP requests with 105 partial cryptographic verification of the request, covering the HTTP 106 method, request URI, and host. 108 Similar to the HTTP Basic access authentication scheme [RFC2617], the 109 MAC scheme utilizes a set of client credentials which include an 110 identifier and key. However, in contrast with the Basic scheme, the 111 key is never included in authenticated requests but is used to 112 calculate the request MAC value which is included instead. 114 The MAC scheme requires the establishment of a shared symmetric key 115 between the client and the server. This specification offers one 116 such method for issuing a set of MAC credentials to the client using 117 OAuth 2.0 in the form of a MAC-type access token. 119 The primary design goal of this mechanism is to simplify and improve 120 HTTP authentication for services that are unwilling or unable to 121 employ TLS for every request. In particular, this mechanism leverage 122 an initial TLS setup phase to establish a shared secret between the 123 client and the server. The shared secret is then used over an 124 insecure channel to provide protection against a passive network 125 attacker. 127 In particular, when a server uses this mechanism, a passive network 128 attacker will be unable to "steal" the user's session token, as is 129 possible today with cookies and other bearer tokens. In addition, 130 this mechanism helps secure the session token against leakage when 131 sent over a secure channel to the wrong server. For example, when 132 the client uses some form of dynamic configuration to determine where 133 to send an authenticated request, or when the client fails to 134 properly validate the server's identity as part of its TLS handshake. 136 Unlike the HTTP Digest authentication scheme, this mechanism does not 137 require interacting with the server to prevent replay attacks. 138 Instead, the client provides both a nonce and a timestamp, which the 139 server can use to prevent replay attacks using a bounded amount of 140 storage. Also unlike Digest, this mechanism is not intended to 141 protect the user's password itself because the client and server both 142 have access to the key material in the clear. Instead, servers 143 should issue a short-lived derivative credential for this mechanism 144 during the initial TLS setup phase. 146 1.1. Example 148 The client attempts to access a protected resource without 149 authentication, making the following HTTP request to the resource 150 server: 152 GET /resource/1?b=1&a=2 HTTP/1.1 153 Host: example.com 155 The resource server returns the following authentication challenge: 157 HTTP/1.1 401 Unauthorized 158 WWW-Authenticate: MAC 160 The client has previously obtained a set of MAC credentials for 161 accessing resources on the "http://example.com/" server. The MAC 162 credentials issued to the client include the following attributes: 164 MAC key identifier: h480djs93hd8 166 MAC key: 489dks293j39 168 MAC algorithm: hmac-sha-1 170 The client constructs the authentication header by calculating a 171 timestamp (e.g. the number of seconds since January 1, 1970 00:00:00 172 GMT) and generating a random string used as a nonce: 174 Timestamp: 1336363200 176 Nonce: dj83hs9s 178 The client constructs the normalized request string (the new line 179 separator character is represented by "\n" for display purposes only; 180 the trailing new line separator signify that no extension value is 181 included with the request, explained below): 183 1336363200\n 184 dj83hs9s\n 185 GET\n 186 /resource/1?b=1&a=2\n 187 example.com\n 188 80\n 189 \n 191 The request MAC is calculated using the specified MAC algorithm 192 "hmac-sha-1" and the MAC key over the normalized request string. The 193 result is base64-encoded to produce the request MAC: 195 bhCQXTVyfj5cmA9uKkPFx1zeOXM= 197 The client includes the MAC key identifier, nonce, and request MAC 198 with the request using the "Authorization" request header field: 200 GET /resource/1?b=1&a=2 HTTP/1.1 201 Host: example.com 202 Authorization: MAC id="h480djs93hd8", 203 ts="1336363200", 204 nonce="dj83hs9s", 205 mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM=" 207 The server validates the request by calculating the request MAC again 208 based on the request received and verifies the validity and scope of 209 the MAC credentials. If valid, the server responds with the 210 requested resource representation. 212 1.2. Notational Conventions 214 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 215 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 216 specification are to be interpreted as described in [RFC2119]. 218 This specification uses the Augmented Backus-Naur Form (ABNF) 219 notation of [I-D.ietf-httpbis-p1-messaging]. Additionally, the 220 following rules are included from [RFC2617]: auth-param. 222 2. Issuing MAC Credentials 224 This specification provides one method for issuing MAC credentials 225 using OAuth 2.0 as described in Section 5. This specification does 226 not mandate servers to support any particular method for issuing MAC 227 credentials, and other methods MAY be defined and used. Whenever MAC 228 credentials are issued, the credentials MUST include the following 229 attributes: 231 MAC key identifier 232 A string identifying the MAC key used to calculate the request 233 MAC. The string is usually opaque to the client. The server 234 typically assigns a specific scope and lifetime to each set of 235 MAC credentials. The identifier MAY denote a unique value used 236 to retrieve the authorization information (e.g. from a 237 database), or self-contain the authorization information in a 238 verifiable manner (i.e. a string consisting of some data and a 239 signature). 241 MAC key 242 A shared symmetric secret used as the MAC algorithm key. The 243 server MUST NOT reissue a previously issued MAC key and MAC key 244 identifier combination. 246 MAC algorithm 247 A MAC algorithm used to calculate the request MAC. Value MUST 248 be one of "hmac-sha-1", "hmac-sha-256", or a registered 249 extension algorithm name as described in Section 7.1. 250 Algorithm names are case-sensitive. If the MAC algorithm is 251 not understood by the client, the client MUST NOT use the MAC 252 credentials and continue as if no MAC credentials were issued. 254 The MAC key identifier, MAC key, MAC algorithm strings MUST NOT 255 include characters other than: 257 %x20-21 / %x23-5B / %x5D-7E 258 ; Any printable ASCII character except for <"> and <\> 260 3. Making Requests 262 To make authenticated requests, the client must be in the possession 263 of a valid set of MAC credentials accepted by the server. The client 264 constructs the request by calculating a set of attributes, and adding 265 them to the HTTP request using the "Authorization" request header 266 field as described in Section 3.1. 268 3.1. The "Authorization" Request Header 270 The "Authorization" request header field uses the framework defined 271 by [RFC2617] as follows: 273 credentials = "MAC" 1*SP #params 275 params = id / ts / nonce / ext / mac 277 id = "id" "=" string-value 278 ts = "ts" "=" ( <"> timestamp <"> ) / timestamp 279 nonce = "nonce" "=" string-value 280 ext = "ext" "=" string-value 281 mac = "mac" "=" string-value 283 timestamp = 1*DIGIT 284 string-value = ( <"> plain-string <"> ) / plain-string 285 plain-string = 1*( %x20-21 / %x23-5B / %x5D-7E ) 287 The header attributes are set as follows: 289 id 290 REQUIRED. The MAC key identifier. 292 ts 293 REQUIRED. The request timestamp. The value MUST be a positive 294 integer set by the client when making each request to the 295 number of seconds elapsed from a fixed point in time (e.g. 296 January 1, 1970 00:00:00 GMT). The value MUST NOT include 297 leading zeros (e.g. "000273154346"). 299 nonce 300 REQUIRED. A unique string generated by the client. The value 301 MUST be unique across all requests with the same timestamp and 302 MAC key identifier combination. 304 ext 305 OPTIONAL. A string used to include additional information which 306 is covered by the request MAC. The content and format of the 307 string is beyond the scope of this specification. 309 mac 310 REQUIRED. The HTTP request MAC as described in Section 3.2. 312 Attributes MUST NOT appear more than once. Attribute values are 313 limited to a subset of ASCII, which does not require escaping, as 314 defined by the plain-string ABNF. 316 3.2. Request MAC 318 The client uses the MAC algorithm and the MAC key to calculate the 319 request MAC. This specification defines two algorithms: "hmac-sha-1" 320 and "hmac-sha-256", and provides an extension registry for additional 321 algorithms. 323 3.2.1. Normalized Request String 325 The normalized request string is a consistent, reproducible 326 concatenation of several of the HTTP request elements into a single 327 string. By normalizing the request into a reproducible string, the 328 client and server can both calculate the request MAC over the exact 329 same value. 331 The string is constructed by concatenating together, in order, the 332 following HTTP request elements, each followed by a new line 333 character (%x0A): 335 1. The timestamp value calculated for the request. 337 2. The nonce value generated for the request. 339 3. The HTTP request method in upper case. For example: "HEAD", 340 "GET", "POST", etc. 342 4. The HTTP request-URI as defined by [RFC2616] section 5.1.2. 344 5. The hostname included in the HTTP request using the "Host" 345 request header field in lower case. 347 6. The port as included in the HTTP request using the "Host" request 348 header field. If the header field does not include a port, the 349 default value for the scheme MUST be used (e.g. 80 for HTTP and 350 443 for HTTPS). 352 7. The value of the "ext" "Authorization" request header field 353 attribute if one was included in the request, otherwise, an empty 354 string. 356 Each element is followed by a new line character (%x0A) including the 357 last element and even when an element value is an empty string. 359 For example, the HTTP request: 361 POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1 362 Host: example.com 364 Hello World! 366 using timestamp "264095:7d8f3e4a", nonce "7d8f3e4a", and extension 367 string "a,b,c" is normalized into the following string (the new line 368 separator character is represented by "\n" for display purposes 369 only): 371 264095\n 372 7d8f3e4a\n 373 POST\n 374 /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q\n 375 example.com\n 376 80\n 377 a,b,c\n 379 3.2.2. hmac-sha-1 381 "hmac-sha-1" uses the HMAC-SHA1 algorithm as defined in [RFC2104]: 383 mac = HMAC-SHA1 (key, text) 385 Where: 387 text 388 is set to the value of the normalized request string as 389 described in Section 3.2.1, 391 key 392 is set to the MAC key provided by the server, and 394 mac 395 is used to set the value of the "mac" attribute, after the 396 result octet string is base64-encoded per [RFC2045] section 397 6.8. 399 3.2.3. hmac-sha-256 401 "hmac-sha-256" uses the HMAC algorithm as defined in [RFC2104] 402 together with the SHA-256 hash function defined in [NIST-FIPS-180-3]: 404 mac = HMAC-SHA256 (key, text) 406 Where: 408 text 409 is set to the value of the normalize request string as 410 described in Section 3.2.1, 412 key 413 is set to the MAC key provided by the server, and 415 mac 416 is used to set the value of the "mac" attribute, after the 417 result octet string is base64-encoded per [RFC2045] section 418 6.8. 420 4. Verifying Requests 422 A server receiving an authenticated request validates it by 423 performing the following REQUIRED steps: 425 1. Recalculate the request MAC as described in Section 3.2 and 426 compare the request MAC to the value received from the client via 427 the "mac" attribute. 429 2. Ensure that the combination of timestamp, nonce, and MAC key 430 identifier received from the client has not been received before 431 in a previous request. The server MAY reject requests with stale 432 timestamps as described in Section 4.1. 434 3. Verify the scope and validity of the MAC credentials. 436 If the request fails verification, the server SHOULD respond using 437 the 401 (Unauthorized) HTTP status code and include the "WWW- 438 Authenticate" response header field as described in Section 4.2. 440 4.1. Timestamp Verification 441 The timestamp, nonce, and MAC key identifier combination provide a 442 unique identifier which enables the server to prevent replay attacks. 443 Without replay protection, an attacker can use a compromised (but 444 otherwise valid and authenticated) request more than once, gaining 445 long term access to a protected resource. 447 Including a timestamp with the nonce removes the need to retain an 448 infinite number of nonce values for future checks, by enabling the 449 server to restrict the time period after which a request with an old 450 timestamp is rejected. If such a restriction is enforced, the server 451 MUST: 453 o At the time the first request is received from the client for each 454 MAC key identifier, calculate the difference (in seconds) between 455 the request timestamp and the server's clock. The difference - 456 the request time delta - MUST be kept as long as the MAC key 457 credentials are valid. 459 o For each subsequent client request, apply the request time delta 460 to request timestamp to calculate the adjusted request time - the 461 time when the request MAC has been generated by the client, 462 adjusted to the server's clock. 464 o Verify that the adjusted request time is within the allowed time 465 period defined by the server. The server SHOULD allow for a 466 sufficiently large window to accommodate network delays (between 467 the time the request has been generated by the client to the time 468 it is received by the server and processed). 470 4.2. The "WWW-Authenticate" Response Header Field 472 If the protected resource request does not include authentication 473 credentials, contains an invalid MAC key identifier, or is malformed, 474 the server SHOULD include the HTTP "WWW-Authenticate" response header 475 field. 477 For example: 479 HTTP/1.1 401 Unauthorized 480 WWW-Authenticate: MAC 482 The "WWW-Authenticate" request header field uses the framework 483 defined by [RFC2617] as follows: 485 challenge = "MAC" [ 1*SP #param ] 486 param = error / auth-param 487 error = "error" "=" ( token / quoted-string) 489 Each attribute MUST NOT appear more than once. 491 If the protected resource request included a MAC "Authorization" 492 request header field and failed authentication, the server MAY 493 include the "error" attribute to provide the client with a human- 494 readable explanation why the access request was declined to assist 495 the client developer in identifying the problem. 497 For example: 499 HTTP/1.1 401 Unauthorized 500 WWW-Authenticate: MAC error="The MAC credentials expired" 502 5. Use with OAuth 2.0 504 OAuth 2.0 ([RFC6749]) defines an extensible token-based 505 authentication framework. The MAC authentication scheme can be used 506 to make OAuth-based requests by issuing MAC-type access tokens. 508 This specification does not define methods for the client to 509 specifically request a MAC-type token from the authorization server. 510 Additionally, it does not include any discovery facilities for 511 identifying which HMAC algorithms are supported by a resource server, 512 or how the client may go about obtaining MAC access tokens for any 513 given protected resource. 515 5.1. Issuing MAC-Type Access Tokens 517 Authorization servers issuing MAC-type access tokens MUST include the 518 following parameters whenever a response includes the "access_token" 519 parameter: 521 access_token 522 REQUIRED. The MAC key identifier. 524 mac_key 525 REQUIRED. The MAC key. 527 mac_algorithm 528 REQUIRED. The MAC algorithm used to calculate the request MAC. 529 Value MUST be one of "hmac-sha-1", "hmac-sha-256", or a 530 registered extension algorithm name as described in Section 531 7.1. 533 For example: 535 HTTP/1.1 200 OK 536 Content-Type: application/json 537 Cache-Control: no-store 539 { 540 "access_token":"SlAV32hkKG", 541 "token_type":"mac", 542 "expires_in":3600, 543 "refresh_token":"8xLOxBtZp8", 544 "mac_key":"adijq39jdlaska9asud", 545 "mac_algorithm":"hmac-sha-256" 546 } 548 6. Security Considerations 550 As stated in [RFC2617], the greatest sources of risks are usually 551 found not in the core protocol itself but in policies and procedures 552 surrounding its use. Implementers are strongly encouraged to assess 553 how this protocol addresses their security requirements. 555 6.1. MAC Keys Transmission 557 This specification describes two mechanism for obtaining or 558 transmitting MAC keys, both require the use of a transport-layer 559 security mechanism when sending MAC keys to the client. Additional 560 methods used to obtain MAC credentials must ensure that these 561 transmissions are protected using transport-layer mechanisms such as 562 TLS or SSL. 564 6.2. Confidentiality of Requests 566 While this protocol provides a mechanism for verifying the integrity 567 of requests, it provides no guarantee of request confidentiality. 568 Unless further precautions are taken, eavesdroppers will have full 569 access to request content. Servers should carefully consider the 570 kinds of data likely to be sent as part of such requests, and should 571 employ transport-layer security mechanisms to protect sensitive 572 resources. 574 6.3. Spoofing by Counterfeit Servers 576 This protocol makes no attempt to verify the authenticity of the 577 server. A hostile party could take advantage of this by intercepting 578 the client's requests and returning misleading or otherwise incorrect 579 responses. Service providers should consider such attacks when 580 developing services using this protocol, and should require 581 transport-layer security for any requests where the authenticity of 582 the resource server or of request responses is an issue. 584 6.4. Plaintext Storage of Credentials 585 The MAC key functions the same way passwords do in traditional 586 authentication systems. In order to compute the request MAC, the 587 server must have access to the MAC key in plaintext form. This is in 588 contrast, for example, to modern operating systems, which store only 589 a one-way hash of user credentials. 591 If an attacker were to gain access to these MAC keys - or worse, to 592 the server's database of all such MAC keys - he or she would be able 593 to perform any action on behalf of any resource owner. Accordingly, 594 it is critical that servers protect these MAC keys from unauthorized 595 access. 597 6.5. Entropy of MAC Keys 599 Unless a transport-layer security protocol is used, eavesdroppers 600 will have full access to authenticated requests and request MAC 601 values, and will thus be able to mount offline brute-force attacks to 602 recover the MAC key used. Servers should be careful to assign MAC 603 keys which are long enough, and random enough, to resist such attacks 604 for at least the length of time that the MAC credentials are valid. 606 For example, if the MAC credentials are valid for two weeks, servers 607 should ensure that it is not possible to mount a brute force attack 608 that recovers the MAC key in less than two weeks. Of course, servers 609 are urged to err on the side of caution, and use the longest MAC key 610 reasonable. 612 It is equally important that the pseudo-random number generator 613 (PRNG) used to generate these MAC keys be of sufficiently high 614 quality. Many PRNG implementations generate number sequences that 615 may appear to be random, but which nevertheless exhibit patterns or 616 other weaknesses which make cryptanalysis or brute force attacks 617 easier. Implementers should be careful to use cryptographically 618 secure PRNGs to avoid these problems. 620 6.6. Denial of Service / Resource Exhaustion Attacks 622 This specification includes a number of features which may make 623 resource exhaustion attacks against servers possible. For example, 624 this protocol requires servers to track used nonces. If an attacker 625 is able to use many nonces quickly, the resources required to track 626 them may exhaust available capacity. And again, this protocol can 627 require servers to perform potentially expensive computations in 628 order to verify the request MAC on incoming requests. An attacker 629 may exploit this to perform a denial of service attack by sending a 630 large number of invalid requests to the server. 632 Resource Exhaustion attacks are by no means specific to this 633 specification. However, implementers should be careful to consider 634 the additional avenues of attack that this protocol exposes, and 635 design their implementations accordingly. For example, entropy 636 starvation typically results in either a complete denial of service 637 while the system waits for new entropy or else in weak (easily 638 guessable) MAC keys. When implementing this protocol, servers should 639 consider which of these presents a more serious risk for their 640 application and design accordingly. 642 6.7. Timing Attacks 644 This specification makes use of HMACs, for which a signature 645 verification involves comparing the received MAC string to the 646 expected one. If the string comparison operator operates in 647 observably different times depending on inputs, e.g. because it 648 compares the strings character by character and returns a negative 649 result as soon as two characters fail to match, then it may be 650 possible to use this timing information to determine the expected 651 MAC, character by character. 653 Service implementers are encouraged to use fixed-time string 654 comparators for MAC verification. 656 6.8. CSRF Attacks 658 A Cross-Site Request Forgery attack occurs when a site, evil.com, 659 initiates within the victim's browser the loading of a URL from or 660 the posting of a form to a web site where a side-effect will occur, 661 e.g. transfer of money, change of status message, etc. To prevent 662 this kind of attack, web sites may use various techniques to 663 determine that the originator of the request is indeed the site 664 itself, rather than a third party. The classic approach is to 665 include, in the set of URL parameters or form content, a nonce 666 generated by the server and tied to the user's session, which 667 indicates that only the server could have triggered the action. 669 Recently, the Origin HTTP header has been proposed and deployed in 670 some browsers. This header indicates the scheme, host, and port of 671 the originator of a request. Some web applications may use this 672 Origin header as a defense against CSRF. 674 To keep this specification simple, HTTP headers are not part of the 675 string to be MAC'ed. As a result, MAC authentication cannot defend 676 against header spoofing, and a web site that uses the Host header to 677 defend against CSRF attacks cannot use MAC authentication to defend 678 against active network attackers. Sites that want the full 679 protection of MAC Authentication should use traditional, cookie-tied 680 CSRF defenses. 682 6.9. Coverage Limitations 683 The normalized request string has been designed to support the 684 authentication methods defined in this specification. Those 685 designing additional methods, should evaluated the compatibility of 686 the normalized request string with their security requirements. 687 Since the normalized request string does not cover the entire HTTP 688 request, servers should employ additional mechanisms to protect such 689 elements. 691 The request MAC does not cover entity-header fields which can often 692 affect how the request body is interpreted by the server (i.e. 693 Content-Type). If the server behavior is influenced by the presence 694 or value of such header fields, an attacker can manipulate the 695 request header without being detected. 697 7. IANA Considerations 699 7.1. The HTTP MAC Authentication Scheme Algorithm Registry 701 This specification establishes the HTTP MAC authentication scheme 702 algorithm registry. 704 Additional MAC algorithms are registered on the advice of one or more 705 Designated Experts (appointed by the IESG or their delegate), with a 706 Specification Required (using terminology from [RFC5226]). However, 707 to allow for the allocation of values prior to publication, the 708 Designated Expert(s) may approve registration once they are satisfied 709 that such a specification will be published. 711 Registration requests should be sent to the [TBD]@ietf.org mailing 712 list for review and comment, with an appropriate subject (e.g., 713 "Request for MAC Algorithm: example"). [[ Note to RFC-EDITOR: The 714 name of the mailing list should be determined in consultation with 715 the IESG and IANA. Suggested name: http-mac-ext-review. ]] 717 Within at most 14 days of the request, the Designated Expert(s) will 718 either approve or deny the registration request, communicating this 719 decision to the review list and IANA. Denials should include an 720 explanation and, if applicable, suggestions as to how to make the 721 request successful. 723 Decisions (or lack thereof) made by the Designated Expert can be 724 first appealed to Application Area Directors (contactable using app- 725 ads@tools.ietf.org email address or directly by looking up their 726 email addresses on http://www.iesg.org/ website) and, if the 727 appellant is not satisfied with the response, to the full IESG (using 728 the iesg@iesg.org mailing list). 730 IANA should only accept registry updates from the Designated 731 Expert(s), and should direct all requests for registration to the 732 review mailing list. 734 7.1.1. Registration Template 735 Algorithm name: 736 The name requested (e.g., "example"). 738 Change controller: 739 For standards-track RFCs, state "IETF". For others, give the name 740 of the responsible party. Other details (e.g., postal address, 741 e-mail address, home page URI) may also be included. 743 Specification document(s): 744 Reference to document that specifies the algorithm, preferably 745 including a URI that can be used to retrieve a copy of the 746 document. An indication of the relevant sections may also be 747 included, but is not required. 749 7.1.2. Initial Registry Contents 751 The HTTP MAC authentication scheme algorithm registry's initial 752 contents are: 754 o Algorithm name: hmac-sha-1 756 o Change controller: IETF 758 o Specification document(s): [[ this document ]] 760 o Algorithm name: hmac-sha-256 762 o Change controller: IETF 764 o Specification document(s): [[ this document ]] 766 7.2. OAuth Access Token Type Registration 768 This specification registers the following access token type in the 769 OAuth Access Token Type Registry. 771 7.2.1. The "mac" OAuth Access Token Type 773 Type name: 774 mac 776 Additional Token Endpoint Response Parameters: 777 secret, algorithm 779 HTTP Authentication Scheme(s): 780 MAC 782 Change controller: 783 IETF 785 Specification document(s): 786 [[ this document ]] 788 7.3. OAuth Parameters Registration 790 This specification registers the following parameters in the OAuth 791 Parameters Registry established by [RFC6749]. 793 7.3.1. The "mac_key" OAuth Parameter 795 Parameter name: mac_key 797 Parameter usage location: authorization response, token response 799 Change controller: IETF 801 Specification document(s): [[ this document ]] 803 Related information: None 805 7.3.2. The "mac_algorithm" OAuth Parameter 807 Parameter name: mac_algorithm 809 Parameter usage location: authorization response, token response 811 Change controller: IETF 813 Specification document(s): [[ this document ]] 815 Related information: None 817 8. Contributors 819 This document is based on OAuth 1.0 and we would like to thank Eran 820 Hammer-Lahav for his work on incorporating the ideas into OAuth 2.0. 822 9. Acknowledgments 824 The author would like to thank Ben Adida, Adam Barth, Phil Hunt, 825 Rasmus Lerdorf, James Manger, William Mills, Scott Renfro, Justin 826 Richer, Toby White, Peter Wolanin, and Skylar Woodward for their 827 contributions, suggestions, and feedback. 829 10. References 831 10.1. Normative References 833 [10] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 834 (HTTP/1.1): Message Syntax and Routing", Internet-Draft 835 draft-ietf-httpbis-p1-messaging-21, October 2012. 837 [11] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 838 6749, October 2012. 840 [12] Hors, A., Raggett, D. and I. Jacobs, "HTML 4.01 841 Specification", World Wide Web Consortium Recommendation 842 REC-html401-19991224, December 1999, . 845 [13] National Institute of Standards and Technology, "Secure 846 Hash Standard (SHS). FIPS PUB 180-3, October 2008", . 848 [1] Bradner, S., "Key words for use in RFCs to Indicate 849 Requirement Levels", BCP 14, RFC 2119, March 1997. 851 [2] Freed, N. and N.S. Borenstein, "Multipurpose Internet Mail 852 Extensions (MIME) Part One: Format of Internet Message 853 Bodies", RFC 2045, November 1996. 855 [3] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed- 856 Hashing for Message Authentication", RFC 2104, February 857 1997. 859 [4] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 860 Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext 861 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 863 [5] Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, 864 S.D., Leach, P.J., Luotonen, A. and L. Stewart, "HTTP 865 Authentication: Basic and Digest Access Authentication", 866 RFC 2617, June 1999. 868 [6] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 869 Resource Identifier (URI): Generic Syntax", STD 66, RFC 870 3986, January 2005. 872 [7] Narten, T. and H. Alvestrand, "Guidelines for Writing an 873 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 874 May 2008. 876 [8] Dierks, T. and E. Rescorla, "The Transport Layer Security 877 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 879 [9] Barth, A., "HTTP State Management Mechanism", RFC 6265, 880 April 2011. 882 10.2. Informative References 884 [1] Tschofenig, H. and P. Hunt, "OAuth 2.0 Security: Going 885 Beyond Bearer Tokens", Internet-Draft draft-tschofenig- 886 oauth-security-00, September 2012. 888 [2] Bradley, J., Hunt, P., Nadalin, A. and H. Tschofenig, "The 889 OAuth 2.0 Authorization Framework: Holder-of-the-Key Token 890 Usage", Internet-Draft draft-tschofenig-oauth-hotk-01, 891 July 2012. 893 [3] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 894 April 2010. 896 Authors' Addresses 898 Justin Richer, editor 899 The MITRE Corporation 901 Email: jricher@mitre.org 903 William Mills, editor 904 Yahoo! Inc. 906 Email: wmills@yahoo-inc.com 908 Hannes Tschofenig, editor 909 Nokia Siemens Networks 910 Linnoitustie 6 911 Espoo, 02600 912 Finland 914 Phone: +358 (50) 4871445 915 Email: Hannes.Tschofenig@gmx.net 916 URI: http://www.tschofenig.priv.at