idnits 2.17.1 draft-ietf-httpauth-mutual-03.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 (August 19, 2014) is 3538 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-02 ** Obsolete normative reference: RFC 2898 (Obsoleted by RFC 8018) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-23) exists of draft-ietf-precis-framework-17 -- 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: 4 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: February 20, 2015 RISEC, AIST 6 K. Maeda 7 T. Hayashi 8 Lepidum 9 Y. Ioku 10 Individual 11 August 19, 2014 13 Mutual Authentication Protocol for HTTP 14 draft-ietf-httpauth-mutual-03 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 February 20, 2015. 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 . . . . . . . . . . . . . . . . . . 44 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 03 . . . . . . . . . . . . 46 111 B.2. Changes in Httpauth WG Revision 02 . . . . . . . . . . . . 46 112 B.3. Changes in Httpauth WG Revision 01 . . . . . . . . . . . . 47 113 B.4. Changes in Httpauth Revision 00 . . . . . . . . . . . . . 47 114 B.5. Changes in HttpBis Revision 00 . . . . . . . . . . . . . . 47 115 B.6. Changes in Revision 12 . . . . . . . . . . . . . . . . . . 47 116 B.7. Changes in Revision 11 . . . . . . . . . . . . . . . . . . 47 117 B.8. Changes in Revision 10 . . . . . . . . . . . . . . . . . . 48 118 B.9. Changes in Revision 09 . . . . . . . . . . . . . . . . . . 48 119 B.10. Changes in Revision 08 . . . . . . . . . . . . . . . . . . 49 120 B.11. Changes in Revision 07 . . . . . . . . . . . . . . . . . . 49 121 B.12. Changes in Revision 06 . . . . . . . . . . . . . . . . . . 49 122 B.13. Changes in Revision 05 . . . . . . . . . . . . . . . . . . 50 123 B.14. Changes in Revision 04 . . . . . . . . . . . . . . . . . . 50 124 B.15. Changes in Revision 03 . . . . . . . . . . . . . . . . . . 50 125 B.16. Changes in Revision 02 . . . . . . . . . . . . . . . . . . 50 126 B.17. Changes in Revision 01 . . . . . . . . . . . . . . . . . . 51 127 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51 129 1. Introduction 131 This document specifies a mutual authentication method for Hyper-Text 132 Transfer Protocol (HTTP). The method, called "Mutual Authentication 133 Protocol" in this document, provides a true mutual authentication 134 between an HTTP client and an HTTP server, using just a simple 135 password as a credential. 137 The authentication method proposed in this document has the following 138 main characteristics: 140 o It provides "true" mutual authentication: in addition to assuring 141 the server that the user knows the password, it also assures the 142 user that the server truly knows the user's encrypted password at 143 the same time. This makes it impossible for fake website owners 144 to persuade users that they have authenticated with the original 145 websites. 147 o It uses only passwords as the user's credential: unlike public- 148 key-based security algorithms, the method does not rely on secret 149 keys or other cryptographic data that have to be stored inside the 150 users' computers. The proposed method can be used as a drop-in 151 replacement to the current authentication methods like Basic or 152 Digest, while ensuring a much stronger level of security. 154 o It is secure: when the server fails to authenticate with a user, 155 the protocol will not reveal any tiny bit of information about the 156 user's password. 158 1.1. Terminology 160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 161 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 162 "OPTIONAL" in this document are to be interpreted as described in 163 [RFC2119]. 165 This document distinguishes the terms "client" and "user" in the 166 following way: A "client" is an entity understanding and talking HTTP 167 and the specified authentication protocol, usually computer software; 168 a "user" is a (usually natural) person who wants to access data 169 resources using "a client". 171 The term "natural numbers" refers to the non-negative integers 172 (including zero) throughout this document. 174 This document treats target (codomain) of hash functions to be octet 175 strings. The notation INT(H(s)) gives a numerical (natural-number) 176 output of hash function H applied to string s. 178 1.2. Document Structure and Related Documents 180 The entire document is organized as follows: 182 o Section 2 presents an overview of the protocol design. 184 o Sections 3 to 10 define a general framework of the Mutual 185 authentication protocol. This framework is independent of 186 specific cryptographic primitives. 188 o Section 11 describes properties needed for cryptographic 189 algorithms used with this protocol framework, and defines a few 190 functions which will be shared among such cryptographic 191 algorithms. 193 o The sections after that contain general normative and informative 194 information about the protocol. 196 o The appendices contain some information that may help developers 197 to implement the protocol. 199 In addition, there are two companion documents which are referred 200 from/related to this specification: 202 o [I-D.ietf-httpauth-mutual-algo]: defines a cryptographic 203 primitives which can be used with this protocol framework. [draft 204 note: it is separated from this document so that it may be 205 replaced with another crypto in future.] 207 o [I-D.ietf-httpauth-extension]: defines a small but useful 208 extensions to the current HTTP authentication framework so that it 209 can support application-level semantics of existing Web systems. 211 2. Protocol Overview 213 The protocol, as a whole, is designed as a natural extension to the 214 HTTP protocol [RFC7230] using a framework defined in [RFC7235]. 215 Internally, the server and the client will first perform a 216 cryptographic key exchange, using the secret password as a "tweak" to 217 the exchange. The key-exchange will only succeed when the secrets 218 used by the both peers are correctly related (i.e. generated from the 219 same password). Then, both peers will verify the authentication 220 results by confirming the sharing of the exchanged key. This section 221 describes a brief image of the 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 [RFC7230] and [RFC5234]. The 432 following elements are quoted from [RFC5234], [RFC7230] and 433 [RFC7235]: DIGIT, ALPHA, SP, auth-scheme, quoted-string, auth-param, 434 header-field, token, challenge, and credential. 436 The Mutual authentication protocol uses three headers: 437 WWW-Authenticate (in responses with status code 401), Authorization 438 (in requests), and Authentication-Info (in responses other than 401 439 status). These headers follow a common framework described in 440 [RFC7235]. The detailed meanings for these headers are contained in 441 Section 4. 443 The framework in [RFC7235] defines the syntax for the headers 444 WWW-Authenticate and Authorization as the syntax elements "challenge" 445 and "credentials", respectively. The "auth-scheme" contained in 446 those headers MUST be "Mutual" throughout this protocol 447 specification. The syntax for "challenge" and "credentials" to be 448 used with the "Mutual" auth-scheme SHALL be name-value pairs (#auth- 449 param), not the "b64token" defined in [RFC7235]. 451 The Authentication-Info: header used in this protocol SHALL contain 452 the value in same syntax as those the "WWW-Authenticate" header, i.e. 453 the "challenge" syntax element. 455 In HTTP, the WWW-Authenticate header may contain more than one 456 challenges. Client implementations SHOULD be aware of and be capable 457 of handle those cases correctly. 459 3.1. Values 461 The parameter values contained in challenge/credentials MUST be 462 parsed strictly conforming to the HTTP semantics (especially un- 463 quoting of the string parameter values). In this protocol, those 464 values are further categorized into the following value types: tokens 465 (bare-token and extensive-token), string, integer, hex-fixed-number, 466 and base64-fixed-number. 468 For clarity, implementations are RECOMMENDED to use the canonical 469 representations specified in the following subsections for sending 470 values. Recipients SHOULD accept both quoted and unquoted 471 representations interchangeably as specified in HTTP. 473 3.1.1. Tokens 475 For sustaining both security and extensibility at the same time, this 476 protocol defines a stricter sub-syntax for the "token" to be used. 477 The extensive-token values SHOULD follow the following syntax (after 478 HTTP value parsing): 480 bare-token = 1*(DIGIT / ALPHA / "-" / "_") 481 extension-token = "-" bare-token 1*("." bare-token) 482 extensive-token = bare-token / extension-token 483 Figure 3: BNF syntax for token values 485 The tokens (bare-token and extension-token) are case insensitive; 486 Senders SHOULD send these in lower-case, and receivers MUST accept 487 both upper- and lower-cases. When tokens are used as (partial) 488 inputs to any hash or other mathematical functions, it MUST always be 489 used in lower-case. 491 Extensive-tokens are used in this protocol where the set of 492 acceptable tokens may include non-standard extensions. Any non- 493 standard extensions of this protocol SHOULD use the extension-tokens 494 with format "-.", where is a 495 validly registered (sub-)domain name on the Internet owned by the 496 party who defines the extensions. 498 Bare-tokens and extensive-tokens are also used for parameter names 499 (of course in the unquoted form). Requirements for using the 500 extension-token for the parameter names are the same as the above. 502 The canonical format for bare-tokens and tokens are unquoted tokens. 504 3.1.2. Strings 506 All character strings MUST be encoded to octet strings using the 507 UTF-8 encoding [RFC3629] for the ISO 10646-1 character set 508 [ISO.10646-1.1993]. Such strings MUST NOT contain any leading BOM 509 characters (ZERO WIDTH NO-BREAK SPACE, U+FEFF or EF BB BF). Both 510 peers are RECOMMENDED to reject any invalid UTF-8 sequences that 511 might cause decoding ambiguities (e.g., containing <"> in the second 512 or later bytes of the UTF-8 encoded characters). 514 If strings are representing a domain name or URI that contains non- 515 ASCII characters, the host parts SHOULD be encoded as it is used in 516 the HTTP protocol layer (e.g. in a Host: header); under current 517 standards it will be the one defined in [RFC5890]. It SHOULD use 518 lower-case ASCII characters. 520 The canonical format for strings are quoted-string (as it may contain 521 equal signs, plus signs and slashes). 523 3.1.3. Numbers 525 The following syntax definitions gives a syntax for number-type 526 values: 528 integer = "0" / (%x31-39 *DIGIT) ; no leading zeros 529 hex-fixed-number = 1*(2(DIGIT / %x41-46 / %x61-66)) 530 base64-fixed-number = 1*( ALPHA / DIGIT / "+" / "/" ) 0*2"=" 532 Figure 4: BNF syntax for number types 534 The syntax definition of the integers only allows representations 535 that do not contain extra leading zeros. 537 The numbers represented as a hex-fixed-number MUST include an even 538 number of characters (i.e. multiples of eight bits). Those values 539 are case-insensitive, and SHOULD be sent in lower-case. When these 540 values are generated from any cryptographic values, they SHOULD have 541 their "natural length": if these are generated from a hash function, 542 these lengths SHOULD correspond to the hash size; if these are 543 representing elements of a mathematical set (or group), its lengths 544 SHOULD be the shortest for representing all the elements in the set. 545 For example, any results of SHA-256 hash function will be represented 546 by 64 characters, and any elements in 2048-bit prime field (modulo a 547 2048-bit integer) will be represented by 512 characters, regardless 548 of how much 0's will be appear in front of such representations. 549 Session-identifiers and other non-cryptographically generated values 550 are represented in any (even) length determined by the side who 551 generates it first, and the same length SHALL be used throughout the 552 all communications by both peers. 554 The numbers represented as base64-fixed-number SHALL be generated as 555 follows: first, the number is converted to a big-endian radix-256 556 binary representation as an octet string. The length of the 557 representation is determined in the same way as mentioned above. 558 Then, the string is encoded using the Base 64 encoding [RFC4648] 559 without any spaces and newlines. Implementations decoding base64- 560 fixed-number SHOULD reject any input data with invalid characters, 561 excess/insufficient paddings, or non-canonical pad bits (See Sections 562 3.1 to 3.5 of [RFC4648]). 564 The canonical format for integer and hex-fixed-number are unquoted 565 tokens, and that for base64-fixed-number is quoted-string. 567 4. Messages 569 In this section we define the seven kinds of messages used in the 570 authentication protocol along with the formats and requirements of 571 the headers for each message. 573 To determine which message are expected to be sent, see Sections 9 574 and 10. 576 In the descriptions below, the type of allowable values for each 577 header parameter is shown in parenthesis after each parameter name. 578 The "algorithm-determined" type means that the acceptable value for 579 the parameter is one of the types defined in Section 3, and is 580 determined by the value of the "algorithm" parameter. The parameters 581 marked "mandatory" SHALL be contained in the message. The parameters 582 marked "non-mandatory" MAY either be contained or omitted in the 583 message. Each parameter SHALL appear in each headers exactly once at 584 most. 586 All credentials and challenges MAY contain any parameters not 587 explicitly specified in the following sections. Recipients who do 588 not understand such parameters MUST silently ignore those. However, 589 all credentials and challenges MUST meet the following criteria: 591 o For responses, the parameters "reason", any "ks*" (where * stands 592 for any decimal integers), and "vks" are mutually exclusive: any 593 challenge MUST NOT contain two or more parameters among them. 594 They MUST NOT contain any "kc*" and "vkc" parameters. 596 o For requests, the parameters "kc*" (where * stands for any decimal 597 integers), and "vkc" are mutually exclusive and any challenge 598 MUST NOT contain two or more parameters among them. They MUST NOT 599 contain any "ks*" and "vks" parameters. 601 Every message in this section contains a "version" field, to detect 602 future incompatible revisions of the protocol. Implementations of 603 the protocol described in this specification MUST always send a token 604 "-wg-draft03", and recipients MUST reject messages which contain any 605 other value as a version, unless another specification defines a 606 behavior for that version. [[Editorial Note: This token is updated 607 on every draft revisions which will affect the wire protocol. It 608 will (shall) be updated to "1" in the final published RFC.]] 610 4.1. 401-INIT and 401-STALE 612 Every 401-INIT or 401-STALE message SHALL be a valid HTTP 401-status 613 (Authentication Required) message containing one (and only one: 614 hereafter not explicitly noticed) "WWW-Authenticate" header 615 containing a "reason" parameter in the challenge. The challenge 616 SHALL contain all of the parameters marked "mandatory" below, and MAY 617 contain those marked "non-mandatory". 619 version: (mandatory extensive-token) should be the token "-wg- 620 draft03". 622 algorithm: (mandatory extensive-token) specifies the 623 authentication algorithm to be used. The value MUST 624 be one of the tokens specified in 625 [I-D.ietf-httpauth-mutual-algo] or other supplemental 626 specification documentation. 628 validation: (mandatory extensive-token) specifies the method of 629 host validation. The value MUST be one of the tokens 630 described in Section 7, or the tokens specified in 631 other supplemental specification documentation. 633 auth-domain: (non-mandatory string) specifies the authentication 634 domain, the set of hosts for which the authentication 635 credentials are valid. It MUST be one of the strings 636 described in Section 5. If the value is omitted, it 637 is assumed to be the "single-server" type domain in 638 Section 5. 640 realm: (mandatory string) is a UTF-8 encoded string 641 representing the name of the authentication realm 642 inside the authentication domain. As specified in 643 [RFC7235], this value MUST always be sent in the 644 quoted-string form. 646 pwd-hash: (non-mandatory extensive-token) specifies the hash 647 algorithm (hereafter referred to by ph) used for 648 additionally hashing the password. The valid tokens 649 are 651 * none: ph(p) = p 653 * md5: ph(p) = MD5(p) 655 * digest-md5: ph(p) = MD5(username | ":" | realm | 656 ":" | p), the same value as MD5(A1) for "MD5" 657 algorithm in [RFC2617]. 659 * sha1: ph(p) = SHA1(p) 661 If omitted, the value "none" is assumed. The use of 662 "none" is desirable. 664 reason: (mandatory extensive-token) SHALL be an extensive- 665 token which describes the possible reason of the 666 failed authentication/authorization. Both servers and 667 clients SHALL understand and support the following 668 three tokens: 670 * initial: authentication was not tried because there 671 was no Authorization header in the corresponding 672 request. 674 * stale-session: the provided sid; in the request was 675 either unknown to or expired in the server. 677 * auth-failed: authentication trial was failed by 678 some reasons, possibly with a bad authentication 679 credentials. 681 Implementations MAY support the following tokens or 682 any extensive-tokens defined outside this 683 specification. If clients has received any unknown 684 tokens, these SHOULD treat these as if it were "auth- 685 failed" or "initial". 687 * reauth-needed: server-side application requires a 688 new authentication trial, regardless of the current 689 status. 691 * invalid-parameters: authentication was not even 692 tried in the server-side because some parameters 693 are not acceptable. 695 * internal-error: authentication was not even tried 696 in the server-side because there is some troubles 697 on the server-side. 699 * user-unknown: a special case of auth-failed, 700 suggesting that the provided user-name is invalid. 701 The use of this parameter is NOT RECOMMENDED for 702 security implications, except for special-purpose 703 applications which makes this value sense. 705 * invalid-credential: ditto, suggesting that the 706 provided user-name was valid but authentication was 707 failed. The use of this parameter is 708 NOT RECOMMENDED as the same as the above. 710 * authz-failed: authentication was successful, but 711 access to the specified resource is not authorized 712 to the specific authenticated user. (It is 713 different from 403 responses which suggest that the 714 reason of inaccessibility is other that 715 authentication.) 717 The algorithm specified in this header will determine the types 718 (among those defined in Section 3) and the values for K_c1, K_s1, 719 VK_c and VK_s. 721 Among these messages, those with the reason parameter of value 722 "stale-session" will be called "401-STALE" messages hereafter, 723 because these have a special meaning in the protocol flow. Messages 724 with any other reason parameters will be called "401-INIT" messages. 726 4.2. req-KEX-C1 728 Every req-KEX-C1 message SHALL be a valid HTTP request message 729 containing an "Authorization" header with a credential containing a 730 "kc1" parameter. 732 The credential SHALL contain the parameters with the following names: 734 version: (mandatory, extensive-token) should be the token "-wg- 735 draft03". 737 algorithm, validation, auth-domain, realm: MUST be the same value as 738 it is when received from the server. 740 user: (mandatory, string) is the UTF-8 encoded name of the 741 user. If this name comes from a user input, client 742 software SHOULD prepare the string using HTTPAUTHprep 743 [I-D.oiwa-precis-httpauthprep] before encoding it to 744 UTF-8. [[Editorial: merger with new SASLprep is being 745 considered and discussed in precis WG. Replace the 746 reference once it is done.]] 748 kc1: (mandatory, algorithm-determined) is the client-side 749 key exchange value K_c1, which is specified by the 750 algorithm that is used. 752 4.3. 401-KEX-S1 754 Every 401-KEX-S1 message SHALL be a valid HTTP 401-status 755 (Authentication Required) response message containing a 756 "WWW-Authenticate" header with a challenge containing a "ks1" 757 parameter. 759 The challenge SHALL contain the parameters with the following names: 761 version: (mandatory, extensive-token) should be the token "-wg- 762 draft03". 764 algorithm, validation, auth-domain, realm: MUST be the same value as 765 it is when received from the client. 767 sid: (mandatory, hex-fixed-number) MUST be a session 768 identifier, which is a random integer. The sid SHOULD 769 have uniqueness of at least 80 bits or the square of 770 the maximal estimated transactions concurrently 771 available in the session table, whichever is larger. 772 See Section 6 for more details. 774 ks1: (mandatory, algorithm-determined) is the server-side 775 key exchange value K_s1, which is specified by the 776 algorithm. 778 nc-max: (mandatory, integer) is the maximal value of nonce 779 counts that the server accepts. 781 nc-window: (mandatory, integer) the number of available nonce 782 slots that the server will accept. The value of the 783 nc-window parameter is RECOMMENDED to be 32 or more. 785 time: (mandatory, integer) represents the suggested time (in 786 seconds) that the client can reuse the session 787 represented by the sid. It is RECOMMENDED to be at 788 least 60. The value of this parameter is not directly 789 linked to the duration that the server keeps track of 790 the session represented by the sid. 792 path: (non-mandatory, string) specifies which path in the 793 URI space the same authentication is expected to be 794 applied. The value is a space-separated list of URIs, 795 in the same format as it was specified in domain 796 parameter [RFC2617] for the Digest authentications. 797 The all path elements contained in the parameter MUST 798 be inside the specified auth-domain; if not, clients 799 SHOULD ignore such elements. For better performance, 800 recognition of this parameter by clients are 801 significantly important. 803 4.4. req-VFY-C 805 Every req-VFY-C message SHALL be a valid HTTP request message 806 containing an "Authorization" header with a credential containing a 807 "vkc" parameter. 809 The parameters contained in the header are as follows: 811 version: (mandatory, extensive-token) should be the token "-wg- 812 draft03". 814 algorithm, validation, auth-domain, realm: MUST be the same value as 815 it is when received from the server for the session. 817 sid: (mandatory, hex-fixed-number) MUST be one of the sid 818 values that was received from the server for the same 819 authentication realm. 821 nc: (mandatory, integer) is a nonce value that is unique 822 among the requests sharing the same sid. The values 823 of the nonces SHOULD satisfy the properties outlined 824 in Section 6. 826 vkc: (mandatory, algorithm-determined) is the client-side 827 authentication verification value VK_c, which is 828 specified by the algorithm. 830 4.5. 200-VFY-S 832 Every 200-VFY-S message SHALL be a valid HTTP message that is not of 833 the 401 (Authentication Required) status, containing an 834 "Authentication-Info" header with a "vks" parameter. 836 The parameters contained in the header are as follows: 838 version: (mandatory, extensive-token) should be the token "-wg- 839 draft03". 841 sid: (mandatory, hex-fixed-number) MUST be the value 842 received from the client. 844 vks: (mandatory, algorithm-determined) is the server-side 845 authentication verification value VK_s, which is 846 specified by the algorithm. 848 The header MUST be sent before the content body: it MUST NOT be sent 849 in the trailer of a chunked-encoded response. If a "100 Continue" 850 response is sent from the server, the Authentication-Info header 851 SHOULD be included in that response, instead of the final response. 853 5. Authentication Realms 855 In this protocol, an "authentication realm" is defined as a set of 856 resources (URIs) for which the same set of user names and passwords 857 is valid for. If the server requests authentication for an 858 authentication realm that the client is already authenticated for, 859 the client will automatically perform the authentication using the 860 already-known secrets. However, for the different authentication 861 realms, the clients MUST NOT automatically reuse the user names and 862 passwords for another realm. 864 Just like in Basic and Digest access authentication protocols, Mutual 865 authentication protocol supports multiple, separate protection spaces 866 to be set up inside each host. Furthermore, the protocol supports 867 that a single authentication realm spans over several hosts within 868 the same Internet domain. 870 Each authentication realm is defined and distinguished by the triple 871 of an "authentication algorithm", an "authentication domain", and a 872 "realm" parameter. However, server operators are NOT RECOMMENDED to 873 use the same pair of an authentication domain and a realm for 874 different authentication algorithms. 876 The realm parameter is a string as defined in Section 4. 877 Authentication domains are described in the remainder of this 878 section. 880 An authentication domain specifies the range of hosts that the 881 authentication realm spans over. In this protocol, it MUST be one of 882 the following strings. 884 o Single-server type: The string in format "://" or 885 "://:", where , , and are 886 the corresponding URI parts of the request URI. If the default 887 port (i.e. 80 for http and 443 for https) is used for the 888 underlying HTTP communications, the port part MUST be omitted, 889 regardless of whether it was present in the request-URI. In other 890 cases, the port part MUST be present, and it MUST NOT contain 891 leading zeros. Use this when authentication is only valid for 892 specific protocol (such as https). This format is equivalent to 893 the ASCII serialization of a Web Origin, presented in Section 6.2 894 of [RFC6454]. 896 o Single-host type: The "host" part of the requested URI. This is 897 the default value. Authentication realms within this kind of 898 authentication domain will span over several protocols (i.e. http 899 and https) and ports, but not over different hosts. 901 o Wildcard-domain type: The string in format "*.", 902 where is either the host part of the requested 903 URI or any domain in which the requested host is included (this 904 means that the specification "*.example.com" is valid for all of 905 hosts "www.example.com", "web.example.com", 906 "www.sales.example.com" and "example.com"). The domain-postfix 907 sent from the servers MUST be equal to or included in a valid 908 Internet domain assigned to a specific organization: if clients 909 know, by some means such as a blacklist for HTTP cookies 910 [RFC6265], that the specified domain is not to be assigned to any 911 specific organization (e.g. "*.com" or "*.jp"), the clients are 912 RECOMMENDED to reject the authentication request. 914 In the above specifications, every "scheme", "host", and "domain" 915 MUST be in lower-case, and any internationalized domain names beyond 916 the ASCII character set SHALL be represented in the way they are sent 917 in the underlying HTTP protocol, represented in lower-case 918 characters; i.e. these SHALL be in the form of the LDH labels in IDNA 919 [RFC5890]. All "port"s MUST be in the shortest, unsigned, decimal 920 number notation. Not obeying these requirements will cause failure 921 of valid authentication attempts. 923 5.1. Resolving Ambiguities 925 In the above definitions of authentication domains, several domains 926 will overlap each other. If a client has already been authenticated 927 to several realms applicable to the same server, the client may have 928 a multiple list of the "path" parameters received with the 929 "401-KEX-S1" message (see Section 4). If these path lists have any 930 overlap, a single URI may belong to multiple possible candidate of 931 realms to be authenticated to. In such cases, clients faces an 932 ambiguity on deciding which credentials to be sent for a new request 933 (in steps 3 and 4 of the decision procedure presented in Section 9). 935 In such cases, clients MAY send requests which belongs to any of 936 these candidate realms freely, or it MAY simply send an 937 unauthenticated request and see for which realm the server request an 938 authentication. Server operators are RECOMMENDED to provide 939 properly-configured "path" parameters (more precisely, disjoint path 940 sets for each realms) for clients so that such ambiguities will not 941 occur. 943 The following procedure are one of the possible tactics for resolving 944 ambiguity in such cases. 946 o If the client has previously sent a request to the same URI, and 947 if it remembers the authentication realm requested by 401-INIT 948 messages at that time, use that realm. 950 o In other cases, use one of authentication realms representing the 951 most-specific authentication domains. From the list of possible 952 domain specifications shown above, each one earlier has priority 953 over ones described after that. 955 If there are several choices with different domain-postfix 956 specifications, the one that has the longest domain-postfix has 957 priority over ones with a shorter domain-postfix. 959 o If there are realms with the same authentication domain, there is 960 no defined priority: the client MAY choose any one of the possible 961 choices. 963 6. Session Management 965 In the Mutual authentication protocol, a session represented by an 966 sid is set up using first four messages (first request, 401-INIT, 967 req-KEX-C1 and 401-KEX-S1), and a "session secret" (z) associated 968 with the session is established. After sharing a session secret, 969 this session, along with the secret, can be used for one or more 970 requests for resources protected by the same realm in the same 971 server. Note that session management is only an inside detail of the 972 protocol and usually not visible to normal users. If a session 973 expires, the client and server SHOULD automatically re-establish 974 another session without informing the users. 976 Sessions and session identifiers are local to each server (defined by 977 scheme, host and port), even if an authentication domain covers 978 multiple servers; the clients MUST establish separate sessions for 979 each port of a host to be accessed. Furthermore, sessions and 980 identifiers are also local to each authentication realm, even if 981 these are provided from the same server. The same session 982 identifiers provided either from different servers or for different 983 realms MUST be treated as independent ones. 985 The server SHOULD accept at least one req-VFY-C request for each 986 session, given that the request reaches the server in a time window 987 specified by the timeout parameter in the 401-KEX-S1 message, and 988 that there are no emergent reasons (such as flooding attacks) to 989 forget the sessions. After that, the server MAY discard any session 990 at any time and MAY send 401-STALE messages for any req-VFY-C 991 requests. 993 The client MAY send two or more requests using a single session 994 specified by the sid. However, for all such requests, each value of 995 the nonce (in the nc parameter) MUST satisfy the following 996 conditions: 998 o It is a natural number. 1000 o The same nonce was not sent within the same session. 1002 o It is not larger than the nc-max value that was sent from the 1003 server in the session represented by the sid. 1005 o It is larger than (largest-nc - nc-window), where largest-nc is 1006 the maximal value of nc which was previously sent in the session, 1007 and nc-window is the value of the nc-window parameter which was 1008 received from the server in the session. 1010 The last condition allows servers to reject any nonce values that are 1011 "significantly" smaller than the "current" value (defined by the 1012 value of nc-window) of the nonce used in the session involved. In 1013 other words, servers MAY treat such nonces as "already received". 1014 This restriction enables servers to implement duplicated nonce 1015 detection in a constant amount of memory (for each session). 1017 Servers MUST check for duplication of the received nonces, and if any 1018 duplication is detected, the server MUST discard the session and 1019 respond with a 401-STALE message, as outlined in Section 10. The 1020 server MAY also reject other invalid nonce values (such as ones above 1021 the nc-max limit) by sending a 401-STALE message. 1023 For example, assume the nc-window value of the current session is 32, 1024 nc-max is 100, and that the client has already used the following 1025 nonce values: {1-20, 22, 24, 30-38, 45-60, 63-72}. Then the nonce 1026 values that can be used for next request is one of the following set: 1027 {41-44, 61-62, 73-100}. The values {0, 21, 23, 25-29, 39-40} MAY be 1028 rejected by the server because they are not above the current "window 1029 limit" (40 = 72 - 32). 1031 Typically, clients can ensure the above property by using a 1032 monotonically-increasing integer counter that counts from zero upto 1033 the value of nc-max. 1035 The values of the nonces and any nonce-related values MUST always be 1036 treated as natural numbers within an infinite range. Implementations 1037 which uses fixed-width integer representations, fixed-precision 1038 floating numbers or similar representations SHOULD NOT reject any 1039 larger values which overflow such representative limits, and MUST NOT 1040 silently truncate it using any modulus-like rounding operation (e.g. 1041 by mod 2^32). Instead, the whole protocol is carefully designed so 1042 that recipients MAY replace any such overflowed values (e.g. 2^80) 1043 with some reasonably-large maximal representative integer (e.g. 2^31 1044 - 1 or others). 1046 7. Host Validation Methods 1048 The "validation method" specifies a method to "relate" (or "bind") 1049 the mutual authentication processed by this protocol with other 1050 authentications already performed in the underlying layers and to 1051 prevent man-in-the-middle attacks. It decides the value vh that is 1052 an input to the authentication protocols. 1054 When HTTPS or other possible secure transport is used, this 1055 corresponds to the idea of "channel binding" described in [RFC5929]. 1056 Even when HTTP is used, similar, but somewhat limited, "binding" is 1057 performed to prevent a malicious server from trying to authenticate 1058 themselves to another server as a valid user by forwarding the 1059 received credentials. 1061 The valid tokens for the validation parameter and corresponding 1062 values of vh are as follows: 1064 host: host-name validation: The value vh will be the ASCII 1065 string in the following format: 1066 "://:", where , , 1067 and are the URI components corresponding to the 1068 currently accessing resource. The scheme and host are 1069 in lower-case, and the port is in a shortest decimal 1070 representation. Even if the request-URI does not have 1071 a port part, v will include the default port number. 1073 tls-server-end-point: TLS endpoint (certificate) validation: The 1074 value vh will be the octet string of the hash value of 1075 the server's public key certificate used in the 1076 underlying TLS [RFC5246] (or SSL) connection, 1077 processed as specified in Section 4.1 of [RFC5929]. 1079 [[Pending editorial issue: a small security issue is 1080 pending around here, awaiting analysis and WG 1081 discussions for final adoption.]] 1083 tls-unique: TLS shared-key validation: The value v will be the 1084 channel binding material derived from the Finished 1085 messages, as defined in Section 3.1 of [RFC5929]. 1087 If the HTTP protocol is used on a non-encrypted channel (TCP and 1088 SCTP, for example), the validation type MUST be "host". If HTTP/TLS 1089 [RFC2818] (HTTPS) protocol is used with the server certificates, the 1090 validation type MUST be "tls-server-end-point". If HTTP/TLS protocol 1091 is used with an anonymous Diffie-Hellman key exchange, the validation 1092 type MUST be "tls-unique" (see the note below). 1094 Implementations supporting a Mutual authentication over the HTTPS 1095 protocol SHOULD support the "tls-server-end-point" validation. 1096 Support for "tls-unique" validation is OPTIONAL for both the servers 1097 and clients. 1099 If the validation type "tls-server-end-point" is used, the server 1100 certificate provided on TLS connection MUST be verified at least to 1101 make sure that the server actually owns the corresponding secret key. 1102 (Note: this verification is automatic in some RSA-based key exchanges 1103 but NOT automatic in Diffie-Hellman-based key exchanges with separate 1104 exchange for server verifications.) 1106 Clients MUST validate this parameter upon reception of the 401-INIT 1107 messages. 1109 Note: The protocol defines two variants for validation on the TLS 1110 connections. The "tls-unique" method is more secure. However, there 1111 are some situations where tls-server-end-point is more preferable. 1113 o When TLS accelerating proxies are used, it is difficult for the 1114 authenticating server to acquire the TLS key information that is 1115 used between the client and the proxy. This is not the case for 1116 client-side "tunneling" proxies using a CONNECT method extension 1117 of HTTP. 1119 o When a black-box implementation of the TLS protocol is used on 1120 either peer. 1122 7.1. Applicability notes 1124 When the client is a Web browser with any scripting capabilities, the 1125 underlying TLS channel used with HTTP/TLS MUST provide server 1126 identity verification. This means (1) the anonymous Diffie-Hellman 1127 key exchange cipher-suite MUST NOT be used, and (2) the verification 1128 of the server certificate provided from the server MUST be performed. 1130 For other systems, when the underlying TLS channel used with HTTP/TLS 1131 does not perform server identity verification, the client SHOULD 1132 ensure that all the responses are validated using the Mutual 1133 authentication protocol, regardless of the existence of the 401-INIT 1134 responses. 1136 7.2. Interoperability notes on tls-unique 1138 As described in the interoperability note in the above channel 1139 binding specification, the tls-unique verification value will be 1140 changed by possible TLS renegotiation, causing an interoperability 1141 problem. TLS re-negotiations are used in several HTTPS server 1142 implementations for enforcing some security properties (such as 1143 cryptographic strength) for some specific responses. 1145 If an implementation supports "tls-unique" verification method, the 1146 following caution SHOULD be taken: 1148 o Both peers must be aware that the values vh used for vkc (in 1149 req-VFY-C) and for vks (in 200-VFY-S) may be different. These 1150 values MUST be retrieved from underlying TLS libraries each time 1151 it is used. 1153 o After calculating value vh and vkc to send a req-VFY-C request, 1154 Clients SHOULD NOT initiate TLS renegotiation until the end of the 1155 corresponding response header is received. Exceptionally, Clients 1156 can and SHOULD perform TLS re-negotiation as a response to 1157 server's request for TLS renegotiation, occurring before the top 1158 of response header. 1160 8. Authentication Extensions 1162 Interactive clients (e.g. Web browsers) supporting this protocol are 1163 RECOMMENDED to support non-mandatory authentication and the 1164 Authentication-Control header defined in 1165 [I-D.ietf-httpauth-extension], except the "auth-style" parameter. 1166 This specification also proposes (however, not mandates) default 1167 "auth-style" to be "non-modal". Web applications SHOULD however 1168 consider the security impacts of the behaviors of clients that do not 1169 support these headers. 1171 Authentication-initializing messages with the 1172 Optional-WWW-Authenticate header are used only where 401-INIT 1173 response is valid. It will not replace other 401-type messages such 1174 as 401-STALE and 401-KEX-S1. 1176 9. Decision Procedure for Clients 1178 9.1. General Principles and Requirements 1180 To securely implement the protocol, the user client must be careful 1181 about accepting the authenticated responses from the server. This 1182 also holds true for the reception of "normal responses" (responses 1183 which do not contain Mutual-related headers) from HTTP servers. 1185 As usual in the HTTP authentication, a single user-level request may 1186 result in exchange of two-or-more HTTP requests and responses in 1187 sequence. The following care MUST be taken by the all clients 1188 implementing this protocol: 1190 o Any kinds of "normal responses" MUST only be accepted for the very 1191 first request in the sequence. Any "normal responses" returned 1192 for the second or later request in the sequence SHALL be 1193 considered invalid. 1195 o In the same principle, any responses which refer to, or request 1196 changing to, the authentication realm different from the client's 1197 request MUST only be accepted for the very first request in the 1198 sequence. Any kind of responses referring to the different realms 1199 which are returned for the second or later request in the sequence 1200 SHALL be considered invalid. 1202 o A req-KEX-C1 message MAY be sent either as a initial request or as 1203 a response to 401-INIT, and 401-STALE. However, it SHOULD NOT be 1204 sent more than once in the sequence for a single authentication 1205 realm, to avoid infinite loops of messages. A 401-KEX-S1 response 1206 MUST be accepted only when the corresponding request is 1207 req-KEX-C1. 1209 o A req-VFY-C message MAY be sent if there is a valid session key 1210 shared between the client and the server, established by 1211 req-KEX-C1 and 401-KEX-S1. If any response with 401 status is 1212 returned for such a message, the corresponding session key SHOULD 1213 be discarded as unusable. 1214 Especially, upon the reception of response 401-STALE, the client 1215 SHOULD try establishing a new session by sending req-KEX-C1, but 1216 only once within the request/response sequence. 1218 o A 200-VFY-S message MUST be accepted only as a response to 1219 req-VFY-C and nothing else. The VK_s field of such response 1220 message MUST always be checked against the correct value, and if 1221 it is incorrect, the whole response SHOULD be considered invalid. 1222 Any content, both the content body and the headers, of such an 1223 invalid response SHOULD be ignored and discarded. 1225 The final status of the client request following the message exchange 1226 sequence shall be determined as follows: 1228 o AUTH-SUCCEED: A 200-VFY-S message with the correct VK_s value is 1229 returned to the req-VFY-C request in the sequence. 1231 o AUTH-REQUIRED: Two cases exists. 1233 * A 401-INIT message is returned from the server, and the client 1234 does not know how to authenticate to the given authentication 1235 realm. 1237 * A 401-INIT response is returned for req-VFY-C (or req-KEX-C1), 1238 which means the user-supplied authentication credentials are 1239 not accepted. 1241 o UNAUTHENTICATED: a normal response is returned for an initial 1242 request of any kind in the sequence. 1244 Any kind of response (including a normal response) other than those 1245 explicitly allowed in the above rules SHOULD be interpreted as a 1246 fatal communication error. In such cases, the clients MUST NOT 1247 process any data (the response body and other content-related 1248 headers) sent from the server. However, to handle exceptional error 1249 cases, clients MAY accept a message without an Authentication-Info 1250 header, if it is a Server-Error (5xx) status. In such cases, they 1251 SHOULD be careful about processing the body of the content (ignoring 1252 it is still RECOMMENDED, as it may possibly be forged by intermediate 1253 attackers,) and the client will be in the "UNAUTHENTICATED" status 1254 then. 1256 If a request is a sub-request for a resource included in another 1257 resources (e.g., embedded images, style sheets, frames etc.), clients 1258 MAY treat an AUTH-REQUESTED status as the same as UNAUTHENTICATED 1259 status. In other words, the client MAY ignore server's request to 1260 start authentication with new credentials via sub-requests. 1262 9.2. State machine for the client-side 1264 The following state machine describes the possible request-response 1265 sequences derived from the above general rules. If implementors are 1266 not quite sure on the security consequences of the above rules, it is 1267 strongly RECOMMENDED to follow the decision procedure below. In 1268 particular, clients SHOULD NOT accept "normal responses" unless 1269 explicitly allowed in the rules. The labels on the steps are for 1270 informational purposes only. Action entries within each step are 1271 checked in top-to-bottom order, and the first clause satisfied SHOULD 1272 be taken. 1274 Step 1 (step_new_request): 1275 If the client software needs to access a new Web resource, check 1276 whether the resource is expected to be inside some authentication 1277 realm for which the user has already been authenticated by the 1278 Mutual authentication scheme. If yes, go to Step 2. Otherwise, 1279 go to Step 5. 1281 Step 2: 1282 Check whether there is an available sid for the authentication 1283 realm you expect. If there is one, go to Step 3. Otherwise, go 1284 to Step 4. 1286 Step 3 (step_send_vfy_1): 1287 Send a req-VFY-C request. 1289 * If you receive a 401-INIT message with a different 1290 authentication realm than expected, go to Step 6. 1292 * If you receive a 401-STALE message, go to Step 9. 1294 * If you receive a 401-INIT message, go to Step 13. 1296 * If you receive a 200-VFY-S message, go to Step 14. 1298 * If you receive a normal response, go to Step 11. 1300 Step 4 (step_send_kex1_1): 1301 Send a req-KEX-C1 request. 1303 * If you receive a 401-INIT message with a different 1304 authentication realm than expected, go to Step 6. 1306 * If you receive a 401-KEX-S1 message, go to Step 10. 1308 * If you receive a 401-INIT message with the same authentication 1309 realm, go to Step 13 (see Note 1). 1311 * If you receive a normal response, go to Step 11. 1313 Step 5 (step_send_normal_1): 1314 Send a request without any Mutual authentication headers. 1316 * If you receive a 401-INIT message, go to Step 6. 1318 * If you receive a normal response, go to Step 11. 1320 Step 6 (step_rcvd_init): 1321 Check whether you know the user's password for the requested 1322 authentication realm. If yes, go to Step 7. Otherwise, go to 1323 Step 12. 1325 Step 7: 1326 Check whether there is an available sid for the authentication 1327 realm you expect. If there is one, go to Step 8. Otherwise, go 1328 to Step 9. 1330 Step 8 (step_send_vfy): 1331 Send a req-VFY-C request. 1333 * If you receive a 401-STALE message, go to Step 9. 1335 * If you receive a 401-INIT message, go to Step 13. 1337 * If you receive a 200-VFY-S message, go to Step 14. 1339 Step 9 (step_send_kex1): 1340 Send a req-KEX-C1 request. 1342 * If you receive a 401-KEX-S1 message, go to Step 10. 1344 * If you receive a 401-INIT message, go to Step 13 (See Note 1). 1346 Step 10 (step_rcvd_kex1): 1347 Send a req-VFY-C request. 1349 * If you receive a 401-INIT message, go to Step 13. 1351 * If you receive a 200-VFY-S message, go to Step 14. 1353 Step 11 (step_rcvd_normal): 1354 The requested resource is out of the authenticated area. The 1355 client will be in the "UNAUTHENTICATED" status. If the response 1356 contains a request for authentications other than Mutual, it MAY 1357 be handled normally. 1359 Step 12 (step_rcvd_init_unknown): 1360 The requested resource requires a Mutual authentication, and the 1361 user is not yet authenticated. The client will be in the "AUTH- 1362 REQUESTED" status, and is RECOMMENDED to process the content sent 1363 from the server, and to ask user for a user name and a password. 1364 When those are supplied from the user, proceed to Step 9. 1366 Step 13 (step_rcvd_init_failed): 1367 For some reason the authentication failed: possibly the password 1368 or the username is invalid for the authenticated resource. 1369 Forget the password for the authentication realm and go to Step 1370 12. 1372 Step 14 (step_rcvd_vfy): 1373 The received message is the 200-VFY-S message, which SHALL always 1374 contain a vks field. Check the validity of the received VK_s 1375 value. If it is equal to the expected value, it means that the 1376 mutual authentication has succeeded. The client will be in the 1377 "AUTH-SUCCEEDED" status. 1379 If the value is unexpected, it is a fatal communication error. 1381 If a user explicitly requests to log out (via user interfaces), 1382 the client MUST forget the user's password, go to step 5 and 1383 reload the current resource without an authentication header. 1385 Note 1: These transitions MAY be accepted by clients, but 1386 NOT RECOMMENDED for servers to initiate. 1388 Figure 5 shows a diagram of the client-side state. 1390 =========== -(11)------------ 1391 NEW REQUEST ( UNAUTHENTICATED ) 1392 =========== ----------------- 1393 | ^ normal 1394 v | response 1395 +(1)-------------------+ NO +(5)----------+ 1396 | The requested URI |--------------------------->| send normal | 1397 | known to be auth'ed? | | request | 1398 +----------------------+ +-------------+ 1399 YES | 401-INIT 401-INIT| 1400 | with a different realm | 1401 | -----------------------------------. | 1402 | / v v 1403 | | -(12)------------ NO +(6)--------+ 1404 | | ( AUTH-REQUESTED )<------| user/pass | 1405 | | ----------------- | known? | 1406 | | +-----------+ 1407 | | |YES 1408 v | v 1409 +(2)--------+ | +(7)--------+ 1410 | session | | | session | NO 1411 NO /| available?| | | available?|\ 1412 / +-----------+ | +-----------+ | 1413 / |YES | |YES | 1414 | | /| | | 1415 | v / | 401- 401- v | 1416 | +(3)--------+ | INIT --(13)---------- INIT +(8)--------+ | 1417 | | send |--+----->/ AUTH-REQUESTED \<-------| send | | 1418 | /| req-VFY-C | | \forget password / | req-VFY-C | | 1419 \/ +-----------+ / ---------------- /+-----------+ | 1420 /\ \ \/ ^ 401-INIT | |401- | 1421 | ------ \/\ 401-STALE | | | STALE / 1422 | \ /\ -----------------+--------------+---. | / 1423 | | / \ | | | | / 1424 | v / | 401- | 401- | v v v 1425 | +(4)--------+ | KEX-S1 +(10)-------+ KEX-S1 | +(9)--------+ 1426 | | send |-|--------->| send |<-------+-| send | 1427 | --| req-KEX-C1| | | req-VFY-C | | | req-KEX-C1| 1428 |/ +-----------+ | +-----------+ | +-----------+ 1429 | |200-VFY-S | 200-VFY-S| ^ 1430 |normal | |200-VFY-S / | 1431 |response | v / ================== 1432 v \ -(14)--------- / USER/PASS INPUTTED 1433 -(11)------------ ------->( AUTH-SUCCEED )<-- ================== 1434 ( UNAUTHENTICATED ) -------------- 1435 ----------------- 1437 Figure 5: State diagram for clients 1439 10. Decision Procedure for Servers 1441 Each server SHOULD have a table of session states. This table need 1442 not be persistent over a long term; it MAY be cleared upon server 1443 restart, reboot, or others. Each entry in the table SHOULD contain 1444 at least the following information: 1446 o The session identifier, the value of the sid parameter. 1448 o The algorithm used. 1450 o The authentication realm. 1452 o The state of the protocol: one of "key exchanging", 1453 "authenticated", "rejected", or "inactive". 1455 o The user name received from the client 1457 o The boolean flag noting whether or not the session is fake. 1459 o When the state is "key exchanging", the values of K_c1 and S_s1. 1461 o When the state is "authenticated", the following information: 1463 * The value of the session secret z 1465 * The largest nc received from the client (largest-nc) 1467 * For each possible nc values between (largest-nc - nc- 1468 window + 1) and max_nc, a flag whether or not a request with 1469 the corresponding nc has been received. 1471 The table MAY contain other information. 1473 Servers SHOULD respond to the client requests according to the 1474 following procedure: (See Note 1 below for 401-INIT message with * 1475 marks) 1477 o When the server receives a normal request: 1479 * If the requested resource is not protected by the Mutual 1480 Authentication, send a normal response. 1482 * If the resource is protected by the Mutual Authentication, send 1483 a 401-INIT response. 1485 o When the server receives a req-KEX-C1 request: 1487 * If the requested resource is not protected by the Mutual 1488 Authentication, send a normal response. 1490 * If the authentication realm specified in the req-KEX-C1 request 1491 is not the expected one, send a 401-INIT response. 1493 * If the server cannot validate the parameter kc1, send a 1494 401-INIT (*) response. 1496 * If the received user name is either invalid, unknown or 1497 unacceptable, create a new session, mark it a "fake" session, 1498 compute a random value as K_s1, and send a fake 401-KEX-S1 1499 response. (Note 2) 1501 * Otherwise, create a new session, compute K_s1 and send a 1502 401-KEX-S1 response. 1504 The created session has the "key exchanging" state. 1506 o When the server receives a req-VFY-C request: 1508 * If the requested resource is not protected by the Mutual 1509 Authentication, send a normal response. 1511 * If the authentication realm specified in the req-VFY-C request 1512 is not the expected one, send a 401-INIT response. 1514 If none of above holds true, the server will lookup the session 1515 corresponding to the received sid and the authentication realm. 1517 * If the session corresponding to the received sid could not be 1518 found, or it is in the "inactive" state, send a 401-STALE 1519 response. 1521 * If the session is in the "rejected" state, send either a 1522 401-INIT (*) or a 401-STALE message. 1524 * If the session is in the "authenticated" state, and the request 1525 has an nc value that was previously received from the client, 1526 send a 401-STALE message. The session SHOULD be changed to the 1527 "inactive" status. 1529 * If the nc value in the request is larger than the nc-max 1530 parameter sent from the server, or if it is not larger then 1531 (largest-nc - nc-window) (when in "authenticated" status), the 1532 server MAY (but not REQUIRED to) send a 401-STALE message. The 1533 session SHOULD be changed to the "inactive" status if so. 1535 * If the session is a "fake" session, or if the received vkc is 1536 incorrect, then send a 401-INIT (*) response. If the session 1537 is in the "key exchanging" state, it SHOULD be changed to the 1538 "rejected" state; otherwise, it MAY either be changed to the 1539 "rejected" status or kept in the previous state. 1541 * Otherwise, send a 200-VFY-S response. If the session was in 1542 the "key exchanging" state, the session SHOULD be changed to an 1543 "authenticated" state. The maximum nc and nc flags of the 1544 state SHOULD be updated properly. 1546 At any time, the server MAY change any state entries with both the 1547 "rejected" and "authenticated" statuses to the "inactive" status, and 1548 MAY discard any "inactive" states from the table. The entries with 1549 the "key exchanging" status SHOULD be kept unless there is an 1550 emergency situation such as a server reboot or a table capacity 1551 overflow. 1553 Note 1: In relation with, and following the specification of the 1554 optional authentication defined in [I-D.ietf-httpauth-extension], the 1555 401-INIT messages marked with the asterisks can not be replaced with 1556 a successful responses with an Optional-WWW-Authenticate header. 1557 Every other 401-INIT can be a response with an 1558 Optional-WWW-Authenticate. 1560 Note 2: the server SHOULD NOT send a 401-INIT response in this case, 1561 because it will leak the information to the client that the specified 1562 user will not be accepted. Instead, postpone it to the response for 1563 the next req-VFY-C request. 1565 11. Authentication Algorithms 1567 Cryptographic authentication algorithms which are used with this 1568 protocol will be defined separately. The algorithm definition MUST 1569 at least provide a definitions for the following functions: 1571 o The server-side authentication credential J, derived from user- 1572 side authentication credential pi. 1574 o Key exchange values K_c1, K_s1 (exchanged on wire) and S_c1, S_s1 1575 (kept secret in each peer). 1577 o Shared secret z, to be computed in both server-side and client 1578 side. 1580 o A hash function H to be used with the protocol, along with its 1581 output size hSize. 1583 o The number of iteration for password hasing nIterPi, if it uses 1584 the default password hashing function defined below. 1586 Specifications for cryptographic algorithms used with this framework 1587 MUST specify whether these will use the default functions defined 1588 below for the functions pi, VK_c, and VK_s; or, these will define 1589 their own versions for these functions. 1591 All algorithm used with this protocol SHOULD provide secure mutual 1592 authentication between client and servers, and generate a 1593 cryptographically strong shared secret value z, equivalently strong 1594 to or stronger than the hash function H. If any passwords (or pass- 1595 phrases or any equivalents, i.e. weak secrets) are involved, these 1596 SHOULD NOT be guessable from any data transmitted in the protocol, 1597 even if an attacker (either an eavesdropper or an active server) 1598 knows the possible thoroughly-searchable candidate list of the 1599 passwords. Furthermore, if possible, the function for deriving 1600 server-side authentication credential J is RECOMMENDED to be one-way 1601 so that pi should not be easily computed from J(pi). 1603 11.1. Support Functions and Notations 1605 In this section we define several support functions and notations to 1606 be shared by several algorithm definitions: 1608 The integers in the specification are in decimal, or in hexadecimal 1609 when prefixed with "0x". 1611 The function octet(c) generates a single octet string whose code 1612 value is equal to c. The operator |, when applied to octet strings, 1613 denotes the concatenation of two operands. 1615 The function VI encodes natural numbers into octet strings in the 1616 following manner: numbers are represented in big-endian radix-128 1617 string, where each digit is represented by a octet within 0x80-0xff 1618 except the last digit represented by a octet within 0x00-0x7f. The 1619 first octet MUST NOT be 0x80. For example, VI(i) = octet(i) for i < 1620 128, and VI(i) = octet(0x80 + (i >> 7)) | octet(i & 127) for 128 <= i 1621 < 16384. This encoding is the same as the one used for the 1622 subcomponents of object identifiers in the ASN.1 encoding 1623 [ITU.X690.1994], and available as a "w" conversion in the pack 1624 function of several scripting languages. 1626 The function VS encodes a variable-length octet string into a 1627 uniquely-decoded, self-delimited octet string, as in the following 1628 manner: 1630 VS(s) = VI(length(s)) | s 1632 where length(s) is a number of octets (not characters) in s. 1634 Some examples: 1636 VI(0) = "\000" (in C string notation) 1638 VI(100) = "d" 1640 VI(10000) = "\316\020" 1642 VI(1000000) = "\275\204@" 1644 VS("") = "\000" 1646 VS("Tea") = "\003Tea" 1648 VS("Caf" [in UTF-8]) = "\005Caf\303\251" 1650 VS([10000 "a"s]) = "\316\020aaaaa..." (10002 octets) 1652 (Note: Unlike the colon-separated notion used in the Basic/Digest 1653 HTTP authentication scheme, the string generated by a concatenation 1654 of the VS-encoded strings will be unique, regardless of the 1655 characters included in the strings to be encoded.) 1657 The function OCTETS converts an integer into the corresponding radix- 1658 256 big-endian octet string having its natural length: See 1659 Section 3.1.3 for the definition of "natural length". 1661 The function INT converts an octet string into a natural number, 1662 where the input string is treated as a radix-256 big-endian notation. 1663 The identity INT(OCTETS(n)) = n always holds for any natural number 1664 n. 1666 11.2. Default Functions for Algorithms 1668 The functions defined in this section are common default functions 1669 among authentication algorithms. 1671 The client-side password-based (credential) pi used by this 1672 authentication is a natural number derived in the following manner: 1674 pi = INT(PBKDF2(HMAC_H, ph(password), VS(algorithm) | VS(auth-domain) 1675 | VS(realm) | VS(username), nIterPi, hSize / 8)), 1676 where 1678 o PBKDF2 is the password-based key derivation function defined in 1679 [RFC2898], 1681 o HMAC_H is the HMAC function, defined in [RFC2104], composed from 1682 the hash function H, and 1684 o hSize is the output size of hash H, counted in bits. 1686 The values of algorithm, realm, and auth-domain are taken from the 1687 values contained in the 401-INIT message. The function ph is 1688 determined by the value of the pwd-hash parameter given in a 401-INIT 1689 message. If the password comes from a user input, it SHOULD first be 1690 prepared using [I-D.oiwa-precis-httpauthprep]. Then, the password 1691 SHALL be encoded as a UTF-8 string before passed to ph. 1693 The values VK_c and VK_s are derived by the following equation. 1695 VK_c = INT(H(octet(4) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | 1696 VI(nc) | VS(vh))) 1698 VK_s = INT(H(octet(3) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | 1699 VI(nc) | VS(vh))) 1701 12. Application Channel Binding 1703 Applications and upper-layer communication protocols may need 1704 authentication binding to the HTTP-layer authenticated user. Such 1705 applications MAY use the following values as a standard shared 1706 secret. 1708 These values are parameterized with an optional octet string (t) 1709 which may be arbitrarily chosen by each applications or protocols. 1710 If there is no appropriate value to be specified, use a null string 1711 for t. 1713 For applications requiring binding to either an authenticated user or 1714 a shared-key session (to ensure that the requesting client is 1715 certainly authenticated), the following value b_1 MAY be used. 1717 b_1 = H(H(octet(6) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VI(0) 1718 | VS(vh)) | VS(t)). 1720 For applications requiring binding to a specific request (to ensure 1721 that the payload data is generated for the exact HTTP request), the 1722 following value b_2 MAY be used. 1724 b_2 = H(H(octet(7) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VI(nc) 1725 | VS(vh)) | VS(t)). 1727 Note: Channel bindings to lower-layer transports (TCP and TLS) are 1728 defined in Section 7. 1730 13. Application for Proxy Authentication 1732 The authentication scheme defined by the previous sections can be 1733 applied (with modifications) for proxy authentications. In such 1734 cases, the following alterations MUST be applied: 1736 o The 407 status is to be sent and recognized for places where the 1737 401 status is used, 1739 o Proxy-Authenticate: header is to be used for places where WWW- 1740 Authenticate: is used, 1742 o Proxy-Authorization: header is to be used for places where 1743 Authorization: is used, 1745 o Proxy-Authentication-Info: header is to be used for places where 1746 Authentication-Info: is used, 1748 o The auth-domain parameter is fixed to the host-name of the proxy, 1749 which means to cover all requests processed through the specific 1750 proxy, 1752 o The limitation for the paths contained in the path parameter of 1753 401-KEX-S1 messages is disregarded, 1755 o The omission of the path parameter of 401-KEX-S1 messages means 1756 that the authentication realm will potentially cover all requests 1757 processed by the proxy, 1759 o The scheme, host name and the port of the proxy is used for host 1760 validation tokens, and 1762 o Authentication extensions in [I-D.ietf-httpauth-extension] are not 1763 applicable. 1765 14. Methods to Extend This Protocol 1767 If a private extension to this protocol is implemented, it MUST use 1768 the extension-tokens defined in Section 3 to avoid conflicts with 1769 this protocol and other extensions. (standardized or being- 1770 standardizing extensions MAY use either bare-tokens or extension- 1771 tokens.) 1773 Specifications defining authentication algorithms MAY use other 1774 representations for the parameters "kc1", "ks1", "vkc", and "vks", 1775 replace those parameter names, and/or add parameters to the messages 1776 containing those parameters in supplemental specifications, provided 1777 that syntactic and semantic requirements in Section 3, [RFC7230] and 1778 [RFC7235] are satisfied. Any parameters starting with "kc", "ks", 1779 "vkc" or "vks" and followed by decimal natural numbers (e.g. kc2, 1780 ks0, vkc1, vks3 etc.) are reserved for this purpose. If those 1781 specifications use names other than those mentioned above, it is 1782 RECOMMENDED to use extension-tokens to avoid any parameter name 1783 conflict with the future extension of this protocol. 1785 Extension-tokens MAY be freely used for any non-standard, private, 1786 and/or experimental uses for those parameters provided that the 1787 domain part in the token is appropriately used. 1789 15. IANA Considerations 1791 When bare-tokens are used for the authentication-algorithm, pwd-hash, 1792 and validation parameters MUST be allocated by IANA. To acquire 1793 registered tokens, a specification for the use of such tokens MUST be 1794 available as an RFC, as outlined in [RFC5226]. 1796 Note: More formal declarations will be added in the future drafts to 1797 meet the RFC 5226 requirements. 1799 16. Security Considerations 1801 16.1. Security Properties 1803 o The protocol is secure against passive eavesdropping and replay 1804 attacks. However, the protocol relies on transport security 1805 including DNS integrity for data secrecy and integrity. HTTP/TLS 1806 SHOULD be used where transport security is not assured and/or data 1807 confidentiality is important. 1809 o When used with HTTP/TLS, if TLS server certificates are reliably 1810 verified, the protocol provides true protection against active 1811 man-in-the-middle attacks. 1813 o Even if the server certificate is not used or is unreliable, the 1814 protocol provides protection against active man-in-the-middle 1815 attacks for each HTTP request/response pair. However, in such 1816 cases, JavaScript or similar scripting facilities can be used to 1817 affect the Mutually-authenticated contents from other contents not 1818 protected by this authentication mechanism. This is the reason 1819 why this protocol requires that valid TLS server certificates MUST 1820 be presented (Section 7). 1822 16.2. Denial-of-service Attacks to Servers 1824 The protocol requires a server-side table of active sessions, which 1825 may become a critical point of the server resource consumptions. For 1826 proper operation, the protocol requires that at least one key 1827 verification request is processed for each session identifier. After 1828 that, servers MAY discard sessions internally at any time, without 1829 causing any operational problems to clients. Clients will silently 1830 reestablishes a new session then. 1832 However, if a malicious client sends too many requests of key 1833 exchanges (req-KEX-C1 messages) only, resource starvation might 1834 occur. In such critical situations, servers MAY discard any kind of 1835 existing sessions regardless of these statuses. One way to mitigate 1836 such attacks are that servers MAY have a number and a time limits for 1837 unverified pending key exchange requests (in the "key exchanging" 1838 status). 1840 This is a common weakness of authentication protocols with almost any 1841 kind of negotiations or states, including Digest authentication 1842 method and most Cookie-based authentication implementations. 1843 However, regarding the resource consumption, a situation of the 1844 mutual authentication method is a slightly better than the Digest, 1845 because HTTP requests without any kind of authentication requests 1846 will not generate any kind of sessions. Session identifiers are only 1847 generated after a client starts a key negotiation. It means that 1848 simple clients such as web crawlers will not accidentally consume 1849 server-side resources for session managements. 1851 16.2.1. On-line Active Password Attacks 1853 Although the protocol provides very strong protection against off- 1854 line dictionary attacks from eavesdropped traffics, the protocol, by 1855 its nature, can not prevent an active password attacks which the 1856 attackers sends so many authentication trial requests for every 1857 possible passwords. 1859 Possible countermeasures for preventing such attacks may be rate- 1860 limiting of the password authentication trials, statistics-based 1861 intrusion detection measures or similar protection schemes. If the 1862 server operators assume that the passwords of users are not strong 1863 enough, it may be desirable to introduce such ad-hoc countermeasures. 1865 16.3. Communicating the status of mutual authentication with users 1867 This protocol is designed for two goals. The first goal is just 1868 providing a secure alternative for existing Basic and Digest 1869 authentication. The second goal is to provide users a way to detect 1870 forged rogue servers imitating user's registered account on server- 1871 side, commonly known as (a part or kind of) Phishing attacks. 1873 For this protocol to effectively work as some countermeasures to such 1874 attacks, it is very important that end users of clients will be 1875 notified of the result of mutual authentication performed by this 1876 protocol, especially the three states "AUTH-SUCCEED", 1877 "UNAUTHENTICATED" and "AUTH-REQUIRED" defined in Section 9. The 1878 design of secure users' interfaces of the HTTP interactive clients 1879 are out of the scope of this document, but if possible, having some 1880 kind of UI indication for the three states above will be desirable 1881 for user's benefits on their security. 1883 Of course, in such cases, the user interfaces for asking passwords 1884 for this authentication shall be clearly identifiable against 1885 imitation by other insecure password input fields (such as forms). 1886 If the passwords are known to malicious attackers outside of the 1887 protocol, the protocol can not work as an effective security 1888 measures. 1890 16.4. Implementation Considerations 1892 o To securely implement the protocol, the Authentication-Info 1893 headers in the 200-VFY-S messages MUST always be validated by the 1894 client. If the validation fails, the client MUST NOT process any 1895 content sent with the message, including other headers and the 1896 body part. Non-compliance to this requirement will allow phishing 1897 attacks. 1899 o For HTTP/TLS communications, when a web form is submitted from 1900 Mutually-authenticated pages with the "tls-server-end-point" 1901 validation method to a URI that is protected by the same realm (so 1902 indicated by the path parameter), if the server certificate has 1903 been changed since the pages were received, the peer is 1904 RECOMMENDED to be revalidated using a req-KEX-C1 message with an 1905 "Expect: 100-continue" header. The same applies when the page is 1906 received with the "tls-unique" validation method, and when the TLS 1907 session has expired. 1909 o For better protection against possible password database steal, 1910 Server-side storages of user passwords are better containing the 1911 values encrypted by one-way function J(pi), instead of the real 1912 passwords, those hashed by ph, or pi. 1914 16.5. Usage Considerations 1916 o The user-names inputted by a user may be sent automatically to any 1917 servers sharing the same auth-domain. This means that when host- 1918 type auth-domain is used for authentication on an HTTPS site, and 1919 when an HTTP server on the same host requests Mutual 1920 authentication within the same realm, the client will send the 1921 user-name in a clear text. If user-names have to be kept secret 1922 against eavesdropping, the server must use full-scheme-type auth- 1923 domain parameter and HTTPS. Contrarily, passwords are not exposed 1924 to eavesdroppers even on HTTP requests. 1926 o The "pwd-hash" parameter is only provided for backward 1927 compatibility of password databases. The use of "none" function 1928 is the most secure choice and is RECOMMENDED. If values other 1929 than "none" are used, you MUST ensure that the hash values of the 1930 passwords were not exposed to the public. Note that hashed 1931 password databases for plain-text authentications are usually not 1932 considered secret. 1934 o If the server provides several ways for storing server-side 1935 password secrets into the password database, it is desirable for 1936 better security to store the values encrypted by using the one-way 1937 function J(pi), instead of the real passwords, those hashed by ph, 1938 or pi. 1940 17. Notice on Intellectual Properties 1942 The National Institute of Advanced Industrial Science and Technology 1943 (AIST) and Yahoo! Japan, Inc. has jointly submitted a patent 1944 application on the protocol proposed in this documentation to the 1945 Patent Office of Japan. The patent is intended to be open to any 1946 implementors of this protocol and its variants under non-exclusive 1947 royalty-free manner. For the details of the patent application and 1948 its status, please contact the author of this document. 1950 The elliptic-curve based authentication algorithms might involve 1951 several existing third-party patents. The authors of the document 1952 take no position regarding the validity or scope of such patents, and 1953 other patents as well. 1955 18. References 1956 18.1. Normative References 1958 [I-D.ietf-httpauth-extension] 1959 Oiwa, Y., Watanabe, H., Takagi, H., Hayashi, T., and Y. 1960 Ioku, "HTTP Authentication Extensions for Interactive 1961 Clients", draft-ietf-httpauth-extension-02 (work in 1962 progress), August 2014. 1964 [I-D.oiwa-precis-httpauthprep] 1965 Oiwa, Y., Nemoto, T., and B. Kihara, "HTTPAuthPrep: PRECIS 1966 profile for HTTP Authentication", 1967 draft-oiwa-precis-httpauthprep-00 (work in progress), 1968 July 2013. 1970 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1971 Hashing for Message Authentication", RFC 2104, 1972 February 1997. 1974 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1975 Requirement Levels", BCP 14, RFC 2119, March 1997. 1977 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 1978 Specification Version 2.0", RFC 2898, September 2000. 1980 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1981 10646", STD 63, RFC 3629, November 2003. 1983 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1984 Encodings", RFC 4648, October 2006. 1986 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1987 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1989 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1990 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1992 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1993 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 1994 June 2014. 1996 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1997 (HTTP/1.1): Authentication", RFC 7235, June 2014. 1999 18.2. Informative References 2001 [I-D.ietf-httpauth-mutual-algo] 2002 Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi, 2003 T., and Y. Ioku, "Mutual Authentication Protocol for HTTP: 2005 KAM3-based Cryptographic Algorithms", 2006 draft-ietf-httpauth-mutual-algo-01 (work in progress), 2007 August 2014. 2009 [I-D.ietf-precis-framework] 2010 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 2011 Preparation and Comparison of Internationalized Strings in 2012 Application Protocols", draft-ietf-precis-framework-17 2013 (work in progress), May 2014. 2015 [ISO.10646-1.1993] 2016 International Organization for Standardization, 2017 "Information Technology - Universal Multiple-octet coded 2018 Character Set (UCS) - Part 1: Architecture and Basic 2019 Multilingual Plane", ISO Standard 10646-1, May 1993. 2021 [ITU.X690.1994] 2022 International Telecommunications Union, "Information 2023 Technology - ASN.1 encoding rules: Specification of Basic 2024 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2025 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2026 X.690, 1994. 2028 [RFC1939] Myers, J. and M. Rose, "Post Office Protocol - Version 3", 2029 STD 53, RFC 1939, May 1996. 2031 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2032 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2033 Authentication: Basic and Digest Access Authentication", 2034 RFC 2617, June 1999. 2036 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2038 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2039 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2040 May 2008. 2042 [RFC5890] Klensin, J., "Internationalized Domain Names for 2043 Applications (IDNA): Definitions and Document Framework", 2044 RFC 5890, August 2010. 2046 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 2047 for TLS", RFC 5929, July 2010. 2049 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2050 April 2011. 2052 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 2053 December 2011. 2055 Appendix A. (Informative) Draft Remarks from Authors 2057 The following items are currently under consideration for future 2058 revisions by the authors. 2060 o Whether to keep TLS-unique validation or not. 2062 o Whether to introduce password strengthening hashes other than 2063 PBKDF2 into the function pi(). This requires standardization of 2064 such other hash algorithms in IETF. 2066 o Whether to modify current definition of nIterPi, which is per- 2067 algorithm defined. To increase this parameter requires defining a 2068 new algorithm, possibly with reconsideration for other security 2069 parameters as well. 2071 o Whether to keep ph() function for legacy migration or not. 2073 o Adding test vectors for ensuring implementation correctness. 2075 o Possibly adding a method for servers to detect availability of 2076 Mutual authentication on client-side. 2078 Appendix B. (Informative) Draft Change Log 2080 B.1. Changes in Httpauth WG Revision 03 2082 o Incompatible change: Single-port type authentication realm label 2083 has been changed to harmonize with Web Origin. (That is, the 2084 default ports (80 and 443) are to be omitted.) 2086 B.2. Changes in Httpauth WG Revision 02 2088 o Major change: introduction of password-strengtheing function 2089 PBKDF2. 2091 o Changed Section 9 to adopt "list of requirements" style. Strict 2092 definition of state machine is now a derived, informational 2093 definition. 2095 B.3. Changes in Httpauth WG Revision 01 2097 o Changed "tls-key" verification to "tls-unique" verification, and 2098 "tls-cert" to "tls-server-end-point", adopting RFC 5929. 2100 o Adopted [I-D.ietf-precis-framework]. 2102 o Reverted reservation of "rekey-sid" and "rekey-method" parameters. 2104 o Degraded secure UI requirement to application note level, non- 2105 normative. 2107 o Adjusted levels of several requirements. 2109 o Added warning text for handling of exceptional 5XX responses. 2111 o Dropped several references for optional authentications, except 2112 one "Note". 2114 o Several textual fixes, improvements and revisions. 2116 B.4. Changes in Httpauth Revision 00 2118 o Changed the version token. 2120 o Renamed "verification tokens" to "Host verification tokens" and 2121 variables "v" to "vh" for clarification. (Back-ported from 2122 draft-oiwa-httpauth-multihop-template-00) 2124 B.5. Changes in HttpBis Revision 00 2126 None. 2128 B.6. Changes in Revision 12 2130 o Added a reason "authz-failed". 2132 B.7. Changes in Revision 11 2134 o Message syntax definition reverted to pre-07 style as httpbis-p1 2135 and p7 now defines a precise rule for parameter value parsing. 2137 o Replaced "stale" parameter with more infomative/extensive "reason" 2138 parameter in 401-INIT and 401-STALE. 2140 o Reserved "rekey-sid" and "rekey-method" parameters for future 2141 extensions. 2143 o Added descriptions for replacing/non-replacing existing 2144 technologies. 2146 B.8. Changes in Revision 10 2148 o The authentication extension parts (non-mandatory authentication 2149 and authentication controls) are separated to yet another draft. 2151 o The default auth-domain parameter is changed to the full scheme- 2152 host-port syntax, which is consistent with usual HTTP 2153 authentication framework behavior. 2155 o Provision for application channel binding is added. 2157 o Provision for proxy access authentication is added. 2159 o Bug fix: syntax specification of sid parameter was wrong: it was 2160 inconsistent with the type specified in the main text (the bug 2161 introduced in -07 draft). 2163 o Terminologies for headers are changed to be in harmony with 2164 httpbis drafts (e.g. field to parameter). 2166 o Syntax definitions are changed to use HTTP-extended ABNF syntax, 2167 and only the header values are shown for header syntax, in harmony 2168 with httpbis drafts. 2170 o Names of parameters and corresponding mathematical values are now 2171 renamed to more informative ones. The following list shows 2172 correspondence between the new and the old names. 2174 +------------+----------+-------------------------------------------+ 2175 | new name | old name | description | 2176 +------------+----------+-------------------------------------------+ 2177 | S_c1, S_s1 | s_a, s_b | client/server-side secret randoms | 2178 | K_c1, K_s1 | w_a, w_b | client/server-side exchanged key | 2179 | | | components | 2180 | kc1, ks1 | wa, wb | parameter names for those | 2181 | VK_c, VK_s | o_a, o_b | client/server-side key verifiers | 2182 | vkc, vks | oa, ob | parameter names for those | 2183 | z | z | session secrets | 2184 +------------+----------+-------------------------------------------+ 2186 B.9. Changes in Revision 09 2188 o The (default) cryptographic algorithms are separated to another 2189 draft. 2191 o Names of the messages are changed to more informative ones than 2192 before. The following is the correspondence table of those names: 2194 +-------------------+-----------------+-----------------------------+ 2195 | new name | old name | description | 2196 +-------------------+-----------------+-----------------------------+ 2197 | 401-INIT | 401-B0 | initial response | 2198 | 401-STALE | 401-B0-stale | session key expired | 2199 | req-KEX-C1 | req-A1 | client->server key exchange | 2200 | 401-KEX-S1 | 401-B1 | server->client key exchange | 2201 | req-VFY-C | req-A3 | client->server auth. | 2202 | | | verification | 2203 | 200-VFY-S | 200-B4 | server->client auth. | 2204 | | | verification | 2205 | 200-Optional-INIT | 200-Optional-B0 | initial with non-mandatory | 2206 | | | authentication | 2207 +-------------------+-----------------+-----------------------------+ 2209 B.10. Changes in Revision 08 2211 o The English text has been revised. 2213 B.11. Changes in Revision 07 2215 o Adapt to httpbis HTTP/1.1 drafts: 2217 * Changed definition of extensive-token. 2219 * LWSP continuation-line (%0D.0A.20) deprecated. 2221 o To simplify the whole spec, the type of nonce-counter related 2222 parameters are change from hex-integer to integer. 2224 o Algorithm tokens are renamed to include names of hash algorithms. 2226 o Clarified the session management, added details of server-side 2227 protocol decisions. 2229 o The whole draft was reorganized; introduction and overview has 2230 been rewritten. 2232 B.12. Changes in Revision 06 2234 o Integrated Optional Mutual Authentication to the main part. 2236 o Clarified the decision procedure for message recognitions. 2238 o Clarified that a new authentication request for any sub-requests 2239 in interactive clients may be silently discarded. 2241 o Typos and confusing phrases are fixed. 2243 o Several "future considerations" are added. 2245 B.13. Changes in Revision 05 2247 o A new parameter called "version" is added for supporting future 2248 incompatible changes with a single implementation. In the (first) 2249 final specification its value will be changed to 1. 2251 o A new header "Authentication-Control" is added for precise control 2252 of application-level authentication behavior. 2254 B.14. Changes in Revision 04 2256 o Changed text of patent licenses: the phrase "once the protocol is 2257 accepted as an Internet standard" is removed so that the sentence 2258 also covers the draft versions of this protocol. 2260 o The "tls-key" verification is now OPTIONAL. 2262 o Several description fixes and clarifications. 2264 B.15. Changes in Revision 03 2266 o Wildcard domain specifications (e.g. "*.example.com") are allowed 2267 for auth-domain parameters (Section 4.1). 2269 o Specification of the tls-cert verification is updated 2270 (incompatible change). 2272 o State transitions fixed. 2274 o Requirements for servers concerning w_a values are clarified. 2276 o RFC references are updated. 2278 B.16. Changes in Revision 02 2280 o Auth-realm is extended to allow full-scheme type. 2282 o A decision diagram for clients and decision procedures for servers 2283 are added. 2285 o 401-B1 and req-A3 messages are changed to contain authentication 2286 realm information. 2288 o Bugs on equations for o_A and o_B are fixed. 2290 o Detailed equations for the entire algorithm are included. 2292 o Elliptic-curve algorithms are updated. 2294 o Several clarifications and other minor updates. 2296 B.17. Changes in Revision 01 2298 o Several texts are rewritten for clarification. 2300 o Added several security consideration clauses. 2302 Authors' Addresses 2304 Yutaka Oiwa 2305 National Institute of Advanced Industrial Science and Technology 2306 Research Institute for Secure Systems 2307 3-11-46 Nakouji 2308 Amagasaki, Hyogo 2309 JP 2311 Email: mutual-auth-contact-ml@aist.go.jp 2313 Hajime Watanabe 2314 National Institute of Advanced Industrial Science and Technology 2315 Research Institute for Secure Systems 2316 Tsukuba Central 2 2317 1-1-1 Umezono 2318 Tsukuba-shi, Ibaraki 2319 JP 2321 Hiromitsu Takagi 2322 National Institute of Advanced Industrial Science and Technology 2323 Research Institute for Secure Systems 2324 Tsukuba Central 2 2325 1-1-1 Umezono 2326 Tsukuba-shi, Ibaraki 2327 JP 2328 Kaoru Maeda 2329 Lepidum Co. Ltd. 2330 #602, Village Sasazuka 3 2331 1-30-3 Sasazuka 2332 Shibuya-ku, Tokyo 2333 JP 2335 Tatsuya Hayashi 2336 Lepidum Co. Ltd. 2337 #602, Village Sasazuka 3 2338 1-30-3 Sasazuka 2339 Shibuya-ku, Tokyo 2340 JP 2342 Yuichi Ioku 2343 Individual