idnits 2.17.1 draft-ietf-httpauth-mutual-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- 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 (April 24, 2014) is 3655 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-09) exists of draft-ietf-httpauth-extension-01 ** Obsolete normative reference: RFC 2898 (Obsoleted by RFC 8018) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-23) exists of draft-ietf-precis-framework-16 -- Obsolete informational reference (is this intentional?): RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPAUTH Working Group Y. Oiwa 3 Internet-Draft H. Watanabe 4 Intended status: Experimental H. Takagi 5 Expires: October 26, 2014 RISEC, AIST 6 K. Maeda 7 T. Hayashi 8 Lepidum 9 Y. Ioku 10 Individual 11 April 24, 2014 13 Mutual Authentication Protocol for HTTP 14 draft-ietf-httpauth-mutual-02 16 Abstract 18 This document specifies a mutual authentication method for the Hyper- 19 text Transfer Protocol (HTTP). This method provides a true mutual 20 authentication between an HTTP client and an HTTP server using 21 password-based authentication. Unlike the Basic and Digest 22 authentication methods, the Mutual authentication method specified in 23 this document assures the user that the server truly knows the user's 24 encrypted password. 26 Status of this Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on October 26, 2014. 43 Copyright Notice 45 Copyright (c) 2014 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.2. Document Structure and Related Documents . . . . . . . . . 5 63 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 5 64 2.1. Messages Overview . . . . . . . . . . . . . . . . . . . . 6 65 2.2. Typical Flows of the Protocol . . . . . . . . . . . . . . 6 66 2.3. Alternative Flows . . . . . . . . . . . . . . . . . . . . 9 67 3. Message Syntax . . . . . . . . . . . . . . . . . . . . . . . . 10 68 3.1. Values . . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 3.1.1. Tokens . . . . . . . . . . . . . . . . . . . . . . . . 11 70 3.1.2. Strings . . . . . . . . . . . . . . . . . . . . . . . 12 71 3.1.3. Numbers . . . . . . . . . . . . . . . . . . . . . . . 12 72 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 73 4.1. 401-INIT and 401-STALE . . . . . . . . . . . . . . . . . . 14 74 4.2. req-KEX-C1 . . . . . . . . . . . . . . . . . . . . . . . . 17 75 4.3. 401-KEX-S1 . . . . . . . . . . . . . . . . . . . . . . . . 17 76 4.4. req-VFY-C . . . . . . . . . . . . . . . . . . . . . . . . 18 77 4.5. 200-VFY-S . . . . . . . . . . . . . . . . . . . . . . . . 19 78 5. Authentication Realms . . . . . . . . . . . . . . . . . . . . 19 79 5.1. Resolving Ambiguities . . . . . . . . . . . . . . . . . . 21 80 6. Session Management . . . . . . . . . . . . . . . . . . . . . . 22 81 7. Host Validation Methods . . . . . . . . . . . . . . . . . . . 23 82 7.1. Applicability notes . . . . . . . . . . . . . . . . . . . 25 83 7.2. Interoperability notes on tls-unique . . . . . . . . . . . 25 84 8. Authentication Extensions . . . . . . . . . . . . . . . . . . 26 85 9. Decision Procedure for Clients . . . . . . . . . . . . . . . . 26 86 9.1. General Principles and Requirements . . . . . . . . . . . 26 87 9.2. State machine for the client-side . . . . . . . . . . . . 28 88 10. Decision Procedure for Servers . . . . . . . . . . . . . . . . 33 89 11. Authentication Algorithms . . . . . . . . . . . . . . . . . . 35 90 11.1. Support Functions and Notations . . . . . . . . . . . . . 36 91 11.2. Default Functions for Algorithms . . . . . . . . . . . . . 37 92 12. Application Channel Binding . . . . . . . . . . . . . . . . . 38 93 13. Application for Proxy Authentication . . . . . . . . . . . . . 39 94 14. Methods to Extend This Protocol . . . . . . . . . . . . . . . 39 95 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 96 16. Security Considerations . . . . . . . . . . . . . . . . . . . 40 97 16.1. Security Properties . . . . . . . . . . . . . . . . . . . 40 98 16.2. Denial-of-service Attacks to Servers . . . . . . . . . . . 41 99 16.2.1. On-line Active Password Attacks . . . . . . . . . . . 41 100 16.3. Communicating the status of mutual authentication with 101 users . . . . . . . . . . . . . . . . . . . . . . . . . . 42 102 16.4. Implementation Considerations . . . . . . . . . . . . . . 42 103 16.5. Usage Considerations . . . . . . . . . . . . . . . . . . . 43 104 17. Notice on Intellectual Properties . . . . . . . . . . . . . . 43 105 18. References . . . . . . . . . . . . . . . . . . . . . . . . . . 44 106 18.1. Normative References . . . . . . . . . . . . . . . . . . . 44 107 18.2. Informative References . . . . . . . . . . . . . . . . . . 45 108 Appendix A. (Informative) Draft Remarks from Authors . . . . . . 46 109 Appendix B. (Informative) Draft Change Log . . . . . . . . . . . 46 110 B.1. Changes in Httpauth WG Revision 02 . . . . . . . . . . . . 46 111 B.2. Changes in Httpauth WG Revision 01 . . . . . . . . . . . . 46 112 B.3. Changes in Httpauth Revision 00 . . . . . . . . . . . . . 47 113 B.4. Changes in HttpBis Revision 00 . . . . . . . . . . . . . . 47 114 B.5. Changes in Revision 12 . . . . . . . . . . . . . . . . . . 47 115 B.6. Changes in Revision 11 . . . . . . . . . . . . . . . . . . 47 116 B.7. Changes in Revision 10 . . . . . . . . . . . . . . . . . . 47 117 B.8. Changes in Revision 09 . . . . . . . . . . . . . . . . . . 48 118 B.9. Changes in Revision 08 . . . . . . . . . . . . . . . . . . 49 119 B.10. Changes in Revision 07 . . . . . . . . . . . . . . . . . . 49 120 B.11. Changes in Revision 06 . . . . . . . . . . . . . . . . . . 49 121 B.12. Changes in Revision 05 . . . . . . . . . . . . . . . . . . 50 122 B.13. Changes in Revision 04 . . . . . . . . . . . . . . . . . . 50 123 B.14. Changes in Revision 03 . . . . . . . . . . . . . . . . . . 50 124 B.15. Changes in Revision 02 . . . . . . . . . . . . . . . . . . 50 125 B.16. Changes in Revision 01 . . . . . . . . . . . . . . . . . . 51 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51 128 1. Introduction 130 This document specifies a mutual authentication method for Hyper-Text 131 Transfer Protocol (HTTP). The method, called "Mutual Authentication 132 Protocol" in this document, provides a true mutual authentication 133 between an HTTP client and an HTTP server, using just a simple 134 password as a credential. 136 The authentication method proposed in this document has the following 137 main characteristics: 139 o It provides "true" mutual authentication: in addition to assuring 140 the server that the user knows the password, it also assures the 141 user that the server truly knows the user's encrypted password at 142 the same time. This makes it impossible for fake website owners 143 to persuade users that they have authenticated with the original 144 websites. 146 o It uses only passwords as the user's credential: unlike public- 147 key-based security algorithms, the method does not rely on secret 148 keys or other cryptographic data that have to be stored inside the 149 users' computers. The proposed method can be used as a drop-in 150 replacement to the current authentication methods like Basic or 151 Digest, while ensuring a much stronger level of security. 153 o It is secure: when the server fails to authenticate with a user, 154 the protocol will not reveal any tiny bit of information about the 155 user's password. 157 1.1. Terminology 159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 161 "OPTIONAL" in this document are to be interpreted as described in 162 [RFC2119]. 164 This document distinguishes the terms "client" and "user" in the 165 following way: A "client" is an entity understanding and talking HTTP 166 and the specified authentication protocol, usually computer software; 167 a "user" is a (usually natural) person who wants to access data 168 resources using "a client". 170 The term "natural numbers" refers to the non-negative integers 171 (including zero) throughout this document. 173 This document treats target (codomain) of hash functions to be octet 174 strings. The notation INT(H(s)) gives a numerical (natural-number) 175 output of hash function H applied to string s. 177 1.2. Document Structure and Related Documents 179 The entire document is organized as follows: 181 o Section 2 presents an overview of the protocol design. 183 o Sections 3 to 10 define a general framework of the Mutual 184 authentication protocol. This framework is independent of 185 specific cryptographic primitives. 187 o Section 11 describes properties needed for cryptographic 188 algorithms used with this protocol framework, and defines a few 189 functions which will be shared among such cryptographic 190 algorithms. 192 o The sections after that contain general normative and informative 193 information about the protocol. 195 o The appendices contain some information that may help developers 196 to implement the protocol. 198 In addition, there are two companion documents which are referred 199 from/related to this specification: 201 o [I-D.oiwa-httpauth-mutual-algo]: defines a cryptographic 202 primitives which can be used with this protocol framework. [draft 203 note: it is separated from this document so that it may be 204 replaced with another crypto in future.] 206 o [I-D.ietf-httpauth-extension]: defines a small but useful 207 extensions to the current HTTP authentication framework so that it 208 can support application-level semantics of existing Web systems. 210 2. Protocol Overview 212 The protocol, as a whole, is designed as a natural extension to the 213 HTTP protocol [I-D.ietf-httpbis-p1-messaging] using a framework 214 defined in [I-D.ietf-httpbis-p7-auth]. Internally, the server and 215 the client will first perform a cryptographic key exchange, using the 216 secret password as a "tweak" to the exchange. The key-exchange will 217 only succeed when the secrets used by the both peers are correctly 218 related (i.e. generated from the same password). Then, both peers 219 will verify the authentication results by confirming the sharing of 220 the exchanged key. This section describes a brief image of the 221 protocol and the exchanged messages. 223 2.1. Messages Overview 225 The authentication protocol uses seven kinds of messages to perform 226 mutual authentication. These messages have specific names within 227 this specification. 229 o Authentication request messages: used by the servers to request 230 clients to start mutual authentication. 232 * 401-INIT message: a general message to start the authentication 233 protocol. It is also used as a message indicating an 234 authentication failure. 236 * 401-STALE message: a message indicating that it has to start a 237 new authentication trial. 239 o Authenticated key exchange messages: used by both peers to perform 240 authentication and the sharing of a cryptographic secret. 242 * req-KEX-C1 message: a message sent from the client. 244 * 401-KEX-S1 message: a message sent from the server as a 245 response to a req-KEX-C1 message. 247 o Authentication verification messages: used by both peers to verify 248 the authentication results. 250 * req-VFY-C message: a message used by the client, requesting 251 that the server authenticates and authorizes the client. 253 * 200-VFY-S message: a successful response used by the server, 254 and also asserting that the server is authentic to the client 255 simultaneously. 257 In addition to the above, either a request or a response without any 258 HTTP headers related to this specification will be hereafter called a 259 "normal request" or a "normal response", respectively. 261 2.2. Typical Flows of the Protocol 263 In typical cases, the client access to a resource protected by the 264 Mutual authentication will follow the following protocol sequence. 266 Client Server 267 | | 268 | ---- (1) normal request ---------> | 269 GET / HTTP/1.1 | 270 | | 271 | <---------------- (2) 401-INIT --- | 272 | 401 Authentication Required 273 | WWW-Authenticate: Mutual realm="a realm" 274 | | 275 [user, | | 276 pass]-->| | 277 | ---- (3) req-KEX-C1 -------------> | 278 GET / HTTP/1.1 | 279 Authorization: Mutual user="john", |--> [user DB] 280 kc1="...", ... |<-- [user info] 281 | | 282 | <-------------- (4) 401-KEX-S1 --- | 283 | 401 Authentication Required 284 | WWW-Authenticate: Mutual sid=..., ks1="...", ... 285 | | 286 [compute] (5) compute session secret [compute] 287 | | 288 | | 289 | ---- (6) req-VFY-C --------------> | 290 GET / HTTP/1.1 |--> [verify (6)] 291 Authorization: Mutual sid=..., |<-- OK 292 vkc="...", ... | 293 | | 294 | <--------------- (7) 200-VFY-S --- | 295 [verify | 200 OK | 296 (7)]<--| Authentication-Info: Mutual vks="..." 297 | | 298 v v 300 Figure 1: Typical communication flow for first access to resource 302 o As usual in general HTTP protocol designs, a client will at first 303 request a resource without any authentication attempt (1). If the 304 requested resource is protected by the Mutual authentication, the 305 server will respond with a message requesting authentication 306 (401-INIT) (2). 308 o The client processes the body of the message, and waits for the 309 user to input the user name and a password. If the user name and 310 the password are available, the client will send a message with 311 the authenticated key exchange (req-KEX-C1) to start the 312 authentication (3). 314 o If the server has received a req-KEX-C1 message, the server looks 315 up the user's authentication information within its user database. 316 Then the server creates a new session identifier (sid) that will 317 be used to identify sets of the messages that follow it, and 318 responds back with a message containing a server-side 319 authenticated key exchange value (401-KEX-S1) (4). 321 o At this point (5), both peers calculate a shared "session secret" 322 using the exchanged values in the key exchange messages. Only 323 when both the server and the client have used secret credentials 324 generated from the same password,the session secret values will 325 match. This session secret will be used for access authentication 326 of every individual request after this point. 328 o The client will send a request with a client-side authentication 329 verification value (req-VFY-C) (6), generated from the client- 330 owned session secret. The server will check the validity of the 331 verification value using its own session secret. 333 o If the authentication verification value from the client was 334 correct, it means that the client definitely owns the credential 335 based on the expected password (i.e. the client authentication 336 succeeded.) The server will respond with a successful message 337 (200-VFY-S) (7). Contrary to the usual one-way authentication 338 (e.g. HTTP Basic authentication or POP APOP authentication 339 [RFC1939]), this message also contains a server-side 340 authentication verification value. 342 When the client's verification value is incorrect (e.g. because 343 the user-supplied password was incorrect), the server will respond 344 with the 401-INIT message (the same one as used in (2)) instead. 346 o The client MUST first check the validity of the server-side 347 authentication verification value contained in the message (7). 348 If the value was equal to the expected one, the server 349 authentication succeeded. 351 If it is not the value expected, or if the message does not 352 contain the authentication verification value, it means that the 353 mutual authentication has been broken for some unexpected reason. 354 The client MUST NOT process any body or header values contained in 355 this case. (Note: This case should not happen between a 356 correctly-implemented server and a client without any 357 interventions. Possible cause of such cases might be either a 358 man-in-the-middle attack or a mis-implementation.) 360 2.3. Alternative Flows 362 As shown above, the typical flow for a first authenticated request 363 requires three request-response pairs. To reduce the protocol 364 overhead, the protocol enables several short-cut flows which require 365 fewer messages. 367 o (case A) If the client knows that the resource is likely to 368 require the authentication, the client MAY omit the first 369 unauthenticated request (1) and immediately send a key exchange 370 (req-KEX-C1 message). This will reduce one round-trip of 371 messages. 373 o (case B) If both the client and the server previously shared a 374 session secret associated with a valid session identifier (sid), 375 the client MAY directly send a req-VFY-C message using the 376 existing session identifier and corresponding session secret. 377 This will further reduce one round-trip of messages. 379 In such cases, the server MAY have thrown out the corresponding 380 sessions from the session table. In this case, the server will 381 respond with a 401-STALE message, indicating a new key exchange is 382 required. The client SHOULD retry constructing a req-KEX-C1 383 message in this case. 385 Figure 2 depicts the shortcut flows described above. Under the 386 appropriate settings and implementations, most of the requests to 387 resources are expected to meet both the criteria, and thus only one 388 round-trip of request/responses will be required in most cases. 390 (A) omit first request 391 (2 round trips) 393 Client Server 394 | | 395 | --- req-KEX-C1 ----> | 396 | | 397 | <---- 401-KEX-S1 --- | 398 | | 399 | ---- req-VFY-C ----> | 400 | | 401 | <----- 200-VFY-S --- | 402 | | 404 (B) reusing session secret (re-authentication) 406 (B-1) key available (B-2) key expired 407 (1 round trip) (3 round trips) 409 Client Server Client Server 410 | | | | 411 | ---- req-VFY-C ----> | | --- req-VFY-C -------> | 412 | | | | 413 | <----- 200-VFY-S --- | | <------- 401-STALE --- | 414 | | | | 415 | --- req-KEX-C1 ------> | 416 | | 417 | <------ 401-KEX-S1 --- | 418 | | 419 | --- req-VFY-C -------> | 420 | | 421 | <------- 200-VFY-S --- | 422 | | 424 Figure 2: Several alternative flows on protocol 426 For more details, see Sections 9 and 10. 428 3. Message Syntax 430 Throughout this specification, The syntax is denoted in the extended 431 augmented BNF syntax defined in [I-D.ietf-httpbis-p1-messaging] and 432 [RFC5234]. The following elements are quoted from [RFC5234], 433 [I-D.ietf-httpbis-p1-messaging] and [I-D.ietf-httpbis-p7-auth]: 434 DIGIT, ALPHA, SP, auth-scheme, quoted-string, auth-param, header- 435 field, token, challenge, and credential. 437 The Mutual authentication protocol uses three headers: 438 WWW-Authenticate (in responses with status code 401), Authorization 439 (in requests), and Authentication-Info (in responses other than 401 440 status). These headers follow a common framework described in 441 [I-D.ietf-httpbis-p7-auth]. The detailed meanings for these headers 442 are contained in Section 4. 444 The framework in [I-D.ietf-httpbis-p7-auth] defines the syntax for 445 the headers WWW-Authenticate and Authorization as the syntax elements 446 "challenge" and "credentials", respectively. The "auth-scheme" 447 contained in those headers MUST be "Mutual" throughout this protocol 448 specification. The syntax for "challenge" and "credentials" to be 449 used with the "Mutual" auth-scheme SHALL be name-value pairs (#auth- 450 param), not the "b64token" defined in [I-D.ietf-httpbis-p7-auth]. 452 The Authentication-Info: header used in this protocol SHALL contain 453 the value in same syntax as those the "WWW-Authenticate" header, i.e. 454 the "challenge" syntax element. 456 In HTTP, the WWW-Authenticate header may contain more than one 457 challenges. Client implementations SHOULD be aware of and be capable 458 of handle those cases correctly. 460 3.1. Values 462 The parameter values contained in challenge/credentials MUST be 463 parsed strictly conforming to the HTTP semantics (especially un- 464 quoting of the string parameter values). In this protocol, those 465 values are further categorized into the following value types: tokens 466 (bare-token and extensive-token), string, integer, hex-fixed-number, 467 and base64-fixed-number. 469 For clarity, implementations are RECOMMENDED to use the canonical 470 representations specified in the following subsections for sending 471 values. Recipients SHOULD accept both quoted and unquoted 472 representations interchangeably as specified in HTTP. 474 3.1.1. Tokens 476 For sustaining both security and extensibility at the same time, this 477 protocol defines a stricter sub-syntax for the "token" to be used. 478 The extensive-token values SHOULD follow the following syntax (after 479 HTTP value parsing): 481 bare-token = 1*(DIGIT / ALPHA / "-" / "_") 482 extension-token = "-" bare-token 1*("." bare-token) 483 extensive-token = bare-token / extension-token 484 Figure 3: BNF syntax for token values 486 The tokens (bare-token and extension-token) are case insensitive; 487 Senders SHOULD send these in lower-case, and receivers MUST accept 488 both upper- and lower-cases. When tokens are used as (partial) 489 inputs to any hash or other mathematical functions, it MUST always be 490 used in lower-case. 492 Extensive-tokens are used in this protocol where the set of 493 acceptable tokens may include non-standard extensions. Any non- 494 standard extensions of this protocol SHOULD use the extension-tokens 495 with format "-.", where is a 496 validly registered (sub-)domain name on the Internet owned by the 497 party who defines the extensions. 499 Bare-tokens and extensive-tokens are also used for parameter names 500 (of course in the unquoted form). Requirements for using the 501 extension-token for the parameter names are the same as the above. 503 The canonical format for bare-tokens and tokens are unquoted tokens. 505 3.1.2. Strings 507 All character strings MUST be encoded to octet strings using the 508 UTF-8 encoding [RFC3629] for the ISO 10646-1 character set 509 [ISO.10646-1.1993]. Such strings MUST NOT contain any leading BOM 510 characters (ZERO WIDTH NO-BREAK SPACE, U+FEFF or EF BB BF). Both 511 peers are RECOMMENDED to reject any invalid UTF-8 sequences that 512 might cause decoding ambiguities (e.g., containing <"> in the second 513 or later bytes of the UTF-8 encoded characters). 515 If strings are representing a domain name or URI that contains non- 516 ASCII characters, the host parts SHOULD be encoded as it is used in 517 the HTTP protocol layer (e.g. in a Host: header); under current 518 standards it will be the one defined in [RFC5890]. It SHOULD use 519 lower-case ASCII characters. 521 The canonical format for strings are quoted-string (as it may contain 522 equal signs, plus signs and slashes). 524 3.1.3. Numbers 526 The following syntax definitions gives a syntax for number-type 527 values: 529 integer = "0" / (%x31-39 *DIGIT) ; no leading zeros 530 hex-fixed-number = 1*(2(DIGIT / %x41-46 / %x61-66)) 531 base64-fixed-number = 1*( ALPHA / DIGIT / "+" / "/" ) 0*2"=" 533 Figure 4: BNF syntax for number types 535 The syntax definition of the integers only allows representations 536 that do not contain extra leading zeros. 538 The numbers represented as a hex-fixed-number MUST include an even 539 number of characters (i.e. multiples of eight bits). Those values 540 are case-insensitive, and SHOULD be sent in lower-case. When these 541 values are generated from any cryptographic values, they SHOULD have 542 their "natural length": if these are generated from a hash function, 543 these lengths SHOULD correspond to the hash size; if these are 544 representing elements of a mathematical set (or group), its lengths 545 SHOULD be the shortest for representing all the elements in the set. 546 For example, any results of SHA-256 hash function will be represented 547 by 64 characters, and any elements in 2048-bit prime field (modulo a 548 2048-bit integer) will be represented by 512 characters, regardless 549 of how much 0's will be appear in front of such representations. 550 Session-identifiers and other non-cryptographically generated values 551 are represented in any (even) length determined by the side who 552 generates it first, and the same length SHALL be used throughout the 553 all communications by both peers. 555 The numbers represented as base64-fixed-number SHALL be generated as 556 follows: first, the number is converted to a big-endian radix-256 557 binary representation as an octet string. The length of the 558 representation is determined in the same way as mentioned above. 559 Then, the string is encoded using the Base 64 encoding [RFC4648] 560 without any spaces and newlines. Implementations decoding base64- 561 fixed-number SHOULD reject any input data with invalid characters, 562 excess/insufficient paddings, or non-canonical pad bits (See Sections 563 3.1 to 3.5 of [RFC4648]). 565 The canonical format for integer and hex-fixed-number are unquoted 566 tokens, and that for base64-fixed-number is quoted-string. 568 4. Messages 570 In this section we define the seven kinds of messages used in the 571 authentication protocol along with the formats and requirements of 572 the headers for each message. 574 To determine which message are expected to be sent, see Sections 9 575 and 10. 577 In the descriptions below, the type of allowable values for each 578 header parameter is shown in parenthesis after each parameter name. 579 The "algorithm-determined" type means that the acceptable value for 580 the parameter is one of the types defined in Section 3, and is 581 determined by the value of the "algorithm" parameter. The parameters 582 marked "mandatory" SHALL be contained in the message. The parameters 583 marked "non-mandatory" MAY either be contained or omitted in the 584 message. Each parameter SHALL appear in each headers exactly once at 585 most. 587 All credentials and challenges MAY contain any parameters not 588 explicitly specified in the following sections. Recipients who do 589 not understand such parameters MUST silently ignore those. However, 590 all credentials and challenges MUST meet the following criteria: 592 o For responses, the parameters "reason", any "ks*" (where * stands 593 for any decimal integers), and "vks" are mutually exclusive: any 594 challenge MUST NOT contain two or more parameters among them. 595 They MUST NOT contain any "kc*" and "vkc" parameters. 597 o For requests, the parameters "kc*" (where * stands for any decimal 598 integers), and "vkc" are mutually exclusive and any challenge 599 MUST NOT contain two or more parameters among them. They MUST NOT 600 contain any "ks*" and "vks" parameters. 602 Every message in this section contains a "version" field, to detect 603 future incompatible revisions of the protocol. Implementations of 604 the protocol described in this specification MUST always send a token 605 "-wg-draft02", and recipients MUST reject messages which contain any 606 other value as a version, unless another specification defines a 607 behavior for that version. [[Editorial Note: This token is updated 608 on every draft revisions which will affect the wire protocol. It 609 will (shall) be updated to "1" in the final published RFC.]] 611 4.1. 401-INIT and 401-STALE 613 Every 401-INIT or 401-STALE message SHALL be a valid HTTP 401-status 614 (Authentication Required) message containing one (and only one: 615 hereafter not explicitly noticed) "WWW-Authenticate" header 616 containing a "reason" parameter in the challenge. The challenge 617 SHALL contain all of the parameters marked "mandatory" below, and MAY 618 contain those marked "non-mandatory". 620 version: (mandatory extensive-token) should be the token "-wg- 621 draft02". 623 algorithm: (mandatory extensive-token) specifies the 624 authentication algorithm to be used. The value MUST 625 be one of the tokens specified in 626 [I-D.oiwa-httpauth-mutual-algo] or other supplemental 627 specification documentation. 629 validation: (mandatory extensive-token) specifies the method of 630 host validation. The value MUST be one of the tokens 631 described in Section 7, or the tokens specified in 632 other supplemental specification documentation. 634 auth-domain: (non-mandatory string) specifies the authentication 635 domain, the set of hosts for which the authentication 636 credentials are valid. It MUST be one of the strings 637 described in Section 5. If the value is omitted, it 638 is assumed to be the "single-server" type domain in 639 Section 5. 641 realm: (mandatory string) is a UTF-8 encoded string 642 representing the name of the authentication realm 643 inside the authentication domain. As specified in 644 [I-D.ietf-httpbis-p7-auth], this value MUST always be 645 sent in the quoted-string form. 647 pwd-hash: (non-mandatory extensive-token) specifies the hash 648 algorithm (hereafter referred to by ph) used for 649 additionally hashing the password. The valid tokens 650 are 652 * none: ph(p) = p 654 * md5: ph(p) = MD5(p) 656 * digest-md5: ph(p) = MD5(username | ":" | realm | 657 ":" | p), the same value as MD5(A1) for "MD5" 658 algorithm in [RFC2617]. 660 * sha1: ph(p) = SHA1(p) 662 If omitted, the value "none" is assumed. The use of 663 "none" is desirable. 665 reason: (mandatory extensive-token) SHALL be an extensive- 666 token which describes the possible reason of the 667 failed authentication/authorization. Both servers and 668 clients SHALL understand and support the following 669 three tokens: 671 * initial: authentication was not tried because there 672 was no Authorization header in the corresponding 673 request. 675 * stale-session: the provided sid; in the request was 676 either unknown to or expired in the server. 678 * auth-failed: authentication trial was failed by 679 some reasons, possibly with a bad authentication 680 credentials. 682 Implementations MAY support the following tokens or 683 any extensive-tokens defined outside this 684 specification. If clients has received any unknown 685 tokens, these SHOULD treat these as if it were "auth- 686 failed" or "initial". 688 * reauth-needed: server-side application requires a 689 new authentication trial, regardless of the current 690 status. 692 * invalid-parameters: authentication was not even 693 tried in the server-side because some parameters 694 are not acceptable. 696 * internal-error: authentication was not even tried 697 in the server-side because there is some troubles 698 on the server-side. 700 * user-unknown: a special case of auth-failed, 701 suggesting that the provided user-name is invalid. 702 The use of this parameter is NOT RECOMMENDED for 703 security implications, except for special-purpose 704 applications which makes this value sense. 706 * invalid-credential: ditto, suggesting that the 707 provided user-name was valid but authentication was 708 failed. The use of this parameter is 709 NOT RECOMMENDED as the same as the above. 711 * authz-failed: authentication was successful, but 712 access to the specified resource is not authorized 713 to the specific authenticated user. (It is 714 different from 403 responses which suggest that the 715 reason of inaccessibility is other that 716 authentication.) 718 The algorithm specified in this header will determine the types 719 (among those defined in Section 3) and the values for K_c1, K_s1, 720 VK_c and VK_s. 722 Among these messages, those with the reason parameter of value 723 "stale-session" will be called "401-STALE" messages hereafter, 724 because these have a special meaning in the protocol flow. Messages 725 with any other reason parameters will be called "401-INIT" messages. 727 4.2. req-KEX-C1 729 Every req-KEX-C1 message SHALL be a valid HTTP request message 730 containing an "Authorization" header with a credential containing a 731 "kc1" parameter. 733 The credential SHALL contain the parameters with the following names: 735 version: (mandatory, extensive-token) should be the token "-wg- 736 draft02". 738 algorithm, validation, auth-domain, realm: MUST be the same value as 739 it is when received from the server. 741 user: (mandatory, string) is the UTF-8 encoded name of the 742 user. If this name comes from a user input, client 743 software SHOULD prepare the string using HTTPAUTHprep 744 [I-D.oiwa-precis-httpauthprep] before encoding it to 745 UTF-8. [[Editorial: merger with new SASLprep is being 746 considered and discussed in precis WG. Replace the 747 reference once it is done.]] 749 kc1: (mandatory, algorithm-determined) is the client-side 750 key exchange value K_c1, which is specified by the 751 algorithm that is used. 753 4.3. 401-KEX-S1 755 Every 401-KEX-S1 message SHALL be a valid HTTP 401-status 756 (Authentication Required) response message containing a 757 "WWW-Authenticate" header with a challenge containing a "ks1" 758 parameter. 760 The challenge SHALL contain the parameters with the following names: 762 version: (mandatory, extensive-token) should be the token "-wg- 763 draft02". 765 algorithm, validation, auth-domain, realm: MUST be the same value as 766 it is when received from the client. 768 sid: (mandatory, hex-fixed-number) MUST be a session 769 identifier, which is a random integer. The sid SHOULD 770 have uniqueness of at least 80 bits or the square of 771 the maximal estimated transactions concurrently 772 available in the session table, whichever is larger. 773 See Section 6 for more details. 775 ks1: (mandatory, algorithm-determined) is the server-side 776 key exchange value K_s1, which is specified by the 777 algorithm. 779 nc-max: (mandatory, integer) is the maximal value of nonce 780 counts that the server accepts. 782 nc-window: (mandatory, integer) the number of available nonce 783 slots that the server will accept. The value of the 784 nc-window parameter is RECOMMENDED to be 32 or more. 786 time: (mandatory, integer) represents the suggested time (in 787 seconds) that the client can reuse the session 788 represented by the sid. It is RECOMMENDED to be at 789 least 60. The value of this parameter is not directly 790 linked to the duration that the server keeps track of 791 the session represented by the sid. 793 path: (non-mandatory, string) specifies which path in the 794 URI space the same authentication is expected to be 795 applied. The value is a space-separated list of URIs, 796 in the same format as it was specified in domain 797 parameter [RFC2617] for the Digest authentications. 798 The all path elements contained in the parameter MUST 799 be inside the specified auth-domain; if not, clients 800 SHOULD ignore such elements. For better performance, 801 recognition of this parameter by clients are 802 significantly important. 804 4.4. req-VFY-C 806 Every req-VFY-C message SHALL be a valid HTTP request message 807 containing an "Authorization" header with a credential containing a 808 "vkc" parameter. 810 The parameters contained in the header are as follows: 812 version: (mandatory, extensive-token) should be the token "-wg- 813 draft02". 815 algorithm, validation, auth-domain, realm: MUST be the same value as 816 it is when received from the server for the session. 818 sid: (mandatory, hex-fixed-number) MUST be one of the sid 819 values that was received from the server for the same 820 authentication realm. 822 nc: (mandatory, integer) is a nonce value that is unique 823 among the requests sharing the same sid. The values 824 of the nonces SHOULD satisfy the properties outlined 825 in Section 6. 827 vkc: (mandatory, algorithm-determined) is the client-side 828 authentication verification value VK_c, which is 829 specified by the algorithm. 831 4.5. 200-VFY-S 833 Every 200-VFY-S message SHALL be a valid HTTP message that is not of 834 the 401 (Authentication Required) status, containing an 835 "Authentication-Info" header with a "vks" parameter. 837 The parameters contained in the header are as follows: 839 version: (mandatory, extensive-token) should be the token "-wg- 840 draft02". 842 sid: (mandatory, hex-fixed-number) MUST be the value 843 received from the client. 845 vks: (mandatory, algorithm-determined) is the server-side 846 authentication verification value VK_s, which is 847 specified by the algorithm. 849 The header MUST be sent before the content body: it MUST NOT be sent 850 in the trailer of a chunked-encoded response. If a "100 Continue" 851 response is sent from the server, the Authentication-Info header 852 SHOULD be included in that response, instead of the final response. 854 5. Authentication Realms 856 In this protocol, an "authentication realm" is defined as a set of 857 resources (URIs) for which the same set of user names and passwords 858 is valid for. If the server requests authentication for an 859 authentication realm that the client is already authenticated for, 860 the client will automatically perform the authentication using the 861 already-known secrets. However, for the different authentication 862 realms, the clients MUST NOT automatically reuse the user names and 863 passwords for another realm. 865 Just like in Basic and Digest access authentication protocols, Mutual 866 authentication protocol supports multiple, separate protection spaces 867 to be set up inside each host. Furthermore, the protocol supports 868 that a single authentication realm spans over several hosts within 869 the same Internet domain. 871 Each authentication realm is defined and distinguished by the triple 872 of an "authentication algorithm", an "authentication domain", and a 873 "realm" parameter. However, server operators are NOT RECOMMENDED to 874 use the same pair of an authentication domain and a realm for 875 different authentication algorithms. 877 The realm parameter is a string as defined in Section 4. 878 Authentication domains are described in the remainder of this 879 section. 881 An authentication domain specifies the range of hosts that the 882 authentication realm spans over. In this protocol, it MUST be one of 883 the following strings. 885 o Single-server type: The string in format 886 "://:", where , , and are 887 the corresponding URI parts of the request URI. Even if the 888 request-URI does not have a port part, the string will include one 889 (i.e. 80 for http and 443 for https). The port part MUST NOT 890 contain leading zeros. Use this when authentication is only valid 891 for specific protocol (such as https). 893 o Single-host type: The "host" part of the requested URI. This is 894 the default value. Authentication realms within this kind of 895 authentication domain will span over several protocols (i.e. http 896 and https) and ports, but not over different hosts. 898 o Wildcard-domain type: The string in format "*.", 899 where is either the host part of the requested 900 URI or any domain in which the requested host is included (this 901 means that the specification "*.example.com" is valid for all of 902 hosts "www.example.com", "web.example.com", 903 "www.sales.example.com" and "example.com"). The domain-postfix 904 sent from the servers MUST be equal to or included in a valid 905 Internet domain assigned to a specific organization: if clients 906 know, by some means such as a blacklist for HTTP cookies 908 [RFC6265], that the specified domain is not to be assigned to any 909 specific organization (e.g. "*.com" or "*.jp"), the clients are 910 RECOMMENDED to reject the authentication request. 912 In the above specifications, every "scheme", "host", and "domain" 913 MUST be in lower-case, and any internationalized domain names beyond 914 the ASCII character set SHALL be represented in the way they are sent 915 in the underlying HTTP protocol, represented in lower-case 916 characters; i.e. these SHALL be in the form of the LDH labels in IDNA 917 [RFC5890]. All "port"s MUST be in the shortest, unsigned, decimal 918 number notation. Not obeying these requirements will cause failure 919 of valid authentication attempts. 921 5.1. Resolving Ambiguities 923 In the above definitions of authentication domains, several domains 924 will overlap each other. If a client has already been authenticated 925 to several realms applicable to the same server, the client may have 926 a multiple list of the "path" parameters received with the 927 "401-KEX-S1" message (see Section 4). If these path lists have any 928 overlap, a single URI may belong to multiple possible candidate of 929 realms to be authenticated to. In such cases, clients faces an 930 ambiguity on deciding which credentials to be sent for a new request 931 (in steps 3 and 4 of the decision procedure presented in Section 9). 933 In such cases, clients MAY send requests which belongs to any of 934 these candidate realms freely, or it MAY simply send an 935 unauthenticated request and see for which realm the server request an 936 authentication. Server operators are RECOMMENDED to provide 937 properly-configured "path" parameters (more precisely, disjoint path 938 sets for each realms) for clients so that such ambiguities will not 939 occur. 941 The following procedure are one of the possible tactics for resolving 942 ambiguity in such cases. 944 o If the client has previously sent a request to the same URI, and 945 if it remembers the authentication realm requested by 401-INIT 946 messages at that time, use that realm. 948 o In other cases, use one of authentication realms representing the 949 most-specific authentication domains. From the list of possible 950 domain specifications shown above, each one earlier has priority 951 over ones described after that. 953 If there are several choices with different domain-postfix 954 specifications, the one that has the longest domain-postfix has 955 priority over ones with a shorter domain-postfix. 957 o If there are realms with the same authentication domain, there is 958 no defined priority: the client MAY choose any one of the possible 959 choices. 961 6. Session Management 963 In the Mutual authentication protocol, a session represented by an 964 sid is set up using first four messages (first request, 401-INIT, 965 req-KEX-C1 and 401-KEX-S1), and a "session secret" (z) associated 966 with the session is established. After sharing a session secret, 967 this session, along with the secret, can be used for one or more 968 requests for resources protected by the same realm in the same 969 server. Note that session management is only an inside detail of the 970 protocol and usually not visible to normal users. If a session 971 expires, the client and server SHOULD automatically re-establish 972 another session without informing the users. 974 Sessions and session identifiers are local to each server (defined by 975 scheme, host and port), even if an authentication domain covers 976 multiple servers; the clients MUST establish separate sessions for 977 each port of a host to be accessed. Furthermore, sessions and 978 identifiers are also local to each authentication realm, even if 979 these are provided from the same server. The same session 980 identifiers provided either from different servers or for different 981 realms MUST be treated as independent ones. 983 The server SHOULD accept at least one req-VFY-C request for each 984 session, given that the request reaches the server in a time window 985 specified by the timeout parameter in the 401-KEX-S1 message, and 986 that there are no emergent reasons (such as flooding attacks) to 987 forget the sessions. After that, the server MAY discard any session 988 at any time and MAY send 401-STALE messages for any req-VFY-C 989 requests. 991 The client MAY send two or more requests using a single session 992 specified by the sid. However, for all such requests, each value of 993 the nonce (in the nc parameter) MUST satisfy the following 994 conditions: 996 o It is a natural number. 998 o The same nonce was not sent within the same session. 1000 o It is not larger than the nc-max value that was sent from the 1001 server in the session represented by the sid. 1003 o It is larger than (largest-nc - nc-window), where largest-nc is 1004 the maximal value of nc which was previously sent in the session, 1005 and nc-window is the value of the nc-window parameter which was 1006 received from the server in the session. 1008 The last condition allows servers to reject any nonce values that are 1009 "significantly" smaller than the "current" value (defined by the 1010 value of nc-window) of the nonce used in the session involved. In 1011 other words, servers MAY treat such nonces as "already received". 1012 This restriction enables servers to implement duplicated nonce 1013 detection in a constant amount of memory (for each session). 1015 Servers MUST check for duplication of the received nonces, and if any 1016 duplication is detected, the server MUST discard the session and 1017 respond with a 401-STALE message, as outlined in Section 10. The 1018 server MAY also reject other invalid nonce values (such as ones above 1019 the nc-max limit) by sending a 401-STALE message. 1021 For example, assume the nc-window value of the current session is 32, 1022 nc-max is 100, and that the client has already used the following 1023 nonce values: {1-20, 22, 24, 30-38, 45-60, 63-72}. Then the nonce 1024 values that can be used for next request is one of the following set: 1025 {41-44, 61-62, 73-100}. The values {0, 21, 23, 25-29, 39-40} MAY be 1026 rejected by the server because they are not above the current "window 1027 limit" (40 = 72 - 32). 1029 Typically, clients can ensure the above property by using a 1030 monotonically-increasing integer counter that counts from zero upto 1031 the value of nc-max. 1033 The values of the nonces and any nonce-related values MUST always be 1034 treated as natural numbers within an infinite range. Implementations 1035 which uses fixed-width integer representations, fixed-precision 1036 floating numbers or similar representations SHOULD NOT reject any 1037 larger values which overflow such representative limits, and MUST NOT 1038 silently truncate it using any modulus-like rounding operation (e.g. 1039 by mod 2^32). Instead, the whole protocol is carefully designed so 1040 that recipients MAY replace any such overflowed values (e.g. 2^80) 1041 with some reasonably-large maximal representative integer (e.g. 2^31 1042 - 1 or others). 1044 7. Host Validation Methods 1046 The "validation method" specifies a method to "relate" (or "bind") 1047 the mutual authentication processed by this protocol with other 1048 authentications already performed in the underlying layers and to 1049 prevent man-in-the-middle attacks. It decides the value vh that is 1050 an input to the authentication protocols. 1052 When HTTPS or other possible secure transport is used, this 1053 corresponds to the idea of "channel binding" described in [RFC5929]. 1054 Even when HTTP is used, similar, but somewhat limited, "binding" is 1055 performed to prevent a malicious server from trying to authenticate 1056 themselves to another server as a valid user by forwarding the 1057 received credentials. 1059 The valid tokens for the validation parameter and corresponding 1060 values of vh are as follows: 1062 host: host-name validation: The value vh will be the ASCII 1063 string in the following format: 1064 "://:", where , , 1065 and are the URI components corresponding to the 1066 currently accessing resource. The scheme and host are 1067 in lower-case, and the port is in a shortest decimal 1068 representation. Even if the request-URI does not have 1069 a port part, v will include the default port number. 1071 tls-server-end-point: TLS endpoint (certificate) validation: The 1072 value vh will be the octet string of the hash value of 1073 the server's public key certificate used in the 1074 underlying TLS [RFC5246] (or SSL) connection, 1075 processed as specified in Section 4.1 of [RFC5929]. 1077 [[Pending editorial issue: a small security issue is 1078 pending around here, awaiting analysis and WG 1079 discussions for final adoption.]] 1081 tls-unique: TLS shared-key validation: The value v will be the 1082 channel binding material derived from the Finished 1083 messages, as defined in Section 3.1 of [RFC5929]. 1085 If the HTTP protocol is used on a non-encrypted channel (TCP and 1086 SCTP, for example), the validation type MUST be "host". If HTTP/TLS 1087 [RFC2818] (HTTPS) protocol is used with the server certificates, the 1088 validation type MUST be "tls-server-end-point". If HTTP/TLS protocol 1089 is used with an anonymous Diffie-Hellman key exchange, the validation 1090 type MUST be "tls-unique" (see the note below). 1092 Implementations supporting a Mutual authentication over the HTTPS 1093 protocol SHOULD support the "tls-server-end-point" validation. 1094 Support for "tls-unique" validation is OPTIONAL for both the servers 1095 and clients. 1097 If the validation type "tls-server-end-point" is used, the server 1098 certificate provided on TLS connection MUST be verified at least to 1099 make sure that the server actually owns the corresponding secret key. 1100 (Note: this verification is automatic in some RSA-based key exchanges 1101 but NOT automatic in Diffie-Hellman-based key exchanges with separate 1102 exchange for server verifications.) 1104 Clients MUST validate this parameter upon reception of the 401-INIT 1105 messages. 1107 Note: The protocol defines two variants for validation on the TLS 1108 connections. The "tls-unique" method is more secure. However, there 1109 are some situations where tls-server-end-point is more preferable. 1111 o When TLS accelerating proxies are used, it is difficult for the 1112 authenticating server to acquire the TLS key information that is 1113 used between the client and the proxy. This is not the case for 1114 client-side "tunneling" proxies using a CONNECT method extension 1115 of HTTP. 1117 o When a black-box implementation of the TLS protocol is used on 1118 either peer. 1120 7.1. Applicability notes 1122 When the client is a Web browser with any scripting capabilities, the 1123 underlying TLS channel used with HTTP/TLS MUST provide server 1124 identity verification. This means (1) the anonymous Diffie-Hellman 1125 key exchange cipher-suite MUST NOT be used, and (2) the verification 1126 of the server certificate provided from the server MUST be performed. 1128 For other systems, when the underlying TLS channel used with HTTP/TLS 1129 does not perform server identity verification, the client SHOULD 1130 ensure that all the responses are validated using the Mutual 1131 authentication protocol, regardless of the existence of the 401-INIT 1132 responses. 1134 7.2. Interoperability notes on tls-unique 1136 As described in the interoperability note in the above channel 1137 binding specification, the tls-unique verification value will be 1138 changed by possible TLS renegotiation, causing an interoperability 1139 problem. TLS re-negotiations are used in several HTTPS server 1140 implementations for enforcing some security properties (such as 1141 cryptographic strength) for some specific responses. 1143 If an implementation supports "tls-unique" verification method, the 1144 following caution SHOULD be taken: 1146 o Both peers must be aware that the values vh used for vkc (in 1147 req-VFY-C) and for vks (in 200-VFY-S) may be different. These 1148 values MUST be retrieved from underlying TLS libraries each time 1149 it is used. 1151 o After calculating value vh and vkc to send a req-VFY-C request, 1152 Clients SHOULD NOT initiate TLS renegotiation until the end of the 1153 corresponding response header is received. Exceptionally, Clients 1154 can and SHOULD perform TLS re-negotiation as a response to 1155 server's request for TLS renegotiation, occurring before the top 1156 of response header. 1158 8. Authentication Extensions 1160 Interactive clients (e.g. Web browsers) supporting this protocol are 1161 RECOMMENDED to support non-mandatory authentication and the 1162 Authentication-Control header defined in 1163 [I-D.ietf-httpauth-extension], except the "auth-style" parameter. 1164 This specification also proposes (however, not mandates) default 1165 "auth-style" to be "non-modal". Web applications SHOULD however 1166 consider the security impacts of the behaviors of clients that do not 1167 support these headers. 1169 Authentication-initializing messages with the 1170 Optional-WWW-Authenticate header are used only where 401-INIT 1171 response is valid. It will not replace other 401-type messages such 1172 as 401-STALE and 401-KEX-S1. 1174 9. Decision Procedure for Clients 1176 9.1. General Principles and Requirements 1178 To securely implement the protocol, the user client must be careful 1179 about accepting the authenticated responses from the server. This 1180 also holds true for the reception of "normal responses" (responses 1181 which do not contain Mutual-related headers) from HTTP servers. 1183 As usual in the HTTP authentication, a single user-level request may 1184 result in exchange of two-or-more HTTP requests and responses in 1185 sequence. The following care MUST be taken by the all clients 1186 implementing this protocol: 1188 o Any kinds of "normal responses" MUST only be accepted for the very 1189 first request in the sequence. Any "normal responses" returned 1190 for the second or later request in the sequence SHALL be 1191 considered invalid. 1193 o In the same principle, any responses which refer to, or request 1194 changing to, the authentication realm different from the client's 1195 request MUST only be accepted for the very first request in the 1196 sequence. Any kind of responses referring to the different realms 1197 which are returned for the second or later request in the sequence 1198 SHALL be considered invalid. 1200 o A req-KEX-C1 message MAY be sent either as a initial request or as 1201 a response to 401-INIT, and 401-STALE. However, it SHOULD NOT be 1202 sent more than once in the sequence for a single authentication 1203 realm, to avoid infinite loops of messages. A 401-KEX-S1 response 1204 MUST be accepted only when the corresponding request is 1205 req-KEX-C1. 1207 o A req-VFY-C message MAY be sent if there is a valid session key 1208 shared between the client and the server, established by 1209 req-KEX-C1 and 401-KEX-S1. If any response with 401 status is 1210 returned for such a message, the corresponding session key SHOULD 1211 be discarded as unusable. 1212 Especially, upon the reception of response 401-STALE, the client 1213 SHOULD try establishing a new session by sending req-KEX-C1, but 1214 only once within the request/response sequence. 1216 o A 200-VFY-S message MUST be accepted only as a response to 1217 req-VFY-C and nothing else. The VK_s field of such response 1218 message MUST always be checked against the correct value, and if 1219 it is incorrect, the whole response SHOULD be considered invalid. 1220 Any content, both the content body and the headers, of such an 1221 invalid response SHOULD be ignored and discarded. 1223 The final status of the client request following the message exchange 1224 sequence shall be determined as follows: 1226 o AUTH-SUCCEED: A 200-VFY-S message with the correct VK_s value is 1227 returned to the req-VFY-C request in the sequence. 1229 o AUTH-REQUIRED: Two cases exists. 1231 * A 401-INIT message is returned from the server, and the client 1232 does not know how to authenticate to the given authentication 1233 realm. 1235 * A 401-INIT response is returned for req-VFY-C (or req-KEX-C1), 1236 which means the user-supplied authentication credentials are 1237 not accepted. 1239 o UNAUTHENTICATED: a normal response is returned for an initial 1240 request of any kind in the sequence. 1242 Any kind of response (including a normal response) other than those 1243 explicitly allowed in the above rules SHOULD be interpreted as a 1244 fatal communication error. In such cases, the clients MUST NOT 1245 process any data (the response body and other content-related 1246 headers) sent from the server. However, to handle exceptional error 1247 cases, clients MAY accept a message without an Authentication-Info 1248 header, if it is a Server-Error (5xx) status. In such cases, they 1249 SHOULD be careful about processing the body of the content (ignoring 1250 it is still RECOMMENDED, as it may possibly be forged by intermediate 1251 attackers,) and the client will be in the "UNAUTHENTICATED" status 1252 then. 1254 If a request is a sub-request for a resource included in another 1255 resources (e.g., embedded images, style sheets, frames etc.), clients 1256 MAY treat an AUTH-REQUESTED status as the same as UNAUTHENTICATED 1257 status. In other words, the client MAY ignore server's request to 1258 start authentication with new credentials via sub-requests. 1260 9.2. State machine for the client-side 1262 The following state machine describes the possible request-response 1263 sequences derived from the above general rules. If implementors are 1264 not quite sure on the security consequences of the above rules, it is 1265 strongly RECOMMENDED to follow the decision procedure below. In 1266 particular, clients SHOULD NOT accept "normal responses" unless 1267 explicitly allowed in the rules. The labels on the steps are for 1268 informational purposes only. Action entries within each step are 1269 checked in top-to-bottom order, and the first clause satisfied SHOULD 1270 be taken. 1272 Step 1 (step_new_request): 1273 If the client software needs to access a new Web resource, check 1274 whether the resource is expected to be inside some authentication 1275 realm for which the user has already been authenticated by the 1276 Mutual authentication scheme. If yes, go to Step 2. Otherwise, 1277 go to Step 5. 1279 Step 2: 1280 Check whether there is an available sid for the authentication 1281 realm you expect. If there is one, go to Step 3. Otherwise, go 1282 to Step 4. 1284 Step 3 (step_send_vfy_1): 1285 Send a req-VFY-C request. 1287 * If you receive a 401-INIT message with a different 1288 authentication realm than expected, go to Step 6. 1290 * If you receive a 401-STALE message, go to Step 9. 1292 * If you receive a 401-INIT message, go to Step 13. 1294 * If you receive a 200-VFY-S message, go to Step 14. 1296 * If you receive a normal response, go to Step 11. 1298 Step 4 (step_send_kex1_1): 1299 Send a req-KEX-C1 request. 1301 * If you receive a 401-INIT message with a different 1302 authentication realm than expected, go to Step 6. 1304 * If you receive a 401-KEX-S1 message, go to Step 10. 1306 * If you receive a 401-INIT message with the same authentication 1307 realm, go to Step 13 (see Note 1). 1309 * If you receive a normal response, go to Step 11. 1311 Step 5 (step_send_normal_1): 1312 Send a request without any Mutual authentication headers. 1314 * If you receive a 401-INIT message, go to Step 6. 1316 * If you receive a normal response, go to Step 11. 1318 Step 6 (step_rcvd_init): 1319 Check whether you know the user's password for the requested 1320 authentication realm. If yes, go to Step 7. Otherwise, go to 1321 Step 12. 1323 Step 7: 1324 Check whether there is an available sid for the authentication 1325 realm you expect. If there is one, go to Step 8. Otherwise, go 1326 to Step 9. 1328 Step 8 (step_send_vfy): 1329 Send a req-VFY-C request. 1331 * If you receive a 401-STALE message, go to Step 9. 1333 * If you receive a 401-INIT message, go to Step 13. 1335 * If you receive a 200-VFY-S message, go to Step 14. 1337 Step 9 (step_send_kex1): 1338 Send a req-KEX-C1 request. 1340 * If you receive a 401-KEX-S1 message, go to Step 10. 1342 * If you receive a 401-INIT message, go to Step 13 (See Note 1). 1344 Step 10 (step_rcvd_kex1): 1345 Send a req-VFY-C request. 1347 * If you receive a 401-INIT message, go to Step 13. 1349 * If you receive a 200-VFY-S message, go to Step 14. 1351 Step 11 (step_rcvd_normal): 1352 The requested resource is out of the authenticated area. The 1353 client will be in the "UNAUTHENTICATED" status. If the response 1354 contains a request for authentications other than Mutual, it MAY 1355 be handled normally. 1357 Step 12 (step_rcvd_init_unknown): 1358 The requested resource requires a Mutual authentication, and the 1359 user is not yet authenticated. The client will be in the "AUTH- 1360 REQUESTED" status, and is RECOMMENDED to process the content sent 1361 from the server, and to ask user for a user name and a password. 1362 When those are supplied from the user, proceed to Step 9. 1364 Step 13 (step_rcvd_init_failed): 1365 For some reason the authentication failed: possibly the password 1366 or the username is invalid for the authenticated resource. 1367 Forget the password for the authentication realm and go to Step 1368 12. 1370 Step 14 (step_rcvd_vfy): 1371 The received message is the 200-VFY-S message, which SHALL always 1372 contain a vks field. Check the validity of the received VK_s 1373 value. If it is equal to the expected value, it means that the 1374 mutual authentication has succeeded. The client will be in the 1375 "AUTH-SUCCEEDED" status. 1377 If the value is unexpected, it is a fatal communication error. 1379 If a user explicitly requests to log out (via user interfaces), 1380 the client MUST forget the user's password, go to step 5 and 1381 reload the current resource without an authentication header. 1383 Note 1: These transitions MAY be accepted by clients, but 1384 NOT RECOMMENDED for servers to initiate. 1386 Figure 5 shows a diagram of the client-side state. 1388 =========== -(11)------------ 1389 NEW REQUEST ( UNAUTHENTICATED ) 1390 =========== ----------------- 1391 | ^ normal 1392 v | response 1393 +(1)-------------------+ NO +(5)----------+ 1394 | The requested URI |--------------------------->| send normal | 1395 | known to be auth'ed? | | request | 1396 +----------------------+ +-------------+ 1397 YES | 401-INIT 401-INIT| 1398 | with a different realm | 1399 | -----------------------------------. | 1400 | / v v 1401 | | -(12)------------ NO +(6)--------+ 1402 | | ( AUTH-REQUESTED )<------| user/pass | 1403 | | ----------------- | known? | 1404 | | +-----------+ 1405 | | |YES 1406 v | v 1407 +(2)--------+ | +(7)--------+ 1408 | session | | | session | NO 1409 NO /| available?| | | available?|\ 1410 / +-----------+ | +-----------+ | 1411 / |YES | |YES | 1412 | | /| | | 1413 | v / | 401- 401- v | 1414 | +(3)--------+ | INIT --(13)---------- INIT +(8)--------+ | 1415 | | send |--+----->/ AUTH-REQUESTED \<-------| send | | 1416 | /| req-VFY-C | | \forget password / | req-VFY-C | | 1417 \/ +-----------+ / ---------------- /+-----------+ | 1418 /\ \ \/ ^ 401-INIT | |401- | 1419 | ------ \/\ 401-STALE | | | STALE / 1420 | \ /\ -----------------+--------------+---. | / 1421 | | / \ | | | | / 1422 | v / | 401- | 401- | v v v 1423 | +(4)--------+ | KEX-S1 +(10)-------+ KEX-S1 | +(9)--------+ 1424 | | send |-|--------->| send |<-------+-| send | 1425 | --| req-KEX-C1| | | req-VFY-C | | | req-KEX-C1| 1426 |/ +-----------+ | +-----------+ | +-----------+ 1427 | |200-VFY-S | 200-VFY-S| ^ 1428 |normal | |200-VFY-S / | 1429 |response | v / ================== 1430 v \ -(14)--------- / USER/PASS INPUTTED 1431 -(11)------------ ------->( AUTH-SUCCEED )<-- ================== 1432 ( UNAUTHENTICATED ) -------------- 1433 ----------------- 1435 Figure 5: State diagram for clients 1437 10. Decision Procedure for Servers 1439 Each server SHOULD have a table of session states. This table need 1440 not be persistent over a long term; it MAY be cleared upon server 1441 restart, reboot, or others. Each entry in the table SHOULD contain 1442 at least the following information: 1444 o The session identifier, the value of the sid parameter. 1446 o The algorithm used. 1448 o The authentication realm. 1450 o The state of the protocol: one of "key exchanging", 1451 "authenticated", "rejected", or "inactive". 1453 o The user name received from the client 1455 o The boolean flag noting whether or not the session is fake. 1457 o When the state is "key exchanging", the values of K_c1 and S_s1. 1459 o When the state is "authenticated", the following information: 1461 * The value of the session secret z 1463 * The largest nc received from the client (largest-nc) 1465 * For each possible nc values between (largest-nc - nc- 1466 window + 1) and max_nc, a flag whether or not a request with 1467 the corresponding nc has been received. 1469 The table MAY contain other information. 1471 Servers SHOULD respond to the client requests according to the 1472 following procedure: (See Note 1 below for 401-INIT message with * 1473 marks) 1475 o When the server receives a normal request: 1477 * If the requested resource is not protected by the Mutual 1478 Authentication, send a normal response. 1480 * If the resource is protected by the Mutual Authentication, send 1481 a 401-INIT response. 1483 o When the server receives a req-KEX-C1 request: 1485 * If the requested resource is not protected by the Mutual 1486 Authentication, send a normal response. 1488 * If the authentication realm specified in the req-KEX-C1 request 1489 is not the expected one, send a 401-INIT response. 1491 * If the server cannot validate the parameter kc1, send a 1492 401-INIT (*) response. 1494 * If the received user name is either invalid, unknown or 1495 unacceptable, create a new session, mark it a "fake" session, 1496 compute a random value as K_s1, and send a fake 401-KEX-S1 1497 response. (Note 2) 1499 * Otherwise, create a new session, compute K_s1 and send a 1500 401-KEX-S1 response. 1502 The created session has the "key exchanging" state. 1504 o When the server receives a req-VFY-C request: 1506 * If the requested resource is not protected by the Mutual 1507 Authentication, send a normal response. 1509 * If the authentication realm specified in the req-VFY-C request 1510 is not the expected one, send a 401-INIT response. 1512 If none of above holds true, the server will lookup the session 1513 corresponding to the received sid and the authentication realm. 1515 * If the session corresponding to the received sid could not be 1516 found, or it is in the "inactive" state, send a 401-STALE 1517 response. 1519 * If the session is in the "rejected" state, send either a 1520 401-INIT (*) or a 401-STALE message. 1522 * If the session is in the "authenticated" state, and the request 1523 has an nc value that was previously received from the client, 1524 send a 401-STALE message. The session SHOULD be changed to the 1525 "inactive" status. 1527 * If the nc value in the request is larger than the nc-max 1528 parameter sent from the server, or if it is not larger then 1529 (largest-nc - nc-window) (when in "authenticated" status), the 1530 server MAY (but not REQUIRED to) send a 401-STALE message. The 1531 session SHOULD be changed to the "inactive" status if so. 1533 * If the session is a "fake" session, or if the received vkc is 1534 incorrect, then send a 401-INIT (*) response. If the session 1535 is in the "key exchanging" state, it SHOULD be changed to the 1536 "rejected" state; otherwise, it MAY either be changed to the 1537 "rejected" status or kept in the previous state. 1539 * Otherwise, send a 200-VFY-S response. If the session was in 1540 the "key exchanging" state, the session SHOULD be changed to an 1541 "authenticated" state. The maximum nc and nc flags of the 1542 state SHOULD be updated properly. 1544 At any time, the server MAY change any state entries with both the 1545 "rejected" and "authenticated" statuses to the "inactive" status, and 1546 MAY discard any "inactive" states from the table. The entries with 1547 the "key exchanging" status SHOULD be kept unless there is an 1548 emergency situation such as a server reboot or a table capacity 1549 overflow. 1551 Note 1: In relation with, and following the specification of the 1552 optional authentication defined in [I-D.ietf-httpauth-extension], the 1553 401-INIT messages marked with the asterisks can not be replaced with 1554 a successful responses with an Optional-WWW-Authenticate header. 1555 Every other 401-INIT can be a response with an 1556 Optional-WWW-Authenticate. 1558 Note 2: the server SHOULD NOT send a 401-INIT response in this case, 1559 because it will leak the information to the client that the specified 1560 user will not be accepted. Instead, postpone it to the response for 1561 the next req-VFY-C request. 1563 11. Authentication Algorithms 1565 Cryptographic authentication algorithms which are used with this 1566 protocol will be defined separately. The algorithm definition MUST 1567 at least provide a definitions for the following functions: 1569 o The server-side authentication credential J, derived from user- 1570 side authentication credential pi. 1572 o Key exchange values K_c1, K_s1 (exchanged on wire) and S_c1, S_s1 1573 (kept secret in each peer). 1575 o Shared secret z, to be computed in both server-side and client 1576 side. 1578 o A hash function H to be used with the protocol, along with its 1579 output size hSize. 1581 o The number of iteration for password hasing nIterPi, if it uses 1582 the default password hashing function defined below. 1584 Specifications for cryptographic algorithms used with this framework 1585 MUST specify whether these will use the default functions defined 1586 below for the functions pi, VK_c, and VK_s; or, these will define 1587 their own versions for these functions. 1589 All algorithm used with this protocol SHOULD provide secure mutual 1590 authentication between client and servers, and generate a 1591 cryptographically strong shared secret value z, equivalently strong 1592 to or stronger than the hash function H. If any passwords (or pass- 1593 phrases or any equivalents, i.e. weak secrets) are involved, these 1594 SHOULD NOT be guessable from any data transmitted in the protocol, 1595 even if an attacker (either an eavesdropper or an active server) 1596 knows the possible thoroughly-searchable candidate list of the 1597 passwords. Furthermore, if possible, the function for deriving 1598 server-side authentication credential J is RECOMMENDED to be one-way 1599 so that pi should not be easily computed from J(pi). 1601 11.1. Support Functions and Notations 1603 In this section we define several support functions and notations to 1604 be shared by several algorithm definitions: 1606 The integers in the specification are in decimal, or in hexadecimal 1607 when prefixed with "0x". 1609 The function octet(c) generates a single octet string whose code 1610 value is equal to c. The operator |, when applied to octet strings, 1611 denotes the concatenation of two operands. 1613 The function VI encodes natural numbers into octet strings in the 1614 following manner: numbers are represented in big-endian radix-128 1615 string, where each digit is represented by a octet within 0x80-0xff 1616 except the last digit represented by a octet within 0x00-0x7f. The 1617 first octet MUST NOT be 0x80. For example, VI(i) = octet(i) for i < 1618 128, and VI(i) = octet(0x80 + (i >> 7)) | octet(i & 127) for 128 <= i 1619 < 16384. This encoding is the same as the one used for the 1620 subcomponents of object identifiers in the ASN.1 encoding 1621 [ITU.X690.1994], and available as a "w" conversion in the pack 1622 function of several scripting languages. 1624 The function VS encodes a variable-length octet string into a 1625 uniquely-decoded, self-delimited octet string, as in the following 1626 manner: 1628 VS(s) = VI(length(s)) | s 1630 where length(s) is a number of octets (not characters) in s. 1632 Some examples: 1634 VI(0) = "\000" (in C string notation) 1636 VI(100) = "d" 1638 VI(10000) = "\316\020" 1640 VI(1000000) = "\275\204@" 1642 VS("") = "\000" 1644 VS("Tea") = "\003Tea" 1646 VS("Caf" [in UTF-8]) = "\005Caf\303\251" 1648 VS([10000 "a"s]) = "\316\020aaaaa..." (10002 octets) 1650 (Note: Unlike the colon-separated notion used in the Basic/Digest 1651 HTTP authentication scheme, the string generated by a concatenation 1652 of the VS-encoded strings will be unique, regardless of the 1653 characters included in the strings to be encoded.) 1655 The function OCTETS converts an integer into the corresponding radix- 1656 256 big-endian octet string having its natural length: See 1657 Section 3.1.3 for the definition of "natural length". 1659 The function INT converts an octet string into a natural number, 1660 where the input string is treated as a radix-256 big-endian notation. 1661 The identity INT(OCTETS(n)) = n always holds for any natural number 1662 n. 1664 11.2. Default Functions for Algorithms 1666 The functions defined in this section are common default functions 1667 among authentication algorithms. 1669 The client-side password-based (credential) pi used by this 1670 authentication is a natural number derived in the following manner: 1672 pi = INT(PBKDF2(HMAC_H, ph(password), VS(algorithm) | VS(auth-domain) 1673 | VS(realm) | VS(username), nIterPi, hSize / 8)), 1674 where 1676 o PBKDF2 is the password-based key derivation function defined in 1677 [RFC2898], 1679 o HMAC_H is the HMAC function, defined in [RFC2104], composed from 1680 the hash function H, and 1682 o hSize is the output size of hash H, counted in bits. 1684 The values of algorithm, realm, and auth-domain are taken from the 1685 values contained in the 401-INIT message. The function ph is 1686 determined by the value of the pwd-hash parameter given in a 401-INIT 1687 message. If the password comes from a user input, it SHOULD first be 1688 prepared using [I-D.oiwa-precis-httpauthprep]. Then, the password 1689 SHALL be encoded as a UTF-8 string before passed to ph. 1691 The values VK_c and VK_s are derived by the following equation. 1693 VK_c = INT(H(octet(4) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | 1694 VI(nc) | VS(vh))) 1696 VK_s = INT(H(octet(3) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | 1697 VI(nc) | VS(vh))) 1699 12. Application Channel Binding 1701 Applications and upper-layer communication protocols may need 1702 authentication binding to the HTTP-layer authenticated user. Such 1703 applications MAY use the following values as a standard shared 1704 secret. 1706 These values are parameterized with an optional octet string (t) 1707 which may be arbitrarily chosen by each applications or protocols. 1708 If there is no appropriate value to be specified, use a null string 1709 for t. 1711 For applications requiring binding to either an authenticated user or 1712 a shared-key session (to ensure that the requesting client is 1713 certainly authenticated), the following value b_1 MAY be used. 1715 b_1 = H(H(octet(6) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VI(0) 1716 | VS(vh)) | VS(t)). 1718 For applications requiring binding to a specific request (to ensure 1719 that the payload data is generated for the exact HTTP request), the 1720 following value b_2 MAY be used. 1722 b_2 = H(H(octet(7) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VI(nc) 1723 | VS(vh)) | VS(t)). 1725 Note: Channel bindings to lower-layer transports (TCP and TLS) are 1726 defined in Section 7. 1728 13. Application for Proxy Authentication 1730 The authentication scheme defined by the previous sections can be 1731 applied (with modifications) for proxy authentications. In such 1732 cases, the following alterations MUST be applied: 1734 o The 407 status is to be sent and recognized for places where the 1735 401 status is used, 1737 o Proxy-Authenticate: header is to be used for places where WWW- 1738 Authenticate: is used, 1740 o Proxy-Authorization: header is to be used for places where 1741 Authorization: is used, 1743 o Proxy-Authentication-Info: header is to be used for places where 1744 Authentication-Info: is used, 1746 o The auth-domain parameter is fixed to the host-name of the proxy, 1747 which means to cover all requests processed through the specific 1748 proxy, 1750 o The limitation for the paths contained in the path parameter of 1751 401-KEX-S1 messages is disregarded, 1753 o The omission of the path parameter of 401-KEX-S1 messages means 1754 that the authentication realm will potentially cover all requests 1755 processed by the proxy, 1757 o The scheme, host name and the port of the proxy is used for host 1758 validation tokens, and 1760 o Authentication extensions in [I-D.ietf-httpauth-extension] are not 1761 applicable. 1763 14. Methods to Extend This Protocol 1765 If a private extension to this protocol is implemented, it MUST use 1766 the extension-tokens defined in Section 3 to avoid conflicts with 1767 this protocol and other extensions. (standardized or being- 1768 standardizing extensions MAY use either bare-tokens or extension- 1769 tokens.) 1771 Specifications defining authentication algorithms MAY use other 1772 representations for the parameters "kc1", "ks1", "vkc", and "vks", 1773 replace those parameter names, and/or add parameters to the messages 1774 containing those parameters in supplemental specifications, provided 1775 that syntactic and semantic requirements in Section 3, 1776 [I-D.ietf-httpbis-p1-messaging] and [I-D.ietf-httpbis-p7-auth] are 1777 satisfied. Any parameters starting with "kc", "ks", "vkc" or "vks" 1778 and followed by decimal natural numbers (e.g. kc2, ks0, vkc1, vks3 1779 etc.) are reserved for this purpose. If those specifications use 1780 names other than those mentioned above, it is RECOMMENDED to use 1781 extension-tokens to avoid any parameter name conflict with the future 1782 extension of this protocol. 1784 Extension-tokens MAY be freely used for any non-standard, private, 1785 and/or experimental uses for those parameters provided that the 1786 domain part in the token is appropriately used. 1788 15. IANA Considerations 1790 When bare-tokens are used for the authentication-algorithm, pwd-hash, 1791 and validation parameters MUST be allocated by IANA. To acquire 1792 registered tokens, a specification for the use of such tokens MUST be 1793 available as an RFC, as outlined in [RFC5226]. 1795 Note: More formal declarations will be added in the future drafts to 1796 meet the RFC 5226 requirements. 1798 16. Security Considerations 1800 16.1. Security Properties 1802 o The protocol is secure against passive eavesdropping and replay 1803 attacks. However, the protocol relies on transport security 1804 including DNS integrity for data secrecy and integrity. HTTP/TLS 1805 SHOULD be used where transport security is not assured and/or data 1806 confidentiality is important. 1808 o When used with HTTP/TLS, if TLS server certificates are reliably 1809 verified, the protocol provides true protection against active 1810 man-in-the-middle attacks. 1812 o Even if the server certificate is not used or is unreliable, the 1813 protocol provides protection against active man-in-the-middle 1814 attacks for each HTTP request/response pair. However, in such 1815 cases, JavaScript or similar scripting facilities can be used to 1816 affect the Mutually-authenticated contents from other contents not 1817 protected by this authentication mechanism. This is the reason 1818 why this protocol requires that valid TLS server certificates MUST 1819 be presented (Section 7). 1821 16.2. Denial-of-service Attacks to Servers 1823 The protocol requires a server-side table of active sessions, which 1824 may become a critical point of the server resource consumptions. For 1825 proper operation, the protocol requires that at least one key 1826 verification request is processed for each session identifier. After 1827 that, servers MAY discard sessions internally at any time, without 1828 causing any operational problems to clients. Clients will silently 1829 reestablishes a new session then. 1831 However, if a malicious client sends too many requests of key 1832 exchanges (req-KEX-C1 messages) only, resource starvation might 1833 occur. In such critical situations, servers MAY discard any kind of 1834 existing sessions regardless of these statuses. One way to mitigate 1835 such attacks are that servers MAY have a number and a time limits for 1836 unverified pending key exchange requests (in the "key exchanging" 1837 status). 1839 This is a common weakness of authentication protocols with almost any 1840 kind of negotiations or states, including Digest authentication 1841 method and most Cookie-based authentication implementations. 1842 However, regarding the resource consumption, a situation of the 1843 mutual authentication method is a slightly better than the Digest, 1844 because HTTP requests without any kind of authentication requests 1845 will not generate any kind of sessions. Session identifiers are only 1846 generated after a client starts a key negotiation. It means that 1847 simple clients such as web crawlers will not accidentally consume 1848 server-side resources for session managements. 1850 16.2.1. On-line Active Password Attacks 1852 Although the protocol provides very strong protection against off- 1853 line dictionary attacks from eavesdropped traffics, the protocol, by 1854 its nature, can not prevent an active password attacks which the 1855 attackers sends so many authentication trial requests for every 1856 possible passwords. 1858 Possible countermeasures for preventing such attacks may be rate- 1859 limiting of the password authentication trials, statistics-based 1860 intrusion detection measures or similar protection schemes. If the 1861 server operators assume that the passwords of users are not strong 1862 enough, it may be desirable to introduce such ad-hoc countermeasures. 1864 16.3. Communicating the status of mutual authentication with users 1866 This protocol is designed for two goals. The first goal is just 1867 providing a secure alternative for existing Basic and Digest 1868 authentication. The second goal is to provide users a way to detect 1869 forged rogue servers imitating user's registered account on server- 1870 side, commonly known as (a part or kind of) Phishing attacks. 1872 For this protocol to effectively work as some countermeasures to such 1873 attacks, it is very important that end users of clients will be 1874 notified of the result of mutual authentication performed by this 1875 protocol, especially the three states "AUTH-SUCCEED", 1876 "UNAUTHENTICATED" and "AUTH-REQUIRED" defined in Section 9. The 1877 design of secure users' interfaces of the HTTP interactive clients 1878 are out of the scope of this document, but if possible, having some 1879 kind of UI indication for the three states above will be desirable 1880 for user's benefits on their security. 1882 Of course, in such cases, the user interfaces for asking passwords 1883 for this authentication shall be clearly identifiable against 1884 imitation by other insecure password input fields (such as forms). 1885 If the passwords are known to malicious attackers outside of the 1886 protocol, the protocol can not work as an effective security 1887 measures. 1889 16.4. Implementation Considerations 1891 o To securely implement the protocol, the Authentication-Info 1892 headers in the 200-VFY-S messages MUST always be validated by the 1893 client. If the validation fails, the client MUST NOT process any 1894 content sent with the message, including other headers and the 1895 body part. Non-compliance to this requirement will allow phishing 1896 attacks. 1898 o For HTTP/TLS communications, when a web form is submitted from 1899 Mutually-authenticated pages with the "tls-server-end-point" 1900 validation method to a URI that is protected by the same realm (so 1901 indicated by the path parameter), if the server certificate has 1902 been changed since the pages were received, the peer is 1903 RECOMMENDED to be revalidated using a req-KEX-C1 message with an 1904 "Expect: 100-continue" header. The same applies when the page is 1905 received with the "tls-unique" validation method, and when the TLS 1906 session has expired. 1908 o For better protection against possible password database steal, 1909 Server-side storages of user passwords are better containing the 1910 values encrypted by one-way function J(pi), instead of the real 1911 passwords, those hashed by ph, or pi. 1913 16.5. Usage Considerations 1915 o The user-names inputted by a user may be sent automatically to any 1916 servers sharing the same auth-domain. This means that when host- 1917 type auth-domain is used for authentication on an HTTPS site, and 1918 when an HTTP server on the same host requests Mutual 1919 authentication within the same realm, the client will send the 1920 user-name in a clear text. If user-names have to be kept secret 1921 against eavesdropping, the server must use full-scheme-type auth- 1922 domain parameter and HTTPS. Contrarily, passwords are not exposed 1923 to eavesdroppers even on HTTP requests. 1925 o The "pwd-hash" parameter is only provided for backward 1926 compatibility of password databases. The use of "none" function 1927 is the most secure choice and is RECOMMENDED. If values other 1928 than "none" are used, you MUST ensure that the hash values of the 1929 passwords were not exposed to the public. Note that hashed 1930 password databases for plain-text authentications are usually not 1931 considered secret. 1933 o If the server provides several ways for storing server-side 1934 password secrets into the password database, it is desirable for 1935 better security to store the values encrypted by using the one-way 1936 function J(pi), instead of the real passwords, those hashed by ph, 1937 or pi. 1939 17. Notice on Intellectual Properties 1941 The National Institute of Advanced Industrial Science and Technology 1942 (AIST) and Yahoo! Japan, Inc. has jointly submitted a patent 1943 application on the protocol proposed in this documentation to the 1944 Patent Office of Japan. The patent is intended to be open to any 1945 implementors of this protocol and its variants under non-exclusive 1946 royalty-free manner. For the details of the patent application and 1947 its status, please contact the author of this document. 1949 The elliptic-curve based authentication algorithms might involve 1950 several existing third-party patents. The authors of the document 1951 take no position regarding the validity or scope of such patents, and 1952 other patents as well. 1954 18. References 1955 18.1. Normative References 1957 [I-D.ietf-httpauth-extension] 1958 Oiwa, Y., Watanabe, H., Takagi, H., Hayashi, T., and Y. 1959 Ioku, "HTTP Authentication Extensions for Interactive 1960 Clients", draft-ietf-httpauth-extension-01 (work in 1961 progress), October 2013. 1963 [I-D.ietf-httpbis-p1-messaging] 1964 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1965 (HTTP/1.1): Message Syntax and Routing", 1966 draft-ietf-httpbis-p1-messaging-26 (work in progress), 1967 February 2014. 1969 [I-D.ietf-httpbis-p7-auth] 1970 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1971 (HTTP/1.1): Authentication", draft-ietf-httpbis-p7-auth-26 1972 (work in progress), February 2014. 1974 [I-D.oiwa-precis-httpauthprep] 1975 Oiwa, Y., Nemoto, T., and B. Kihara, "HTTPAuthPrep: PRECIS 1976 profile for HTTP Authentication", 1977 draft-oiwa-precis-httpauthprep-00 (work in progress), 1978 July 2013. 1980 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1981 Hashing for Message Authentication", RFC 2104, 1982 February 1997. 1984 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1985 Requirement Levels", BCP 14, RFC 2119, March 1997. 1987 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 1988 Specification Version 2.0", RFC 2898, September 2000. 1990 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1991 10646", STD 63, RFC 3629, November 2003. 1993 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1994 Encodings", RFC 4648, October 2006. 1996 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1997 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1999 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2000 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2002 18.2. Informative References 2004 [I-D.ietf-precis-framework] 2005 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 2006 Preparation and Comparison of Internationalized Strings in 2007 Application Protocols", draft-ietf-precis-framework-16 2008 (work in progress), April 2014. 2010 [I-D.oiwa-httpauth-mutual-algo] 2011 Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi, 2012 T., and Y. Ioku, "Mutual Authentication Protocol for HTTP: 2013 KAM3-based Cryptographic Algorithms", 2014 draft-oiwa-httpauth-mutual-algo-02 (work in progress), 2015 April 2014. 2017 [ISO.10646-1.1993] 2018 International Organization for Standardization, 2019 "Information Technology - Universal Multiple-octet coded 2020 Character Set (UCS) - Part 1: Architecture and Basic 2021 Multilingual Plane", ISO Standard 10646-1, May 1993. 2023 [ITU.X690.1994] 2024 International Telecommunications Union, "Information 2025 Technology - ASN.1 encoding rules: Specification of Basic 2026 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2027 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2028 X.690, 1994. 2030 [RFC1939] Myers, J. and M. Rose, "Post Office Protocol - Version 3", 2031 STD 53, RFC 1939, May 1996. 2033 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2034 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2035 Authentication: Basic and Digest Access Authentication", 2036 RFC 2617, June 1999. 2038 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2040 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2041 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2042 May 2008. 2044 [RFC5890] Klensin, J., "Internationalized Domain Names for 2045 Applications (IDNA): Definitions and Document Framework", 2046 RFC 5890, August 2010. 2048 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 2049 for TLS", RFC 5929, July 2010. 2051 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2052 April 2011. 2054 Appendix A. (Informative) Draft Remarks from Authors 2056 The following items are currently under consideration for future 2057 revisions by the authors. 2059 o Whether to keep TLS-unique validation or not. 2061 o Whether to introduce password strengthening hashes other than 2062 PBKDF2 into the function pi(). This requires standardization of 2063 such other hash algorithms in IETF. 2065 o Whether to modify current definition of nIterPi, which is per- 2066 algorithm defined. To increase this parameter requires defining a 2067 new algorithm, possibly with reconsideration for other security 2068 parameters as well. 2070 o Whether to keep ph() function for legacy migration or not. 2072 o Adding test vectors for ensuring implementation correctness. 2074 o Possibly adding a method for servers to detect availability of 2075 Mutual authentication on client-side. 2077 Appendix B. (Informative) Draft Change Log 2079 B.1. Changes in Httpauth WG Revision 02 2081 o Major change: introduction of password-strengtheing function 2082 PBKDF2. 2084 o Changed Section 9 to adopt "list of requirements" style. Strict 2085 definition of state machine is now a derived, informational 2086 definition. 2088 B.2. Changes in Httpauth WG Revision 01 2090 o Changed "tls-key" verification to "tls-unique" verification, and 2091 "tls-cert" to "tls-server-end-point", adopting RFC 5929. 2093 o Adopted [I-D.ietf-precis-framework]. 2095 o Reverted reservation of "rekey-sid" and "rekey-method" parameters. 2097 o Degraded secure UI requirement to application note level, non- 2098 normative. 2100 o Adjusted levels of several requirements. 2102 o Added warning text for handling of exceptional 5XX responses. 2104 o Dropped several references for optional authentications, except 2105 one "Note". 2107 o Several textual fixes, improvements and revisions. 2109 B.3. Changes in Httpauth Revision 00 2111 o Changed the version token. 2113 o Renamed "verification tokens" to "Host verification tokens" and 2114 variables "v" to "vh" for clarification. (Back-ported from 2115 draft-oiwa-httpauth-multihop-template-00) 2117 B.4. Changes in HttpBis Revision 00 2119 None. 2121 B.5. Changes in Revision 12 2123 o Added a reason "authz-failed". 2125 B.6. Changes in Revision 11 2127 o Message syntax definition reverted to pre-07 style as httpbis-p1 2128 and p7 now defines a precise rule for parameter value parsing. 2130 o Replaced "stale" parameter with more infomative/extensive "reason" 2131 parameter in 401-INIT and 401-STALE. 2133 o Reserved "rekey-sid" and "rekey-method" parameters for future 2134 extensions. 2136 o Added descriptions for replacing/non-replacing existing 2137 technologies. 2139 B.7. Changes in Revision 10 2141 o The authentication extension parts (non-mandatory authentication 2142 and authentication controls) are separated to yet another draft. 2144 o The default auth-domain parameter is changed to the full scheme- 2145 host-port syntax, which is consistent with usual HTTP 2146 authentication framework behavior. 2148 o Provision for application channel binding is added. 2150 o Provision for proxy access authentication is added. 2152 o Bug fix: syntax specification of sid parameter was wrong: it was 2153 inconsistent with the type specified in the main text (the bug 2154 introduced in -07 draft). 2156 o Terminologies for headers are changed to be in harmony with 2157 httpbis drafts (e.g. field to parameter). 2159 o Syntax definitions are changed to use HTTP-extended ABNF syntax, 2160 and only the header values are shown for header syntax, in harmony 2161 with httpbis drafts. 2163 o Names of parameters and corresponding mathematical values are now 2164 renamed to more informative ones. The following list shows 2165 correspondence between the new and the old names. 2167 +------------+----------+-------------------------------------------+ 2168 | new name | old name | description | 2169 +------------+----------+-------------------------------------------+ 2170 | S_c1, S_s1 | s_a, s_b | client/server-side secret randoms | 2171 | K_c1, K_s1 | w_a, w_b | client/server-side exchanged key | 2172 | | | components | 2173 | kc1, ks1 | wa, wb | parameter names for those | 2174 | VK_c, VK_s | o_a, o_b | client/server-side key verifiers | 2175 | vkc, vks | oa, ob | parameter names for those | 2176 | z | z | session secrets | 2177 +------------+----------+-------------------------------------------+ 2179 B.8. Changes in Revision 09 2181 o The (default) cryptographic algorithms are separated to another 2182 draft. 2184 o Names of the messages are changed to more informative ones than 2185 before. The following is the correspondence table of those names: 2187 +-------------------+-----------------+-----------------------------+ 2188 | new name | old name | description | 2189 +-------------------+-----------------+-----------------------------+ 2190 | 401-INIT | 401-B0 | initial response | 2191 | 401-STALE | 401-B0-stale | session key expired | 2192 | req-KEX-C1 | req-A1 | client->server key exchange | 2193 | 401-KEX-S1 | 401-B1 | server->client key exchange | 2194 | req-VFY-C | req-A3 | client->server auth. | 2195 | | | verification | 2196 | 200-VFY-S | 200-B4 | server->client auth. | 2197 | | | verification | 2198 | 200-Optional-INIT | 200-Optional-B0 | initial with non-mandatory | 2199 | | | authentication | 2200 +-------------------+-----------------+-----------------------------+ 2202 B.9. Changes in Revision 08 2204 o The English text has been revised. 2206 B.10. Changes in Revision 07 2208 o Adapt to httpbis HTTP/1.1 drafts: 2210 * Changed definition of extensive-token. 2212 * LWSP continuation-line (%0D.0A.20) deprecated. 2214 o To simplify the whole spec, the type of nonce-counter related 2215 parameters are change from hex-integer to integer. 2217 o Algorithm tokens are renamed to include names of hash algorithms. 2219 o Clarified the session management, added details of server-side 2220 protocol decisions. 2222 o The whole draft was reorganized; introduction and overview has 2223 been rewritten. 2225 B.11. Changes in Revision 06 2227 o Integrated Optional Mutual Authentication to the main part. 2229 o Clarified the decision procedure for message recognitions. 2231 o Clarified that a new authentication request for any sub-requests 2232 in interactive clients may be silently discarded. 2234 o Typos and confusing phrases are fixed. 2236 o Several "future considerations" are added. 2238 B.12. Changes in Revision 05 2240 o A new parameter called "version" is added for supporting future 2241 incompatible changes with a single implementation. In the (first) 2242 final specification its value will be changed to 1. 2244 o A new header "Authentication-Control" is added for precise control 2245 of application-level authentication behavior. 2247 B.13. Changes in Revision 04 2249 o Changed text of patent licenses: the phrase "once the protocol is 2250 accepted as an Internet standard" is removed so that the sentence 2251 also covers the draft versions of this protocol. 2253 o The "tls-key" verification is now OPTIONAL. 2255 o Several description fixes and clarifications. 2257 B.14. Changes in Revision 03 2259 o Wildcard domain specifications (e.g. "*.example.com") are allowed 2260 for auth-domain parameters (Section 4.1). 2262 o Specification of the tls-cert verification is updated 2263 (incompatible change). 2265 o State transitions fixed. 2267 o Requirements for servers concerning w_a values are clarified. 2269 o RFC references are updated. 2271 B.15. Changes in Revision 02 2273 o Auth-realm is extended to allow full-scheme type. 2275 o A decision diagram for clients and decision procedures for servers 2276 are added. 2278 o 401-B1 and req-A3 messages are changed to contain authentication 2279 realm information. 2281 o Bugs on equations for o_A and o_B are fixed. 2283 o Detailed equations for the entire algorithm are included. 2285 o Elliptic-curve algorithms are updated. 2287 o Several clarifications and other minor updates. 2289 B.16. Changes in Revision 01 2291 o Several texts are rewritten for clarification. 2293 o Added several security consideration clauses. 2295 Authors' Addresses 2297 Yutaka Oiwa 2298 National Institute of Advanced Industrial Science and Technology 2299 Research Institute for Secure Systems 2300 3-11-46 Nakouji 2301 Amagasaki, Hyogo 2302 JP 2304 Email: mutual-auth-contact-ml@aist.go.jp 2306 Hajime Watanabe 2307 National Institute of Advanced Industrial Science and Technology 2308 Research Institute for Secure Systems 2309 Tsukuba Central 2 2310 1-1-1 Umezono 2311 Tsukuba-shi, Ibaraki 2312 JP 2314 Hiromitsu Takagi 2315 National Institute of Advanced Industrial Science and Technology 2316 Research Institute for Secure Systems 2317 Tsukuba Central 2 2318 1-1-1 Umezono 2319 Tsukuba-shi, Ibaraki 2320 JP 2321 Kaoru Maeda 2322 Lepidum Co. Ltd. 2323 #602, Village Sasazuka 3 2324 1-30-3 Sasazuka 2325 Shibuya-ku, Tokyo 2326 JP 2328 Tatsuya Hayashi 2329 Lepidum Co. Ltd. 2330 #602, Village Sasazuka 3 2331 1-30-3 Sasazuka 2332 Shibuya-ku, Tokyo 2333 JP 2335 Yuichi Ioku 2336 Individual