3. Digest Access Authentication Scheme

3.1 Introduction

3.1.1 Purpose

The protocol referred to as "HTTP/1.0" includes specification for a Basic Access Authentication scheme [1]. This scheme is not considered to be a secure method of user authentication, as the user name and password are passed over the network in an unencrypted form. This section provides specification for a scheme that does not send the password in cleartext, but instead uses a checksum technique, referred to as "Digest Access Authentication".

The Digest Access Authentication scheme is not intended to be a complete answer to the need for security on the World Wide Web. This scheme does not provide encryption of message content. The intent is simply to create an access authentication method that avoids the most serious flaws of Basic authentication.

3.1.2 Overall Operation

Like Basic Access Authentication, the Digest scheme is based on a simple challenge-response paradigm. The Digest scheme challenges using a nonce value. A valid response contains a checksum (by default, the MD5 checksum) of the username, the password, the given nonce value, the HTTP method, and the requested URI. In this way, the password is never sent in the clear. As with Basic, the username and password must be prearranged in some fashion not addressed by this document.

3.1.3 Representation of digest values

An optional header allows the server to specify the algorithm used to create the checksum or digest. By default the MD5 algorithm is used and that is the only algorithm described in this document.

For the purposes of this document, an MD5 digest of 128 bits is represented as 32 ASCII printable characters. The bits of the 128 bit digest are converted from most significant to least significant bit, four bits at a time to their ASCII presentation as follows. Each four bits is represented by its familiar hexadecimal notation from the characters 0123456789abcdef. That is, binary 0000 is represented by the character '0', 0001 by '1', and so on up to the representation of 1111 as 'f'.

3.1.4 Limitations

The Digest authentication scheme described in this document suffers from many known limitations. It is intended to replace Basic authentication and nothing more. It is a password-based system and (on the server end) suffers from all the same problems of any password system. In particular, no provision is made in this protocol for the initial secure arrangement between user and server to establish the user's password.

Users and implementors should be aware that this protocol is not as secure as Kerberos, and not as secure as any client-side private-key scheme. Nevertheless it is better than nothing, better than what is commonly used with telnet and ftp, and better than Basic authentication.

3.2 Specification of Digest Headers

The Digest Access Authentication scheme is conceptually similar to the Basic scheme. The formats for the modified WWW-Authenticate header line and the Authorization header line are specified below. In addition, a new header, Authentication-Info, is also specified.

3.2.1 The WWW-Authenticate Response Header

If a server receives a request for an access-protected object, and an acceptable Authorization header is not sent, the server responds with a "401 Unauthorized" status code, and a WWW-Authenticate header as per the framework defined above, which for the digest scheme is utilized as follows:

challenge        =  "Digest" digest-challenge

digest-challenge  = 1#( realm | [ domain ] | nonce |
                    [ opaque ] |[ stale ] | [ algorithm ] |
                    [ qop-options ] | [auth-param] )

domain            = "domain" "=" <"> URI ( 1*SP URI ) <">
URI               = absoluteURI | abs_path
nonce             = "nonce" "=" nonce-value
nonce-value       = quoted-string
opaque            = "opaque" "=" quoted-string
stale             = "stale" "=" ( "true" | "false" )
algorithm         = "algorithm" "=" ( "MD5" | "MD5-sess" | token )
qop-options       = "qop" "=" <"> 1#qop-value <">
qop-value         = "auth" | "auth-int" | token

The meanings of the values of the directives used above are as follows:

realm

• A string to be displayed to users so they know which username and password to use. This string should contain at least the name of the host performing the authentication and might additionally indicate the collection of users who might have access. An example might be "[email protected]".

domain

• A quoted, space-separated list of URIs that define the protection space. If a URI is an abs_path, it is relative to the canonical root URL of the server being accessed. An absoluteURI in this list may refer to a different server than the one being accessed. If this directive is omitted or its value is empty, the client should assume that the protection space consists of all URIs on the responding server.

nonce

• A server-specified data string which should be uniquely generated each time a 401 response is made. It is recommended that this string be base64 or hexadecimal data. The nonce is opaque to the client.

opaque

• A string of data, specified by the server, which should be returned by the client unchanged in the Authorization header of subsequent requests with URIs in the same protection space.

stale

• A flag, indicating that the previous request from the client was rejected because the nonce value was stale. If stale is TRUE (case-insensitive), the client may wish to simply retry the request with a new encrypted response, without reprompting the user for a new username and password.

algorithm

• A string indicating a pair of algorithms used to produce the digest and a checksum. If this is not present it is assumed to be "MD5". If the algorithm is not understood, the challenge should be ignored.

qop-options

• This directive is optional, but is made so only for backward compatibility with RFC 2069 [6]; it SHOULD be used by all implementations compliant with this version of the Digest scheme. If present, it is a quoted string of one or more tokens indicating the "quality of protection" values supported by the server. The value "auth" indicates authentication; the value "auth-int" indicates authentication with integrity protection. Unrecognized options MUST be ignored.

3.2.2 The Authorization Request Header

The client is expected to retry the request, passing an Authorization header line with the response directive calculated as specified below.

credentials      = "Digest" digest-response
digest-response  = 1#( username | realm | nonce | digest-uri
                   | response | [ algorithm ] | [cnonce] |
                   [opaque] | [message-qop] |
                   [nonce-count]  | [auth-param] )

username         = "username" "=" username-value
username-value   = quoted-string
digest-uri       = "uri" "=" digest-uri-value
digest-uri-value = request-uri
message-qop      = "qop" "=" qop-value
cnonce           = "cnonce" "=" cnonce-value
cnonce-value     = nonce-value
nonce-count      = "nc" "=" nc-value
nc-value         = 8LHEX
response         = "response" "=" request-digest
request-digest   = <"> 32LHEX <">
LHEX             = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
                   "8" | "9" | "a" | "b" | "c" | "d" | "e" | "f"

3.2.3 The Authentication-Info Header

The Authentication-Info header field MAY be used by the server in a response to transmit information about the successful authentication. This header is particularly useful with the "auth-int" quality of protection.

AuthenticationInfo = "Authentication-Info" ":" auth-info
auth-info          = 1#(nextnonce | [ message-qop ]
                     | [ response-auth ] | [ cnonce ]
                     | [nonce-count] )
nextnonce          = "nextnonce" "=" nonce-value
response-auth      = "rspauth" "=" response-digest
response-digest    = <"> *LHEX <">

3.3 Digest Operation

The operation of Digest access authentication is as follows. The client makes a request to the server, which challenges with a 401 response providing a nonce and other parameters. The client uses these parameters to calculate the response value and sends it along with other information in a subsequent request to the server. The server verifies the response value, and if correct, grants access.

3.4 Security Protocol Negotiation

A server may provide multiple challenges in the WWW-Authenticate header, each using a different authentication scheme. The client SHOULD select the strongest scheme it supports.

3.5 Example

The following example assumes access to the protected document requires authentication. The server challenges with a 401 response:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Digest
    realm="[email protected]",
    qop="auth,auth-int",
    nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
    opaque="5ccc069c403ebaf9f0171e9517f40e41"

The client may respond with the following Authorization header:

Authorization: Digest username="Mufasa",
    realm="[email protected]",
    nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
    uri="/dir/index.html",
    qop=auth,
    nc=00000001,
    cnonce="0a4f113b",
    response="6629fae49393a05397450978507c4ef1",
    opaque="5ccc069c403ebaf9f0171e9517f40e41"

3.6 Proxy-Authentication and Proxy-Authorization

Proxy authentication and authorization work similarly to origin server authentication and authorization, but use the Proxy-Authenticate and Proxy-Authorization header fields. The proxy MUST be completely transparent in handling authentication between the client and origin server.

---