draft-ietf-httpauth-mutual-11.txt   rfc8120.txt 
HTTPAUTH Working Group Y. Oiwa Internet Engineering Task Force (IETF) Y. Oiwa
Internet-Draft H. Watanabe Request for Comments: 8120 H. Watanabe
Intended status: Experimental H. Takagi Category: Experimental H. Takagi
Expires: May 18, 2017 ITRI, AIST ISSN: 2070-1721 ITRI, AIST
K. Maeda K. Maeda
Individual Contributor
T. Hayashi T. Hayashi
Lepidum Lepidum
Y. Ioku Y. Ioku
Individual Individual Contributor
November 14, 2016 April 2017
Mutual Authentication Protocol for HTTP Mutual Authentication Protocol for HTTP
draft-ietf-httpauth-mutual-11
Abstract Abstract
This document specifies a mutual authentication scheme for the This document specifies an authentication scheme for the Hypertext
Hypertext Transfer Protocol (HTTP). This scheme provides true mutual Transfer Protocol (HTTP) that is referred to as either the Mutual
authentication between an HTTP client and an HTTP server using authentication scheme or the Mutual authentication protocol. This
password-based authentication. Unlike the Basic and Digest scheme provides true mutual authentication between an HTTP client and
authentication schemes, the Mutual authentication scheme specified in an HTTP server using password-based authentication. Unlike the Basic
this document assures the user that the server truly knows the user's and Digest authentication schemes, the Mutual authentication scheme
encrypted password. specified in this document assures the user that the server truly
knows the user's encrypted password.
Status of this Memo
This Internet-Draft is submitted in full conformance with the Status of This Memo
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering This document is not an Internet Standards Track specification; it is
Task Force (IETF). Note that other groups may also distribute published for examination, experimental implementation, and
working documents as Internet-Drafts. The list of current Internet- evaluation.
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document defines an Experimental Protocol for the Internet
and may be updated, replaced, or obsoleted by other documents at any community. This document is a product of the Internet Engineering
time. It is inappropriate to use Internet-Drafts as reference Task Force (IETF). It represents the consensus of the IETF
material or to cite them other than as "work in progress." community. It has received public review and has been approved for
publication by the Internet Engineering Steering Group (IESG). Not
all documents approved by the IESG are a candidate for any level of
Internet Standard; see Section 2 of RFC 7841.
This Internet-Draft will expire on May 18, 2017. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc8120.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction ....................................................3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Terminology ................................................5
1.2. Document Structure and Related Documents . . . . . . . . . 6 1.2. Document Structure and Related Documents ...................6
2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 2. Protocol Overview ...............................................6
2.1. Messages Overview . . . . . . . . . . . . . . . . . . . . 7 2.1. Messages ...................................................7
2.2. Typical Flows of the Protocol . . . . . . . . . . . . . . 8 2.2. Typical Flows of the Protocol ..............................8
2.3. Alternative Flows . . . . . . . . . . . . . . . . . . . . 10 2.3. Alternative Flows .........................................10
3. Message Syntax . . . . . . . . . . . . . . . . . . . . . . . . 11 3. Message Syntax .................................................12
3.1. Non-ASCII extended header parameters . . . . . . . . . . . 12 3.1. Non-ASCII Extended Header Parameters ......................12
3.2. Values . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2. Values ....................................................13
3.2.1. Tokens . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2.1. Tokens .............................................13
3.2.2. Strings . . . . . . . . . . . . . . . . . . . . . . . 14 3.2.2. Strings ............................................14
3.2.3. Numbers . . . . . . . . . . . . . . . . . . . . . . . 14 3.2.3. Numbers ............................................14
4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4. Messages .......................................................15
4.1. 401-INIT and 401-STALE . . . . . . . . . . . . . . . . . . 16 4.1. 401-INIT and 401-STALE ....................................16
4.2. req-KEX-C1 . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2. req-KEX-C1 ................................................19
4.3. 401-KEX-S1 . . . . . . . . . . . . . . . . . . . . . . . . 19 4.3. 401-KEX-S1 ................................................19
4.4. req-VFY-C . . . . . . . . . . . . . . . . . . . . . . . . 20 4.4. req-VFY-C .................................................20
4.5. 200-VFY-S . . . . . . . . . . . . . . . . . . . . . . . . 20 4.5. 200-VFY-S .................................................21
5. Authentication Realms . . . . . . . . . . . . . . . . . . . . 21 5. Authentication Realms ..........................................21
5.1. Resolving Ambiguities . . . . . . . . . . . . . . . . . . 22 5.1. Resolving Ambiguities .....................................23
6. Session Management . . . . . . . . . . . . . . . . . . . . . . 23 6. Session Management .............................................24
7. Host Validation Methods . . . . . . . . . . . . . . . . . . . 25 7. Host Validation Methods ........................................26
7.1. Applicability notes . . . . . . . . . . . . . . . . . . . 26 7.1. Applicability Notes .......................................27
7.2. Notes on tls-unique . . . . . . . . . . . . . . . . . . . 27 7.2. Notes on "tls-unique" .....................................28
8. Authentication Extensions . . . . . . . . . . . . . . . . . . 27 8. Authentication Extensions ......................................28
9. String Preparation . . . . . . . . . . . . . . . . . . . . . . 28 9. String Preparation .............................................29
10. Decision Procedure for Clients . . . . . . . . . . . . . . . . 28 10. Decision Procedure for Clients ................................29
10.1. General Principles and Requirements . . . . . . . . . . . 28 10.1. General Principles and Requirements ......................29
10.2. State machine for the client (informative) . . . . . . . . 30 10.2. State Machine for the Client (Informative) ...............31
11. Decision Procedure for Servers . . . . . . . . . . . . . . . . 35
12. Authentication Algorithms . . . . . . . . . . . . . . . . . . 37 11. Decision Procedure for Servers ................................36
12.1. Support Functions and Notations . . . . . . . . . . . . . 38 12. Authentication Algorithms .....................................39
12.2. Default Functions for Algorithms . . . . . . . . . . . . . 39 12.1. Support Functions and Notations ..........................39
13. Application Channel Binding . . . . . . . . . . . . . . . . . 40 12.2. Default Functions for Algorithms .........................41
14. Application for Proxy Authentication . . . . . . . . . . . . . 41 13. Application Channel Binding ...................................42
15. Methods to Extend This Protocol . . . . . . . . . . . . . . . 42 14. Application for Proxy Authentication ..........................42
16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 15. Methods to Extend This Protocol ...............................43
16.1. Registry for Authentication Algorithms . . . . . . . . . . 42 16. IANA Considerations ...........................................44
16.2. Registry for Validation Methods . . . . . . . . . . . . . 43 16.1. Addition to HTTP Authentication Schemes Registry .........44
17. Security Considerations . . . . . . . . . . . . . . . . . . . 44 16.2. Registry for Authentication Algorithms ...................44
17.1. Security Properties . . . . . . . . . . . . . . . . . . . 44 16.3. Registry for Validation Methods ..........................45
17.2. Secrecy of Credentials . . . . . . . . . . . . . . . . . . 44 17. Security Considerations .......................................46
17.3. Denial-of-service Attacks to Servers . . . . . . . . . . . 45 17.1. Security Properties ......................................46
17.3.1. On-line Active Password Attacks . . . . . . . . . . . 45 17.2. Secrecy of Credentials ...................................46
17.4. Communicating the status of mutual authentication with 17.3. Denial-of-Service Attacks on Servers .....................47
users . . . . . . . . . . . . . . . . . . . . . . . . . . 45 17.3.1. Online Active Password Attacks ....................47
17.5. Implementation Considerations . . . . . . . . . . . . . . 46 17.4. Communicating the Status of Mutual Authentication
17.6. Usage Considerations . . . . . . . . . . . . . . . . . . . 47 with Users ...............................................48
18. References . . . . . . . . . . . . . . . . . . . . . . . . . . 47 17.5. Implementation Considerations ............................48
18.1. Normative References . . . . . . . . . . . . . . . . . . . 47 17.6. Usage Considerations .....................................49
18.2. Informative References . . . . . . . . . . . . . . . . . . 48 18. References ....................................................49
Appendix A. (Informative) Draft Change Log . . . . . . . . . . . 50 18.1. Normative References .....................................49
A.1. Changes in Httpauth WG Revision 11 . . . . . . . . . . . . 50 18.2. Informative References ...................................51
A.2. Changes in Httpauth WG Revision 10 . . . . . . . . . . . . 50 Authors' Addresses ................................................53
A.3. Changes in Httpauth WG Revision 09 . . . . . . . . . . . . 50
A.4. Changes in Httpauth WG Revision 08 . . . . . . . . . . . . 50
A.5. Changes in Httpauth WG Revision 07 . . . . . . . . . . . . 51
A.6. Changes in Httpauth WG Revision 06 . . . . . . . . . . . . 51
A.7. Changes in Httpauth WG Revision 05 . . . . . . . . . . . . 51
A.8. Changes in Httpauth WG Revision 04 . . . . . . . . . . . . 51
A.9. Changes in Httpauth WG Revision 03 . . . . . . . . . . . . 51
A.10. Changes in Httpauth WG Revision 02 . . . . . . . . . . . . 51
A.11. Changes in Httpauth WG Revision 01 . . . . . . . . . . . . 52
A.12. Changes in Httpauth Revision 00 . . . . . . . . . . . . . 52
A.13. Changes in HttpBis Revision 00 . . . . . . . . . . . . . . 52
A.14. Changes in Revision 12 . . . . . . . . . . . . . . . . . . 52
A.15. Changes in Revision 11 . . . . . . . . . . . . . . . . . . 52
A.16. Changes in Revision 10 . . . . . . . . . . . . . . . . . . 53
A.17. Changes in Revision 09 . . . . . . . . . . . . . . . . . . 54
A.18. Changes in Revision 08 . . . . . . . . . . . . . . . . . . 54
A.19. Changes in Revision 07 . . . . . . . . . . . . . . . . . . 54
A.20. Changes in Revision 06 . . . . . . . . . . . . . . . . . . 55
A.21. Changes in Revision 05 . . . . . . . . . . . . . . . . . . 55
A.22. Changes in Revision 04 . . . . . . . . . . . . . . . . . . 55
A.23. Changes in Revision 03 . . . . . . . . . . . . . . . . . . 55
A.24. Changes in Revision 02 . . . . . . . . . . . . . . . . . . 56
A.25. Changes in Revision 01 . . . . . . . . . . . . . . . . . . 56
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56
1. Introduction 1. Introduction
This document specifies a mutual authentication scheme for Hypertext This document specifies an authentication scheme for the Hypertext
Transfer Protocol (HTTP). The scheme, called "Mutual Authentication Transfer Protocol (HTTP) that is referred to as either the Mutual
Protocol" in this document, provides true mutual authentication authentication scheme or the Mutual authentication protocol. This
between an HTTP client and an HTTP server, using just a simple scheme provides true mutual authentication between an HTTP client and
password as a credential. an HTTP server using just a simple password as a credential.
Password-stealing attacks are one of most critical threats for Web Password-stealing attacks are one of the most critical threats for
systems. For a long time, plain-text password authentications (Basic Web systems. Plain-text password authentication techniques (Basic
and Web form-based) are widely used (and are in use now). When these authentication and Web-form-based authentication) have been widely
are used with plain HTTP protocols, it is trivially easy for used for a long time. When these techniques are used with plain HTTP
attackers to sniff the password credentials on the wire. protocols, it is trivially easy for attackers to sniff the password
credentials on the wire.
Digest authentication scheme [RFC7616] uses a SHA-2 (formerly SHA-1 The Digest authentication scheme [RFC7616] uses SHA-256 and
and MD5) hash algorithms to hide the raw user password from the SHA-512/256 (formerly SHA-1 and MD5) hash algorithms to hide the raw
sniffing. However, if the number of possible candidates of users' user password from network sniffers. However, if the number of
password is not enough, recent powerful computers can compute possible candidate users' passwords is not enough, newer and more
possible hash values for billions of password candidates, and compare powerful computers can compute possible hash values for billions of
these with the sniffed values to find out the correct password. This password candidates and compare these with the sniffed values to find
kind of attack is called "offline password dictionary attacks"; out the correct password. This kind of attack is called an offline
recently, the size of possible search space by computers is quite password dictionary attack; the search capacity of these newer
competing with possibility of user's memorable passwords, threatening computers reduces the effectiveness of users' memorable passwords,
the effectiveness of such hash-based password protections. thereby threatening the effectiveness of such hash-based password
protections.
TLS [RFC5246] provides a strong cryptographic protection against the Transport Layer Security (TLS) [RFC5246] provides strong
network-based sniffing of passwords and other communication contents. cryptographic protection against the network-based sniffing of
If TLS is correctly used by both server operators and client users, passwords and other communication contents. If TLS is correctly used
passwords and other credentials will not be available for any outside by both server operators and client users, passwords and other
attackers. However, there is a pit-hole in the TLS deployment on the credentials will not be available to any outside attackers. However,
Web systems; if the users are forged into a "wrong website" by some there is a pitfall related to TLS deployment on Web systems: if the
kind of social attacks and tridked to perform authentication on that users are fraudulently routed to a "wrong Website" via some kind of
site, the credentials will be sent to the attacker's server and social engineering attack (e.g., phishing) and tricked into
trivially leaked. Such attacks are called "Phishing", and becoming a performing authentication on that site, the credentials will be sent
real threats in these days. In the curent Web system deployment, TLS to the attacker's server and trivially leaked. Attacks such as
certificates will be issued to almost any users of Internet phishing have become a serious threat. In current Web system
(including malicious attackers). Although those certificate includes deployments, TLS certificates will be issued to almost any users of
several levels of the "validation results" (such as corporate names) the Internet (including malicious attackers). Although those
of the issued entities, task of "checking" those validation results certificates include several levels of the "validation results" (such
are left to the users of Web browsers, still leaving the possibility as corporate names) of the issued entities, the task of "checking"
of such social attacks. those validation results is left to the users of Web browsers, still
leaving open the possibility of such social engineering attacks.
Another direction to avoid such threats is to avoid password-based Another way to avoid such threats is to avoid password-based
authentication and use some kind of pre-deployed strong secret keys authentication and use some kinds of pre-deployed strong secret keys
(either on client side or on server-side) for authentications. (on either the client side or the server side) for authentications.
Several federated authentication framework as well as HOBA [RFC7486] Several federated authentication frameworks, as well as HTTP
are proposed and deployed on the real Web systems to satisfy those Origin-Bound Authentication (HOBA) [RFC7486], are proposed and
needs. However, a kind of authentication based on "human-memorable deployed on real Web systems to satisfy those needs. However, a type
secret" (i.e. passwords) is still required on several situations of authentication based on "human-memorable secrets" (i.e.,
within those systems, such is initialization, key deployment to new passwords) is still required in several scenarios, such as
clients, or recovery of secret accounts with lost cryptographic keys. initialization, key deployment to new clients, or recovery of secret
accounts with lost cryptographic keys.
The Mutual authentication protocol proposed in this document is a The Mutual authentication protocol, as proposed in this document, is
strong cryptographic solution for password authentications. It a strong cryptographic solution for password authentications. It
mainly provides the two key features: mainly provides the following two key features:
o No password information, at all, is exchanged in the o No password information at all is exchanged in the communications.
communications. When the server and the user fails to When the server and the user fail to authenticate with each other,
authenticate with each other, the protocol will not reveal the the protocol will not reveal even the tiniest bit of information
tiniest bit of information about the user's password. This about the user's password. This prevents any kind of offline
prevents any kind of off-line password dictionary attacks, even password dictionary attacks, even with the existence of phishing
with the existence of Phishing attacks. attacks.
o To successfully authenticate, the server must own the valid o To successfully authenticate, the server, as well as client users,
registered credentials (authentication secret), as well as client must own the valid registered credentials (authentication secret).
users. (Non-intuitively, this is not true for Basic and Digest This means that a phishing attacker cannot trick users into
authentication. For example, servers for Basic authentications thinking that it is an "authentic" server. (It should be
can answer "YES" to any clients, without actually checking pointed out that this is not true for Basic and Digest
authentication at all.) This means that phishing attackers cannot authentication; for example, servers using Basic authentication
forge users that they are the "authentic" servers. Client users can answer "YES" to any clients without actually checking
can assert whether the communicating peer is "the server" who have authentication at all.) Client users can ascertain whether or not
registered their account beforehand. In other words, it provides the communicating peer is truly "the server" that registered their
"true" mutual authentication between servers and clients. account beforehand. In other words, it provides "true" mutual
authentication between servers and clients.
Given these, the proposed protocol can serve as a strong alternative Given the information above, the proposed protocol can serve as a
to the Basic, Digest, and web-form-based authentications, and also as strong alternative to the Basic, Digest, and Web-form-based
a strong companion to the non-password-based authentication authentication schemes and also as a strong companion to the
frameworks. non-password-based authentication frameworks.
The proposed protocol will serve in the same way as existing Basic/ The proposed protocol will serve in the same way as does existing
Digest authentication: it meets the requirement for new Basic or Digest authentication: it meets the requirements for new
authentication scheme for HTTP as described in Section 5.1.2 of authentication schemes for HTTP, as described in Section 5.1.2 of
[RFC7235]. Additionally, to communiate authentication results more [RFC7235]. Additionally, to communicate authentication results more
reliably between the server and the client user, it suggests for Web reliably between the server and the client user, it suggests that Web
browsers to have some "secure" way of displaying the authentication browsers have some "secure" way of displaying the authentication
results. Having such an user interface in future browser will results. Having such a user interface in future browsers will
greatly reduce the risk of impersonation by kinds of social attacks, greatly reduce the risk of impersonation by various kinds of social
similarly in the manner of the "green padlock" for extended engineering attacks, in a manner similar to that of the
verification TLS certificates. "green padlock" for Extended Validation TLS certificates.
Technically, the authentication scheme proposed in this document is a Technically, the authentication scheme proposed in this document is a
general framework for using password-based authenticated key exchange general framework for using password-based authenticated key exchange
(PAKE) and similar stronger cryptographic primitives with HTTP. The (PAKE) and similar stronger cryptographic primitives with HTTP. The
two key features shown above are corresponding to the nature of PAKE. two key features shown above correspond to the nature of PAKE.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
[RFC2119]. [RFC2119].
This document distinguishes the terms "client" and "user" in the This document distinguishes the terms "client" and "user" in the
following way: A "client" is an entity understanding and talking HTTP following way: a "client" is an entity that understands and
and the specified authentication protocol, usually computer software; implements HTTP and the specified authentication protocol -- usually
a "user" is a (usually natural) person who wants to access data computer software; a "user" is typically a human being who wants to
resources using a "client". access data resources using a "client".
The term "natural numbers" refers to the non-negative integers The term "natural numbers" refers to the non-negative integers
(including zero) throughout this document. (including zero) throughout this document.
This document treats both the input (domain) and the output This document treats both the input (domain) and the output
(codomain) of hash functions to be octet strings. When a natural (codomain) of hash functions as octet strings. When a natural number
number output for a hash function is required, it will be written as output for a hash function is required, it will be written as
INT(H(s)). INT(H(s)).
1.2. Document Structure and Related Documents 1.2. Document Structure and Related Documents
The entire document is organized as follows: The entire document is organized as follows:
o Section 2 presents an overview of the protocol design. o Section 2 presents an overview of the protocol design.
o Sections 3 to 11 define a general framework of the Mutual o Sections 3 through 11 define a general framework of the Mutual
authentication protocol. This framework is independent of authentication protocol. This framework is independent of
specific cryptographic primitives. specific cryptographic primitives.
o Section 12 describes properties needed for cryptographic o Section 12 describes properties needed for cryptographic
algorithms used with this protocol framework, and defines a few algorithms used with this protocol framework and defines a few
functions which will be shared among such cryptographic functions that will be shared among such cryptographic algorithms.
algorithms.
o The sections after that contain general normative and informative o Sections 13 through 15 contain general normative and informative
information about the protocol. information about the protocol.
In addition, there are two companion documents which are referred o Sections 16 and 17 describe IANA considerations and security
from/related to this specification: considerations, respectively.
o [I-D.ietf-httpauth-mutual-algo]: defines cryptographic primitives In addition, we will refer to the following two companion documents,
which can be used with this protocol framework. as they are related to this specification:
o [I-D.ietf-httpauth-extension]: defines small but useful extensions o [RFC8121] defines cryptographic primitives that can be used with
to the current HTTP authentication framework so that it can this protocol framework.
support application-level semantics of existing Web systems.
o [RFC8053] defines small but useful extensions to the current HTTP
authentication framework so that it can support application-level
semantics of existing Web systems.
2. Protocol Overview 2. Protocol Overview
The protocol, as a whole, is designed as a natural extension to the The protocol, as a whole, is designed as a natural extension to HTTP
HTTP protocol [RFC7230] using a framework defined in [RFC7235]. [RFC7230] and uses the framework defined in [RFC7235]. Internally,
Internally, the server and the client will first perform a the server and the client will first perform a cryptographic key
cryptographic key exchange, using the secret password as a "tweak" to exchange, using the secret password as a "tweak" to the exchange.
the exchange. The key exchange will only succeed when the secrets The key exchange will only succeed when the secrets used by both
used by the both peers are correctly related (i.e., generated from peers are correctly related (i.e., generated from the same password).
the same password). Then, both peers will verify the authentication Then, both peers will verify the authentication results by confirming
results by confirming the sharing of the exchanged key. This section the sharing of the exchanged key. This section provides a brief
provides a brief outline of the protocol and the exchanged messages. outline of the protocol and the exchanged messages.
2.1. Messages Overview 2.1. Messages
The authentication protocol uses seven kinds of messages to perform The authentication protocol uses six kinds of messages to perform
mutual authentication. These messages have specific names within mutual authentication. These messages have specific names within
this specification. this specification.
o Authentication request messages: used by the servers to request o Authentication request messages: used by the servers to request
clients to start mutual authentication. that clients start mutual authentication.
* 401-INIT message: a general message to start the authentication * 401-INIT message: a general message to start the authentication
protocol. It is also used as a message indicating an protocol. It is also used as a message indicating an
authentication failure. authentication failure.
* 401-STALE message: a message indicating that client has to * 401-STALE message: a message indicating that the client has to
start a new key exchange. start a new key exchange.
o Authenticated key exchange messages: used by both peers to perform o Authenticated key exchange messages: used by both peers to perform
authentication and the sharing of a cryptographic secret. authentication and the sharing of a cryptographic secret.
* req-KEX-C1 message: a message sent from the client. * req-KEX-C1 message: a message sent from the client.
* 401-KEX-S1 message: an intermediate response to a req-KEX-C1 * 401-KEX-S1 message: an intermediate response to a req-KEX-C1
message from the server. message from the server.
o Authentication verification messages: used by both peers to verify o Authentication verification messages: used by both peers to verify
the authentication results. the authentication results.
* req-VFY-C message: a message used by the client, requesting the * req-VFY-C message: a message used by the client to request that
server authenticate and authorize the client. the server authenticate and authorize the client.
* 200-VFY-S message: a response used by the server to indicate * 200-VFY-S message: a response used by the server to indicate
the successful client-authentication. It also contains that client authentication succeeded. It also contains
information necessary for the client to check the authenticity information necessary for the client to check the authenticity
of the server. of the server.
In addition to the above, either a request or a response without any In addition to the above six kinds of messages, a request or response
HTTP headers related to this specification will be hereafter called a without any HTTP headers related to this specification will be
"normal request" or a "normal response", respectively. hereafter called a "normal request" or "normal response",
respectively.
2.2. Typical Flows of the Protocol 2.2. Typical Flows of the Protocol
In typical cases, the client access to a resource protected by the In typical cases, client access to a resource protected by the
Mutual authentication scheme will use the following protocol Mutual authentication scheme will use the following protocol
sequence. sequence:
Client Server Client Server
| | | |
| ---- (1) normal request ---------> | | ---- (1) normal request ---------> |
GET / HTTP/1.1 | GET / HTTP/1.1 |
| | | |
| <---------------- (2) 401-INIT --- | | <---------------- (2) 401-INIT --- |
| 401 Authentication Required | 401 Unauthorized |
| WWW-Authenticate: Mutual realm="a realm" | WWW-Authenticate: Mutual realm="a realm"
| | | |
[user, | | [user, | |
pass]-->| | pass]-->| |
| ---- (3) req-KEX-C1 -------------> | | ---- (3) req-KEX-C1 -------------> |
GET / HTTP/1.1 | GET / HTTP/1.1 |
Authorization: Mutual user="john", |--> [user DB] Authorization: Mutual user="john", |--> [user DB]
kc1="...", ... |<-- [user info] kc1="...", ... |<-- [user info]
| | | |
| <-------------- (4) 401-KEX-S1 --- | | <-------------- (4) 401-KEX-S1 --- |
| 401 Authentication Required | 401 Unauthorized |
| WWW-Authenticate: Mutual sid=..., ks1="...", ... | WWW-Authenticate: Mutual sid=..., ks1="...", ...
| | | |
[compute] (5) compute session secret [compute] [compute] (5) compute session secret [compute]
| | | |
| | | |
| ---- (6) req-VFY-C --------------> | | ---- (6) req-VFY-C --------------> |
GET / HTTP/1.1 |--> [verify (6)] GET / HTTP/1.1 |--> [verify (6)]
Authorization: Mutual sid=..., |<-- OK Authorization: Mutual sid=..., |<-- OK
vkc="...", ... | vkc="...", ... |
| | | |
| <--------------- (7) 200-VFY-S --- | | <--------------- (7) 200-VFY-S --- |
[verify | 200 OK | [verify | 200 OK |
(7)]<--| Authentication-Info: Mutual vks="..." (7)]<--| Authentication-Info: Mutual vks="..."
| | | |
v v v v
Figure 1: Typical communication flow for first access to resource Figure 1: Typical Communication Flow for First Access to Resource
o As usual in general HTTP protocol designs, a client will at first o As is typical in general HTTP protocol designs, a client will at
request a resource without any authentication attempt (1). If the first request a resource without any authentication attempt (1).
requested resource is protected by the Mutual authentication, the If the requested resource is protected by the Mutual
server will respond with a message requesting authentication authentication protocol, the server will respond with a message
(401-INIT) (2). requesting authentication (401-INIT) (2).
o The client processes the body of the message and waits for the o The client processes the body of the message and waits for the
user to input the user name and a password. If the user name and user to input the username and password. If the username and
the password are available, the client will send a message with password are available, the client will send a message with the
the authenticated key exchange (req-KEX-C1) to start the authenticated key exchange (req-KEX-C1) to start the
authentication (3). authentication (3).
o If the server has received a req-KEX-C1 message, the server looks o If the server has received a req-KEX-C1 message, the server
up the user's authentication information within its user database. looks up the user's authentication information within its user
Then the server creates a new session identifier (sid) that will database. Then, the server creates a new session identifier (sid)
be used to identify sets of the messages that follow it and that will be used to identify sets of the messages that follow it
responds back with a message containing a server-side and responds with a message containing a server-side authenticated
authenticated key exchange value (401-KEX-S1) (4). key exchange value (401-KEX-S1) (4).
o At this point (5), both peers calculate a shared "session secret" o At this point (5), both peers calculate a shared "session secret"
using the exchanged values in the key exchange messages. Only using the exchanged values in the key exchange messages. Only
when both the server and the client have used secret credentials when both the server and the client have used secret credentials
generated from the same password will the session secret values generated from the same password will the session secret values
match. This session secret will be used for access authentication match. This session secret will be used for access authentication
of every individual request/response pair after this point. of every individual request/response pair after this point.
o The client will send a request with a client-side authentication o The client will send a request with a client-side authentication
verification value (req-VFY-C) (6), calculated from the client- verification value (req-VFY-C) (6), calculated from the
generated session secret. The server will check the validity of client-generated session secret. The server will check the
the verification value using its own version of the session validity of the verification value using its own version of the
secret. session secret.
o If the authentication verification value from the client was o If the authentication verification value from the client was
correct, it means that the client definitely owns the credential correct, then the client definitely owns the credential based on
based on the expected password (i.e., the client authentication the expected password (i.e., the client authentication succeeded).
succeeded). The server will respond with a successful message The server will respond with a successful message (200-VFY-S) (7).
(200-VFY-S) (7). Contrary to the usual one-way authentication Unlike the usual one-way authentication (e.g., HTTP Basic
(e.g., HTTP Basic authentication or POP APOP authentication authentication or POP APOP authentication [RFC1939]), this message
[RFC1939]), this message also contains a server-side also contains a server-side authentication verification value.
authentication verification value.
When the client's verification value is incorrect (e.g., because When the client's verification value is incorrect (e.g., because
the user-supplied password was incorrect), the server will respond the user-supplied password was incorrect), the server will respond
with the 401-INIT message (the same one as used in (2)) instead. with a 401-INIT message (the same message as the message used
in (2)) instead.
o The client MUST first check the validity of the server-side o The client MUST first check the validity of the server-side
authentication verification value contained in the message (7). authentication verification value contained in the message (7).
If the value was equal to the expected one, server authentication If the value was equal to the expected value, server
succeeded. authentication succeeded.
If it is not the value expected, or if the message does not If it is not the expected value or the message does not contain
contain the authentication verification value, it means that the the authentication verification value, then the mutual
mutual authentication has been broken for some unexpected reason. authentication has been broken for some unexpected reason. The
The client MUST NOT process any body or header values contained in client MUST NOT process any body or header values contained in the
the HTTP response in this case. (Note: This case should not HTTP response in this case. (Note: This case should not happen
happen between a correctly implemented server and client without between a correctly implemented server and client without any
any active attacks. The possible cause of such a case might be active attacks; such a scenario could be caused by either a
either a man-in-the-middle attack or an incorrect implementation.) man-in-the-middle attack or incorrect implementation.)
2.3. Alternative Flows 2.3. Alternative Flows
As shown above, the typical flow for a first authentication request As shown above, the typical flow for a first authentication request
requires three request-response pairs. To reduce the protocol requires three request-response pairs. To reduce protocol overhead,
overhead, the protocol enables several short-cut flows which require the protocol enables several shortcut flows that require fewer
fewer messages. messages.
o (case A) If the client knows that the resource is likely to o Case A: If the client knows that the resource is likely to require
require authentication, the client MAY omit the first authentication, the client MAY omit the first unauthenticated
unauthenticated request (1) and immediately send a key exchange request (1) and immediately send a key exchange (req-KEX-C1)
(req-KEX-C1 message). This will reduce one round-trip of message. This will reduce the number of round trips by one.
messages.
o (case B) If both the client and the server previously shared a o Case B: If both the client and the server previously shared a
session secret associated with a valid session identifier (sid), session secret associated with a valid sid, the client MAY
the client MAY directly send a req-VFY-C message using the directly send a req-VFY-C message using the existing sid and
existing session identifier and corresponding session secret. corresponding session secret. This will further reduce the number
This will further reduce one round-trip of messages. of round trips by one.
The server MAY have thrown out the corresponding session from the The server MAY have thrown out the corresponding session from the
session table. If so, the server will respond with a 401-STALE session table. If so, the server will respond with a 401-STALE
message, indicating a new key exchange is required. The client message, indicating that a new key exchange is required. The
SHOULD retry constructing a req-KEX-C1 message in this case. client SHOULD try again to construct a req-KEX-C1 message in
this case.
Figure 2 depicts the shortcut flows described above. Under the Figure 2 depicts the shortcut flows described above. When using
appropriate settings and implementations, most of the requests to appropriate settings and implementations, most of the requests to
resources are expected to meet both criteria, and thus only one resources are expected to meet both criteria; thus, only one
round-trip of request/response will be required. round trip of request/response will be required.
(A) omit first request Case A: Omit first request
(2 round trips) (2 round trips)
Client Server Client Server
| | | |
| --- req-KEX-C1 ----> | | --- req-KEX-C1 ----> |
| | | |
| <---- 401-KEX-S1 --- | | <---- 401-KEX-S1 --- |
| | | |
| ---- req-VFY-C ----> | | ---- req-VFY-C ----> |
| | | |
| <----- 200-VFY-S --- | | <----- 200-VFY-S --- |
| | | |
(B) reusing session secret (re-authentication) Case B: Reuse session secret (re-authentication)
(B-1) key available (B-2) key expired (B-1) key available (B-2) key expired
(1 round trip) (3 round trips) (1 round trip) (3 round trips)
Client Server Client Server Client Server Client Server
| | | | | | | |
| ---- req-VFY-C ----> | | --- req-VFY-C -------> | | ---- req-VFY-C ----> | | --- req-VFY-C -------> |
| | | | | | | |
| <----- 200-VFY-S --- | | <------- 401-STALE --- | | <----- 200-VFY-S --- | | <------- 401-STALE --- |
| | | | | | | |
| --- req-KEX-C1 ------> | | --- req-KEX-C1 ------> |
| | | |
| <------ 401-KEX-S1 --- | | <------ 401-KEX-S1 --- |
| | | |
| --- req-VFY-C -------> | | --- req-VFY-C -------> |
| | | |
| <------- 200-VFY-S --- | | <------- 200-VFY-S --- |
| | | |
Figure 2: Several alternative protocol flows Figure 2: Several Alternative Protocol Flows
For more details, see Sections 10 and 11. For more details, see Sections 10 and 11.
3. Message Syntax 3. Message Syntax
Throughout this specification, the syntax is denoted in the extended Throughout this specification, the syntax is denoted in the extended
augmented BNF syntax defined in [RFC7230], and [RFC5234]. The augmented BNF syntax as defined in [RFC7230] and [RFC5234]. The
following elements are quoted from [RFC5234], [RFC7230] and following elements are used in this document per [RFC5234],
[RFC7235]: DIGIT, ALPHA, SP, auth-scheme, quoted-string, auth-param, [RFC7230], and [RFC7235]: DIGIT, ALPHA, SP, auth-scheme,
header-field, token, challenge, and credential. quoted-string, auth-param, header-field, token, challenge, and
credentials.
The Mutual authentication protocol uses three headers: The Mutual authentication protocol uses three headers:
WWW-Authenticate (usually in responses with status code 401), WWW-Authenticate (usually in responses with a 401 status code),
Authorization (in requests), and Authentication-Info (in responses Authorization (in requests), and Authentication-Info (in responses
other than 401 status). These headers follow a common framework other than a 401 status code). These headers follow the frameworks
described in [RFC7235] and [RFC7615]. The detailed meanings for described in [RFC7235] and [RFC7615]. See Section 4 for more details
these headers are contained in Section 4. regarding these headers.
The framework in [RFC7235] defines the syntax for the headers The framework in [RFC7235] defines the syntax for the headers
WWW-Authenticate and Authorization as the syntax elements "challenge" WWW-Authenticate and Authorization as the syntax elements "challenge"
and "credentials", respectively. The "auth-scheme" contained in and "credentials", respectively. The auth-scheme element contained
those headers MUST be "Mutual" throughout this protocol in those headers MUST be set to "Mutual" when using the protocol
specification. The syntax for "challenge" and "credentials" to be specified in this document. The syntax for "challenge" and
used with the "Mutual" auth-scheme SHALL be name-value pairs (#auth- "credentials" to be used with the "Mutual" auth-scheme SHALL be
param), not the "b64token" defined in [RFC7235]. name-value pairs (#auth-param), not the "token68" parameter defined
in [RFC7235].
The Authentication-Info: header used in this protocol SHALL follow The Authentication-Info header used in this protocol SHALL follow the
the syntax defined in [RFC7615]. syntax defined in [RFC7615].
In HTTP, the WWW-Authenticate header may contain two or more In HTTP, the WWW-Authenticate header may contain two or more
challenges. Client implementations SHOULD be aware of and be capable challenges. Client implementations SHOULD be aware of, and be
of handling those cases correctly. capable of correctly handling, those cases.
3.1. Non-ASCII extended header parameters 3.1. Non-ASCII Extended Header Parameters
All of parameters contained in the above three headers, except the All of the parameters contained in the above three headers, except
"realm" field, MAY be extended to ISO 10646-1 values using the for the "realm" field, MAY be extended to ISO 10646-1 values using
framework described in [RFC5987]. All servers and clients MUST be the framework described in [RFC5987]. All servers and clients MUST
capable of receiving and sending values encoded in [RFC5987] syntax. be capable of receiving and sending values encoded per the syntax
specified in [RFC5987].
If a value to be sent contains only ASCII characters, the field MUST If a value to be sent contains only ASCII characters, the field MUST
be sent using plain RFC 7235 syntax. The syntax as extended by RFC be sent using plain syntax as defined in RFC 7235. The syntax as
5987 MUST NOT be used in this case. extended by RFC 5987 MUST NOT be used in this case.
If a value (except the "realm" header) contains one or more non-ASCII If a value (except for the "realm" header) contains one or more
characters, the parameter SHOULD be sent using the syntax defined in non-ASCII characters, the parameter SHOULD be sent using the syntax
Section 3.2 of [RFC5987] as "ext-parameter". Such a parameter MUST defined in Section 3.2 of [RFC5987] as "ext-parameter". Such a
have a charset value of "UTF-8", and the language value MUST always parameter MUST have a charset value of "UTF-8", and the language
be omitted (have an empty value). The same parameter MUST NOT be value MUST always be omitted (have an empty value). The same
sent more than once, regardless of the used syntax. parameter MUST NOT be sent more than once, regardless of the
syntax used.
For example, a parameter "user" with value "Renee of France" SHOULD For example, a parameter "user" with the value "Renee of France"
be sent as < user="Renee of France" >. If the value is SHOULD be sent as < user="Renee of France" >. If the value is
"Ren<e acute>e of France", it SHOULD be sent as < user*=UTF- "Ren<e acute>e of France", it SHOULD be sent as
8''Ren%C3%89e%20of%20France > instead. < user*=UTF-8''Ren%C3%89e%20of%20France > instead.
[RFC7235] requires the realm parameter to be in its plain form (not [RFC7235] requires that the "realm" parameter be in its plain form
as an extended "realm*" parameter), so RFC 5987 syntax MUST NOT be (not as an extended "realm*" parameter), so the syntax specified in
used for this parameter. RFC 5987 MUST NOT be used for this parameter.
3.2. Values 3.2. Values
The parameter values contained in challenge/credentials MUST be The parameter values contained in challenges or credentials MUST be
parsed strictly conforming to the HTTP semantics (especially un- parsed in strict conformance with HTTP semantics (especially the
quoting of the string parameter values). In this protocol, those unquoting of string parameter values). In this protocol, those
values are further categorized into the following value types: tokens values are further categorized into the following value types:
(bare-token and extensive-token), string, integer, hex-fixed-number, tokens (bare-token and extensive-token), string, integer,
and base64-fixed-number. hex-fixed-number, and base64-fixed-number.
For clarity, implementations are RECOMMENDED to use the canonical For clarity, it is RECOMMENDED that implementations use the canonical
representations specified in the following subsections for sending representations specified in the following subsections for sending
values. However, recipients MUST accept both quoted and unquoted values. However, recipients MUST accept both quoted and unquoted
representations interchangeably as specified in HTTP. representations interchangeably, as specified in HTTP.
3.2.1. Tokens 3.2.1. Tokens
For sustaining both security and extensibility at the same time, this For sustaining both security and extensibility at the same time, this
protocol defines a stricter sub-syntax for the "token" to be used. protocol defines a stricter sub-syntax for the "token" to be used.
Extensive-token values SHOULD use the following syntax (after HTTP Extensive-token values SHOULD use the following syntax (after the
value parsing): parsing of HTTP values):
bare-token = bare-token-lead-char *bare-token-char bare-token = bare-token-lead-char *bare-token-char
bare-token-lead-char = %x30-39 / %x41-5A / %x61-7A bare-token-lead-char = %x30-39 / %x41-5A / %x61-7A
bare-token-char = %x30-39 / %x41-5A / %x61-7A / "-" / "_" bare-token-char = %x30-39 / %x41-5A / %x61-7A / "-" / "_"
extension-token = "-" bare-token 1*("." bare-token) extension-token = "-" bare-token 1*("." bare-token)
extensive-token = bare-token / extension-token extensive-token = bare-token / extension-token
Figure 3: BNF syntax for token values Figure 3: BNF Syntax for Token Values
The tokens (bare-token and extension-token) are case insensitive; The tokens (bare-token and extension-token) are case insensitive.
Senders SHOULD send these in lower case, and receivers MUST accept Senders SHOULD send these in lower case, and receivers MUST accept
both upper and lower cases. When tokens are used as (partial) inputs both upper and lower cases. When tokens are used as (partial) inputs
to any hash or other mathematical functions, they MUST always be used to any hash functions or other mathematical functions, they MUST
in lower case. always be used in lower case.
Extensive-tokens are used in this protocol where the set of Extensive-tokens are used in this protocol where the set of
acceptable tokens may include non-standard extensions. Any extension acceptable tokens may include non-standard extensions. Any extension
of this protocol MAY use either the bare-tokens allocated by IANA of this protocol MAY use either the bare-tokens allocated by IANA
(under the procedure described in Section 16), or extension-tokens (see the procedure described in Section 16) or extension-tokens with
with the format "-<bare-token>.<domain-name>", where <domain-name> is the format "-<bare-token>.<domain-name>", where <domain-name> is a
a valid (sub-)domain name on the Internet owned by the party who valid (sub)domain name on the Internet owned by the party who defines
defines the extension. the extension.
Bare-tokens and extensive-tokens are also used for parameter names, Bare-tokens and extensive-tokens are also used for parameter names,
in the unquoted form. Requirements for using the extension-token for in the unquoted form. Requirements for using the extension-token for
the parameter names are the same as the previous paragraph. the parameter names are the same as those described in the previous
paragraph.
The canonical format for bare-tokens and extensive-tokens is the The canonical format for bare-tokens and extensive-tokens is the
unquoted representation. unquoted representation.
3.2.2. Strings 3.2.2. Strings
All character strings MUST be encoded to octet strings using the All character strings MUST be encoded to octet strings using UTF-8
UTF-8 encoding [RFC3629] for the Unicode character set [Unicode]. encoding [RFC3629] for the Unicode character set [Unicode]. Such
Such strings MUST NOT contain any leading BOM markers (also known as strings MUST NOT contain any leading Byte Order Marks (BOMs) (also
ZERO WIDTH NO-BREAK SPACE, U+FEFF or EF BB BF). Both peers are known as ZERO WIDTH NO-BREAK SPACE, U+FEFF, or EF BB BF). It is
RECOMMENDED to reject any invalid UTF-8 sequences that might cause RECOMMENDED that both peers reject any invalid UTF-8 sequences that
decoding ambiguities (e.g., containing <"> in the second or later might cause decoding ambiguities (e.g., containing <"> in the second
bytes of the UTF-8 encoded characters). or subsequent bytes of the UTF-8 encoded characters).
If strings are representing a domain name or URI that contains non- If strings represent a domain name or URI that contains non-ASCII
ASCII characters, the host parts SHOULD be encoded as it is used in characters, the host parts SHOULD be encoded as they (the parts) are
the HTTP protocol layer (e.g., in a Host: header); under current used in the HTTP protocol layer (e.g., in a Host: header); per
standards it will be the one defined in [RFC5890]. It SHOULD use current standards, the A-label as defined in [RFC5890] will be used.
lower-case ASCII characters. Lowercase ASCII characters SHOULD be used.
The canonical format for strings is quoted-string (as it may contain The canonical format for strings is quoted-string (as it may contain
equal signs, plus signs and slashes), unless the parameter containing equals signs ("="), plus signs ("+"), and slashes ("/")), unless the
the string value will use extended syntax defined in [RFC5987]. (An parameter containing the string value will use extended syntax as
[RFC5987] extended parameter will have an unquoted encoded value, as defined in [RFC5987]. (Per [RFC5987], an extended parameter will
defined therein.) have an unquoted encoded value.)
3.2.3. Numbers 3.2.3. Numbers
The following syntax definitions give a syntax for numeric values: The following syntax definitions provide a syntax for numeric values:
integer = "0" / (%x31-39 *DIGIT) ; no leading zeros integer = "0" / (%x31-39 *DIGIT) ; no leading zeros
hex-fixed-number = 1*(2(DIGIT / %x41-46 / %x61-66)) hex-fixed-number = 1*(2(DIGIT / %x41-46 / %x61-66))
base64-fixed-number = 1*( ALPHA / DIGIT / "+" / "/" ) 0*2"=" base64-fixed-number = 1*( ALPHA / DIGIT / "+" / "/" ) 0*2"="
Figure 4: BNF syntax for numbers Figure 4: BNF Syntax for Numbers
The syntax definition of the integers only allows representations The syntax definition of the integers only allows representations
that do not contain leading zeros. that do not contain leading zeros.
A number represented as a hex-fixed-number MUST include an even A number represented as a hex-fixed-number MUST include an even
number of hexadecimal digits (i.e., multiples of eight bits). Those number of hexadecimal digits (i.e., multiples of eight bits). Those
values are case-insensitive, and SHOULD be sent in lower case. When values are case insensitive and SHOULD be sent in lower case. When
these values are generated from any cryptographic values, they MUST these values are generated from any cryptographic values, they MUST
have their "natural length"; if these values are generated from a have their "natural length"; if they are generated from a hash
hash function, these lengths correspond to the hash size; if these function, their lengths correspond to the hash size; if they
are representing elements of a mathematical set (or group), these represent elements of a mathematical set (or group), their lengths
lengths SHALL be the shortest for representing all the elements in SHALL be the shortest lengths that represent all the elements in the
the set. For example, the results of the SHA-256 hash function will set. For example, the results of the SHA-256 hash function will be
be represented by 64 digits, and any elements in a 2048-bit prime represented by 64 digits, and any elements in a 2048-bit prime field
field (modulo a 2048-bit integer) will be represented by 512 digits, (modulo a 2048-bit integer) will be represented by 512 digits,
regardless of how much zeros appear in front of such representations. regardless of how many zeros appear in front of such representations.
Session-identifiers and other non-cryptographically generated values Session identifiers and other non-cryptographically generated values
are represented in any (even) length determined by the side that are represented in any (even) length determined by the side that
generates it first, and the same length MUST be used throughout all generates it first, and the same length MUST be used in all
communications by both peers. communications by both peers.
The numbers represented as base64-fixed-number SHALL be generated as The numbers represented as base64-fixed-number SHALL be generated as
follows: first, the number is converted to a big-endian radix-256 follows: first, the number is converted to a big-endian radix-256
binary representation as an octet string. The length of the binary representation as an octet string. The length of the
representation is determined in the same way as mentioned above. representation is determined in the same way as the technique
Then, the string is encoded using the Base 64 encoding (described in mentioned above. Then, the string is encoded using base64 encoding
Section 4 of [RFC4648]) without any spaces and newlines. (described in Section 4 of [RFC4648]) without any spaces and
Implementations decoding base64-fixed-number SHOULD reject any input newlines. Implementations decoding base64-fixed-number SHOULD reject
data with invalid characters, excess/insufficient padding, or non- any input data with invalid characters, excess or insufficient
canonical pad bits (See Sections 3.1 to 3.5 of [RFC4648]). padding, or non-canonical pad bits (see Sections 3.1 through 3.5 of
[RFC4648]).
The canonical format for integer and hex-fixed-number are unquoted The canonical format for integer and hex-fixed-number is unquoted
tokens, and that for base64-fixed-number is quoted-string. tokens, and the canonical format for base64-fixed-number is
quoted-string.
4. Messages 4. Messages
In this section we define the seven kinds of messages used in the In this section, we define the six kinds of messages in the
authentication protocol along with the formats and requirements of authentication protocol, along with the formats and requirements of
the headers for each message. the headers for each type of message.
To determine in what circumstances each message is expected to be To determine under what circumstances each message is expected to be
sent, see Sections 10 and 11. sent, see Sections 10 and 11.
In the descriptions below, the type of allowable values for each In the descriptions below, the types of allowable values for each
header parameter is shown in parenthesis after each parameter name. header parameter are shown in parentheses after each parameter name.
The "algorithm-determined" type means that the acceptable value for The "algorithm-determined" type means that the acceptable value for
the parameter is one of the types defined in Section 3, and is the parameter is one of the types defined in Section 3 and is
determined by the value of the "algorithm" parameter. The parameters determined by the value of the "algorithm" parameter. The parameters
marked "mandatory" SHALL be contained in the message. The parameters marked "mandatory" SHALL be contained in the message. The parameters
marked "non-mandatory" MAY either be contained or omitted in the marked "non-mandatory" MAY be either contained in the message or
message. Each parameter SHALL appear in each header exactly once at omitted from it. Each parameter SHALL appear in each header exactly
most. once at most.
All credentials and challenges MAY contain any parameters not All credentials and challenges MAY contain any parameters not
explicitly specified in the following sections. Recipients that do explicitly specified in the following sections. Recipients that
not understand such parameters MUST silently ignore those. However, do not understand such parameters MUST silently ignore them.
all credentials and challenges MUST meet the following criteria: However, all credentials and challenges MUST meet the following
criteria:
o For responses, the parameters "reason", any "ks#" (where # stands o For responses, the parameters "reason", any "ks#" (where "#"
for any decimal integer), and "vks" are mutually exclusive; any stands for any decimal integer), and "vks" are mutually exclusive;
challenge MUST NOT contain two or more parameters among them. any challenges MUST NOT contain two or more parameters among them.
They MUST NOT contain any "kc#" or "vkc" parameters. They MUST NOT contain any "kc#" or "vkc" parameters.
o For requests, the parameters "kc#" (where # stands for any decimal o For requests, the parameters "kc#" (where "#" stands for any
integer), and "vkc" are mutually exclusive and any challenge decimal integer) and "vkc" are mutually exclusive; any challenges
MUST NOT contain two or more parameters among them. They MUST NOT MUST NOT contain two or more parameters among them. They MUST NOT
contain any "ks#" or "vks" parameters. contain any "ks#" or "vks" parameters.
Every message in this section contains a "version" field, to detect Every message defined in this section contains a "version" field to
future, incompatible revisions of the protocol. Implementations of detect any future revisions of the protocol that are incompatible.
the protocol described in this specification MUST always send a token Implementations of the protocol described in this specification MUST
"1", and recipients MUST reject messages that contain any other value always send a token "1" to represent the version number. Recipients
as a version, unless another specification defines a behavior for MUST reject messages that contain any other value for the version,
that version. unless another specification defines specific behavior for that
version.
4.1. 401-INIT and 401-STALE 4.1. 401-INIT and 401-STALE
Every 401-INIT or 401-STALE message SHALL be a valid HTTP 401-status Every 401-INIT or 401-STALE message SHALL be a valid HTTP 401
(Authentication Required) message (or other 4XX status if sensible) (Unauthorized) status message (or some other 4xx status message, if
containing one and only one (hereafter not explicitly noted) appropriate) containing one and only one (hereafter not explicitly
"WWW-Authenticate" header containing a "reason" parameter in the noted) WWW-Authenticate header containing a "reason" parameter in the
challenge. The challenge SHALL contain all of the parameters marked challenge. The challenge SHALL contain all of the parameters marked
"mandatory" below, and MAY contain those marked "non-mandatory". "mandatory" below and MAY contain those marked "non-mandatory".
version: (mandatory extensive-token) should be the token "1". version:
(mandatory extensive-token) should be the token "1".
algorithm: (mandatory extensive-token) specifies the algorithm:
authentication algorithm to be used. The value MUST (mandatory extensive-token) specifies the authentication algorithm
be one of the tokens specified in to be used. The value MUST be one of the tokens specified in
[I-D.ietf-httpauth-mutual-algo] or another [RFC8121] or another supplemental specification.
supplemental specification.
validation: (mandatory extensive-token) specifies the method of validation:
host validation. The value MUST be one of the tokens (mandatory extensive-token) specifies the method of host
described in Section 7 or the tokens specified in validation. The value MUST be one of the tokens described in
another supplemental specification. Section 7 or the tokens specified in another supplemental
specification.
auth-scope: (non-mandatory string) specifies the authentication auth-scope:
scope, the set of hosts for which the authentication (non-mandatory string) specifies the authentication scope, i.e.,
credentials are valid. It MUST be one of the strings the set of hosts for which the authentication credentials are
described in Section 5. If the value is omitted, it valid. It MUST be one of the strings described in Section 5. If
is assumed to be the "single-server" type domain in the value is omitted, it is assumed to be the "single-server type"
Section 5. domain as described in Section 5.
realm: (mandatory string) is a string representing the name realm:
of the authentication realm inside the authentication (mandatory string) is a string representing the name of the
scope. As specified in [RFC7235], this value MUST authentication realm inside the authentication scope. As
always be sent in the quoted-string form, and an specified in [RFC7235], this value MUST always be sent in the
[RFC5987] encoding MUST NOT be used. quoted-string form, and an encoding as specified in [RFC5987]
The realm value sent from the server SHOULD be an MUST NOT be used.
ASCII string. Clients MAY treat any non-ASCII value
received in this field as a binary blob, an NFC-
normalized UTF-8 string, or an error.
reason: (mandatory extensive-token) SHALL be an extensive- The realm value sent from the server SHOULD be an ASCII string.
token that describes the possible reason of the failed Clients MAY treat any non-ASCII value received in this field as a
authentication/authorization. Both servers and binary blob, an NFC-normalized UTF-8 string ("NFC" stands for
clients SHALL understand and support the following "Normalization Form C"), or an error.
three tokens:
* initial: authentication was not tried because there reason:
was no Authorization header in the corresponding (mandatory extensive-token) SHALL be an extensive-token that
request. describes the possible reason for the failed authentication or
authorization. Both servers and clients SHALL understand and
support the following three tokens:
* stale-session: the provided sid in the request was * initial: Authentication was not attempted because there was no
either unknown to or expired in the server. Authorization header in the corresponding request.
* auth-failed: authentication trial was failed for * stale-session: The provided sid in the request was either
some reason, possibly with a bad authentication unknown to the server or expired in the server.
credential.
Implementations MAY support the following tokens or * auth-failed: The authentication trial failed for some reason,
any extensive-tokens defined outside this possibly because of a bad authentication credential.
specification. If clients receive any unknown tokens,
they SHOULD treat these as if they were "auth-failed"
or "initial".
* reauth-needed: the server-side application requires Implementations MAY support the following tokens or any
a new authentication trial, regardless of the extensive-tokens defined outside of this specification. If
current status. clients receive any unknown tokens, they SHOULD treat them as if
they were "auth-failed" or "initial".
* invalid-parameters: the server did not attempt * reauth-needed: The server-side application requires a new
authentication because some parameters were not authentication trial, regardless of the current status.
acceptable.
* internal-error: the server did not attempt * invalid-parameters: The server did not attempt authentication
authentication because there are some troubles on because some parameters were not acceptable.
the server-side.
* user-unknown: this is a special case of auth- * internal-error: The server did not attempt authentication
failed, suggesting that the provided user name is because there are some problems on the server side.
invalid. The use of this parameter is
NOT RECOMMENDED due to security implications,
except for special-purpose applications where it
makes sense.
* invalid-credential: ditto, suggesting that the * user-unknown: This is a special case of auth-failed; it
provided user name was valid but authentication suggests that the provided username is invalid. Due to
still failed. The use of this parameter is security implications, the use of this parameter is
NOT RECOMMENDED for security reasons. NOT RECOMMENDED, except for special-purpose applications where
it would make sense to do so.
* authz-failed: authentication was successful, but * invalid-credential: This is another special case of
access to the specified resource is not authorized auth-failed; it suggests that the provided username was valid
to the specific authenticated user. (It might be but authentication still failed. For security reasons, the use
used along with either a 401 or 403 status to of this parameter is NOT RECOMMENDED.
indicate that the authentication result is one of
the existing reasons for the failed authorization.)
It is RECOMMENDED to record the reasons to a kind of * authz-failed: Authentication was successful, but access to the
diagnostic log, for an example, or shown to the client specified resource is not authorized to the specific
user immediately. It will be helpful to find out authenticated user. (It might be used along with either a
later that the reason of the failed authentication is 401 (Unauthorized) or 403 (Forbidden) status code to indicate
either technical reasons of user errors. that the authentication result is one of the existing reasons
for the failed authorization.)
It is RECOMMENDED that the reason for failure be recorded to some
type of diagnostic log, shown to the client user immediately, or
both. It will be helpful to find out later whether the reason for
the failure is technical or caused by user error.
The algorithm specified in this header will determine the types The algorithm specified in this header will determine the types
(among those defined in Section 3) and the values for K_c1, K_s1, (among those defined in Section 3) and the values for K_c1, K_s1,
VK_c and VK_s. VK_c, and VK_s.
Among these messages, those with the reason parameter of value Among these messages, any messages with the "reason" parameter value
"stale-session" will be called "401-STALE" messages hereafter, "stale-session" will be called "401-STALE" messages hereafter,
because these have a special meaning in the protocol flow. Messages because these messages have a special meaning in the protocol flow.
with any other reason parameters will be called "401-INIT" messages. Messages with any other "reason" parameters will be called "401-INIT"
messages.
4.2. req-KEX-C1 4.2. req-KEX-C1
Every req-KEX-C1 message SHALL be a valid HTTP request message Every req-KEX-C1 message SHALL be a valid HTTP request message
containing an "Authorization" header with a credential containing a containing an Authorization header with a credential containing a
"kc1" parameter. "kc1" parameter.
The credential SHALL contain the parameters with the following names: The credential SHALL contain the parameters with the following names:
version: (mandatory, extensive-token) should be the token "1". version:
(mandatory, extensive-token) should be the token "1".
algorithm, validation, auth-scope, realm: MUST be the same values as algorithm, validation, auth-scope, realm:
received from the server. MUST be the same values as those received from the server.
user: (mandatory, string) is the UTF-8 encoded name of the user:
user. The string SHOULD be prepared according to the (mandatory, string) is the UTF-8 encoded name of the user. The
method presented in Section 9. string SHOULD be prepared according to the method presented in
Section 9.
kc1: (mandatory, algorithm-determined) is the client-side kc1:
key exchange value K_c1, which is specified by the (mandatory, algorithm-determined) is the client-side key exchange
algorithm that is used. value K_c1, which is specified by the algorithm that is used.
4.3. 401-KEX-S1 4.3. 401-KEX-S1
Every 401-KEX-S1 message SHALL be a valid HTTP 401-status Every 401-KEX-S1 message SHALL be a valid HTTP 401 (Unauthorized)
(Authentication Required) response message containing a status response message containing a WWW-Authenticate header with a
"WWW-Authenticate" header with a challenge containing a "ks1" challenge containing a "ks1" parameter.
parameter.
The challenge SHALL contain the parameters with the following names: The challenge SHALL contain the parameters with the following names:
version: (mandatory, extensive-token) should be the token "1". version:
(mandatory, extensive-token) should be the token "1".
algorithm, validation, auth-scope, realm: MUST be the same values as algorithm, validation, auth-scope, realm:
received from the client. MUST be the same values as those received from the client.
sid: (mandatory, hex-fixed-number) MUST be a session sid:
identifier, which is a random integer. The sid SHOULD (mandatory, hex-fixed-number) MUST be a session identifier, which
have uniqueness of at least 80 bits or the square of is a random integer. The sid SHOULD have uniqueness of at least
the maximum estimated transactions concurrently 80 bits or the square of the maximum estimated transactions
available in the session table, whichever is larger. concurrently available in the session table, whichever is larger.
See Section 6 for more details. See Section 6 for more details.
ks1: (mandatory, algorithm-determined) is the server-side ks1:
key exchange value K_s1, which is specified by the (mandatory, algorithm-determined) is the server-side key exchange
algorithm. value K_s1, which is specified by the algorithm.
nc-max: (mandatory, integer) is the maximum value of nonce nc-max:
numbers that the server accepts. (mandatory, integer) is the maximum value of nonce numbers that
the server accepts.
nc-window: (mandatory, integer) the number of available nonce nc-window:
number slots that the server will accept. The value (mandatory, integer) is the number of available nonce number slots
of the nc-window parameter is RECOMMENDED to be 128 or that the server will accept. It is RECOMMENDED that the value of
more. the "nc-window" parameter be 128 or more.
time: (mandatory, integer) represents the suggested time (in time:
seconds) that the client can reuse the session (mandatory, integer) represents the suggested time (in seconds)
represented by the sid. It is RECOMMENDED to be at that the client can reuse the session represented by the sid. It
least 60. The value of this parameter is not directly is RECOMMENDED that the time be set to at least 60 (seconds).
linked to the duration that the server keeps track for However, the server is not required to guarantee that the session
the session represented by the sid. represented by the sid will be available (e.g., alive, usable) for
the time specified in this parameter.
path: (non-mandatory, string) specifies which path in the path:
URI space the same authentication is expected to be (non-mandatory, string) specifies to which path in the URI space
applied. The value is a space-separated list of URIs, the same authentication is expected to be applied. The value is a
in the same format as it was specified in domain space-separated list of URIs, in the same format as that specified
parameter [RFC7616] for Digest authentications. All in the "domain" parameter [RFC7616] for Digest authentications.
path elements contained in the parameter MUST be All path elements contained in the "path" parameter MUST be inside
inside the specified auth-scope; if not, clients the specified auth-scope; if not, clients SHOULD ignore such
SHOULD ignore such elements. For better performance, elements. For better performance, it is important that clients
recognition of this parameter by clients is important. recognize and use this parameter.
4.4. req-VFY-C 4.4. req-VFY-C
Every req-VFY-C message SHALL be a valid HTTP request message Every req-VFY-C message SHALL be a valid HTTP request message
containing an "Authorization" header with a credential containing a containing an Authorization header with a credential containing a
"vkc" parameter. "vkc" parameter.
The parameters contained in the header are as follows: The parameters contained in the header are as follows:
version: (mandatory, extensive-token) should be the token "1". version:
(mandatory, extensive-token) should be the token "1".
algorithm, validation, auth-scope, realm: MUST be the same values as algorithm, validation, auth-scope, realm:
received from the server for the session. MUST be the same values as those received from the server for the
session.
sid: (mandatory, hex-fixed-number) MUST be one of the sid sid:
values that was received from the server for the same (mandatory, hex-fixed-number) MUST be one of the sid values that
authentication realm. was received from the server for the same authentication realm.
nc: (mandatory, integer) is a nonce request number that is nc:
unique among the requests sharing the same sid. The (mandatory, integer) is a nonce request number that is unique
values of the nonce numbers SHOULD satisfy the among the requests sharing the same sid. The values of the nonce
properties outlined in Section 6. numbers SHOULD satisfy the properties outlined in Section 6.
vkc: (mandatory, algorithm-determined) is the client-side vkc:
authentication verification value VK_c, which is (mandatory, algorithm-determined) is the client-side
specified by the algorithm. authentication verification value VK_c, which is specified by the
algorithm.
4.5. 200-VFY-S 4.5. 200-VFY-S
Every 200-VFY-S message SHALL be a valid HTTP message that does not Every 200-VFY-S message SHALL be a valid HTTP message that does not
have a 401 (Authentication Required) status code and SHALL contain an have a 401 (Unauthorized) status code and SHALL contain an
"Authentication-Info" header with a "vks" parameter. Authentication-Info header with a "vks" parameter.
The parameters contained in the header are as follows: The parameters contained in the header are as follows:
version: (mandatory, extensive-token) should be the token "1". version:
(mandatory, extensive-token) should be the token "1".
sid: (mandatory, hex-fixed-number) MUST be the value sid:
received from the client. (mandatory, hex-fixed-number) MUST be the value received from the
client.
vks: (mandatory, algorithm-determined) is the server-side vks:
authentication verification value VK_s, which is (mandatory, algorithm-determined) is the server-side
specified by the algorithm. authentication verification value VK_s, which is specified by the
algorithm.
The header MUST be sent before the content body: it MUST NOT be sent The header MUST be sent before the content body; it MUST NOT be sent
in the trailer of a chunked-encoded response. If a "100 Continue" in the trailer of a chunked-encoded response. If a "100 (Continue)"
response is sent from the server, the Authentication-Info header [RFC7231] response is sent from the server, the Authentication-Info
SHOULD be included in that response, instead of the final response. header SHOULD be included in that response instead of the final
response.
5. Authentication Realms 5. Authentication Realms
In this protocol, an "authentication realm" is defined as a set of In this protocol, an authentication realm is defined as a set of
resources (URIs) for which the same set of user names and passwords resources (URIs) for which the same set of usernames and passwords is
is valid. If the server requests authentication for an valid. If the server requests authentication for an authentication
authentication realm that the client is already authenticated for, realm for which the client is already authenticated, the client will
the client will automatically perform the authentication using the automatically perform the authentication using the already-known
already-known credentials. However, for different authentication credentials. However, for different authentication realms, clients
realms, clients MUST NOT automatically reuse user names and passwords MUST NOT automatically reuse usernames and passwords for another
for another realm. realm.
Just like in the Basic and Digest access authentication protocols, As is the case for the Basic and Digest access authentication
the Mutual authentication protocol supports multiple, separate protocols, the Mutual authentication protocol supports multiple,
protection spaces to be set up inside each host. Furthermore, the separate protection spaces to be set up inside each host.
protocol allows a single authentication realm to span over several Furthermore, the protocol allows a single authentication realm to
hosts within the same Internet domain. span several hosts within the same Internet domain.
Each authentication realm is defined and distinguished by the triple Each authentication realm is defined and distinguished by the triple
of an "authentication algorithm", an "authentication scope", and a of an authentication algorithm, an authentication scope, and a
"realm" parameter. However, server operators are NOT RECOMMENDED to "realm" parameter. However, it is NOT RECOMMENDED that server
use the same pair of an authentication scope and a realm with operators use the same pair of an authentication scope and a realm
different authentication algorithms. with different authentication algorithms.
The realm parameter is a string as defined in Section 4. The "realm" parameter is a string as defined in Section 4.
Authentication scopes are described in the remainder of this section. Authentication scopes are described in the remainder of this section.
An authentication scope specifies the range of hosts that the An authentication scope specifies the range of hosts spanned by the
authentication realm spans over. In this protocol, it MUST be one of authentication realm. In this protocol, it MUST be one of the
the following kinds of strings. following kinds of strings:
o Single-server type: A string in the format "<scheme>://<host>" or o Single-server type: A string in the format "<scheme>://<host>" or
"<scheme>://<host>:<port>", where <scheme>, <host>, and <port> are "<scheme>://<host>:<port>", where <scheme>, <host>, and <port> are
the corresponding URI parts of the request URI. If the default the corresponding URI parts of the request URI. If the default
port (i.e., 80 for http and 443 for https) is used for the port (i.e., 80 for HTTP and 443 for HTTPS) is used for the
underlying HTTP communications, the port part MUST be omitted, underlying HTTP communications, the port part MUST be omitted,
regardless of whether it was present in the request-URI. In all regardless of whether it was present in the request URI. In all
other cases, the port part MUST be present, and it MUST NOT other cases, the port part MUST be present, and it MUST NOT
contain leading zeros. Use this format when authentication is contain leading zeros. Use this format when authentication is
only valid for a specific protocol (such as https). This format only valid for a specific protocol (such as HTTPS). This format
is equivalent to the ASCII serialization of a Web Origin, is equivalent to the ASCII serialization of a Web origin, as
presented in Section 6.2 of [RFC6454]. presented in Section 6.2 of [RFC6454].
o Single-host type: The "host" part of the requested URI. This is o Single-host type: The "host" part of the requested URI. This is
the default value. Authentication realms within this kind of the default value. Authentication realms within this kind of
authentication scope will span over several protocols (e.g., http authentication scope will span several protocols (e.g., HTTP and
and https) and ports, but not over different hosts. HTTPS) and ports but will not span different hosts.
o Wildcard-domain type: A string in the format "*.<domain-postfix>", o Wildcard-domain type: A string in the format "*.<domain-postfix>",
where <domain-postfix> is either the host part of the requested where <domain-postfix> is either the host part of the requested
URI or any domain in which the requested host is included (this URI or any domain in which the requested host is included (this
means that the specification "*.example.com" is valid for all of means that the specification "*.example.com" is valid for all of
hosts "www.example.com", "web.example.com", hosts "www.example.com", "web.example.com",
"www.sales.example.com" and "example.com"). The domain-postfix "www.sales.example.com", and "example.com"). The domain-postfix
sent by the servers MUST be equal to or included in a valid sent by the servers MUST be equal to or included in a valid
Internet domain assigned to a specific organization; if clients Internet domain assigned to a specific organization; if clients
know, by some means such as a blacklist for HTTP cookies know, via some means such as a blacklist for HTTP cookies
[RFC6265], that the specified domain is not to be assigned to any [RFC6265], that the specified domain is not to be assigned to any
specific organization (e.g., "*.com" or "*.jp"), clients are specific organization (e.g., "*.com" or "*.jp"), it is RECOMMENDED
RECOMMENDED to reject the authentication request. that clients reject the authentication request.
In the above specifications, every "scheme", "host", and "domain" In the above specifications, every "scheme", "host", and "domain"
MUST be in lower case, and any internationalized domain names beyond MUST be in lower case, and any internationalized domain names beyond
the ASCII character set SHALL be represented in the way they are sent the ASCII character set SHALL be represented in the way they are sent
in the underlying HTTP protocol, represented in lower case in the underlying HTTP protocol, represented in lowercase characters,
characters, i.e., these domain names SHALL be in the form of LDH i.e., these domain names SHALL be in the form of LDH ("letters,
labels in IDNA [RFC5890]. A "port" MUST be given in the shortest, digits, hyphen") labels as defined in the Internationalized Domain
unsigned, decimal number notation. Not obeying these requirements Names for Applications (IDNA) specification [RFC5890]. A "port" MUST
will cause failure of valid authentication attempts. be given in shortest unsigned decimal number notation. Not obeying
these requirements will cause valid authentication attempts to fail.
5.1. Resolving Ambiguities 5.1. Resolving Ambiguities
In the above definitions of authentication scopes, several scopes may In the above definitions of authentication scopes, several scopes may
overlap each other. If a client has already been authenticated to overlap each other. If a client has already been authenticated to
several realms applicable to the same server, the client may have a several realms applicable to the same server, the client may have
multiple lists of the "path" parameters received with the multiple lists of the "path" parameters received with the
"401-KEX-S1" message (see Section 4). If these path lists have any "401-KEX-S1" message (see Section 4). If these path lists have any
overlap, a single URI may belong to multiple possible candidate of overlap, a single URI may belong to multiple possible candidate
realms to be authenticated to. In such cases, clients faces an realms to which the client can be authenticated. In such cases,
ambiguity in deciding which credentials to send for a new request (in clients face an ambiguous choice regarding which credentials to send
steps 3 and 4 of the decision procedure presented in Section 10). for a new request (see Steps 3 and 4 of the decision procedure
presented in Section 10).
In such cases, a client MAY send request which belong to any of these In such cases, a client MAY freely send requests that belong to any
candidate realms freely, or it MAY simply send an unauthenticated of these candidate realms, or it MAY simply send an unauthenticated
request and see for which realm the server requests an request and see for which realm the server requests an
authentication. Server operators are RECOMMENDED to provide authentication. It is RECOMMENDED that server operators provide
properly-configured "path" parameters (more precisely, disjoint path properly configured "path" parameters (more precisely, disjoint path
sets for each realms) for clients so that such ambiguities will not sets for each realm) for clients so that such ambiguities will not
occur. occur.
The following procedure is one possible tactic for resolving The following procedure is one possible tactic for resolving
ambiguity in such cases. ambiguities in such cases:
o If the client has previously sent a request to the same URI, and o If the client has previously sent a request to the same URI and it
if it remembers the authentication realm requested by the 401-INIT remembers the authentication realm requested by the 401-INIT
message at that time, use that realm. message at that time, use that realm.
o In other cases, use one of the authentication realms representing o In other cases, use one of the authentication realms representing
the most-specific authentication scopes. The list of possible the most-specific authentication scopes. The list of possible
domain specifications shown above is given from most specific to domain specifications shown above is given from most specific to
least specific. least specific.
If there are several choices with different wildcard-domain If there are several choices with different wildcard-domain
specifications, the one that has the longest domain-postfix has specifications, the one that has the longest domain-postfix has
priority over ones with shorter domain-postfixes. priority over those with shorter domain-postfixes.
o If there are realms with the same authentication scope, there is o If there are realms with the same authentication scope, there is
no defined priority; the client MAY choose any one of the possible no defined priority; the client MAY choose any one of the possible
choices. choices.
6. Session Management 6. Session Management
In the Mutual authentication protocol, a session represented by an In the Mutual authentication protocol, a session represented by
sid is set up using four messages (first request, 401-INIT, an sid is set up using four messages (first request, 401-INIT,
req-KEX-C1 and 401-KEX-S1), after which a "session secret" (z) req-KEX-C1, and 401-KEX-S1), after which a session secret (z)
associated with the session is established. After mutually associated with the session is established. After mutually
establishing a session secret, this session, along with the secret, establishing a session secret, this session, along with the secret,
can be used for one or more requests for resources protected by the can be used for one or more requests for resources protected by the
same realm on the same server. Note that session management is only same realm on the same server. Note that session management is only
an inside detail of the protocol and usually not visible to normal an inside detail of the protocol and usually not visible to normal
users. If a session expires, the client and server SHOULD users. If a session expires, the client and server SHOULD
automatically re-establish another session without informing the automatically re-establish another session without informing
user. the user.
Sessions and session identifiers are local to each server (defined by Sessions and session identifiers are local to each server (defined by
scheme, host, and port), even if an authentication scope covers scheme, host, and port), even if an authentication scope covers
multiple servers; clients MUST establish separate sessions for each multiple servers; clients MUST establish separate sessions for each
port of a host to be accessed. Furthermore, sessions and identifiers port of a host to be accessed. Furthermore, sessions and identifiers
are also local to each authentication realm, even if these are are also local to each authentication realm, even if they are
provided by the same server. The same session identifiers provided provided by the same server. The same session identifiers provided
either from different servers or for different realms MUST be treated either from different servers or for different realms MUST be treated
as independent or each other. as being independent of each other.
The server SHOULD accept at least one req-VFY-C request for each The server SHOULD accept at least one req-VFY-C request for each
session, if the request reaches the server in a time window specified session if the request reaches the server in a time window specified
by the timeout parameter in the 401-KEX-S1 message, and there are no by the "timeout" parameter in the 401-KEX-S1 message and if there are
emergent reasons (such as flooding attacks) to forget the session. no emergent reasons (such as flooding attacks) to forget the session.
After that, the server MAY discard any session at any time and MAY After that, the server MAY discard any session at any time and MAY
send 401-STALE messages for any further req-VFY-C requests received send 401-STALE messages for any further req-VFY-C requests received
for that session. for that session.
The client MAY send two or more requests using a single session The client MAY send two or more requests using a single session
specified by the sid. However, for all such requests, each value of specified by the sid. However, for all such requests, each value of
the nonce number (in the nc parameter) MUST satisfy the following the nonce number (in the "nc" parameter) MUST satisfy the following
conditions: conditions:
o It is a natural number. o It is a natural number.
o The same nonce number was not sent within the same session. o The same nonce number was not sent within the same session.
o It is not larger than the nc-max value that was sent from the o It is not larger than the nc-max value that was sent from the
server in the session represented by the sid. server in the session represented by the sid.
o It is larger than (largest-nc - nc-window), where largest-nc is o It is larger than (largest-nc - nc-window), where largest-nc is
the largest value of nc which was previously sent in the session, the largest value of nc that was previously sent in the session
and nc-window is the value of the nc-window parameter that was and nc-window is the value of the "nc-window" parameter that was
received from the server for the session. received from the server for the session.
The last condition allows servers to reject any nonce numbers that The last condition allows servers to reject any nonce numbers that
are "significantly" smaller than the "current" value (defined by the are "significantly" smaller than the "current" value (defined by the
value of nc-window) of the nonce number used in the session involved. value of nc-window) of the nonce number used in the session involved.
In other words, servers MAY treat such nonce numbers as "already In other words, servers MAY treat such nonce numbers as "already
received". This restriction enables servers to implement duplicate received". This restriction enables servers to implement
nonce detection in a constant amount of memory for each session. duplicate-nonce detection in a constant amount of memory for each
session.
Servers MUST check for duplication of the received nonce numbers, and Servers MUST check for duplication of the received nonce numbers, and
if any duplication is detected, the server MUST discard the session if any duplication is detected, the server MUST discard the session
and respond with a 401-STALE message, as outlined in Section 11. The and respond with a 401-STALE message, as outlined in Section 11. The
server MAY also reject other invalid nonce numbers (such as ones server MAY also reject other invalid nonce numbers (such as those
above the nc-max limit) by sending a 401-STALE message. above the nc-max limit) by sending a 401-STALE message.
For example, assume the nc-window value of the current session is For example, assume that the nc-window value of the current session
128, nc-max is 400, and that the client has already used the is 128 and nc-max is 400, and that the client has already used the
following nonce numbers: {1-120, 122, 124, 130-238, 255-360, 363- following nonce numbers: {1-120, 122, 124, 130-238, 255-360,
372}. Then the nonce number that can be used for the next request is 363-372}. The nonce number that can then be used for the next
one of the following set: {245-254, 361, 362, 373-400}. The values request is a number from the following set: {245-254, 361, 362,
{0, 121, 123, 125-129, 239-244} MAY be rejected by the server because 373-400}. The values {0, 121, 123, 125-129, 239-244} MAY be rejected
they are not above the current "window limit" (244 = 372 - 128). by the server because they are not above the current "window limit"
(244 = 372 - 128).
Typically, clients can ensure the above property by using a Typically, clients can ensure the above property by using a
monotonically-increasing integer counter that counts from zero up to monotonically increasing integer counter that counts from zero up to
the value of nc-max. the value of nc-max.
The values of the nonce numbers and any nonce-related values MUST The values of the nonce numbers and any nonce-related values MUST
always be treated as natural numbers within an infinite range. always be treated as natural numbers within an infinite range.
Implementations which uses fixed-width integer representations, Implementations that use fixed-width integer representations,
fixed-precision floating-point numbers, or similar representations fixed-precision floating-point numbers, or similar representations
SHOULD NOT reject any larger values which overflow such SHOULD NOT reject any larger values that overflow such representative
representative limits, and MUST NOT silently truncate them using any limits and MUST NOT silently truncate them using any modulus-like
modulus-like rounding operation (e.g., by mod 2^32). Instead, the rounding operation (e.g., by mod 2^32). Instead, the whole protocol
whole protocol is carefully designed so that recipients MAY replace is carefully designed so that recipients MAY replace any such
any such overflowing values (e.g. 2^80) with some reasonably-large overflowing values (e.g., 2^80) with some reasonably large maximum
maximum representative integer (e.g., 2^31 - 1 or others). representative integer (e.g., 2^31 - 1 or others).
7. Host Validation Methods 7. Host Validation Methods
The "validation method" specifies a method to "relate" (or "bind") The "validation method" specifies a method to "relate" (or "bind")
the mutual authentication processed by this protocol with other the mutual authentication processed by this protocol with other
authentications already performed in the underlying layers and to authentications already performed in the underlying layers and to
prevent man-in-the-middle attacks. It determines the value vh that prevent man-in-the-middle attacks. It determines the value vh that
is an input to the authentication protocols. is an input to the authentication protocols.
When HTTPS or other possible secure transport is used, this When HTTPS or another possible secure transport is used, this
corresponds to the idea of "channel binding" described in [RFC5929]. corresponds to the idea of "channel binding" as described in
Even when HTTP is used, similar, but somewhat limited, "binding" is [RFC5929]. Even when HTTP is used, similar, but somewhat limited,
performed to prevent a malicious server from trying to authenticate "binding" is performed to prevent a malicious server from trying to
itself to another server as a valid user by forwarding the received authenticate itself to another server as a valid user by forwarding
credentials. the received credentials.
The valid tokens for the validation parameter and corresponding The valid tokens for the "validation" parameter and corresponding
values of vh are as follows: values of vh are as follows:
host: host-name validation: The value vh will be the ASCII host:
string in the following format: hostname validation. The value vh will be the ASCII string in the
"<scheme>://<host>:<port>", where <scheme>, <host>, following format: "<scheme>://<host>:<port>", where <scheme>,
and <port> are the URI components corresponding to the <host>, and <port> are the URI components corresponding to the
server-side resource currently being accessed. The server-side resource currently being accessed. The scheme and
scheme and host are in lower case, and the port is in host are in lower case, and the port is listed in shortest decimal
a shortest decimal representation. Even if the notation. Even if the request URI does not have a port part, vh
request-URI does not have a port part, v will include will include the default port number.
the default port number.
tls-server-end-point: TLS endpoint (certificate) validation: The tls-server-end-point:
value vh will be the octet string of the hash value of TLS endpoint (certificate) validation. The value vh will be the
the server's public key certificate used in the octet string of the hash value of the server's public key
underlying TLS [RFC5246] connection, processed as certificate used in the underlying TLS [RFC5246] connection,
specified in Section 4.1 of [RFC5929]. processed as specified in Section 4.1 of [RFC5929].
tls-unique: TLS shared-key validation: The value vh will be the tls-unique:
channel binding material derived from the Finished TLS shared-key validation. The value vh will be the
messages, as defined in Section 3.1 of [RFC5929]. channel-binding material derived from the Finished messages,
(Note: see Section 7.2 for some security notices when as defined in Section 3.1 of [RFC5929]. (Note: See Section 7.2
using this validation method.) for some security-related notes regarding this validation method.)
If HTTP is used on a non-encrypted channel (TCP and SCTP, for If HTTP is used on a non-encrypted channel (TCP and the Stream
example), the validation type MUST be "host". If HTTP/TLS [RFC2818] Control Transmission Protocol (SCTP), for example), the validation
(HTTPS) is used with a server certificate, the validation type MUST type MUST be "host". If HTTP/TLS [RFC2818] (HTTPS) is used with a
be "tls-server-end-point". If HTTP/TLS is used with an anonymous server certificate, the validation type MUST be
"tls-server-end-point". If HTTP/TLS is used with an anonymous
Diffie-Hellman key exchange, the validation type MUST be "tls-unique" Diffie-Hellman key exchange, the validation type MUST be "tls-unique"
(see the note below). (see the note below).
If the validation type "tls-server-end-point" is used, the server If the validation type "tls-server-end-point" is used, the server
certificate provided in the TLS connection MUST be verified at least certificate provided in the TLS connection MUST be verified at least
to make sure that the server actually owns the corresponding private to make sure that the server actually owns the corresponding private
key. (Note: this verification is automatic in some RSA-based key key. (Note: This verification is automatic in some RSA-based key
exchanges but NOT automatic in Diffie-Hellman-based key exchanges exchanges but is NOT automatic in Diffie-Hellman-based key exchanges
with separate exchange for server verification.) with separate exchanges for server verification.)
Clients MUST validate this parameter upon receipt of 401-INIT Clients MUST validate this parameter upon receipt of 401-INIT
messages. messages.
Note: The protocol defines two variants of validation on the TLS Note: The protocol defines two variants of validation on the TLS
connections. The "tls-unique" method is technically more secure. connections. The "tls-unique" method is technically more secure.
However, there are some situations where tls-server-end-point is more However, there are some situations where "tls-server-end-point" is
preferable. preferable:
o When TLS accelerating proxies are used, it is difficult for the o When TLS accelerating proxies are used. In this case, it is
authenticating server to acquire the TLS key information that is difficult for the authenticating server to acquire the TLS key
used between the client and the proxy. This is not the case for information that is used between the client and the proxy. This
client-side "tunneling" proxies using the HTTP CONNECT method. is not the case for client-side "tunneling" proxies using the HTTP
CONNECT method.
o When a black-box implementation of the TLS protocol is used on o When a black-box implementation of the TLS protocol is used on
either peer. either peer.
7.1. Applicability notes 7.1. Applicability Notes
When the client is a Web browser with any scripting capabilities When the client is a Web browser with any scripting capabilities
(dynamic contents support), the underlying TLS channel used with (support of dynamic contents), the underlying TLS channel used with
HTTP/TLS MUST provide server identity verification. This means (1) HTTP/TLS MUST provide server identity verification. This means that
anonymous Diffie-Hellman key exchange cipher suites MUST NOT be used, (1) anonymous Diffie-Hellman key exchange cipher suites MUST NOT be
and (2) verification of the server certificate provided by the server used and (2) verification of the server certificate provided by the
MUST be performed. This is to prevent loading identity- server MUST be performed. This is to prevent loading identity-
unauthenticated scripts or dynamic contents, which are referenced unauthenticated scripts or dynamic contents, which are referenced
from the authenticated page. from the authenticated page.
For other systems, when the underlying TLS channel used with HTTP/TLS For other systems, when the underlying TLS channel used with HTTP/TLS
does not perform server identity verification, the client SHOULD does not perform server identity verification, the client SHOULD
ensure that all responses are validated using the Mutual ensure that all responses are validated using the Mutual
authentication protocol, regardless of the existence of 401-INIT authentication protocol, regardless of the existence of 401-INIT
responses. responses.
7.2. Notes on tls-unique 7.2. Notes on "tls-unique"
As described in the interoperability note in the above channel As described in the interoperability note in Section 3.1 of
binding specification, the tls-unique verification value will be [RFC5929], the "tls-unique" verification value will be changed by
changed by possible TLS renegotiation, causing an interoperability possible TLS renegotiation, causing an interoperability problem. TLS
problem. TLS re-negotiations are used in several HTTPS server renegotiations are used in several HTTPS server implementations for
implementations for enforcing some security properties (such as enforcing some security properties (such as cryptographic strength)
cryptographic strength) for some specific responses. for some specific responses.
If an implementation supports the "tls-unique" verification method, If an implementation supports the "tls-unique" verification method,
the following caution SHOULD be taken: the following precautions SHOULD be taken:
o Both peers must be aware that the vh values used for vkc (in o Both peers must be aware that the vh values used for vkc (in
req-VFY-C) and for vks (in 200-VFY-S) may be different. These req-VFY-C messages) and vks (in 200-VFY-S messages) may be
values MUST be retrieved from underlying TLS libraries each time different. These values MUST be retrieved from underlying TLS
they are used. libraries each time they are used.
o After calculating the values vh and vkc to send a req-VFY-C o After calculating the values vh and vkc to send a req-VFY-C
request, Clients SHOULD NOT initiate TLS renegotiation until the request, clients SHOULD NOT initiate TLS renegotiation until the
end of the corresponding response header is received. An end of the corresponding response header is received. An
exception is that clients can and SHOULD perform TLS re- exception is that clients can and SHOULD perform TLS renegotiation
negotiation as a response to the server's request for TLS as a response to the server's request for TLS renegotiation,
renegotiation, before receipt of the beginning of the response before receipt of the beginning of the response header.
header.
Also, implementers MUST take care of session resumption attacks Also, implementers MUST take care of session resumption attacks
regarding tls-unique channel binding mechanisms and master secrets. regarding "tls-unique" channel-binding mechanisms and master secrets.
As a mitigation, a TLS extension defined in [RFC7627] SHOULD be used As a mitigation, the TLS extension defined in [RFC7627] SHOULD be
when tls-unique host verification is to be used. used when "tls-unique" host verification is to be used.
8. Authentication Extensions 8. Authentication Extensions
Interactive clients (e.g., Web browsers) supporting this protocol are It is RECOMMENDED that interactive clients (e.g., Web browsers)
RECOMMENDED to support non-mandatory authentication and the supporting this protocol support non-mandatory authentication and the
Authentication-Control header defined in Authentication-Control header defined in [RFC8053], except for the
[I-D.ietf-httpauth-extension], except for the "auth-style" parameter. "auth-style" parameter. This specification also proposes (but does
This specification also proposes (however, does not mandate) the not mandate) that the default "auth-style" be "non-modal". Web
default "auth-style" be "non-modal". Web applications SHOULD however applications SHOULD, however, consider the security impacts of the
consider the security impacts of the behaviors of clients that do not behavior of clients that do not support these headers.
support these headers.
Authentication-initializing messages with the Authentication-initializing messages with the
Optional-WWW-Authenticate header are used only where the 401-INIT Optional-WWW-Authenticate header are used only where the 401-INIT
response is valid. It will not replace other 401-type messages such response is valid. It will not replace other 401-type messages such
as 401-STALE and 401-KEX-S1. That is, the reason field of such a as 401-STALE and 401-KEX-S1. That is, the "reason" field of such a
message MUST be "initial" (or any extensive-tokens NOT defined in message MUST be "initial" (or any extensive-tokens NOT defined in
Section 4.1). Section 4.1).
9. String Preparation 9. String Preparation
It is important for interoperability that user names and passwords For interoperability reasons, it is important that usernames and
used in this protocol are binary-comparable regardless of the user's passwords used in this protocol be binary-comparable, regardless of
input methods and/or environments. To ensure this, the following the user's input methods and/or environments. To ensure this, the
preparation SHOULD be performed: following preparation SHOULD be performed:
o User names received from users SHOULD be prepared using the o Usernames received from users SHOULD be prepared using the
"UsernameCasePreserved" profile defined in Section 3.3 of "UsernameCasePreserved" profile defined in Section 3.3 of
[RFC7613]. [RFC7613].
o Passwords received from users SHOULD be prepared using the o Passwords received from users SHOULD be prepared using the
"OpaqueString" profile defined in Section 4.2 of [RFC7613]. "OpaqueString" profile defined in Section 4.2 of [RFC7613].
In both cases, it is the sender's duty to correctly prepare the In both cases, it is the sender's duty to correctly prepare the
character strings. If any non-prepared character string is received character strings. If any non-prepared character string is received
from the other peer of the communication, the behavior of its from the other peer of the communication, the behavior of its
recipient is not defined; the recipient MAY either accept or reject recipient is not defined; the recipient MAY either accept or reject
such input. such input.
Server applications SHOULD also prepare user names and passwords Server applications SHOULD also prepare usernames and passwords
accordingly upon registration of user credentials. accordingly upon registration of user credentials.
In addition, binary-based "interfaces" of implementations MAY require In addition, binary-based "interfaces" of implementations MAY require
and assume that the string is already prepared accordingly; when a and assume that the string is already prepared accordingly; when a
string is already stored as a binary Unicode string form, string is already stored as a binary Unicode string form,
implementations MAY omit preparation and Unicode normalization implementations MAY omit preparation and Unicode normalization
(performing UTF-8 encoding only) before using it. When a string is (performing UTF-8 encoding only) before using it. When a string is
already stored as an octet blob, implementations MAY send it as is. already stored as an octet blob, implementations MAY send it as is.
10. Decision Procedure for Clients 10. Decision Procedure for Clients
10.1. General Principles and Requirements 10.1. General Principles and Requirements
To securely implement the protocol, the client must be careful about To securely implement the protocol, the client must be careful about
accepting the authenticated responses from the server. This also accepting the authenticated responses from the server. This also
holds true for the reception of a "normal response" (a response which holds true for the reception of a "normal response" (a response that
does not contain Mutual authentication-related headers) from HTTP does not contain mutual-authentication-related headers) from HTTP
servers. servers.
As usual in the HTTP authentication, a single user-level request may Per typical HTTP authentication, a single user-level request may
result in exchange of two-or-more HTTP requests and responses in result in the exchange of two or more HTTP requests and responses in
sequence. The following normative rules MUST be followed by the sequence. The following normative rules MUST be followed by the
clients implementing this protocol: clients implementing this protocol:
o Any kind of a "normal response" MUST only be accepted for the very o Any kind of "normal response" MUST only be accepted for the very
first request in the sequence. Any "normal response" returned for first request in the sequence. Any "normal response" returned for
the second or later requests in the sequence SHALL be considered the second or subsequent requests in the sequence SHALL be
invalid. considered invalid.
o In the same principle, if any response is related to an o By the same principle, if any response is related to an
authentication realm which is different from that of the client's authentication realm that is different from that of the client's
request (for example, a 401-INIT message requesting authentication request (for example, a 401-INIT message requesting authentication
on another realm), it MUST only be accepted for the very first on another realm), it MUST only be accepted for the very first
request in the sequence. Such a response returned for a second or request in the sequence. Such a response returned for a second or
later request in the sequence SHALL be considered invalid. subsequent request in the sequence SHALL be considered invalid.
o A req-KEX-C1 message MAY be sent either as a initial request or as o A req-KEX-C1 message MAY be sent as either an initial request or a
a response to 401-INIT or 401-STALE. However, it SHOULD NOT be response to a 401-INIT or 401-STALE message. However, to avoid
infinite loops of messages, the req-KEX-C1 message SHOULD NOT be
sent more than once in the sequence for a single authentication sent more than once in the sequence for a single authentication
realm, to avoid infinite loops of messages. A 401-KEX-S1 response realm. A 401-KEX-S1 response MUST be accepted only when the
MUST be accepted only when the corresponding request is corresponding request is req-KEX-C1.
req-KEX-C1.
o A req-VFY-C message MAY be sent if there is a valid session secret o A req-VFY-C message MAY be sent if there is a valid session secret
shared between the client and the server, established by shared between the client and the server, as established by
req-KEX-C1 and 401-KEX-S1. If any response with 401 status is req-KEX-C1 and 401-KEX-S1 messages. If any response with a
returned for such a message, the corresponding session secret 401 status code is returned for such a message, the corresponding
SHOULD be discarded as unusable. session secret SHOULD be discarded as unusable.
Especially, upon the reception of a 401-STALE response, the client
SHOULD try establishing a new session by sending req-KEX-C1, but
only once within the request/response sequence.
o A 200-VFY-S message MUST be accepted only as a response to In particular, upon the reception of a 401-STALE response, the
req-VFY-C and nothing else. The VK_s values of such response client SHOULD try to establish a new session by sending a
messages MUST always be checked against the correct value, and if req-KEX-C1 message, but only once within the request/response
it is incorrect, the whole response SHOULD be considered invalid. sequence.
o A 200-VFY-S message MUST be accepted only as a response to a
req-VFY-C message and nothing else. The VK_s values of such
response messages MUST always be checked against the correct
value, and if it is incorrect, the whole response SHOULD be
considered invalid.
The final status of the client request following the message exchange The final status of the client request following the message exchange
sequence shall be determined as follows: sequence shall be determined as follows:
o AUTH-SUCCEED: A 200-VFY-S message with the correct VK_s value was o AUTH-SUCCEED: A 200-VFY-S message with the correct VK_s value was
returned in response to the req-VFY-C request in the sequence. returned in response to the req-VFY-C request in the sequence.
o AUTH-REQUIRED: Two cases exists. o AUTH-REQUIRED: Two cases exist:
* A 401-INIT message was returned from the server, and the client * A 401-INIT message was returned from the server, and the client
does not know how to authenticate to the given authentication does not know how to authenticate to the given authentication
realm. realm.
* A 401-INIT response was returned for req-VFY-C (or req-KEX-C1), * A 401-INIT response was returned for a req-VFY-C (or
which means the user-supplied authentication credentials were req-KEX-C1) message, which means that the user-supplied
not accepted. authentication credentials were not accepted.
o UNAUTHENTICATED: a normal response is returned for an initial o UNAUTHENTICATED: A "normal response" is returned for an initial
request of any kind in the sequence. request of any kind in the sequence.
Any kind of response (including a normal response) other than those Any kind of response (including a "normal response") other than those
explicitly allowed in the above rules SHOULD be interpreted as a explicitly allowed in the above rules SHOULD be interpreted as a
fatal communication error. In such cases, the clients MUST NOT fatal communication error. In such cases, the clients MUST NOT
process any data (the response body and other content-related process any data (the response body and other content-related
headers) sent from the server. However, to handle exceptional error headers) sent from the server. However, to handle exceptional error
cases, clients MAY accept a message without an Authentication-Info cases, clients MAY accept a message without an Authentication-Info
header, if it has a Server-Error (5xx) status code. In such cases, header if it has a Server Error (5xx) status code. In such cases,
they SHOULD be careful about processing the body of the content they SHOULD be careful about processing the body of the content
(ignoring it is still RECOMMENDED, as it may possibly be forged by (ignoring it is still RECOMMENDED, as it may possibly be forged by
intermediate attackers), and the client will be in the intermediate attackers), and the client will then have a status of
"UNAUTHENTICATED" status then. "UNAUTHENTICATED".
If a request is a sub-request for a resource included in another If a request is a sub-request for a resource included in another
resource (e.g., embedded images, style sheets, frames etc.), clients resource (e.g., embedded images, style sheets, frames), clients MAY
MAY treat an AUTH-REQUESTED status as the same as an UNAUTHENTICATED treat an AUTH-REQUESTED status the same way they would treat an
status. In other words, the client MAY ignore server's request to UNAUTHENTICATED status. In other words, the client MAY ignore the
start authentication with new credentials via sub-requests. server's request to start authentication with new credentials via
sub-requests.
10.2. State machine for the client (informative) 10.2. State Machine for the Client (Informative)
The following state machine describes the possible request-response The following state machine describes the possible request-response
sequences derived from the above normative rules. If implementers sequences derived from the above normative rules. If implementers
are not quite sure on the security consequences of the above rules, are not quite sure of the security consequences of the above rules,
it is strongly advised to follow the decision procedure below. In we strongly advise that the decision procedure below be followed. In
particular, clients SHOULD NOT accept "normal responses" unless particular, clients SHOULD NOT accept "normal responses" unless
explicitly allowed in the rules. The labels on the steps are for explicitly allowed in the rules. The labels in the steps below are
informational purposes only. Action entries within each step are for informational purposes only. Action entries within each step are
checked in top-to-bottom order, and the first clause satisfied is to checked in top-to-bottom order, and the first clause satisfied is to
be followed. be followed.
Step 1 (step_new_request): Step 1 (step_new_request):
If the client software needs to access a new Web resource, check If the client software needs to access a new Web resource, check
whether the resource is expected to be inside some authentication to see whether the resource is expected to be inside some
realm for which the user has already been authenticated by the authentication realm for which the user has already been
Mutual authentication scheme. If yes, go to Step 2. Otherwise, authenticated via the Mutual authentication scheme. If yes,
go to Step 5. go to Step 2. Otherwise, go to Step 5.
Step 2: Step 2:
Check whether there is an available sid for the expected Check to see whether there is an available sid for the expected
authentication realm. If there is one, go to Step 3. Otherwise, authentication realm. If there is one, go to Step 3. Otherwise,
go to Step 4. go to Step 4.
Step 3 (step_send_vfy_1): Step 3 (step_send_vfy_1):
Send a req-VFY-C request. Send a req-VFY-C request.
* If you receive a 401-INIT message with a different * If a 401-INIT message is received with a different
authentication realm than expected, go to Step 6. authentication realm than expected, go to Step 6.
* If a 401-STALE message is received, go to Step 9. * If a 401-STALE message is received, go to Step 9.
* If a 401-INIT message is received, go to Step 13. * If a 401-INIT message is received, go to Step 13.
* If a 200-VFY-S message is received, go to Step 14. * If a 200-VFY-S message is received, go to Step 14.
* If a normal response is received, go to Step 11. * If a "normal response" is received, go to Step 11.
Step 4 (step_send_kex1_1): Step 4 (step_send_kex1_1):
Send a req-KEX-C1 request. Send a req-KEX-C1 request.
* If a 401-INIT message is received with a different * If a 401-INIT message is received with a different
authentication realm than expected, go to Step 6. authentication realm than expected, go to Step 6.
* If a 401-KEX-S1 message is received, go to Step 10. * If a 401-KEX-S1 message is received, go to Step 10.
* If a 401-INIT message is received with the same authentication * If a 401-INIT message is received with the same authentication
realm, go to Step 13 (see Note 1). realm, go to Step 13 (see Note 1).
* If a normal response is received, go to Step 11. * If a "normal response" is received, go to Step 11.
Step 5 (step_send_normal_1): Step 5 (step_send_normal_1):
Send a request without any Mutual authentication headers. Send a request without any mutual-authentication headers.
* If a 401-INIT message is received, go to Step 6. * If a 401-INIT message is received, go to Step 6.
* If a normal response is received, go to Step 11. * If a "normal response" is received, go to Step 11.
Step 6 (step_rcvd_init): Step 6 (step_rcvd_init):
Check whether the user's password for the requested Check to see whether the user's password for the requested
authentication realm is known. If yes, go to Step 7. Otherwise, authentication realm is known. If yes, go to Step 7. Otherwise,
go to Step 12. go to Step 12.
Step 7: Step 7:
Check whether there is an available sid for the expected Check to see whether there is an available sid for the expected
authentication realm. If there is one, go to Step 8. Otherwise, authentication realm. If there is one, go to Step 8. Otherwise,
go to Step 9. go to Step 9.
Step 8 (step_send_vfy): Step 8 (step_send_vfy):
Send a req-VFY-C request. Send a req-VFY-C request.
* If a 401-STALE message is received, go to Step 9. * If a 401-STALE message is received, go to Step 9.
* If a 401-INIT message is received, go to Step 13. * If a 401-INIT message is received, go to Step 13.
* If a 200-VFY-S message is received, go to Step 14. * If a 200-VFY-S message is received, go to Step 14.
Step 9 (step_send_kex1): Step 9 (step_send_kex1):
Send a req-KEX-C1 request. Send a req-KEX-C1 request.
* If a 401-KEX-S1 message is received, go to Step 10. * If a 401-KEX-S1 message is received, go to Step 10.
* If a 401-INIT message is received, go to Step 13 (See Note 1). * If a 401-INIT message is received, go to Step 13 (see Note 1).
Step 10 (step_rcvd_kex1): Step 10 (step_rcvd_kex1):
Send a req-VFY-C request. Send a req-VFY-C request.
* If a 401-INIT message is received, go to Step 13. * If a 401-INIT message is received, go to Step 13.
* If a 200-VFY-S message is received, go to Step 14. * If a 200-VFY-S message is received, go to Step 14.
Step 11 (step_rcvd_normal): Step 11 (step_rcvd_normal):
The requested resource is out of the authenticated area. The The requested resource is out of the authenticated area. The
client will be in the "UNAUTHENTICATED" status. If the response client will be in the "UNAUTHENTICATED" status. If the response
contains a request for authentications other than Mutual, it MAY contains a request for authentication other than Mutual
be handled normally. authentication, it MAY be handled normally.
Step 12 (step_rcvd_init_unknown): Step 12 (step_rcvd_init_unknown):
The requested resource requires Mutual authentication, and the The requested resource requires Mutual authentication, and the
user is not yet authenticated. The client will be in the "AUTH- user is not yet authenticated. The client will be in the
REQUESTED" status, and is RECOMMENDED to process the content sent "AUTH-REQUESTED" status; it is RECOMMENDED that the client
from the server, and to ask the user for a user name and a process the content sent from the server and ask the user for a
password. When those are supplied from the user, proceed to Step username and password. When those are supplied by the user,
9. go to Step 9.
Step 13 (step_rcvd_init_failed): Step 13 (step_rcvd_init_failed):
For some reason the authentication failed: possibly the password The authentication failed for some reason, possibly because the
or the username is invalid for the authenticated resource. password or username is invalid for the authenticated resource.
Forget the user-provided credentials for the authentication realm Forget the user-provided credentials for the authentication
and go to Step 12. realm, and go to Step 12.
Step 14 (step_rcvd_vfy): Step 14 (step_rcvd_vfy):
The received message is the 200-VFY-S message, which always The received message is the 200-VFY-S message, which always
contains a vks field. Check the validity of the received VK_s contains a "vks" field. Check the validity of the received VK_s
value. If it is equal to the expected value, it means that the value. If it is equal to the expected value, then the mutual
mutual authentication has succeeded. The client will be in the authentication succeeded. The client will be in the
"AUTH-SUCCEEDED" status. "AUTH-SUCCEED" status.
If the value is unexpected, it is a fatal communication error. An unexpected value is interpreted as a fatal communication
error.
If a user explicitly requests to log out (via the user If a user explicitly asks to log out (via the user interface),
interface), the client MUST forget the user's password, go to the client MUST forget the user's password, go to Step 5, and
step 5, and reload the current resource without an authentication reload the current resource without an authentication header.
header.
Note 1: These transitions MAY be accepted by clients, but are Note 1: These transitions MAY be accepted by clients, but it is
NOT RECOMMENDED for servers to initiate. NOT RECOMMENDED that servers initiate them.
Figure 5 shows an informative diagram of the client state. Figure 5 shows an informative diagram of the client state.
=========== -(11)------------ =========== -(11)------------
NEW REQUEST ( UNAUTHENTICATED ) NEW REQUEST ( UNAUTHENTICATED )
=========== ----------------- =========== -----------------
| ^ normal | ^ normal
v | response v | response
+(1)-------------------+ NO +(5)----------+ +(1)-------------------+ NO +(5)----------+
| The requested URI |--------------------------->| send normal | | The requested URI |--------------------------->| send normal |
skipping to change at page 34, line 52 skipping to change at page 35, line 52
| --| req-KEX-C1| | | req-VFY-C | | | req-KEX-C1| | --| req-KEX-C1| | | req-VFY-C | | | req-KEX-C1|
|/ +-----------+ | +-----------+ | +-----------+ |/ +-----------+ | +-----------+ | +-----------+
| |200-VFY-S | 200-VFY-S| ^ | |200-VFY-S | 200-VFY-S| ^
|normal | |200-VFY-S / | |normal | |200-VFY-S / |
|response | v / ================== |response | v / ==================
v \ -(14)--------- / USER/PASS INPUTTED v \ -(14)--------- / USER/PASS INPUTTED
-(11)------------ ------->( AUTH-SUCCEED )<-- ================== -(11)------------ ------->( AUTH-SUCCEED )<-- ==================
( UNAUTHENTICATED ) -------------- ( UNAUTHENTICATED ) --------------
----------------- -----------------
Figure 5: State diagram for clients Figure 5: State Diagram for Clients
11. Decision Procedure for Servers 11. Decision Procedure for Servers
Each server SHOULD have a table of session states. This table need Each server SHOULD have a table of session states. This table need
not be persistent over the long term; it MAY be cleared upon server not be persistent over the long term; it MAY be cleared upon server
restart, reboot, or for other reasons. Each entry in the table restart, reboot, or for other reasons. Each entry in the table
SHOULD contain at least the following information: SHOULD contain at least the following information:
o The session identifier, which is the value of the sid parameter. o The session identifier, which is the value of the "sid" parameter.
o The algorithm used. o The algorithm used.
o The authentication realm. o The authentication realm.
o The state of the protocol: one of "key exchanging", o The state of the protocol: one of "key exchanging",
"authenticated", "rejected", or "inactive". "authenticated", "rejected", or "inactive".
o The user name received from the client. o The username received from the client.
o A boolean flag representing whether or not the session is fake. o A boolean flag indicating whether or not the session is fake.
o When the state is "key exchanging", the values of K_c1 and S_s1. o When the state is "key exchanging", the values of K_c1 and S_s1.
o When the state is "authenticated", the following information: o When the state is "authenticated", the following information:
* The value of the session secret, z * The value of the session secret (z).
* The largest nc received from the client (largest-nc) * The largest nc received from the client (largest-nc).
* For each possible nc values between (largest-nc - nc- * For each possible nc value between (largest-nc - nc-window + 1)
window + 1) and max_nc, a boolean flag whether or not a request and max_nc, a boolean flag indicating whether or not a request
with the corresponding nc has been received. with the corresponding nc has been received.
The table MAY contain other information. The table MAY contain other information.
Servers SHOULD respond to the client requests according to the Servers SHOULD respond to the client requests according to the
following procedure: (See Note 1 below for 401-INIT message with a following procedure (see Note 1 below regarding 401-INIT messages
plus sign) with a plus sign):
o When the server receives a normal request: o When the server receives a "normal request":
* If the requested resource is not protected by the Mutual * If the requested resource is not protected by the Mutual
authentication, send a normal response. authentication, send a "normal response".
* If the resource is protected by the Mutual authentication, send * If the resource is protected by the Mutual authentication, send
a 401-INIT response. a 401-INIT response.
o When the server receives a req-KEX-C1 request: o When the server receives a req-KEX-C1 request:
* If the requested resource is not protected by the Mutual * If the requested resource is not protected by the Mutual
authentication, send a normal response. authentication, send a "normal response".
* If the authentication realm specified in the req-KEX-C1 request * If the authentication realm specified in the req-KEX-C1 request
is not the expected one, send a 401-INIT response. is not the expected realm, send a 401-INIT response.
* If the server cannot validate the parameter kc1, send a * If the server cannot validate the parameter "kc1", send a
401-INIT (+) response. 401-INIT (+) response.
* If the received user name is either invalid, unknown or * If the received username is either invalid, unknown, or
unacceptable, create a new session, mark it a "fake" session, unacceptable, create a new session, mark it as a "fake"
compute a random value as K_s1, and send a fake 401-KEX-S1 session, compute a random value as K_s1, and send a fake
response. (See Note 2.) 401-KEX-S1 response (see Note 2).
* Otherwise, create a new session, compute K_s1 and send a * Otherwise, create a new session, compute K_s1, and send a
401-KEX-S1 response. The created session is marked as not 401-KEX-S1 response. The created session is marked as not
fake, and its largest-nc is initialized to zero. fake, and its largest-nc value is initialized to zero.
The created session has the "key exchanging" state. The created session is in the "key exchanging" state.
o When the server receives a req-VFY-C request: o When the server receives a req-VFY-C request:
* If the requested resource is not protected by the Mutual * If the requested resource is not protected by the Mutual
authentication, send a normal response. authentication, send a "normal response".
* If the authentication realm specified in the req-VFY-C request * If the authentication realm specified in the req-VFY-C request
is not the expected one, send a 401-INIT response. is not the expected realm, send a 401-INIT response.
If none of above holds true, the server will look up the session If none of the above holds true, the server will look up the
corresponding to the received sid and the authentication realm. session corresponding to the received sid and the authentication
realm.
* If the session corresponding to the received sid could not be * If the session corresponding to the received sid could not be
found, or it is in the "inactive" state, send a 401-STALE found or it is in the "inactive" state, send a 401-STALE
response. response.
* If the session is in the "rejected" state, send either a * If the session is in the "rejected" state, send either a
401-INIT (+) or a 401-STALE message. 401-INIT (+) response or a 401-STALE message.
* If the nc value in the request is larger than the nc-max * If the nc value in the request is larger than the "nc-max"
parameter sent from the server, or if it is not larger then parameter sent from the server or it is not larger than
(largest-nc - nc-window) (when in "authenticated" status), the (largest-nc - nc-window) (when in the "authenticated" state),
server MAY (but is not REQUIRED to; See Note 3) send a the server MAY (but is not REQUIRED to; see Note 3) send a
401-STALE message. The session is changed to the "inactive" 401-STALE message. The session is changed to the "inactive"
state if so did. state if the 401-STALE message was sent.
* If the session is in the "authenticated" state, and the request * If the session is in the "authenticated" state and the request
has an nc value that was previously received from the client, has an nc value that was previously received from the client,
send a 401-STALE message. The session it changed to the send a 401-STALE message. The session is changed to the
"inactive" state. "inactive" state.
* If the session is a "fake" session, or if the received vkc is * If the session is a "fake" session or the received vkc is
incorrect, then send a 401-INIT (+) response. If the session incorrect, then send a 401-INIT (+) response. If the session
is in the "key exchanging" state, it MUST be changed to the is in the "key exchanging" state, it MUST be changed to the
"rejected" state; otherwise, it MAY either be changed to the "rejected" state; otherwise, it MAY be either changed to the
"rejected" state or kept in the previous state. "rejected" state or kept in the previous state.
* Otherwise, send a 200-VFY-S response. If the session was in * Otherwise, send a 200-VFY-S response. If the session was in
the "key exchanging" state, the session SHOULD be changed to an the "key exchanging" state, the session SHOULD be changed to
"authenticated" state. The maximum nc and nc flags of the the "authenticated" state. The maximum nc and nc flags of the
state MUST be updated appropriately. state MUST be updated appropriately.
At any time, the server MAY change any state entries with both the At any time, the server MAY change any state entries with both the
"rejected" and "authenticated" states to the "inactive" status, and "rejected" and "authenticated" states to the "inactive" state and MAY
MAY discard any "inactive" states from the table. Entries with the discard any "inactive" states from the table. Entries with the "key
"key exchanging" state SHOULD be kept unless there is an emergency exchanging" state SHOULD be kept unless there is an emergency
situation such as a server reboot or a table capacity overflow. situation such as a server reboot or a table capacity overflow.
Note 1: In relation with and following the specification of the Note 1: In relation to, and following the specification of, the
optional authentication defined in [I-D.ietf-httpauth-extension], the optional authentication defined in [RFC8053], the 401-INIT messages
401-INIT messages marked with the pluses cannot be replaced with a marked with plus signs cannot be replaced with a successful response
successful responses with an Optional-WWW-Authenticate header. Every with an Optional-WWW-Authenticate header. Every other 401-INIT can
other 401-INIT can be a response with an Optional-WWW-Authenticate. be a response with an Optional-WWW-Authenticate header.
Note 2: the server SHOULD NOT send a 401-INIT response in this case, Note 2: The server SHOULD NOT send a 401-INIT response in this case,
because it will leak the information to the client that the specified because it will leak the information to the client that the specified
user name will not be accepted. Instead, postpone it to the response username will not be accepted. Instead, postpone it until the
for the next req-VFY-C request. response to the next req-VFY-C request.
Note 3: The next case implies that, when the request is not rejected Note 3: If the request is not rejected in this clause, the server
in this clause, the server must be able to determine whether the same will be required, in the next step, to determine whether the same nc
nc value was previously received from the client. If the server does value was previously received from the client. If that is
not remember a whole history of the nc values received from the impossible, the server MUST send a 401-STALE response in this step.
client, the server MUST send a 401-STALE message on this clause. If the server does not remember the whole history of the nc values
received from the client, the server MUST send a 401-STALE message in
this clause.
12. Authentication Algorithms 12. Authentication Algorithms
Cryptographic authentication algorithms which are used with this Cryptographic authentication algorithms that are used with this
protocol will be defined separately. The algorithm definition MUST protocol will be defined separately. The algorithm definition MUST
at least provide definitions for the following functions: at least provide definitions for the following functions:
o The server-side authentication credential J, derived from client- o The server-side authentication credential J, derived from the
side authentication credential pi. client-side authentication credential pi.
o Key exchange values K_c1, K_s1 (exchanged on wire) and S_c1, S_s1 o Key exchange values K_c1, K_s1 (exchanged on the wire) and
(kept secret in each peer). S_c1, S_s1 (kept secret in each peer).
o Shared session secret z, to be computed by both server and client. o Shared session secret (z), to be computed by both server and
client.
o A hash function H to be used with the protocol, along with its o A hash function H to be used with the protocol, along with its
output size hSize. output size hSize.
o The number of iterations for password hashing nIterPi, if it uses o The value nIterPi, the number of iterations for the key derivation
the default password hashing function defined below. operation.
Specifications for cryptographic algorithms used with this framework Specifications for cryptographic algorithms used with this framework
MUST specify whether these will use the default functions defined MUST specify whether those algorithms will (1) use the default
below for values pi, VK_c, and VK_s; or, these will define their own functions defined below for values pi, VK_c, and VK_s or (2) define
versions for these. their own comparable functions.
All algorithm used with this protocol SHOULD provide secure mutual All algorithms used with this protocol SHOULD provide secure mutual
authentication between client and servers, and generate a authentication between clients and servers and generate a
cryptographically strong shared secret value z, equivalently strong cryptographically strong shared secret value (z) that is equally
to or stronger than the hash function H. If any passwords (or pass- strong or stronger than the hash function H. If any passwords (or
phrases or any equivalents, i.e., weak secrets) are involved, these passphrases or any equivalents, i.e., weak secrets) are involved,
SHOULD NOT be guessable from any data transmitted in the protocol, these SHOULD NOT be guessable from any data transmitted in the
even if an attacker (either an eavesdropper or an active server) protocol, even if an attacker (either an eavesdropper or an active
knows the possible thoroughly-searchable candidate list of the server) knows the possible thoroughly searchable candidate list of
passwords. Furthermore, if possible, the function J for deriving passwords. Furthermore, it is RECOMMENDED that the function J for
server-side authentication credential J(pi) is RECOMMENDED to be one- deriving the server-side authentication credential J(pi) be one-way,
way so that pi should not be easily computed from J(pi). if possible, so that pi cannot be easily computed from J(pi).
12.1. Support Functions and Notations 12.1. Support Functions and Notations
In this section we define several support functions and notations to In this section, we define several support functions and notations to
be shared by several algorithm definitions. be shared by several algorithm definitions.
The integers in the specification are in decimal, or in hexadecimal The integers in the specification are in decimal, or in hexadecimal
when prefixed with "0x". when prefixed with "0x".
The function octet(i) generates an octet string containing a single The function octet(i) generates an octet string containing a single
octet of value i. The operator |, when applied to octet strings, octet of value i. The operator "|", when applied to octet strings,
denotes the concatenation of two operands. denotes the concatenation of two operands.
The function VI encodes natural numbers into octet strings in the The function VI encodes natural numbers into octet strings in the
following manner: numbers are represented as big-endian radix-128 following manner: numbers are represented as big-endian radix-128
strings, where each digit is represented by an octet within the range strings, where each digit is represented by an octet within the range
0x80-0xff except the last digit, which is represented by a octet 0x80-0xff, except for the last digit, which is represented by an
within the range 0x00-0x7f. The first octet MUST NOT be 0x80. For octet within the range 0x00-0x7f. The first octet MUST NOT be 0x80.
example, VI(i) = octet(i) for i < 128, and VI(i) = octet(0x80 + (i >> For example, VI(i) = octet(i) for i < 128, and
7)) | octet(i & 127) for 128 <= i < 16384. This encoding is the same VI(i) = octet(0x80 + (i >> 7)) | octet(i & 127) for 128 <= i < 16384.
as the one used for the sub-components of object identifiers in the This encoding is the same as the encoding used for the subcomponents
ASN.1 encoding [ITU.X690.1994], and available as a "w" conversion in of object identifiers in ASN.1 encoding [ITU.X690.2015] and is
the "pack" function of several scripting languages. available as a "w" conversion in the "pack" function of several
scripting languages.
The function VS encodes a variable-length octet string into a The function VS encodes a variable-length octet string into a
uniquely-decoded, self-delimited octet string, as in the following uniquely decoded, self-delimited octet string in the following
manner: manner:
VS(s) = VI(length(s)) | s VS(s) = VI(length(s)) | s
where length(s) is a number of octets (not characters) in s. where length(s) is a number of octets (not characters) in s.
Some examples: Some examples:
VI(0) = "\000" (in C string notation) VI(0) = "\000" (in C string notation)
skipping to change at page 39, line 33 skipping to change at page 40, line 47
VI(1000000) = "\275\204@" VI(1000000) = "\275\204@"
VS("") = "\000" VS("") = "\000"
VS("Tea") = "\003Tea" VS("Tea") = "\003Tea"
VS("Caf<e acute>" [in UTF-8]) = "\005Caf\303\251" VS("Caf<e acute>" [in UTF-8]) = "\005Caf\303\251"
VS([10000 "a"s]) = "\316\020aaaaa..." (10002 octets) VS([10000 "a"s]) = "\316\020aaaaa..." (10002 octets)
(Note: Unlike the colon-separated notion used in the Basic/Digest (Note: Unlike the colon-separated format used in the Basic and Digest
HTTP authentication scheme, the string generated by a concatenation HTTP authentication schemes, the string generated by a concatenation
of the VS-encoded strings will be unique, regardless of the of the VS-encoded strings will be unique, regardless of the
characters included in the strings to be encoded.) characters included in the strings to be encoded.)
The function OCTETS converts an integer into the corresponding
The function OCTETS converts an integer into the corresponding radix- radix-256 big-endian octet string having its natural length. See
256 big-endian octet string having its natural length. See
Section 3.2.3 for the definition of "natural length". Section 3.2.3 for the definition of "natural length".
The function INT converts an octet string into a natural number, The function INT converts an octet string into a natural number,
where the input string is treated as being in radix-256 big-endian where the input string is treated as being in radix-256 big-endian
notation. The identity INT(OCTETS(n)) = n always holds for any notation. The identity INT(OCTETS(n)) = n always holds for any
natural number n. natural number n.
12.2. Default Functions for Algorithms 12.2. Default Functions for Algorithms
The functions defined in this section are common default functions The functions defined in this section are common default functions
among authentication algorithms. among authentication algorithms.
The client-side password-based (credential) pi used by this The client-side password-based (credential) pi used by this
authentication is a natural number derived in the following manner: authentication is a natural number derived in the following manner:
pi = INT(PBKDF2(HMAC_H, password, VS(algorithm) | VS(auth-scope) | pi = INT(PBKDF2(HMAC_H, password, VS(algorithm) | VS(auth-scope) |
VS(realm) | VS(username), nIterPi, hSize / 8)), VS(realm) | VS(username), nIterPi, hSize / 8))
where where
o PBKDF2 is the password-based key derivation function defined in o PBKDF2 is the password-based key derivation function defined in
[RFC2898], [RFC8018],
o HMAC_H is the HMAC function, defined in [RFC2104], composed from o HMAC_H is the Hashed Message Authentication Code (HMAC) function,
the hash function H, and defined in [RFC2104], composed from the hash function H, and
o hSize is the output size of hash H in bits. o hSize is the output size of hash H in bits.
The values of algorithm, realm, and auth-scope are taken from the The values of algorithm, realm, and auth-scope are taken from the
values contained in the 401-INIT message. If the password comes from values contained in the 401-INIT message. If the password comes from
user input, it SHOULD first be prepared according to the method user input, it SHOULD first be prepared according to the method
presented in Section 9. Then, the password SHALL be encoded as a presented in Section 9. Then, the password SHALL be encoded as a
UTF-8 string. UTF-8 string.
The values VK_c and VK_s are derived by the following equation. The values VK_c and VK_s are derived via the following equations:
VK_c = INT(H(octet(4) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VK_c = INT(H(octet(4) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) |
VI(nc) | VS(vh))) VI(nc) | VS(vh)))
VK_s = INT(H(octet(3) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VK_s = INT(H(octet(3) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) |
VI(nc) | VS(vh))) VI(nc) | VS(vh)))
13. Application Channel Binding 13. Application Channel Binding
Applications and upper-layer communication protocols may need Applications and upper-layer communication protocols may need
authentication binding to the HTTP-layer authenticated user. Such authentication binding to the HTTP-layer authenticated user. Such
applications MAY use the following values as a standard shared applications MAY use the following values as a standard shared
secret. secret.
These values are parameterized with an optional octet string (t) These values are parameterized with an optional octet string (t),
which may be arbitrarily chosen by each application or protocol. If which may be arbitrarily chosen by each application or protocol. If
there is no appropriate value to be specified, use an empty string there is no appropriate value to be specified, use an empty string
for t. for t.
For applications requiring binding to either an authenticated user or For applications requiring binding to either an authenticated user or
a shared-key session (to ensure that the requesting client is a shared-key session (to ensure that the requesting client is
certainly authenticated), the following value b_1 MAY be used. authenticated), the following value b_1 MAY be used:
b_1 = H(H(octet(6) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VI(0) b_1 = H(H(octet(6) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) |
| VS(vh)) | VS(t)). VI(0) | VS(vh)) | VS(t))
For applications requiring binding to a specific request (to ensure For applications requiring binding to a specific request (to ensure
that the payload data is generated for the exact HTTP request), the that the payload data is generated for the exact HTTP request), the
following value b_2 MAY be used. following value b_2 MAY be used:
b_2 = H(H(octet(7) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) | VI(nc) b_2 = H(H(octet(7) | OCTETS(K_c1) | OCTETS(K_s1) | OCTETS(z) |
| VS(vh)) | VS(t)). VI(nc) | VS(vh)) | VS(t))
Note: Channel bindings to lower-layer transports (TCP and TLS) are Note: Channel bindings to lower-layer transports (TCP and TLS) are
defined in Section 7. defined in Section 7.
14. Application for Proxy Authentication 14. Application for Proxy Authentication
The authentication scheme defined by the previous sections can be The authentication scheme defined in the previous sections can be
applied (with modifications) for proxy authentication. In such applied (with modifications) to proxy authentication. In such cases,
cases, the following alterations MUST be applied: the following alterations MUST be applied:
o The 407 status is to be sent and recognized in places where the o The 407 (Proxy Authentication Required) status code is to be sent
401 status is used, and recognized in places where the 401 status code is used,
o Proxy-Authenticate header is to be used in places where WWW- o The Proxy-Authenticate header is to be used in places where the
Authenticate is used, WWW-Authenticate header is used,
o Proxy-Authorization header is to be used in places where o The Proxy-Authorization header is to be used in places where the
Authorization is used, Authorization header is used,
o Proxy-Authentication-Info header is to be used in places where o The Proxy-Authentication-Info header is to be used in places where
Authentication-Info is used, the Authentication-Info header is used,
o The auth-scope parameter is fixed to the host-name of the proxy, o The "auth-scope" parameter is fixed to the hostname of the proxy,
which means it covers all requests processed through the specific which means that it covers all requests processed by the specific
proxy, proxy,
o The limitation for the paths contained in the path parameter of o The limitation for the paths contained in the "path" parameter of
401-KEX-S1 messages is disregarded, 401-KEX-S1 messages is disregarded,
o The omission of the path parameter of 401-KEX-S1 messages means o The omission of the "path" parameter of 401-KEX-S1 messages means
that the authentication realm will potentially cover all requests that the authentication realm will potentially cover all requests
processed by the proxy, processed by the proxy,
o The scheme, host name, and the port of the proxy is used for host o The scheme, hostname, and port of the proxy are used for host
validation tokens, and validation tokens, and
o Authentication extensions in [I-D.ietf-httpauth-extension] are not o Authentication extensions defined in [RFC8053] are not applicable.
applicable.
15. Methods to Extend This Protocol 15. Methods to Extend This Protocol
If a private extension to this protocol is implemented, it MUST use If a private extension to this protocol is implemented, it MUST use
the extension-tokens defined in Section 3 to avoid conflicts with the extension-tokens defined in Section 3 to avoid conflicts with
this protocol and other extensions. (Standardized or being- this protocol and other extensions. (Standardized extensions, as
standardized extensions MAY use either bare-tokens or extension- well as extensions that are in the process of being standardized, MAY
tokens.) use either bare-tokens or extension-tokens.)
Specifications defining authentication algorithms MAY use other Specifications defining authentication algorithms MAY use other
representations for the parameters "kc1", "ks1", "vkc", and "vks", representations for the parameters "kc1", "ks1", "vkc", and "vks";
replace those parameter names, and/or add parameters to the messages replace those parameter names; and/or add parameters to the messages
containing those parameters in supplemental specifications, provided containing those parameters in supplemental specifications, provided
that syntactic and semantic requirements in Section 3, [RFC7230] and that syntactic and semantic requirements in Section 3 of this
[RFC7235] are satisfied. Any parameters starting with "kc", "ks", document, [RFC7230], and [RFC7235] are satisfied. Any parameters
"vkc" or "vks" and followed by decimal natural numbers (e.g. kc2, starting with "kc", "ks", "vkc", or "vks" and followed by decimal
ks0, vkc1, vks3 etc.) are reserved for this purpose. If those natural numbers (e.g., kc2, ks0, vkc1, vks3) are reserved for this
specifications use names other than those mentioned above, it is purpose. If those specifications use names other than those
RECOMMENDED to use extension-tokens to avoid any parameter name mentioned above, it is RECOMMENDED that extension-tokens be used to
conflict with future extensions to this protocol. avoid any parameter-name conflicts with future extensions to this
protocol.
Extension-tokens MAY be freely used for any non-standard, private, Extension-tokens MAY be freely used for any non-standard, private,
and/or experimental uses for those parameters provided that the and/or experimental uses for those parameters provided that the
domain part in the token is used in the manner defined in Section 3. domain part in the token is used in the manner defined in Section 3.
16. IANA Considerations 16. IANA Considerations
This document requires an additional entry to the "Hypertext Transfer 16.1. Addition to HTTP Authentication Schemes Registry
Protocol (HTTP) Authentication Scheme Registry" as follows:
o Authentication Scheme Name: "Mutual" IANA has added the following entry to the "HTTP Authentication
Schemes" registry:
o Pointer to specification text: (this document) o Authentication Scheme Name: Mutual
When bare-tokens are used for the authentication-algorithm and o Reference: RFC 8120
validation parameters, these MUST be allocated by IANA. To acquire
registered tokens, the usage of such tokens MUST be reviewed by a
designated expert, as outlined in [RFC5226].
16.1. Registry for Authentication Algorithms 16.2. Registry for Authentication Algorithms
This document establishes a registry for HTTP Mutual authentication This document establishes the "HTTP Mutual Authentication Algorithms"
algorithms. The registry manages case-insensitive ASCII strings. registry. The registry manages case-insensitive ASCII strings. The
The strings MUST follow the extensive-token syntax defined in strings MUST follow the extensive-token syntax defined in Section 3.
Section 3.
When bare-tokens are used for the authentication-algorithm parameter,
they MUST be allocated by IANA. To acquire registered tokens, the
usage of such tokens MUST be reviewed by a Designated Expert, as
outlined in [RFC5226].
Registrations for an authentication algorithm are required to include Registrations for an authentication algorithm are required to include
a description of the authentication algorithms. Reviewers assigned descriptions of the authentication algorithms. Reviewers assigned by
by IESG are advised to examine minimum security requirements and the IESG are advised to examine minimum security requirements and
consistency of the key exchange algorithm descriptions. consistency of the key exchange algorithm descriptions.
New registrations are advised to provide the following information: It is advised that new registrations provide the following
information:
o Token: a token used in HTTP headers for identifying the algorithm. o Token: A token used in HTTP headers for identifying the algorithm.
o Description: A brief description of the algorithm. o Description: A brief description of the algorithm.
o Specification: A reference for a specification defining the o Specification: A reference for a specification defining the
algorithm. algorithm.
The initial content of this registry is empty. [[Editorial Note: A [RFC8121] defines the initial contents of this registry.
separate document [I-D.ietf-httpauth-mutual-algo] will effectively
define the initial content of the registry.]]
16.2. Registry for Validation Methods 16.3. Registry for Validation Methods
This document establishes a registry for HTTP Mutual authentication This document establishes the "HTTP Mutual Authentication Host
host validation methods. The registry manages case-insensitive ASCII Validation Methods" registry. The registry manages case-insensitive
strings. The strings MUST follow the extensive-token syntax defined ASCII strings. The strings MUST follow the extensive-token syntax
in Section 3. defined in Section 3.
When bare-tokens are used for the validation parameter, they MUST be
allocated by IANA. To acquire registered tokens, the usage of such
tokens MUST be reviewed by a Designated Expert, as outlined in
[RFC5226].
Registrations for a validation method are required to include a Registrations for a validation method are required to include a
description of the validation method. Reviewers assigned by IESG are description of the validation method. Reviewers assigned by the IESG
advised to examine its use-case requirements and security consequence are advised to examine its use-case requirements and any security
of its introduction. consequences related to its introduction.
New registrations are advised to provide the following information: It is advised that new registrations provide the following
information:
o Token: a token used in HTTP headers for identifying the method. o Token: A token used in HTTP headers for identifying the method.
o Description: A brief description of the method. o Description: A brief description of the method.
o Specification: A reference for a specification defining the o Specification: A reference for a specification defining the
method. method.
The initial content of this registry is as follows: The initial contents of this registry are as follows:
+----------------------+----------------------------+---------------+ +----------------------+------------------------+----------------+
| Token | Description | Specification | | Token | Description | Reference |
+----------------------+----------------------------+---------------+ +----------------------+------------------------+----------------+
| host | Host name verification | Section 7 | | host | Hostname verification | RFC 8120, |
| | only | | | | only | Section 7 |
| tls-server-end-point | TLS certificate-based | Section 7 | | | | |
| tls-unique | TLS unique key-based | Section 7 | | tls-server-end-point | TLS certificate-based | RFC 8120, |
+----------------------+----------------------------+---------------+ | | | Section 7 |
| | | |
| tls-unique | TLS unique key-based | RFC 8120, |
| | | Section 7 |
+----------------------+------------------------+----------------+
17. Security Considerations 17. Security Considerations
17.1. Security Properties 17.1. Security Properties
o The protocol is secure against passive eavesdropping and replay o The protocol is secure against passive eavesdropping and replay
attacks. However, the protocol relies on transport security attacks. However, the protocol relies on transport security
including DNS integrity for data secrecy and integrity. HTTP/TLS (including DNS integrity) for data secrecy and integrity.
SHOULD be used where transport security is not assured and/or data HTTP/TLS SHOULD be used where transport security is not assured
confidentiality is important. and/or data confidentiality is important.
o When used with HTTP/TLS, if TLS server certificates are reliably o When used with HTTP/TLS, if TLS server certificates are reliably
verified, the protocol provides true protection against active verified, the protocol provides true protection against active
man-in-the-middle attacks. man-in-the-middle attacks.
o Even if the server certificate is not used or is unreliable, the o Even if the server certificate is not used or is unreliable, the
protocol provides protection against active man-in-the-middle protocol provides protection against active man-in-the-middle
attacks for each HTTP request/response pair. However, in such attacks for each HTTP request/response pair. However, in such
cases, JavaScript or similar scripting facilities can be used to cases, JavaScript or similar scripts that are not authenticated by
affect the Mutually-authenticated contents from other contents not this authentication mechanism can affect mutually authenticated
protected by this authentication mechanism. This is the reason contents to circumvent the protection. This is why this protocol
why this protocol requires that valid TLS server certificates MUST stipulates that valid TLS server certificates MUST be shown from
be presented (Section 7). the server to the client (Section 7).
17.2. Secrecy of Credentials 17.2. Secrecy of Credentials
The client-side password credential MUST be kept secret all the time, The client-side password credential MUST always be kept secret and
and SHOULD NOT be used with any other (possibly insecure) SHOULD NOT be used for any other (possibly insecure) authentication
authentication purpose. Loss of control of the credential will purposes. Loss of control of the credential will directly affect the
directly affect the control of corresponding server-side account. control of the corresponding server-side account.
Use of client-side credential with THIS authentication scheme is The use of a client-side credential with THIS authentication scheme
always safe, even if the connected server peer is not trustful is always safe, even if the connected server peer is not trustworthy
(condition of Phishing). However, if it is used with other (e.g., a phishing scenario). However, if it is used with other
authentication schemes (such as Web forms), and if the recipient is authentication schemes (such as Web forms) and the recipient is
rogue, the result will be obvious. rogue, the result will be obvious.
The server-side password credential (J) is also important to be kept It is also important that the server-side password credential (J) be
secret. If it is stolen, and if the client's choice of password is kept secret. If it is stolen and the client's choice of password is
not strong, the person aware of server-side password credential can not strong, anyone who is aware of the server-side password
employ a off-line dictionary attack to search for the client credential can employ an offline dictionary attack to search for the
password. However, if the client has chosen a strong password, so client's password. However, if the client has chosen a strong
that the attacker cannot guess the client's password from dictionary password so that an attacker cannot guess the client's password from
candidate, the client is still well protected from any attacks. dictionary candidates, the client is still well protected from any
attacks.
The shared session secret (z) MUST be kept secret inside the server/ The shared session secret (z) MUST be kept secret inside the
client software; if it is lost, and if the session is still active, server/client software; if it is lost and the session is still
it will lead to session hijacking. After the session is expired, the active, session hijacking will result. After the session expires,
key is valueless for attackers. the key is of no value to attackers.
17.3. Denial-of-service Attacks to Servers 17.3. Denial-of-Service Attacks on Servers
The protocol requires a server-side table of active sessions, which The protocol requires a server-side table of active sessions, which
may become a critical point for server resource consumption. For may become a critical point for server resource consumption. For
proper operation, the protocol requires that at least one key proper operation, the protocol requires that at least one key
verification request is processed for each session identifier. After verification request be processed for each session identifier. After
that, servers MAY discard sessions internally at any time, without that, servers MAY discard sessions internally at any time without
causing any operational problems to clients. Clients will silently causing any operational problems for clients. Clients will then
reestablish a new session then. silently re-establish a new session.
However, if a malicious client sends too many requests for key However, if a malicious client sends too many requests for key
exchanges (req-KEX-C1 messages) only, resource starvation might exchanges (req-KEX-C1 messages) only, resource starvation might
occur. In such critical situations, servers MAY discard any kind of occur. In such critical situations, servers MAY discard any kind of
existing sessions regardless of their statuses. One way to mitigate existing sessions, regardless of their statuses. One way to mitigate
such attacks is that servers MAY have a number and a time limit for such attacks is that servers MAY set number and time limits for
unverified, pending key exchange requests (in the "key exchanging" unverified, pending key exchange requests (in the "key exchanging"
state). state).
This is a common weakness of authentication protocols with almost any This is a common weakness of authentication protocols with almost any
kind of negotiations or states, including Digest authentication kind of negotiations or states, including the Digest authentication
scheme and most Cookie-based authentication implementations. scheme and most cookie-based authentication implementations.
However, regarding the resource consumption, the situation for the However, regarding resource consumption, the situation for the
mutual authentication scheme is a slightly better than for Digest, Mutual authentication scheme is slightly better than that for Digest,
because HTTP requests without any kind of authentication requests because HTTP requests without any kind of authentication requests
will not generate any kind of sessions. Session identifiers are only will not generate any kind of sessions. Session identifiers are only
generated after a client starts a key negotiation. It means that generated after a client starts a key negotiation, so that simple
simple clients such as Web crawlers will not accidentally consume clients such as Web crawlers will not accidentally consume
server-side resources for session managements. server-side resources for session management.
17.3.1. On-line Active Password Attacks 17.3.1. Online Active Password Attacks
Although the protocol provides very strong protection against off- Although the protocol provides very strong protection against offline
line dictionary attacks from eavesdropped traffic, the protocol, by dictionary attacks from eavesdropped traffic, the protocol, by its
its nature, cannot prevent active password attacks in which the nature, cannot prevent active password attacks in which an attacker
attackers sends so many authentication trial requests for every sends so many authentication trial requests for every possible
possible password. password.
Possible countermeasures for preventing such attacks may be rate- Possible countermeasures for preventing such attacks may be the
limiting of password authentication trials, statistics-based rate-limiting of password authentication trials, statistics-based
intrusion detection measures, or similar protection schemes. If the intrusion-detection measures, or similar protection schemes. If the
server operators assume that the passwords of users are not strong server operators assume that the passwords of users are not strong
enough, it may be desirable to introduce such ad-hoc countermeasures. enough, it may be desirable to introduce such ad hoc countermeasures.
17.4. Communicating the status of mutual authentication with users 17.4. Communicating the Status of Mutual Authentication with Users
This protocol is designed for two goals. The first goal is just This protocol is designed with two goals in mind. The first goal is
providing a secure alternative for existing Basic and Digest simply to provide a secure alternative to existing Basic and Digest
authentication. The second goal is to provide users a way to detect authentication schemes. The second goal is to provide users with a
forged rogue servers imitating a user's registered account on a way to detect forged rogue servers imitating (e.g., via a phishing
server, commonly known as (a part or kind of) Phishing attacks. attack) a user's registered account on a server.
For this protocol to effectively work as some countermeasure to such For this protocol to effectively work as a countermeasure against
attacks, it is very important that end users of clients be notified such attacks, it is very important that end users of clients be
of the result of the mutual authentication performed by this notified of the result of mutual authentication performed by this
protocol, especially the three states "AUTH-SUCCEED", protocol, especially the three states "AUTH-SUCCEED",
"UNAUTHENTICATED", and "AUTH-REQUIRED" defined in Section 10. The "AUTH-REQUIRED", and "UNAUTHENTICATED" as defined in Section 10. The
design of secure user interfaces of the HTTP interactive clients is design of secure user interfaces for HTTP interactive clients is out
out of the scope of this document, but if possible, having some kind of scope for this document, but if possible, having some kind of UI
of UI indication for the three states above will be desirable for the indication for the three states above will be desirable from the
user's security benefit. standpoint of providing user security.
Of course, in such cases, the user interfaces for asking passwords Of course, in such cases, the user interfaces for requesting
for this authentication shall be clearly identifiable against passwords for this authentication shall be protected against
imitation by other insecure password input fields (such as forms). imitation (for example, by other insecure password input fields, such
If the passwords are known to malicious attackers outside of the as forms). If the passwords are known to malicious attackers outside
protocol, the protocol cannot work as an effective security measures. of the protocol, the protocol cannot work as an effective security
measure.
17.5. Implementation Considerations 17.5. Implementation Considerations
o To securely implement the protocol, the Authentication-Info o To securely implement the protocol, the Authentication-Info
headers in the 200-VFY-S messages MUST always be validated by the headers in the 200-VFY-S messages MUST always be validated by the
client. If the validation fails, the client MUST NOT process any client. If the validation fails, the client MUST NOT process any
content sent with the message, including other headers and the content sent with the message, including other headers and the
body part. Non-compliance to this requirement will allow phishing body part. Non-compliance with this requirement will allow
attacks. phishing attacks.
o For HTTP/TLS communications, when a web form is submitted from o For HTTP/TLS communications, when a Web form is submitted from
Mutually-authenticated pages with the "tls-server-end-point" mutually authenticated pages via the "tls-server-end-point"
validation method to a URI that is protected by the same realm (so validation method to a URI that is protected by the same realm
indicated by the path parameter), if the server certificate has (so indicated by the "path" parameter), if the server certificate
been changed since the pages were received, the peer is has been changed since the pages were received, it is RECOMMENDED
RECOMMENDED to be re-validated using a req-KEX-C1 message with an that the peer be revalidated using a req-KEX-C1 message with an
"Expect: 100-continue" header. The same applies when the page is "Expect: 100-continue" header. The same applies when the page is
received with the "tls-unique" validation method, and when the TLS received via the "tls-unique" validation method and when the TLS
session has expired. session has expired.
o For better protection against possible password database stealing, o For better protection against possible password database stealing,
server-side storage of user passwords should contain the values server-side storage of user passwords should contain the values
encrypted by the one-way function J(pi), instead of the real encrypted by the one-way function J(pi) instead of the real
passwords or those hashed by pi. passwords or those hashed by pi.
o If the TLS 1.2 is used for underlying HTTP/TLS communications, o If TLS 1.2 [RFC5246] is used for underlying HTTP/TLS
follow best practices in [RFC7525]. communications, follow the best practices specified in [RFC7525].
17.6. Usage Considerations 17.6. Usage Considerations
o The user names inputted by a user may be sent automatically to any o The usernames inputted by a user may be sent automatically to any
servers sharing the same auth-scope. This means that when a host- servers sharing the same auth-scope. This means that when a
type auth-scope is used for authentication on an HTTPS site, and host-type auth-scope is used for authentication on an HTTPS site
when an HTTP server on the same host requests Mutual and an HTTP server on the same host requests the Mutual
authentication within the same realm, the client will send the authentication scheme within the same realm, the client will send
user name in clear text. If user names have to be kept secret the username in clear text. If usernames have to be kept secret
against eavesdropping, the server must use the full-scheme-type (protected from eavesdroppers), the server must use the
auth-scope parameter and HTTPS. Contrarily, passwords are not full-scheme-type "auth-scope" parameter and HTTPS. Passwords, on
exposed to eavesdroppers even on HTTP requests. the other hand, are not exposed to eavesdroppers, even in HTTP
requests.
o If the server provides several ways for storing server-side o If the server provides several ways to store server-side password
password secrets in the password database, it is desirable for secrets in the password database, it is desirable, for purposes of
better security to store the values encrypted by using the one-way better security, to store the values encrypted by using the
function J(pi), instead of the real passwords or those hashed by one-way function J(pi) instead of the real passwords or those
pi. hashed by pi.
18. References 18. References
18.1. Normative References 18.1. Normative References
[I-D.ietf-httpauth-extension] [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC:
Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi, Keyed-Hashing for Message Authentication", RFC 2104,
T., and Y. Ioku, "HTTP Authentication Extensions for
Interactive Clients", draft-ietf-httpauth-extension-09
(work in progress), August 2016.
[RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
Hashing for Message Authentication", RFC 2104,
DOI 10.17487/RFC2104, February 1997, DOI 10.17487/RFC2104, February 1997,
<http://www.rfc-editor.org/info/rfc2104>. <http://www.rfc-editor.org/info/rfc2104>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ Requirement Levels", BCP 14, RFC 2119,
RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography [RFC3629] Yergeau, F., "UTF-8, a transformation format of
Specification Version 2.0", RFC 2898, DOI 10.17487/ ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629,
RFC2898, September 2000,
<http://www.rfc-editor.org/info/rfc2898>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629,
November 2003, <http://www.rfc-editor.org/info/rfc3629>. November 2003, <http://www.rfc-editor.org/info/rfc3629>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<http://www.rfc-editor.org/info/rfc4648>. <http://www.rfc-editor.org/info/rfc4648>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ Syntax Specifications: ABNF", STD 68, RFC 5234,
RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>. <http://www.rfc-editor.org/info/rfc5234>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ (TLS) Protocol Version 1.2", RFC 5246,
RFC5246, August 2008, DOI 10.17487/RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>. <http://www.rfc-editor.org/info/rfc5246>.
[RFC5987] Reschke, J., "Character Set and Language Encoding for [RFC5987] Reschke, J., "Character Set and Language Encoding for
Hypertext Transfer Protocol (HTTP) Header Field Hypertext Transfer Protocol (HTTP) Header Field
Parameters", RFC 5987, DOI 10.17487/RFC5987, August 2010, Parameters", RFC 5987, DOI 10.17487/RFC5987, August 2010,
<http://www.rfc-editor.org/info/rfc5987>. <http://www.rfc-editor.org/info/rfc5987>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7230] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext
Protocol (HTTP/1.1): Message Syntax and Routing", Transfer Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014, RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>. <http://www.rfc-editor.org/info/rfc7230>.
[RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7235] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext
Protocol (HTTP/1.1): Authentication", RFC 7235, Transfer Protocol (HTTP/1.1): Authentication", RFC 7235,
DOI 10.17487/RFC7235, June 2014, DOI 10.17487/RFC7235, June 2014,
<http://www.rfc-editor.org/info/rfc7235>. <http://www.rfc-editor.org/info/rfc7235>.
[RFC7613] Saint-Andre, P. and A. Melnikov, "Preparation, [RFC7613] Saint-Andre, P. and A. Melnikov, "Preparation,
Enforcement, and Comparison of Internationalized Strings Enforcement, and Comparison of Internationalized Strings
Representing Usernames and Passwords", RFC 7613, Representing Usernames and Passwords", RFC 7613,
DOI 10.17487/RFC7613, August 2015, DOI 10.17487/RFC7613, August 2015,
<http://www.rfc-editor.org/info/rfc7613>. <http://www.rfc-editor.org/info/rfc7613>.
[RFC7615] Reschke, J., "HTTP Authentication-Info and Proxy- [RFC7615] Reschke, J., "HTTP Authentication-Info and
Authentication-Info Response Header Fields", RFC 7615, Proxy-Authentication-Info Response Header Fields",
DOI 10.17487/RFC7615, September 2015, RFC 7615, DOI 10.17487/RFC7615, September 2015,
<http://www.rfc-editor.org/info/rfc7615>. <http://www.rfc-editor.org/info/rfc7615>.
[RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5:
Password-Based Cryptography Specification Version 2.1",
RFC 8018, DOI 10.17487/RFC8018, January 2017,
<http://www.rfc-editor.org/info/rfc8018>.
[RFC8053] Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi,
T., and Y. Ioku, "HTTP Authentication Extensions for
Interactive Clients", RFC 8053, DOI 10.17487/RFC8053,
January 2017, <http://www.rfc-editor.org/info/rfc8053>.
[Unicode] The Unicode Consortium, "The Unicode Standard", [Unicode] The Unicode Consortium, "The Unicode Standard",
<http://www.unicode.org/versions/latest/>. <http://www.unicode.org/versions/latest/>.
18.2. Informative References 18.2. Informative References
[I-D.ietf-httpauth-mutual-algo] [ITU.X690.2015]
Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi, International Telecommunication Union, "Information
T., and Y. Ioku, "Mutual Authentication Protocol for HTTP:
KAM3-based Cryptographic Algorithms",
draft-ietf-httpauth-mutual-algo-07 (work in progress),
November 2016.
[ITU.X690.1994]
International Telecommunications Union, "Information
Technology - ASN.1 encoding rules: Specification of Basic Technology - ASN.1 encoding rules: Specification of Basic
Encoding Rules (BER), Canonical Encoding Rules (CER) and Encoding Rules (BER), Canonical Encoding Rules (CER) and
Distinguished Encoding Rules (DER)", ITU-T Recommendation Distinguished Encoding Rules (DER)", ITU-T Recommendation
X.690, 1994. X.690, ISO/IEC 8825-1, August 2015,
<https://www.itu.int/rec/T-REC-X.690/>.
[RFC1939] Myers, J. and M. Rose, "Post Office Protocol - Version 3", [RFC1939] Myers, J. and M. Rose, "Post Office Protocol - Version 3",
STD 53, RFC 1939, DOI 10.17487/RFC1939, May 1996, STD 53, RFC 1939, DOI 10.17487/RFC1939, May 1996,
<http://www.rfc-editor.org/info/rfc1939>. <http://www.rfc-editor.org/info/rfc1939>.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/ [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
RFC2818, May 2000, DOI 10.17487/RFC2818, May 2000,
<http://www.rfc-editor.org/info/rfc2818>. <http://www.rfc-editor.org/info/rfc2818>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008, DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>. <http://www.rfc-editor.org/info/rfc5226>.
[RFC5890] Klensin, J., "Internationalized Domain Names for [RFC5890] Klensin, J., "Internationalized Domain Names for
Applications (IDNA): Definitions and Document Framework", Applications (IDNA): Definitions and Document Framework",
RFC 5890, DOI 10.17487/RFC5890, August 2010, RFC 5890, DOI 10.17487/RFC5890, August 2010,
skipping to change at page 49, line 46 skipping to change at page 51, line 45
<http://www.rfc-editor.org/info/rfc5929>. <http://www.rfc-editor.org/info/rfc5929>.
[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
DOI 10.17487/RFC6265, April 2011, DOI 10.17487/RFC6265, April 2011,
<http://www.rfc-editor.org/info/rfc6265>. <http://www.rfc-editor.org/info/rfc6265>.
[RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
DOI 10.17487/RFC6454, December 2011, DOI 10.17487/RFC6454, December 2011,
<http://www.rfc-editor.org/info/rfc6454>. <http://www.rfc-editor.org/info/rfc6454>.
[RFC7486] Farrell, S., Hoffman, P., and M. Thomas, "HTTP Origin- [RFC7231] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext
Bound Authentication (HOBA)", RFC 7486, DOI 10.17487/ Transfer Protocol (HTTP/1.1): Semantics and Content",
RFC7486, March 2015, RFC 7231, DOI 10.17487/RFC7231, June 2014,
<http://www.rfc-editor.org/info/rfc7231>.
[RFC7486] Farrell, S., Hoffman, P., and M. Thomas, "HTTP
Origin-Bound Authentication (HOBA)", RFC 7486,
DOI 10.17487/RFC7486, March 2015,
<http://www.rfc-editor.org/info/rfc7486>. <http://www.rfc-editor.org/info/rfc7486>.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer "Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525,
May 2015, <http://www.rfc-editor.org/info/rfc7525>. May 2015, <http://www.rfc-editor.org/info/rfc7525>.
[RFC7564] Saint-Andre, P. and M. Blanchet, "PRECIS Framework:
Preparation, Enforcement, and Comparison of
Internationalized Strings in Application Protocols",
RFC 7564, DOI 10.17487/RFC7564, May 2015,
<http://www.rfc-editor.org/info/rfc7564>.
[RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP
Digest Access Authentication", RFC 7616, DOI 10.17487/ Digest Access Authentication", RFC 7616,
RFC7616, September 2015, DOI 10.17487/RFC7616, September 2015,
<http://www.rfc-editor.org/info/rfc7616>. <http://www.rfc-editor.org/info/rfc7616>.
[RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A., [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A.,
Langley, A., and M. Ray, "Transport Layer Security (TLS) Langley, A., and M. Ray, "Transport Layer Security (TLS)
Session Hash and Extended Master Secret Extension", Session Hash and Extended Master Secret Extension",
RFC 7627, DOI 10.17487/RFC7627, September 2015, RFC 7627, DOI 10.17487/RFC7627, September 2015,
<http://www.rfc-editor.org/info/rfc7627>. <http://www.rfc-editor.org/info/rfc7627>.
Appendix A. (Informative) Draft Change Log [RFC8121] Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi,
T., and Y. Ioku, "Mutual Authentication Protocol for HTTP:
[To be removed on final publication] Cryptographic Algorithms Based on the Key Agreement
Mechanism 3 (KAM3)", RFC 8121, DOI 10.17487/RFC8121,
A.1. Changes in Httpauth WG Revision 11 April 2017, <http://www.rfc-editor.org/info/rfc8121>.
o Reflecting IESG comments.
A.2. Changes in Httpauth WG Revision 10
o Small rephrasing and a typo fix.
A.3. Changes in Httpauth WG Revision 09
o Reflected AD review comments.
o Authors' addresses updated.
A.4. Changes in Httpauth WG Revision 08
o Minor text update, in sync with httpauth-extension.
o The version token is raised to "1".
A.5. Changes in Httpauth WG Revision 07
o Several comments from reviewers are reflected to the text.
o The password-hash has been completely dropped.
o The version token is raised to "1".
A.6. Changes in Httpauth WG Revision 06
o The auth-domain parameter has been renamed to auth-scope,
following suggestions on the mailing list.
o The digest-md5 password-hash has been dropped, as Digest with MD5
hash is now obsoleted.
A.7. Changes in Httpauth WG Revision 05
o Minimum nonce number window has increased to 128. (HTTP 2.0
recommends at least 100 concurrent sessions to exist)
o Reference to TLS session hash extension added for tls-unique
security issues.
o Comments in the previous F2F meeting has been reflected to the
text.
A.8. Changes in Httpauth WG Revision 04
o Merged httpauthprep proposal into general PRECIS Username/Password
profile.
o Adopting RFC 5987 extended syntax for non-ASCII parameter values.
o Refer draft-ietf-httpbis-auth-info for Authentication-Info header.
This results in a different syntax for that header.
A.9. Changes in Httpauth WG Revision 03
o Incompatible change: Single-port type authentication realm label
has been changed to harmonize with Web Origin. (That is, the
default ports (80 and 443) are to be omitted.)
A.10. Changes in Httpauth WG Revision 02
o Major change: introduction of password-strengthening function
PBKDF2.
o Changed Section 10 to adopt "list of requirements" style. Strict
definition of state machine is now a derived, informational
definition.
A.11. Changes in Httpauth WG Revision 01
o Changed "tls-key" verification to "tls-unique" verification, and
"tls-cert" to "tls-server-end-point", adopting RFC 5929.
o Adopted PRECIS framework [RFC7564].
o Reverted reservation of "rekey-sid" and "rekey-method" parameters.
o Degraded secure UI requirement to application note level, non-
normative.
o Adjusted levels of several requirements.
o Added warning text for handling of exceptional 5XX responses.
o Dropped several references for optional authentications, except
one "Note".
o Several textual fixes, improvements and revisions.
A.12. Changes in Httpauth Revision 00
o Changed the version token.
o Renamed "verification tokens" to "Host verification tokens" and
variables "v" to "vh" for clarification. (Back-ported from
draft-oiwa-httpauth-multihop-template-00)
A.13. Changes in HttpBis Revision 00
None.
A.14. Changes in Revision 12
o Added a reason "authz-failed".
A.15. Changes in Revision 11
o Message syntax definition reverted to pre-07 style as httpbis-p1
and p7 now defines a precise rule for parameter value parsing.
o Replaced "stale" parameter with more informative/extensive
"reason" parameter in 401-INIT and 401-STALE.
o Reserved "rekey-sid" and "rekey-method" parameters for future
extensions.
o Added descriptions for replacing/non-replacing existing
technologies.
A.16. Changes in Revision 10
o The authentication extension parts (non-mandatory authentication
and authentication controls) are separated to yet another draft.
o The default auth-domain parameter is changed to the full scheme-
host-port syntax, which is consistent with usual HTTP
authentication framework behavior.
o Provision for application channel binding is added.
o Provision for proxy access authentication is added.
o Bug fix: syntax specification of sid parameter was wrong: it was
inconsistent with the type specified in the main text (the bug
introduced in -07 draft).
o Terminologies for headers are changed to be in harmony with
httpbis drafts (e.g. field to parameter).
o Syntax definitions are changed to use HTTP-extended ABNF syntax,
and only the header values are shown for header syntax, in harmony
with httpbis drafts.
o Names of parameters and corresponding mathematical values are now
renamed to more informative ones. The following list shows
correspondence between the new and the old names.
+------------+----------+-------------------------------------------+
| new name | old name | description |
+------------+----------+-------------------------------------------+
| S_c1, S_s1 | s_a, s_b | client/server-side secret randoms |
| K_c1, K_s1 | w_a, w_b | client/server-side exchanged key |
| | | components |
| kc1, ks1 | wa, wb | parameter names for those |
| VK_c, VK_s | o_a, o_b | client/server-side key verifiers |
| vkc, vks | oa, ob | parameter names for those |
| z | z | session secrets |
+------------+----------+-------------------------------------------+
A.17. Changes in Revision 09
o The (default) cryptographic algorithms are separated to another
draft.
o Names of the messages are changed to more informative ones than
before. The following is the correspondence table of those names:
+-------------------+-----------------+-----------------------------+
| new name | old name | description |
+-------------------+-----------------+-----------------------------+
| 401-INIT | 401-B0 | initial response |
| 401-STALE | 401-B0-stale | session shared secret |
| | | expired |
| req-KEX-C1 | req-A1 | client->server key exchange |
| 401-KEX-S1 | 401-B1 | server->client key exchange |
| req-VFY-C | req-A3 | client->server auth. |
| | | verification |
| 200-VFY-S | 200-B4 | server->client auth. |
| | | verification |
| 200-Optional-INIT | 200-Optional-B0 | initial with non-mandatory |
| | | authentication |
+-------------------+-----------------+-----------------------------+
A.18. Changes in Revision 08
o The English text has been revised.
A.19. Changes in Revision 07
o Adapt to httpbis HTTP/1.1 drafts:
* Changed definition of extensive-token.
* LWSP continuation-line (%0D.0A.20) deprecated.
o To simplify the whole spec, the type of nonce-counter related
parameters are change from hex-integer to integer.
o Algorithm tokens are renamed to include names of hash algorithms.
o Clarified the session management, added details of server-side
protocol decisions.
o The whole draft was reorganized; introduction and overview has
been rewritten.
A.20. Changes in Revision 06
o Integrated Optional Mutual Authentication to the main part.
o Clarified the decision procedure for message recognitions.
o Clarified that a new authentication request for any sub-requests
in interactive clients may be silently discarded.
o Typos and confusing phrases are fixed.
o Several "future considerations" are added.
A.21. Changes in Revision 05
o A new parameter called "version" is added for supporting future
incompatible changes with a single implementation. In the (first)
final specification its value will be changed to 1.
o A new header "Authentication-Control" is added for precise control
of application-level authentication behavior.
A.22. Changes in Revision 04
o Changed text of patent licenses: the phrase "once the protocol is
accepted as an Internet standard" is removed so that the sentence
also covers the draft versions of this protocol.
o The "tls-key" verification is now OPTIONAL.
o Several description fixes and clarifications.
A.23. Changes in Revision 03
o Wildcard domain specifications (e.g. "*.example.com") are allowed
for auth-domain parameters (Section 4.1).
o Specification of the tls-cert verification is updated
(incompatible change).
o State transitions fixed.
o Requirements for servers concerning w_a values are clarified.
o RFC references are updated.
A.24. Changes in Revision 02
o Auth-realm is extended to allow full-scheme type.
o A decision diagram for clients and decision procedures for servers
are added.
o 401-B1 and req-A3 messages are changed to contain authentication
realm information.
o Bugs on equations for o_A and o_B are fixed.
o Detailed equations for the entire algorithm are included.
o Elliptic-curve algorithms are updated.
o Several clarifications and other minor updates.
A.25. Changes in Revision 01
o Several texts are rewritten for clarification.
o Added several security consideration clauses.
Authors' Addresses Authors' Addresses
Yutaka Oiwa Yutaka Oiwa
National Institute of Advanced Industrial Science and Technology National Institute of Advanced Industrial Science and Technology
Information Technology Research Institute Information Technology Research Institute
Tsukuba Central 1 Tsukuba Central 1
1-1-1 Umezono 1-1-1 Umezono
Tsukuba-shi, Ibaraki Tsukuba-shi, Ibaraki
JP Japan
Email: y.oiwa@aist.go.jp Email: y.oiwa@aist.go.jp
Hajime Watanabe Hajime Watanabe
National Institute of Advanced Industrial Science and Technology National Institute of Advanced Industrial Science and Technology
Information Technology Research Institute Information Technology Research Institute
Tsukuba Central 1 Tsukuba Central 1
1-1-1 Umezono 1-1-1 Umezono
Tsukuba-shi, Ibaraki Tsukuba-shi, Ibaraki
JP Japan
Email: h-watanabe@aist.go.jp Email: h-watanabe@aist.go.jp
Hiromitsu Takagi Hiromitsu Takagi
National Institute of Advanced Industrial Science and Technology National Institute of Advanced Industrial Science and Technology
Information Technology Research Institute Information Technology Research Institute
Tsukuba Central 1 Tsukuba Central 1
1-1-1 Umezono 1-1-1 Umezono
Tsukuba-shi, Ibaraki Tsukuba-shi, Ibaraki
JP Japan
Email: takagi.hiromitsu@aist.go.jp Email: takagi.hiromitsu@aist.go.jp
Kaoru Maeda Kaoru Maeda
Lepidum Co. Ltd. Individual Contributor
Village Sasazuka 3, Suite #602 Email: kaorumaeda.ml@gmail.com
1-30-3 Sasazuka
Shibuya-ku, Tokyo
JP
Email: maeda@lepidum.co.jp
Tatsuya Hayashi Tatsuya Hayashi
Lepidum Co. Ltd. Lepidum Co. Ltd.
Village Sasazuka 3, Suite #602 Village Sasazuka 3, Suite #602
1-30-3 Sasazuka 1-30-3 Sasazuka
Shibuya-ku, Tokyo Shibuya-ku, Tokyo
JP Japan
Email: hayashi@lepidum.co.jp Email: hayashi@lepidum.co.jp
Yuichi Ioku Yuichi Ioku
Individual Individual Contributor
Email: mutual-work@ioku.org Email: mutual-work@ioku.org
 End of changes. 381 change blocks. 
1432 lines changed or deleted 1162 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/