idnits 2.17.1 draft-hammer-http-token-auth-00.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 (December 7, 2009) is 5252 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 December 7, 2009 5 Expires: June 10, 2010 7 HTTP Authentication: Token Access Authentication 8 draft-hammer-http-token-auth-00 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 June 10, 2010. 37 Copyright Notice 39 Copyright (c) 2009 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 . . . . . . . . . . . . . . . . . . . . . . . 6 59 3. Verifying Requests . . . . . . . . . . . . . . . . . . . . . . 7 60 4. The WWW-Authenticate Response Header . . . . . . . . . . . . . 8 61 4.1. The 'class' Attribute . . . . . . . . . . . . . . . . . . 9 62 4.2. The 'method' Attribute . . . . . . . . . . . . . . . . . . 9 63 4.3. The 'coverage' Attribute . . . . . . . . . . . . . . . . . 9 64 4.4. The 'timestamp' Attribute . . . . . . . . . . . . . . . . 10 65 5. The Authorization Request Header . . . . . . . . . . . . . . . 10 66 5.1. The 'token' Attribute . . . . . . . . . . . . . . . . . . 11 67 5.2. The 'class' Attribute . . . . . . . . . . . . . . . . . . 11 68 5.3. The 'method' Attribute . . . . . . . . . . . . . . . . . . 11 69 5.4. The 'coverage' Attribute . . . . . . . . . . . . . . . . . 11 70 5.5. The 'nonce' Attribute . . . . . . . . . . . . . . . . . . 11 71 5.6. The 'timestamp' Attribute . . . . . . . . . . . . . . . . 11 72 5.7. The 'auth' Attribute . . . . . . . . . . . . . . . . . . . 11 73 6. The Authentication-Error Response Header . . . . . . . . . . . 11 74 6.1. The 'error-code' attribute . . . . . . . . . . . . . . . . 12 75 6.2. The 'error-info' attribute . . . . . . . . . . . . . . . . 12 76 6.3. The 'error-message' attribute . . . . . . . . . . . . . . 12 77 7. Authentication Methods . . . . . . . . . . . . . . . . . . . . 12 78 7.1. The 'none' Method . . . . . . . . . . . . . . . . . . . . 12 79 7.2. The 'hmac-sha-1' Method . . . . . . . . . . . . . . . . . 13 80 7.3. The 'hmac-sha-256' Method . . . . . . . . . . . . . . . . 13 81 7.4. The 'rsassa-pkcs1-v1.5-sha-256' Method . . . . . . . . . . 14 82 8. Coverage Methods . . . . . . . . . . . . . . . . . . . . . . . 15 83 8.1. The 'base' Method . . . . . . . . . . . . . . . . . . . . 15 84 8.1.1. String Construction . . . . . . . . . . . . . . . . . 15 85 8.2. The 'base+body-hmac-sha-256' Method . . . . . . . . . . . 16 86 9. Scheme Extensions . . . . . . . . . . . . . . . . . . . . . . 16 87 10. Security Considerations . . . . . . . . . . . . . . . . . . . 16 88 10.1. Credentials Transmission . . . . . . . . . . . . . . . . . 17 89 10.2. Confidentiality of Requests . . . . . . . . . . . . . . . 17 90 10.3. Spoofing by Counterfeit Servers . . . . . . . . . . . . . 17 91 10.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 17 92 10.5. Scoping of Access Requests . . . . . . . . . . . . . . . . 17 93 10.6. Entropy of Secrets . . . . . . . . . . . . . . . . . . . . 18 94 10.7. Denial of Service / Resource Exhaustion Attacks . . . . . 18 95 10.8. Coverage Limitations . . . . . . . . . . . . . . . . . . . 19 97 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 98 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 99 Appendix A. Document History . . . . . . . . . . . . . . . . . . 19 100 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 101 13.1. Normative References . . . . . . . . . . . . . . . . . . . 19 102 13.2. Informative References . . . . . . . . . . . . . . . . . . 20 103 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 105 1. Introduction 107 [[ This draft is submitted for the consideration of the OAuth Working 108 Group to be adopted as an official working group item per its current 109 charter. It is presented in its raw form to assist in facilitating a 110 more effective working group conversation and should not be 111 considered a complete proposal. Please discuss this draft on the 112 oauth@ietf.org [1] mailing list. ]] 114 With the growing use of distributed web services and cloud computing, 115 clients need to allow other parties access to the resources they 116 control. When granting access, clients should not be required to 117 share their credentials (typically a username and password), and 118 should have the ability to restrict access to a limited subset of the 119 resources they control or the access methods supported by these 120 resources. These goals require new classes of authentication 121 credentials. 123 The HTTP Basic and Digest Access authentication schemes defined by 124 [RFC2617], enable clients to make authenticated HTTP requests by 125 using a username (or userid) and a password. In most cases, the 126 client uses a single set of credentials to access all the resources 127 it controls which are hosted by the server. 129 While the Basic and Digest schemes can be used to send credentials 130 other than a username and password, their wide deployment and well- 131 established behavior in user-agents preclude them from being used 132 with other classes of credentials. Extending these schemes to 133 support new classes would require impractical changes to their 134 existing deployment. 136 The Token Access Authentication scheme provides a method for making 137 authenticated HTTP requests using a token - an identifier used to 138 denote an access grant with specific scope, duration, cryptographic 139 properties, and other attributes. Tokens can issued by the server, 140 self-issued by the client, or issued by a third party. 142 The token scheme support an extensible set of credential classes, by 143 enabling the server to declare the classes it supports. Token 144 classes determine how tokens are obtained and the context in which 145 they can be used. It also supports an extensible set of 146 authentication methods and authentication coverage (the elements of 147 the HTTP request such as the request URI or entity-body included in 148 the authentication process). 150 This specification defines four token authentication methods to 151 support the most common use cases and describes their security 152 properties. The methods through which clients obtain tokens 153 supporting these methods are beyond the scope of this specification. 154 The OAuth protocol [I-D.ietf-oauth-web-delegation] defines one such 155 set of methods for obtaining oauth-class token credentials. 157 1.1. Terminology 159 client 160 An HTTP client (per [RFC2616]) capable of making Token- 161 authenticated requests (Section 2). 163 server 164 An HTTP server (per [RFC2616]) capable of accepting Token- 165 authenticated requests (Section 2). 167 protected resource 168 An access-restricted resource (per [RFC2616]) hosted by the 169 server and accessible by making a Token-authenticated request 170 (Section 2). 172 token credentials 173 A set of a unique identifier (token) and an authentication 174 method with an OPTIONAL shared secret (symmetric or 175 asymmetric), as well as other attributes (e.g. class, duration, 176 scope), used by the client to make authenticated requests. 178 normalized request string 179 A string representing various elements of the HTTP request, 180 normalized and concatenated together. The elements included in 181 the normalize request string are determined by the 182 authentication coverage supported by the server. 184 1.2. Example 186 The following HTTP request: 188 GET /resource/1 HTTP/1.1 189 Host: example.com 191 returns the following authentication challenge: 193 HTTP/1.1 401 Unauthorized 194 WWW-Authenticate: Token class="oauth", 195 methods="hmac-sha-1 hmac-sha-256", 196 timestamp="137131190" 198 This means the server is expecting an "oauth" class token using 199 either the "hmac-sha-1" or "hmac-sha-256" authentication methods. It 200 also provides its current time to assist the client in synchronizing 201 its clock with the server's clock for the purpose of producing a 202 unique nonce value. 204 The client attempts the HTTP request again, this time using a set of 205 token credentials supporting the "hmac-sha-1" method issued by the 206 server earlier to authenticate: 208 GET /resource/1 HTTP/1.1 209 Host: example.com 210 Authorization: Token token="h480djs93hd8", 211 class="oauth", 212 method="hmac-sha-1", 213 timestamp="137131200", 214 nonce="dj83hs9s", 215 auth="djosJKDKJSD8743243/jdk33klY=" 217 to which the server respond with the requested resource 218 representation after validating the request. 220 1.3. Notational Conventions 222 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 223 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 224 document are to be interpreted as described in [RFC2119]. 226 This document uses the Augmented Backus-Naur Form (ABNF) notation of 227 [I-D.ietf-httpbis-p1-messaging]. Additionally, the following rules 228 are included from [RFC2617]: realm, auth-param. 230 2. Making Requests 232 The client makes authenticated requests by calculating the values of 233 a set of attributes and adding them to the HTTP request using the 234 Authorization header field (Section 5). Authenticated request can be 235 sent either directly (without first receiving a challenge), or in 236 response to an authentication challenge. 238 To make an authenticated request, the client obtains information 239 about the attributes supported by the server. This information is 240 provided by the server via the WWW-Authenticate header field 241 (Section 4). The client SHOULD only send an authenticated request to 242 the server (without first receiving a challenge) if it has prior 243 knowledge of the attributes supported by server. 245 The client chooses an available token with the supported class and 246 authentication method. It also chooses a supported authentication 247 coverage. The methods through which the client obtains a valid 248 token, or the criteria used to choose a token if more than one is 249 available are beyond the scope of this specification. 251 Once the client selects the appropriate token credentials it proceeds 252 to: 254 1. Assign values based on its selection to the following attributes: 256 * "token" 258 * "class" 260 * "method" 262 * "coverage" 264 2. If the client uses a coverage method other than "none" it MUST 265 assign values to the following attributes: 267 * "nonce" 269 * "timestamp" 271 3. Assigns value to any additional class-specific, method-specific, 272 or coverage-specific attributes as defined by protocol 273 extensions. 275 4. If the client uses a coverage method other than "none" it 276 constructs the normalized request string based on the selected 277 coverage as described in Section 8. 279 5. Calculates the value of the "auth" attribute as defined by the 280 selected authentication method. 282 6. Adds the assigned attributes to the request via the Authorization 283 header field (Section 5). 285 7. Sends the authenticated HTTP request to the server. 287 3. Verifying Requests 289 A servers receiving an authenticated request validates it by 290 performing the following REQUIRED steps: 292 1. Verify that the token used by the client as well as the coverage 293 method matches the server's requirements. 295 2. If the client used a coverage method other than "none", construct 296 the normalized request string based on the selected coverage as 297 described in Section 8. 299 3. If the client used an authentication method other than "none", 300 recalculate the value of the "auth" attribute as described in 301 Section 7 and compare it to the value received from the client 302 via the "auth" attribute. 304 4. If the client used a coverage method other than "none", ensure 305 that the combination of nonce, timestamp, and token received from 306 the client has not been used before in a previous request (the 307 server MAY reject requests with stale timestamps; the 308 determination of staleness is left up to the server to define). 310 5. Verify the scope and status of the client credentials as 311 represented by the token. 313 If the request fails verification, the server SHOULD respond with an 314 HTTP 401 (unauthorized) status code, and SHOULD include a token 315 scheme authentication challenge using the WWW-Authenticate header 316 field (Section 6). The server MAY include further details about why 317 the request was rejected using the Authorization-Error header field 318 (Section 6). 320 4. The WWW-Authenticate Response Header 322 A server receiving a request for a protected resource without a valid 323 Authorization header field (Section 5) MUST respond with a 401 status 324 code (Unauthorized), and includes at least one "WWW-Authenticate" 325 header field including a token scheme challenge. 327 The "WWW-Authenticate" header field uses the framework defined by 328 [RFC2617] as follows: 330 challenge = "Token" RWS token-challenge 332 token-challenge = class 333 CS method-list 334 [ CS coverage-list ] 335 [ CS timestamp ] 337 class = "class" "=" <"> token <"> 339 method-list = "method" "=" <"> 1#method-name <"> 340 method-name = "none" / 341 "hmac-sha-1" / 342 "hmac-sha-256" / 343 "rsassa-pkcs1-v1.5-sha-256" / 344 token 346 coverage-list = "coverage" "=" <"> 1#coverage-name <"> 347 coverage-name = "none" / 348 "base" / 349 "base+body-sha-256" / 350 token 352 timestamp = "timestamp" "=" <"> 1*DIGIT <"> 354 CS = OWF "," OWF 356 4.1. The 'class' Attribute 358 The name of the token class supported by the server. Servers MAY 359 support multiple classes per protected resource by providing multiple 360 challenges, each with a different class. 362 4.2. The 'method' Attribute 364 The list of authentication method names supported by the server, 365 provided as a space-delimited list. Authentication methods are 366 described in Section 7. 368 4.3. The 'coverage' Attribute 370 The list of authentication coverage names supported by the server, 371 provided as a space-delimited list. If omitted, the attribute 372 defaults to "base". Authentication coverage is described in 373 Section 8. 375 4.4. The 'timestamp' Attribute 377 Signature-based and hash-based authentication methods use timestamps 378 in combination with unique nonce values to protect against replay 379 attacks when used over an unsecure channel. 381 The timestamp attribute is used by the server to publish its current 382 time, enabling clients to synchronize their close with the server. 383 The timestamp value is the current time expressed in the number of 384 seconds since January 1, 1970 00:00:00 GMT, and MUST be a positive 385 integer. 387 To avoid the need to retain an infinite number of nonce values for 388 future checks, servers MAY choose to restrict the time period after 389 which a request with an old timestamp is rejected. Servers applying 390 such a restriction SHOULD provide their current time to the client 391 either in every challenge or when a request fails due to a timestamp 392 outside the allowed window. 394 5. The Authorization Request Header 396 A client making a request for a protected resource either directly, 397 or in retrying a request after receiving a 401 status code 398 (Unauthorized) with a token challenge, MUST include at least one 399 "Authorization" header field including token scheme credentials. 401 The "Authorization" header field uses the framework defined by 402 [RFC2617] as follows: 404 credentials = "Token" RWS token-response 406 token-response = token-id 407 CS class 408 CS method 409 [ CS coverage ] 410 [ CS nonce ] 411 [ CS timestamp ] 412 [ CS auth ] 414 token-id = "token" "=" <"> token <"> 415 method = "method" "=" <"> method-name <"> 416 coverage = "coverage" "=" <"> coverage-name <"> 417 nonce = "nonce" "=" <"> token <"> 418 auth = "auth" "=" <"> token <"> 420 5.1. The 'token' Attribute 422 The value used to identify the set of token credentials used by the 423 client to authenticate. The token identifier can be an opaque string 424 or use a well-defined internal structure, which is determined by the 425 token class. 427 5.2. The 'class' Attribute 429 The name of the token class used by the client to make the request. 431 5.3. The 'method' Attribute 433 The name of the authentication method used by the client to make the 434 request. 436 5.4. The 'coverage' Attribute 438 The name of the authentication coverage method used by the client to 439 make the request. If the attribute is omitted, its value defaults to 440 "base". 442 5.5. The 'nonce' Attribute 444 A random string, uniquely generated by the client to allow the server 445 to verify that a request has never been made before and helps prevent 446 replay attacks when requests are made over a non-secure channel. The 447 nonce value MUST be unique across all requests with the same 448 timestamp and token combinations. 450 5.6. The 'timestamp' Attribute 452 The timestamp value is the current time expressed in the number of 453 seconds since January 1, 1970 00:00:00 GMT, and MUST be a positive 454 integer. 456 5.7. The 'auth' Attribute 458 The output of the authentication method function after applying it to 459 the selected coverage as described in Section 7. 461 6. The Authentication-Error Response Header 463 A server receiving a request for a protected resource with an invalid 464 Authorization header field (Section 5) MAY includes the 465 "Authentication-Error" header field providing the client with 466 information to help it successfully authenticate with the server. 468 The "Authentication-Error" header field is defined as follows: 470 Authentication-Error = "Authentication-Error" ":" 471 OWS #1error-param 473 error-param = error-code / 474 error-info / 475 error-message / 476 auth-param 478 error-code = "error-code" "=" <"> token <"> 479 error-info = "error-info" "=" <"> token <"> 480 error-message = "error-message" "=" quoted-string 482 6.1. The 'error-code' attribute 484 6.2. The 'error-info' attribute 486 6.3. The 'error-message' attribute 488 7. Authentication Methods 490 In order for the server to verify the authenticity of the request and 491 prevent unauthorized access, the client must prove it is the rightful 492 owner of the credentials. This is accomplished using the 493 authentication method associated with the token. 495 This specification provides three methods for the client to prove its 496 rightful ownership of the credentials: "hmac-sha-1", "hmac-sha-256", 497 and "rsassa-pkcs1-v1.5-sha-256". In addition, the "none" method is 498 defined to allow the use of bearer token which does not utilizes any 499 cryptographic means. 501 The authentication process does not change the request or its 502 parameters, with the exception of the "auth" attribute. 504 7.1. The 'none' Method 506 The "none" method does not employ a cryptographic algorithm and does 507 not provide any security on its own. Servers utilizing this method 508 use the token identifier as a bearer token, relying solely on the 509 value of the token identifier to authenticate the client. 511 The "nonce", "timestamp", and "auth" attributes are not used, and 512 SHOULD NOT be included in authenticated requests. The "coverage" 513 attribute MUST be set to "none" but MAY be omitted from the request. 515 Nevertheless, these attributes MUST be included in the normalized 516 request string together with any other authentication attributes. 518 7.2. The 'hmac-sha-1' Method 520 The "hmac-sha-1" authentication method uses the HMAC-SHA1 algorithm 521 as defined in [RFC2104]: 523 digest = HMAC-SHA1 (key, text) 525 The HMAC-SHA1 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.3. The 'hmac-sha-256' Method 541 The "hmac-sha-256" authentication method uses the HMAC algorithm as 542 defined in [RFC2104] together with the SHA-256 hash function defined 543 in [NIST FIPS-180-3]: 545 digest = HMAC-SHA256 (key, text) 547 The HMAC-SHA256 function variables are used in following way: 549 text 550 is set to the value of the normalize request string as 551 described in Section 8. 553 key 554 is set to the shared-secret associated with the token. 556 digest 557 is used to set the value of the "auth" attribute, after the 558 result octet string is base64-encoded per [RFC2045] section 559 6.8. 561 7.4. The 'rsassa-pkcs1-v1.5-sha-256' Method 563 The "rsassa-pkcs1-v1.5-sha-256" signature method uses the RSASSA- 564 PKCS1-v1_5 signature algorithm as defined in [RFC3447] section 8.2 565 (also known as PKCS#1), using SHA-256 as the hash function as defined 566 in [NIST FIPS-180-3] for EMSA-PKCS1-v1_5. 568 The normalized request string is signed using the RSA private key 569 associated with the token as defined in [RFC3447] section 8.2.1: 571 S = RSASSA-PKCS1-V1_5-SIGN (K, M) 573 Where: 575 K 576 is set to the RSA private key associated with the token, 578 M 579 is set to the value of the normalized request string described 580 in Section 8, and 582 S 583 is the result signature used to set the value of the "auth" 584 attribute, after the result octet string is base64-encoded per 585 [RFC2045] section 6.8. 587 The server verifies the signature per [RFC3447] section 8.2.2: 589 RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, S) 591 Where: 593 (n, e) 594 is set to the RSA public key associated with the token, 596 M 597 is set to the value of the normalized request string described 598 in Section 8, and 600 S 601 is set to the octet string value of the "auth" attribute 602 received from the client. 604 8. Coverage Methods 606 The normalized request string is a consistent, reproducible 607 concatenation of several of the HTTP request elements into a single 608 string. The string is used as an input to the authentication methods 609 with the exception of "none". 611 8.1. The 'base' Method 613 When using the "base" method, the normalized request string includes 614 the following components of the HTTP request: 616 o The HTTP request method (e.g. "GET", "POST", etc.). 618 o The authority as declared by the HTTP "Host" request header. 620 o The request resource URI. 622 o The Authorization header field (Section 5) attributes, with the 623 exception of the "auth" attribute. 625 The "base" normalized request string does not cover the entire HTTP 626 request. Most notably, it does not include the entity-body or most 627 HTTP entity-headers. It is important to note that the server cannot 628 verify the authenticity of the excluded request elements without 629 using additional protections such as SSL/TLS or other methods. 631 8.1.1. String Construction 633 The normalized request string is constructed by concatenating 634 together, in order, the following HTTP request elements: 636 1. The HTTP request method in uppercase. For example: "HEAD", 637 "GET", "POST", etc. 639 2. A "," character (ASCII code 44). 641 3. The hostname, colon-separated (ASCII code 58) from the TCP port 642 used to make the request as included in the HTTP request "Host" 643 header field. The port MUST be included even if it is not 644 included in the "Host" header field (i.e. the default port for 645 the scheme). 647 4. A "," character (ASCII code 44). 649 5. Any authentication attribute, with the exception of the "auth", 650 which is assigned a value (including default values), are added 651 to the normalized request string as follows: 653 1. The name of each parameter is concatenated to its 654 corresponding value using an "=" character (ASCII code 61) as 655 separator, even if the value is empty. 657 2. The name/value pairs are sorted using ascending byte value 658 ordering. 660 3. The sorted name/value pairs are concatenated together into a 661 single string by using a "," character (ASCII code 44) as 662 separator. 664 6. A "," character (ASCII code 44). 666 7. The request resource URI. 668 8.2. The 'base+body-hmac-sha-256' Method 670 The "base+body-hmac-sha-256" method added the request entity-body to 671 the elements included in the normalized request string. It does not 672 include the entity-body directly in the normalized string. Instead, 673 it calculates the hash value of the entity-body using the SHA-256 674 hash function defined in [NIST FIPS-180-3]. 676 The normalized request string is constructed following the same 677 process defined in Section 8.1.1, with the following addition: 679 o Before constructing the string, the entity-body hash is calculated 680 by applying the SHA-256 hash function on the raw entity-body 681 content. 683 o The hash value is added to the list of authentication attributes 684 by assigning its value to the "body-hash" attribute name. This is 685 done prior to the attributes being sorted and added to the string. 687 o The "body-hash" attribute is only included in the normalized 688 request string and is not added to the Authorization header field 689 (Section 5). 691 9. Scheme Extensions 693 10. Security Considerations 695 As stated in [RFC2617], the greatest sources of risks are usually 696 found not in the core protocol itself but in policies and procedures 697 surrounding its use. Implementers are strongly encouraged to assess 698 how this protocol addresses their security requirements. 700 10.1. Credentials Transmission 702 This specification does not describe any mechanism for obtaining or 703 transmitting raw tokens credentials. Methods used to obtain tokens 704 should ensure that these transmissions are protected using transport- 705 layer mechanisms such as TLS or SSL. 707 10.2. Confidentiality of Requests 709 While this protocol provides a mechanism for verifying the integrity 710 of requests, it provides no guarantee of request confidentiality. 711 Unless further precautions are taken, eavesdroppers will have full 712 access to request content. Servers should carefully consider the 713 kinds of data likely to be sent as part of such requests, and should 714 employ transport-layer security mechanisms to protect sensitive 715 resources. 717 10.3. Spoofing by Counterfeit Servers 719 This protocol makes no attempt to verify the authenticity of the 720 server. A hostile party could take advantage of this by intercepting 721 the client's requests and returning misleading or otherwise incorrect 722 responses. Service providers should consider such attacks when 723 developing services using this protocol, and should require 724 transport-layer security for any requests where the authenticity of 725 the server or of request responses is an issue. 727 10.4. Plaintext Storage of Credentials 729 When used with a symmetric shared-secret authentication method, the 730 token shared-secret function the same way passwords do in traditional 731 authentication systems. In order to compute the signatures used in 732 methods, the server must have access to these secrets in plaintext 733 form. This is in contrast, for example, to modern operating systems, 734 which store only a one-way hash of user credentials. 736 If an attacker were to gain access to these secrets - or worse, to 737 the server's database of all such secrets - he or she would be able 738 to perform any action on behalf of any resource owner. Accordingly, 739 it is critical that servers protect these secrets from unauthorized 740 access. 742 10.5. Scoping of Access Requests 744 By itself, this protocol does not provide any method for scoping the 745 access rights granted to a client. However, most applications do 746 require greater granularity of access rights. For example, servers 747 may wish to make it possible to grant access to some protected 748 resources but not others, or to grant only limited access (such as 749 read-only access) to those protected resources. 751 When implementing this protocol, servers should consider the types of 752 access resource owners may wish to grant clients, and should provide 753 mechanisms to do so. Servers should also take care to ensure that 754 resource owners understand the access they are granting, as well as 755 any risks that may be involved. 757 10.6. Entropy of Secrets 759 Unless a transport-layer security protocol is used, eavesdroppers 760 will have full access to authenticated requests and signatures, and 761 will thus be able to mount offline brute-force attacks to recover the 762 credentials used. Servers should be careful to assign shared-secrets 763 which are long enough, and random enough, to resist such attacks for 764 at least the length of time that the shared-secrets are valid. 766 For example, if shared-secrets are valid for two weeks, servers 767 should ensure that it is not possible to mount a brute force attack 768 that recovers the shared-secret in less than two weeks. Of course, 769 servers are urged to err on the side of caution, and use the longest 770 secrets reasonable. 772 It is equally important that the pseudo-random number generator 773 (PRNG) used to generate these secrets be of sufficiently high 774 quality. Many PRNG implementations generate number sequences that 775 may appear to be random, but which nevertheless exhibit patterns or 776 other weaknesses which make cryptanalysis or brute force attacks 777 easier. Implementers should be careful to use cryptographically 778 secure PRNGs to avoid these problems. 780 10.7. Denial of Service / Resource Exhaustion Attacks 782 This specification includes a number of features which may make 783 resource exhaustion attacks against servers possible. For example, 784 this protocol requires servers to track used nonces. If an attacker 785 is able to use many nonces quickly, the resources required to track 786 them may exhaust available capacity. And again, this protocol can 787 require servers to perform potentially expensive computations in 788 order to verify the signature on incoming requests. An attacker may 789 exploit this to perform a denial of service attack by sending a large 790 number of invalid requests to the server. 792 Resource Exhaustion attacks are by no means specific to this 793 specification. However, implementers should be careful to consider 794 the additional avenues of attack that this protocol exposes, and 795 design their implementations accordingly. For example, entropy 796 starvation typically results in either a complete denial of service 797 while the system waits for new entropy or else in weak (easily 798 guessable) secrets. When implementing this protocol, servers should 799 consider which of these presents a more serious risk for their 800 application and design accordingly. 802 10.8. Coverage Limitations 804 The normalized request string has been designed to support the 805 authentication methods defined in this specification. Those 806 designing additional methods, should evaluated the compatibility of 807 the normalized request string with their security requirements. 808 Since the normalized request string does not cover the entire HTTP 809 request, servers should employ additional mechanisms to protect such 810 elements. 812 11. IANA Considerations 814 12. Acknowledgments 816 The author would like to thank Richard Barnes, Breno de Medeiros, 817 Brian Eaton, Ben Laurie, Mark Nottingham, John Panzer, and Peter 818 Saint-Andre for their suggestions, feedback, and continued support. 820 Appendix A. Document History 822 [[ To be removed by the RFC editor before publication as an RFC. ]] 824 -00 826 o Initial (incomplete) draft. 828 13. References 830 13.1. Normative References 832 [I-D.ietf-httpbis-p1-messaging] 833 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 834 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 835 "HTTP/1.1, part 1: URIs, Connections, and Message 836 Parsing", draft-ietf-httpbis-p1-messaging-08 (work in 837 progress), October 2009. 839 [NIST FIPS-180-3] 840 National Institute of Standards and Technology, "Secure 841 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 843 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 844 Extensions (MIME) Part One: Format of Internet Message 845 Bodies", RFC 2045, November 1996. 847 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 848 Hashing for Message Authentication", RFC 2104, 849 February 1997. 851 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 852 Requirement Levels", BCP 14, RFC 2119, March 1997. 854 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 855 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 856 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 858 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 859 Leach, P., Luotonen, A., and L. Stewart, "HTTP 860 Authentication: Basic and Digest Access Authentication", 861 RFC 2617, June 1999. 863 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 864 Standards (PKCS) #1: RSA Cryptography Specifications 865 Version 2.1", RFC 3447, February 2003. 867 13.2. Informative References 869 [I-D.ietf-oauth-web-delegation] 870 Hammer-Lahav, E., "The OAuth Protocol: Web Delegation", 871 draft-ietf-oauth-web-delegation-01 (work in progress), 872 July 2009. 874 URIs 876 [1] 878 Author's Address 880 Eran Hammer-Lahav 881 Yahoo! 883 Email: eran@hueniverse.com 884 URI: http://hueniverse.com