idnits 2.17.1 draft-ietf-httpauth-mutual-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 19, 2015) is 3347 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-09) exists of draft-ietf-httpauth-extension-03 == Outdated reference: A later version (-05) exists of draft-ietf-httpbis-auth-info-02 == Outdated reference: A later version (-18) exists of draft-ietf-precis-saslprepbis-13 ** Obsolete normative reference: RFC 2898 (Obsoleted by RFC 8018) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-07) exists of draft-ietf-httpauth-mutual-algo-02 == Outdated reference: A later version (-23) exists of draft-ietf-precis-framework-22 -- 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: 5 errors (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPAUTH Working Group Y. Oiwa 3 Internet-Draft H. Watanabe 4 Intended status: Experimental H. Takagi 5 Expires: August 23, 2015 RISEC, AIST 6 K. Maeda 7 T. Hayashi 8 Lepidum 9 Y. Ioku 10 Individual 11 February 19, 2015 13 Mutual Authentication Protocol for HTTP 14 draft-ietf-httpauth-mutual-04 16 Abstract 18 This document specifies a mutual authentication method for the Hyper- 19 text Transfer Protocol (HTTP). This method provides a true mutual 20 authentication between an HTTP client and an HTTP server using 21 password-based authentication. Unlike the Basic and Digest 22 authentication methods, the Mutual authentication method specified in 23 this document assures the user that the server truly knows the user's 24 encrypted password. 26 Status of this Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on August 23, 2015. 43 Copyright Notice 45 Copyright (c) 2015 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.2. Document Structure and Related Documents . . . . . . . . . 5 63 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 5 64 2.1. Messages Overview . . . . . . . . . . . . . . . . . . . . 6 65 2.2. Typical Flows of the Protocol . . . . . . . . . . . . . . 6 66 2.3. Alternative Flows . . . . . . . . . . . . . . . . . . . . 9 67 3. Message Syntax . . . . . . . . . . . . . . . . . . . . . . . . 10 68 3.1. Non-ASCII extended header parameters . . . . . . . . . . . 11 69 3.2. Values . . . . . . . . . . . . . . . . . . . . . . . . . . 12 70 3.2.1. Tokens . . . . . . . . . . . . . . . . . . . . . . . . 12 71 3.2.2. Strings . . . . . . . . . . . . . . . . . . . . . . . 13 72 3.2.3. Numbers . . . . . . . . . . . . . . . . . . . . . . . 13 73 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 74 4.1. 401-INIT and 401-STALE . . . . . . . . . . . . . . . . . . 15 75 4.2. req-KEX-C1 . . . . . . . . . . . . . . . . . . . . . . . . 17 76 4.3. 401-KEX-S1 . . . . . . . . . . . . . . . . . . . . . . . . 18 77 4.4. req-VFY-C . . . . . . . . . . . . . . . . . . . . . . . . 19 78 4.5. 200-VFY-S . . . . . . . . . . . . . . . . . . . . . . . . 20 79 5. Authentication Realms . . . . . . . . . . . . . . . . . . . . 20 80 5.1. Resolving Ambiguities . . . . . . . . . . . . . . . . . . 22 81 6. Session Management . . . . . . . . . . . . . . . . . . . . . . 22 82 7. Host Validation Methods . . . . . . . . . . . . . . . . . . . 24 83 7.1. Applicability notes . . . . . . . . . . . . . . . . . . . 26 84 7.2. Interoperability notes on tls-unique . . . . . . . . . . . 26 85 8. Authentication Extensions . . . . . . . . . . . . . . . . . . 27 86 9. String Preparation . . . . . . . . . . . . . . . . . . . . . . 27 87 10. Decision Procedure for Clients . . . . . . . . . . . . . . . . 28 88 10.1. General Principles and Requirements . . . . . . . . . . . 28 89 10.2. State machine for the client-side . . . . . . . . . . . . 29 90 11. Decision Procedure for Servers . . . . . . . . . . . . . . . . 34 91 12. Authentication Algorithms . . . . . . . . . . . . . . . . . . 36 92 12.1. Support Functions and Notations . . . . . . . . . . . . . 37 93 12.2. Default Functions for Algorithms . . . . . . . . . . . . . 38 94 13. Application Channel Binding . . . . . . . . . . . . . . . . . 39 95 14. Application for Proxy Authentication . . . . . . . . . . . . . 40 96 15. Methods to Extend This Protocol . . . . . . . . . . . . . . . 40 97 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 98 17. Security Considerations . . . . . . . . . . . . . . . . . . . 41 99 17.1. Security Properties . . . . . . . . . . . . . . . . . . . 41 100 17.2. Denial-of-service Attacks to Servers . . . . . . . . . . . 42 101 17.2.1. On-line Active Password Attacks . . . . . . . . . . . 42 102 17.3. Communicating the status of mutual authentication with 103 users . . . . . . . . . . . . . . . . . . . . . . . . . . 43 104 17.4. Implementation Considerations . . . . . . . . . . . . . . 43 105 17.5. Usage Considerations . . . . . . . . . . . . . . . . . . . 44 106 18. Notice on Intellectual Properties . . . . . . . . . . . . . . 44 107 19. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 108 19.1. Normative References . . . . . . . . . . . . . . . . . . . 45 109 19.2. Informative References . . . . . . . . . . . . . . . . . . 46 110 Appendix A. (Informative) Draft Remarks from Authors . . . . . . 47 111 Appendix B. (Informative) Draft Change Log . . . . . . . . . . . 47 112 B.1. Changes in Httpauth WG Revision 04 . . . . . . . . . . . . 47 113 B.2. Changes in Httpauth WG Revision 03 . . . . . . . . . . . . 48 114 B.3. Changes in Httpauth WG Revision 02 . . . . . . . . . . . . 48 115 B.4. Changes in Httpauth WG Revision 01 . . . . . . . . . . . . 48 116 B.5. Changes in Httpauth Revision 00 . . . . . . . . . . . . . 48 117 B.6. Changes in HttpBis Revision 00 . . . . . . . . . . . . . . 49 118 B.7. Changes in Revision 12 . . . . . . . . . . . . . . . . . . 49 119 B.8. Changes in Revision 11 . . . . . . . . . . . . . . . . . . 49 120 B.9. Changes in Revision 10 . . . . . . . . . . . . . . . . . . 49 121 B.10. Changes in Revision 09 . . . . . . . . . . . . . . . . . . 50 122 B.11. Changes in Revision 08 . . . . . . . . . . . . . . . . . . 50 123 B.12. Changes in Revision 07 . . . . . . . . . . . . . . . . . . 50 124 B.13. Changes in Revision 06 . . . . . . . . . . . . . . . . . . 51 125 B.14. Changes in Revision 05 . . . . . . . . . . . . . . . . . . 51 126 B.15. Changes in Revision 04 . . . . . . . . . . . . . . . . . . 51 127 B.16. Changes in Revision 03 . . . . . . . . . . . . . . . . . . 52 128 B.17. Changes in Revision 02 . . . . . . . . . . . . . . . . . . 52 129 B.18. Changes in Revision 01 . . . . . . . . . . . . . . . . . . 52 130 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52 132 1. Introduction 134 This document specifies a mutual authentication method for Hyper-Text 135 Transfer Protocol (HTTP). The method, called "Mutual Authentication 136 Protocol" in this document, provides a true mutual authentication 137 between an HTTP client and an HTTP server, using just a simple 138 password as a credential. 140 The authentication method proposed in this document has the following 141 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. This makes it impossible for fake website owners 147 to persuade users that they have authenticated with the original 148 websites. 150 o It uses only passwords as the user's credential: unlike public- 151 key-based security algorithms, the method does not rely on secret 152 keys or other cryptographic data that have to be stored inside the 153 users' computers. The proposed method can be used as a drop-in 154 replacement to the current authentication methods like Basic or 155 Digest, while ensuring a much stronger level of security. 157 o It is secure: when the server fails to authenticate with a user, 158 the protocol will not reveal any tiny bit of information about the 159 user's password. 161 1.1. Terminology 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 165 "OPTIONAL" in this document are to be interpreted as described in 166 [RFC2119]. 168 This document distinguishes the terms "client" and "user" in the 169 following way: A "client" is an entity understanding and talking HTTP 170 and the specified authentication protocol, usually computer software; 171 a "user" is a (usually natural) person who wants to access data 172 resources using "a client". 174 The term "natural numbers" refers to the non-negative integers 175 (including zero) throughout this document. 177 This document treats target (codomain) of hash functions to be octet 178 strings. The notation INT(H(s)) gives a numerical (natural-number) 179 output of hash function H applied to string s. 181 1.2. Document Structure and Related Documents 183 The entire document is organized as follows: 185 o Section 2 presents an overview of the protocol design. 187 o Sections 3 to 11 define a general framework of the Mutual 188 authentication protocol. This framework is independent of 189 specific cryptographic primitives. 191 o Section 12 describes properties needed for cryptographic 192 algorithms used with this protocol framework, and defines a few 193 functions which will be shared among such cryptographic 194 algorithms. 196 o The sections after that contain general normative and informative 197 information about the protocol. 199 o The appendices contain some information that may help developers 200 to implement the protocol. 202 In addition, there are two companion documents which are referred 203 from/related to this specification: 205 o [I-D.ietf-httpauth-mutual-algo]: defines a cryptographic 206 primitives which can be used with this protocol framework. [draft 207 note: it is separated from this document so that it may be 208 replaced with another crypto in future.] 210 o [I-D.ietf-httpauth-extension]: defines a small but useful 211 extensions to the current HTTP authentication framework so that it 212 can support application-level semantics of existing Web systems. 214 2. Protocol Overview 216 The protocol, as a whole, is designed as a natural extension to the 217 HTTP protocol [RFC7230] using a framework defined in [RFC7235]. 218 Internally, the server and the client will first perform a 219 cryptographic key exchange, using the secret password as a "tweak" to 220 the exchange. The key-exchange will only succeed when the secrets 221 used by the both peers are correctly related (i.e. generated from the 222 same password). Then, both peers will verify the authentication 223 results by confirming the sharing of the exchanged key. This section 224 describes a brief image of the protocol and the exchanged messages. 226 2.1. Messages Overview 228 The authentication protocol uses seven kinds of messages to perform 229 mutual authentication. These messages have specific names within 230 this specification. 232 o Authentication request messages: used by the servers to request 233 clients to start mutual authentication. 235 * 401-INIT message: a general message to start the authentication 236 protocol. It is also used as a message indicating an 237 authentication failure. 239 * 401-STALE message: a message indicating that it has to start a 240 new authentication trial. 242 o Authenticated key exchange messages: used by both peers to perform 243 authentication and the sharing of a cryptographic secret. 245 * req-KEX-C1 message: a message sent from the client. 247 * 401-KEX-S1 message: a message sent from the server as a 248 response to a req-KEX-C1 message. 250 o Authentication verification messages: used by both peers to verify 251 the authentication results. 253 * req-VFY-C message: a message used by the client, requesting 254 that the server authenticates and authorizes the client. 256 * 200-VFY-S message: a successful response used by the server, 257 and also asserting that the server is authentic to the client 258 simultaneously. 260 In addition to the above, either a request or a response without any 261 HTTP headers related to this specification will be hereafter called a 262 "normal request" or a "normal response", respectively. 264 2.2. Typical Flows of the Protocol 266 In typical cases, the client access to a resource protected by the 267 Mutual authentication will follow the following protocol sequence. 269 Client Server 270 | | 271 | ---- (1) normal request ---------> | 272 GET / HTTP/1.1 | 273 | | 274 | <---------------- (2) 401-INIT --- | 275 | 401 Authentication Required 276 | WWW-Authenticate: Mutual realm="a realm" 277 | | 278 [user, | | 279 pass]-->| | 280 | ---- (3) req-KEX-C1 -------------> | 281 GET / HTTP/1.1 | 282 Authorization: Mutual user="john", |--> [user DB] 283 kc1="...", ... |<-- [user info] 284 | | 285 | <-------------- (4) 401-KEX-S1 --- | 286 | 401 Authentication Required 287 | WWW-Authenticate: Mutual sid=..., ks1="...", ... 288 | | 289 [compute] (5) compute session secret [compute] 290 | | 291 | | 292 | ---- (6) req-VFY-C --------------> | 293 GET / HTTP/1.1 |--> [verify (6)] 294 Authorization: Mutual sid=..., |<-- OK 295 vkc="...", ... | 296 | | 297 | <--------------- (7) 200-VFY-S --- | 298 [verify | 200 OK | 299 (7)]<--| Authentication-Info: Mutual vks="..." 300 | | 301 v v 303 Figure 1: Typical communication flow for first access to resource 305 o As usual in general HTTP protocol designs, a client will at first 306 request a resource without any authentication attempt (1). If the 307 requested resource is protected by the Mutual authentication, the 308 server will respond with a message requesting authentication 309 (401-INIT) (2). 311 o The client processes the body of the message, and waits for the 312 user to input the user name and a password. If the user name and 313 the password are available, the client will send a message with 314 the authenticated key exchange (req-KEX-C1) to start the 315 authentication (3). 317 o If the server has received a req-KEX-C1 message, the server looks 318 up the user's authentication information within its user database. 319 Then the server creates a new session identifier (sid) that will 320 be used to identify sets of the messages that follow it, and 321 responds back with a message containing a server-side 322 authenticated key exchange value (401-KEX-S1) (4). 324 o At this point (5), both peers calculate a shared "session secret" 325 using the exchanged values in the key exchange messages. Only 326 when both the server and the client have used secret credentials 327 generated from the same password,the session secret values will 328 match. This session secret will be used for access authentication 329 of every individual request after this point. 331 o The client will send a request with a client-side authentication 332 verification value (req-VFY-C) (6), generated from the client- 333 owned session secret. The server will check the validity of the 334 verification value using its own session secret. 336 o If the authentication verification value from the client was 337 correct, it means that the client definitely owns the credential 338 based on the expected password (i.e. the client authentication 339 succeeded.) The server will respond with a successful message 340 (200-VFY-S) (7). Contrary to the usual one-way authentication 341 (e.g. HTTP Basic authentication or POP APOP authentication 342 [RFC1939]), this message also contains a server-side 343 authentication verification value. 345 When the client's verification value is incorrect (e.g. because 346 the user-supplied password was incorrect), the server will respond 347 with the 401-INIT message (the same one as used in (2)) instead. 349 o The client MUST first check the validity of the server-side 350 authentication verification value contained in the message (7). 351 If the value was equal to the expected one, the server 352 authentication succeeded. 354 If it is not the value expected, or if the message does not 355 contain the authentication verification value, it means that the 356 mutual authentication has been broken for some unexpected reason. 357 The client MUST NOT process any body or header values contained in 358 this case. (Note: This case should not happen between a 359 correctly-implemented server and a client without any 360 interventions. Possible cause of such cases might be either a 361 man-in-the-middle attack or a mis-implementation.) 363 2.3. Alternative Flows 365 As shown above, the typical flow for a first authenticated request 366 requires three request-response pairs. To reduce the protocol 367 overhead, the protocol enables several short-cut flows which require 368 fewer messages. 370 o (case A) If the client knows that the resource is likely to 371 require the authentication, the client MAY omit the first 372 unauthenticated request (1) and immediately send a key exchange 373 (req-KEX-C1 message). This will reduce one round-trip of 374 messages. 376 o (case B) If both the client and the server previously shared a 377 session secret associated with a valid session identifier (sid), 378 the client MAY directly send a req-VFY-C message using the 379 existing session identifier and corresponding session secret. 380 This will further reduce one round-trip of messages. 382 In such cases, the server MAY have thrown out the corresponding 383 sessions from the session table. In this case, the server will 384 respond with a 401-STALE message, indicating a new key exchange is 385 required. The client SHOULD retry constructing a req-KEX-C1 386 message in this case. 388 Figure 2 depicts the shortcut flows described above. Under the 389 appropriate settings and implementations, most of the requests to 390 resources are expected to meet both the criteria, and thus only one 391 round-trip of request/responses will be required in most cases. 393 (A) omit first request 394 (2 round trips) 396 Client Server 397 | | 398 | --- req-KEX-C1 ----> | 399 | | 400 | <---- 401-KEX-S1 --- | 401 | | 402 | ---- req-VFY-C ----> | 403 | | 404 | <----- 200-VFY-S --- | 405 | | 407 (B) reusing session secret (re-authentication) 409 (B-1) key available (B-2) key expired 410 (1 round trip) (3 round trips) 412 Client Server Client Server 413 | | | | 414 | ---- req-VFY-C ----> | | --- req-VFY-C -------> | 415 | | | | 416 | <----- 200-VFY-S --- | | <------- 401-STALE --- | 417 | | | | 418 | --- req-KEX-C1 ------> | 419 | | 420 | <------ 401-KEX-S1 --- | 421 | | 422 | --- req-VFY-C -------> | 423 | | 424 | <------- 200-VFY-S --- | 425 | | 427 Figure 2: Several alternative flows on protocol 429 For more details, see Sections 10 and 11. 431 3. Message Syntax 433 Throughout this specification, The syntax is denoted in the extended 434 augmented BNF syntax defined in [RFC7230] and [RFC5234]. The 435 following elements are quoted from [RFC5234], [RFC7230] and 436 [RFC7235]: DIGIT, ALPHA, SP, auth-scheme, quoted-string, auth-param, 437 header-field, token, challenge, and credential. 439 The Mutual authentication protocol uses three headers: 440 WWW-Authenticate (in responses with status code 401), Authorization 441 (in requests), and Authentication-Info (in responses other than 401 442 status). These headers follow a common framework described in 443 [RFC7235] and [I-D.ietf-httpbis-auth-info]. The detailed meanings 444 for these headers are contained in Section 4. 446 The framework in [RFC7235] defines the syntax for the headers 447 WWW-Authenticate and Authorization as the syntax elements "challenge" 448 and "credentials", respectively. The "auth-scheme" contained in 449 those headers MUST be "Mutual" throughout this protocol 450 specification. The syntax for "challenge" and "credentials" to be 451 used with the "Mutual" auth-scheme SHALL be name-value pairs (#auth- 452 param), not the "b64token" defined in [RFC7235]. 454 The Authentication-Info: header used in this protocol SHALL follow 455 the syntax defined in [I-D.ietf-httpbis-auth-info]. 457 In HTTP, the WWW-Authenticate header may contain more than one 458 challenges. Client implementations SHOULD be aware of and be capable 459 of handle those cases correctly. 461 3.1. Non-ASCII extended header parameters 463 All of parameters contained in the above three headers, except the 464 "realm" field, MAY be extended to ISO 10646-1 values using the 465 framework described in [RFC5987]. All servers and clients MUST be 466 capable of receiving and sending values encoded in [RFC5987] syntax. 468 If a value to be sent contains only ASCII characters, the field MUST 469 be sent in clear using plain RFC 7235 syntax. The syntax extended by 470 RFC 5987 MUST NOT be used in this case. 472 If a value (except the "realm" header) contains one or more non-ASCII 473 characters, the parameter SHOULD be sent using the syntax defined in 474 Section 3.2 of [RFC5987] as "ext-parameter". Such parameter MUST 475 have charset value of "UTF-8", and the language value MUST always be 476 omitted (have an empty value). The same parameter MUST NOT be sent 477 twice or more, those in both plain- and extended-syntax. 479 For example, a parameter "user" with value "Renee or France" SHOULD 480 be sent as < user="Renee of France" >. If the value is "Rene of France", it SHOULD be sent as < user*=UTF- 482 8''Ren%C3%89e%20of%20France > instead. 484 [RFC7235] requires realm parameter to be exist as its plain form (not 485 as extended "realm*" parameter), so RFC 5987 syntax MUST NOT be used 486 for this parameter. 488 3.2. Values 490 The parameter values contained in challenge/credentials MUST be 491 parsed strictly conforming to the HTTP semantics (especially un- 492 quoting of the string parameter values). In this protocol, those 493 values are further categorized into the following value types: tokens 494 (bare-token and extensive-token), string, integer, hex-fixed-number, 495 and base64-fixed-number. 497 For clarity, implementations are RECOMMENDED to use the canonical 498 representations specified in the following subsections for sending 499 values. Recipients SHOULD accept both quoted and unquoted 500 representations interchangeably as specified in HTTP. 502 3.2.1. Tokens 504 For sustaining both security and extensibility at the same time, this 505 protocol defines a stricter sub-syntax for the "token" to be used. 506 The extensive-token values SHOULD follow the following syntax (after 507 HTTP value parsing): 509 bare-token = 1*(DIGIT / ALPHA / "-" / "_") 510 extension-token = "-" bare-token 1*("." bare-token) 511 extensive-token = bare-token / extension-token 513 Figure 3: BNF syntax for token values 515 The tokens (bare-token and extension-token) are case insensitive; 516 Senders SHOULD send these in lower-case, and receivers MUST accept 517 both upper- and lower-cases. When tokens are used as (partial) 518 inputs to any hash or other mathematical functions, it MUST always be 519 used in lower-case. 521 Extensive-tokens are used in this protocol where the set of 522 acceptable tokens may include non-standard extensions. Any non- 523 standard extensions of this protocol SHOULD use the extension-tokens 524 with format "-.", where is a 525 validly registered (sub-)domain name on the Internet owned by the 526 party who defines the extensions. 528 Bare-tokens and extensive-tokens are also used for parameter names 529 (of course in the unquoted form). Requirements for using the 530 extension-token for the parameter names are the same as the above. 532 The canonical format for bare-tokens and tokens are unquoted tokens. 534 3.2.2. Strings 536 All character strings MUST be encoded to octet strings using the 537 UTF-8 encoding [RFC3629] for the ISO 10646-1 character set 538 [ISO.10646-1.1993]. Such strings MUST NOT contain any leading BOM 539 characters (ZERO WIDTH NO-BREAK SPACE, U+FEFF or EF BB BF). Both 540 peers are RECOMMENDED to reject any invalid UTF-8 sequences that 541 might cause decoding ambiguities (e.g., containing <"> in the second 542 or later bytes of the UTF-8 encoded characters). 544 If strings are representing a domain name or URI that contains non- 545 ASCII characters, the host parts SHOULD be encoded as it is used in 546 the HTTP protocol layer (e.g. in a Host: header); under current 547 standards it will be the one defined in [RFC5890]. It SHOULD use 548 lower-case ASCII characters. 550 The canonical format for strings are quoted-string (as it may contain 551 equal signs, plus signs and slashes), unless the parameter containing 552 the string value will use extended syntax defined in [RFC5987]. 553 ([RFC5987] extended parameter will have unquoted encoded value, as 554 defined there.) 556 3.2.3. Numbers 558 The following syntax definitions gives a syntax for number-type 559 values: 561 integer = "0" / (%x31-39 *DIGIT) ; no leading zeros 562 hex-fixed-number = 1*(2(DIGIT / %x41-46 / %x61-66)) 563 base64-fixed-number = 1*( ALPHA / DIGIT / "+" / "/" ) 0*2"=" 565 Figure 4: BNF syntax for number types 567 The syntax definition of the integers only allows representations 568 that do not contain extra leading zeros. 570 The numbers represented as a hex-fixed-number MUST include an even 571 number of characters (i.e. multiples of eight bits). Those values 572 are case-insensitive, and SHOULD be sent in lower-case. When these 573 values are generated from any cryptographic values, they SHOULD have 574 their "natural length": if these are generated from a hash function, 575 these lengths SHOULD correspond to the hash size; if these are 576 representing elements of a mathematical set (or group), its lengths 577 SHOULD be the shortest for representing all the elements in the set. 578 For example, any results of SHA-256 hash function will be represented 579 by 64 characters, and any elements in 2048-bit prime field (modulo a 580 2048-bit integer) will be represented by 512 characters, regardless 581 of how much 0's will be appear in front of such representations. 583 Session-identifiers and other non-cryptographically generated values 584 are represented in any (even) length determined by the side who 585 generates it first, and the same length SHALL be used throughout the 586 all communications by both peers. 588 The numbers represented as base64-fixed-number SHALL be generated as 589 follows: first, the number is converted to a big-endian radix-256 590 binary representation as an octet string. The length of the 591 representation is determined in the same way as mentioned above. 592 Then, the string is encoded using the Base 64 encoding [RFC4648] 593 without any spaces and newlines. Implementations decoding base64- 594 fixed-number SHOULD reject any input data with invalid characters, 595 excess/insufficient paddings, or non-canonical pad bits (See Sections 596 3.1 to 3.5 of [RFC4648]). 598 The canonical format for integer and hex-fixed-number are unquoted 599 tokens, and that for base64-fixed-number is quoted-string. 601 4. Messages 603 In this section we define the seven kinds of messages used in the 604 authentication protocol along with the formats and requirements of 605 the headers for each message. 607 To determine which message are expected to be sent, see Sections 10 608 and 11. 610 In the descriptions below, the type of allowable values for each 611 header parameter is shown in parenthesis after each parameter name. 612 The "algorithm-determined" type means that the acceptable value for 613 the parameter is one of the types defined in Section 3, and is 614 determined by the value of the "algorithm" parameter. The parameters 615 marked "mandatory" SHALL be contained in the message. The parameters 616 marked "non-mandatory" MAY either be contained or omitted in the 617 message. Each parameter SHALL appear in each headers exactly once at 618 most. 620 All credentials and challenges MAY contain any parameters not 621 explicitly specified in the following sections. Recipients who do 622 not understand such parameters MUST silently ignore those. However, 623 all credentials and challenges MUST meet the following criteria: 625 o For responses, the parameters "reason", any "ks#" (where # stands 626 for any decimal integers), and "vks" are mutually exclusive: any 627 challenge MUST NOT contain two or more parameters among them. 628 They MUST NOT contain any "kc#" and "vkc" parameters. 630 o For requests, the parameters "kc#" (where # stands for any decimal 631 integers), and "vkc" are mutually exclusive and any challenge 632 MUST NOT contain two or more parameters among them. They MUST NOT 633 contain any "ks#" and "vks" parameters. 635 Every message in this section contains a "version" field, to detect 636 future incompatible revisions of the protocol. Implementations of 637 the protocol described in this specification MUST always send a token 638 "-wg-draft04", and recipients MUST reject messages which contain any 639 other value as a version, unless another specification defines a 640 behavior for that version. [[Editorial Note: This token is updated 641 on every draft revisions which will affect the wire protocol. It 642 will (shall) be updated to "1" in the final published RFC.]] 644 4.1. 401-INIT and 401-STALE 646 Every 401-INIT or 401-STALE message SHALL be a valid HTTP 401-status 647 (Authentication Required) message containing one (and only one: 648 hereafter not explicitly noticed) "WWW-Authenticate" header 649 containing a "reason" parameter in the challenge. The challenge 650 SHALL contain all of the parameters marked "mandatory" below, and MAY 651 contain those marked "non-mandatory". 653 version: (mandatory extensive-token) should be the token "-wg- 654 draft04". 656 algorithm: (mandatory extensive-token) specifies the 657 authentication algorithm to be used. The value MUST 658 be one of the tokens specified in 659 [I-D.ietf-httpauth-mutual-algo] or other supplemental 660 specification documentation. 662 validation: (mandatory extensive-token) specifies the method of 663 host validation. The value MUST be one of the tokens 664 described in Section 7, or the tokens specified in 665 other supplemental specification documentation. 667 auth-domain: (non-mandatory string) specifies the authentication 668 domain, the set of hosts for which the authentication 669 credentials are valid. It MUST be one of the strings 670 described in Section 5. If the value is omitted, it 671 is assumed to be the "single-server" type domain in 672 Section 5. 674 realm: (mandatory string) is a string representing the name 675 of the authentication realm inside the authentication 676 domain. As specified in [RFC7235], this value MUST 677 always be sent in the quoted-string form, and an 679 [RFC5987] encoding MUST NOT be used. 680 The realm value sent from the server SHOULD be an 681 ASCII string. Clients MAY treat any non-ASCII value 682 received in this field as one of a binary blob, an 683 NFC-normalized UTF-8 string, or an error. 685 pwd-hash: (non-mandatory extensive-token) specifies the hash 686 algorithm (hereafter referred to by ph) used for 687 additionally hashing the password. The valid tokens 688 are 690 * none: ph(p) = p 692 * md5: ph(p) = MD5(p) 694 * digest-md5: ph(p) = MD5(username | ":" | realm | 695 ":" | p), the same value as MD5(A1) for "MD5" 696 algorithm in [RFC2617]. 698 * sha1: ph(p) = SHA1(p) 700 If omitted, the value "none" is assumed. The use of 701 "none" is desirable. 703 reason: (mandatory extensive-token) SHALL be an extensive- 704 token which describes the possible reason of the 705 failed authentication/authorization. Both servers and 706 clients SHALL understand and support the following 707 three tokens: 709 * initial: authentication was not tried because there 710 was no Authorization header in the corresponding 711 request. 713 * stale-session: the provided sid; in the request was 714 either unknown to or expired in the server. 716 * auth-failed: authentication trial was failed by 717 some reasons, possibly with a bad authentication 718 credentials. 720 Implementations MAY support the following tokens or 721 any extensive-tokens defined outside this 722 specification. If clients has received any unknown 723 tokens, these SHOULD treat these as if it were "auth- 724 failed" or "initial". 726 * reauth-needed: server-side application requires a 727 new authentication trial, regardless of the current 728 status. 730 * invalid-parameters: authentication was not even 731 tried in the server-side because some parameters 732 are not acceptable. 734 * internal-error: authentication was not even tried 735 in the server-side because there is some troubles 736 on the server-side. 738 * user-unknown: a special case of auth-failed, 739 suggesting that the provided user-name is invalid. 740 The use of this parameter is NOT RECOMMENDED for 741 security implications, except for special-purpose 742 applications which makes this value sense. 744 * invalid-credential: ditto, suggesting that the 745 provided user-name was valid but authentication was 746 failed. The use of this parameter is 747 NOT RECOMMENDED as the same as the above. 749 * authz-failed: authentication was successful, but 750 access to the specified resource is not authorized 751 to the specific authenticated user. (It is 752 different from 403 responses which suggest that the 753 reason of inaccessibility is other that 754 authentication.) 756 The algorithm specified in this header will determine the types 757 (among those defined in Section 3) and the values for K_c1, K_s1, 758 VK_c and VK_s. 760 Among these messages, those with the reason parameter of value 761 "stale-session" will be called "401-STALE" messages hereafter, 762 because these have a special meaning in the protocol flow. Messages 763 with any other reason parameters will be called "401-INIT" messages. 765 4.2. req-KEX-C1 767 Every req-KEX-C1 message SHALL be a valid HTTP request message 768 containing an "Authorization" header with a credential containing a 769 "kc1" parameter. 771 The credential SHALL contain the parameters with the following names: 773 version: (mandatory, extensive-token) should be the token "-wg- 774 draft04". 776 algorithm, validation, auth-domain, realm: MUST be the same value as 777 it is when received from the server. 779 user: (mandatory, string) is the UTF-8 encoded name of the 780 user. The string SHOULD be prepared according to the 781 method presented in Section 9. 783 kc1: (mandatory, algorithm-determined) is the client-side 784 key exchange value K_c1, which is specified by the 785 algorithm that is used. 787 4.3. 401-KEX-S1 789 Every 401-KEX-S1 message SHALL be a valid HTTP 401-status 790 (Authentication Required) response message containing a 791 "WWW-Authenticate" header with a challenge containing a "ks1" 792 parameter. 794 The challenge SHALL contain the parameters with the following names: 796 version: (mandatory, extensive-token) should be the token "-wg- 797 draft04". 799 algorithm, validation, auth-domain, realm: MUST be the same value as 800 it is when received from the client. 802 sid: (mandatory, hex-fixed-number) MUST be a session 803 identifier, which is a random integer. The sid SHOULD 804 have uniqueness of at least 80 bits or the square of 805 the maximal estimated transactions concurrently 806 available in the session table, whichever is larger. 807 See Section 6 for more details. 809 ks1: (mandatory, algorithm-determined) is the server-side 810 key exchange value K_s1, which is specified by the 811 algorithm. 813 nc-max: (mandatory, integer) is the maximal value of nonce 814 counts that the server accepts. 816 nc-window: (mandatory, integer) the number of available nonce 817 slots that the server will accept. The value of the 818 nc-window parameter is RECOMMENDED to be 32 or more. 820 time: (mandatory, integer) represents the suggested time (in 821 seconds) that the client can reuse the session 822 represented by the sid. It is RECOMMENDED to be at 823 least 60. The value of this parameter is not directly 824 linked to the duration that the server keeps track of 825 the session represented by the sid. 827 path: (non-mandatory, string) specifies which path in the 828 URI space the same authentication is expected to be 829 applied. The value is a space-separated list of URIs, 830 in the same format as it was specified in domain 831 parameter [RFC2617] for the Digest authentications. 832 The all path elements contained in the parameter MUST 833 be inside the specified auth-domain; if not, clients 834 SHOULD ignore such elements. For better performance, 835 recognition of this parameter by clients are 836 significantly important. 838 4.4. req-VFY-C 840 Every req-VFY-C message SHALL be a valid HTTP request message 841 containing an "Authorization" header with a credential containing a 842 "vkc" parameter. 844 The parameters contained in the header are as follows: 846 version: (mandatory, extensive-token) should be the token "-wg- 847 draft04". 849 algorithm, validation, auth-domain, realm: MUST be the same value as 850 it is when received from the server for the session. 852 sid: (mandatory, hex-fixed-number) MUST be one of the sid 853 values that was received from the server for the same 854 authentication realm. 856 nc: (mandatory, integer) is a nonce value that is unique 857 among the requests sharing the same sid. The values 858 of the nonces SHOULD satisfy the properties outlined 859 in Section 6. 861 vkc: (mandatory, algorithm-determined) is the client-side 862 authentication verification value VK_c, which is 863 specified by the algorithm. 865 4.5. 200-VFY-S 867 Every 200-VFY-S message SHALL be a valid HTTP message that is not of 868 the 401 (Authentication Required) status, containing an 869 "Authentication-Info" header with a "vks" parameter. 871 The parameters contained in the header are as follows: 873 version: (mandatory, extensive-token) should be the token "-wg- 874 draft04". 876 sid: (mandatory, hex-fixed-number) MUST be the value 877 received from the client. 879 vks: (mandatory, algorithm-determined) is the server-side 880 authentication verification value VK_s, which is 881 specified by the algorithm. 883 The header MUST be sent before the content body: it MUST NOT be sent 884 in the trailer of a chunked-encoded response. If a "100 Continue" 885 response is sent from the server, the Authentication-Info header 886 SHOULD be included in that response, instead of the final response. 888 5. Authentication Realms 890 In this protocol, an "authentication realm" is defined as a set of 891 resources (URIs) for which the same set of user names and passwords 892 is valid for. If the server requests authentication for an 893 authentication realm that the client is already authenticated for, 894 the client will automatically perform the authentication using the 895 already-known secrets. However, for the different authentication 896 realms, the clients MUST NOT automatically reuse the user names and 897 passwords for another realm. 899 Just like in Basic and Digest access authentication protocols, Mutual 900 authentication protocol supports multiple, separate protection spaces 901 to be set up inside each host. Furthermore, the protocol supports 902 that a single authentication realm spans over several hosts within 903 the same Internet domain. 905 Each authentication realm is defined and distinguished by the triple 906 of an "authentication algorithm", an "authentication domain", and a 907 "realm" parameter. However, server operators are NOT RECOMMENDED to 908 use the same pair of an authentication domain and a realm for 909 different authentication algorithms. 911 The realm parameter is a string as defined in Section 4. 913 Authentication domains are described in the remainder of this 914 section. 916 An authentication domain specifies the range of hosts that the 917 authentication realm spans over. In this protocol, it MUST be one of 918 the following strings. 920 o Single-server type: The string in format "://" or 921 "://:", where , , and are 922 the corresponding URI parts of the request URI. If the default 923 port (i.e. 80 for http and 443 for https) is used for the 924 underlying HTTP communications, the port part MUST be omitted, 925 regardless of whether it was present in the request-URI. In other 926 cases, the port part MUST be present, and it MUST NOT contain 927 leading zeros. Use this when authentication is only valid for 928 specific protocol (such as https). This format is equivalent to 929 the ASCII serialization of a Web Origin, presented in Section 6.2 930 of [RFC6454]. 932 o Single-host type: The "host" part of the requested URI. This is 933 the default value. Authentication realms within this kind of 934 authentication domain will span over several protocols (i.e. http 935 and https) and ports, but not over different hosts. 937 o Wildcard-domain type: The string in format "*.", 938 where is either the host part of the requested 939 URI or any domain in which the requested host is included (this 940 means that the specification "*.example.com" is valid for all of 941 hosts "www.example.com", "web.example.com", 942 "www.sales.example.com" and "example.com"). The domain-postfix 943 sent from the servers MUST be equal to or included in a valid 944 Internet domain assigned to a specific organization: if clients 945 know, by some means such as a blacklist for HTTP cookies 946 [RFC6265], that the specified domain is not to be assigned to any 947 specific organization (e.g. "*.com" or "*.jp"), the clients are 948 RECOMMENDED to reject the authentication request. 950 In the above specifications, every "scheme", "host", and "domain" 951 MUST be in lower-case, and any internationalized domain names beyond 952 the ASCII character set SHALL be represented in the way they are sent 953 in the underlying HTTP protocol, represented in lower-case 954 characters; i.e. these SHALL be in the form of the LDH labels in IDNA 955 [RFC5890]. All "port"s MUST be in the shortest, unsigned, decimal 956 number notation. Not obeying these requirements will cause failure 957 of valid authentication attempts. 959 5.1. Resolving Ambiguities 961 In the above definitions of authentication domains, several domains 962 will overlap each other. If a client has already been authenticated 963 to several realms applicable to the same server, the client may have 964 a multiple list of the "path" parameters received with the 965 "401-KEX-S1" message (see Section 4). If these path lists have any 966 overlap, a single URI may belong to multiple possible candidate of 967 realms to be authenticated to. In such cases, clients faces an 968 ambiguity on deciding which credentials to be sent for a new request 969 (in steps 3 and 4 of the decision procedure presented in Section 10). 971 In such cases, clients MAY send requests which belongs to any of 972 these candidate realms freely, or it MAY simply send an 973 unauthenticated request and see for which realm the server request an 974 authentication. Server operators are RECOMMENDED to provide 975 properly-configured "path" parameters (more precisely, disjoint path 976 sets for each realms) for clients so that such ambiguities will not 977 occur. 979 The following procedure are one of the possible tactics for resolving 980 ambiguity in such cases. 982 o If the client has previously sent a request to the same URI, and 983 if it remembers the authentication realm requested by 401-INIT 984 messages at that time, use that realm. 986 o In other cases, use one of authentication realms representing the 987 most-specific authentication domains. From the list of possible 988 domain specifications shown above, each one earlier has priority 989 over ones described after that. 991 If there are several choices with different domain-postfix 992 specifications, the one that has the longest domain-postfix has 993 priority over ones with a shorter domain-postfix. 995 o If there are realms with the same authentication domain, there is 996 no defined priority: the client MAY choose any one of the possible 997 choices. 999 6. Session Management 1001 In the Mutual authentication protocol, a session represented by an 1002 sid is set up using first four messages (first request, 401-INIT, 1003 req-KEX-C1 and 401-KEX-S1), and a "session secret" (z) associated 1004 with the session is established. After sharing a session secret, 1005 this session, along with the secret, can be used for one or more 1006 requests for resources protected by the same realm in the same 1007 server. Note that session management is only an inside detail of the 1008 protocol and usually not visible to normal users. If a session 1009 expires, the client and server SHOULD automatically re-establish 1010 another session without informing the users. 1012 Sessions and session identifiers are local to each server (defined by 1013 scheme, host and port), even if an authentication domain covers 1014 multiple servers; the clients MUST establish separate sessions for 1015 each port of a host to be accessed. Furthermore, sessions and 1016 identifiers are also local to each authentication realm, even if 1017 these are provided from the same server. The same session 1018 identifiers provided either from different servers or for different 1019 realms MUST be treated as independent ones. 1021 The server SHOULD accept at least one req-VFY-C request for each 1022 session, given that the request reaches the server in a time window 1023 specified by the timeout parameter in the 401-KEX-S1 message, and 1024 that there are no emergent reasons (such as flooding attacks) to 1025 forget the sessions. After that, the server MAY discard any session 1026 at any time and MAY send 401-STALE messages for any req-VFY-C 1027 requests. 1029 The client MAY send two or more requests using a single session 1030 specified by the sid. However, for all such requests, each value of 1031 the nonce (in the nc parameter) MUST satisfy the following 1032 conditions: 1034 o It is a natural number. 1036 o The same nonce was not sent within the same session. 1038 o It is not larger than the nc-max value that was sent from the 1039 server in the session represented by the sid. 1041 o It is larger than (largest-nc - nc-window), where largest-nc is 1042 the maximal value of nc which was previously sent in the session, 1043 and nc-window is the value of the nc-window parameter which was 1044 received from the server in the session. 1046 The last condition allows servers to reject any nonce values that are 1047 "significantly" smaller than the "current" value (defined by the 1048 value of nc-window) of the nonce used in the session involved. In 1049 other words, servers MAY treat such nonces as "already received". 1050 This restriction enables servers to implement duplicated nonce 1051 detection in a constant amount of memory (for each session). 1053 Servers MUST check for duplication of the received nonces, and if any 1054 duplication is detected, the server MUST discard the session and 1055 respond with a 401-STALE message, as outlined in Section 11. The 1056 server MAY also reject other invalid nonce values (such as ones above 1057 the nc-max limit) by sending a 401-STALE message. 1059 For example, assume the nc-window value of the current session is 32, 1060 nc-max is 100, and that the client has already used the following 1061 nonce values: {1-20, 22, 24, 30-38, 45-60, 63-72}. Then the nonce 1062 values that can be used for next request is one of the following set: 1063 {41-44, 61-62, 73-100}. The values {0, 21, 23, 25-29, 39-40} MAY be 1064 rejected by the server because they are not above the current "window 1065 limit" (40 = 72 - 32). 1067 Typically, clients can ensure the above property by using a 1068 monotonically-increasing integer counter that counts from zero upto 1069 the value of nc-max. 1071 The values of the nonces and any nonce-related values MUST always be 1072 treated as natural numbers within an infinite range. Implementations 1073 which uses fixed-width integer representations, fixed-precision 1074 floating numbers or similar representations SHOULD NOT reject any 1075 larger values which overflow such representative limits, and MUST NOT 1076 silently truncate it using any modulus-like rounding operation (e.g. 1077 by mod 2^32). Instead, the whole protocol is carefully designed so 1078 that recipients MAY replace any such overflowed values (e.g. 2^80) 1079 with some reasonably-large maximal representative integer (e.g. 2^31 1080 - 1 or others). 1082 7. Host Validation Methods 1084 The "validation method" specifies a method to "relate" (or "bind") 1085 the mutual authentication processed by this protocol with other 1086 authentications already performed in the underlying layers and to 1087 prevent man-in-the-middle attacks. It decides the value vh that is 1088 an input to the authentication protocols. 1090 When HTTPS or other possible secure transport is used, this 1091 corresponds to the idea of "channel binding" described in [RFC5929]. 1092 Even when HTTP is used, similar, but somewhat limited, "binding" is 1093 performed to prevent a malicious server from trying to authenticate 1094 themselves to another server as a valid user by forwarding the 1095 received credentials. 1097 The valid tokens for the validation parameter and corresponding 1098 values of vh are as follows: 1100 host: host-name validation: The value vh will be the ASCII 1101 string in the following format: 1102 "://:", where , , 1103 and are the URI components corresponding to the 1104 currently accessing resource. The scheme and host are 1105 in lower-case, and the port is in a shortest decimal 1106 representation. Even if the request-URI does not have 1107 a port part, v will include the default port number. 1109 tls-server-end-point: TLS endpoint (certificate) validation: The 1110 value vh will be the octet string of the hash value of 1111 the server's public key certificate used in the 1112 underlying TLS [RFC5246] (or SSL) connection, 1113 processed as specified in Section 4.1 of [RFC5929]. 1115 [[Pending editorial issue: a small security issue is 1116 pending around here, awaiting analysis and WG 1117 discussions for final adoption.]] 1119 tls-unique: TLS shared-key validation: The value v will be the 1120 channel binding material derived from the Finished 1121 messages, as defined in Section 3.1 of [RFC5929]. 1123 If the HTTP protocol is used on a non-encrypted channel (TCP and 1124 SCTP, for example), the validation type MUST be "host". If HTTP/TLS 1125 [RFC2818] (HTTPS) protocol is used with the server certificates, the 1126 validation type MUST be "tls-server-end-point". If HTTP/TLS protocol 1127 is used with an anonymous Diffie-Hellman key exchange, the validation 1128 type MUST be "tls-unique" (see the note below). 1130 Implementations supporting a Mutual authentication over the HTTPS 1131 protocol SHOULD support the "tls-server-end-point" validation. 1132 Support for "tls-unique" validation is OPTIONAL for both the servers 1133 and clients. 1135 If the validation type "tls-server-end-point" is used, the server 1136 certificate provided on TLS connection MUST be verified at least to 1137 make sure that the server actually owns the corresponding secret key. 1138 (Note: this verification is automatic in some RSA-based key exchanges 1139 but NOT automatic in Diffie-Hellman-based key exchanges with separate 1140 exchange for server verifications.) 1142 Clients MUST validate this parameter upon reception of the 401-INIT 1143 messages. 1145 Note: The protocol defines two variants for validation on the TLS 1146 connections. The "tls-unique" method is more secure. However, there 1147 are some situations where tls-server-end-point is more preferable. 1149 o When TLS accelerating proxies are used, it is difficult for the 1150 authenticating server to acquire the TLS key information that is 1151 used between the client and the proxy. This is not the case for 1152 client-side "tunneling" proxies using a CONNECT method extension 1153 of HTTP. 1155 o When a black-box implementation of the TLS protocol is used on 1156 either peer. 1158 7.1. Applicability notes 1160 When the client is a Web browser with any scripting capabilities, the 1161 underlying TLS channel used with HTTP/TLS MUST provide server 1162 identity verification. This means (1) the anonymous Diffie-Hellman 1163 key exchange cipher-suite MUST NOT be used, and (2) the verification 1164 of the server certificate provided from the server MUST be performed. 1166 For other systems, when the underlying TLS channel used with HTTP/TLS 1167 does not perform server identity verification, the client SHOULD 1168 ensure that all the responses are validated using the Mutual 1169 authentication protocol, regardless of the existence of the 401-INIT 1170 responses. 1172 7.2. Interoperability notes on tls-unique 1174 As described in the interoperability note in the above channel 1175 binding specification, the tls-unique verification value will be 1176 changed by possible TLS renegotiation, causing an interoperability 1177 problem. TLS re-negotiations are used in several HTTPS server 1178 implementations for enforcing some security properties (such as 1179 cryptographic strength) for some specific responses. 1181 If an implementation supports "tls-unique" verification method, the 1182 following caution SHOULD be taken: 1184 o Both peers must be aware that the values vh used for vkc (in 1185 req-VFY-C) and for vks (in 200-VFY-S) may be different. These 1186 values MUST be retrieved from underlying TLS libraries each time 1187 it is used. 1189 o After calculating value vh and vkc to send a req-VFY-C request, 1190 Clients SHOULD NOT initiate TLS renegotiation until the end of the 1191 corresponding response header is received. Exceptionally, Clients 1192 can and SHOULD perform TLS re-negotiation as a response to 1193 server's request for TLS renegotiation, occurring before the top 1194 of response header. 1196 8. Authentication Extensions 1198 Interactive clients (e.g. Web browsers) supporting this protocol are 1199 RECOMMENDED to support non-mandatory authentication and the 1200 Authentication-Control header defined in 1201 [I-D.ietf-httpauth-extension], except the "auth-style" parameter. 1202 This specification also proposes (however, not mandates) default 1203 "auth-style" to be "non-modal". Web applications SHOULD however 1204 consider the security impacts of the behaviors of clients that do not 1205 support these headers. 1207 Authentication-initializing messages with the 1208 Optional-WWW-Authenticate header are used only where 401-INIT 1209 response is valid. It will not replace other 401-type messages such 1210 as 401-STALE and 401-KEX-S1. 1212 9. String Preparation 1214 It is important for interoperability that user-names and passwords 1215 used in this protocol is binary-comparable regardless of the user's 1216 input methods and/or environments. To ensure this, the following 1217 preparation SHOULD be performed: 1219 o User-names received from users SHOULD be prepared using the 1220 "UsernameCasePreserved" profile defined in Section 3.3 of 1221 [I-D.ietf-precis-saslprepbis]. 1223 o Passwords received from users SHOULD be prepared using the 1224 "OpaqueString" profile defined in Section 4.2 of 1225 [I-D.ietf-precis-saslprepbis]. 1227 In both cases, it is the sender's duty to correctly preparing the 1228 character strings. If any non-normalized character string is 1229 received from the other peer of the communication, recipients MAY 1230 either use it as a bare UTF-8 string without any preparation, perform 1231 any appropriate preparations (which may cause authentication 1232 failure), or reject any ill-prepared inputs from the sender and 1233 respond as a communication error. 1235 Server applications SHOULD also prepare user-names and passwords 1236 accordingly upon registration of user credentials. 1238 In addition, binary-based "interfaces" of implementations MAY require 1239 and assume that the string is already prepared accordingly; in 1240 detail, when a string is already stored as an binary Unicode string 1241 form, implementations MAY omit preparation and Unicode normalization 1242 (performs UTF-8 encoding only) before using it. When a string is 1243 already stored as an octet blob, implementations MAY send it as it 1244 is. 1246 10. Decision Procedure for Clients 1248 10.1. General Principles and Requirements 1250 To securely implement the protocol, the user client must be careful 1251 about accepting the authenticated responses from the server. This 1252 also holds true for the reception of "normal responses" (responses 1253 which do not contain Mutual-related headers) from HTTP servers. 1255 As usual in the HTTP authentication, a single user-level request may 1256 result in exchange of two-or-more HTTP requests and responses in 1257 sequence. The following care MUST be taken by the all clients 1258 implementing this protocol: 1260 o Any kinds of "normal responses" MUST only be accepted for the very 1261 first request in the sequence. Any "normal responses" returned 1262 for the second or later request in the sequence SHALL be 1263 considered invalid. 1265 o In the same principle, any responses which refer to, or request 1266 changing to, the authentication realm different from the client's 1267 request MUST only be accepted for the very first request in the 1268 sequence. Any kind of responses referring to the different realms 1269 which are returned for the second or later request in the sequence 1270 SHALL be considered invalid. 1272 o A req-KEX-C1 message MAY be sent either as a initial request or as 1273 a response to 401-INIT, and 401-STALE. However, it SHOULD NOT be 1274 sent more than once in the sequence for a single authentication 1275 realm, to avoid infinite loops of messages. A 401-KEX-S1 response 1276 MUST be accepted only when the corresponding request is 1277 req-KEX-C1. 1279 o A req-VFY-C message MAY be sent if there is a valid session key 1280 shared between the client and the server, established by 1281 req-KEX-C1 and 401-KEX-S1. If any response with 401 status is 1282 returned for such a message, the corresponding session key SHOULD 1283 be discarded as unusable. 1284 Especially, upon the reception of response 401-STALE, the client 1285 SHOULD try establishing a new session by sending req-KEX-C1, but 1286 only once within the request/response sequence. 1288 o A 200-VFY-S message MUST be accepted only as a response to 1289 req-VFY-C and nothing else. The VK_s field of such response 1290 message MUST always be checked against the correct value, and if 1291 it is incorrect, the whole response SHOULD be considered invalid. 1292 Any content, both the content body and the headers, of such an 1293 invalid response SHOULD be ignored and discarded. 1295 The final status of the client request following the message exchange 1296 sequence shall be determined as follows: 1298 o AUTH-SUCCEED: A 200-VFY-S message with the correct VK_s value is 1299 returned to the req-VFY-C request in the sequence. 1301 o AUTH-REQUIRED: Two cases exists. 1303 * A 401-INIT message is returned from the server, and the client 1304 does not know how to authenticate to the given authentication 1305 realm. 1307 * A 401-INIT response is returned for req-VFY-C (or req-KEX-C1), 1308 which means the user-supplied authentication credentials are 1309 not accepted. 1311 o UNAUTHENTICATED: a normal response is returned for an initial 1312 request of any kind in the sequence. 1314 Any kind of response (including a normal response) other than those 1315 explicitly allowed in the above rules SHOULD be interpreted as a 1316 fatal communication error. In such cases, the clients MUST NOT 1317 process any data (the response body and other content-related 1318 headers) sent from the server. However, to handle exceptional error 1319 cases, clients MAY accept a message without an Authentication-Info 1320 header, if it is a Server-Error (5xx) status. In such cases, they 1321 SHOULD be careful about processing the body of the content (ignoring 1322 it is still RECOMMENDED, as it may possibly be forged by intermediate 1323 attackers,) and the client will be in the "UNAUTHENTICATED" status 1324 then. 1326 If a request is a sub-request for a resource included in another 1327 resources (e.g., embedded images, style sheets, frames etc.), clients 1328 MAY treat an AUTH-REQUESTED status as the same as UNAUTHENTICATED 1329 status. In other words, the client MAY ignore server's request to 1330 start authentication with new credentials via sub-requests. 1332 10.2. State machine for the client-side 1334 The following state machine describes the possible request-response 1335 sequences derived from the above general rules. If implementors are 1336 not quite sure on the security consequences of the above rules, it is 1337 strongly RECOMMENDED to follow the decision procedure below. In 1338 particular, clients SHOULD NOT accept "normal responses" unless 1339 explicitly allowed in the rules. The labels on the steps are for 1340 informational purposes only. Action entries within each step are 1341 checked in top-to-bottom order, and the first clause satisfied SHOULD 1342 be taken. 1344 Step 1 (step_new_request): 1345 If the client software needs to access a new Web resource, check 1346 whether the resource is expected to be inside some authentication 1347 realm for which the user has already been authenticated by the 1348 Mutual authentication scheme. If yes, go to Step 2. Otherwise, 1349 go to Step 5. 1351 Step 2: 1352 Check whether there is an available sid for the authentication 1353 realm you expect. If there is one, go to Step 3. Otherwise, go 1354 to Step 4. 1356 Step 3 (step_send_vfy_1): 1357 Send a req-VFY-C request. 1359 * If you receive a 401-INIT message with a different 1360 authentication realm than expected, go to Step 6. 1362 * If you receive a 401-STALE message, go to Step 9. 1364 * If you receive a 401-INIT message, go to Step 13. 1366 * If you receive a 200-VFY-S message, go to Step 14. 1368 * If you receive a normal response, go to Step 11. 1370 Step 4 (step_send_kex1_1): 1371 Send a req-KEX-C1 request. 1373 * If you receive a 401-INIT message with a different 1374 authentication realm than expected, go to Step 6. 1376 * If you receive a 401-KEX-S1 message, go to Step 10. 1378 * If you receive a 401-INIT message with the same authentication 1379 realm, go to Step 13 (see Note 1). 1381 * If you receive a normal response, go to Step 11. 1383 Step 5 (step_send_normal_1): 1384 Send a request without any Mutual authentication headers. 1386 * If you receive a 401-INIT message, go to Step 6. 1388 * If you receive a normal response, go to Step 11. 1390 Step 6 (step_rcvd_init): 1391 Check whether you know the user's password for the requested 1392 authentication realm. If yes, go to Step 7. Otherwise, go to 1393 Step 12. 1395 Step 7: 1396 Check whether there is an available sid for the authentication 1397 realm you expect. If there is one, go to Step 8. Otherwise, go 1398 to Step 9. 1400 Step 8 (step_send_vfy): 1401 Send a req-VFY-C request. 1403 * If you receive a 401-STALE message, go to Step 9. 1405 * If you receive a 401-INIT message, go to Step 13. 1407 * If you receive a 200-VFY-S message, go to Step 14. 1409 Step 9 (step_send_kex1): 1410 Send a req-KEX-C1 request. 1412 * If you receive a 401-KEX-S1 message, go to Step 10. 1414 * If you receive a 401-INIT message, go to Step 13 (See Note 1). 1416 Step 10 (step_rcvd_kex1): 1417 Send a req-VFY-C request. 1419 * If you receive a 401-INIT message, go to Step 13. 1421 * If you receive a 200-VFY-S message, go to Step 14. 1423 Step 11 (step_rcvd_normal): 1424 The requested resource is out of the authenticated area. The 1425 client will be in the "UNAUTHENTICATED" status. If the response 1426 contains a request for authentications other than Mutual, it MAY 1427 be handled normally. 1429 Step 12 (step_rcvd_init_unknown): 1430 The requested resource requires a Mutual authentication, and the 1431 user is not yet authenticated. The client will be in the "AUTH- 1432 REQUESTED" status, and is RECOMMENDED to process the content sent 1433 from the server, and to ask user for a user name and a password. 1434 When those are supplied from the user, proceed to Step 9. 1436 Step 13 (step_rcvd_init_failed): 1437 For some reason the authentication failed: possibly the password 1438 or the username is invalid for the authenticated resource. 1439 Forget the password for the authentication realm and go to Step 1440 12. 1442 Step 14 (step_rcvd_vfy): 1443 The received message is the 200-VFY-S message, which SHALL always 1444 contain a vks field. Check the validity of the received VK_s 1445 value. If it is equal to the expected value, it means that the 1446 mutual authentication has succeeded. The client will be in the 1447 "AUTH-SUCCEEDED" status. 1449 If the value is unexpected, it is a fatal communication error. 1451 If a user explicitly requests to log out (via user interfaces), 1452 the client MUST forget the user's password, go to step 5 and 1453 reload the current resource without an authentication header. 1455 Note 1: These transitions MAY be accepted by clients, but 1456 NOT RECOMMENDED for servers to initiate. 1458 Figure 5 shows a diagram of the client-side state. 1460 =========== -(11)------------ 1461 NEW REQUEST ( UNAUTHENTICATED ) 1462 =========== ----------------- 1463 | ^ normal 1464 v | response 1465 +(1)-------------------+ NO +(5)----------+ 1466 | The requested URI |--------------------------->| send normal | 1467 | known to be auth'ed? | | request | 1468 +----------------------+ +-------------+ 1469 YES | 401-INIT 401-INIT| 1470 | with a different realm | 1471 | -----------------------------------. | 1472 | / v v 1473 | | -(12)------------ NO +(6)--------+ 1474 | | ( AUTH-REQUESTED )<------| user/pass | 1475 | | ----------------- | known? | 1476 | | +-----------+ 1477 | | |YES 1478 v | v 1479 +(2)--------+ | +(7)--------+ 1480 | session | | | session | NO 1481 NO /| available?| | | available?|\ 1482 / +-----------+ | +-----------+ | 1483 / |YES | |YES | 1484 | | /| | | 1485 | v / | 401- 401- v | 1486 | +(3)--------+ | INIT --(13)---------- INIT +(8)--------+ | 1487 | | send |--+----->/ AUTH-REQUESTED \<-------| send | | 1488 | /| req-VFY-C | | \forget password / | req-VFY-C | | 1489 \/ +-----------+ / ---------------- /+-----------+ | 1490 /\ \ \/ ^ 401-INIT | |401- | 1491 | ------ \/\ 401-STALE | | | STALE / 1492 | \ /\ -----------------+--------------+---. | / 1493 | | / \ | | | | / 1494 | v / | 401- | 401- | v v v 1495 | +(4)--------+ | KEX-S1 +(10)-------+ KEX-S1 | +(9)--------+ 1496 | | send |-|--------->| send |<-------+-| send | 1497 | --| req-KEX-C1| | | req-VFY-C | | | req-KEX-C1| 1498 |/ +-----------+ | +-----------+ | +-----------+ 1499 | |200-VFY-S | 200-VFY-S| ^ 1500 |normal | |200-VFY-S / | 1501 |response | v / ================== 1502 v \ -(14)--------- / USER/PASS INPUTTED 1503 -(11)------------ ------->( AUTH-SUCCEED )<-- ================== 1504 ( UNAUTHENTICATED ) -------------- 1505 ----------------- 1507 Figure 5: State diagram for clients 1509 11. Decision Procedure for Servers 1511 Each server SHOULD have a table of session states. This table need 1512 not be persistent over a long term; it MAY be cleared upon server 1513 restart, reboot, or others. Each entry in the table SHOULD contain 1514 at least the following information: 1516 o The session identifier, the value of the sid parameter. 1518 o The algorithm used. 1520 o The authentication realm. 1522 o The state of the protocol: one of "key exchanging", 1523 "authenticated", "rejected", or "inactive". 1525 o The user name received from the client 1527 o The boolean flag noting whether or not the session is fake. 1529 o When the state is "key exchanging", the values of K_c1 and S_s1. 1531 o When the state is "authenticated", the following information: 1533 * The value of the session secret z 1535 * The largest nc received from the client (largest-nc) 1537 * For each possible nc values between (largest-nc - nc- 1538 window + 1) and max_nc, a flag whether or not a request with 1539 the corresponding nc has been received. 1541 The table MAY contain other information. 1543 Servers SHOULD respond to the client requests according to the 1544 following procedure: (See Note 1 below for 401-INIT message with * 1545 marks) 1547 o When the server receives a normal request: 1549 * If the requested resource is not protected by the Mutual 1550 Authentication, send a normal response. 1552 * If the resource is protected by the Mutual Authentication, send 1553 a 401-INIT response. 1555 o When the server receives a req-KEX-C1 request: 1557 * If the requested resource is not protected by the Mutual 1558 Authentication, send a normal response. 1560 * If the authentication realm specified in the req-KEX-C1 request 1561 is not the expected one, send a 401-INIT response. 1563 * If the server cannot validate the parameter kc1, send a 1564 401-INIT (*) response. 1566 * If the received user name is either invalid, unknown or 1567 unacceptable, create a new session, mark it a "fake" session, 1568 compute a random value as K_s1, and send a fake 401-KEX-S1 1569 response. (Note 2) 1571 * Otherwise, create a new session, compute K_s1 and send a 1572 401-KEX-S1 response. 1574 The created session has the "key exchanging" state. 1576 o When the server receives a req-VFY-C request: 1578 * If the requested resource is not protected by the Mutual 1579 Authentication, send a normal response. 1581 * If the authentication realm specified in the req-VFY-C request 1582 is not the expected one, send a 401-INIT response. 1584 If none of above holds true, the server will lookup the session 1585 corresponding to the received sid and the authentication realm. 1587 * If the session corresponding to the received sid could not be 1588 found, or it is in the "inactive" state, send a 401-STALE 1589 response. 1591 * If the session is in the "rejected" state, send either a 1592 401-INIT (*) or a 401-STALE message. 1594 * If the session is in the "authenticated" state, and the request 1595 has an nc value that was previously received from the client, 1596 send a 401-STALE message. The session SHOULD be changed to the 1597 "inactive" status. 1599 * If the nc value in the request is larger than the nc-max 1600 parameter sent from the server, or if it is not larger then 1601 (largest-nc - nc-window) (when in "authenticated" status), the 1602 server MAY (but not REQUIRED to) send a 401-STALE message. The 1603 session SHOULD be changed to the "inactive" status if so. 1605 * If the session is a "fake" session, or if the received vkc is 1606 incorrect, then send a 401-INIT (*) response. If the session 1607 is in the "key exchanging" state, it SHOULD be changed to the 1608 "rejected" state; otherwise, it MAY either be changed to the 1609 "rejected" status or kept in the previous state. 1611 * Otherwise, send a 200-VFY-S response. If the session was in 1612 the "key exchanging" state, the session SHOULD be changed to an 1613 "authenticated" state. The maximum nc and nc flags of the 1614 state SHOULD be updated properly. 1616 At any time, the server MAY change any state entries with both the 1617 "rejected" and "authenticated" statuses to the "inactive" status, and 1618 MAY discard any "inactive" states from the table. The entries with 1619 the "key exchanging" status SHOULD be kept unless there is an 1620 emergency situation such as a server reboot or a table capacity 1621 overflow. 1623 Note 1: In relation with, and following the specification of the 1624 optional authentication defined in [I-D.ietf-httpauth-extension], the 1625 401-INIT messages marked with the asterisks can not be replaced with 1626 a successful responses with an Optional-WWW-Authenticate header. 1627 Every other 401-INIT can be a response with an 1628 Optional-WWW-Authenticate. 1630 Note 2: the server SHOULD NOT send a 401-INIT response in this case, 1631 because it will leak the information to the client that the specified 1632 user will not be accepted. Instead, postpone it to the response for 1633 the next req-VFY-C request. 1635 12. Authentication Algorithms 1637 Cryptographic authentication algorithms which are used with this 1638 protocol will be defined separately. The algorithm definition MUST 1639 at least provide a definitions for the following functions: 1641 o The server-side authentication credential J, derived from user- 1642 side authentication credential pi. 1644 o Key exchange values K_c1, K_s1 (exchanged on wire) and S_c1, S_s1 1645 (kept secret in each peer). 1647 o Shared secret z, to be computed in both server-side and client 1648 side. 1650 o A hash function H to be used with the protocol, along with its 1651 output size hSize. 1653 o The number of iteration for password hasing nIterPi, if it uses 1654 the default password hashing function defined below. 1656 Specifications for cryptographic algorithms used with this framework 1657 MUST specify whether these will use the default functions defined 1658 below for the functions pi, VK_c, and VK_s; or, these will define 1659 their own versions for these functions. 1661 All algorithm used with this protocol SHOULD provide secure mutual 1662 authentication between client and servers, and generate a 1663 cryptographically strong shared secret value z, equivalently strong 1664 to or stronger than the hash function H. If any passwords (or pass- 1665 phrases or any equivalents, i.e. weak secrets) are involved, these 1666 SHOULD NOT be guessable from any data transmitted in the protocol, 1667 even if an attacker (either an eavesdropper or an active server) 1668 knows the possible thoroughly-searchable candidate list of the 1669 passwords. Furthermore, if possible, the function for deriving 1670 server-side authentication credential J is RECOMMENDED to be one-way 1671 so that pi should not be easily computed from J(pi). 1673 12.1. Support Functions and Notations 1675 In this section we define several support functions and notations to 1676 be shared by several algorithm definitions: 1678 The integers in the specification are in decimal, or in hexadecimal 1679 when prefixed with "0x". 1681 The function octet(c) generates a single octet string whose code 1682 value is equal to c. The operator |, when applied to octet strings, 1683 denotes the concatenation of two operands. 1685 The function VI encodes natural numbers into octet strings in the 1686 following manner: numbers are represented in big-endian radix-128 1687 string, where each digit is represented by a octet within 0x80-0xff 1688 except the last digit represented by a octet within 0x00-0x7f. The 1689 first octet MUST NOT be 0x80. For example, VI(i) = octet(i) for i < 1690 128, and VI(i) = octet(0x80 + (i >> 7)) | octet(i & 127) for 128 <= i 1691 < 16384. This encoding is the same as the one used for the 1692 subcomponents of object identifiers in the ASN.1 encoding 1693 [ITU.X690.1994], and available as a "w" conversion in the pack 1694 function of several scripting languages. 1696 The function VS encodes a variable-length octet string into a 1697 uniquely-decoded, self-delimited octet string, as in the following 1698 manner: 1700 VS(s) = VI(length(s)) | s 1702 where length(s) is a number of octets (not characters) in s. 1704 Some examples: 1706 VI(0) = "\000" (in C string notation) 1708 VI(100) = "d" 1710 VI(10000) = "\316\020" 1712 VI(1000000) = "\275\204@" 1714 VS("") = "\000" 1716 VS("Tea") = "\003Tea" 1718 VS("Caf" [in UTF-8]) = "\005Caf\303\251" 1720 VS([10000 "a"s]) = "\316\020aaaaa..." (10002 octets) 1722 (Note: Unlike the colon-separated notion used in the Basic/Digest 1723 HTTP authentication scheme, the string generated by a concatenation 1724 of the VS-encoded strings will be unique, regardless of the 1725 characters included in the strings to be encoded.) 1727 The function OCTETS converts an integer into the corresponding radix- 1728 256 big-endian octet string having its natural length: See 1729 Section 3.2.3 for the definition of "natural length". 1731 The function INT converts an octet string into a natural number, 1732 where the input string is treated as a radix-256 big-endian notation. 1733 The identity INT(OCTETS(n)) = n always holds for any natural number 1734 n. 1736 12.2. Default Functions for Algorithms 1738 The functions defined in this section are common default functions 1739 among authentication algorithms. 1741 The client-side password-based (credential) pi used by this 1742 authentication is a natural number derived in the following manner: 1744 pi = INT(PBKDF2(HMAC_H, ph(password), VS(algorithm) | VS(auth-domain) 1745 | VS(realm) | VS(username), nIterPi, hSize / 8)), 1746 where 1748 o PBKDF2 is the password-based key derivation function defined in 1749 [RFC2898], 1751 o HMAC_H is the HMAC function, defined in [RFC2104], composed from 1752 the hash function H, and 1754 o hSize is the output size of hash H, counted in bits. 1756 The values of algorithm, realm, and auth-domain are taken from the 1757 values contained in the 401-INIT message. The function ph is 1758 determined by the value of the pwd-hash parameter given in a 401-INIT 1759 message. If the password comes from a user input, it SHOULD first be 1760 prepared according to the method presented in Section 9. Then, the 1761 password SHALL be encoded as a UTF-8 string before passed to ph. 1763 The values VK_c and VK_s are derived by the following equation. 1765 VK_c = INT(H(octet(4) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | 1766 VI(nc) | VS(vh))) 1768 VK_s = INT(H(octet(3) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | 1769 VI(nc) | VS(vh))) 1771 13. Application Channel Binding 1773 Applications and upper-layer communication protocols may need 1774 authentication binding to the HTTP-layer authenticated user. Such 1775 applications MAY use the following values as a standard shared 1776 secret. 1778 These values are parameterized with an optional octet string (t) 1779 which may be arbitrarily chosen by each applications or protocols. 1780 If there is no appropriate value to be specified, use a null string 1781 for t. 1783 For applications requiring binding to either an authenticated user or 1784 a shared-key session (to ensure that the requesting client is 1785 certainly authenticated), the following value b_1 MAY be used. 1787 b_1 = H(H(octet(6) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VI(0) 1788 | VS(vh)) | VS(t)). 1790 For applications requiring binding to a specific request (to ensure 1791 that the payload data is generated for the exact HTTP request), the 1792 following value b_2 MAY be used. 1794 b_2 = H(H(octet(7) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VI(nc) 1795 | VS(vh)) | VS(t)). 1797 Note: Channel bindings to lower-layer transports (TCP and TLS) are 1798 defined in Section 7. 1800 14. Application for Proxy Authentication 1802 The authentication scheme defined by the previous sections can be 1803 applied (with modifications) for proxy authentications. In such 1804 cases, the following alterations MUST be applied: 1806 o The 407 status is to be sent and recognized for places where the 1807 401 status is used, 1809 o Proxy-Authenticate: header is to be used for places where WWW- 1810 Authenticate: is used, 1812 o Proxy-Authorization: header is to be used for places where 1813 Authorization: is used, 1815 o Proxy-Authentication-Info: header is to be used for places where 1816 Authentication-Info: is used, 1818 o The auth-domain parameter is fixed to the host-name of the proxy, 1819 which means to cover all requests processed through the specific 1820 proxy, 1822 o The limitation for the paths contained in the path parameter of 1823 401-KEX-S1 messages is disregarded, 1825 o The omission of the path parameter of 401-KEX-S1 messages means 1826 that the authentication realm will potentially cover all requests 1827 processed by the proxy, 1829 o The scheme, host name and the port of the proxy is used for host 1830 validation tokens, and 1832 o Authentication extensions in [I-D.ietf-httpauth-extension] are not 1833 applicable. 1835 15. Methods to Extend This Protocol 1837 If a private extension to this protocol is implemented, it MUST use 1838 the extension-tokens defined in Section 3 to avoid conflicts with 1839 this protocol and other extensions. (standardized or being- 1840 standardizing extensions MAY use either bare-tokens or extension- 1841 tokens.) 1843 Specifications defining authentication algorithms MAY use other 1844 representations for the parameters "kc1", "ks1", "vkc", and "vks", 1845 replace those parameter names, and/or add parameters to the messages 1846 containing those parameters in supplemental specifications, provided 1847 that syntactic and semantic requirements in Section 3, [RFC7230] and 1848 [RFC7235] are satisfied. Any parameters starting with "kc", "ks", 1849 "vkc" or "vks" and followed by decimal natural numbers (e.g. kc2, 1850 ks0, vkc1, vks3 etc.) are reserved for this purpose. If those 1851 specifications use names other than those mentioned above, it is 1852 RECOMMENDED to use extension-tokens to avoid any parameter name 1853 conflict with the future extension of this protocol. 1855 Extension-tokens MAY be freely used for any non-standard, private, 1856 and/or experimental uses for those parameters provided that the 1857 domain part in the token is appropriately used. 1859 16. IANA Considerations 1861 When bare-tokens are used for the authentication-algorithm, pwd-hash, 1862 and validation parameters MUST be allocated by IANA. To acquire 1863 registered tokens, a specification for the use of such tokens MUST be 1864 available as an RFC, as outlined in [RFC5226]. 1866 Note: More formal declarations will be added in the future drafts to 1867 meet the RFC 5226 requirements. 1869 17. Security Considerations 1871 17.1. Security Properties 1873 o The protocol is secure against passive eavesdropping and replay 1874 attacks. However, the protocol relies on transport security 1875 including DNS integrity for data secrecy and integrity. HTTP/TLS 1876 SHOULD be used where transport security is not assured and/or data 1877 confidentiality is important. 1879 o When used with HTTP/TLS, if TLS server certificates are reliably 1880 verified, the protocol provides true protection against active 1881 man-in-the-middle attacks. 1883 o Even if the server certificate is not used or is unreliable, the 1884 protocol provides protection against active man-in-the-middle 1885 attacks for each HTTP request/response pair. However, in such 1886 cases, JavaScript or similar scripting facilities can be used to 1887 affect the Mutually-authenticated contents from other contents not 1888 protected by this authentication mechanism. This is the reason 1889 why this protocol requires that valid TLS server certificates MUST 1890 be presented (Section 7). 1892 17.2. Denial-of-service Attacks to Servers 1894 The protocol requires a server-side table of active sessions, which 1895 may become a critical point of the server resource consumptions. For 1896 proper operation, the protocol requires that at least one key 1897 verification request is processed for each session identifier. After 1898 that, servers MAY discard sessions internally at any time, without 1899 causing any operational problems to clients. Clients will silently 1900 reestablishes a new session then. 1902 However, if a malicious client sends too many requests of key 1903 exchanges (req-KEX-C1 messages) only, resource starvation might 1904 occur. In such critical situations, servers MAY discard any kind of 1905 existing sessions regardless of these statuses. One way to mitigate 1906 such attacks are that servers MAY have a number and a time limits for 1907 unverified pending key exchange requests (in the "key exchanging" 1908 status). 1910 This is a common weakness of authentication protocols with almost any 1911 kind of negotiations or states, including Digest authentication 1912 method and most Cookie-based authentication implementations. 1913 However, regarding the resource consumption, a situation of the 1914 mutual authentication method is a slightly better than the Digest, 1915 because HTTP requests without any kind of authentication requests 1916 will not generate any kind of sessions. Session identifiers are only 1917 generated after a client starts a key negotiation. It means that 1918 simple clients such as web crawlers will not accidentally consume 1919 server-side resources for session managements. 1921 17.2.1. On-line Active Password Attacks 1923 Although the protocol provides very strong protection against off- 1924 line dictionary attacks from eavesdropped traffics, the protocol, by 1925 its nature, can not prevent an active password attacks which the 1926 attackers sends so many authentication trial requests for every 1927 possible passwords. 1929 Possible countermeasures for preventing such attacks may be rate- 1930 limiting of the password authentication trials, statistics-based 1931 intrusion detection measures or similar protection schemes. If the 1932 server operators assume that the passwords of users are not strong 1933 enough, it may be desirable to introduce such ad-hoc countermeasures. 1935 17.3. Communicating the status of mutual authentication with users 1937 This protocol is designed for two goals. The first goal is just 1938 providing a secure alternative for existing Basic and Digest 1939 authentication. The second goal is to provide users a way to detect 1940 forged rogue servers imitating user's registered account on server- 1941 side, commonly known as (a part or kind of) Phishing attacks. 1943 For this protocol to effectively work as some countermeasures to such 1944 attacks, it is very important that end users of clients will be 1945 notified of the result of mutual authentication performed by this 1946 protocol, especially the three states "AUTH-SUCCEED", 1947 "UNAUTHENTICATED" and "AUTH-REQUIRED" defined in Section 10. The 1948 design of secure users' interfaces of the HTTP interactive clients 1949 are out of the scope of this document, but if possible, having some 1950 kind of UI indication for the three states above will be desirable 1951 for user's benefits on their security. 1953 Of course, in such cases, the user interfaces for asking passwords 1954 for this authentication shall be clearly identifiable against 1955 imitation by other insecure password input fields (such as forms). 1956 If the passwords are known to malicious attackers outside of the 1957 protocol, the protocol can not work as an effective security 1958 measures. 1960 17.4. Implementation Considerations 1962 o To securely implement the protocol, the Authentication-Info 1963 headers in the 200-VFY-S messages MUST always be validated by the 1964 client. If the validation fails, the client MUST NOT process any 1965 content sent with the message, including other headers and the 1966 body part. Non-compliance to this requirement will allow phishing 1967 attacks. 1969 o For HTTP/TLS communications, when a web form is submitted from 1970 Mutually-authenticated pages with the "tls-server-end-point" 1971 validation method to a URI that is protected by the same realm (so 1972 indicated by the path parameter), if the server certificate has 1973 been changed since the pages were received, the peer is 1974 RECOMMENDED to be revalidated using a req-KEX-C1 message with an 1975 "Expect: 100-continue" header. The same applies when the page is 1976 received with the "tls-unique" validation method, and when the TLS 1977 session has expired. 1979 o For better protection against possible password database steal, 1980 Server-side storages of user passwords are better containing the 1981 values encrypted by one-way function J(pi), instead of the real 1982 passwords, those hashed by ph, or pi. 1984 17.5. Usage Considerations 1986 o The user-names inputted by a user may be sent automatically to any 1987 servers sharing the same auth-domain. This means that when host- 1988 type auth-domain is used for authentication on an HTTPS site, and 1989 when an HTTP server on the same host requests Mutual 1990 authentication within the same realm, the client will send the 1991 user-name in a clear text. If user-names have to be kept secret 1992 against eavesdropping, the server must use full-scheme-type auth- 1993 domain parameter and HTTPS. Contrarily, passwords are not exposed 1994 to eavesdroppers even on HTTP requests. 1996 o The "pwd-hash" parameter is only provided for backward 1997 compatibility of password databases. The use of "none" function 1998 is the most secure choice and is RECOMMENDED. If values other 1999 than "none" are used, you MUST ensure that the hash values of the 2000 passwords were not exposed to the public. Note that hashed 2001 password databases for plain-text authentications are usually not 2002 considered secret. 2004 o If the server provides several ways for storing server-side 2005 password secrets into the password database, it is desirable for 2006 better security to store the values encrypted by using the one-way 2007 function J(pi), instead of the real passwords, those hashed by ph, 2008 or pi. 2010 18. Notice on Intellectual Properties 2012 The National Institute of Advanced Industrial Science and Technology 2013 (AIST) and Yahoo! Japan, Inc. has jointly submitted a patent 2014 application on the protocol proposed in this documentation to the 2015 Patent Office of Japan. The patent is intended to be open to any 2016 implementors of this protocol and its variants under non-exclusive 2017 royalty-free manner. For the details of the patent application and 2018 its status, please contact the author of this document. 2020 The elliptic-curve based authentication algorithms might involve 2021 several existing third-party patents. The authors of the document 2022 take no position regarding the validity or scope of such patents, and 2023 other patents as well. 2025 19. References 2026 19.1. Normative References 2028 [I-D.ietf-httpauth-extension] 2029 Oiwa, Y., Watanabe, H., Takagi, H., Hayashi, T., and Y. 2030 Ioku, "HTTP Authentication Extensions for Interactive 2031 Clients", draft-ietf-httpauth-extension-03 (work in 2032 progress), February 2015. 2034 [I-D.ietf-httpbis-auth-info] 2035 Reschke, J., "The Hypertext Transfer Protocol (HTTP) 2036 Authentication-Info and Proxy- Authentication-Info 2037 Response Header Fields", draft-ietf-httpbis-auth-info-02 2038 (work in progress), February 2015. 2040 [I-D.ietf-precis-saslprepbis] 2041 Saint-Andre, P. and A. Melnikov, "Preparation, 2042 Enforcement, and Comparison of Internationalized Strings 2043 Representing Usernames and Passwords", 2044 draft-ietf-precis-saslprepbis-13 (work in progress), 2045 December 2014. 2047 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2048 Hashing for Message Authentication", RFC 2104, 2049 February 1997. 2051 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2052 Requirement Levels", BCP 14, RFC 2119, March 1997. 2054 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 2055 Specification Version 2.0", RFC 2898, September 2000. 2057 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2058 10646", STD 63, RFC 3629, November 2003. 2060 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2061 Encodings", RFC 4648, October 2006. 2063 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2064 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2066 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2067 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2069 [RFC5987] Reschke, J., "Character Set and Language Encoding for 2070 Hypertext Transfer Protocol (HTTP) Header Field 2071 Parameters", RFC 5987, August 2010. 2073 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2074 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 2075 June 2014. 2077 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2078 (HTTP/1.1): Authentication", RFC 7235, June 2014. 2080 19.2. Informative References 2082 [I-D.ietf-httpauth-mutual-algo] 2083 Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi, 2084 T., and Y. Ioku, "Mutual Authentication Protocol for HTTP: 2085 KAM3-based Cryptographic Algorithms", 2086 draft-ietf-httpauth-mutual-algo-02 (work in progress), 2087 February 2015. 2089 [I-D.ietf-precis-framework] 2090 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 2091 Preparation, Enforcement, and Comparison of 2092 Internationalized Strings in Application Protocols", 2093 draft-ietf-precis-framework-22 (work in progress), 2094 February 2015. 2096 [ISO.10646-1.1993] 2097 International Organization for Standardization, 2098 "Information Technology - Universal Multiple-octet coded 2099 Character Set (UCS) - Part 1: Architecture and Basic 2100 Multilingual Plane", ISO Standard 10646-1, May 1993. 2102 [ITU.X690.1994] 2103 International Telecommunications Union, "Information 2104 Technology - ASN.1 encoding rules: Specification of Basic 2105 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2106 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2107 X.690, 1994. 2109 [RFC1939] Myers, J. and M. Rose, "Post Office Protocol - Version 3", 2110 STD 53, RFC 1939, May 1996. 2112 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2113 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2114 Authentication: Basic and Digest Access Authentication", 2115 RFC 2617, June 1999. 2117 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2119 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2120 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2121 May 2008. 2123 [RFC5890] Klensin, J., "Internationalized Domain Names for 2124 Applications (IDNA): Definitions and Document Framework", 2125 RFC 5890, August 2010. 2127 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 2128 for TLS", RFC 5929, July 2010. 2130 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2131 April 2011. 2133 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 2134 December 2011. 2136 Appendix A. (Informative) Draft Remarks from Authors 2138 The following items are currently under consideration for future 2139 revisions by the authors. 2141 o Whether to keep TLS-unique validation or not. 2143 o Whether to introduce password strengthening hashes other than 2144 PBKDF2 into the function pi(). This requires standardization of 2145 such other hash algorithms in IETF. 2147 o Whether to modify current definition of nIterPi, which is per- 2148 algorithm defined. To increase this parameter requires defining a 2149 new algorithm, possibly with reconsideration for other security 2150 parameters as well. 2152 o Whether to keep ph() function for legacy migration or not. 2154 o Adding test vectors for ensuring implementation correctness. 2156 o Possibly adding a method for servers to detect availability of 2157 Mutual authentication on client-side. 2159 Appendix B. (Informative) Draft Change Log 2161 B.1. Changes in Httpauth WG Revision 04 2163 o Merged httpauthprep proposal into general PRECIS Username/Password 2164 profile. 2166 o Adopting RFC 5987 extended syntax for non-ASCII parameter values. 2168 o Refer draft-ietf-httpbis-auth-info for Authentication-Info header. 2169 This results in a different syntax for that header. 2171 B.2. Changes in Httpauth WG Revision 03 2173 o Incompatible change: Single-port type authentication realm label 2174 has been changed to harmonize with Web Origin. (That is, the 2175 default ports (80 and 443) are to be omitted.) 2177 B.3. Changes in Httpauth WG Revision 02 2179 o Major change: introduction of password-strengtheing function 2180 PBKDF2. 2182 o Changed Section 10 to adopt "list of requirements" style. Strict 2183 definition of state machine is now a derived, informational 2184 definition. 2186 B.4. Changes in Httpauth WG Revision 01 2188 o Changed "tls-key" verification to "tls-unique" verification, and 2189 "tls-cert" to "tls-server-end-point", adopting RFC 5929. 2191 o Adopted [I-D.ietf-precis-framework]. 2193 o Reverted reservation of "rekey-sid" and "rekey-method" parameters. 2195 o Degraded secure UI requirement to application note level, non- 2196 normative. 2198 o Adjusted levels of several requirements. 2200 o Added warning text for handling of exceptional 5XX responses. 2202 o Dropped several references for optional authentications, except 2203 one "Note". 2205 o Several textual fixes, improvements and revisions. 2207 B.5. Changes in Httpauth Revision 00 2209 o Changed the version token. 2211 o Renamed "verification tokens" to "Host verification tokens" and 2212 variables "v" to "vh" for clarification. (Back-ported from 2213 draft-oiwa-httpauth-multihop-template-00) 2215 B.6. Changes in HttpBis Revision 00 2217 None. 2219 B.7. Changes in Revision 12 2221 o Added a reason "authz-failed". 2223 B.8. Changes in Revision 11 2225 o Message syntax definition reverted to pre-07 style as httpbis-p1 2226 and p7 now defines a precise rule for parameter value parsing. 2228 o Replaced "stale" parameter with more infomative/extensive "reason" 2229 parameter in 401-INIT and 401-STALE. 2231 o Reserved "rekey-sid" and "rekey-method" parameters for future 2232 extensions. 2234 o Added descriptions for replacing/non-replacing existing 2235 technologies. 2237 B.9. Changes in Revision 10 2239 o The authentication extension parts (non-mandatory authentication 2240 and authentication controls) are separated to yet another draft. 2242 o The default auth-domain parameter is changed to the full scheme- 2243 host-port syntax, which is consistent with usual HTTP 2244 authentication framework behavior. 2246 o Provision for application channel binding is added. 2248 o Provision for proxy access authentication is added. 2250 o Bug fix: syntax specification of sid parameter was wrong: it was 2251 inconsistent with the type specified in the main text (the bug 2252 introduced in -07 draft). 2254 o Terminologies for headers are changed to be in harmony with 2255 httpbis drafts (e.g. field to parameter). 2257 o Syntax definitions are changed to use HTTP-extended ABNF syntax, 2258 and only the header values are shown for header syntax, in harmony 2259 with httpbis drafts. 2261 o Names of parameters and corresponding mathematical values are now 2262 renamed to more informative ones. The following list shows 2263 correspondence between the new and the old names. 2265 +------------+----------+-------------------------------------------+ 2266 | new name | old name | description | 2267 +------------+----------+-------------------------------------------+ 2268 | S_c1, S_s1 | s_a, s_b | client/server-side secret randoms | 2269 | K_c1, K_s1 | w_a, w_b | client/server-side exchanged key | 2270 | | | components | 2271 | kc1, ks1 | wa, wb | parameter names for those | 2272 | VK_c, VK_s | o_a, o_b | client/server-side key verifiers | 2273 | vkc, vks | oa, ob | parameter names for those | 2274 | z | z | session secrets | 2275 +------------+----------+-------------------------------------------+ 2277 B.10. Changes in Revision 09 2279 o The (default) cryptographic algorithms are separated to another 2280 draft. 2282 o Names of the messages are changed to more informative ones than 2283 before. The following is the correspondence table of those names: 2285 +-------------------+-----------------+-----------------------------+ 2286 | new name | old name | description | 2287 +-------------------+-----------------+-----------------------------+ 2288 | 401-INIT | 401-B0 | initial response | 2289 | 401-STALE | 401-B0-stale | session key expired | 2290 | req-KEX-C1 | req-A1 | client->server key exchange | 2291 | 401-KEX-S1 | 401-B1 | server->client key exchange | 2292 | req-VFY-C | req-A3 | client->server auth. | 2293 | | | verification | 2294 | 200-VFY-S | 200-B4 | server->client auth. | 2295 | | | verification | 2296 | 200-Optional-INIT | 200-Optional-B0 | initial with non-mandatory | 2297 | | | authentication | 2298 +-------------------+-----------------+-----------------------------+ 2300 B.11. Changes in Revision 08 2302 o The English text has been revised. 2304 B.12. Changes in Revision 07 2306 o Adapt to httpbis HTTP/1.1 drafts: 2308 * Changed definition of extensive-token. 2310 * LWSP continuation-line (%0D.0A.20) deprecated. 2312 o To simplify the whole spec, the type of nonce-counter related 2313 parameters are change from hex-integer to integer. 2315 o Algorithm tokens are renamed to include names of hash algorithms. 2317 o Clarified the session management, added details of server-side 2318 protocol decisions. 2320 o The whole draft was reorganized; introduction and overview has 2321 been rewritten. 2323 B.13. Changes in Revision 06 2325 o Integrated Optional Mutual Authentication to the main part. 2327 o Clarified the decision procedure for message recognitions. 2329 o Clarified that a new authentication request for any sub-requests 2330 in interactive clients may be silently discarded. 2332 o Typos and confusing phrases are fixed. 2334 o Several "future considerations" are added. 2336 B.14. Changes in Revision 05 2338 o A new parameter called "version" is added for supporting future 2339 incompatible changes with a single implementation. In the (first) 2340 final specification its value will be changed to 1. 2342 o A new header "Authentication-Control" is added for precise control 2343 of application-level authentication behavior. 2345 B.15. Changes in Revision 04 2347 o Changed text of patent licenses: the phrase "once the protocol is 2348 accepted as an Internet standard" is removed so that the sentence 2349 also covers the draft versions of this protocol. 2351 o The "tls-key" verification is now OPTIONAL. 2353 o Several description fixes and clarifications. 2355 B.16. Changes in Revision 03 2357 o Wildcard domain specifications (e.g. "*.example.com") are allowed 2358 for auth-domain parameters (Section 4.1). 2360 o Specification of the tls-cert verification is updated 2361 (incompatible change). 2363 o State transitions fixed. 2365 o Requirements for servers concerning w_a values are clarified. 2367 o RFC references are updated. 2369 B.17. Changes in Revision 02 2371 o Auth-realm is extended to allow full-scheme type. 2373 o A decision diagram for clients and decision procedures for servers 2374 are added. 2376 o 401-B1 and req-A3 messages are changed to contain authentication 2377 realm information. 2379 o Bugs on equations for o_A and o_B are fixed. 2381 o Detailed equations for the entire algorithm are included. 2383 o Elliptic-curve algorithms are updated. 2385 o Several clarifications and other minor updates. 2387 B.18. Changes in Revision 01 2389 o Several texts are rewritten for clarification. 2391 o Added several security consideration clauses. 2393 Authors' Addresses 2395 Yutaka Oiwa 2396 National Institute of Advanced Industrial Science and Technology 2397 Research Institute for Secure Systems 2398 3-11-46 Nakouji 2399 Tsukuba Central 2 2400 1-1-1 Umezono 2401 Tsukuba-shi, Ibaraki 2402 JP 2404 Email: mutual-auth-contact-ml@aist.go.jp 2406 Hajime Watanabe 2407 National Institute of Advanced Industrial Science and Technology 2408 Research Institute for Secure Systems 2409 Tsukuba Central 2 2410 1-1-1 Umezono 2411 Tsukuba-shi, Ibaraki 2412 JP 2414 Hiromitsu Takagi 2415 National Institute of Advanced Industrial Science and Technology 2416 Research Institute for Secure Systems 2417 Tsukuba Central 2 2418 1-1-1 Umezono 2419 Tsukuba-shi, Ibaraki 2420 JP 2422 Kaoru Maeda 2423 Lepidum Co. Ltd. 2424 Village Sasazuka 3, Suite #602 2425 1-30-3 Sasazuka 2426 Shibuya-ku, Tokyo 2427 JP 2429 Tatsuya Hayashi 2430 Lepidum Co. Ltd. 2431 Village Sasazuka 3, Suite #602 2432 1-30-3 Sasazuka 2433 Shibuya-ku, Tokyo 2434 JP 2435 Yuichi Ioku 2436 Individual