idnits 2.17.1 draft-oiwa-http-mutualauth-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 5, 2011) is 4680 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 4013 (Obsoleted by RFC 7613) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force Y. Oiwa 3 Internet-Draft H. Watanabe 4 Intended status: Standards Track H. Takagi 5 Expires: January 6, 2012 RCIS, AIST 6 Y. Ioku 7 Yahoo! Japan 8 T. Hayashi 9 Lepidum 10 July 5, 2011 12 Mutual Authentication Protocol for HTTP 13 draft-oiwa-http-mutualauth-09 15 Abstract 17 This document specifies a mutual authentication method for the Hyper- 18 text Transport Protocol (HTTP). This method provides a true mutual 19 authentication between an HTTP client and an HTTP server using 20 password-based authentication. Unlike the Basic and Digest 21 authentication methods, the Mutual authentication method specified in 22 this document assures the user that the server truly knows the user's 23 encrypted password. This prevents common phishing attacks: a 24 phishing attacker controlling a fake website cannot convince a user 25 that he authenticated to the genuine website. Furthermore, even when 26 a user authenticates to an illegitimate server, the server cannot 27 gain any information about the user's password. The Mutual 28 authentication method is designed as an extension to the HTTP 29 protocol, and is intended to replace the existing authentication 30 methods used in HTTP (the Basic method, Digest method, and 31 authentication using HTML forms). 33 Status of this Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on January 6, 2012. 50 Copyright Notice 52 Copyright (c) 2011 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 69 1.2. Document Structure Overview . . . . . . . . . . . . . . . 6 70 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 71 2.1. Messages . . . . . . . . . . . . . . . . . . . . . . . . . 6 72 2.2. Typical Flows of the protocol . . . . . . . . . . . . . . 7 73 2.3. Alternative flows . . . . . . . . . . . . . . . . . . . . 10 74 3. Message Syntax . . . . . . . . . . . . . . . . . . . . . . . . 11 75 3.1. Tokens and Extensive-tokens . . . . . . . . . . . . . . . 12 76 3.2. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 12 77 3.3. Strings . . . . . . . . . . . . . . . . . . . . . . . . . 13 78 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 79 4.1. 401-INIT . . . . . . . . . . . . . . . . . . . . . . . . . 14 80 4.2. 401-STALE . . . . . . . . . . . . . . . . . . . . . . . . 16 81 4.3. req-KEX-C1 . . . . . . . . . . . . . . . . . . . . . . . . 16 82 4.4. 401-KEX-S1 . . . . . . . . . . . . . . . . . . . . . . . . 17 83 4.5. req-VFY-C . . . . . . . . . . . . . . . . . . . . . . . . 18 84 4.6. 200-VFY-S . . . . . . . . . . . . . . . . . . . . . . . . 19 85 4.7. 200-Optional-INIT . . . . . . . . . . . . . . . . . . . . 20 86 5. Authentication Realms . . . . . . . . . . . . . . . . . . . . 21 87 5.1. Resolving ambiguities . . . . . . . . . . . . . . . . . . 23 88 6. Session Management . . . . . . . . . . . . . . . . . . . . . . 23 89 7. Validation Methods . . . . . . . . . . . . . . . . . . . . . . 25 90 8. Decision procedure for client . . . . . . . . . . . . . . . . 27 91 9. Decision procedure for the server . . . . . . . . . . . . . . 32 92 10. Authentication-Control header . . . . . . . . . . . . . . . . 34 93 10.1. Location-when-unauthenticated field . . . . . . . . . . . 35 94 10.2. Location-when-logout field . . . . . . . . . . . . . . . . 35 95 10.3. Logout-timeout . . . . . . . . . . . . . . . . . . . . . . 36 96 11. Authentication Algorithms . . . . . . . . . . . . . . . . . . 36 97 11.1. Support functions and notations . . . . . . . . . . . . . 37 98 11.2. Default functions for algorithms . . . . . . . . . . . . . 38 99 12. Methods to extend this protocol . . . . . . . . . . . . . . . 38 100 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 101 14. Security Considerations . . . . . . . . . . . . . . . . . . . 39 102 14.1. Security Properties . . . . . . . . . . . . . . . . . . . 39 103 14.2. Denial-of-service attacks to servers . . . . . . . . . . . 39 104 14.3. Implementation Considerations . . . . . . . . . . . . . . 40 105 14.4. Usage Considerations . . . . . . . . . . . . . . . . . . . 41 106 15. Notice on intellectual properties . . . . . . . . . . . . . . 41 107 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 42 108 16.1. Normative References . . . . . . . . . . . . . . . . . . . 42 109 16.2. Informative References . . . . . . . . . . . . . . . . . . 42 110 Appendix A. (Informative) Generic syntax of headers . . . . . . . 43 111 Appendix B. (Informative) Draft Remarks from Authors . . . . . . 45 112 Appendix C. (Informative) Draft Change Log . . . . . . . . . . . 46 113 C.1. Changes in revision 09 . . . . . . . . . . . . . . . . . . 46 114 C.2. Changes in revision 08 . . . . . . . . . . . . . . . . . . 46 115 C.3. Changes in revision 07 . . . . . . . . . . . . . . . . . . 46 116 C.4. Changes in revision 06 . . . . . . . . . . . . . . . . . . 47 117 C.5. Changes in revision 05 . . . . . . . . . . . . . . . . . . 47 118 C.6. Changes in revision 04 . . . . . . . . . . . . . . . . . . 47 119 C.7. Changes in revision 03 . . . . . . . . . . . . . . . . . . 47 120 C.8. Changes in revision 02 . . . . . . . . . . . . . . . . . . 48 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 48 123 1. Introduction 125 This document specifies a mutual authentication method for Hyper-Text 126 Transport Protocol (HTTP). The method, called "Mutual Authentication 127 Protocol" in this document, provides a true mutual authentication 128 between an HTTP client and an HTTP server, using just a simple 129 password as a credential. 131 The currently available methods for authentication in HTTP and Web 132 systems have several deficiencies. The Basic authentication method 133 [RFC2617] sends a plaintext password to a server without any 134 protection; the Digest method uses a hash function that suffers from 135 simple dictionary-based off-line attacks, and people have begun to 136 think it is obsolete. 138 The authentication method proposed in this document solves these 139 problems, substitutes for these existing methods, and serves as a 140 long-term solution to Web authentication security. It has the 141 following main characteristics: 143 o It provides "true" mutual authentication: in addition to assuring 144 the server that the user knows the password, it also assures the 145 user that the server truly knows the user's encrypted password at 146 the same time. It makes it impossible for fake website owners to 147 persuade users that thee authenticated with the original websites. 149 o It uses only passwords as the user's credential: unlike public- 150 key-based security algorithms, the method does not rely on secret 151 keys or other cryptographic data that have to be stored inside the 152 users' computers. The proposed method can be used as a drop-in 153 replacement to the current authentication methods like Basic or 154 Digest, while ensuring a much stronger level of security. 156 o It is secure: when the server fails to authenticate with a user, 157 the protocol will not reveal any bit of the user's password. 159 Users can discriminate between true and fake Web servers using their 160 own passwords by using the proposed method. Even when a user inputs 161 his/her password to a fake website owned by illegitimate phishers, 162 the user will certainly notice that the authentication has failed. 163 Phishers will not be successful in their authentication attempts, 164 even if they forward the received data from a user to a legitimate 165 server or vice versa. Users can input sensitive data to the web 166 forms after confirming that the mutual authentication has succeeded, 167 without fear of phishing attacks. 169 The document also proposes several extensions to the current HTTP 170 authentication framework, to replace current widely-used form-based 171 Web authentication. A majority of the recent Web-sites on the 172 Internet use custom application-layer authentication implementations 173 using Web forms. The reasons for these may vary, but many people 174 believe that the current HTTP Basic (and Digest, too) authentication 175 method does not have enough functionality (including a good-feeling 176 user interfaces) to support most of realistic Web-based applications. 177 However, the method is very weak against phishing attacks, because 178 the whole behavior of the authentication is controlled from the 179 server side. To overcome this problem, we need to "modernize" the 180 HTTP authentication framework so that better client-controlled secure 181 methods can be used with Web applications. The extensions proposed 182 in this document include: 184 o Multi-host single authentication within an Internet domain 185 (Section 5), 187 o non-mandatory, optional authentication on HTTP (Section 4.7), 189 o log out from both server and client side (Section 10), and 191 o finer control for redirection depending on authentication status 192 (Section 10). 194 1.1. Terminology 196 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 197 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 198 "OPTIONAL" in this document are to be interpreted as described in 199 [RFC2119]. 201 The terms "encouraged" and "advised" are used for suggestions that do 202 not constitute "SHOULD"-level requirements. People MAY freely choose 203 not to include the suggested items regarding [RFC2119], but complying 204 with those suggestions would be a best practice; it will improve the 205 security, interoperability, and/or operational performance. 207 This document distinguishes the terms "client" and "user" in the 208 following way: A "client" is an entity understanding and talking HTTP 209 and the specified authentication protocol, usually computer software; 210 a "user" is a (usually natural) person who wants to access data 211 resources using "a client". 213 The term "natural numbers" refers to the non-negative integers 214 (including zero) throughout this document. 216 1.2. Document Structure Overview 218 The entire document is organized as follows: 220 o Section 2 presents an overview of the protocol design. 222 o Sections 3 to 9 define a general framework of the Mutual 223 authentication protocol. This framework is independent of 224 specific cryptographic primitives. 226 o Section 10 defines an optional extension to the generic HTTP 227 authentication framework, which is mostly useful for controlling 228 the behavior of the Web browser for the authentication. 230 o Section 11 describes properties needed for cryptographic 231 algorithms used with this protocol framework, and defines a few 232 functions which will be shared among such cryptographic 233 algorithms. 235 o The sections after that contain general normative and informative 236 information about the protocol. 238 o The appendices contain some information that may help developers 239 to implement the protocol. 241 2. Protocol Overview 243 The protocol, as a whole, is designed as a natural extension to the 244 HTTP protocol [RFC2616] using a framework defined in [RFC2617]. 245 Internally, the server and the client will first perform a 246 cryptographic key exchange, using the secret password as a "tweak" to 247 the exchange. The key-exchange will only succeed when the secrets 248 used by the both peers are correctly related (i.e. generated from the 249 same password). Then, both peers will verify the authentication 250 results by confirming the sharing of the exchanged key. This section 251 describes a brief image of the protocol and the exchanged messages. 253 2.1. Messages 255 The authentication protocol uses seven kinds of messages to perform 256 mutual authentication. These messages have specific names within 257 this specification. 259 o Authentication request messages: used by the servers to request 260 clients to start mutual authentication. 262 * 401-INIT message: a general message to start the authentication 263 protocol. It is also used as a message indicating an 264 authentication failure. 266 * 200-Optional-INIT message: a variant of the 401-INIT message 267 indicating that an authentication is not mandatory. 269 * 401-STALE message: a message indicating that it has to start a 270 new authentication trial. 272 o Authenticated key exchange messages: used by both peers to perform 273 authentication and the sharing of a cryptographic secret. 275 * req-KEX-C1 message: a message sent from the client. 277 * 401-KEX-S1 message: a message sent from the server as a 278 response to a req-KEX-C1 message. 280 o Authentication verification messages: used by both peers to verify 281 the authentication results. 283 * req-VFY-C message: a message used by the client, requesting 284 that the server authenticates and authorizes the client. 286 * 200-VFY-S message: a successful response used by the server, 287 and also asserting that the server is authentic to the client 288 simultaneously. 290 In addition to the above, either a request or a response without any 291 HTTP headers related to this specification will be hereafter called a 292 "normal request" or a "normal response", respectively. 294 2.2. Typical Flows of the protocol 296 In typical cases, the client access to a resource protected by the 297 Mutual authentication will follow the following protocol sequence. 299 Client Server 300 | | 301 | ---- (1) normal request ---------> | 302 GET / HTTP/1.1 | 303 | | 304 | <---------------- (2) 401-INIT --- | 305 | 401 Authentication Required 306 | WWW-Authenticate: Mutual realm="a realm" 307 | | 308 [user, | | 309 pass]-->| | 310 | ---- (3) req-KEX-C1 -------------> | 311 GET / HTTP/1.1 | 312 Authorization: Mutual user="john", |--> [user DB] 313 wa="...", ... |<-- [user info] 314 | | 315 | <-------------- (4) 401-KEX-S1 --- | 316 | 401 Authentication Required 317 | WWW-Authenticate: Mutual sid=..., wb="...", ... 318 | | 319 [compute] (5) compute session secret [compute] 320 | | 321 | | 322 | ---- (6) req-VFY-C --------------> | 323 GET / HTTP/1.1 |--> [verify (6)] 324 Authorization: Mutual sid=..., |<-- OK 325 oa="...", ... | 326 | | 327 | <--------------- (7) 200-VFY-S --- | 328 [verify | 200 OK | 329 (7)]<--| Authentication-Info: Mutual ob="..." 330 | | 331 v v 333 Figure 1: Typical communication flow for first access to resource 335 o As usual in general HTTP protocol designs, a client will at first 336 request a resource without any authentication attempt (1). If the 337 requested resource is protected by the Mutual authentication, the 338 server will respond with a message requesting authentication 339 (401-INIT) (2). 341 o The client processes the body of the message, and waits for the 342 user to input the user name and a password. If the user name and 343 the password are available, the client will send a message with 344 the authenticated key exchange (req-KEX-C1) to start the 345 authentication (3). 347 o If the server has received a req-KEX-C1 message, the server looks 348 up the user's authentication information within its user database. 349 Then the server creates a new session identifier (sid) that will 350 be used to identify sets of the messages that follow it, and 351 responds back with a message containing a server-side 352 authenticated key exchange value (401-KEX-S1) (4). 354 o At this point (5), both peers calculate a shared "session secret" 355 using the exchanged values in the key exchange messages. Only 356 when both the server and the client have used secret credentials 357 generated from the same password will the session secret values 358 match. This session secret will be used for the actual access 359 authentication after this point. 361 o The client will send a request with a client-side authentication 362 verification value (req-VFY-C) (6), generated from the client- 363 owned session secret. The server will check the validity of the 364 verification value using its own session secret. 366 o If the authentication verification value from the client was 367 correct, it means that the client definitely owns the credential 368 based on the expected password (i.e. the client authentication 369 succeeded.) The server will respond with a successful message 370 (200-VFY-S) (7). Contrary to the usual one-way authentication 371 (e.g. HTTP Basic authentication or POP APOP authentication), this 372 message also contains a server-side authentication verification 373 value. 375 When the client's verification value is incorrect (e.g. because 376 the user-supplied password was incorrect), the server will respond 377 with the 401-INIT message (the same one as used in (2)) instead. 379 o The client MUST first check the validity of the server-side 380 authentication verification value contained in the message (7). 381 If the value was equal to the expected one, the server 382 authentication succeeded. 384 If it is not the value expected, or if the message does not 385 contain the authentication verification value, it means that the 386 mutual authentication has been broken for some unexpected reason. 387 The client MUST NOT process any body or header values contained in 388 this case. (Note: This case should not happen between a 389 correctly-implemented server and a client.) 391 2.3. Alternative flows 393 As shown above, the typical flow for a first authenticated request 394 requires three request-response pairs. To reduce the protocol 395 overhead, the protocol enables several short-cut flows which require 396 fewer messages. 398 o (case A) If the client knows that the resource is likely to 399 require the authentication, the client MAY omit the first 400 unauthenticated request (1) and immediately send a key exchange 401 (req-KEX-C1 message). This will reduce one round-trip of 402 messages. 404 o (case B) If both the client and the server previously shared a 405 session secret associated with a valid session identifier (sid), 406 the client MAY directly send a req-VFY-C message using the 407 existing session identifier and corresponding session secret. 408 This will further reduce one round-trip of messages. 410 In such cases, the server MAY have thrown out the corresponding 411 sessions from the session table. In this case, the server will 412 respond with a 401-STALE message, indicating a new key exchange is 413 required. The client SHOULD retry constructing a req-KEX-C1 414 message in this case. 416 Figure 2 depicts the shortcut flows described above. Under the 417 appropriate settings and implementations, most of the requests to 418 resources are expected to meet both the criteria, and thus only one 419 round-trip of request/responses will be required in most cases. 421 (A) omit first request 422 (2 round trips) 424 Client Server 425 | | 426 | --- req-KEX-C1 ----> | 427 | | 428 | <---- 401-KEX-S1 --- | 429 | | 430 | ---- req-VFY-C ----> | 431 | | 432 | <----- 200-VFY-S --- | 433 | | 435 (B) reusing session secret 437 (B-1) key available (B-2) key expired 438 (1 round trip) (3 round trips) 440 Client Server Client Server 441 | | | | 442 | ---- req-VFY-C ----> | | --- req-VFY-C -------> | 443 | | | | 444 | <----- 200-VFY-S --- | | <------- 401-STALE --- | 445 | | | | 446 | --- req-KEX-C1 ------> | 447 | | 448 | <------ 401-KEX-S1 --- | 449 | | 450 | --- req-VFY-C -------> | 451 | | 452 | <------- 200-VFY-S --- | 453 | | 455 Figure 2: Several alternative flows on protocol 457 For more details, see Sections 8 and 9. 459 3. Message Syntax 461 The Mutual authentication protocol uses five headers: 462 WWW-Authenticate (in responses with status code 401), 463 Optional-WWW-Authenticate (in responses with non-401 status codes), 464 Authentication-Control (in responses), Authorization (in requests), 465 and Authentication-Info (in responses other than 401 status). These 466 headers follow a common framework described in [RFC2617] [Editorial 467 Note: to be httpbis-p7]. The detailed syntax definitions for these 468 headers are contained in Section 4. 470 These headers use some common syntax elements described in Figure 3. 471 The syntax is denoted in the augmented BNF syntax defined in 472 [RFC5234]. 474 auth-scheme = "Mutual" ; see HTTP for other values 475 extension-field = extension-token "=" value 476 token = 1*(%x30-39 / %x41-5A / %x61-7A / "-" / "_") 477 extensive-token = token / extension-token 478 extension-token = "-" token 1*("." token) 479 value = extensive-token / integer 480 / hex-fixed-number 481 / base64-fixed-number / string 482 integer = "0" / (%x31-39 *%x30-39) ; no leading zeros 483 hex-fixed-number = 1*(%x30-39 / %x41-46 / %x61-66) 484 base64-fixed-number = string 485 string = %x22 *(%x20-21 / %x23-5B / %x5D-FF 486 / %x5C.22 / "\\") %x22 487 spaces = 1*(" " / %x09) 489 Figure 3: BNF syntax for common elements used in protocol 491 3.1. Tokens and Extensive-tokens 493 The tokens are case insensitive; Senders SHOULD send these in lower- 494 case, and receivers MUST accept both upper- and lower-cases. When 495 tokens are used as the (partial) inputs to any hash or other 496 mathematical functions, it MUST always be used in lower-case. All 497 hexadecimal numbers are also case-insensitive, and SHOULD be sent in 498 lower-case. 500 Extensive-tokens are used in this protocol where the set of 501 acceptable tokens may include non-standard extensions. Any non- 502 standard extensions of this protocol MUST use the extension-tokens 503 with format "-.", where is a 504 validly registered (sub-)domain name on the Internet owned by the 505 party who defines the extensions. 507 3.2. Numbers 509 The syntax definition of the integers only allows representations 510 that do not contain extra leading zeros. 512 The numbers represented as a hex-fixed-number MUST include an even 513 number of characters (i.e. multiples of eight bits). When these are 514 generated from any cryptographic values, they SHOULD have their 515 "natural length": if these are generated from a hash function, these 516 lengths SHOULD correspond to the hash size; if these are representing 517 elements of a mathematical set (or group), its lengths SHOULD be the 518 shortest for representing all the elements in the set. For example, 519 any results of SHA-256 hash function will be represented by 64 520 characters, and any elements in 2048-bit prime field (modulo a 2048- 521 bit integer) will be represented by 512 characters, regardless of how 522 much 0's will be appear in front of such representations. Session- 523 identifiers and other non-cryptographically generated values are 524 represented in any (even) length determined by the side who generates 525 it first, and the same length SHALL be used throughout the all 526 communications by both peers. 528 The numbers represented as base64-fixed-number SHALL be generated as 529 follows: first, the number is converted to a big-endian octet-string 530 representation. The length of the representation is determined in 531 the same way as mentioned above. Then, the string is encoded using 532 the Base 64 encoding [RFC4648] without any spaces and newlines, and 533 then enclosed by two double-quotations. 535 3.3. Strings 537 All the strings outside ASCII character sets MUST be encoded using 538 the UTF-8 encoding [RFC3629] for the ISO 10646-1 character set 539 [ISO.10646-1.1993]. Both peers are RECOMMENDED to reject any invalid 540 UTF-8 sequences that might cause decoding ambiguities (e.g., 541 containing <"> in the second or later byte of the UTF-8 encoded 542 characters). 544 To encode character strings to header values, they will first be 545 encoded according to UTF-8 without a leading BOM, then all 546 occurrences of the characters <"> and "\" will be escaped by 547 prepending "\", and two <">s will be put around the string. These 548 escaping backslashes and enclosing quotes SHALL be removed before any 549 processing other than when using them in a header field. 551 If strings are representing a domain name or URI that contains non- 552 ASCII characters, the host parts SHOULD be encoded as it is used in 553 the HTTP protocol layer (e.g. in a Host: header); under current 554 standards it will be the one defined in [RFC5890]. It SHOULD use 555 lower-case ASCII characters. 557 For base64-fixed-numbers, which use the string syntax, see the 558 previous section. 560 4. Messages 562 In this section we define the seven kinds of messages used in the 563 authentication protocol along with the formats and requirements of 564 the headers for each message. 566 To determine which message are expected to be sent, see Sections 8 567 and 9. 569 In the descriptions below, the type of allowable values for each 570 header field is shown in parenthesis after the key names. The 571 "algorithm-determined" type means that the acceptable value for the 572 field is one of the types defined in Section 3, and is determined by 573 the value of the "algorithm" field. The fields marked "mandatory" 574 SHALL be contained in the message. The fields marked "non-mandatory" 575 MAY either be contained or omitted in the message. Each field SHALL 576 appear in each headers exactly once at most. 578 4.1. 401-INIT 580 Every 401-INIT message SHALL be a valid HTTP 401 (Authentication 581 Required) message containing one (and only one: hereafter not 582 explicitly noticed) "WWW-Authenticate" header of the following 583 format. 585 WWW-Authenticate: Mutual algorithm=xxxx, validation=xxxx, 586 realm="xxxx", stale=0, version=-draft07 588 header-401-INIT = "WWW-Authenticate" ":" [spaces] 589 auth-scheme spaces fields-401-INIT 590 fields-401-INIT = field-401-INIT *([spaces] "," spaces field-401-INIT) 591 field-401-INIT = version / algorithm / validation 592 / auth-domain / realm / pwd-hash / stale 593 / extension-field 594 version = "version" "=" extensive-token 595 algorithm = "algorithm" "=" extensive-token 596 validation = "validation" "=" extensive-token 597 auth-domain = "auth-domain" "=" string 598 realm = "realm" "=" string 599 pwd-hash = "pwd-hash" "=" extensive-token 600 stale = token 602 Figure 4: BNF syntax for header in 401-INIT header 604 The header SHALL contain all of the fields marked "mandatory" below, 605 and MAY contain those marked "non-mandatory". 607 version: (mandatory extensive-token) should be the token 608 "-draft07" in this specification. The behavior is 609 undefined when other values are specified. 611 algorithm: (mandatory extensive-token) specifies the 612 authentication algorithm to be used. The value MUST 613 be one of the tokens specified in &algo_draft; or 614 other supplemental specification documentation. 616 validation: (mandatory extensive-token) specifies the method of 617 host validation. The value MUST be one of the tokens 618 described in Section 7, or the tokens specified in 619 other supplemental specification documentation. 621 auth-domain: (non-mandatory string) specifies the authentication 622 domain, the set of hosts for which the authentication 623 credentials are valid. It MUST be one of the strings 624 described in Section 5. If the value is omitted, it 625 is assumed to be the host part of the requested URI. 627 realm: (mandatory string) is a UTF-8 encoded string 628 representing the name of the authentication realm 629 inside the authentication domain. 631 pwd-hash: (non-mandatory extensive-token) specifies the hash 632 algorithm (hereafter referred to by ph) used for 633 additionally hashing the password. The valid tokens 634 are 636 * none: ph(p) = p 638 * md5: ph(p) = MD5(p) 640 * digest-md5: ph(p) = MD5(username | ":" | realm | 641 ":" | p), the same value as MD5(A1) for "MD5" 642 algorithm in [RFC2617]. 644 * sha1: ph(p) = SHA1(p) 646 If omitted, the value "none" is assumed. The use of 647 "none" is recommended. 649 stale: (mandatory token) MUST be "0". 651 The algorithm specified in this header will determine the types and 652 the values for w_A, w_B, o_A and o_B. 654 4.2. 401-STALE 656 A 401-STALE message is a variant of the 401-INIT message, which means 657 that the client has sent a request message that is not for any active 658 session. 660 WWW-Authenticate: Mutual algorithm=xxxx, validation=xxxx, 661 realm="xxxx", stale=1, version=-draft07 663 The header MUST contain the same fields as in 401-INIT, except that 664 the stale field contains token 1. 666 4.3. req-KEX-C1 668 Every req-KEX-C1 message SHALL be a valid HTTP request message 669 containing an "Authorization" header of the following format. 671 Authorization: Mutual algorithm=xxxx, validation=xxxx, realm="xxxx", 672 user="xxxx", wa=xxxx, version=-draft07 674 header-req-KEX-C1 = "Authorization" ":" [spaces] 675 auth-scheme spaces fields-req-KEX-C1 676 fields-req-KEX-C1 = field-req-KEX-C1 677 *([spaces] "," spaces field-req-KEX-C1) 678 field-req-KEX-C1 = version / algorithm / validation 679 / auth-domain / realm / user / wa 680 / extension-field 681 user = "user" "=" string 682 wa = "wa" "=" value 684 Figure 5: the BNF syntax for the header in req-KEX-C1 message 686 The header SHALL contain the fields with the following keys: 688 version: (mandatory, extensive-token) should be the token 689 "-draft07" in this specification. The behavior is 690 undefined when other values are specified. 692 algorithm, validation, auth-domain, realm: MUST be the same value as 693 it is when received from the server. 695 user: (mandatory, string) is the UTF-8 encoded name of the 696 user. If this name comes from a user input, client 697 software SHOULD prepare the string using SASLprep 698 [RFC4013] before encoding it to UTF-8. 700 wa: (mandatory, algorithm-determined) is the client-side 701 key exchange value w_A, which is specified by the 702 algorithm that is used. 704 4.4. 401-KEX-S1 706 Every 401-KEX-S1 message SHALL be a valid HTTP 401 (Authentication 707 Required) message containing a "WWW-Authenticate" header of the 708 following format. 710 WWW-Authenticate: Mutual algorithm=xxxx, validation=xxxx, 711 realm="xxxx", sid=xxxx, wb=xxxx, nc-max=x, nc-window=x, time=x, 712 path="xxxx", version=-draft07 714 header-401-KEX-S1 = "WWW-Authenticate" ":" [spaces] 715 auth-scheme spaces fields-401-KEX-S1 716 fields-401-KEX-S1 = field-401-KEX-S1 717 *([spaces] "," spaces field-401-KEX-S1) 718 field-401-KEX-S1 = version / algorithm / validation 719 / auth-domain / realm / sid / wb 720 / nc-max / nc-window / time / path 721 / extension-field 722 sid = "sid" "=" string 723 wb = "wb" "=" value 724 nc-max = "nc-max" "=" integer 725 nc-window = "nc-window" "=" integer 726 time = "time" "=" integer 727 path = "path" "=" string 729 Figure 6: the BNF syntax for the header in 401-KEX-S1 message 731 The header SHALL contain the fields with the following keys: 733 version: (mandatory, extensive-token) should be the token 734 "-draft07" in this specification. The behavior is 735 undefined when other values are specified. 737 algorithm, validation, auth-domain, realm: MUST be the same value as 738 it is when received from the client. 740 sid: (mandatory, hex-fixed-number) MUST be a session 741 identifier, which is a random integer. The sid SHOULD 742 have uniqueness of at least 80 bits or the square of 743 the maximal estimated transactions concurrently 744 available in the session table, whichever is larger. 745 Session identifiers are local to each concerned 746 authentication realm: the same sids for different 747 authentication realms SHOULD be treated as independent 748 ones. 750 wb: (mandatory, algorithm-determined) is the server-side 751 key exchange value w_B, which is specified by the 752 algorithm. 754 nc-max: (mandatory, integer) is the maximal value of nonce 755 counts that the server accepts. 757 nc-window: (mandatory, integer) the number of available nonce 758 slots that the server will accept. The value of the 759 nc-window field is RECOMMENDED to be 32 or more. 761 time: (mandatory, integer) represents the suggested time (in 762 seconds) that the client can reuse the session 763 represented by the sid. It is RECOMMENDED to be at 764 least 60. The value of this field is not directly 765 linked to the duration that the server keeps track of 766 the session represented by the sid. 768 path: (non-mandatory, string) specifies which path in the 769 URI space the same authentication is expected to be 770 applied. The value is a space-separated list of URIs, 771 in the same format as it was specified in domain 772 parameter [RFC2617] for the Digest authentications, 773 and clients are RECOMMENDED to recognize it. The all 774 path elements contained in the field MUST be inside 775 the specified auth-domain: if not, clients SHOULD 776 ignore such elements. 778 4.5. req-VFY-C 780 Every req-VFY-C message SHALL be a valid HTTP request message 781 containing an "Authorization" header of the following format. 783 Authorization: Mutual algorithm=xxxx, validation=xxxx, realm="xxxx", 784 sid=xxxx, nc=x, oa=xxxx, version=-draft07 786 header-req-VFY-C = "Authorization" ":" [spaces] 787 auth-scheme spaces fields-req-VFY-C 788 fields-req-VFY-C = field-req-VFY-C 789 *([spaces] "," spaces field-req-VFY-C) 790 field-req-VFY-C = version / algorithm / validation 791 / auth-domain / realm / sid / nc / oa 792 / extension-field 793 nc = "nc" "=" integer 794 oa = "oa" "=" value 795 Figure 7: the BNF syntax for the header in req-VFY-C message 797 The fields contained in the header are as follows: 799 version: (mandatory, extensive-token) should be the token 800 "-draft07" in this specification. The behavior is 801 undefined when other values are specified. 803 algorithm, validation, auth-domain, realm: MUST be the same value as 804 it is when received from the server for the session. 806 sid: (mandatory, hex-fixed-number) MUST be one of the sid 807 values that was received from the server for the same 808 authentication realm. 810 nc: (mandatory, integer) is a nonce value that is unique 811 among the requests sharing the same sid. The values 812 of the nonces SHOULD satisfy the properties outlined 813 in Section 6. 815 oa: (mandatory, algorithm-determined) is the client-side 816 authentication verification value o_A, which is 817 specified by the algorithm. 819 4.6. 200-VFY-S 821 Every 200-VFY-S message SHALL be a valid HTTP message that is not of 822 the 401 (Authentication Required) type, containing an 823 "Authentication-Info" header of the following format. 825 Authentication-Info: Mutual sid=xxxx, ob=xxxx, version=-draft07 827 header-200-VFY-S = "Authentication-Info" ":" [spaces] 828 auth-scheme spaces fields-200-VFY-S 829 fields-200-VFY-S = field-200-VFY-S 830 *([spaces] "," spaces field-200-VFY-S) 831 field-200-VFY-S = version / sid / ob / logout-timeout 832 ob = "ob" "=" value 833 logout-timeout = "logout-timeout" "=" integer 835 Figure 8: BNF syntax for header in 200-VFY-S message 837 The fields contained in the header are as follows: 839 version: (mandatory, extensive-token) should be the token 840 "-draft07" in this specification. The behavior is 841 undefined when other values are specified. 843 sid: (mandatory, hex-fixed-number) MUST be the value 844 received from the client. 846 ob: (mandatory, algorithm-determined) is the server-side 847 authentication verification value o_B, which is 848 specified by the algorithm. 850 logout-timeout: (non-mandatory, integer) is the number of seconds 851 after which the client should re-validate the user's 852 password for the current authentication realm. The 853 value 0 means that the client SHOULD automatically 854 forget the user-inputted password for the current 855 authentication realm and revert to the unauthenticated 856 state (i.e. server-initiated logout). This does not, 857 however, mean that the long-term memories for the 858 passwords (such as the password reminders and auto 859 fill-ins) should be removed. If a new timeout value 860 is received for the same authentication realm, it 861 overrides the previous timeout. 863 The header MUST be sent before the content body: it MUST NOT be sent 864 in the trailer of a chunked-encoded response. If a "100 Continue" 865 response is sent from the server, the Authentication-Info header 866 SHOULD be included in that response, instead of the final response. 868 4.7. 200-Optional-INIT 870 The 200-Optional-INIT messages enable a non-mandatory authentication, 871 which is not possible under the current HTTP authentication 872 mechanism. In several Web applications, users can access the same 873 contents as both a guest user and an authenticated user. In most Web 874 applications, it is implemented using HTTP cookies [RFC6265] and 875 custom form-based authentications. The new authentication method 876 using this message will provide a replacement for these 877 authentication systems. Support for this message is RECOMMENDED, 878 unless the protocol is used for some specific applications in which 879 the authentication is always mandatory. 881 Servers MAY send HTTP successful responses (response code 200, 206 882 and others) containing the Optional-WWW-Authenticate header, when it 883 is allowed to send 401-INIT responses (with one exception described 884 below). Such responses are hereafter called 200-Optional-INIT 885 responses. 887 HTTP/1.1 200 OK 888 Optional-WWW-Authenticate: Mutual version=-draft07, algorithm=xxxx, 889 validation=xxxx, realm="xxxx", stale=0 891 header-200-Optional-INIT = "Optional-WWW-Authenticate" ":" 892 [spaces] auth-scheme 893 spaces fields-401-INIT 895 Figure 9: BNF syntax for header in 200-Optional-INIT header 897 The fields contained in the Optional-WWW-Authenticate header are the 898 same as those for the 401-INIT message described in Section 4.1. For 899 authentication-related matters, a 200-Optional-INIT message will have 900 the same meaning as a 401-INIT message with a corresponding 901 WWW-Authenticate header. (The behavior for other matters, such as 902 caching, MAY be different between the 200-Optional-INIT and 401-INIT 903 messages.) 905 The 200-Optional-INIT message is the only place where an 906 Optional-WWW-Authenticate header is allowed. If a server is supposed 907 to send a 401-KEX-S1 or a 401-STALE response, it SHALL NOT replace it 908 with 200-Optional-INIT or similar responses. Furthermore, if a 909 server is going to send a 401-INIT message as a response to a 910 req-VFY-C message with a correct realm, the server MUST send a 911 401-INIT message, not a 200-Optional-INIT message. 913 Servers requesting non-mandatory authentication SHOULD send the path 914 field in the 401-KEX-S1 messages with an appropriate value. Clients 915 supporting non-mandatory authentication MUST recognize the field, and 916 MUST send either a req-KEX-C1 or a req-VFY-C request for the URI 917 space inside the specified paths, instead of a normal request without 918 an Authorization header. 920 5. Authentication Realms 922 In this protocol, an "authentication realm" is defined as a set of 923 resources (URIs) for which the same set of user names and passwords 924 is valid for. If the server requests authentication for an 925 authentication realm that the client is already authenticated for, 926 the client will automatically perform the authentication using the 927 already-known secrets. However, for the different authentication 928 realms, the clients SHOULD NOT automatically reuse the usernames and 929 passwords for another realm. 931 Just like in Basic and Digest access authentication protocols, Mutual 932 authentication protocol supports multiple, separate authentication 933 realms to be set up inside each host. Furthermore, the protocol 934 supports that a single authentication realm spans over several hosts 935 within the same Internet domain. 937 Each authentication realm is defined and distinguished by the triple 938 of an "authentication algorithm", an "authentication domain", and a 939 "realm" parameter. However, server operators are NOT RECOMMENDED to 940 use the same pair of an authentication domain and a realm for 941 different authentication algorithms. 943 The realm parameter is a string as defined in Section 4. 944 Authentication domains are described in the remainder of this 945 section. 947 An authentication domain specifies the range of hosts that the 948 authentication realm spans over. In this protocol, it MUST be one of 949 the following strings. 951 o The string in format "://:", where , 952 , and are the URI parts of the requested URI. Even 953 if the request-URI does not have a port part, the string will 954 include one (i.e. 80 for http and 443 for https). Use this when 955 authentication is only valid for specific protocol (such as 956 https). 958 o The "host" part of the requested URI. This is the default value. 959 Authentication realms within this kind of authentication domain 960 will span over several protocols (i.e. http and https) and ports, 961 but not over different hosts. 963 o The string in format "*.", where 964 is either the host part of the requested URI or any domain in 965 which the requested host is included (this means that the 966 specification "*.example.com" is valid for all of hosts 967 "www.example.com", "web.example.com", "www.sales.example.com" and 968 "example.com"). The domain-postfix sent from the servers MUST be 969 equal to or included in a valid Internet domain assigned to a 970 specific organization: if clients know, by some means such as a 971 blacklist for HTTP cookies, that the specified domain is not to be 972 assigned to any specific organization (e.g. "*.com" or "*.jp"), 973 the clients are RECOMMENDED to reject the authentication request. 975 In the above specifications, every "scheme", "host", and "domain" 976 MUST be in lower-case, and any internationalized domain names beyond 977 the ASCII character set SHALL be represented in the way they are sent 978 in the underlying HTTP protocol, represented in lower-case 979 characters; i.e.  these SHALL be in the form of the LDH labels in 980 IDNA [RFC5890]. All "port"s MUST be in the shortest, unsigned, 981 decimal number notation. Not obeying these requirements will cause 982 failure of valid authentication attempts. 984 5.1. Resolving ambiguities 986 In the above definitions of authentication domains, several domains 987 will overlap each other. Depending on the "path" parameters given in 988 the "401-KEX-S1" message (see Section 4), there may be several 989 candidates when the client is going to send a request including an 990 authentication credential (Steps 3 and 4 of the decision procedure 991 presented in Section 8). 993 If such choices are required, the following procedure SHOULD be 994 followed. 996 o If the client has previously sent a request to the same URI, and 997 it remembers the authentication realm requested by 401-INIT 998 messages at that time, use that realm. 1000 o In other cases, use one of authentication realms representing the 1001 most-specific authentication domains. From the list of possible 1002 domain specifications shown above, each one has priority over ones 1003 described after that. 1005 If there are several choices with different domain-postfix 1006 specifications, the one that has the longest domain-postfix has 1007 priority over ones with a shorter domain-postfix. 1009 o If there are realms with the same authentication domain, there is 1010 no defined priority: the client MAY choose any one of the possible 1011 choices. 1013 If possible, server operators are encouraged to avoid such 1014 ambiguities by properly setting the "path" parameters. 1016 6. Session Management 1018 In the Mutual authentication protocol, a session represented by an 1019 sid is set up using first four messages (first request, 401-INIT, 1020 req-KEX-C1 and 401-KEX-S1), and a "session secret" (z) associated 1021 with the session is established. After sharing a session secret, 1022 this session, along with the secret, can be used for one or more 1023 requests for resources protected by the same realm in the same 1024 server. Note that session management is only an inside detail of the 1025 protocol and usually not visible to normal users. If a session 1026 expires, the client and server SHOULD automatically reestablish 1027 another session without informing the users. 1029 The sessions are local to each port of the host inside an 1030 authentication domain; the clients MUST establish separate sessions 1031 for each port of a host to be accessed. 1033 The server SHOULD accept at least one req-VFY-C request for each 1034 session, given that the request reaches the server in a time window 1035 specified by the timeout field in the 401-KEX-S1 message, and that 1036 there are no emergent reasons (such as flooding attacks) to forget 1037 the sessions. After that, the server MAY discard any session at any 1038 time and MAY send 401-STALE messages for any req-VFY-C requests. 1040 The client MAY send two or more requests using a single session 1041 specified by the sid. However, for all such requests, each value of 1042 the nonce (in the nc field) MUST satisfy the following conditions: 1044 o It is a natural number. 1046 o The same nonce was not sent within the same session. 1048 o It is not larger than the nc-max value that was sent from the 1049 server in the session represented by the sid. 1051 o It is larger than (largest-nc - nc-window), where largest-nc is 1052 the maximal value of nc which was previously sent in the session, 1053 and nc-window is the value of the nc-window field which was 1054 received from the server in the session. 1056 The last condition allows servers to reject any nonce values that are 1057 "significantly" smaller than the "current" value (defined by the 1058 value of nc-window) of the nonce used in the session involved. In 1059 other words, servers MAY treat such nonces as "already received". 1060 This restriction enables servers to implement duplicated nonce 1061 detection in a constant amount of memory (for each session). 1063 Servers MUST check for duplication of the received nonces, and if any 1064 duplication is detected, the server MUST discard the session and 1065 respond with a 401-STALE message, as outlined in Section 9. The 1066 server MAY also reject other invalid nonce values (such as ones above 1067 the nc-max limit) by sending a 401-STALE message. 1069 For example, assume the nc-window value of the current session is 32, 1070 nc-max is 100, and that the client has already used the following 1071 nonce values: {1-20, 22, 24, 30-38, 45-60, 63-72}. Then the nonce 1072 values that can be used for next request is one of the following set: 1073 {41-44, 61-62, 73-100}. The values {0, 21, 23, 25-29, 39-40} MAY be 1074 rejected by the server because they are not above the current "window 1075 limit" (40 = 72 - 32). 1077 Typically, clients can ensure the above property by using a 1078 monotonically-increasing integer counter that counts from zero upto 1079 the value of nc-max. 1081 The values of the nonces and any nonce-related values MUST always be 1082 treated as natural numbers within an infinite range. Implementations 1083 using fixed-width integers or fixed-precision floating numbers MUST 1084 correctly and carefully handle integer overflows. Such 1085 implementations are RECOMMENDED to accept any larger values that 1086 cannot be represented in the fixed-width integer representations, as 1087 long as other limits such as internal header-length restrictions are 1088 not involved. The protocol is designed carefully so that both the 1089 clients and servers can implement the protocol using only fixed-width 1090 integers, by rounding any overflowed values to the maximum possible 1091 value. 1093 7. Validation Methods 1095 The "validation method" specifies a method to "relate" the mutual 1096 authentication processed by this protocol with other authentications 1097 already performed in the underlying layers and to prevent man-in-the- 1098 middle attacks. It decides the value v that is an input to the 1099 authentication protocols. 1101 The valid tokens for the validation field and corresponding values of 1102 v are as follows: 1104 host: hostname validation: The value v will be the ASCII 1105 string in the following format: 1106 "://:", where , , 1107 and are the URI components corresponding to the 1108 currently accessing resource. The scheme and host are 1109 in lower-case, and the port is in a shortest decimal 1110 representation. Even if the request-URI does not have 1111 a port part, v will include one. 1113 tls-cert: TLS certificate validation: The value v will be the 1114 octet string of the hash value of the public key 1115 certificate used in the underlying TLS [RFC5246] (or 1116 SSL) connection. The hash value is defined as the 1117 value of the entire signed certificate (specified as 1118 "Certificate" in [RFC5280]), hashed by the hash 1119 algorithm specified by the authentication algorithm 1120 used. 1122 tls-key: TLS shared-key validation: The value v will be the 1123 octet string of the shared master secret negotiated in 1124 the underlying TLS (or SSL) connection. 1126 If the HTTP protocol is used on a non-encrypted channel (TCP and 1127 SCTP, for example), the validation type MUST be "host". If HTTP/TLS 1128 [RFC2818] (https) protocol is used with the server certificates, the 1129 validation type MUST be either "tls-cert" or "tls-key". If HTTP/TLS 1130 protocol is used with an anonymous Diffie-Hellman key exchange, the 1131 validation type MUST be "tls-key" (see the note below). 1133 If the validation type "tls-cert" is used, the server certificate 1134 provided on TLS connection MUST be verified to make sure that the 1135 server actually owns the corresponding secret key. 1137 Clients MUST validate this field upon reception of the 401-INIT 1138 messages. 1140 However, when the client is a Web browser with any scripting 1141 capabilities, the underlying TLS channel used with HTTP/TLS MUST 1142 provide server identity verification. This means (1) the anonymous 1143 Diffie-Hellman key exchange ciphersuite MUST NOT be used, and (2) the 1144 verification of the server certificate provided from the server MUST 1145 be performed. 1147 For other systems, when the underlying TLS channel used with HTTP/TLS 1148 does not perform server identity verification, the client SHOULD 1149 ensure that all the responses are validated using the Mutual 1150 authentication protocol, regardless of the existence of the 401-INIT 1151 responses. 1153 Note: The protocol defines two variants for validation on the TLS 1154 connections. The "tls-key" method is more secure. However, there 1155 are some situations where tls-cert is more preferable. 1157 o When TLS accelerating proxies are used, it is difficult for the 1158 authenticating server to acquire the TLS key information that is 1159 used between the client and the proxy. This is not the case for 1160 client-side "tunneling" proxies using a CONNECT method extension 1161 of HTTP. 1163 o When a black-box implementation of the TLS protocol is used on 1164 either peer. 1166 Implementations supporting a Mutual authentication over the HTTPS 1167 protocol SHOULD support the "tls-cert" validation. Support for 1168 "tls-key" validation is OPTIONAL for both the servers and clients. 1170 8. Decision procedure for client 1172 To securely implement the protocol, the user client must be careful 1173 about accepting the authenticated responses from the server. This 1174 also holds true for the reception of "normal responses" (responses 1175 which do not contain Mutual-related headers) from HTTP servers. 1177 Clients SHOULD implement a decision procedure equivalent to the one 1178 shown below. (Unless implementers understand what is required for 1179 the security, they should not alter this.) In particular, clients 1180 SHOULD NOT accept "normal responses" unless explicitly allowed below. 1181 The labels on the steps are for informational purposes only. Action 1182 entries within each step are checked in top-to-bottom order, and the 1183 first clause satisfied SHOULD be taken. 1185 Step 1 (step_new_request): 1186 If the client software needs to access a new Web resource, check 1187 whether the resource is expected to be inside some authentication 1188 realm for which the user has already been authenticated by the 1189 Mutual authentication scheme. If yes, go to Step 2. Otherwise, 1190 go to Step 5. 1192 Step 2: 1193 Check whether there is an available sid for the authentication 1194 realm you expect. If there is one, go to Step 3. Otherwise, go 1195 to Step 4. 1197 Step 3 (step_send_vfy_1): 1198 Send a req-VFY-C request. 1200 * If you receive a 401-INIT message with a different 1201 authentication realm than expected, go to Step 6. 1203 * If you receive a 200-Optional-INIT message with a different 1204 authentication realm than expected, go to Step 6. 1206 * If you receive a 401-STALE message, go to Step 9. 1208 * If you receive a 401-INIT message, go to Step 13. 1210 * If you receive a 200-VFY-S message, go to Step 14. 1212 * If you receive a normal response, go to Step 11. 1214 Step 4 (step_send_kex1_1): 1215 Send a req-KEX-C1 request. 1217 * If you receive a 401-INIT message with a different 1218 authentication realm than expected, go to Step 6. 1220 * If you receive a 200-Optional-INIT message with a different 1221 authentication realm than expected, go to Step 6. 1223 * If you receive a 401-KEX-S1 message, go to Step 10. 1225 * If you receive a 401-INIT message with the same authentication 1226 realm, go to Step 13 (see Note 1). 1228 * If you receive a normal response, go to Step 11. 1230 Step 5 (step_send_normal_1): 1231 Send a request without any Mutual authentication headers. 1233 * If you receive a 401-INIT message, go to Step 6. 1235 * If you receive a 200-Optional-INIT message, go to Step 6. 1237 * If you receive a normal response, go to Step 11. 1239 Step 6 (step_rcvd_init): 1240 Check whether you know the user's password for the requested 1241 authentication realm. If yes, go to Step 7. Otherwise, go to 1242 Step 12. 1244 Step 7: 1245 Check whether there is an available sid for the authentication 1246 realm you expect. If there is one, go to Step 8. Otherwise, go 1247 to Step 9. 1249 Step 8 (step_send_vfy): 1250 Send a req-VFY-C request. 1252 * If you receive a 401-STALE message, go to Step 9. 1254 * If you receive a 401-INIT message, go to Step 13. 1256 * If you receive a 200-VFY-S message, go to Step 14. 1258 Step 9 (step_send_kex1): 1259 Send a req-KEX-C1 request. 1261 * If you receive a 401-KEX-S1 message, go to Step 10. 1263 * If you receive a 401-INIT message, go to Step 13 (See Note 1). 1265 Step 10 (step_rcvd_kex1): 1266 Send a req-VFY-C request. 1268 * If you receive a 401-INIT message, go to Step 13. 1270 * If you receive a 200-VFY-S message, go to Step 14. 1272 Step 11 (step_rcvd_normal): 1273 The requested resource is out of the authenticated area. The 1274 client will be in the "UNAUTHENTICATED" status. If the response 1275 contains a request for authentications other than Mutual, it MAY 1276 be handled normally. 1278 Step 12 (step_rcvd_init_unknown): 1279 The requested resource requires a Mutual authentication, and the 1280 user is not yet authenticated. The client will be in the 1281 "AUTH_REQUESTED" status, and is RECOMMENDED to process the 1282 content sent from the server, and to ask user for a user name and 1283 a password. When those are supplied from the user, proceed to 1284 Step 9. 1286 Step 13 (step_rcvd_init_failed): 1287 For some reason the authentication failed: possibly the password 1288 or the username is invalid for the authenticated resource. 1289 Forget the password for the authentication realm and go to Step 1290 12. 1292 Step 14 (step_rcvd_vfy): 1293 Check the validity of the received o_b value. If it is equal to 1294 the expected value, it means that the mutual authentication has 1295 succeeded. The client will be in the "AUTH_SUCCEEDED" status. 1297 If the value is unexpected, it is a fatal communication error. 1299 If a user explicitly requests to log out (via user interfaces), 1300 the client MUST forget the user's password, go to step 5 and 1301 reload the current resource without an authentication header. 1303 Note 1: These transitions are valid for clients, but not recommended 1304 for servers to initiate. 1306 Any kind of response (including a normal response) other than those 1307 shown in the above procedure SHOULD be interpreted as a fatal 1308 communication error, and in such cases the clients MUST NOT process 1309 any data (response body and other content-related headers) sent from 1310 the server. However, to handle exceptional error cases, clients MAY 1311 accept a message without an Authentication-Info header, if it is a 1312 Server-Error (5xx) status. The client will be in the 1313 "UNAUTHENTICATED" status in these cases. 1315 The client software SHOULD display the three client status to the 1316 end-user. For an interactive client, however, if a request is a sub- 1317 request for a resource included in another page (e.g., embedded 1318 images, style sheets, frames etc.), its status MAY be omitted from 1319 being shown, and any "AUTH_REQUESTED" statuses MAY be treated in the 1320 same way as an "UNAUTHENTICATED" status. 1322 Figure 10 shows a diagram of the client-side state. 1324 =========== -(11)------------ 1325 NEW REQUEST ( UNAUTHENTICATED ) 1326 =========== ----------------- 1327 | ^ normal 1328 v | response 1329 +(1)-------------------+ NO +(5)----------+ 1330 | The requested URI |--------------------------->| send normal | 1331 | known to be auth'ed? | | request | 1332 +----------------------+ +-------------+ 1333 YES | 401-INIT, 200-Optional-INIT 401-INIT| 1334 | with a different realm 200-Optional-INIT| 1335 | -----------------------------------. | 1336 | / v v 1337 | | -(12)------------ NO +(6)--------+ 1338 | | ( AUTH_REQUESTED )<------| user/pass | 1339 | | ----------------- | known? | 1340 | | +-----------+ 1341 | | |YES 1342 v | v 1343 +(2)--------+ | +(7)--------+ 1344 | session | | | session | NO 1345 NO /| available?| | | available?|\ 1346 / +-----------+ | +-----------+ | 1347 / |YES | |YES | 1348 | | /| | | 1349 | v / | 401- 401- v | 1350 | +(3)--------+ | INIT --(13)---------- INIT +(8)--------+ | 1351 | | send |--+----->/ AUTH_REQUESTED \<-------| send | | 1352 | /| req-VFY-C | | \forget password / | req-VFY-C | | 1353 \/ +-----------+ / ---------------- /+-----------+ | 1354 /\ \ \/ ^ 401-INIT | |401- | 1355 | ------ \/\ 401-STALE | | | STALE / 1356 | \ /\ -----------------+--------------+---. | / 1357 | | / \ | | | | / 1358 | v / | 401- | 401- | v v v 1359 | +(4)--------+ | KEX-S1 +(10)-------+ KEX-S1 | +(9)--------+ 1360 | | send |-|--------->| send |<-------+-| send | 1361 | --| req-KEX-C1| | | req-VFY-C | | | req-KEX-C1| 1362 |/ +-----------+ | +-----------+ | +-----------+ 1363 | |200-VFY-S | 200-VFY-S| ^ 1364 |normal | |200-VFY-S / | 1365 |response | v / ================== 1366 v \ -(14)--------- / USER/PASS INPUTTED 1367 -(11)------------ ------->( AUTH-SUCCEED )<-- ================== 1368 ( UNAUTHENTICATED ) -------------- 1369 ----------------- 1371 Figure 10: State diagram for clients 1373 9. Decision procedure for the server 1375 Each server SHOULD have a table of session states. This table need 1376 not be persistent over a long term; it MAY be cleared upon server 1377 restart, reboot, or others. Each entry in the table SHOULD contain 1378 at least the following information: 1380 o The session identifier, the value of the sid field. 1382 o The algorithm used. 1384 o The authentication realm. 1386 o The state of the protocol: one of "wa received", "authenticated", 1387 "rejected", or "inactive". 1389 o The user name received from the client 1391 o The boolean flag noting whether or not the session is fake. 1393 o When the state is "wa received", the values of wa and sb. 1395 o When the state is "authenticated", the following information: 1397 * The value of the session secret z 1399 * The largest nc received from the client (largest-nc) 1401 * For each possible nc values between (largest-nc - nc- 1402 window + 1) and max_nc, a flag whether or not a request with 1403 the corresponding nc has been received. 1405 The table MAY contain other information. 1407 Servers SHOULD respond to the client requests according to the 1408 following procedure: 1410 o When the server receives a normal request: 1412 * If the requested resource is not protected by the Mutual 1413 Authentication, send a normal response. 1415 * If the resource is protected by the Mutual Authentication, send 1416 a 401-INIT response. 1418 * If the resource is protected by the optional Mutual 1419 Authentication, send a 200-Optional-INIT response. 1421 o When the server receives a req-KEX-C1 request: 1423 * If the requested resource is not protected by the Mutual 1424 Authentication, send a normal response. 1426 * If the authentication realm specified in the req-KEX-C1 request 1427 is not the expected one, send either a 401-INIT or a 1428 200-Optional-INIT response. 1430 * If the server cannot validate the field wa, send a 401-INIT 1431 response. 1433 * If the received user name is either invalid, unknown or 1434 unacceptable, create a new session, mark it a "fake" session, 1435 compute a random value as wb, and send a fake 401-KEX-S1 1436 response. (Note: the server SHOULD NOT send a 401-INIT 1437 response in this case, because it will leak the information to 1438 the client that the specified user will not be accepted. 1439 Instead, postpone it to the response for the next req-VFY-C 1440 request.) 1442 * Otherwise, create a new session, compute wb and send a 1443 401-KEX-S1 response. 1445 The created session has the "wa received" state. 1447 o When the server receives a req-VFY-C request: 1449 * If the requested resource is not protected by the Mutual 1450 Authentication, send a normal response. 1452 * If the authentication realm specified in the req-VFY-C request 1453 is not the expected one, send either a 401-INIT or a 1454 200-Optional-INIT response. 1456 If none of above holds true, the server will lookup the session 1457 corresponding to the received sid and the authentication realm. 1459 * If the session corresponding to the received sid could not be 1460 found, or it is inactive, send a 401-STALE response. 1462 * If the session is in the "rejected" state, send either a 1463 401-INIT or a 401-STALE message. 1465 * If the session is a "fake" session, or if the received oa is 1466 incorrect, then send a 401-INIT response. If the session is in 1467 the "wa received" state, it SHOULD be changed to the "rejected" 1468 state; otherwise, it MAY either be changed to the "rejected" 1469 status or kept in the previous state. 1471 * If the session is in the "active" state, and the request has an 1472 nc value that was previously received from the client, send a 1473 401-STALE message. The session SHOULD be changed to the 1474 "inactive" status. 1476 * If the nc value in the request is larger than the nc-max field 1477 sent from the server, or if it is not larger then (largest-nc - 1478 nc-window) (when in "authenticated" status), the server MAY 1479 (not REQUIRED to) send a 401-STALE message. The session SHOULD 1480 be changed to the "inactive" status if so. 1482 * Otherwise, send a 200-VFY-S response. If the session was in 1483 the "wa received" state, the session SHOULD be changed to an 1484 "authenticated" state. The maximum nc and nc flags of the 1485 state SHOULD be updated properly. 1487 At any time, the server MAY change any state entries with both the 1488 "rejected" and "authenticated" statuses to the "inactive" status, and 1489 MAY discard any "inactive" states from the table. The entries with 1490 the "wa received" status SHOULD be kept unless there is an emergency 1491 situation such as a server reboot or a table capacity overflow. 1493 10. Authentication-Control header 1495 Authentication-Control-header 1496 = "Authentication-Control" ":" [spaces] 1497 auth-scheme spaces Auth-Ctrl-fields 1498 Auth-Ctrl-fields = Auth-Ctrl-field 1499 *([spaces] "," spaces Auth-Ctrl-field) 1500 Auth-Ctrl-field = loc-when-unauthed / loc-when-logout 1501 / logout-timeout 1502 / extension-field 1503 loc-when-unauthed = "location-when-unauthenticated" "=" string 1504 loc-when-logout = "location-when-logout" "=" string 1506 Figure 11: the BNF syntax for the Authentication-Control header 1508 The Authentication-Control header provides a more precise control of 1509 the client behavior for Web applications using the Mutual 1510 authentication protocol. This header will usually be generated in 1511 the application layer, as opposed to WWW-Authenticate headers which 1512 will be generated by the Web servers. 1514 Support of this header is RECOMMENDED for interactive clients and not 1515 required for non-interactive clients. Web applications SHOULD 1516 consider the security impacts of the behaviors of clients that do not 1517 support this header. 1519 The "auth-scheme" of this header and other authentication-related 1520 headers within the same message MUST be equal. This document does 1521 not define any behavior associated with this header, when the 1522 "auth-scheme" of this header is not "Mutual". 1524 10.1. Location-when-unauthenticated field 1526 Authentication-Control: Mutual 1527 location-when-unauthenticated="http://www.example.com/login.html" 1529 The field "location-when-unauthenticated" specifies a location where 1530 any unauthenticated clients should be redirected to. This header may 1531 be used, for example, when there is a central login page for the 1532 entire Web application. The value of this field MUST be a string 1533 that contains an absolute URL location. If a given URL is not 1534 absolute, the clients MAY consider it a relative URL from the current 1535 location. 1537 This field MAY be used with a 401-INIT and 200-Optional-INIT message; 1538 however, use of this field with 200-Optional-INIT messages is not 1539 recommended. If there is a 200-VFY-S, 401-STALE or 401-KEX-S1 1540 message with this field, the clients MUST ignore this field. 1542 When a client receives a message with this field, if and only if the 1543 client's state after processing the response is either Step 12 or 13 1544 (i.e., a state in which the client will process the response body and 1545 ask for the user's password), the client will treat the entire 1546 response as if it were a 303 "See Other" response with a Location 1547 header that contains the value of this field (i.e., client will be 1548 redirected to the specified location with a GET request). Unlike a 1549 normal 303 response, if the client can process authentication without 1550 the user's interaction (like Steps 3, 4, 8, 9 and 10), this field is 1551 ignored. 1553 The specified location SHOULD be included in a set of locations 1554 specified in the "auth-domain" field of the corresponding 401-INIT 1555 message. If this is not satisfied, the clients MAY ignore this 1556 field. 1558 10.2. Location-when-logout field 1560 Authentication-Control: Mutual 1561 location-when-logout="http://www.example.com/byebye.html" 1563 The field "location-when-logout" specifies a location where the 1564 client is to be redirected when the user explicitly request a logout. 1565 The value of this field MUST be a string that contains an absolute 1566 URL location. If a given URL is not absolute, the clients MAY 1567 consider it a relative URL from the current location. 1569 This field MAY be used with 200-VFY-S messages. If there is a 1570 401-INIT, 401-KEX-S1, 401-STALE, 200-Optional-INIT or normal 200 1571 message with this field, the clients MUST ignore this field. 1573 When the user of a client request to terminate an authentication 1574 session, and if the client currently displays a page supplied by a 1575 response with this field, the client will be redirected to the 1576 specified location by a new GET request (as if it received a 303 1577 response), instead of reloading the page without the authentication 1578 credential. Web applications are encouraged to send this field with 1579 an appropriate value for any responses (except those with redirection 1580 (3XX) statuses) for non-GET requests. 1582 10.3. Logout-timeout 1584 Authentication-Control: Mutual logout-timeout=300 1586 The field "logout-timeout" has the same meaning as the field of the 1587 same name in the "Authentication-Info" header. This field will be 1588 used with 200-VFY-S messages. If both are specified, clients are 1589 RECOMMENDED to use the one with the smaller value. 1591 11. Authentication Algorithms 1593 Cryptographic authentication algorithms which are used with this 1594 protocol will be defined separately. The algorithm definition MUST 1595 at least provide a definitions for the following functions: 1597 o The server-side authentication credential J, derived from user- 1598 side authentication credential pi. 1600 o Key exchange values w_A and w_B. 1602 o Shared secret z, to be computed in both server-side and client 1603 side. 1605 o A hash function H to be used with the protocol. 1607 All algorithm used with this protocol SHOULD provide secure mutual 1608 authentication between client and servers, and generate a 1609 cryptographically strong shared secret value z, equivalently strong 1610 to or stronger than the hash function H. If any passwords (or pass- 1611 phrases or any equivalents, i.e. weak secrets) are involved, these 1612 SHOULD NOT be guessable from any data transmitted in the protocol, 1613 even if an attacker (either an eavesdropper or an active server) 1614 knows the possible thoroughly-searchable candidate list of the 1615 passwords. Furthermore, if possible, the function for deriving 1616 server-side authentication credential J is RECOMMENDED to be one-way 1617 so that pi should not be easily computed from J(pi). 1619 11.1. Support functions and notations 1621 In this section we define several support functions and notations to 1622 be shared by several algorithm definitions: 1624 The integers in the specification are in decimal, or in hexadecimal 1625 when prefixed with "0x". 1627 The function octet(c) generates a single octet string whose code 1628 value is equal to c. The operator |, when applied to octet strings, 1629 denotes the concatenation of two operands. 1631 The function VI encodes natural numbers into octet strings in the 1632 following manner: numbers are represented in big-endian radix-128 1633 string, where each digit is represented by a octet within 0x80-0xff 1634 except the last digit represented by a octet within 0x00-0x7f. The 1635 first octet MUST NOT be 0x80. For example, VI(i) = octet(i) for i < 1636 128, and VI(i) = octet(0x80 + (i >> 7)) | octet(i & 127) for 128 <= i 1637 < 16384. This encoding is the same as the one used for the 1638 subcomponents of object identifiers in the ASN.1 encoding 1639 [ITU.X690.1994], and available as a "w" conversion in the pack 1640 function of several scripting languages. 1642 The function VS encodes a variable-length octet string into a 1643 uniquely-decoded, self-delimited octet string, as in the following 1644 manner: 1646 VS(s) = VI(length(s)) | s 1648 where length(s) is a number of octets (not characters) in s. 1650 [Editorial note: Unlike the colon-separated notion used in the Basic/ 1651 Digest HTTP authentication scheme, the string generated by a 1652 concatenation of the VS-encoded strings will be unique, regardless of 1653 the characters included in the strings to be encoded.] 1655 The function OCTETS converts an integer into the corresponding radix- 1656 256 big-endian octet string having its natural length: See 1657 Section 3.2 for the definition of "natural length". 1659 11.2. Default functions for algorithms 1661 The functions defined in this section are common default functions 1662 among authentication algorithms. 1664 The client-side password-based string pi used by this authentication 1665 is derived in the following manner: 1667 pi = H(VS(algorithm) | VS(auth-domain) | VS(realm) | VS(username) | 1668 VS(ph(password)). 1670 The values of algorithm, realm, and auth-domain are taken from the 1671 values contained in the 401-INIT (or 200-Optional-INIT, hereafter 1672 implied) message. When pi is used in the context of an octet string, 1673 it SHALL have the natural length derived from the size of the output 1674 of function H (e.g. 32 octets for SHA-256). The function ph is 1675 determined by the value of the pwd-hash field given in a 401-INIT 1676 message. If the password comes from a user input, it SHOULD first be 1677 prepared using SASLprep [RFC4013]. Then, the password SHALL be 1678 encoded as a UTF-8 string before passed to ph. 1680 The values o_A and o_B are derived by the following equation. 1682 o_A = H(octet(4) | OCTETS(w_A) | OCTETS(w_B) | OCTETS(z) | VI(nc) | 1683 VS(v)) 1685 o_B = H(octet(3) | OCTETS(w_A) | OCTETS(w_B) | OCTETS(z) | VI(nc) | 1686 VS(v)) 1688 Specifications for cryptographic algorithms used with this framework 1689 MAY override the functions pi, o_A, and o_B defined above. In such 1690 cases implementations MUST use the ones defined with such algorithm 1691 specifications. 1693 12. Methods to extend this protocol 1695 If a non-standard extension to this protocol is implemented, it MUST 1696 use the extension-tokens defined in Section 3 to avoid conflicts with 1697 this protocol and other extensions. 1699 Authentication algorithms other than those defined in this document 1700 MAY use other representations for the fields "wa", "wb", "oa", and 1701 "ob", replace those keys, and/or add fields to the messages 1702 containing those fields in supplemental specifications. Two-octet 1703 keys from "wc" to "wz" and from "oc" to "oz" are reserved for this 1704 purpose. If those specifications use keys other than those mentioned 1705 above, it is RECOMMENDED to use extension-tokens to avoid any key- 1706 name conflict with the future extension of this protocol. 1708 Extension-tokens MAY be freely used for any non-standard, private, 1709 and/or experimental uses for those fields provided that the domain 1710 part in the token is appropriately used. 1712 13. IANA Considerations 1714 The tokens used for the authentication-algorithm, pwd-hash, and 1715 validation fields MUST be allocated by IANA. To acquire registered 1716 tokens, a specification for the use of such tokens MUST be available 1717 as an RFC, as outlined in [RFC5226]. 1719 Note: More formal declarations will be added in the future drafts to 1720 meet the RFC 5226 requirements. 1722 14. Security Considerations 1724 14.1. Security Properties 1726 o The protocol is secure against passive eavesdropping and replay 1727 attacks. However, the protocol relies on transport security 1728 including DNS integrity for data secrecy and integrity. HTTP/TLS 1729 SHOULD be used where transport security is not assured and/or data 1730 secrecy is important. 1732 o When used with HTTP/TLS, if TLS server certificates are reliably 1733 verified, the protocol provides true protection against active 1734 man-in-the-middle attacks. 1736 o Even if the server certificate is not used or is unreliable, the 1737 protocol provides protection against active man-in-the-middle 1738 attacks for each HTTP request/response pair. However, in such 1739 cases, JavaScript or similar scripting facilities can be used to 1740 affect the Mutually-authenticated contents from other contents not 1741 protected by this authentication mechanism. This is the reason 1742 why this protocol requires that valid TLS server certificates MUST 1743 be presented (Section 7). 1745 14.2. Denial-of-service attacks to servers 1747 The protocol requires a server-side table of active sessions, which 1748 may become a critical point of the server resource consumptions. For 1749 proper operation, the protocol requires that at least one key 1750 verification request is processed for each session identifier. After 1751 that, servers MAY discard sessions internally at any time, without 1752 causing any operational problems to clients. Clients will silently 1753 reestablishes a new session then. 1755 However, if a malicious client sends too many requests of key 1756 exchanges (req-KEX-C1 messages) only, resource starvation might 1757 occur. In such critical situations, servers MAY discard any kind of 1758 existing sessions regardless of these statuses. One way to mitigate 1759 such attacks are that servers MAY have a number and a time limits for 1760 unverified pending key exchange requests (in the "wa received" 1761 status). 1763 This is a common weakness of authentication protocols with almost any 1764 kind of negotiations or states, including Digest authentication 1765 method and most Cookie-based authentication implementations. 1766 However, regarding the resource consumption, a situation of the 1767 mutual authentication method is a slightly better than the Digest, 1768 because HTTP requests without any kind of authentication requests 1769 will not generate any kind of sessions. Session identifiers are only 1770 generated after a client starts a key negotiation. It means that 1771 simple clients such as web crawlers will not accidentally consume 1772 server-side resources for session managements. 1774 14.3. Implementation Considerations 1776 o To securely implement the protocol, the Authentication-Info 1777 headers in the 200-VFY-S messages MUST always be validated by the 1778 client. If the validation fails, the client MUST NOT process any 1779 content sent with the message, including other headers and the 1780 body part. Non-compliance to this requirement will allow phishing 1781 attacks. 1783 o The authentication status on the client-side SHOULD be visible to 1784 the users of the client. In addition, the method for asking for 1785 the user's name and passwords SHOULD be carefully designed so that 1786 (1) the user can easily distinguish the request from this 1787 authentication method from any other authentication methods such 1788 as Basic and Digest methods, and (2) the Web contents cannot 1789 imitate the user-interfaces for this protocol. 1791 An informational memo regarding user-interface considerations and 1792 recommendations for implementing this protocol will be separately 1793 published. 1795 o For HTTP/TLS communications, when a web form is submitted from 1796 Mutually-authenticated pages with the "tls-cert" validation method 1797 to a URI that is protected by the same realm (so indicated by the 1798 path field), if the server certificate has been changed since the 1799 pages were received, the peer is RECOMMENDED to be revalidated 1800 using a req-KEX-C1 message with an "Expect: 100-continue" header. 1801 The same applies when the page is received with the "tls-key" 1802 validation method, and when the TLS session has expired. 1804 o Server-side storages of user passwords are advised to contain the 1805 values encrypted by one-way function J(pi), instead of the real 1806 passwords, those hashed by ph, or pi. 1808 14.4. Usage Considerations 1810 o The user-names inputted by a user may be sent automatically to any 1811 servers sharing the same auth-domain. This means that when host- 1812 type auth-domain is used for authentication on an HTTPS site, and 1813 when an HTTP server on the same host requests Mutual 1814 authentication within the same realm, the client will send the 1815 user-name in a clear text. If user-names have to be kept secret 1816 against eavesdropping, the server must use full-scheme-type auth- 1817 domain parameter. Contrarily, passwords are not exposed to 1818 eavesdroppers even on HTTP requests. 1820 o The "Pwd_hash" field is only provided for backward compatibility 1821 of password databases. The use of "none" function is the most 1822 secure choice and is RECOMMENDED. If values other than "none" are 1823 used, you MUST ensure that the hash values of the passwords were 1824 not exposed to the public. Note that hashed password databases 1825 for plain-text authentications are usually not considered secret. 1827 o If the server provides several ways for storing server-side 1828 password secrets into the password database, it is advised to 1829 store the values encrypted by using the one-way function J(pi), 1830 instead of the real passwords, those hashed by ph, or pi. 1832 15. Notice on intellectual properties 1834 The National Institute of Advanced Industrial Science and Technology 1835 (AIST) and Yahoo! Japan, Inc. has jointly submitted a patent 1836 application on the protocol proposed in this documentation to the 1837 Patent Office of Japan. The patent is intended to be open to any 1838 implementors of this protocol and its variants under non-exclusive 1839 royalty-free manner. For the details of the patent application and 1840 its status, please contact the author of this document. 1842 The elliptic-curve based authentication algorithms might involve 1843 several existing third-party patents. The authors of the document 1844 take no position regarding the validity or scope of such patents, and 1845 other patents as well. 1847 16. References 1849 16.1. Normative References 1851 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1852 Requirement Levels", BCP 14, RFC 2119, March 1997. 1854 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1855 10646", STD 63, RFC 3629, November 2003. 1857 [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names 1858 and Passwords", RFC 4013, February 2005. 1860 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1861 Encodings", RFC 4648, October 2006. 1863 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1864 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1866 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1867 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1869 16.2. Informative References 1871 [ISO.10646-1.1993] 1872 International Organization for Standardization, 1873 "Information Technology - Universal Multiple-octet coded 1874 Character Set (UCS) - Part 1: Architecture and Basic 1875 Multilingual Plane", ISO Standard 10646-1, May 1993. 1877 [ITU.X690.1994] 1878 International Telecommunications Union, "Information 1879 Technology - ASN.1 encoding rules: Specification of Basic 1880 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1881 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1882 X.690, 1994. 1884 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1885 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1886 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1888 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1889 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1890 Authentication: Basic and Digest Access Authentication", 1891 RFC 2617, June 1999. 1893 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1895 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1896 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1897 May 2008. 1899 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1900 Housley, R., and W. Polk, "Internet X.509 Public Key 1901 Infrastructure Certificate and Certificate Revocation List 1902 (CRL) Profile", RFC 5280, May 2008. 1904 [RFC5890] Klensin, J., "Internationalized Domain Names for 1905 Applications (IDNA): Definitions and Document Framework", 1906 RFC 5890, August 2010. 1908 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 1909 for TLS", RFC 5929, July 2010. 1911 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1912 April 2011. 1914 Appendix A. (Informative) Generic syntax of headers 1916 Several headers (e.g. WWW-Authenticate: headers in 401-INIT, 1917 401-STALE, and 401-KEX-S1 messages) shares common header names. To 1918 parse these headers, one MAY use the following general syntax 1919 definition of the message syntax: 1921 header = header-name ":" [spaces] auth-scheme 1922 spaces fields 1923 header-name = "WWW-Authenticate" / "Optional-WWW-Authenticate" 1924 / "Authorization" / "Authentication-info" 1925 / "Authentication-Control" 1926 auth-scheme = "Mutual" ; see HTTP for other values 1927 fields = field *([spaces] "," spaces field) 1928 field = key "=" value ; either a specific or 1929 ; an extension field 1930 key = extensive-token 1931 token = 1*(%x30-39 / %x41-5A / %x61-7A / "-" / "_") 1932 extensive-token = token / extension-token 1933 extension-token = "-" token 1*("." token) 1934 value = extensive-token / integer 1935 / hex-fixed-number 1936 / base64-fixed-number / string 1937 integer = "0" / (%x31-39 *%x30-39) ; no leading zeros 1938 hex-fixed-number = 1*(%x30-39 / %x41-46 / %x61-66) 1939 base64-fixed-number = string 1940 string = %x22 *(%x20-21 / %x23-5B / %x5D-FF 1941 / %x5C.22 / "\\") %x22 1942 spaces = 1*(" " / %x09) 1944 Figure 12: Common BNF syntax for headers in the protocol 1946 In this way of parsing, messages will be distinguished by the fields 1947 contained in a header corresponding to the authentication. The 1948 procedure below determines the kind of each HTTP request/response. 1950 o If the message is a response with a "401" status: 1952 * If it does not contain any WWW-Authenticate header, it is an 1953 error. 1955 * If the WWW-Authenticate header specifies a scheme other than 1956 "Mutual", it is a normal response within this draft's scope. 1958 * Otherwise, the response contains a "WWW-Authenticate: Mutual" 1959 header. If the header contains both sid and stale fields, it 1960 is an error. 1962 * If the header contains a stale field with a value of 0, it is a 1963 401-INIT message. 1965 * If the header contains a stale field with a value of 1, it is a 1966 401-STALE message. 1968 * If the header contains an sid field, it is a 401-KEX-S1 1969 message. 1971 o If the message is a response other than a "401" status: 1973 * If it contains both Authentication-Info and 1974 Optional-WWW-Authenticate headers, it is an error. 1976 * If it contains a Authentication-Info header with the "Mutual" 1977 scheme, it is a 200-VFY-S message. 1979 * If it contains a Optional-WWW-Authenticate header with the 1980 "Mutual" scheme, it is a 200-Optional-INIT message. 1982 * If it contains a Optional-WWW-Authenticate header with a scheme 1983 other than "Mutual", it is either an error or a normal 1984 response, and the behavior is not defined in this 1985 specification. 1987 * Otherwise, it is a normal response. 1989 o If the message is a request: 1991 * If it does not contain an Authorization header, or it contains 1992 an Authorization header with a scheme other than Mutual, it is 1993 a normal request. 1995 * Otherwise, the request contains a "Authorization: Mutual" 1996 header. If the header contains an sid field, it is a req-VFY-C 1997 message. 1999 * If the header do not contain an sid field, it is a req-KEX-C1 2000 message. 2002 Implementations MAY perform checks stricter than the procedure above, 2003 according to the definitions in Section 3. 2005 Appendix B. (Informative) Draft Remarks from Authors 2007 The following items are currently under consideration for future 2008 revisions by the authors. 2010 o Restructuring of the draft, further separating the HTTP extensions 2011 part from this document. 2013 o Format of the "Authentication-Control" header and other header 2014 fields extending the general HTTP authentication scheme, and 2015 harmonization of those with other draft proposals. 2017 o Whether to keep TLS-key validation or not. 2019 o When keeping tls-key validation, whether to use "TLS channel 2020 binding" [RFC5929] for "tls-key" verification (Section 7). Note 2021 that existing TLS implementations should be considered to 2022 determine this. 2024 o Adding test vectors for ensuring implementation correctness. 2026 o Possibly adding a method for servers to detect availability of 2027 Mutual authentication on client-side. 2029 o Applying the protocol for proxy authentication/authorization. 2031 o Possible support for optional key renewal and cross-site federated 2032 authentication. 2034 Appendix C. (Informative) Draft Change Log 2036 C.1. Changes in revision 09 2038 Note: the token for the header field "version" is NOT changed from 2039 draft-07, because the protocol semantics has not been changed in this 2040 revision. 2042 o The (default) cryptographic algorithms are separated to another 2043 draft. 2045 o Names of the messages are changed to more informative one (like 2046 KEX-C for client key-exchange) than before. 2048 C.2. Changes in revision 08 2050 o The English text has been revised. 2052 C.3. Changes in revision 07 2054 o Adapt to httpbis HTTP/1.1 drafts: 2056 * Changed definition of extensive-token. 2058 * LWSP continuation-line (%0D.0A.20) deprecated. 2060 o To simplify the whole spec, the type of nonce-counter related 2061 fields are change from hex-integer to integer. 2063 o Algorithm tokens are renamed to include names of hash algorithms. 2065 o Clarified the session management, added details of server-side 2066 protocol decisions. 2068 o The whole draft was reorganized; introduction and overview has 2069 been rewritten. 2071 C.4. Changes in revision 06 2073 o Integrated Optional Mutual Authentication to the main part. 2075 o Clarified the decision procedure for message recognitions. 2077 o Clarified that a new authentication request for any sub-requests 2078 in interactive clients may be silently discarded. 2080 o Typos and confusing phrases are fixed. 2082 o Several "future considerations" are added. 2084 C.5. Changes in revision 05 2086 o A new field called "version" is added for supporting future 2087 incompatible changes with a single implementation. In the (first) 2088 final specification its value will be changed to 1. 2090 o A new header "Authentication-Control" is added for precise control 2091 of application-level authentication behavior. 2093 C.6. Changes in revision 04 2095 o Changed text of patent licenses: the phrase "once the protocol is 2096 accepted as an Internet standard" is removed so that the sentence 2097 also covers the draft versions of this protocol. 2099 o The "tls-key" verification is now OPTIONAL. 2101 o Several description fixes and clarifications. 2103 C.7. Changes in revision 03 2105 o Wildcard domain specifications (e.g. "*.example.com") are allowed 2106 for auth-domain parameters (Section 4.1). 2108 o Specification of the "tls-cert" verification is updated 2109 (incompatible change). 2111 o State transitions fixed. 2113 o Requirements for servers concerning w_a values are clarified. 2115 o RFC references are updated. 2117 C.8. Changes in revision 02 2119 o Auth-realm is extended to allow full-scheme type. 2121 o A decision diagram for clients and decision procedures for servers 2122 are added. 2124 o 401-KEX-S1 and req-VFY-C messages are changed to contain 2125 authentication realm information. 2127 o Bugs on equations for o_A and o_B are fixed. 2129 o Detailed equations for the entire algorithm are included. 2131 o Elliptic-curve algorithms are updated. 2133 o Several clarifications and other minor updates. 2135 Authors' Addresses 2137 Yutaka Oiwa 2138 National Institute of Advanced Industrial Science and Technology 2139 Research Center for Information Security 2140 Room #1003, Akihabara Daibiru 2141 1-18-13 Sotokanda 2142 Chiyoda-ku, Tokyo 2143 JP 2145 Phone: +81 3-5298-4722 2146 Email: mutual-auth-contact@m.aist.go.jp 2148 Hajime Watanabe 2149 National Institute of Advanced Industrial Science and Technology 2150 Hiromitsu Takagi 2151 National Institute of Advanced Industrial Science and Technology 2153 Yuichi Ioku 2154 Yahoo! Japan, Inc. 2155 Midtown Tower 2156 9-7-1 Akasaka 2157 Minato-ku, Tokyo 2158 JP 2160 Tatsuya Hayashi 2161 Lepidum Co. Ltd. 2162 #602, Village Sasazuka 3 2163 1-30-3 Sasazuka 2164 Shibuya-ku, Tokyo 2165 JP