tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 8120

 
 
 

Mutual Authentication Protocol for HTTP

Part 2 of 3, p. 15 to 35
Prev Section       Next Section

 


prevText      Top      ToC       Page 15 
4.  Messages

   In this section, we define the six kinds of messages in the
   authentication protocol, along with the formats and requirements of
   the headers for each type of message.

   To determine under what circumstances each message is expected to be
   sent, see Sections 10 and 11.

   In the descriptions below, the types of allowable values for each
   header parameter are shown in parentheses after each parameter name.
   The "algorithm-determined" type means that the acceptable value for
   the parameter is one of the types defined in Section 3 and is

Top      Up      ToC       Page 16 
   determined by the value of the "algorithm" parameter.  The parameters
   marked "mandatory" SHALL be contained in the message.  The parameters
   marked "non-mandatory" MAY be either contained in the message or
   omitted from it.  Each parameter SHALL appear in each header exactly
   once at most.

   All credentials and challenges MAY contain any parameters not
   explicitly specified in the following sections.  Recipients that
   do not understand such parameters MUST silently ignore them.
   However, all credentials and challenges MUST meet the following
   criteria:

   o  For responses, the parameters "reason", any "ks#" (where "#"
      stands for any decimal integer), and "vks" are mutually exclusive;
      any challenges MUST NOT contain two or more parameters among them.
      They MUST NOT contain any "kc#" or "vkc" parameters.

   o  For requests, the parameters "kc#" (where "#" stands for any
      decimal integer) and "vkc" are mutually exclusive; any challenges
      MUST NOT contain two or more parameters among them.  They MUST NOT
      contain any "ks#" or "vks" parameters.

   Every message defined in this section contains a "version" field to
   detect any future revisions of the protocol that are incompatible.
   Implementations of the protocol described in this specification MUST
   always send a token "1" to represent the version number.  Recipients
   MUST reject messages that contain any other value for the version,
   unless another specification defines specific behavior for that
   version.

4.1.  401-INIT and 401-STALE

   Every 401-INIT or 401-STALE message SHALL be a valid HTTP 401
   (Unauthorized) status message (or some other 4xx status message, if
   appropriate) containing one and only one (hereafter not explicitly
   noted) WWW-Authenticate header containing a "reason" parameter in the
   challenge.  The challenge SHALL contain all of the parameters marked
   "mandatory" below and MAY contain those marked "non-mandatory".

   version:
      (mandatory extensive-token) should be the token "1".

   algorithm:
      (mandatory extensive-token) specifies the authentication algorithm
      to be used.  The value MUST be one of the tokens specified in
      [RFC8121] or another supplemental specification.

Top      Up      ToC       Page 17 
   validation:
      (mandatory extensive-token) specifies the method of host
      validation.  The value MUST be one of the tokens described in
      Section 7 or the tokens specified in another supplemental
      specification.

   auth-scope:
      (non-mandatory string) specifies the authentication scope, i.e.,
      the set of hosts for which the authentication credentials are
      valid.  It MUST be one of the strings described in Section 5.  If
      the value is omitted, it is assumed to be the "single-server type"
      domain as described in Section 5.

   realm:
      (mandatory string) is a string representing the name of the
      authentication realm inside the authentication scope.  As
      specified in [RFC7235], this value MUST always be sent in the
      quoted-string form, and an encoding as specified in [RFC5987]
      MUST NOT be used.

      The realm value sent from the server SHOULD be an ASCII string.
      Clients MAY treat any non-ASCII value received in this field as a
      binary blob, an NFC-normalized UTF-8 string ("NFC" stands for
      "Normalization Form C"), or an error.

   reason:
      (mandatory extensive-token) SHALL be an extensive-token that
      describes the possible reason for the failed authentication or
      authorization.  Both servers and clients SHALL understand and
      support the following three tokens:

      *  initial: Authentication was not attempted because there was no
         Authorization header in the corresponding request.

      *  stale-session: The provided sid in the request was either
         unknown to the server or expired in the server.

      *  auth-failed: The authentication trial failed for some reason,
         possibly because of a bad authentication credential.

Top      Up      ToC       Page 18 
      Implementations MAY support the following tokens or any
      extensive-tokens defined outside of this specification.  If
      clients receive any unknown tokens, they SHOULD treat them as if
      they were "auth-failed" or "initial".

      *  reauth-needed: The server-side application requires a new
         authentication trial, regardless of the current status.

      *  invalid-parameters: The server did not attempt authentication
         because some parameters were not acceptable.

      *  internal-error: The server did not attempt authentication
         because there are some problems on the server side.

      *  user-unknown: This is a special case of auth-failed; it
         suggests that the provided username is invalid.  Due to
         security implications, the use of this parameter is
         NOT RECOMMENDED, except for special-purpose applications where
         it would make sense to do so.

      *  invalid-credential: This is another special case of
         auth-failed; it suggests that the provided username was valid
         but authentication still failed.  For security reasons, the use
         of this parameter is NOT RECOMMENDED.

      *  authz-failed: Authentication was successful, but access to the
         specified resource is not authorized to the specific
         authenticated user.  (It might be used along with either a
         401 (Unauthorized) or 403 (Forbidden) status code to indicate
         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
   (among those defined in Section 3) and the values for K_c1, K_s1,
   VK_c, and VK_s.

   Among these messages, any messages with the "reason" parameter value
   "stale-session" will be called "401-STALE" messages hereafter,
   because these messages have a special meaning in the protocol flow.
   Messages with any other "reason" parameters will be called "401-INIT"
   messages.

Top      Up      ToC       Page 19 
4.2.  req-KEX-C1

   Every req-KEX-C1 message SHALL be a valid HTTP request message
   containing an Authorization header with a credential containing a
   "kc1" parameter.

   The credential SHALL contain the parameters with the following names:

   version:
      (mandatory, extensive-token) should be the token "1".

   algorithm, validation, auth-scope, realm:
      MUST be the same values as those received from the server.

   user:
      (mandatory, string) is the UTF-8 encoded name of the user.  The
      string SHOULD be prepared according to the method presented in
      Section 9.

   kc1:
      (mandatory, algorithm-determined) is the client-side key exchange
      value K_c1, which is specified by the algorithm that is used.

4.3.  401-KEX-S1

   Every 401-KEX-S1 message SHALL be a valid HTTP 401 (Unauthorized)
   status response message containing a WWW-Authenticate header with a
   challenge containing a "ks1" parameter.

   The challenge SHALL contain the parameters with the following names:

   version:
      (mandatory, extensive-token) should be the token "1".

   algorithm, validation, auth-scope, realm:
      MUST be the same values as those received from the client.

   sid:
      (mandatory, hex-fixed-number) MUST be a session identifier, which
      is a random integer.  The sid SHOULD have uniqueness of at least
      80 bits or the square of the maximum estimated transactions
      concurrently available in the session table, whichever is larger.
      See Section 6 for more details.

   ks1:
      (mandatory, algorithm-determined) is the server-side key exchange
      value K_s1, which is specified by the algorithm.

Top      Up      ToC       Page 20 
   nc-max:
      (mandatory, integer) is the maximum value of nonce numbers that
      the server accepts.

   nc-window:
      (mandatory, integer) is the number of available nonce number slots
      that the server will accept.  It is RECOMMENDED that the value of
      the "nc-window" parameter be 128 or more.

   time:
      (mandatory, integer) represents the suggested time (in seconds)
      that the client can reuse the session represented by the sid.  It
      is RECOMMENDED that the time be set to at least 60 (seconds).
      However, the server is not required to guarantee that the session
      represented by the sid will be available (e.g., alive, usable) for
      the time specified in this parameter.

   path:
      (non-mandatory, string) specifies to which path in the URI space
      the same authentication is expected to be applied.  The value is a
      space-separated list of URIs, in the same format as that specified
      in the "domain" parameter [RFC7616] for Digest authentications.
      All path elements contained in the "path" parameter MUST be inside
      the specified auth-scope; if not, clients SHOULD ignore such
      elements.  For better performance, it is important that clients
      recognize and use this parameter.

4.4.  req-VFY-C

   Every req-VFY-C message SHALL be a valid HTTP request message
   containing an Authorization header with a credential containing a
   "vkc" parameter.

   The parameters contained in the header are as follows:

   version:
      (mandatory, extensive-token) should be the token "1".

   algorithm, validation, auth-scope, realm:
      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 values that
      was received from the server for the same authentication realm.

Top      Up      ToC       Page 21 
   nc:
      (mandatory, integer) is a nonce request number that is unique
      among the requests sharing the same sid.  The values of the nonce
      numbers SHOULD satisfy the properties outlined in Section 6.

   vkc:
      (mandatory, algorithm-determined) is the client-side
      authentication verification value VK_c, which is specified by the
      algorithm.

4.5.  200-VFY-S

   Every 200-VFY-S message SHALL be a valid HTTP message that does not
   have a 401 (Unauthorized) status code and SHALL contain an
   Authentication-Info header with a "vks" parameter.

   The parameters contained in the header are as follows:

   version:
      (mandatory, extensive-token) should be the token "1".

   sid:
      (mandatory, hex-fixed-number) MUST be the value received from the
      client.

   vks:
      (mandatory, algorithm-determined) is the server-side
      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
   in the trailer of a chunked-encoded response.  If a "100 (Continue)"
   [RFC7231] response is sent from the server, the Authentication-Info
   header SHOULD be included in that response instead of the final
   response.

5.  Authentication Realms

   In this protocol, an authentication realm is defined as a set of
   resources (URIs) for which the same set of usernames and passwords is
   valid.  If the server requests authentication for an authentication
   realm for which the client is already authenticated, the client will
   automatically perform the authentication using the already-known
   credentials.  However, for different authentication realms, clients
   MUST NOT automatically reuse usernames and passwords for another
   realm.

Top      Up      ToC       Page 22 
   As is the case for the Basic and Digest access authentication
   protocols, the Mutual authentication protocol supports multiple,
   separate protection spaces to be set up inside each host.
   Furthermore, the protocol allows a single authentication realm to
   span several hosts within the same Internet domain.

   Each authentication realm is defined and distinguished by the triple
   of an authentication algorithm, an authentication scope, and a
   "realm" parameter.  However, it is NOT RECOMMENDED that server
   operators use the same pair of an authentication scope and a realm
   with different authentication algorithms.

   The "realm" parameter is a string as defined in Section 4.
   Authentication scopes are described in the remainder of this section.

   An authentication scope specifies the range of hosts spanned by the
   authentication realm.  In this protocol, it MUST be one of the
   following kinds of strings:

   o  Single-server type: A string in the format "<scheme>://<host>" or
      "<scheme>://<host>:<port>", where <scheme>, <host>, and <port> are
      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
      underlying HTTP communications, the port part MUST be omitted,
      regardless of whether it was present in the request URI.  In all
      other cases, the port part MUST be present, and it MUST NOT
      contain leading zeros.  Use this format when authentication is
      only valid for a specific protocol (such as HTTPS).  This format
      is equivalent to the ASCII serialization of a Web origin, as
      presented in Section 6.2 of [RFC6454].

   o  Single-host type: The "host" part of the requested URI.  This is
      the default value.  Authentication realms within this kind of
      authentication scope will span several protocols (e.g., HTTP and
      HTTPS) and ports but will not span different hosts.

   o  Wildcard-domain type: A string in the format "*.<domain-postfix>",
      where <domain-postfix> is either the host part of the requested
      URI or any domain in which the requested host is included (this
      means that the specification "*.example.com" is valid for all of
      hosts "www.example.com", "web.example.com",
      "www.sales.example.com", and "example.com").  The domain-postfix
      sent by the servers MUST be equal to or included in a valid
      Internet domain assigned to a specific organization; if clients
      know, via some means such as a blacklist for HTTP cookies
      [RFC6265], that the specified domain is not to be assigned to any
      specific organization (e.g., "*.com" or "*.jp"), it is RECOMMENDED
      that clients reject the authentication request.

Top      Up      ToC       Page 23 
   In the above specifications, every "scheme", "host", and "domain"
   MUST be in lower case, and any internationalized domain names beyond
   the ASCII character set SHALL be represented in the way they are sent
   in the underlying HTTP protocol, represented in lowercase characters,
   i.e., these domain names SHALL be in the form of LDH ("letters,
   digits, hyphen") labels as defined in the Internationalized Domain
   Names for Applications (IDNA) specification [RFC5890].  A "port" MUST
   be given in shortest unsigned decimal number notation.  Not obeying
   these requirements will cause valid authentication attempts to fail.

5.1.  Resolving Ambiguities

   In the above definitions of authentication scopes, several scopes may
   overlap each other.  If a client has already been authenticated to
   several realms applicable to the same server, the client may have
   multiple lists of the "path" parameters received with the
   "401-KEX-S1" message (see Section 4).  If these path lists have any
   overlap, a single URI may belong to multiple possible candidate
   realms to which the client can be authenticated.  In such cases,
   clients face an ambiguous choice regarding which credentials to send
   for a new request (see Steps 3 and 4 of the decision procedure
   presented in Section 10).

   In such cases, a client MAY freely send requests that belong to any
   of these candidate realms, or it MAY simply send an unauthenticated
   request and see for which realm the server requests an
   authentication.  It is RECOMMENDED that server operators provide
   properly configured "path" parameters (more precisely, disjoint path
   sets for each realm) for clients so that such ambiguities will not
   occur.

   The following procedure is one possible tactic for resolving
   ambiguities in such cases:

   o  If the client has previously sent a request to the same URI and it
      remembers the authentication realm requested by the 401-INIT
      message at that time, use that realm.

   o  In other cases, use one of the authentication realms representing
      the most-specific authentication scopes.  The list of possible
      domain specifications shown above is given from most specific to
      least specific.

      If there are several choices with different wildcard-domain
      specifications, the one that has the longest domain-postfix has
      priority over those with shorter domain-postfixes.

Top      Up      ToC       Page 24 
   o  If there are realms with the same authentication scope, there is
      no defined priority; the client MAY choose any one of the possible
      choices.

6.  Session Management

   In the Mutual authentication protocol, a session represented by
   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)
   associated with the session is established.  After mutually
   establishing a session secret, this session, along with the secret,
   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
   an inside detail of the protocol and usually not visible to normal
   users.  If a session expires, the client and server SHOULD
   automatically re-establish another session without informing
   the user.

   Sessions and session identifiers are local to each server (defined by
   scheme, host, and port), even if an authentication scope covers
   multiple servers; clients MUST establish separate sessions for each
   port of a host to be accessed.  Furthermore, sessions and identifiers
   are also local to each authentication realm, even if they are
   provided by the same server.  The same session identifiers provided
   either from different servers or for different realms MUST be treated
   as being independent of each other.

   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
   by the "timeout" parameter in the 401-KEX-S1 message and if there are
   no emergent reasons (such as flooding attacks) to forget the session.
   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
   for that 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
   the nonce number (in the "nc" parameter) MUST satisfy the following
   conditions:

   o  It is a natural number.

   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
      server in the session represented by the sid.

Top      Up      ToC       Page 25 
   o  It is larger than (largest-nc - nc-window), where largest-nc is
      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
      received from the server for the session.

   The last condition allows servers to reject any nonce numbers that
   are "significantly" smaller than the "current" value (defined by the
   value of nc-window) of the nonce number used in the session involved.
   In other words, servers MAY treat such nonce numbers as "already
   received".  This restriction enables servers to implement
   duplicate-nonce detection in a constant amount of memory for each
   session.

   Servers MUST check for duplication of the received nonce numbers, and
   if any duplication is detected, the server MUST discard the session
   and respond with a 401-STALE message, as outlined in Section 11.  The
   server MAY also reject other invalid nonce numbers (such as those
   above the nc-max limit) by sending a 401-STALE message.

   For example, assume that the nc-window value of the current session
   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-372}.  The nonce number that can then be used for the next
   request is a number from the following set: {245-254, 361, 362,
   373-400}.  The values {0, 121, 123, 125-129, 239-244} MAY be rejected
   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
   monotonically increasing integer counter that counts from zero up to
   the value of nc-max.

   The values of the nonce numbers and any nonce-related values MUST
   always be treated as natural numbers within an infinite range.
   Implementations that use fixed-width integer representations,
   fixed-precision floating-point numbers, or similar representations
   SHOULD NOT reject any larger values that overflow such representative
   limits and MUST NOT silently truncate them using any modulus-like
   rounding operation (e.g., by mod 2^32).  Instead, the whole protocol
   is carefully designed so that recipients MAY replace any such
   overflowing values (e.g., 2^80) with some reasonably large maximum
   representative integer (e.g., 2^31 - 1 or others).

Top      Up      ToC       Page 26 
7.  Host Validation Methods

   The "validation method" specifies a method to "relate" (or "bind")
   the mutual authentication processed by this protocol with other
   authentications already performed in the underlying layers and to
   prevent man-in-the-middle attacks.  It determines the value vh that
   is an input to the authentication protocols.

   When HTTPS or another possible secure transport is used, this
   corresponds to the idea of "channel binding" as described in
   [RFC5929].  Even when HTTP is used, similar, but somewhat limited,
   "binding" is performed to prevent a malicious server from trying to
   authenticate itself to another server as a valid user by forwarding
   the received credentials.

   The valid tokens for the "validation" parameter and corresponding
   values of vh are as follows:

   host:
      hostname validation.  The value vh will be the ASCII string in the
      following format: "<scheme>://<host>:<port>", where <scheme>,
      <host>, and <port> are the URI components corresponding to the
      server-side resource currently being accessed.  The scheme and
      host are in lower case, and the port is listed in shortest decimal
      notation.  Even if the request URI does not have a port part, vh
      will include the default port number.

   tls-server-end-point:
      TLS endpoint (certificate) validation.  The value vh will be the
      octet string of the hash value of the server's public key
      certificate used in the underlying TLS [RFC5246] connection,
      processed as specified in Section 4.1 of [RFC5929].

   tls-unique:
      TLS shared-key validation.  The value vh will be the
      channel-binding material derived from the Finished messages,
      as defined in Section 3.1 of [RFC5929].  (Note: See Section 7.2
      for some security-related notes regarding this validation method.)

   If HTTP is used on a non-encrypted channel (TCP and the Stream
   Control Transmission Protocol (SCTP), for example), the validation
   type MUST be "host".  If HTTP/TLS [RFC2818] (HTTPS) is used with a
   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"
   (see the note below).

Top      Up      ToC       Page 27 
   If the validation type "tls-server-end-point" is used, the server
   certificate provided in the TLS connection MUST be verified at least
   to make sure that the server actually owns the corresponding private
   key.  (Note: This verification is automatic in some RSA-based key
   exchanges but is NOT automatic in Diffie-Hellman-based key exchanges
   with separate exchanges for server verification.)

   Clients MUST validate this parameter upon receipt of 401-INIT
   messages.

   Note: The protocol defines two variants of validation on the TLS
   connections.  The "tls-unique" method is technically more secure.
   However, there are some situations where "tls-server-end-point" is
   preferable:

   o  When TLS accelerating proxies are used.  In this case, it is
      difficult for the authenticating server to acquire the TLS key
      information that is used between the client and the proxy.  This
      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
      either peer.

7.1.  Applicability Notes

   When the client is a Web browser with any scripting capabilities
   (support of dynamic contents), the underlying TLS channel used with
   HTTP/TLS MUST provide server identity verification.  This means that
   (1) anonymous Diffie-Hellman key exchange cipher suites MUST NOT be
   used and (2) verification of the server certificate provided by the
   server MUST be performed.  This is to prevent loading identity-
   unauthenticated scripts or dynamic contents, which are referenced
   from the authenticated page.

   For other systems, when the underlying TLS channel used with HTTP/TLS
   does not perform server identity verification, the client SHOULD
   ensure that all responses are validated using the Mutual
   authentication protocol, regardless of the existence of 401-INIT
   responses.

Top      Up      ToC       Page 28 
7.2.  Notes on "tls-unique"

   As described in the interoperability note in Section 3.1 of
   [RFC5929], the "tls-unique" verification value will be changed by
   possible TLS renegotiation, causing an interoperability problem.  TLS
   renegotiations are used in several HTTPS server implementations for
   enforcing some security properties (such as cryptographic strength)
   for some specific responses.

   If an implementation supports the "tls-unique" verification method,
   the following precautions SHOULD be taken:

   o  Both peers must be aware that the vh values used for vkc (in
      req-VFY-C messages) and vks (in 200-VFY-S messages) may be
      different.  These values MUST be retrieved from underlying TLS
      libraries each time they are used.

   o  After calculating the values vh and vkc to send a req-VFY-C
      request, clients SHOULD NOT initiate TLS renegotiation until the
      end of the corresponding response header is received.  An
      exception is that clients can and SHOULD perform TLS renegotiation
      as a response to the server's request for TLS renegotiation,
      before receipt of the beginning of the response header.

   Also, implementers MUST take care of session resumption attacks
   regarding "tls-unique" channel-binding mechanisms and master secrets.
   As a mitigation, the TLS extension defined in [RFC7627] SHOULD be
   used when "tls-unique" host verification is to be used.

8.  Authentication Extensions

   It is RECOMMENDED that interactive clients (e.g., Web browsers)
   supporting this protocol support non-mandatory authentication and the
   Authentication-Control header defined in [RFC8053], except for the
   "auth-style" parameter.  This specification also proposes (but does
   not mandate) that the default "auth-style" be "non-modal".  Web
   applications SHOULD, however, consider the security impacts of the
   behavior of clients that do not support these headers.

   Authentication-initializing messages with the
   Optional-WWW-Authenticate header are used only where the 401-INIT
   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
   message MUST be "initial" (or any extensive-tokens NOT defined in
   Section 4.1).

Top      Up      ToC       Page 29 
9.  String Preparation

   For interoperability reasons, it is important that usernames and
   passwords used in this protocol be binary-comparable, regardless of
   the user's input methods and/or environments.  To ensure this, the
   following preparation SHOULD be performed:

   o  Usernames received from users SHOULD be prepared using the
      "UsernameCasePreserved" profile defined in Section 3.3 of
      [RFC7613].

   o  Passwords received from users SHOULD be prepared using the
      "OpaqueString" profile defined in Section 4.2 of [RFC7613].

   In both cases, it is the sender's duty to correctly prepare the
   character strings.  If any non-prepared character string is received
   from the other peer of the communication, the behavior of its
   recipient is not defined; the recipient MAY either accept or reject
   such input.

   Server applications SHOULD also prepare usernames and passwords
   accordingly upon registration of user credentials.

   In addition, binary-based "interfaces" of implementations MAY require
   and assume that the string is already prepared accordingly; when a
   string is already stored as a binary Unicode string form,
   implementations MAY omit preparation and Unicode normalization
   (performing UTF-8 encoding only) before using it.  When a string is
   already stored as an octet blob, implementations MAY send it as is.

10.  Decision Procedure for Clients

10.1.  General Principles and Requirements

   To securely implement the protocol, the client must be careful about
   accepting the authenticated responses from the server.  This also
   holds true for the reception of a "normal response" (a response that
   does not contain mutual-authentication-related headers) from HTTP
   servers.

Top      Up      ToC       Page 30 
   Per typical HTTP authentication, a single user-level request may
   result in the exchange of two or more HTTP requests and responses in
   sequence.  The following normative rules MUST be followed by the
   clients implementing this protocol:

   o  Any kind of "normal response" MUST only be accepted for the very
      first request in the sequence.  Any "normal response" returned for
      the second or subsequent requests in the sequence SHALL be
      considered invalid.

   o  By the same principle, if any response is related to an
      authentication realm that is different from that of the client's
      request (for example, a 401-INIT message requesting authentication
      on another realm), it MUST only be accepted for the very first
      request in the sequence.  Such a response returned for a second or
      subsequent request in the sequence SHALL be considered invalid.

   o  A req-KEX-C1 message MAY be sent as either an initial request or a
      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
      realm.  A 401-KEX-S1 response MUST be accepted only when the
      corresponding request is req-KEX-C1.

   o  A req-VFY-C message MAY be sent if there is a valid session secret
      shared between the client and the server, as established by
      req-KEX-C1 and 401-KEX-S1 messages.  If any response with a
      401 status code is returned for such a message, the corresponding
      session secret SHOULD be discarded as unusable.

      In particular, upon the reception of a 401-STALE response, the
      client SHOULD try to establish a new session by sending a
      req-KEX-C1 message, but only once within the request/response
      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.

Top      Up      ToC       Page 31 
   The final status of the client request following the message exchange
   sequence shall be determined as follows:

   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.

   o  AUTH-REQUIRED: Two cases exist:

      *  A 401-INIT message was returned from the server, and the client
         does not know how to authenticate to the given authentication
         realm.

      *  A 401-INIT response was returned for a req-VFY-C (or
         req-KEX-C1) message, which means that the user-supplied
         authentication credentials were not accepted.

   o  UNAUTHENTICATED: A "normal response" is returned for an initial
      request of any kind in the sequence.

   Any kind of response (including a "normal response") other than those
   explicitly allowed in the above rules SHOULD be interpreted as a
   fatal communication error.  In such cases, the clients MUST NOT
   process any data (the response body and other content-related
   headers) sent from the server.  However, to handle exceptional error
   cases, clients MAY accept a message without an Authentication-Info
   header if it has a Server Error (5xx) status code.  In such cases,
   they SHOULD be careful about processing the body of the content
   (ignoring it is still RECOMMENDED, as it may possibly be forged by
   intermediate attackers), and the client will then have a status of
   "UNAUTHENTICATED".

   If a request is a sub-request for a resource included in another
   resource (e.g., embedded images, style sheets, frames), clients MAY
   treat an AUTH-REQUESTED status the same way they would treat an
   UNAUTHENTICATED status.  In other words, the client MAY ignore the
   server's request to start authentication with new credentials via
   sub-requests.

10.2.  State Machine for the Client (Informative)

   The following state machine describes the possible request-response
   sequences derived from the above normative rules.  If implementers
   are not quite sure of the security consequences of the above rules,
   we strongly advise that the decision procedure below be followed.  In
   particular, clients SHOULD NOT accept "normal responses" unless
   explicitly allowed in the rules.  The labels in the steps below are

Top      Up      ToC       Page 32 
   for informational purposes only.  Action entries within each step are
   checked in top-to-bottom order, and the first clause satisfied is to
   be followed.

   Step 1 (step_new_request):
       If the client software needs to access a new Web resource, check
       to see whether the resource is expected to be inside some
       authentication realm for which the user has already been
       authenticated via the Mutual authentication scheme.  If yes,
       go to Step 2.  Otherwise, go to Step 5.

   Step 2:
       Check to see whether there is an available sid for the expected
       authentication realm.  If there is one, go to Step 3.  Otherwise,
       go to Step 4.

   Step 3 (step_send_vfy_1):
       Send a req-VFY-C request.

       *  If a 401-INIT message is received with a different
          authentication realm than expected, go to Step 6.

       *  If a 401-STALE message is received, go to Step 9.

       *  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 "normal response" is received, go to Step 11.

   Step 4 (step_send_kex1_1):
       Send a req-KEX-C1 request.

       *  If a 401-INIT message is received with a different
          authentication realm than expected, go to Step 6.

       *  If a 401-KEX-S1 message is received, go to Step 10.

       *  If a 401-INIT message is received with the same authentication
          realm, go to Step 13 (see Note 1).

       *  If a "normal response" is received, go to Step 11.

Top      Up      ToC       Page 33 
   Step 5 (step_send_normal_1):
       Send a request without any mutual-authentication headers.

       *  If a 401-INIT message is received, go to Step 6.

       *  If a "normal response" is received, go to Step 11.

   Step 6 (step_rcvd_init):
       Check to see whether the user's password for the requested
       authentication realm is known.  If yes, go to Step 7.  Otherwise,
       go to Step 12.

   Step 7:
       Check to see whether there is an available sid for the expected
       authentication realm.  If there is one, go to Step 8.  Otherwise,
       go to Step 9.

   Step 8 (step_send_vfy):
       Send a req-VFY-C request.

       *  If a 401-STALE message is received, go to Step 9.

       *  If a 401-INIT message is received, go to Step 13.

       *  If a 200-VFY-S message is received, go to Step 14.

   Step 9 (step_send_kex1):
       Send a req-KEX-C1 request.

       *  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).

   Step 10 (step_rcvd_kex1):
       Send a req-VFY-C request.

       *  If a 401-INIT message is received, go to Step 13.

       *  If a 200-VFY-S message is received, go to Step 14.

   Step 11 (step_rcvd_normal):
       The requested resource is out of the authenticated area.  The
       client will be in the "UNAUTHENTICATED" status.  If the response
       contains a request for authentication other than Mutual
       authentication, it MAY be handled normally.

Top      Up      ToC       Page 34 
   Step 12 (step_rcvd_init_unknown):
       The requested resource requires Mutual authentication, and the
       user is not yet authenticated.  The client will be in the
       "AUTH-REQUESTED" status; it is RECOMMENDED that the client
       process the content sent from the server and ask the user for a
       username and password.  When those are supplied by the user,
       go to Step 9.

   Step 13 (step_rcvd_init_failed):
       The authentication failed for some reason, possibly because the
       password or username is invalid for the authenticated resource.
       Forget the user-provided credentials for the authentication
       realm, and go to Step 12.

   Step 14 (step_rcvd_vfy):
       The received message is the 200-VFY-S message, which always
       contains a "vks" field.  Check the validity of the received VK_s
       value.  If it is equal to the expected value, then the mutual
       authentication succeeded.  The client will be in the
       "AUTH-SUCCEED" status.

       An unexpected value is interpreted as a fatal communication
       error.

       If a user explicitly asks to log out (via the user interface),
       the client MUST forget the user's password, go to Step 5, and
       reload the current resource without an authentication header.

   Note 1:  These transitions MAY be accepted by clients, but it is
       NOT RECOMMENDED that servers initiate them.

   Figure 5 shows an informative diagram of the client state.

Top      Up      ToC       Page 35 
         ===========                                  -(11)------------
         NEW REQUEST                                 ( UNAUTHENTICATED )
         ===========                                  -----------------
              |                                              ^ normal
              v                                              | response
   +(1)-------------------+ NO                         +(5)----------+
   | The requested URI    |--------------------------->| send normal |
   | known to be auth'ed? |                            |   request   |
   +----------------------+                            +-------------+
          YES |   401-INIT                            401-INIT|
              |   with a different realm                      |
              |          -----------------------------------. |
              |         /                                   v v
              |        |       -(12)------------    NO  +(6)--------+
              |        |      ( AUTH-REQUESTED  )<------| user/pass |
              |        |       -----------------        |   known?  |
              |        |                                +-----------+
              |        |                                      |YES
              v        |                                      v
        +(2)--------+  |                                +(7)--------+
        | session   |  |                                | session   | NO
    NO /| available?|  |                                | available?|\
      / +-----------+  |                                +-----------+ |
     /        |YES     |                                      |YES    |
    |         |       /|                                      |       |
    |         v      / |  401-                   401-         v       |
    |   +(3)--------+  |  INIT --(13)----------  INIT   +(8)--------+ |
    |   |   send    |--+----->/ AUTH-REQUESTED \<-------|   send    | |
    |  /| req-VFY-C |  |      \forget password /        | req-VFY-C | |
     \/ +-----------+ /        ----------------        /+-----------+ |
     /\           \ \/                 ^ 401-INIT     |     |401-     |
    |  ------      \/\  401-STALE      |              |     | STALE  /
    |        \     /\ -----------------+--------------+---. |       /
    |         |   /  \                 |              |   | |      /
    |         v  /    | 401-           |       401-   |   v v     v
    |   +(4)--------+ | KEX-S1   +(10)-------+ KEX-S1 | +(9)--------+
    |   |   send    |-|--------->|   send    |<-------+-|   send    |
    | --| req-KEX-C1| |          | req-VFY-C |        | | req-KEX-C1|
    |/  +-----------+ |          +-----------+        | +-----------+
    |                 |200-VFY-S      |      200-VFY-S|       ^
    |normal           |               |200-VFY-S     /        |
    |response         |               v             / ==================
    v                  \         -(14)---------    /  USER/PASS INPUTTED
    -(11)------------   ------->( AUTH-SUCCEED )<--   ==================
   ( UNAUTHENTICATED )           --------------
    -----------------

                    Figure 5: State Diagram for Clients


Next Section