idnits 2.17.1 draft-oiwa-httpbis-mutualauth-00.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 (June 4, 2012) is 4338 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC3961' is defined on line 2107, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-19 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-19 ** Obsolete normative reference: RFC 4013 (Obsoleted by RFC 7613) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-26 == Outdated reference: A later version (-23) exists of draft-ietf-precis-framework-03 -- Obsolete informational reference (is this intentional?): RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force Y. Oiwa 3 Internet-Draft H. Watanabe 4 Intended status: Standards Track H. Takagi 5 Expires: December 6, 2012 RISEC, AIST 6 B. Kihara 7 T. Hayashi 8 Lepidum 9 Y. Ioku 10 Yahoo! Japan 11 June 4, 2012 13 Mutual Authentication Protocol for HTTP 14 draft-oiwa-httpbis-mutualauth-00 16 Abstract 18 This document specifies a mutual authentication method for the Hyper- 19 text Transport 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. This prevents common phishing attacks: a 25 phishing attacker controlling a fake website cannot convince a user 26 that he authenticated to the genuine website. Furthermore, even when 27 a user authenticates to an illegitimate server, the server cannot 28 gain any information about the user's password. The Mutual 29 authentication method is designed as an extension to the HTTP 30 protocol, and is intended to replace the existing authentication 31 methods used in HTTP (the Basic method, Digest method, and 32 authentication using HTML forms). 34 Status of this Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at http://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on December 6, 2012. 50 Copyright Notice 52 Copyright (c) 2012 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 1.1. Relations to other technologies . . . . . . . . . . . . . 6 69 1.1.1. Technologies updated or superceded by this proposal . 6 70 1.1.1.1. HTTP Basic and Digest authentication . . . . . . . 6 71 1.1.1.2. HTML Form authentication . . . . . . . . . . . . . 6 72 1.1.2. Technologies not updated by this proposal . . . . . . 7 73 1.1.2.1. Federated identity/authorization management . . . 7 74 1.1.2.2. HTTPS and HTTPS client-certificate 75 authentication . . . . . . . . . . . . . . . . . . 8 76 1.1.2.3. Protocols for local identity-management 77 frameworks . . . . . . . . . . . . . . . . . . . . 8 78 1.1.2.4. HTTP and HTTP authentication architecture . . . . 8 79 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 9 80 1.3. Document Structure and Related Documents . . . . . . . . . 9 81 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 10 82 2.1. Messages Overview . . . . . . . . . . . . . . . . . . . . 10 83 2.2. Typical Flows of the Protocol . . . . . . . . . . . . . . 11 84 2.3. Alternative Flows . . . . . . . . . . . . . . . . . . . . 14 85 3. Message Syntax . . . . . . . . . . . . . . . . . . . . . . . . 15 86 3.1. Values . . . . . . . . . . . . . . . . . . . . . . . . . . 16 87 3.1.1. Tokens . . . . . . . . . . . . . . . . . . . . . . . . 16 88 3.1.2. Strings . . . . . . . . . . . . . . . . . . . . . . . 17 89 3.1.3. Numbers . . . . . . . . . . . . . . . . . . . . . . . 17 90 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 91 4.1. 401-INIT and 401-STALE . . . . . . . . . . . . . . . . . . 19 92 4.2. req-KEX-C1 . . . . . . . . . . . . . . . . . . . . . . . . 22 93 4.3. 401-KEX-S1 . . . . . . . . . . . . . . . . . . . . . . . . 22 94 4.4. req-VFY-C . . . . . . . . . . . . . . . . . . . . . . . . 23 95 4.5. 200-VFY-S . . . . . . . . . . . . . . . . . . . . . . . . 24 96 5. Authentication Realms . . . . . . . . . . . . . . . . . . . . 25 97 5.1. Resolving Ambiguities . . . . . . . . . . . . . . . . . . 26 98 6. Session Management . . . . . . . . . . . . . . . . . . . . . . 27 99 7. Validation Methods . . . . . . . . . . . . . . . . . . . . . . 29 100 8. Authentication Extensions . . . . . . . . . . . . . . . . . . 30 101 9. Decision Procedure for Clients . . . . . . . . . . . . . . . . 31 102 10. Decision Procedure for Servers . . . . . . . . . . . . . . . . 36 103 11. Authentication Algorithms . . . . . . . . . . . . . . . . . . 38 104 11.1. Support Functions and Notations . . . . . . . . . . . . . 39 105 11.2. Default Functions for Algorithms . . . . . . . . . . . . . 40 106 12. Application Channel Binding . . . . . . . . . . . . . . . . . 41 107 13. Application for Proxy Authentication . . . . . . . . . . . . . 41 108 14. Methods to Extend This Protocol . . . . . . . . . . . . . . . 42 109 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 110 16. Security Considerations . . . . . . . . . . . . . . . . . . . 43 111 16.1. Security Properties . . . . . . . . . . . . . . . . . . . 43 112 16.2. Denial-of-service Attacks to Servers . . . . . . . . . . . 44 113 16.3. Implementation Considerations . . . . . . . . . . . . . . 44 114 16.4. Usage Considerations . . . . . . . . . . . . . . . . . . . 45 115 17. Notice on Intellectual Properties . . . . . . . . . . . . . . 45 116 18. References . . . . . . . . . . . . . . . . . . . . . . . . . . 46 117 18.1. Normative References . . . . . . . . . . . . . . . . . . . 46 118 18.2. Informative References . . . . . . . . . . . . . . . . . . 47 119 Appendix A. (Informative) Draft Remarks from Authors . . . . . . 48 120 Appendix B. (Informative) Draft Change Log . . . . . . . . . . . 49 121 B.1. Changes in HttpBis Revision 00 . . . . . . . . . . . . . . 49 122 B.2. Changes in Revision 12 . . . . . . . . . . . . . . . . . . 49 123 B.3. Changes in Revision 11 . . . . . . . . . . . . . . . . . . 49 124 B.4. Changes in Revision 10 . . . . . . . . . . . . . . . . . . 49 125 B.5. Changes in Revision 09 . . . . . . . . . . . . . . . . . . 50 126 B.6. Changes in Revision 08 . . . . . . . . . . . . . . . . . . 51 127 B.7. Changes in Revision 07 . . . . . . . . . . . . . . . . . . 51 128 B.8. Changes in Revision 06 . . . . . . . . . . . . . . . . . . 51 129 B.9. Changes in Revision 05 . . . . . . . . . . . . . . . . . . 51 130 B.10. Changes in Revision 04 . . . . . . . . . . . . . . . . . . 52 131 B.11. Changes in Revision 03 . . . . . . . . . . . . . . . . . . 52 132 B.12. Changes in Revision 02 . . . . . . . . . . . . . . . . . . 52 133 B.13. Changes in Revision 01 . . . . . . . . . . . . . . . . . . 52 134 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53 136 1. Introduction 138 This document specifies a mutual authentication method for Hyper-Text 139 Transport Protocol (HTTP). The method, called "Mutual Authentication 140 Protocol" in this document, provides a true mutual authentication 141 between an HTTP client and an HTTP server, using just a simple 142 password as a credential. 144 The currently available methods for authentication in HTTP and Web 145 systems have several deficiencies. The Basic authentication method 146 [RFC2617] sends a plaintext password to a server without any 147 protection; the Digest method uses a hash function that suffers from 148 simple dictionary-based off-line attacks, and people have begun to 149 think it is obsolete. 151 The authentication method proposed in this document solves these 152 problems, substitutes for these existing methods, and serves as a 153 long-term solution to Web authentication security. It has the 154 following main characteristics: 156 o It provides "true" mutual authentication: in addition to assuring 157 the server that the user knows the password, it also assures the 158 user that the server truly knows the user's encrypted password at 159 the same time. This makes it impossible for fake website owners 160 to persuade users that they have authenticated with the original 161 websites. 163 o It uses only passwords as the user's credential: unlike public- 164 key-based security algorithms, the method does not rely on secret 165 keys or other cryptographic data that have to be stored inside the 166 users' computers. The proposed method can be used as a drop-in 167 replacement to the current authentication methods like Basic or 168 Digest, while ensuring a much stronger level of security. 170 o It is secure: when the server fails to authenticate with a user, 171 the protocol will not reveal any bit of the user's password. 173 Users can discriminate between true and fake Web servers using their 174 own passwords by using the proposed method. Even when a user inputs 175 his/her password to a fake website owned by illegitimate phishers, 176 the user will certainly notice that the authentication has failed. 177 Phishers will not be successful in their authentication attempts, 178 even if they forward the received data from a user to a legitimate 179 server or vice versa. Users can input sensitive data to the web 180 forms after confirming that the mutual authentication has succeeded, 181 without fear of phishing attacks. 183 The document, along with [I-D.oiwa-http-auth-extension], also 184 proposes several extensions to the current HTTP authentication 185 framework, to replace current widely-used form-based Web 186 authentication. The extensions provided include: 188 o Multi-host single authentication within an Internet domain 189 (Section 5), 191 o non-mandatory, optional authentication on HTTP (Section 8), 193 o log out from both server and client side (Section 8), and 195 o finer control for redirection depending on authentication status 196 (Section 8). 198 1.1. Relations to other technologies 200 1.1.1. Technologies updated or superceded by this proposal 202 1.1.1.1. HTTP Basic and Digest authentication 204 The main purpose of this proposal is obviously providing an upgrade 205 for the two existing HTTP authentication methods, Basic and Digest 206 [RFC2617]. 208 HTTP Basic authentication, as its name suggests, provides very simple 209 authentication mechanism using plain-text password directly upon the 210 HTTP transport. HTTP Digest authentication focuses on mitigating the 211 fundamental weakness of Basic authentication by using MD5-based 212 hashing to the authentication, but that has almost failed to deploy 213 due to improper implementations, interoperability problems, and 214 missing feature implementations before MD5 has deprecated by its 215 cryptographic weakness. Digest also has a fundamental problem that 216 the server-side must posses a password-equivalent to perform 217 authentication, which increases risks of server-side data leakage. 219 1.1.1.2. HTML Form authentication 221 Another aim of this protocol is (at least) partially replacing the 222 HTML form authentication. Because of inflexibility of the HTTP Basic 223 authentication, recent Web applications tend to use application-level 224 implementations for user authentication using HTML Forms and Web 225 browser rendering engines. However, that method has many potential 226 security weaknesses as same as the HTTP Basic authentication as it 227 uses plaintext. Considering server-impersonations and existence of 228 human-forging rogue servers (i.e. phishing), script-based 229 implementations of hash-based authentication does not help, because 230 its behavior is completely controlled by the web-page content itself, 231 which is possibly provided by such a rogue server. This also closes 232 any possibilities for extending HTML forms to implement cryptography, 233 as its user-interface could not be prevented from being imitated 234 using plain-text forms. Using HTTP-level authentication is better in 235 this field, because it is under the control of the client software 236 (Web browsers), which can enforce security checks regardless of 237 server-provided contents. 239 Of course, we could not ignore the strong reasons of favoring Form 240 authentication over Basic authentication: its flexibility. HTTP 241 authentication framework lacks many features for recent Web 242 applications, mainly for interactions between HTTP-level 243 authentications and application-level management of "authentication 244 sessions". As long as current HTTP-layer (and lower-layer) 245 authentication are used, the new method would share the same problem. 246 To solve this problem, this protocol has a companion mechanism for 247 application-level control of authentication behaviors as a separate 248 draft [I-D.oiwa-http-auth-extension]. By using this additional 249 mechanism, Web applications can implement most of these required 250 features as easy as just calling an already-provided API for them. 252 1.1.2. Technologies not updated by this proposal 254 1.1.2.1. Federated identity/authorization management 256 There are several technologies (protocols, frameworks, or systems) 257 for managing authentications/authorizations involving multiple- 258 parties: some of those examples are OAuth [I-D.ietf-oauth-v2], OpenID 259 Connect [OIDF.Connect.Standard], SAML [OASIS.saml-core-2.0-os] etc. 260 These technologies can be further divided to two categories: 261 federated authentication and authorization delegation, although some 262 of these technologies cover both. 264 Federated authentication provides so-called "three-legged 265 authentication": provided the result of user authentication to a 266 single entity (identity provider) and the user's consent, the 267 mechanism can provide other entities assertion of the user's identity 268 without performing a separate identity management by every entity. 269 Authorization delegation gives a mechanism for transferring a part of 270 the user's privilege on an entity (resource owners) to another entity 271 without requiring users give away the full credential for the 272 authentication. 274 Essentially, both of those technologies are transforming a result of 275 conventional, one-by-one (two-legged) authentication into a multi- 276 party privilege management. The purpose of this protocol is to 277 secure the very part of the two-legged authentication, and so it can 278 be naturally combined with existing federated management frameworks 279 for increasing security of the entire system. 281 Additionally, this protocol can provide a secure peer-to-peer shared 282 key generated during authentication to the higher-layer applications 283 Section 12. These keys can be possibly used by such federating 284 mechanisms in future for simplifying/securing the framework. 286 1.1.2.2. HTTPS and HTTPS client-certificate authentication 288 This protocol will not replace the wide-spread and widely-accepted 289 technology of SSL/TLS and HTTPS [RFC2818]. This protocol will be 290 still relying on the HTTPS for the integrity and secrecy of the HTTP 291 payload. This protocol ensures users the integrity and secrecy of 292 the authentication credentials, and authenticity of the talking peer 293 server. 295 Client certificate (and other public-key-based) authentications have 296 a fair-amount of applications (mainly for high-assurance 297 applications), and there are possible needs for redesigning/updating 298 the whole framework. However, currently public-key-based user- 299 authentication and connection-based user identification is out-of- 300 scope of this proposal. 302 1.1.2.3. Protocols for local identity-management frameworks 304 There are several existing frameworks for managing user identity of 305 tightly-managed, closed group of users, such as Kerberos [RFC3961]/ 306 GSS-API [RFC2743] etc. Some of these have defined a bridging 307 protocol for HTTP authentication. This protocol does not currently 308 aim to replace such existing frameworks. 310 More precisely, requirements for those framework and usual Web user 311 authentication differ fundamentally. In such framework, user 312 authentication in performed first, and the result of the 313 authentication tends to be shared in all applications, sometimes even 314 shared regardless of the underlying protocols. In those systems, it 315 is almost never likely to use a multiple identity to be used inside a 316 single server and inside a single client machine at the same time. 317 In such applications, connection-based or even a machine-based 318 authentication can be used without a trouble. This is not a case for 319 the general Web authentication applications. 321 1.1.2.4. HTTP and HTTP authentication architecture 323 Although HTTP and generic HTTP authentication architecture lacks some 324 required features (see above), the whole structure of per-request, 325 per-resource authentication is well-suited for general Web 326 applications compared with connection-based or machine-based 327 authentication/authorization framework (those which tie user identity 328 to either connections or machines). The whole protocol in this 329 specification is designed on top of the framework of 330 [I-D.ietf-httpbis-p7-auth]. Small extensions to the framework in 331 this specification and [I-D.oiwa-http-auth-extension], which are 332 designed for filling the missing features, are carefully designed so 333 that it can be implemented easily only by the client-side without 334 changing the whole framework. 336 1.2. Terminology 338 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 339 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 340 "OPTIONAL" in this document are to be interpreted as described in 341 [RFC2119]. 343 The terms "encouraged" and "advised" are used for suggestions that do 344 not constitute "SHOULD"-level requirements. People MAY freely choose 345 not to include the suggested items regarding [RFC2119], but complying 346 with those suggestions would be a best practice; it will improve 347 security, interoperability, and/or operational performance. 349 This document distinguishes the terms "client" and "user" in the 350 following way: A "client" is an entity understanding and talking HTTP 351 and the specified authentication protocol, usually computer software; 352 a "user" is a (usually natural) person who wants to access data 353 resources using "a client". 355 The term "natural numbers" refers to the non-negative integers 356 (including zero) throughout this document. 358 This document treats target (codomain) of hash functions to be 359 natural numbers. The notation OCTETS(H(s)) gives a usual octet- 360 string output of hash function H applied to string s. 362 1.3. Document Structure and Related Documents 364 The entire document is organized as follows: 366 o Section 2 presents an overview of the protocol design. 368 o Sections 3 to 10 define a general framework of the Mutual 369 authentication protocol. This framework is independent of 370 specific cryptographic primitives. 372 o Section 11 describes properties needed for cryptographic 373 algorithms used with this protocol framework, and defines a few 374 functions which will be shared among such cryptographic 375 algorithms. 377 o The sections after that contain general normative and informative 378 information about the protocol. 380 o The appendices contain some information that may help developers 381 to implement the protocol. 383 In addition, there are two companion documents which are referred 384 from/related to this specification: 386 o [I-D.oiwa-http-mutualauth-algo]: defines a cryptographic 387 primitives which can be used with this protocol framework. [draft 388 note: it is separated so that it may be replaced with another 389 crypto in future. We need at least one example for testing/ 390 implementing this protocol, so here it is.] 392 o [I-D.oiwa-http-auth-extension]: defines a small but useful 393 extensions to the current HTTP authentication framework so that it 394 can support application-level semantics of existing Web systems. 396 2. Protocol Overview 398 The protocol, as a whole, is designed as a natural extension to the 399 HTTP protocol [I-D.ietf-httpbis-p1-messaging] using a framework 400 defined in [I-D.ietf-httpbis-p7-auth]. Internally, the server and 401 the client will first perform a cryptographic key exchange, using the 402 secret password as a "tweak" to the exchange. The key-exchange will 403 only succeed when the secrets used by the both peers are correctly 404 related (i.e. generated from the same password). Then, both peers 405 will verify the authentication results by confirming the sharing of 406 the exchanged key. This section describes a brief image of the 407 protocol and the exchanged messages. 409 2.1. Messages Overview 411 The authentication protocol uses seven kinds of messages to perform 412 mutual authentication. These messages have specific names within 413 this specification. 415 o Authentication request messages: used by the servers to request 416 clients to start mutual authentication. 418 * 401-INIT message: a general message to start the authentication 419 protocol. It is also used as a message indicating an 420 authentication failure. 422 * 200-Optional-INIT message: a variant of the 401-INIT message 423 indicating that an authentication is not mandatory. 425 * 401-STALE message: a message indicating that it has to start a 426 new authentication trial. 428 o Authenticated key exchange messages: used by both peers to perform 429 authentication and the sharing of a cryptographic secret. 431 * req-KEX-C1 message: a message sent from the client. 433 * 401-KEX-S1 message: a message sent from the server as a 434 response to a req-KEX-C1 message. 436 o Authentication verification messages: used by both peers to verify 437 the authentication results. 439 * req-VFY-C message: a message used by the client, requesting 440 that the server authenticates and authorizes the client. 442 * 200-VFY-S message: a successful response used by the server, 443 and also asserting that the server is authentic to the client 444 simultaneously. 446 In addition to the above, either a request or a response without any 447 HTTP headers related to this specification will be hereafter called a 448 "normal request" or a "normal response", respectively. 450 2.2. Typical Flows of the Protocol 452 In typical cases, the client access to a resource protected by the 453 Mutual authentication will follow the following protocol sequence. 455 Client Server 456 | | 457 | ---- (1) normal request ---------> | 458 GET / HTTP/1.1 | 459 | | 460 | <---------------- (2) 401-INIT --- | 461 | 401 Authentication Required 462 | WWW-Authenticate: Mutual realm="a realm" 463 | | 464 [user, | | 465 pass]-->| | 466 | ---- (3) req-KEX-C1 -------------> | 467 GET / HTTP/1.1 | 468 Authorization: Mutual user="john", |--> [user DB] 469 kc1="...", ... |<-- [user info] 470 | | 471 | <-------------- (4) 401-KEX-S1 --- | 472 | 401 Authentication Required 473 | WWW-Authenticate: Mutual sid=..., ks1="...", ... 474 | | 475 [compute] (5) compute session secret [compute] 476 | | 477 | | 478 | ---- (6) req-VFY-C --------------> | 479 GET / HTTP/1.1 |--> [verify (6)] 480 Authorization: Mutual sid=..., |<-- OK 481 vkc="...", ... | 482 | | 483 | <--------------- (7) 200-VFY-S --- | 484 [verify | 200 OK | 485 (7)]<--| Authentication-Info: Mutual vks="..." 486 | | 487 v v 489 Figure 1: Typical communication flow for first access to resource 491 o As usual in general HTTP protocol designs, a client will at first 492 request a resource without any authentication attempt (1). If the 493 requested resource is protected by the Mutual authentication, the 494 server will respond with a message requesting authentication 495 (401-INIT) (2). 497 o The client processes the body of the message, and waits for the 498 user to input the user name and a password. If the user name and 499 the password are available, the client will send a message with 500 the authenticated key exchange (req-KEX-C1) to start the 501 authentication (3). 503 o If the server has received a req-KEX-C1 message, the server looks 504 up the user's authentication information within its user database. 505 Then the server creates a new session identifier (sid) that will 506 be used to identify sets of the messages that follow it, and 507 responds back with a message containing a server-side 508 authenticated key exchange value (401-KEX-S1) (4). 510 o At this point (5), both peers calculate a shared "session secret" 511 using the exchanged values in the key exchange messages. Only 512 when both the server and the client have used secret credentials 513 generated from the same password will the session secret values 514 match. This session secret will be used for the actual access 515 authentication after this point. 517 o The client will send a request with a client-side authentication 518 verification value (req-VFY-C) (6), generated from the client- 519 owned session secret. The server will check the validity of the 520 verification value using its own session secret. 522 o If the authentication verification value from the client was 523 correct, it means that the client definitely owns the credential 524 based on the expected password (i.e. the client authentication 525 succeeded.) The server will respond with a successful message 526 (200-VFY-S) (7). Contrary to the usual one-way authentication 527 (e.g. HTTP Basic authentication or POP APOP authentication), this 528 message also contains a server-side authentication verification 529 value. 531 When the client's verification value is incorrect (e.g. because 532 the user-supplied password was incorrect), the server will respond 533 with the 401-INIT message (the same one as used in (2)) instead. 535 o The client MUST first check the validity of the server-side 536 authentication verification value contained in the message (7). 537 If the value was equal to the expected one, the server 538 authentication succeeded. 540 If it is not the value expected, or if the message does not 541 contain the authentication verification value, it means that the 542 mutual authentication has been broken for some unexpected reason. 543 The client MUST NOT process any body or header values contained in 544 this case. (Note: This case should not happen between a 545 correctly-implemented server and a client.) 547 2.3. Alternative Flows 549 As shown above, the typical flow for a first authenticated request 550 requires three request-response pairs. To reduce the protocol 551 overhead, the protocol enables several short-cut flows which require 552 fewer messages. 554 o (case A) If the client knows that the resource is likely to 555 require the authentication, the client MAY omit the first 556 unauthenticated request (1) and immediately send a key exchange 557 (req-KEX-C1 message). This will reduce one round-trip of 558 messages. 560 o (case B) If both the client and the server previously shared a 561 session secret associated with a valid session identifier (sid), 562 the client MAY directly send a req-VFY-C message using the 563 existing session identifier and corresponding session secret. 564 This will further reduce one round-trip of messages. 566 In such cases, the server MAY have thrown out the corresponding 567 sessions from the session table. In this case, the server will 568 respond with a 401-STALE message, indicating a new key exchange is 569 required. The client SHOULD retry constructing a req-KEX-C1 570 message in this case. 572 Figure 2 depicts the shortcut flows described above. Under the 573 appropriate settings and implementations, most of the requests to 574 resources are expected to meet both the criteria, and thus only one 575 round-trip of request/responses will be required in most cases. 577 (A) omit first request 578 (2 round trips) 580 Client Server 581 | | 582 | --- req-KEX-C1 ----> | 583 | | 584 | <---- 401-KEX-S1 --- | 585 | | 586 | ---- req-VFY-C ----> | 587 | | 588 | <----- 200-VFY-S --- | 589 | | 591 (B) reusing session secret 593 (B-1) key available (B-2) key expired 594 (1 round trip) (3 round trips) 596 Client Server Client Server 597 | | | | 598 | ---- req-VFY-C ----> | | --- req-VFY-C -------> | 599 | | | | 600 | <----- 200-VFY-S --- | | <------- 401-STALE --- | 601 | | | | 602 | --- req-KEX-C1 ------> | 603 | | 604 | <------ 401-KEX-S1 --- | 605 | | 606 | --- req-VFY-C -------> | 607 | | 608 | <------- 200-VFY-S --- | 609 | | 611 Figure 2: Several alternative flows on protocol 613 For more details, see Sections 9 and 10. 615 3. Message Syntax 617 Throughout this specification, The syntax is denoted in the extended 618 augmented BNF syntax defined in [I-D.ietf-httpbis-p1-messaging] and 619 [RFC5234]. The following elements are quoted from [RFC5234], 620 [I-D.ietf-httpbis-p1-messaging] and [I-D.ietf-httpbis-p7-auth]: 621 DIGIT, ALPHA, SP, auth-scheme, quoted-string, auth-param, header- 622 field, token, challenge, and credential. 624 The Mutual authentication protocol uses three headers: 625 WWW-Authenticate (in responses with status code 401), Authorization 626 (in requests), and Authentication-Info (in responses other than 401 627 status). These headers follow a common framework described in 628 [I-D.ietf-httpbis-p7-auth]. The detailed meanings for these headers 629 are contained in Section 4. 631 The framework in [I-D.ietf-httpbis-p7-auth] defines the syntax for 632 the headers WWW-Authenticate and Authorization as the syntax elements 633 "challenge" and "credentials", respectively. The "auth-scheme" 634 contained in those headers MUST be "Mutual" throughout this protocol 635 specification. The syntax for "challenge" and "credentials" to be 636 used with the "Mutual" auth-scheme SHALL be name-value pairs (#auth- 637 param), not the "b64token" defined in [I-D.ietf-httpbis-p7-auth]. 639 The Authentication-Info: header used in this protocol SHALL contain 640 the value in same syntax as those the "WWW-Authenticate" header, i.e. 641 the "challenge" syntax element. 643 In HTTP, the WWW-Authenticate header may contain more than one 644 challenges. Client implementations SHOULD be aware of and be capable 645 of handle those cases correctly. 647 3.1. Values 649 The parameter values contained in challenge/credentials MUST be 650 parsed strictly conforming to the HTTP semantics (especially un- 651 quoting of the string parameter values). In this protocol, those 652 values are further categorized into the following value types: tokens 653 (bare-token and extensive-token), string, integer, hex-fixed-number, 654 and base64-fixed-number. 656 For clarity, implementations are encouraged to use the canonical 657 representations specified in the following subsections for sending 658 values. Recipients SHOULD accept both quoted and unquoted 659 representations interchangeably as specified in HTTP. 661 3.1.1. Tokens 663 For sustaining both security and extensibility at the same time, this 664 protocol defines a stricter sub-syntax for the "token" to be used. 665 The extensive-token values SHOULD follow the following syntax (after 666 HTTP value parsing): 668 bare-token = 1*(DIGIT / ALPHA / "-" / "_") 669 extension-token = "-" bare-token 1*("." bare-token) 670 extensive-token = bare-token / extension-token 671 Figure 3: BNF syntax for token values 673 The tokens (bare-token and extension-token) are case insensitive; 674 Senders SHOULD send these in lower-case, and receivers MUST accept 675 both upper- and lower-cases. When tokens are used as (partial) 676 inputs to any hash or other mathematical functions, it MUST always be 677 used in lower-case. 679 Extensive-tokens are used in this protocol where the set of 680 acceptable tokens may include non-standard extensions. Any non- 681 standard extensions of this protocol SHOULD use the extension-tokens 682 with format "-.", where is a 683 validly registered (sub-)domain name on the Internet owned by the 684 party who defines the extensions. 686 Bare-tokens and extensive-tokens are also used for parameter names 687 (of course in the unquoted form). Requirements for using the 688 extension-token for the parameter names are the same as the above. 690 The canonical format for bare-tokens and tokens are unquoted tokens. 692 3.1.2. Strings 694 All character strings outside ASCII character sets MUST be encoded 695 using the UTF-8 encoding [RFC3629] for the ISO 10646-1 character set 696 [ISO.10646-1.1993], without any leading BOM characters. Both peers 697 are RECOMMENDED to reject any invalid UTF-8 sequences that might 698 cause decoding ambiguities (e.g., containing <"> in the second or 699 later byte of the UTF-8 encoded characters). 701 If strings are representing a domain name or URI that contains non- 702 ASCII characters, the host parts SHOULD be encoded as it is used in 703 the HTTP protocol layer (e.g. in a Host: header); under current 704 standards it will be the one defined in [RFC5890]. It SHOULD use 705 lower-case ASCII characters. 707 The canonical format for strings are quoted-string. 709 3.1.3. Numbers 711 The following syntax definitions gives a syntax for number-type 712 values: 714 integer = "0" / (%x31-39 *DIGIT) ; no leading zeros 715 hex-fixed-number = 1*(2(DIGIT / %x41-46 / %x61-66)) 716 base64-fixed-number = 1*( ALPHA / DIGIT / 717 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 719 Figure 4: BNF syntax for number types 721 The syntax definition of the integers only allows representations 722 that do not contain extra leading zeros. 724 The numbers represented as a hex-fixed-number MUST include an even 725 number of characters (i.e. multiples of eight bits). Those values 726 are case-insensitive, and SHOULD be sent in lower-case. When these 727 values are generated from any cryptographic values, they SHOULD have 728 their "natural length": if these are generated from a hash function, 729 these lengths SHOULD correspond to the hash size; if these are 730 representing elements of a mathematical set (or group), its lengths 731 SHOULD be the shortest for representing all the elements in the set. 732 For example, any results of SHA-256 hash function will be represented 733 by 64 characters, and any elements in 2048-bit prime field (modulo a 734 2048-bit integer) will be represented by 512 characters, regardless 735 of how much 0's will be appear in front of such representations. 736 Session-identifiers and other non-cryptographically generated values 737 are represented in any (even) length determined by the side who 738 generates it first, and the same length SHALL be used throughout the 739 all communications by both peers. 741 The numbers represented as base64-fixed-number SHALL be generated as 742 follows: first, the number is converted to a big-endian radix-256 743 binary representation as an octet string. The length of the 744 representation is determined in the same way as mentioned above. 745 Then, the string is encoded using the Base 64 encoding [RFC4648] 746 without any spaces and newlines. Implementations decoding base64- 747 fixed-number SHOULD reject any input data with invalid characters, 748 excess/insufficient paddings, or non-canonical pad bits (See Sections 749 3.1 to 3.5 of [RFC4648]). 751 The canonical format for integer and hex-fixed-number are unquoted 752 tokens, and that for base64-fixed-number is quoted-string. 754 4. Messages 756 In this section we define the seven kinds of messages used in the 757 authentication protocol along with the formats and requirements of 758 the headers for each message. 760 To determine which message are expected to be sent, see Sections 9 761 and 10. 763 In the descriptions below, the type of allowable values for each 764 header parameter is shown in parenthesis after each parameter name. 765 The "algorithm-determined" type means that the acceptable value for 766 the parameter is one of the types defined in Section 3, and is 767 determined by the value of the "algorithm" parameter. The parameters 768 marked "mandatory" SHALL be contained in the message. The parameters 769 marked "non-mandatory" MAY either be contained or omitted in the 770 message. Each parameter SHALL appear in each headers exactly once at 771 most. 773 All credentials and challenges MAY contain any parameters not 774 explicitly specified in the following sections. Recipients who do 775 not understand such parameters MUST silently ignore those. However, 776 all credentials and challenges MUST meet the following criteria: 778 o For responses, the parameters "reason", any "ks*" (where * stands 779 for any decimal integers), and "vks" are mutually exclusive: any 780 challenge MUST NOT contain two or more parameters among them. 781 They MUST NOT contain any "kc*" and "vkc" parameters. 783 o For requests, the parameters "kc*" (where * stands for any decimal 784 integers), and "vks" are mutually exclusive and any challenge 785 MUST NOT contain two or more parameters among them. They MUST NOT 786 contain any "ks*" and "vks" parameters. 788 4.1. 401-INIT and 401-STALE 790 Every 401-INIT or 401-STALE message SHALL be a valid HTTP 401-status 791 (Authentication Required) message containing one (and only one: 792 hereafter not explicitly noticed) "WWW-Authenticate" header 793 containing a "reason" parameter in the challenge. The challenge 794 SHALL contain all of the parameters marked "mandatory" below, and MAY 795 contain those marked "non-mandatory". 797 version: (mandatory extensive-token) should be the token 798 "-draft11" in this specification. The behavior is 799 undefined when other values are specified. 801 algorithm: (mandatory extensive-token) specifies the 802 authentication algorithm to be used. The value MUST 803 be one of the tokens specified in 804 [I-D.oiwa-http-mutualauth-algo] or other supplemental 805 specification documentation. 807 validation: (mandatory extensive-token) specifies the method of 808 host validation. The value MUST be one of the tokens 809 described in Section 7, or the tokens specified in 810 other supplemental specification documentation. 812 auth-domain: (non-mandatory string) specifies the authentication 813 domain, the set of hosts for which the authentication 814 credentials are valid. It MUST be one of the strings 815 described in Section 5. If the value is omitted, it 816 is assumed to be the "single-port" type domain in 817 Section 5. 819 realm: (mandatory string) is a UTF-8 encoded string 820 representing the name of the authentication realm 821 inside the authentication domain. As specified in 822 [I-D.ietf-httpbis-p7-auth], this value MUST always be 823 sent in the quoted-string form. 825 pwd-hash: (non-mandatory extensive-token) specifies the hash 826 algorithm (hereafter referred to by ph) used for 827 additionally hashing the password. The valid tokens 828 are 830 * none: ph(p) = p 832 * md5: ph(p) = MD5(p) 834 * digest-md5: ph(p) = MD5(username | ":" | realm | 835 ":" | p), the same value as MD5(A1) for "MD5" 836 algorithm in [RFC2617]. 838 * sha1: ph(p) = SHA1(p) 840 If omitted, the value "none" is assumed. The use of 841 "none" is recommended. 843 reason: (mandatory extensive-token) SHALL be an extensive- 844 token which describes the possible reason of the 845 failed authentication/authorization. Both servers and 846 clients SHALL understand and support the following 847 three tokens: 849 * initial: authentication was not tried because there 850 was no Authorization header in the corresponding 851 request. 853 * stale-session: the provided sid; in the request was 854 either unknown to or expired in the server. 856 * auth-failed: authentication trial was failed by 857 some reasons, possibly with a bad authentication 858 credentials. 860 Implementations MAY support the following tokens or 861 any extensive-tokens defined outside this 862 specification. If clients has received any unknown 863 tokens, these SHOULD treat these as if it were "auth- 864 failed" or "initial". 866 * reauth-needed: server-side application requires a 867 new authentication trial, regardless of the current 868 status. 870 * invalid-parameters: authentication was not even 871 tried in the server-side because some parameters 872 are not acceptable. 874 * internal-error: authentication was not even tried 875 in the server-side because there is some troubles 876 on the server-side. 878 * user-unknown: a special case of auth-failed, 879 suggesting that the provided user-name is invalid. 880 The use of this parameter is NOT RECOMMENDED for 881 security implications, except for special-purpose 882 applications which makes this value sense. 884 * invalid-credential: ditto, suggesting that the 885 provided user-name was valid but authentication was 886 failed. The use of this parameter is 887 NOT RECOMMENDED as the same as the above. 889 * authz-failed: authentication was successful, but 890 access to the specified resource is not authorized 891 to the specific authenticated user. (It is 892 different from 403 responses which suggest that the 893 reason of inaccessibility is other that 894 authentication.) 896 The algorithm specified in this header will determine the types 897 (among those defined in Section 3) and the values for K_c1, K_s1, 898 VK_c and VK_s. 900 Among these messages, those with the reason parameter of value 901 "stale-session" will be called "401-STALE" messages hereafter, 902 because these have a special meaning in the protocol flow. Messages 903 with any other reason parameters will be called "401-INIT" messages. 905 4.2. req-KEX-C1 907 Every req-KEX-C1 message SHALL be a valid HTTP request message 908 containing an "Authorization" header with a credential containing a 909 "kc1" parameter. 911 The credential SHALL contain the parameters with the following names: 913 version: (mandatory, extensive-token) should be the token 914 "-draft11" in this specification. The behavior is 915 undefined when other values are specified. 917 algorithm, validation, auth-domain, realm: MUST be the same value as 918 it is when received from the server. 920 user: (mandatory, string) is the UTF-8 encoded name of the 921 user. If this name comes from a user input, client 922 software SHOULD prepare the string using SASLprep 923 [RFC4013] before encoding it to UTF-8. 925 kc1: (mandatory, algorithm-determined) is the client-side 926 key exchange value K_c1, which is specified by the 927 algorithm that is used. 929 rekey-sid: (non-mandatory, hex-fixed-number): reserved for future 930 extensions (see rekey-method in "200-VFY-S" message). 932 4.3. 401-KEX-S1 934 Every 401-KEX-S1 message SHALL be a valid HTTP 401-status 935 (Authentication Required) response message containing a 936 "WWW-Authenticate" header with a challenge containing a "ks1" 937 parameter. 939 The challenge SHALL contain the parameters with the following names: 941 version: (mandatory, extensive-token) should be the token 942 "-draft11" in this specification. The behavior is 943 undefined when other values are specified. 945 algorithm, validation, auth-domain, realm: MUST be the same value as 946 it is when received from the client. 948 sid: (mandatory, hex-fixed-number) MUST be a session 949 identifier, which is a random integer. The sid SHOULD 950 have uniqueness of at least 80 bits or the square of 951 the maximal estimated transactions concurrently 952 available in the session table, whichever is larger. 954 See Section 6 for more details. 956 ks1: (mandatory, algorithm-determined) is the server-side 957 key exchange value K_s1, which is specified by the 958 algorithm. 960 nc-max: (mandatory, integer) is the maximal value of nonce 961 counts that the server accepts. 963 nc-window: (mandatory, integer) the number of available nonce 964 slots that the server will accept. The value of the 965 nc-window parameter is RECOMMENDED to be 32 or more. 967 time: (mandatory, integer) represents the suggested time (in 968 seconds) that the client can reuse the session 969 represented by the sid. It is RECOMMENDED to be at 970 least 60. The value of this parameter is not directly 971 linked to the duration that the server keeps track of 972 the session represented by the sid. 974 path: (non-mandatory, string) specifies which path in the 975 URI space the same authentication is expected to be 976 applied. The value is a space-separated list of URIs, 977 in the same format as it was specified in domain 978 parameter [RFC2617] for the Digest authentications, 979 and clients are RECOMMENDED to recognize it. The all 980 path elements contained in the parameter MUST be 981 inside the specified auth-domain: if not, clients 982 SHOULD ignore such elements. 984 4.4. req-VFY-C 986 Every req-VFY-C message SHALL be a valid HTTP request message 987 containing an "Authorization" header with a credential containing a 988 "vkc" parameter. 990 The parameters contained in the header are as follows: 992 version: (mandatory, extensive-token) should be the token 993 "-draft11" in this specification. The behavior is 994 undefined when other values are specified. 996 algorithm, validation, auth-domain, realm: MUST be the same value as 997 it is when received from the server for the session. 999 sid: (mandatory, hex-fixed-number) MUST be one of the sid 1000 values that was received from the server for the same 1001 authentication realm. 1003 nc: (mandatory, integer) is a nonce value that is unique 1004 among the requests sharing the same sid. The values 1005 of the nonces SHOULD satisfy the properties outlined 1006 in Section 6. 1008 vkc: (mandatory, algorithm-determined) is the client-side 1009 authentication verification value VK_c, which is 1010 specified by the algorithm. 1012 4.5. 200-VFY-S 1014 Every 200-VFY-S message SHALL be a valid HTTP message that is not of 1015 the 401 (Authentication Required) status, containing an 1016 "Authentication-Info" header with a "vks" parameter. 1018 The parameters contained in the header are as follows: 1020 version: (mandatory, extensive-token) should be the token 1021 "-draft11" in this specification. The behavior is 1022 undefined when other values are specified. 1024 sid: (mandatory, hex-fixed-number) MUST be the value 1025 received from the client. 1027 vks: (mandatory, algorithm-determined) is the server-side 1028 authentication verification value VK_s, which is 1029 specified by the algorithm. 1031 logout-timeout: (non-mandatory, integer) is the number of seconds 1032 after which the client should re-validate the user's 1033 password for the current authentication realm. The 1034 value 0 means that the client SHOULD automatically 1035 forget the user-inputted password for the current 1036 authentication realm and revert to the unauthenticated 1037 state (i.e. server-initiated logout). This does not, 1038 however, mean that the long-term memories for the 1039 passwords (such as the password reminders and auto 1040 fill-ins) should be removed. If a new timeout value 1041 is received for the same authentication realm, it 1042 overrides the previous timeout. If logout-timeout 1043 parameters are specified both in an 1044 Authentication-Info header and an 1045 Authentication-Control header 1046 ([I-D.oiwa-http-auth-extension]), the client SHOULD 1047 respect the smaller one of those and ignore the other. 1049 rekey-method: (non-mandatory, extensive-token): defining a 1050 credential used for reestablishing a new session with 1051 a new sid. It must be either omitted or the token 1052 "passwords" at the current specification. The bare- 1053 tokens "refresh-key" and "refresh-key-global" are 1054 reserved for future extensions. 1056 The header MUST be sent before the content body: it MUST NOT be sent 1057 in the trailer of a chunked-encoded response. If a "100 Continue" 1058 response is sent from the server, the Authentication-Info header 1059 SHOULD be included in that response, instead of the final response. 1061 5. Authentication Realms 1063 In this protocol, an "authentication realm" is defined as a set of 1064 resources (URIs) for which the same set of user names and passwords 1065 is valid for. If the server requests authentication for an 1066 authentication realm that the client is already authenticated for, 1067 the client will automatically perform the authentication using the 1068 already-known secrets. However, for the different authentication 1069 realms, the clients SHOULD NOT automatically reuse the usernames and 1070 passwords for another realm. 1072 Just like in Basic and Digest access authentication protocols, Mutual 1073 authentication protocol supports multiple, separate protection spaces 1074 to be set up inside each host. Furthermore, the protocol supports 1075 that a single authentication realm spans over several hosts within 1076 the same Internet domain. 1078 Each authentication realm is defined and distinguished by the triple 1079 of an "authentication algorithm", an "authentication domain", and a 1080 "realm" parameter. However, server operators are NOT RECOMMENDED to 1081 use the same pair of an authentication domain and a realm for 1082 different authentication algorithms. 1084 The realm parameter is a string as defined in Section 4. 1085 Authentication domains are described in the remainder of this 1086 section. 1088 An authentication domain specifies the range of hosts that the 1089 authentication realm spans over. In this protocol, it MUST be one of 1090 the following strings. 1092 o Single-server type: The string in format 1093 "://:", where , , and are 1094 the corresponding URI parts of the request URI. Even if the 1095 request-URI does not have a port part, the string will include one 1096 (i.e. 80 for http and 443 for https). The port part MUST NOT 1097 contain leading zeros. Use this when authentication is only valid 1098 for specific protocol (such as https). 1100 o Single-host type: The "host" part of the requested URI. This is 1101 the default value. Authentication realms within this kind of 1102 authentication domain will span over several protocols (i.e. http 1103 and https) and ports, but not over different hosts. 1105 o Wildcard-domain type: The string in format "*.", 1106 where is either the host part of the requested 1107 URI or any domain in which the requested host is included (this 1108 means that the specification "*.example.com" is valid for all of 1109 hosts "www.example.com", "web.example.com", 1110 "www.sales.example.com" and "example.com"). The domain-postfix 1111 sent from the servers MUST be equal to or included in a valid 1112 Internet domain assigned to a specific organization: if clients 1113 know, by some means such as a blacklist for HTTP cookies 1114 [RFC6265], that the specified domain is not to be assigned to any 1115 specific organization (e.g. "*.com" or "*.jp"), the clients are 1116 RECOMMENDED to reject the authentication request. 1118 In the above specifications, every "scheme", "host", and "domain" 1119 MUST be in lower-case, and any internationalized domain names beyond 1120 the ASCII character set SHALL be represented in the way they are sent 1121 in the underlying HTTP protocol, represented in lower-case 1122 characters; i.e. these SHALL be in the form of the LDH labels in IDNA 1123 [RFC5890]. All "port"s MUST be in the shortest, unsigned, decimal 1124 number notation. Not obeying these requirements will cause failure 1125 of valid authentication attempts. 1127 5.1. Resolving Ambiguities 1129 In the above definitions of authentication domains, several domains 1130 will overlap each other. Depending on the "path" parameters given in 1131 the "401-KEX-S1" message (see Section 4), there may be several 1132 candidates when the client is going to send a request including an 1133 authentication credential (Steps 3 and 4 of the decision procedure 1134 presented in Section 9). 1136 If such choices are required, the following procedure SHOULD be 1137 followed. 1139 o If the client has previously sent a request to the same URI, and 1140 if it remembers the authentication realm requested by 401-INIT 1141 messages at that time, use that realm. 1143 o In other cases, use one of authentication realms representing the 1144 most-specific authentication domains. From the list of possible 1145 domain specifications shown above, each one earlier has priority 1146 over ones described after that. 1148 If there are several choices with different domain-postfix 1149 specifications, the one that has the longest domain-postfix has 1150 priority over ones with a shorter domain-postfix. 1152 o If there are realms with the same authentication domain, there is 1153 no defined priority: the client MAY choose any one of the possible 1154 choices. 1156 If possible, server operators are encouraged to avoid such 1157 ambiguities by properly setting the "path" parameters. 1159 6. Session Management 1161 In the Mutual authentication protocol, a session represented by an 1162 sid is set up using first four messages (first request, 401-INIT, 1163 req-KEX-C1 and 401-KEX-S1), and a "session secret" (z) associated 1164 with the session is established. After sharing a session secret, 1165 this session, along with the secret, can be used for one or more 1166 requests for resources protected by the same realm in the same 1167 server. Note that session management is only an inside detail of the 1168 protocol and usually not visible to normal users. If a session 1169 expires, the client and server SHOULD automatically reestablish 1170 another session without informing the users. 1172 Sessions and session identifiers are local to each server (defined by 1173 scheme, host and port) inside an authentication domain; the clients 1174 MUST establish separate sessions for each port of a host to be 1175 accessed. Furthermore, sessions and identifiers are also local to 1176 each authentication realm, even if these are provided from the same 1177 servers. The same session identifiers provided either from different 1178 servers or for different realms SHOULD be treated as independent 1179 ones. 1181 The server SHOULD accept at least one req-VFY-C request for each 1182 session, given that the request reaches the server in a time window 1183 specified by the timeout parameter in the 401-KEX-S1 message, and 1184 that there are no emergent reasons (such as flooding attacks) to 1185 forget the sessions. After that, the server MAY discard any session 1186 at any time and MAY send 401-STALE messages for any req-VFY-C 1187 requests. 1189 The client MAY send two or more requests using a single session 1190 specified by the sid. However, for all such requests, each value of 1191 the nonce (in the nc parameter) MUST satisfy the following 1192 conditions: 1194 o It is a natural number. 1196 o The same nonce was not sent within the same session. 1198 o It is not larger than the nc-max value that was sent from the 1199 server in the session represented by the sid. 1201 o It is larger than (largest-nc - nc-window), where largest-nc is 1202 the maximal value of nc which was previously sent in the session, 1203 and nc-window is the value of the nc-window parameter which was 1204 received from the server in the session. 1206 The last condition allows servers to reject any nonce values that are 1207 "significantly" smaller than the "current" value (defined by the 1208 value of nc-window) of the nonce used in the session involved. In 1209 other words, servers MAY treat such nonces as "already received". 1210 This restriction enables servers to implement duplicated nonce 1211 detection in a constant amount of memory (for each session). 1213 Servers MUST check for duplication of the received nonces, and if any 1214 duplication is detected, the server MUST discard the session and 1215 respond with a 401-STALE message, as outlined in Section 10. The 1216 server MAY also reject other invalid nonce values (such as ones above 1217 the nc-max limit) by sending a 401-STALE message. 1219 For example, assume the nc-window value of the current session is 32, 1220 nc-max is 100, and that the client has already used the following 1221 nonce values: {1-20, 22, 24, 30-38, 45-60, 63-72}. Then the nonce 1222 values that can be used for next request is one of the following set: 1223 {41-44, 61-62, 73-100}. The values {0, 21, 23, 25-29, 39-40} MAY be 1224 rejected by the server because they are not above the current "window 1225 limit" (40 = 72 - 32). 1227 Typically, clients can ensure the above property by using a 1228 monotonically-increasing integer counter that counts from zero upto 1229 the value of nc-max. 1231 The values of the nonces and any nonce-related values MUST always be 1232 treated as natural numbers within an infinite range. Implementations 1233 using fixed-width integers or fixed-precision floating numbers MUST 1234 correctly and carefully handle integer overflows. Such 1235 implementations are RECOMMENDED to accept any larger values that 1236 cannot be represented in the fixed-width integer representations, as 1237 long as other limits such as internal header-length restrictions are 1238 not involved. The protocol is designed carefully so that both the 1239 clients and servers can implement the protocol using only fixed-width 1240 integers, by rounding any overflowed values to the maximum possible 1241 value. 1243 7. Validation Methods 1245 The "validation method" specifies a method to "relate" the mutual 1246 authentication processed by this protocol with other authentications 1247 already performed in the underlying layers and to prevent man-in-the- 1248 middle attacks. It decides the value v that is an input to the 1249 authentication protocols. 1251 The valid tokens for the validation parameter and corresponding 1252 values of v are as follows: 1254 host: hostname validation: The value v will be the ASCII 1255 string in the following format: 1256 "://:", where , , 1257 and are the URI components corresponding to the 1258 currently accessing resource. The scheme and host are 1259 in lower-case, and the port is in a shortest decimal 1260 representation. Even if the request-URI does not have 1261 a port part, v will include one. 1263 tls-cert: TLS certificate validation: The value v will be the 1264 octet string of the hash value of the public key 1265 certificate used in the underlying TLS [RFC5246] (or 1266 SSL) connection. The hash value is defined as the 1267 value of the entire signed certificate (specified as 1268 "Certificate" in [RFC5280]), hashed by the hash 1269 algorithm specified by the authentication algorithm 1270 used. 1272 tls-key: TLS shared-key validation: The value v will be the 1273 octet string of the shared master secret negotiated in 1274 the underlying TLS (or SSL) connection. 1276 If the HTTP protocol is used on a non-encrypted channel (TCP and 1277 SCTP, for example), the validation type MUST be "host". If HTTP/TLS 1278 [RFC2818] (HTTPS) protocol is used with the server certificates, the 1279 validation type MUST be either "tls-cert" or "tls-key". If HTTP/TLS 1280 protocol is used with an anonymous Diffie-Hellman key exchange, the 1281 validation type MUST be "tls-key" (see the note below). 1283 If the validation type "tls-cert" is used, the server certificate 1284 provided on TLS connection MUST be verified to make sure that the 1285 server actually owns the corresponding secret key. 1287 Clients MUST validate this parameter upon reception of the 401-INIT 1288 messages. 1290 However, when the client is a Web browser with any scripting 1291 capabilities, the underlying TLS channel used with HTTP/TLS MUST 1292 provide server identity verification. This means (1) the anonymous 1293 Diffie-Hellman key exchange ciphersuite MUST NOT be used, and (2) the 1294 verification of the server certificate provided from the server MUST 1295 be performed. 1297 For other systems, when the underlying TLS channel used with HTTP/TLS 1298 does not perform server identity verification, the client SHOULD 1299 ensure that all the responses are validated using the Mutual 1300 authentication protocol, regardless of the existence of the 401-INIT 1301 responses. 1303 Note: The protocol defines two variants for validation on the TLS 1304 connections. The "tls-key" method is more secure. However, there 1305 are some situations where tls-cert is more preferable. 1307 o When TLS accelerating proxies are used, it is difficult for the 1308 authenticating server to acquire the TLS key information that is 1309 used between the client and the proxy. This is not the case for 1310 client-side "tunneling" proxies using a CONNECT method extension 1311 of HTTP. 1313 o When a black-box implementation of the TLS protocol is used on 1314 either peer. 1316 Implementations supporting a Mutual authentication over the HTTPS 1317 protocol SHOULD support the "tls-cert" validation. Support for 1318 "tls-key" validation is OPTIONAL for both the servers and clients. 1320 8. Authentication Extensions 1322 The HTTP authentication extensions described in 1323 [I-D.oiwa-http-auth-extension] is a definitive part of this protocol. 1324 Interactive clients (e.g. Web browsers) supporting this protocol are 1325 RECOMMENDED to support non-mandatory authentication and the 1326 Authentication-Control header defined there, except the "auth-style" 1327 parameter. This specification also proposes (however, not mandates) 1328 default "auth-style" to be "non-modal". Web applications SHOULD 1329 however consider the security impacts of the behaviors of clients 1330 that do not support these headers. 1332 Authentication-initializing messages with the 1333 Optional-WWW-Authenticate header are used where 401-INIT response is 1334 valid. Such a message is called a 200-Optional-INIT message in this 1335 document. (It will not replace other 401-type messages such as 1336 401-STALE and 401-KEX-S1.) 1338 9. Decision Procedure for Clients 1340 To securely implement the protocol, the user client must be careful 1341 about accepting the authenticated responses from the server. This 1342 also holds true for the reception of "normal responses" (responses 1343 which do not contain Mutual-related headers) from HTTP servers. 1345 Clients SHOULD implement a decision procedure equivalent to the one 1346 shown below. (Unless implementers understand what is required for 1347 the security, they should not alter this.) In particular, clients 1348 SHOULD NOT accept "normal responses" unless explicitly allowed below. 1349 The labels on the steps are for informational purposes only. Action 1350 entries within each step are checked in top-to-bottom order, and the 1351 first clause satisfied SHOULD be taken. 1353 Step 1 (step_new_request): 1354 If the client software needs to access a new Web resource, check 1355 whether the resource is expected to be inside some authentication 1356 realm for which the user has already been authenticated by the 1357 Mutual authentication scheme. If yes, go to Step 2. Otherwise, 1358 go to Step 5. 1360 Step 2: 1361 Check whether there is an available sid for the authentication 1362 realm you expect. If there is one, go to Step 3. Otherwise, go 1363 to Step 4. 1365 Step 3 (step_send_vfy_1): 1366 Send a req-VFY-C request. 1368 * If you receive a 401-INIT message with a different 1369 authentication realm than expected, go to Step 6. 1371 * If you receive a 200-Optional-INIT message with a different 1372 authentication realm than expected, go to Step 6. 1374 * If you receive a 401-STALE message, go to Step 9. 1376 * If you receive a 401-INIT message, go to Step 13. 1378 * If you receive a 200-VFY-S message, go to Step 14. 1380 * If you receive a normal response, go to Step 11. 1382 Step 4 (step_send_kex1_1): 1383 Send a req-KEX-C1 request. 1385 * If you receive a 401-INIT message with a different 1386 authentication realm than expected, go to Step 6. 1388 * If you receive a 200-Optional-INIT message with a different 1389 authentication realm than expected, go to Step 6. 1391 * If you receive a 401-KEX-S1 message, go to Step 10. 1393 * If you receive a 401-INIT message with the same authentication 1394 realm, go to Step 13 (see Note 1). 1396 * If you receive a normal response, go to Step 11. 1398 Step 5 (step_send_normal_1): 1399 Send a request without any Mutual authentication headers. 1401 * If you receive a 401-INIT message, go to Step 6. 1403 * If you receive a 200-Optional-INIT message, go to Step 6. 1405 * If you receive a normal response, go to Step 11. 1407 Step 6 (step_rcvd_init): 1408 Check whether you know the user's password for the requested 1409 authentication realm. If yes, go to Step 7. Otherwise, go to 1410 Step 12. 1412 Step 7: 1413 Check whether there is an available sid for the authentication 1414 realm you expect. If there is one, go to Step 8. Otherwise, go 1415 to Step 9. 1417 Step 8 (step_send_vfy): 1418 Send a req-VFY-C request. 1420 * If you receive a 401-STALE message, go to Step 9. 1422 * If you receive a 401-INIT message, go to Step 13. 1424 * If you receive a 200-VFY-S message, go to Step 14. 1426 Step 9 (step_send_kex1): 1427 Send a req-KEX-C1 request. 1429 * If you receive a 401-KEX-S1 message, go to Step 10. 1431 * If you receive a 401-INIT message, go to Step 13 (See Note 1). 1433 Step 10 (step_rcvd_kex1): 1434 Send a req-VFY-C request. 1436 * If you receive a 401-INIT message, go to Step 13. 1438 * If you receive a 200-VFY-S message, go to Step 14. 1440 Step 11 (step_rcvd_normal): 1441 The requested resource is out of the authenticated area. The 1442 client will be in the "UNAUTHENTICATED" status. If the response 1443 contains a request for authentications other than Mutual, it MAY 1444 be handled normally. 1446 Step 12 (step_rcvd_init_unknown): 1447 The requested resource requires a Mutual authentication, and the 1448 user is not yet authenticated. The client will be in the "AUTH- 1449 REQUESTED" status, and is RECOMMENDED to process the content sent 1450 from the server, and to ask user for a user name and a password. 1451 When those are supplied from the user, proceed to Step 9. 1453 Step 13 (step_rcvd_init_failed): 1454 For some reason the authentication failed: possibly the password 1455 or the username is invalid for the authenticated resource. 1456 Forget the password for the authentication realm and go to Step 1457 12. 1459 Step 14 (step_rcvd_vfy): 1460 Check the validity of the received VK_s value. If it is equal to 1461 the expected value, it means that the mutual authentication has 1462 succeeded. The client will be in the "AUTH-SUCCEEDED" status. 1464 If the value is unexpected, it is a fatal communication error. 1466 If a user explicitly requests to log out (via user interfaces), 1467 the client MUST forget the user's password, go to step 5 and 1468 reload the current resource without an authentication header. 1470 Note 1: These transitions MAY be accepted by clients, but 1471 NOT RECOMMENDED for servers to initiate. 1473 Any kind of response (including a normal response) other than those 1474 shown in the above procedure SHOULD be interpreted as a fatal 1475 communication error, and in such cases the clients MUST NOT process 1476 any data (response body and other content-related headers) sent from 1477 the server. However, to handle exceptional error cases, clients MAY 1478 accept a message without an Authentication-Info header, if it is a 1479 Server-Error (5xx) status. The client will be in the 1480 "UNAUTHENTICATED" status in these cases. 1482 The client software SHOULD display the three client status to the 1483 end-user. For an interactive client, however, if a request is a sub- 1484 request for a resource included in another page (e.g., embedded 1485 images, style sheets, frames etc.), its status MAY be omitted from 1486 being shown, and any "AUTH-REQUESTED" statuses MAY be treated in the 1487 same way as an "UNAUTHENTICATED" status. 1489 Figure 5 shows a diagram of the client-side state. 1491 =========== -(11)------------ 1492 NEW REQUEST ( UNAUTHENTICATED ) 1493 =========== ----------------- 1494 | ^ normal 1495 v | response 1496 +(1)-------------------+ NO +(5)----------+ 1497 | The requested URI |--------------------------->| send normal | 1498 | known to be auth'ed? | | request | 1499 +----------------------+ +-------------+ 1500 YES | 401-INIT, 200-Optional-INIT 401-INIT| 1501 | with a different realm 200-Optional-INIT| 1502 | -----------------------------------. | 1503 | / v v 1504 | | -(12)------------ NO +(6)--------+ 1505 | | ( AUTH-REQUESTED )<------| user/pass | 1506 | | ----------------- | known? | 1507 | | +-----------+ 1508 | | |YES 1509 v | v 1510 +(2)--------+ | +(7)--------+ 1511 | session | | | session | NO 1512 NO /| available?| | | available?|\ 1513 / +-----------+ | +-----------+ | 1514 / |YES | |YES | 1515 | | /| | | 1516 | v / | 401- 401- v | 1517 | +(3)--------+ | INIT --(13)---------- INIT +(8)--------+ | 1518 | | send |--+----->/ AUTH-REQUESTED \<-------| send | | 1519 | /| req-VFY-C | | \forget password / | req-VFY-C | | 1520 \/ +-----------+ / ---------------- /+-----------+ | 1521 /\ \ \/ ^ 401-INIT | |401- | 1522 | ------ \/\ 401-STALE | | | STALE / 1523 | \ /\ -----------------+--------------+---. | / 1524 | | / \ | | | | / 1525 | v / | 401- | 401- | v v v 1526 | +(4)--------+ | KEX-S1 +(10)-------+ KEX-S1 | +(9)--------+ 1527 | | send |-|--------->| send |<-------+-| send | 1528 | --| req-KEX-C1| | | req-VFY-C | | | req-KEX-C1| 1529 |/ +-----------+ | +-----------+ | +-----------+ 1530 | |200-VFY-S | 200-VFY-S| ^ 1531 |normal | |200-VFY-S / | 1532 |response | v / ================== 1533 v \ -(14)--------- / USER/PASS INPUTTED 1534 -(11)------------ ------->( AUTH-SUCCEED )<-- ================== 1535 ( UNAUTHENTICATED ) -------------- 1536 ----------------- 1538 Figure 5: State diagram for clients 1540 10. Decision Procedure for Servers 1542 Each server SHOULD have a table of session states. This table need 1543 not be persistent over a long term; it MAY be cleared upon server 1544 restart, reboot, or others. Each entry in the table SHOULD contain 1545 at least the following information: 1547 o The session identifier, the value of the sid parameter. 1549 o The algorithm used. 1551 o The authentication realm. 1553 o The state of the protocol: one of "key exchanging", 1554 "authenticated", "rejected", or "inactive". 1556 o The user name received from the client 1558 o The boolean flag noting whether or not the session is fake. 1560 o When the state is "key exchanging", the values of K_c1 and S_s1. 1562 o When the state is "authenticated", the following information: 1564 * The value of the session secret z 1566 * The largest nc received from the client (largest-nc) 1568 * For each possible nc values between (largest-nc - nc- 1569 window + 1) and max_nc, a flag whether or not a request with 1570 the corresponding nc has been received. 1572 The table MAY contain other information. 1574 Servers SHOULD respond to the client requests according to the 1575 following procedure: 1577 o When the server receives a normal request: 1579 * If the requested resource is not protected by the Mutual 1580 Authentication, send a normal response. 1582 * If the resource is protected by the Mutual Authentication, send 1583 a 401-INIT response. 1585 * If the resource is protected by the optional Mutual 1586 Authentication, send a 200-Optional-INIT response. 1588 o When the server receives a req-KEX-C1 request: 1590 * If the requested resource is not protected by the Mutual 1591 Authentication, send a normal response. 1593 * If the authentication realm specified in the req-KEX-C1 request 1594 is not the expected one, send either a 401-INIT or a 1595 200-Optional-INIT response. 1597 * If the server cannot validate the parameter kc1, send a 1598 401-INIT response. 1600 * If the received user name is either invalid, unknown or 1601 unacceptable, create a new session, mark it a "fake" session, 1602 compute a random value as K_s1, and send a fake 401-KEX-S1 1603 response. (Note: the server SHOULD NOT send a 401-INIT 1604 response in this case, because it will leak the information to 1605 the client that the specified user will not be accepted. 1606 Instead, postpone it to the response for the next req-VFY-C 1607 request.) 1609 * Otherwise, create a new session, compute K_s1 and send a 1610 401-KEX-S1 response. 1612 The created session has the "key exchanging" state. 1614 o When the server receives a req-VFY-C request: 1616 * If the requested resource is not protected by the Mutual 1617 Authentication, send a normal response. 1619 * If the authentication realm specified in the req-VFY-C request 1620 is not the expected one, send either a 401-INIT or a 1621 200-Optional-INIT response. 1623 If none of above holds true, the server will lookup the session 1624 corresponding to the received sid and the authentication realm. 1626 * If the session corresponding to the received sid could not be 1627 found, or it is in the "inactive" state, send a 401-STALE 1628 response. 1630 * If the session is in the "rejected" state, send either a 1631 401-INIT or a 401-STALE message. 1633 * If the session is in the "authenticated" state, and the request 1634 has an nc value that was previously received from the client, 1635 send a 401-STALE message. The session SHOULD be changed to the 1636 "inactive" status. 1638 * If the nc value in the request is larger than the nc-max 1639 parameter sent from the server, or if it is not larger then 1640 (largest-nc - nc-window) (when in "authenticated" status), the 1641 server MAY (but not REQUIRED to) send a 401-STALE message. The 1642 session SHOULD be changed to the "inactive" status if so. 1644 * If the session is a "fake" session, or if the received vkc is 1645 incorrect, then send a 401-INIT response. If the session is in 1646 the "key exchanging" state, it SHOULD be changed to the 1647 "rejected" state; otherwise, it MAY either be changed to the 1648 "rejected" status or kept in the previous state. 1650 * Otherwise, send a 200-VFY-S response. If the session was in 1651 the "key exchanging" state, the session SHOULD be changed to an 1652 "authenticated" state. The maximum nc and nc flags of the 1653 state SHOULD be updated properly. 1655 At any time, the server MAY change any state entries with both the 1656 "rejected" and "authenticated" statuses to the "inactive" status, and 1657 MAY discard any "inactive" states from the table. The entries with 1658 the "key exchanging" status SHOULD be kept unless there is an 1659 emergency situation such as a server reboot or a table capacity 1660 overflow. 1662 11. Authentication Algorithms 1664 Cryptographic authentication algorithms which are used with this 1665 protocol will be defined separately. The algorithm definition MUST 1666 at least provide a definitions for the following functions: 1668 o The server-side authentication credential J, derived from user- 1669 side authentication credential pi. 1671 o Key exchange values K_c1, K_s1 (exchanged on wire) and S_c1, S_s1 1672 (kept secret in each peer). 1674 o Shared secret z, to be computed in both server-side and client 1675 side. 1677 o A hash function H to be used with the protocol. 1679 All algorithm used with this protocol SHOULD provide secure mutual 1680 authentication between client and servers, and generate a 1681 cryptographically strong shared secret value z, equivalently strong 1682 to or stronger than the hash function H. If any passwords (or pass- 1683 phrases or any equivalents, i.e. weak secrets) are involved, these 1684 SHOULD NOT be guessable from any data transmitted in the protocol, 1685 even if an attacker (either an eavesdropper or an active server) 1686 knows the possible thoroughly-searchable candidate list of the 1687 passwords. Furthermore, if possible, the function for deriving 1688 server-side authentication credential J is RECOMMENDED to be one-way 1689 so that pi should not be easily computed from J(pi). 1691 11.1. Support Functions and Notations 1693 In this section we define several support functions and notations to 1694 be shared by several algorithm definitions: 1696 The integers in the specification are in decimal, or in hexadecimal 1697 when prefixed with "0x". 1699 The function octet(c) generates a single octet string whose code 1700 value is equal to c. The operator |, when applied to octet strings, 1701 denotes the concatenation of two operands. 1703 The function VI encodes natural numbers into octet strings in the 1704 following manner: numbers are represented in big-endian radix-128 1705 string, where each digit is represented by a octet within 0x80-0xff 1706 except the last digit represented by a octet within 0x00-0x7f. The 1707 first octet MUST NOT be 0x80. For example, VI(i) = octet(i) for i < 1708 128, and VI(i) = octet(0x80 + (i >> 7)) | octet(i & 127) for 128 <= i 1709 < 16384. This encoding is the same as the one used for the 1710 subcomponents of object identifiers in the ASN.1 encoding 1711 [ITU.X690.1994], and available as a "w" conversion in the pack 1712 function of several scripting languages. 1714 The function VS encodes a variable-length octet string into a 1715 uniquely-decoded, self-delimited octet string, as in the following 1716 manner: 1718 VS(s) = VI(length(s)) | s 1720 where length(s) is a number of octets (not characters) in s. 1722 Some examples: 1724 VI(0) = "\000" (in C string notation) 1726 VI(100) = "d" 1728 VI(10000) = "\316\020" 1729 VI(1000000) = "\275\204@" 1731 VS("") = "\000" 1733 VS("Tea") = "\003Tea" 1735 VS("Caf" [in UTF-8]) = "\005Caf\303\251" 1737 VS([10000 "a"s]) = "\316\020aaaaa..." (10002 octets) 1739 [Editorial note: Unlike the colon-separated notion used in the Basic/ 1740 Digest HTTP authentication scheme, the string generated by a 1741 concatenation of the VS-encoded strings will be unique, regardless of 1742 the characters included in the strings to be encoded.] 1744 The function OCTETS converts an integer into the corresponding radix- 1745 256 big-endian octet string having its natural length: See 1746 Section 3.1.3 for the definition of "natural length". 1748 11.2. Default Functions for Algorithms 1750 The functions defined in this section are common default functions 1751 among authentication algorithms. 1753 The client-side password-based string pi used by this authentication 1754 is derived in the following manner: 1756 pi = H(VS(algorithm) | VS(auth-domain) | VS(realm) | VS(username) | 1757 VS(ph(password))). 1759 The values of algorithm, realm, and auth-domain are taken from the 1760 values contained in the 401-INIT (or 200-Optional-INIT, hereafter 1761 implied) message. When pi is used in the context of an octet string, 1762 it SHALL have the natural length derived from the size of the output 1763 of function H (e.g. 32 octets for SHA-256). The function ph is 1764 determined by the value of the pwd-hash parameter given in a 401-INIT 1765 message. If the password comes from a user input, it SHOULD first be 1766 prepared using SASLprep [RFC4013]. Then, the password SHALL be 1767 encoded as a UTF-8 string before passed to ph. 1769 The values VK_c and VK_s are derived by the following equation. 1771 VK_c = H(octet(4) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VI(nc) 1772 | VS(v)) 1774 VK_s = H(octet(3) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VI(nc) 1775 | VS(v)) 1776 Specifications for cryptographic algorithms used with this framework 1777 MAY override the functions pi, VK_c, and VK_s defined above. In such 1778 cases implementations MUST use the ones defined with such algorithm 1779 specifications. 1781 12. Application Channel Binding 1783 Applications and upper-layer communication protocols may need 1784 authentication binding to the HTTP-layer authenticated user. Such 1785 applications MAY use the following values as a standard shared 1786 secret. 1788 These values are parameterized with an optional octet string (t) 1789 which may be arbitrarily chosen by each applications or protocols. 1790 If there is no appropriate value to be specified, use a null string 1791 for t. 1793 For applications requiring binding to either an authenticated user or 1794 a shared-key session (to ensure that the requesting client is 1795 certainly authenticated), the following value b_1 MAY be used. 1797 b_1 = OCTETS(H(OCTETS(H(octet(6) | OCTETS(K_c1) | OCTETS(K_s1) | 1798 OCTETS(z) | VI(0) | VS(v))) | VS(t))). 1800 For applications requiring binding to a specific request (to ensure 1801 that the payload data is generated for the exact HTTP request), the 1802 following value b_2 MAY be used. 1804 b_2 = OCTETS(H(OCTETS(H(octet(7) | OCTETS(K_c1) | OCTETS(K_s1) | 1805 OCTETS(z) | VI(nc) | VS(v))) | VS(t))). 1807 Note: Channel bindings to lower-layer transports (TCP and TLS) are 1808 defined in Section 7. 1810 13. Application for Proxy Authentication 1812 The authentication scheme defined by the previous sections can be 1813 applied m.m. for proxy authentications. In such cases, the following 1814 alterations MUST be applied: 1816 o The 407 status is to be sent and recognized for places where the 1817 401 status is used, 1819 o Proxy-Authenticate: header is to be used for places where WWW- 1820 Authenticate: is used, 1822 o Proxy-Authorization: header is to be used for places where 1823 Authorization: is used, 1825 o Proxy-Authentication-Info: header is to be used for places where 1826 Authentication-Info: is used, 1828 o The auth-domain parameter is fixed to the host-name of the proxy, 1829 which means to cover all requests processed through the specific 1830 proxy, 1832 o The limitation for the paths contained in the path parameter of 1833 401-KEX-S1 messages is disregarded, 1835 o The omission of the path parameter of 401-KEX-S1 messages means 1836 that the authentication realm will potentially cover all requests 1837 processed by the proxy, 1839 o The scheme, host name and the port of the proxy is used for 1840 validation tokens, and 1842 o Authentication extension in [I-D.oiwa-http-auth-extension] is not 1843 applicable. 1845 The requirements for client software to display the authentication 1846 status to the end-user is also not applicable for proxy 1847 authentication. If the client software supports both end-to-end and 1848 proxy authentication using this protocol, it SHOULD be careful that 1849 the authentication status of the proxy communication will never be 1850 confused by users with authentication statuses of the end-to-end 1851 resource authentications. 1853 14. Methods to Extend This Protocol 1855 If a private extension to this protocol is implemented, it MUST use 1856 the extension-tokens defined in Section 3 to avoid conflicts with 1857 this protocol and other extensions. (standardized or being- 1858 standardizing extensions MAY use either bare-tokens or extension- 1859 tokens.) 1861 Specifications defining authentication algorithms MAY use other 1862 representations for the parameters "kc1", "ks1", "vkc", and "vks", 1863 replace those parameter names, and/or add parameters to the messages 1864 containing those parameters in supplemental specifications, provided 1865 that syntactic and semantic requirements in Section 3, 1866 [I-D.ietf-httpbis-p1-messaging] and [I-D.ietf-httpbis-p7-auth] are 1867 satisfied. Any parameters starting with "kc", "ks", "vkc" or "vks" 1868 and followed by decimal natural numbers (e.g. kc2, ks0, vkc1, vks3 1869 etc.) are reserved for this purpose. If those specifications use 1870 names other than those mentioned above, it is RECOMMENDED to use 1871 extension-tokens to avoid any parameter name conflict with the future 1872 extension of this protocol. 1874 Extension-tokens MAY be freely used for any non-standard, private, 1875 and/or experimental uses for those parameters provided that the 1876 domain part in the token is appropriately used. 1878 15. IANA Considerations 1880 When bare-tokens are used for the authentication-algorithm, pwd-hash, 1881 and validation parameters MUST be allocated by IANA. To acquire 1882 registered tokens, a specification for the use of such tokens MUST be 1883 available as an RFC, as outlined in [RFC5226]. 1885 Note: More formal declarations will be added in the future drafts to 1886 meet the RFC 5226 requirements. 1888 16. Security Considerations 1890 16.1. Security Properties 1892 o The protocol is secure against passive eavesdropping and replay 1893 attacks. However, the protocol relies on transport security 1894 including DNS integrity for data secrecy and integrity. HTTP/TLS 1895 SHOULD be used where transport security is not assured and/or data 1896 secrecy is important. 1898 o When used with HTTP/TLS, if TLS server certificates are reliably 1899 verified, the protocol provides true protection against active 1900 man-in-the-middle attacks. 1902 o Even if the server certificate is not used or is unreliable, the 1903 protocol provides protection against active man-in-the-middle 1904 attacks for each HTTP request/response pair. However, in such 1905 cases, JavaScript or similar scripting facilities can be used to 1906 affect the Mutually-authenticated contents from other contents not 1907 protected by this authentication mechanism. This is the reason 1908 why this protocol requires that valid TLS server certificates MUST 1909 be presented (Section 7). 1911 16.2. Denial-of-service Attacks to Servers 1913 The protocol requires a server-side table of active sessions, which 1914 may become a critical point of the server resource consumptions. For 1915 proper operation, the protocol requires that at least one key 1916 verification request is processed for each session identifier. After 1917 that, servers MAY discard sessions internally at any time, without 1918 causing any operational problems to clients. Clients will silently 1919 reestablishes a new session then. 1921 However, if a malicious client sends too many requests of key 1922 exchanges (req-KEX-C1 messages) only, resource starvation might 1923 occur. In such critical situations, servers MAY discard any kind of 1924 existing sessions regardless of these statuses. One way to mitigate 1925 such attacks are that servers MAY have a number and a time limits for 1926 unverified pending key exchange requests (in the "wa received" 1927 status). 1929 This is a common weakness of authentication protocols with almost any 1930 kind of negotiations or states, including Digest authentication 1931 method and most Cookie-based authentication implementations. 1932 However, regarding the resource consumption, a situation of the 1933 mutual authentication method is a slightly better than the Digest, 1934 because HTTP requests without any kind of authentication requests 1935 will not generate any kind of sessions. Session identifiers are only 1936 generated after a client starts a key negotiation. It means that 1937 simple clients such as web crawlers will not accidentally consume 1938 server-side resources for session managements. 1940 16.3. Implementation Considerations 1942 o To securely implement the protocol, the Authentication-Info 1943 headers in the 200-VFY-S messages MUST always be validated by the 1944 client. If the validation fails, the client MUST NOT process any 1945 content sent with the message, including other headers and the 1946 body part. Non-compliance to this requirement will allow phishing 1947 attacks. 1949 o The authentication status on the client-side SHOULD be visible to 1950 the users of the client. In addition, the method for asking for 1951 the user's name and passwords SHOULD be carefully designed so that 1952 (1) the user can easily distinguish the request from this 1953 authentication method from any other authentication methods such 1954 as Basic and Digest methods, and (2) the Web contents cannot 1955 imitate the user-interfaces for this protocol. 1957 An informational memo regarding user-interface considerations and 1958 recommendations for implementing this protocol will be separately 1959 published. 1961 o For HTTP/TLS communications, when a web form is submitted from 1962 Mutually-authenticated pages with the "tls-cert" validation method 1963 to a URI that is protected by the same realm (so indicated by the 1964 path parameter), if the server certificate has been changed since 1965 the pages were received, the peer is RECOMMENDED to be revalidated 1966 using a req-KEX-C1 message with an "Expect: 100-continue" header. 1967 The same applies when the page is received with the "tls-key" 1968 validation method, and when the TLS session has expired. 1970 o Server-side storages of user passwords are advised to contain the 1971 values encrypted by one-way function J(pi), instead of the real 1972 passwords, those hashed by ph, or pi. 1974 16.4. Usage Considerations 1976 o The user-names inputted by a user may be sent automatically to any 1977 servers sharing the same auth-domain. This means that when host- 1978 type auth-domain is used for authentication on an HTTPS site, and 1979 when an HTTP server on the same host requests Mutual 1980 authentication within the same realm, the client will send the 1981 user-name in a clear text. If user-names have to be kept secret 1982 against eavesdropping, the server must use full-scheme-type auth- 1983 domain parameter. Contrarily, passwords are not exposed to 1984 eavesdroppers even on HTTP requests. 1986 o The "pwd-hash" parameter is only provided for backward 1987 compatibility of password databases. The use of "none" function 1988 is the most secure choice and is RECOMMENDED. If values other 1989 than "none" are used, you MUST ensure that the hash values of the 1990 passwords were not exposed to the public. Note that hashed 1991 password databases for plain-text authentications are usually not 1992 considered secret. 1994 o If the server provides several ways for storing server-side 1995 password secrets into the password database, it is advised to 1996 store the values encrypted by using the one-way function J(pi), 1997 instead of the real passwords, those hashed by ph, or pi. 1999 17. Notice on Intellectual Properties 2001 The National Institute of Advanced Industrial Science and Technology 2002 (AIST) and Yahoo! Japan, Inc. has jointly submitted a patent 2003 application on the protocol proposed in this documentation to the 2004 Patent Office of Japan. The patent is intended to be open to any 2005 implementors of this protocol and its variants under non-exclusive 2006 royalty-free manner. For the details of the patent application and 2007 its status, please contact the author of this document. 2009 The elliptic-curve based authentication algorithms might involve 2010 several existing third-party patents. The authors of the document 2011 take no position regarding the validity or scope of such patents, and 2012 other patents as well. 2014 18. References 2016 18.1. Normative References 2018 [I-D.ietf-httpbis-p1-messaging] 2019 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 2020 1: URIs, Connections, and Message Parsing", 2021 draft-ietf-httpbis-p1-messaging-19 (work in progress), 2022 March 2012. 2024 [I-D.ietf-httpbis-p7-auth] 2025 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 2026 7: Authentication", draft-ietf-httpbis-p7-auth-19 (work in 2027 progress), March 2012. 2029 [I-D.oiwa-http-auth-extension] 2030 Oiwa, Y., Watanabe, H., Takagi, H., Kihara, B., Hayashi, 2031 T., and Y. Ioku, "HTTP Authentication Extensions for 2032 Interactive Clients", draft-oiwa-httpbis-auth-extension-00 2033 (work in progress), June 2012. 2035 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2036 Requirement Levels", BCP 14, RFC 2119, March 1997. 2038 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2039 10646", STD 63, RFC 3629, November 2003. 2041 [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names 2042 and Passwords", RFC 4013, February 2005. 2044 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2045 Encodings", RFC 4648, October 2006. 2047 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2048 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2050 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2051 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2053 18.2. Informative References 2055 [I-D.ietf-oauth-v2] 2056 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 2057 2.0 Authorization Framework", draft-ietf-oauth-v2-26 (work 2058 in progress), May 2012. 2060 [I-D.ietf-precis-framework] 2061 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 2062 Preparation and Comparison of Internationalized Strings in 2063 Application Protocols", draft-ietf-precis-framework-03 2064 (work in progress), May 2012. 2066 [I-D.oiwa-http-mutualauth-algo] 2067 Oiwa, Y., Watanabe, H., Takagi, H., Kihara, B., Hayashi, 2068 T., and Y. Ioku, "Mutual Authentication Protocol for HTTP: 2069 KAM3-based Cryptographic Algorithms", 2070 draft-oiwa-http-mutualauth-algo-02 (work in progress), 2071 May 2012. 2073 [ISO.10646-1.1993] 2074 International Organization for Standardization, 2075 "Information Technology - Universal Multiple-octet coded 2076 Character Set (UCS) - Part 1: Architecture and Basic 2077 Multilingual Plane", ISO Standard 10646-1, May 1993. 2079 [ITU.X690.1994] 2080 International Telecommunications Union, "Information 2081 Technology - ASN.1 encoding rules: Specification of Basic 2082 Encoding Rules (BER), Canonical Encoding Rules (CER) and 2083 Distinguished Encoding Rules (DER)", ITU-T Recommendation 2084 X.690, 1994. 2086 [OASIS.saml-core-2.0-os] 2087 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 2088 "Assertions and Protocol for the OASIS Security Assertion 2089 Markup Language (SAML) V2.0", OASIS Standard saml-core- 2090 2.0-os, March 2005. 2092 [OIDF.Connect.Standard] 2093 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 2094 Mortimore, C., and E. Jay, "OpenID Connect Standard 1.0 - 2095 draft 10", May 2012. 2097 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2098 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2099 Authentication: Basic and Digest Access Authentication", 2100 RFC 2617, June 1999. 2102 [RFC2743] Linn, J., "Generic Security Service Application Program 2103 Interface Version 2, Update 1", RFC 2743, January 2000. 2105 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2107 [RFC3961] Raeburn, K., "Encryption and Checksum Specifications for 2108 Kerberos 5", RFC 3961, February 2005. 2110 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2111 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2112 May 2008. 2114 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2115 Housley, R., and W. Polk, "Internet X.509 Public Key 2116 Infrastructure Certificate and Certificate Revocation List 2117 (CRL) Profile", RFC 5280, May 2008. 2119 [RFC5890] Klensin, J., "Internationalized Domain Names for 2120 Applications (IDNA): Definitions and Document Framework", 2121 RFC 5890, August 2010. 2123 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 2124 for TLS", RFC 5929, July 2010. 2126 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2127 April 2011. 2129 Appendix A. (Informative) Draft Remarks from Authors 2131 The following items are currently under consideration for future 2132 revisions by the authors. 2134 o Whether to keep TLS-key validation or not. 2136 o When keeping tls-key validation, whether to use "TLS channel 2137 binding" [RFC5929] for "tls-key" verification (Section 7). Note 2138 that existing TLS implementations should be considered to 2139 determine this. 2141 o Adopt [I-D.ietf-precis-framework] for replacing SASLprep 2142 reference. Especially, use NFC canonicalization instead of NFKC. 2144 o Adding test vectors for ensuring implementation correctness. 2146 o Possibly adding a method for servers to detect availability of 2147 Mutual authentication on client-side. 2149 o Possible support for optional key renewal and cross-site federated 2150 authentication. 2152 Appendix B. (Informative) Draft Change Log 2154 B.1. Changes in HttpBis Revision 00 2156 Note: the token for the header parameter "version" is NOT changed 2157 from "-draft11", because the protocol semantics has not been changed 2158 in this revision. 2160 None. 2162 B.2. Changes in Revision 12 2164 o Added a reason "authz-failed". 2166 B.3. Changes in Revision 11 2168 o Message syntax definition reverted to pre-07 style as httpbis-p1 2169 and p7 now defines a precise rule for parameter value parsing. 2171 o Replaced "stale" parameter with more infomative/extensive "reason" 2172 parameter in 401-INIT and 401-STALE. 2174 o Reserved "rekey-sid" and "rekey-method" parameters for future 2175 extensions. 2177 o Added descriptions for replacing/non-replacing existing 2178 technologies. 2180 B.4. Changes in Revision 10 2182 o The authentication extension parts (non-mandatory authentication 2183 and authentication controls) are separated to yet another draft. 2185 o The default auth-domain parameter is changed to the full scheme- 2186 host-port syntax, which is consistent with usual HTTP 2187 authentication framework behavior. 2189 o Provision for application channel binding is added. 2191 o Provision for proxy access authentication is added. 2193 o Bug fix: syntax specification of sid parameter was wrong: it was 2194 inconsistent with the type specified in the main text (the bug 2195 introduced in -07 draft). 2197 o Terminologies for headers are changed to be in harmony with 2198 httpbis drafts (e.g. field to parameter). 2200 o Syntax definitions are changed to use HTTP-extended ABNF syntax, 2201 and only the header values are shown for header syntax, in harmony 2202 with httpbis drafts. 2204 o Names of parameters and corresponding mathematical values are now 2205 renamed to more informative ones. The following list shows 2206 correspondence between the new and the old names. 2208 +------------+----------+-------------------------------------------+ 2209 | new name | old name | description | 2210 +------------+----------+-------------------------------------------+ 2211 | S_c1, S_s1 | s_a, s_b | client/server-side secret randoms | 2212 | K_c1, K_s1 | w_a, w_b | client/server-side exchanged key | 2213 | | | components | 2214 | kc1, ks1 | wa, wb | parameter names for those | 2215 | VK_c, VK_s | o_a, o_b | client/server-side key verifiers | 2216 | vkc, vks | oa, ob | parameter names for those | 2217 | z | z | session secrets | 2218 +------------+----------+-------------------------------------------+ 2220 B.5. Changes in Revision 09 2222 o The (default) cryptographic algorithms are separated to another 2223 draft. 2225 o Names of the messages are changed to more informative ones than 2226 before. The following is the correspondence table of those names: 2228 +-------------------+-----------------+-----------------------------+ 2229 | new name | old name | description | 2230 +-------------------+-----------------+-----------------------------+ 2231 | 401-INIT | 401-B0 | initial response | 2232 | 401-STALE | 401-B0-stale | session key expired | 2233 | req-KEX-C1 | req-A1 | client->server key exchange | 2234 | 401-KEX-S1 | 401-B1 | server->client key exchange | 2235 | req-VFY-C | req-A3 | client->server auth. | 2236 | | | verification | 2237 | 200-VFY-S | 200-B4 | server->client auth. | 2238 | | | verification | 2239 | 200-Optional-INIT | 200-Optional-B0 | initial with non-mandatory | 2240 | | | authentication | 2241 +-------------------+-----------------+-----------------------------+ 2243 B.6. Changes in Revision 08 2245 o The English text has been revised. 2247 B.7. Changes in Revision 07 2249 o Adapt to httpbis HTTP/1.1 drafts: 2251 * Changed definition of extensive-token. 2253 * LWSP continuation-line (%0D.0A.20) deprecated. 2255 o To simplify the whole spec, the type of nonce-counter related 2256 parameters are change from hex-integer to integer. 2258 o Algorithm tokens are renamed to include names of hash algorithms. 2260 o Clarified the session management, added details of server-side 2261 protocol decisions. 2263 o The whole draft was reorganized; introduction and overview has 2264 been rewritten. 2266 B.8. Changes in Revision 06 2268 o Integrated Optional Mutual Authentication to the main part. 2270 o Clarified the decision procedure for message recognitions. 2272 o Clarified that a new authentication request for any sub-requests 2273 in interactive clients may be silently discarded. 2275 o Typos and confusing phrases are fixed. 2277 o Several "future considerations" are added. 2279 B.9. Changes in Revision 05 2281 o A new parameter called "version" is added for supporting future 2282 incompatible changes with a single implementation. In the (first) 2283 final specification its value will be changed to 1. 2285 o A new header "Authentication-Control" is added for precise control 2286 of application-level authentication behavior. 2288 B.10. Changes in Revision 04 2290 o Changed text of patent licenses: the phrase "once the protocol is 2291 accepted as an Internet standard" is removed so that the sentence 2292 also covers the draft versions of this protocol. 2294 o The "tls-key" verification is now OPTIONAL. 2296 o Several description fixes and clarifications. 2298 B.11. Changes in Revision 03 2300 o Wildcard domain specifications (e.g. "*.example.com") are allowed 2301 for auth-domain parameters (Section 4.1). 2303 o Specification of the "tls-cert" verification is updated 2304 (incompatible change). 2306 o State transitions fixed. 2308 o Requirements for servers concerning w_a values are clarified. 2310 o RFC references are updated. 2312 B.12. Changes in Revision 02 2314 o Auth-realm is extended to allow full-scheme type. 2316 o A decision diagram for clients and decision procedures for servers 2317 are added. 2319 o 401-B1 and req-A3 messages are changed to contain authentication 2320 realm information. 2322 o Bugs on equations for o_A and o_B are fixed. 2324 o Detailed equations for the entire algorithm are included. 2326 o Elliptic-curve algorithms are updated. 2328 o Several clarifications and other minor updates. 2330 B.13. Changes in Revision 01 2332 o Several texts are rewritten for clarification. 2334 o Added several security consideration clauses. 2336 Authors' Addresses 2338 Yutaka Oiwa 2339 National Institute of Advanced Industrial Science and Technology 2340 Research Institute for Secure Systems 2341 Tsukuba Central 2 2342 1-1-1 Umezono 2343 Tsukuba-shi, Ibaraki 2344 JP 2346 Email: mutual-auth-contact-ml@aist.go.jp 2348 Hajime Watanabe 2349 National Institute of Advanced Industrial Science and Technology 2351 Hiromitsu Takagi 2352 National Institute of Advanced Industrial Science and Technology 2354 Boku Kihara 2355 Lepidum Co. Ltd. 2356 #602, Village Sasazuka 3 2357 1-30-3 Sasazuka 2358 Shibuya-ku, Tokyo 2359 JP 2361 Tatsuya Hayashi 2362 Lepidum Co. Ltd. 2364 Yuichi Ioku 2365 Yahoo! Japan, Inc. 2366 Midtown Tower 2367 9-7-1 Akasaka 2368 Minato-ku, Tokyo 2369 JP