idnits 2.17.1 draft-hammer-oauth-v2-mac-token-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). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: If the request lacks any authentication information (i.e. the client was unaware authentication is necessary or attempted using an unsupported authentication method), the resource server SHOULD not include an error code or other error information. -- The document date (January 18, 2011) is 4845 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: 'RFC5849' is defined on line 831, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-08 == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-11 -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST FIPS-180-3' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Hammer-Lahav 3 Internet-Draft Yahoo! 4 Intended status: Standards Track January 18, 2011 5 Expires: July 22, 2011 7 HTTP Authentication: MAC Authentication 8 draft-hammer-oauth-v2-mac-token-01 10 Abstract 12 This document specifies the HTTP MAC authentication scheme, as well 13 as its OAuth 2.0 binding. 15 Status of this Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on July 22, 2011. 32 Copyright Notice 34 Copyright (c) 2011 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 1.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 5 52 2. Issuing MAC Credentials . . . . . . . . . . . . . . . . . . . 5 53 3. Making Requests . . . . . . . . . . . . . . . . . . . . . . . 6 54 3.1. The Authorization Request Header . . . . . . . . . . . . . 6 55 3.2. Signature . . . . . . . . . . . . . . . . . . . . . . . . 7 56 3.2.1. Normalized Request String . . . . . . . . . . . . . . 7 57 3.2.2. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . . 11 58 3.2.3. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . . 11 59 4. Verifying Requests . . . . . . . . . . . . . . . . . . . . . . 12 60 4.1. The WWW-Authenticate Response Header Field . . . . . . . . 12 61 4.1.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 13 62 5. Scheme Extensions . . . . . . . . . . . . . . . . . . . . . . 14 63 6. Use with OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . 14 64 6.1. Issuing MAC-Type Access Tokens . . . . . . . . . . . . . . 15 65 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 66 7.1. Secrets Transmission . . . . . . . . . . . . . . . . . . . 15 67 7.2. Confidentiality of Requests . . . . . . . . . . . . . . . 15 68 7.3. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 15 69 7.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 16 70 7.5. Entropy of Secrets . . . . . . . . . . . . . . . . . . . . 16 71 7.6. Denial of Service / Resource Exhaustion Attacks . . . . . 16 72 7.7. Coverage Limitations . . . . . . . . . . . . . . . . . . . 17 73 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 74 8.1. The "secret" OAuth Parameter . . . . . . . . . . . . . . . 17 75 8.2. The "algorithm" OAuth Parameter . . . . . . . . . . . . . 18 76 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 77 Appendix A. Document History . . . . . . . . . . . . . . . . . . 18 78 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 79 10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 80 10.2. Informative References . . . . . . . . . . . . . . . . . . 19 81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 83 1. Introduction 85 This specification defines the HTTP MAC authentication scheme and 86 provides a method for making authenticated HTTP requests with partial 87 cryptographic verification of the request - covering the HTTP method, 88 request URI, host, and in some cases the request body. 90 This specification uses the terminology defined in 91 [I-D.ietf-oauth-v2]. 93 Please discuss this draft on the oauth@ietf.org [1] mailing list. 95 1.1. Example 97 The client attempts to access a protected resource without 98 authentication, making the following HTTP request to the resource 99 server: 101 GET /resource/1?b=1&a=2 HTTP/1.1 102 Host: example.com 104 The resource server returns the following authentication challenge: 106 HTTP/1.1 401 Unauthorized 107 WWW-Authenticate: MAC realm="example" 108 Date: Thu, 02 Dec 2010 21:39:45 GMT 110 The client has previously obtained a set of token credentials for 111 accessing resources on the "http://example.com/" resource server. 112 The MAC credentials issued to the client included the following 113 attributes: 115 Access Token: h480djs93hd8 117 Token secret: 489dks293j39 119 MAC algorithm: hmac-sha-1 121 The client attempts the HTTP request again, this time using the token 122 credentials issued earlier to authenticate. To construct the 123 authentication header, the client calculates the current timestamp 124 and a nonce. The nonce is unique to the timestamp used, typically a 125 random string: 127 Timestamp: 137131200 129 Nonce: dj83hs9s 131 The client normalizes the request and constructs the normalized 132 request string (the new line separator character is represented by 133 "\n" for display purposes only): 135 h480djs93hd8\n 136 137131200\n 137 dj83hs9s\n 138 GET\n 139 example.com\n 140 80\n 141 /resource/1\n 142 a=2\n 143 b=1\n 145 The normalized request string is signed using the specified MAC 146 algorithm "hmac-sha-1" with the normalized request string as text and 147 the token secret as key. The resulting digest is base64-encoded to 148 produce the request signature: 150 kDZvddkndxvhGRXZhvuDjEWhGeE= 152 The client includes the access token, timestamp, nonce, and signature 153 with the request using the "Authorization" request header field: 155 GET /resource/1 HTTP/1.1 156 Host: example.com 157 Authorization: MAC token="h480djs93hd8", 158 timestamp="137131200", 159 nonce="dj83hs9s", 160 signature="kDZvddkndxvhGRXZhvuDjEWhGeE=" 162 The resource server validates the request by calculating the 163 signature again based on the request received and verifies the 164 validity and scope of the access token. If valid, the resource 165 server responds with the requested protected resource representation. 167 1.2. Notational Conventions 169 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 170 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 171 document are to be interpreted as described in [RFC2119]. 173 This document uses the Augmented Backus-Naur Form (ABNF) notation of 174 [I-D.ietf-httpbis-p1-messaging]. Additionally, the following rules 175 are included from [RFC2617]: realm, auth-param. 177 2. Issuing MAC Credentials 179 This specification does not define a general purpose method for 180 requesting or issuing MAC credentials (an OAuth 2.0 181 [I-D.ietf-oauth-v2] binding is provided in Section 6). It simply 182 assumes that the client is in the possession of a set of MAC 183 credentials with the following REQUIRES attributes: 185 access token 186 A string representing an access authorization issued to the 187 client. The string is usually opaque to the client. Tokens 188 represent specific scopes and durations of access. The token 189 may denote an identifier used to retrieve the authorization 190 information, or self-contain the authorization information in a 191 verifiable manner (i.e. a token string consisting of some data 192 and a signature). 194 secret 195 A shared symmetric secret used as the MAC algorithm key. 197 algorithm 198 A MAC algorithm used to calculate the request signature. Value 199 MUST be one of "hmac-sha-1", "hmac-sha-256", or a registered 200 extension algorithm name as described in Section 5. 202 The access token and secret strings MUST NOT include characters other 203 than: 205 DIGIT / ALPHA / %x20-21 / %x23-5B / %x5D-7E 206 ; Any printable ASCII character except for <"> and <\> 208 3. Making Requests 210 To make authenticated requests, the client must be in possession of a 211 valid set of MAC credentials accepted by the resource server. The 212 client constructs the request by calculating of a set of attributes, 213 and adding them to the HTTP request using the Authorization header 214 field (Section 3.1). Authenticated request can be sent in response 215 to an authentication challenge or directly. 217 3.1. The Authorization Request Header 219 The "Authorization" request header field uses the framework defined 220 by [RFC2617] as follows: 222 credentials = 'MAC' [ RWS 1#param ] 224 param = access-token / 225 timestamp / 226 nonce / 227 signature 229 access-token = 'token' '=' <"> plain-string <"> 230 timestamp = 'timestamp' '=' <"> 1*DIGIT <"> 231 nonce = 'nonce' '=' <"> plain-string <"> 232 signature = 'signature' '=' <"> plain-string <"> 234 plain-string = 1*( DIGIT / ALPHA / %x20-21 / %x23-5B / %x5D-7E ) 236 The "token" attribute value is set to the access token string. 238 The "timestamp" attribute value is set to the current time expressed 239 in the number of seconds since January 1, 1970 00:00:00 GMT, and MUST 240 be a positive integer. 242 The "nonce" attribute value is set to a random string, uniquely 243 generated by the client to allow the resource server to verify that a 244 request has never been made before and helps prevent replay attacks 245 when requests are made over an insecure channel. The nonce value 246 MUST be unique across all requests with the same timestamp and access 247 token combination. 249 To avoid the need to retain an infinite number of nonce values for 250 future checks, resource servers MAY choose to restrict the time 251 period after which a request with an old timestamp is rejected. Such 252 a restriction implies a level of synchronization between the client's 253 and server's clocks. The client MAY use the "Date" response header 254 field to synchronize its clock after a failed request. 256 The "signature" attribute value is set as described in Section 3.2. 258 Each of the four attributes MUST appear once, and only once. 259 Attribute values are limited to a subset of ASCII, which does not 260 require escaping. 262 3.2. Signature 264 The client uses the MAC algorithm and the token secret to calculate 265 the request signature. This specification defines two algorithms: 266 "hmac-sha-1" and "hmac-sha-256", and provides an extension registry 267 for additional algorithms. 269 3.2.1. Normalized Request String 271 The normalized request string is a consistent, reproducible 272 concatenation of several of the HTTP request elements into a single 273 string. By normalizing the request into a reproducible string, the 274 client and resource server can both sign the same string. 276 The string is constructed by concatenating together, in order, the 277 following HTTP request elements, each followed by a new line 278 character (%x0A): 280 1. The access token. 282 2. The timestamp value calculated for the request. 284 3. The nonce value generated for the request. 286 4. The HTTP request method in upper case. For example: "HEAD", 287 "GET", "POST", etc. 289 5. The hostname included in the HTTP request using the "Host" 290 request header field in lower case. 292 6. The port as included in the HTTP request using the "Host" request 293 header field. If the header field does not include a port, the 294 default value for the scheme MUST be used (e.g. 80 for HTTP and 295 443 for HTTPS). 297 7. The path component of the HTTP request URI as defined by 298 [RFC3986] section 3.3. 300 8. The query component of the HTTP request URI as defined by 301 [RFC3986] section 3.4, normalized as described in 302 Section 3.2.1.1. 304 [[ TODO: I18N ]] 306 For example, the HTTP request: 308 GET /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1 309 Host: example.com 311 using access token "kkk9d7dh3k39sjv7", timestamp "137131201", and 312 nonce "7d8f3e4a" is normalized into the following string (the new 313 line Separator character is represented by "\n" for display purposes 314 only): 316 kkk9d7dh3k39sjv7\n 317 137131201\n 318 7d8f3e4a\n 319 GET\n 320 example.com\n 321 80\n 322 /request\n 323 a2=r%20b\n 324 a3=2%20q\n 325 a3=a\n 326 b5=%3D%253D\n 327 c%40=\n 328 c2=\n 330 3.2.1.1. Parameters Normalization 332 The query component is parsed into a list of name/value parameter 333 pairs by treating it as an "application/x-www-form-urlencoded" 334 string, separating the names and values and decoding them as defined 335 by [W3C.REC-html401-19991224] section 17.13.4. 337 Once separated and decoded, the parameters are concatenated back 338 together as follows: 340 1. First, the name and value of each parameter are escaped using the 341 [RFC3986] percent-encoding (%XX) mechanism. Characters in the 342 unreserved character set as defined by [RFC3986] section 2.3 343 (ALPHA, DIGIT, "-", ".", "_", "~") MUST NOT be encoded. All 344 other characters MUST be encoded. The two hexadecimal characters 345 used to represent encoded characters MUST be upper case. 347 2. The name of each parameter is concatenated to its corresponding 348 value using an "=" character (ASCII code 61) as separator, even 349 if the value is empty. 351 3. The name/value parameter pairs are sorted using ascending byte 352 value ordering. 354 4. The sorted parameters are concatenated together into a single 355 string by using an new line character (ASCII code 10) as 356 separator. 358 Note that the percent-encoding method described is different from the 359 encoding scheme used by the "application/x-www-form-urlencoded" 360 content-type (for example, it encodes space characters as "%20" 361 instead of the "+" character). It MAY be different from the percent- 362 encoding functions provided by web development frameworks (e.g. 363 encode different characters, use lower case hexadecimal characters). 365 For example, the HTTP request URI: 367 /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q 369 Contains the following (fully decoded) parameters used in the 370 normalized request sting: 372 +------+-------+ 373 | Name | Value | 374 +------+-------+ 375 | b5 | =%3D | 376 | a3 | a | 377 | c@ | | 378 | a2 | r b | 379 | c2 | | 380 | a3 | 2 q | 381 +------+-------+ 383 Note that the value of "b5" is "=%3D" and not "==". Both "c@" and 384 "c2" have empty values. While the encoding rules specified in this 385 specification for the purpose of constructing the normalized request 386 string exclude the use of a "+" character (ASCII code 43) to 387 represent an encoded space character (ASCII code 32), this practice 388 is widely used in "application/x-www-form-urlencoded" encoded values, 389 and MUST be properly decoded, as demonstrated by one of the "a3" 390 parameter instances (the "a3" parameter is used twice in this 391 request). 393 The parsed parameters are normalized as follows: 395 Escaped: 397 +------+----------+ 398 | Name | Value | 399 +------+----------+ 400 | b5 | %3D%253D | 401 | a3 | a | 402 | c%40 | | 403 | a2 | r%20b | 404 | c2 | | 405 | a3 | 2%20q | 406 +------+----------+ 408 Concatenated Pairs: 410 +-------------+ 411 | Name=Value | 412 +-------------+ 413 | b5=%3D%253D | 414 | a3=a | 415 | c%40= | 416 | a2=r%20b | 417 | c2= | 418 | a3=2%20q | 419 +-------------+ 421 Sorted: 423 +-------------+ 424 | Name=Value | 425 +-------------+ 426 | a2=r%20b | 427 | a3=2%20q | 428 | a3=a | 429 | b5=%3D%253D | 430 | c%40= | 431 | c2= | 432 +-------------+ 434 And concatenated together into a single string (the new line 435 separator character is represented by "\n" for display purposes 436 only): 438 a2=r%20b\n 439 a3=2%20q\n 440 a3=a\n 441 b5=%3D%253D\n 442 c%40=\n 443 c2=\n 445 3.2.2. hmac-sha-1 447 "hmac-sha-1" uses the HMAC-SHA1 algorithm as defined in [RFC2104]: 449 digest = HMAC-SHA1 (key, text) 451 Where: 453 text 454 is set to the value of the normalize request string as 455 described in Section 3.2.1. 457 key 458 is set to the access token shared-secret provided by the 459 authorization server. 461 digest 462 is used to set the value of the "signature" attribute, after 463 the result octet string is base64-encoded per [RFC2045] section 464 6.8. 466 3.2.3. hmac-sha-256 468 "hmac-sha-1" uses the HMAC algorithm as defined in [RFC2104] together 469 with the SHA-256 hash function defined in [NIST FIPS-180-3]: 471 digest = HMAC-SHA256 (key, text) 473 Where: 475 text 476 is set to the value of the normalize request string as 477 described in Section 3.2.1. 479 key 480 is set to the access token shared-secret provided by the 481 authorization server. 483 digest 484 is used to set the value of the "signature" attribute, after 485 the result octet string is base64-encoded per [RFC2045] section 486 6.8. 488 4. Verifying Requests 490 A servers receiving an authenticated request validates it by 491 performing the following REQUIRED steps: 493 1. Recalculate the request signature as described in Section 3.2 and 494 compare it to the value received from the client via the 495 "signature" attribute. 497 2. Ensure that the combination of nonce, timestamp, and access token 498 received from the client has not been used before in a previous 499 request (the server MAY reject requests with stale timestamps; 500 the determination of staleness is left up to the server to 501 define). 503 3. Verify the scope and status of the access token. 505 If the request fails verification, the server SHOULD respond with an 506 HTTP 401 (unauthorized) status code, and SHOULD include a token 507 scheme authentication challenge using the WWW-Authenticate header 508 field. The server MAY include further details about why the request 509 was rejected using the error attribute. 511 4.1. The WWW-Authenticate Response Header Field 513 If the protected resource request does not include authentication 514 credentials, contains an invalid access token, or is malformed, the 515 resource server MUST include the HTTP "WWW-Authenticate" response 516 header field. The "WWW-Authenticate" header field uses the framework 517 defined by [RFC2617] as follows: 519 challenge = "MAC" [ RWS 1#param ] 521 param = realm / error / error-desc / error-uri / auth-param 523 error = "error" "=" quoted-string 524 error-desc = "error_description" "=" quoted-string 525 error-uri = "error_uri" = <"> URI-reference <"> 527 Each attribute MUST NOT appear more than once. 529 If the protected resource request included an access token and failed 530 authentication, the resource server SHOULD include the "error" 531 attribute to provide the client with the reason why the access 532 request was declined. The parameter value is described in 533 Section 4.1.1. In addition, the resource server MAY include the 534 "error_description" attribute to provide a human-readable 535 explanation, and the "error-uri" attribute with an absolute URI 536 identifying a human-readable web page explaining the error. 538 For example, in response to a protected resource request without 539 authentication: 541 HTTP/1.1 401 Unauthorized 542 WWW-Authenticate: MAC realm="example" 544 And in response to a protected resource request with an 545 authentication attempt using an expired access token: 547 HTTP/1.1 401 Unauthorized 548 WWW-Authenticate: MAC realm="example" 549 error="invalid_token", 550 error_description="The access token expired" 552 4.1.1. Error Codes 554 When a request fails, the resource server responds using the 555 appropriate HTTP status code (typically, 400, 401, or 403), and 556 includes one of the following error codes in the response: 558 invalid_request 559 The request is missing a required parameter, includes an 560 unsupported parameter or parameter value, repeats the same 561 parameter, uses more than one method for including an access 562 token, or is otherwise malformed. The resource server SHOULD 563 respond with the HTTP 400 (Bad Request) status code. 565 invalid_token 566 The access token provided is expired, revoked, malformed, or 567 invalid for other reasons. The resource SHOULD respond with 568 the HTTP 401 (Unauthorized) status code. The client MAY 569 request a new access token and retry the protected resource 570 request. 572 insufficient_scope 573 The request requires higher privileges than provided by the 574 access token. The resource server SHOULD respond with the HTTP 575 403 (Forbidden) status code and MAY include the "scope" 576 attribute with the scope necessary to access the protected 577 resource. 579 If the request lacks any authentication information (i.e. the client 580 was unaware authentication is necessary or attempted using an 581 unsupported authentication method), the resource server SHOULD not 582 include an error code or other error information. 584 For example: 586 HTTP/1.1 401 Unauthorized 587 WWW-Authenticate: MAC realm="example" 589 5. Scheme Extensions 591 [[ TBD ]] 593 6. Use with OAuth 2.0 595 OAuth 2.0 ([I-D.ietf-oauth-v2]) defines a token-based authentication 596 framework in which third-party applications (clients) access 597 protected resources using access tokens. Access tokens are obtained 598 via the resource owners' authorization from an authorization server. 599 This specification defines the OAuth 2.0 MAC token type, as well as 600 type-specific token attributes. 602 This specification does not define methods for the client to 603 specifically request a MAC-type token from the authorization server. 604 Additionally, it does not include any discovery facilities for 605 identifying which HMAC algorithms are supported by a resource server, 606 or how the client may go about obtaining MAC access tokens. 608 6.1. Issuing MAC-Type Access Tokens 610 Authorization servers issuing MAC-type access tokens MUST include the 611 following parameters whenever a response includes the "access_token" 612 parameter: 614 secret 615 REQUIRED. The token shared secret used as the MAC algorithm 616 key. 618 algorithm 619 REQUIRED. The MAC algorithm used to calculate the request 620 signature. Value MUST be one of "hmac-sha-1", "hmac-sha-256", 621 or a registered extension algorithm name as described in 622 Section 5. 624 7. Security Considerations 626 As stated in [RFC2617], the greatest sources of risks are usually 627 found not in the core protocol itself but in policies and procedures 628 surrounding its use. Implementers are strongly encouraged to assess 629 how this protocol addresses their security requirements. 631 7.1. Secrets Transmission 633 This specification does not describe any mechanism for obtaining or 634 transmitting access token secrets. Methods used to obtain tokens 635 should ensure that these transmissions are protected using transport- 636 layer mechanisms such as TLS or SSL. 638 7.2. Confidentiality of Requests 640 While this protocol provides a mechanism for verifying the integrity 641 of requests, it provides no guarantee of request confidentiality. 642 Unless further precautions are taken, eavesdroppers will have full 643 access to request content. Servers should carefully consider the 644 kinds of data likely to be sent as part of such requests, and should 645 employ transport-layer security mechanisms to protect sensitive 646 resources. 648 7.3. Spoofing by Counterfeit Servers 650 This protocol makes no attempt to verify the authenticity of the 651 resource server. A hostile party could take advantage of this by 652 intercepting the client's requests and returning misleading or 653 otherwise incorrect responses. Service providers should consider 654 such attacks when developing services using this protocol, and should 655 require transport-layer security for any requests where the 656 authenticity of the resource server or of request responses is an 657 issue. 659 7.4. Plaintext Storage of Credentials 661 The access token shared-secret functions the same way passwords do in 662 traditional authentication systems. In order to compute the 663 signature, the server must have access to the secret in plaintext 664 form. This is in contrast, for example, to modern operating systems, 665 which store only a one-way hash of user credentials. 667 If an attacker were to gain access to these secrets - or worse, to 668 the server's database of all such secrets - he or she would be able 669 to perform any action on behalf of any resource owner. Accordingly, 670 it is critical that servers protect these secrets from unauthorized 671 access. 673 7.5. Entropy of Secrets 675 Unless a transport-layer security protocol is used, eavesdroppers 676 will have full access to authenticated requests and signatures, and 677 will thus be able to mount offline brute-force attacks to recover the 678 secret used. Authorization servers should be careful to assign 679 shared-secrets which are long enough, and random enough, to resist 680 such attacks for at least the length of time that the shared-secrets 681 are valid. 683 For example, if shared-secrets are valid for two weeks, authorization 684 servers should ensure that it is not possible to mount a brute force 685 attack that recovers the shared-secret in less than two weeks. Of 686 course, authorization servers are urged to err on the side of 687 caution, and use the longest secrets reasonable. 689 It is equally important that the pseudo-random number generator 690 (PRNG) used to generate these secrets be of sufficiently high 691 quality. Many PRNG implementations generate number sequences that 692 may appear to be random, but which nevertheless exhibit patterns or 693 other weaknesses which make cryptanalysis or brute force attacks 694 easier. Implementers should be careful to use cryptographically 695 secure PRNGs to avoid these problems. 697 7.6. Denial of Service / Resource Exhaustion Attacks 699 This specification includes a number of features which may make 700 resource exhaustion attacks against servers possible. For example, 701 this protocol requires servers to track used nonces. If an attacker 702 is able to use many nonces quickly, the resources required to track 703 them may exhaust available capacity. And again, this protocol can 704 require servers to perform potentially expensive computations in 705 order to verify the signature on incoming requests. An attacker may 706 exploit this to perform a denial of service attack by sending a large 707 number of invalid requests to the server. 709 Resource Exhaustion attacks are by no means specific to this 710 specification. However, implementers should be careful to consider 711 the additional avenues of attack that this protocol exposes, and 712 design their implementations accordingly. For example, entropy 713 starvation typically results in either a complete denial of service 714 while the system waits for new entropy or else in weak (easily 715 guessable) secrets. When implementing this protocol, servers should 716 consider which of these presents a more serious risk for their 717 application and design accordingly. 719 7.7. Coverage Limitations 721 The normalized request string has been designed to support the 722 authentication methods defined in this specification. Those 723 designing additional methods, should evaluated the compatibility of 724 the normalized request string with their security requirements. 725 Since the normalized request string does not cover the entire HTTP 726 request, servers should employ additional mechanisms to protect such 727 elements. 729 8. IANA Considerations 731 8.1. The "secret" OAuth Parameter 733 Parameter name: secret 735 Parameter usage location: The end-user authorization endpoint 736 response and the token endpoint response. 738 Change controller: IETF 740 Specification document(s): [[ this document ]] 742 Related information: None 744 8.2. The "algorithm" OAuth Parameter 746 Parameter name: algorithm 748 Parameter usage location: The end-user authorization endpoint 749 response and the token endpoint response. 751 Change controller: IETF 753 Specification document(s): [[ this document ]] 755 Related information: None 757 9. Acknowledgments 759 The author would like to thank James Manger for his suggestions, 760 feedback, and continued support. 762 Appendix A. Document History 764 [[ To be removed by the RFC editor before publication as an RFC. ]] 766 -01 768 o Changed parameters sorting to come after name=value string 769 construction. 771 o Added new line at the end of the normalized request string. 773 o Moved OAuth2 references to separate section. 775 o Added 'WWW-Authenticate' header definition. 777 o Fixed example header use of single quote. 779 -00 781 o Initial draft. 783 10. References 785 10.1. Normative References 787 [I-D.ietf-httpbis-p1-messaging] 788 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 789 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 790 "HTTP/1.1, part 1: URIs, Connections, and Message 791 Parsing", draft-ietf-httpbis-p1-messaging-08 (work in 792 progress), October 2009. 794 [I-D.ietf-oauth-v2] 795 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 796 2.0 Protocol Framework", draft-ietf-oauth-v2-11 (work in 797 progress), November 2010. 799 [NIST FIPS-180-3] 800 National Institute of Standards and Technology, "Secure 801 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 803 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 804 Extensions (MIME) Part One: Format of Internet Message 805 Bodies", RFC 2045, November 1996. 807 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 808 Hashing for Message Authentication", RFC 2104, 809 February 1997. 811 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 812 Requirement Levels", BCP 14, RFC 2119, March 1997. 814 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 815 Leach, P., Luotonen, A., and L. Stewart, "HTTP 816 Authentication: Basic and Digest Access Authentication", 817 RFC 2617, June 1999. 819 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 820 Resource Identifier (URI): Generic Syntax", STD 66, 821 RFC 3986, January 2005. 823 [W3C.REC-html401-19991224] 824 Hors, A., Jacobs, I., and D. Raggett, "HTML 4.01 825 Specification", World Wide Web Consortium 826 Recommendation REC-html401-19991224, December 1999, 827 . 829 10.2. Informative References 831 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 832 April 2010. 834 URIs 836 [1] 838 Author's Address 840 Eran Hammer-Lahav 841 Yahoo! 843 Email: eran@hueniverse.com 844 URI: http://hueniverse.com