idnits 2.17.1 draft-hammer-http-token-auth-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 date (February 3, 2010) is 5196 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) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-08 -- 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 3447 (Obsoleted by RFC 8017) Summary: 5 errors (**), 0 flaws (~~), 2 warnings (==), 2 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 February 3, 2010 5 Expires: August 7, 2010 7 HTTP Authentication: Token Access Authentication 8 draft-hammer-http-token-auth-01 10 Abstract 12 This document specifies the HTTP Token Access Authentication scheme. 14 Status of this Memo 16 This Internet-Draft is submitted to IETF in full conformance with the 17 provisions of BCP 78 and BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire on August 7, 2010. 37 Copyright Notice 39 Copyright (c) 2010 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.3. Notational Conventions . . . . . . . . . . . . . . . . . . 6 58 2. Making Requests . . . . . . . . . . . . . . . . . . . . . . . 7 59 3. Verifying Requests . . . . . . . . . . . . . . . . . . . . . . 8 60 4. The WWW-Authenticate Response Header . . . . . . . . . . . . . 8 61 4.1. The 'realm' Attribute . . . . . . . . . . . . . . . . . . 9 62 4.2. The 'coverage' Attribute . . . . . . . . . . . . . . . . . 9 63 4.3. The 'timestamp' Attribute . . . . . . . . . . . . . . . . 9 64 5. The Authorization Request Header . . . . . . . . . . . . . . . 10 65 5.1. The 'token' Attribute . . . . . . . . . . . . . . . . . . 10 66 5.2. The 'coverage' Attribute . . . . . . . . . . . . . . . . . 10 67 5.3. The 'nonce' Attribute . . . . . . . . . . . . . . . . . . 10 68 5.4. The 'timestamp' Attribute . . . . . . . . . . . . . . . . 10 69 5.5. The 'auth' Attribute . . . . . . . . . . . . . . . . . . . 11 70 6. The Authentication-Error Response Header . . . . . . . . . . . 11 71 6.1. The 'error-code' attribute . . . . . . . . . . . . . . . . 11 72 6.2. The 'error-info' attribute . . . . . . . . . . . . . . . . 11 73 6.3. The 'error-message' attribute . . . . . . . . . . . . . . 11 74 7. Authentication Methods . . . . . . . . . . . . . . . . . . . . 11 75 7.1. The 'none' Method . . . . . . . . . . . . . . . . . . . . 12 76 7.2. The 'hmac-sha-1' Method . . . . . . . . . . . . . . . . . 12 77 7.3. The 'hmac-sha-256' Method . . . . . . . . . . . . . . . . 13 78 7.4. The 'rsassa-pkcs1-v1.5-sha-256' Method . . . . . . . . . . 13 79 8. Coverage Methods . . . . . . . . . . . . . . . . . . . . . . . 14 80 8.1. The 'base' Method . . . . . . . . . . . . . . . . . . . . 14 81 8.1.1. String Construction . . . . . . . . . . . . . . . . . 15 82 8.2. The 'base+body-hmac-sha-256' Method . . . . . . . . . . . 15 83 9. Scheme Extensions . . . . . . . . . . . . . . . . . . . . . . 16 84 10. Security Considerations . . . . . . . . . . . . . . . . . . . 16 85 10.1. Credentials Transmission . . . . . . . . . . . . . . . . . 16 86 10.2. Confidentiality of Requests . . . . . . . . . . . . . . . 16 87 10.3. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 16 88 10.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 17 89 10.5. Scoping of Access Requests . . . . . . . . . . . . . . . . 17 90 10.6. Entropy of Secrets . . . . . . . . . . . . . . . . . . . . 17 91 10.7. Denial of Service / Resource Exhaustion Attacks . . . . . 18 92 10.8. Coverage Limitations . . . . . . . . . . . . . . . . . . . 18 93 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 94 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 95 Appendix A. Document History . . . . . . . . . . . . . . . . . . 19 96 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 97 13.1. Normative References . . . . . . . . . . . . . . . . . . . 19 98 13.2. Informative References . . . . . . . . . . . . . . . . . . 20 99 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 101 1. Introduction 103 [[ This draft is submitted for the consideration of the OAuth Working 104 Group to be adopted as an official working group item per its current 105 charter. It is presented in its raw form to assist in facilitating a 106 more effective working group conversation and should not be 107 considered a complete proposal. Please discuss this draft on the 108 oauth@ietf.org [1] mailing list. ]] 110 With the growing use of distributed web services and cloud computing, 111 clients need to allow other parties access to the resources they 112 control. When granting access, clients should not be required to 113 share their credentials (typically a username and password). Clients 114 should also have the ability to restrict access to a limited subset 115 of the resources they control or limit access to the methods 116 supported by these resources. These goals require new classes of 117 authentication credentials. 119 The HTTP Basic and Digest Access authentication schemes defined by 120 [RFC2617], enable clients to make authenticated HTTP requests by 121 using a username (or userid) and a password. In most cases, the 122 client uses a single set of credentials to access all the resources 123 it controls which are hosted by the server. 125 While the Basic and Digest schemes can be used to send credentials 126 other than a username and password, their wide deployment and well- 127 established behavior in user-agents preclude them from being used 128 with other classes of credentials. Extending these schemes to 129 support new classes would require an impractical change to their 130 existing deployment. 132 The Token Access Authentication scheme provides a method for making 133 authenticated HTTP requests using a token - an identifier used to 134 denote an access grant with specific scope, duration, cryptographic 135 properties, and other attributes. Tokens can issued by the server, 136 self-issued by the client, or issued by a third-party. 138 The token scheme supports an extensible set of credential classes, 139 authentication methods (e.g. cryptographic algorithm), and 140 authentication coverage (the elements of the HTTP request - such as 141 the request URI or entity-body - covered by the authentication). 143 This specification defines four token authentication methods to 144 support the most common use cases and describes their security 145 properties. The methods through which clients obtain tokens 146 supporting these methods are beyond the scope of this specification. 147 The OAuth protocol [I-D.ietf-oauth-web-delegation] defines one such 148 set of methods for obtaining token credentials. 150 1.1. Terminology 152 client 153 An HTTP client (per [RFC2616]) capable of making Token- 154 authenticated requests (Section 2). 156 server 157 An HTTP server (per [RFC2616]) capable of accepting Token- 158 authenticated requests (Section 2). 160 protected resource 161 An access-restricted resource (per [RFC2616]) hosted by the 162 server and accessible by making a Token-authenticated request 163 (Section 2). 165 token credentials 166 A set of a unique identifier (token) and an authentication 167 method with an OPTIONAL shared secret (symmetric or 168 asymmetric), as well as other attributes (e.g. duration, 169 scope), used by the client to make authenticated requests. 171 normalized request string 172 A string representing various elements of the HTTP request, 173 normalized and concatenated together. The elements included in 174 the normalize request string are determined by the 175 authentication coverage supported by the server. 177 1.2. Example 179 The following HTTP request: 181 GET /resource/1 HTTP/1.1 182 Host: example.com 184 returns the following authentication challenge: 186 HTTP/1.1 401 Unauthorized 187 WWW-Authenticate: Token realm="http://example.com/", 188 coverage="base base+body-sha-256", 189 timestamp="137131190" 191 The response means the server is expecting the client to authenticate 192 using the token scheme, with a set of token credentials issued for 193 the "http://example.com/" realm. The server supports the "base" and 194 "base+body-sha-256" coverage methods which means the client must sign 195 the base request components (e.g. host, port, request URI), and may 196 also sign the request payload (entity-body). It also provides its 197 current time to assist the client in synchronizing its clock with the 198 server's clock for the purpose of producing a unique nonce value 199 (used with some of the authentication methods). 201 The client has previously obtained a set of token credentials for 202 accessing resources in the "http://example.com/" realm. The 203 credentials issued to the client by the server included the following 204 attributes: 206 token: h480djs93hd8 208 method: hmac-sha-1 210 secret: 489dks293j39 212 expiration: 137217600 214 The client attempts the HTTP request again, this time using the token 215 credentials issued by the server earlier to authenticate. The client 216 uses the "base" coverage method and applies the "hmac-sha-1" 217 authentication method as dictated by the token credentials. 219 GET /resource/1 HTTP/1.1 220 Host: example.com 221 Authorization: Token token="h480djs93hd8", 222 coverage="base", 223 timestamp="137131200", 224 nonce="dj83hs9s", 225 auth="djosJKDKJSD8743243/jdk33klY=" 227 to which the server respond with the requested resource 228 representation after validating the request. 230 1.3. Notational Conventions 232 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 233 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 234 document are to be interpreted as described in [RFC2119]. 236 This document uses the Augmented Backus-Naur Form (ABNF) notation of 237 [I-D.ietf-httpbis-p1-messaging]. Additionally, the following rules 238 are included from [RFC2617]: realm, auth-param. 240 2. Making Requests 242 The client makes authenticated requests by calculating the values of 243 a set of attributes and adding them to the HTTP request using the 244 Authorization header field (Section 5). Authenticated request can be 245 sent either directly (without first receiving a challenge), or in 246 response to an authentication challenge. 248 To make an authenticated request, the client obtains information 249 about the attributes supported by the server. This information is 250 provided by the server via the WWW-Authenticate header field 251 (Section 4). The client SHOULD only send an authenticated request to 252 the server (without first receiving a challenge) if it has prior 253 knowledge of the attributes supported by server. 255 The client chooses an available token suitable for accessing the 256 resource realm as well as a a supported authentication coverage. The 257 methods through which the client obtains a valid token, or the 258 criteria used to choose a token if more than one is available are 259 beyond the scope of this specification. 261 Once the client selects the appropriate token credentials it proceeds 262 to: 264 1. Assign values based on its selection to the following attributes: 266 * "token" 268 * "coverage" 270 2. If the client uses a coverage method other than "none" it MUST 271 assign values to the following attributes: 273 * "nonce" 275 * "timestamp" 277 3. Assigns value to any additional method-specific, or coverage- 278 specific attributes as defined by protocol extensions. 280 4. If the client uses a coverage method other than "none" it 281 constructs the normalized request string based on the selected 282 coverage as described in Section 8. 284 5. Calculates the value of the "auth" attribute as defined by the 285 selected authentication method. 287 6. Adds the assigned attributes to the request via the Authorization 288 header field (Section 5). 290 7. Sends the authenticated HTTP request to the server. 292 3. Verifying Requests 294 A servers receiving an authenticated request validates it by 295 performing the following REQUIRED steps: 297 1. Verify that the token used by the client as well as the coverage 298 method matches the server's requirements. 300 2. If the client used a coverage method other than "none", construct 301 the normalized request string based on the selected coverage as 302 described in Section 8. 304 3. If the client used an authentication method other than "none", 305 recalculate the value of the "auth" attribute as described in 306 Section 7 and compare it to the value received from the client 307 via the "auth" attribute. 309 4. If the client used a coverage method other than "none", ensure 310 that the combination of nonce, timestamp, and token received from 311 the client has not been used before in a previous request (the 312 server MAY reject requests with stale timestamps; the 313 determination of staleness is left up to the server to define). 315 5. Verify the scope and status of the client credentials as 316 represented by the token. 318 If the request fails verification, the server SHOULD respond with an 319 HTTP 401 (unauthorized) status code, and SHOULD include a token 320 scheme authentication challenge using the WWW-Authenticate header 321 field (Section 6). The server MAY include further details about why 322 the request was rejected using the Authorization-Error header field 323 (Section 6). 325 4. The WWW-Authenticate Response Header 327 A server receiving a request for a protected resource without a valid 328 Authorization header field (Section 5) MUST respond with a 401 status 329 code (Unauthorized), and includes at least one "WWW-Authenticate" 330 header field including a token scheme challenge. 332 The "WWW-Authenticate" header field uses the framework defined by 334 [RFC2617] as follows: 336 challenge = "Token" RWS token-challenge 338 token-challenge = realm 339 CS coverage-list 340 [ CS timestamp ] 342 coverage-list = "coverage" "=" <"> 1#coverage-name <"> 343 coverage-name = "none" / 344 "base" / 345 "base+body-sha-256" / 346 token 348 timestamp = "timestamp" "=" <"> 1*DIGIT <"> 350 CS = OWF "," OWF 352 4.1. The 'realm' Attribute 354 4.2. The 'coverage' Attribute 356 The list of authentication coverage names supported by the server, 357 provided as a space-delimited list. If omitted, the attribute 358 defaults to "base". Authentication coverage is described in 359 Section 8. 361 4.3. The 'timestamp' Attribute 363 Signature-based and hash-based authentication methods use timestamps 364 in combination with unique nonce values to protect against replay 365 attacks when used over an unsecure channel. 367 The timestamp attribute is used by the server to publish its current 368 time, enabling clients to synchronize their close with the server. 369 The timestamp value is the current time expressed in the number of 370 seconds since January 1, 1970 00:00:00 GMT, and MUST be a positive 371 integer. 373 To avoid the need to retain an infinite number of nonce values for 374 future checks, servers MAY choose to restrict the time period after 375 which a request with an old timestamp is rejected. Servers applying 376 such a restriction SHOULD provide their current time to the client 377 either in every challenge or when a request fails due to a timestamp 378 outside the allowed window. 380 5. The Authorization Request Header 382 A client making a request for a protected resource either directly, 383 or in retrying a request after receiving a 401 status code 384 (Unauthorized) with a token challenge, MUST include at least one 385 "Authorization" header field including token scheme credentials. 387 The "Authorization" header field uses the framework defined by 388 [RFC2617] as follows: 390 credentials = "Token" RWS token-response 392 token-response = token-id 393 CS coverage 394 [ CS nonce ] 395 [ CS timestamp ] 396 [ CS auth ] 398 token-id = "token" "=" <"> token <"> 399 coverage = "coverage" "=" <"> coverage-name <"> 400 nonce = "nonce" "=" <"> token <"> 401 auth = "auth" "=" <"> token <"> 403 5.1. The 'token' Attribute 405 The value used to identify the set of token credentials used by the 406 client to authenticate. The token identifier can be an opaque string 407 or use a well-defined internal structure. 409 5.2. The 'coverage' Attribute 411 The name of the authentication coverage method used by the client to 412 make the request. If the attribute is omitted, its value defaults to 413 "base". 415 5.3. The 'nonce' Attribute 417 A random string, uniquely generated by the client to allow the server 418 to verify that a request has never been made before and helps prevent 419 replay attacks when requests are made over a non-secure channel. The 420 nonce value MUST be unique across all requests with the same 421 timestamp and token combinations. 423 5.4. The 'timestamp' Attribute 425 The timestamp value is the current time expressed in the number of 426 seconds since January 1, 1970 00:00:00 GMT, and MUST be a positive 427 integer. 429 5.5. The 'auth' Attribute 431 The output of the authentication method function after applying it to 432 the selected coverage as described in Section 7. 434 6. The Authentication-Error Response Header 436 A server receiving a request for a protected resource with an invalid 437 Authorization header field (Section 5) MAY includes the 438 "Authentication-Error" header field providing the client with 439 information to help it successfully authenticate with the server. 441 The "Authentication-Error" header field is defined as follows: 443 Authentication-Error = "Authentication-Error" ":" 444 OWS #1error-param 446 error-param = error-code / 447 error-info / 448 error-message / 449 auth-param 451 error-code = "error-code" "=" <"> token <"> 452 error-info = "error-info" "=" <"> token <"> 453 error-message = "error-message" "=" quoted-string 455 6.1. The 'error-code' attribute 457 6.2. The 'error-info' attribute 459 6.3. The 'error-message' attribute 461 7. Authentication Methods 463 In order for the server to verify the authenticity of the request and 464 prevent unauthorized access, the client must prove it is the rightful 465 owner of the credentials. This is accomplished using the 466 authentication method associated with the token. 468 This specification provides three methods for the client to prove its 469 rightful ownership of the credentials: "hmac-sha-1", "hmac-sha-256", 470 and "rsassa-pkcs1-v1.5-sha-256". In addition, the "none" method is 471 defined to allow the use of bearer token which does not utilizes any 472 cryptographic means. 474 method-name = "none" / 475 "hmac-sha-1" / 476 "hmac-sha-256" / 477 "rsassa-pkcs1-v1.5-sha-256" / 478 token 480 The authentication process does not change the request or its 481 parameters, with the exception of the "auth" attribute. 483 7.1. The 'none' Method 485 The "none" method does not employ a cryptographic algorithm and does 486 not provide any security on its own. Servers utilizing this method 487 use the token identifier as a bearer token, relying solely on the 488 value of the token identifier to authenticate the client. 490 The "nonce", "timestamp", and "auth" attributes are not used, and 491 SHOULD NOT be included in authenticated requests. The "coverage" 492 attribute MUST be set to "none" but MAY be omitted from the request. 493 Nevertheless, these attributes MUST be included in the normalized 494 request string together with any other authentication attributes. 496 7.2. The 'hmac-sha-1' Method 498 The "hmac-sha-1" authentication method uses the HMAC-SHA1 algorithm 499 as defined in [RFC2104]: 501 digest = HMAC-SHA1 (key, text) 503 The HMAC-SHA1 function variables are used in following way: 505 text 506 is set to the value of the normalize request string as 507 described in Section 8. 509 key 510 is set to the shared-secret associated with the token. 512 digest 513 is used to set the value of the "auth" attribute, after the 514 result octet string is base64-encoded per [RFC2045] section 515 6.8. 517 7.3. The 'hmac-sha-256' Method 519 The "hmac-sha-256" authentication method uses the HMAC algorithm as 520 defined in [RFC2104] together with the SHA-256 hash function defined 521 in [NIST FIPS-180-3]: 523 digest = HMAC-SHA256 (key, text) 525 The HMAC-SHA256 function variables are used in following way: 527 text 528 is set to the value of the normalize request string as 529 described in Section 8. 531 key 532 is set to the shared-secret associated with the token. 534 digest 535 is used to set the value of the "auth" attribute, after the 536 result octet string is base64-encoded per [RFC2045] section 537 6.8. 539 7.4. The 'rsassa-pkcs1-v1.5-sha-256' Method 541 The "rsassa-pkcs1-v1.5-sha-256" signature method uses the RSASSA- 542 PKCS1-v1_5 signature algorithm as defined in [RFC3447] section 8.2 543 (also known as PKCS#1), using SHA-256 as the hash function as defined 544 in [NIST FIPS-180-3] for EMSA-PKCS1-v1_5. 546 The normalized request string is signed using the RSA private key 547 associated with the token as defined in [RFC3447] section 8.2.1: 549 S = RSASSA-PKCS1-V1_5-SIGN (K, M) 551 Where: 553 K 554 is set to the RSA private key associated with the token, 556 M 557 is set to the value of the normalized request string described 558 in Section 8, and 560 S 561 is the result signature used to set the value of the "auth" 562 attribute, after the result octet string is base64-encoded per 563 [RFC2045] section 6.8. 565 The server verifies the signature per [RFC3447] section 8.2.2: 567 RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, S) 569 Where: 571 (n, e) 572 is set to the RSA public key associated with the token, 574 M 575 is set to the value of the normalized request string described 576 in Section 8, and 578 S 579 is set to the octet string value of the "auth" attribute 580 received from the client. 582 8. Coverage Methods 584 The normalized request string is a consistent, reproducible 585 concatenation of several of the HTTP request elements into a single 586 string. The string is used as an input to the authentication methods 587 with the exception of "none". 589 8.1. The 'base' Method 591 When using the "base" method, the normalized request string includes 592 the following components of the HTTP request: 594 o The HTTP request method (e.g. "GET", "POST", etc.). 596 o The authority as declared by the HTTP "Host" request header. 598 o The request resource URI. 600 o The Authorization header field (Section 5) attributes, with the 601 exception of the "auth" attribute. 603 The "base" normalized request string does not cover the entire HTTP 604 request. Most notably, it does not include the entity-body or most 605 HTTP entity-headers. It is important to note that the server cannot 606 verify the authenticity of the excluded request elements without 607 using additional protections such as SSL/TLS or other methods. 609 8.1.1. String Construction 611 The normalized request string is constructed by concatenating 612 together, in order, the following HTTP request elements: 614 1. The HTTP request method in uppercase. For example: "HEAD", 615 "GET", "POST", etc. 617 2. A "," character (ASCII code 44). 619 3. The hostname, colon-separated (ASCII code 58) from the TCP port 620 used to make the request as included in the HTTP request "Host" 621 header field. The port MUST be included even if it is not 622 included in the "Host" header field (i.e. the default port for 623 the scheme). 625 4. A "," character (ASCII code 44). 627 5. Any authentication attribute, with the exception of the "auth", 628 which is assigned a value (including default values), are added 629 to the normalized request string as follows: 631 1. The name of each parameter is concatenated to its 632 corresponding value using an "=" character (ASCII code 61) as 633 separator, even if the value is empty. 635 2. The name/value pairs are sorted using ascending byte value 636 ordering. 638 3. The sorted name/value pairs are concatenated together into a 639 single string by using a "," character (ASCII code 44) as 640 separator. 642 6. A "," character (ASCII code 44). 644 7. The request resource URI. 646 8.2. The 'base+body-hmac-sha-256' Method 648 The "base+body-hmac-sha-256" method added the request entity-body to 649 the elements included in the normalized request string. It does not 650 include the entity-body directly in the normalized string. Instead, 651 it calculates the hash value of the entity-body using the SHA-256 652 hash function defined in [NIST FIPS-180-3]. 654 The normalized request string is constructed following the same 655 process defined in Section 8.1.1, with the following addition: 657 o Before constructing the string, the entity-body hash is calculated 658 by applying the SHA-256 hash function on the raw entity-body 659 content. 661 o The hash value is added to the list of authentication attributes 662 by assigning its value to the "body-hash" attribute name. This is 663 done prior to the attributes being sorted and added to the string. 665 o The "body-hash" attribute is only included in the normalized 666 request string and is not added to the Authorization header field 667 (Section 5). 669 9. Scheme Extensions 671 10. Security Considerations 673 As stated in [RFC2617], the greatest sources of risks are usually 674 found not in the core protocol itself but in policies and procedures 675 surrounding its use. Implementers are strongly encouraged to assess 676 how this protocol addresses their security requirements. 678 10.1. Credentials Transmission 680 This specification does not describe any mechanism for obtaining or 681 transmitting raw tokens credentials. Methods used to obtain tokens 682 should ensure that these transmissions are protected using transport- 683 layer mechanisms such as TLS or SSL. 685 10.2. Confidentiality of Requests 687 While this protocol provides a mechanism for verifying the integrity 688 of requests, it provides no guarantee of request confidentiality. 689 Unless further precautions are taken, eavesdroppers will have full 690 access to request content. Servers should carefully consider the 691 kinds of data likely to be sent as part of such requests, and should 692 employ transport-layer security mechanisms to protect sensitive 693 resources. 695 10.3. Spoofing by Counterfeit Servers 697 This protocol makes no attempt to verify the authenticity of the 698 server. A hostile party could take advantage of this by intercepting 699 the client's requests and returning misleading or otherwise incorrect 700 responses. Service providers should consider such attacks when 701 developing services using this protocol, and should require 702 transport-layer security for any requests where the authenticity of 703 the server or of request responses is an issue. 705 10.4. Plaintext Storage of Credentials 707 When used with a symmetric shared-secret authentication method, the 708 token shared-secret function the same way passwords do in traditional 709 authentication systems. In order to compute the signatures used in 710 methods, the server must have access to these secrets in plaintext 711 form. This is in contrast, for example, to modern operating systems, 712 which store only a one-way hash of user credentials. 714 If an attacker were to gain access to these secrets - or worse, to 715 the server's database of all such secrets - he or she would be able 716 to perform any action on behalf of any resource owner. Accordingly, 717 it is critical that servers protect these secrets from unauthorized 718 access. 720 10.5. Scoping of Access Requests 722 By itself, this protocol does not provide any method for scoping the 723 access rights granted to a client. However, most applications do 724 require greater granularity of access rights. For example, servers 725 may wish to make it possible to grant access to some protected 726 resources but not others, or to grant only limited access (such as 727 read-only access) to those protected resources. 729 When implementing this protocol, servers should consider the types of 730 access resource owners may wish to grant clients, and should provide 731 mechanisms to do so. Servers should also take care to ensure that 732 resource owners understand the access they are granting, as well as 733 any risks that may be involved. 735 10.6. Entropy of Secrets 737 Unless a transport-layer security protocol is used, eavesdroppers 738 will have full access to authenticated requests and signatures, and 739 will thus be able to mount offline brute-force attacks to recover the 740 credentials used. Servers should be careful to assign shared-secrets 741 which are long enough, and random enough, to resist such attacks for 742 at least the length of time that the shared-secrets are valid. 744 For example, if shared-secrets are valid for two weeks, servers 745 should ensure that it is not possible to mount a brute force attack 746 that recovers the shared-secret in less than two weeks. Of course, 747 servers are urged to err on the side of caution, and use the longest 748 secrets reasonable. 750 It is equally important that the pseudo-random number generator 751 (PRNG) used to generate these secrets be of sufficiently high 752 quality. Many PRNG implementations generate number sequences that 753 may appear to be random, but which nevertheless exhibit patterns or 754 other weaknesses which make cryptanalysis or brute force attacks 755 easier. Implementers should be careful to use cryptographically 756 secure PRNGs to avoid these problems. 758 10.7. Denial of Service / Resource Exhaustion Attacks 760 This specification includes a number of features which may make 761 resource exhaustion attacks against servers possible. For example, 762 this protocol requires servers to track used nonces. If an attacker 763 is able to use many nonces quickly, the resources required to track 764 them may exhaust available capacity. And again, this protocol can 765 require servers to perform potentially expensive computations in 766 order to verify the signature on incoming requests. An attacker may 767 exploit this to perform a denial of service attack by sending a large 768 number of invalid requests to the server. 770 Resource Exhaustion attacks are by no means specific to this 771 specification. However, implementers should be careful to consider 772 the additional avenues of attack that this protocol exposes, and 773 design their implementations accordingly. For example, entropy 774 starvation typically results in either a complete denial of service 775 while the system waits for new entropy or else in weak (easily 776 guessable) secrets. When implementing this protocol, servers should 777 consider which of these presents a more serious risk for their 778 application and design accordingly. 780 10.8. Coverage Limitations 782 The normalized request string has been designed to support the 783 authentication methods defined in this specification. Those 784 designing additional methods, should evaluated the compatibility of 785 the normalized request string with their security requirements. 786 Since the normalized request string does not cover the entire HTTP 787 request, servers should employ additional mechanisms to protect such 788 elements. 790 11. IANA Considerations 791 12. Acknowledgments 793 The author would like to thank Richard Barnes, Breno de Medeiros, 794 Brian Eaton, Ben Laurie, Mark Nottingham, John Panzer, and Peter 795 Saint-Andre for their suggestions, feedback, and continued support. 797 Appendix A. Document History 799 [[ To be removed by the RFC editor before publication as an RFC. ]] 801 -01 803 o Simplified challenge, moving the supported authentication methods 804 to the token definition, as well as using the 'realm' parameter as 805 defined by RFC 2617 instead of the 'class' parameter (which has 806 been dropped). 808 -00 810 o Initial (incomplete) draft. 812 13. References 814 13.1. Normative References 816 [I-D.ietf-httpbis-p1-messaging] 817 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 818 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 819 "HTTP/1.1, part 1: URIs, Connections, and Message 820 Parsing", draft-ietf-httpbis-p1-messaging-08 (work in 821 progress), October 2009. 823 [NIST FIPS-180-3] 824 National Institute of Standards and Technology, "Secure 825 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 827 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 828 Extensions (MIME) Part One: Format of Internet Message 829 Bodies", RFC 2045, November 1996. 831 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 832 Hashing for Message Authentication", RFC 2104, 833 February 1997. 835 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 836 Requirement Levels", BCP 14, RFC 2119, March 1997. 838 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 839 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 840 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 842 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 843 Leach, P., Luotonen, A., and L. Stewart, "HTTP 844 Authentication: Basic and Digest Access Authentication", 845 RFC 2617, June 1999. 847 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 848 Standards (PKCS) #1: RSA Cryptography Specifications 849 Version 2.1", RFC 3447, February 2003. 851 13.2. Informative References 853 [I-D.ietf-oauth-web-delegation] 854 Hammer-Lahav, E., "The OAuth Protocol: Web Delegation", 855 draft-ietf-oauth-web-delegation-01 (work in progress), 856 July 2009. 858 URIs 860 [1] 862 Author's Address 864 Eran Hammer-Lahav 865 Yahoo! 867 Email: eran@hueniverse.com 868 URI: http://hueniverse.com