How Digest Authentication Works

Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2

How Digest Authentication Works

In This Section

• Digest SSP Architecture

• Digest Authentication Processes and Interactions

• Network Ports Used by Digest Authentication

• Related Information

Digest SSP Architecture

The Windows Server 2003 operating system implements the Digest Authentication protocol as a security support provider (SSP), a dynamic-link library (DLL) that is supplied with the operating system. Which SSP is used depends on the capabilities of the computer on the other side of the connection and the preferences of the individual application that is being used.

The Microsoft Security Support Provider Interface (SSPI) is the foundation for authentication in Windows Server 2003. Applications and infrastructure services that require authentication use SSPI to provide it.

SSPI is the implementation of the Generic Security Service API (GSSAPI) in Windows Server 2003. For more information about GSSAPI, see RFC 2743 and RFC 2744 in the IETF RFC Database.

The default SSPs in Windows Server 2003 — Negotiate (SPNEGO), Kerberos, NTLM, Schannel, and Digest Authentication protocols — are incorporated into the SSPI as DLLs. Additional SSPs can be incorporated if they can operate with the SSPI.

SSPI Architecture

The SSPI in Windows Server 2003 provides a mechanism that carries authentication tokens over the existing communication channel between the client and server. When two parties need to be authenticated so that they can communicate securely, the requests for authentication are routed to the SSPI, which completes the authentication process, regardless of the network protocol currently in use. The SSPI returns transparent binary large objects, these are passed between the applications, at which point they can be passed to the SSPI layer on that side. Thus, the SSPI enables an application to use various security models available on a computer or network without changing the interface to the security system.

The following table describes the SSP components that are plugged into the SSPI. Each of the protocols in the table is used in different ways in Windows Server 2003 to promote secure communication in an unsecure network environment.

SSP Layer Components

Digest SSP

The Digest SSP, which is implemented through wdigest.dll, is one of the authentication protocols for some applications such as LDAP and HTTP. Depending on your deployment scenario, it might be the preferred protocol.

The Digest SSP is used for the following:

• Internet Explorer (IE) and Internet Information Services (IIS) access

• LDAP queries

Digest Authentication Processes and Interactions

Digest Authentication Scheme

Overview of a Digest Authentication Scheme That Is Using HTTP

The Digest Authentication process involves the following steps:

1. The client sends the server a request for an access-protected resource.

2. The server receives the request from the client and recognizes that the request is for information or a service that requires authentication. The server checks whether the client has provided authentication information. Because this is the client’s first request, it does not find any. The server responds by returning an HTTP WWW-Authenticate header to the client. This header includes the following:

   • The domain for which the server must supply credentials.

   • Information about whether authentication is required. If the exchange is Secure Authentication Socket Layer (SASL)-based, integrity and confidentiality might also be specified.

   • Server-side data, which often includes items such as a timestamp, nonce and an HTML tag that references the Uniform Resource Indicator (URI) requested, and is protected in the server’s private key.

   • Hints about the security context.

   • A list of ciphers that the server supports.

   • Specification of the encryption algorithm that is used in this authentication protocol. If the authentication is SASL-based, rather than HTTP-based, RC4 is the algorithm that is used in Windows Server 2003, although this is extensible and could be designed to use other algorithms.

   The header is returned with a 401 message code, indicating that the client’s request has generated an unauthorized access error.

3. The client receives the server’s challenge and gathers the required credentials, either by accessing information in existing credentials or by prompting the user. The client’s challenge response is then hashed with the user’s secret key. This response includes the following parts:

   • The original nonce protected with the user’s secret key, proving the client’s knowledge of the user’s password.

   • The user name and domain.

   • The original nonce and timestamp sent by the server, the number of times this number has been used, and a new random number, called a nonce number, which is unique and is used only once. To prevent replay attacks nonce counts are used.

   • The URI, which is the location of the resource that the client initially requested.

   • Information about whether authentication, integrity, and confidentiality is used.

   • Specification of the algorithms that are used.

4. The server receives the message and, as part of the authentication of the challenge response, the following checks are made:

   • That the challenge response is to a challenge issued by the server, and not another source.

   • That the challenge response message is properly formatted and the server-enforced options are valid.

   • That the nonce number has not been used before in challenge responses, to ensure that this is not a replay attack.

   If any of these checks fail, the server fails the authentication of the request.

   If the response meets the server’s criteria, it relays the client’s response to a domain controller, which completes the authentication. The Digest SSP checks whether the Digest Authentication response is valid and ensure that access restrictions, such as an expired password, do not apply.

   If the check is successful, the domain controller notifies the server that the client is authentic. A Digest Authentication session key is also returned to the originating server. If the check is not successful, the originating server sends the client an error message. After a successful authentication, the originating server allows the client to access the resource indicated by the URI.

   The Digest Authentication session key returned by the authenticating domain controller is cached by the originating server for use in authenticating future requests.

Authentication of Subsequent Requests

Example Subsequent Request Using HTTP

For subsequent requests, the client simply needs to send an authorization header with the security context reference to the server, because the security context has already been established with the server.

Digest Authentication Headers

Because Digest Authentication is accomplished through other protocols such as HTTP and LDAP, what is defined next is the challenge and challenge response that applications will transport to the Digest SSP.

WWW-Authenticate Response Header

When the server receives a request for an access-protected resource, the server replies with a “401 Unauthorized” status code and a WWW-Authenticate header with the digest scheme below. This section describes the directives that make up a Digest Authentication challenge.

RFC 2831 requires the size of a Digest Authentication challenge must be less than 2048 bytes. The Digest SSP enforces this for all Digest Authentication challenges. Following digest scheme is used:

Challenge = “Digest” digest-challenge

HTTP Authentication Digest-challenge = 1# (realm=realm | [domain=“domainname”] | nonce=“nonce-value” | [opaque=“opaque-value”] | [stale=(“true” | “false”)] | [algorithm=(“MD5” | “MD5-sess” | token] | [qop=1#(“auth” | “auth-int” | token)] | [auth-parm]

SASL Digest-challenge = 1# (“realm” | nonce=“nonce-value” | [qop=1#(“auth” | “auth-int” | “auth-conf” | token”)] | [stale=(true | false)] | [maxbuf=maxbuf] | [charset=charset] | [algorithm=(“MD5” | “MD5-sess” | token] | [cipher=(“3des” | “des” | “rc4-40” | “rc4” | “rc4-56” | token) | [auth-parm]

Note

• RFC 2617-compliant Digest Authentication challenges and responses must also comply with RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 quoted string requirements. This requirement particularly affects the use of backslash (\) and embedded double quotes. Both must be preceded (escaped) with a backslash.

• For example, domain\username according to RFC 2616 is read as domainusername. This reading is important because if an application sends information in this format rather than as domain\\username, authentication fails.

• However, because this is a known issue with domain\username , if authenticating with backslash encoding fails, Digest SSP attempts to authenticate the response and assumes that the backslash is part of the string. This behavior can be turned off by setting the ServerCompat registry key.

A Digest Authentication challenge can contain the following directives, which are defined in the relevant RFCs.

Realm

An implementation-defined string that is displayed to users if Digest Authentication is prompting users for credentials. This string helps users know which user name and password is required.

Domainname (optional, not used in-SASL)

A space-separated list of URIs that are contained in quotation marks and that define the protection space.

Nonce-value

A unique, encoded value that is generated by the server for each challenge. This value must not be altered by the client.

Opaque-value (optional, not used in-SASL)

A string of data specified by the server that contains a reference for the security context that is being established.

Stale (optional)

A flag that when set to TRUE indicates that the previous request from the client was rejected because the nonce value was stale, but the digest was valid. When not set to TRUE or not present then the user name and/or password are invalid and new values must be obtained.

Algorithm (optional)

A string indicating that the pair of algorithms used to produce the digest and checksum. If MD5 is not present, it is assumed. Digest SSP supports MD5 and MD5-Sess. For optimal performance, use MD5-Sess.

QOP-(optional)

Should be used by all RFC 2617-compliant implementations. The quality of protection (QOP) determines the level of security that is used when sending and receiving messages. The possible values for the QOP directive are described in the following table.

QOP Options

Auth-parm (optional)

Allows for future extensions of the RFC. Unrecognized directives must be ignored.

• Maxbuf (optional, SASL only)

  Number indicating the size of the largest buffer the server is able to receive when using “auth-int” or “auth-conf.” The default is 65536.

• Charset (optional)

  Specified in RFC 2831, the charset directive can be set to UTF-8 if the server can process UTF-8–encoded user names and realms.

  Note

  • Digest SSP uses the charset directive for both HTTP and SASL mode. This directive allows the use of UTF-8 in HTTP mode. To maintain backwards compatibility with clients that do not understand the charset directive, the realm in the challenge is encoded in the standard ISO 8859-1 (Latin-1) character set. If the client understands the charset directive, then the username and realm (and password) can be encoded in UTF-8 in the challenge response sent back to the server. If the client does not understand the charset directive, then the standard ISO 8859-1 (Latin-1) must be used.

• Cipher (SASL only)

  The list of ciphers that the server supports. This element can be present in a Digest SASL challenge only if the QOP directive specifies auth-conf.

Authorization Request Header

The client must send the server a Digest Authentication challenge response when it receives a Digest Authentication challenge in response to a request for a resource. The client must send the request again and supply an Authorization Request header with the challenge response. This section describes the directives that make up a Digest Authentication challenge response.

RFC 2831 requires that the size of a Digest Authentication challenge response must be less than 4096 bytes. The Digest SSP enforces this for all Digest Authentication challenge responses. The following digest scheme is used:

Credentials = “Digest” digest-response

HTTP Authentication Digest-response = 1# (username=“username”| realm | nonce | uri=digest-uri | response=“response ”| [algorithm] | [cnonce=cnonce] | [opaque] | [qop=message-qop] | [nc=nonce-count] | [auth-param])

SASL Digest-response = 1# (username=“username”| realm | nonce | [cnonce=cnonce] | [nc=nonce-count] | [qop=message-qop] | uri=digest-uri | response="response” | [maxbuf=maxbuf] | [charset=charset] | cipher=cipher | [authzid=authzid] | [auth-param])

Username

The account name of the security principal requesting the resource.

Realm

The name of the domain that contains the account indicated by the user name.

Nonce

The nonce received in the Digest Authentication challenge.

Digest-URI

The URI of the requested resource.

Response

A value computed according to RFC 2617. An accurate response is conclusive proof that the user’s password is known on the client side.

Algorithm (Optional, not used in-SASL)

The algorithm received in the Digest Authentication challenge.

Cnonce (Optional)

A unique, encoded value that is generated by the client for each challenge response, and that is used to avoid chosen plaintext attacks, provides some message integrity protection, and provides mutual authentication. This authentication is provided mutually in that the server proves it knows the user’s secret information and not in that the server proves its identity. The nonce must be specified if a QOP directive is sent.

Opaque (Optional, not used in-SASL)

The opaque value received in the Digest Authentication challenge.

Message-QOP (Optional)

The quality of protection.

Nonce-count (optional)

The nonce count. The number of times the client has sent a challenge response by using the nonce. The nonce must be specified if a QOP directive is sent.

Auth-parm (optional)

Allows for future extensions of RFC. Unrecognized directives must be ignored.

• Maxbuf (optional, SASL only)

  Number indicating the size of the largest buffer that the client is able to receive. The default is 65536.

• Charset (optional)

  If the client understands the charset directive, it can respond by using UTF-8–encoded values.

  Note

  • Digest SSP uses the charset directive for both HTTP and SASL mode. This allows the use of UTF-8 in HTTP mode. To maintain backwards compatibility with clients that do not understand charset directive, the realm in the challenge is encoded in the standard ISO 8859-1 (Latin-1) character set. If the client understands the charset directive, then the username and realm (and password) can be encoded in UTF-8 in the challenge response sent back to the server. If the client does not understand the charset directive, then the standard ISO 8859-1 (Latin-1) must be used.

• Cipher (SASL only)

  The cipher selected by the client. This element must be present in a Digest SASL challenge if the QOP directive specifies auth-conf.

• Authzid (optional, SASL only)

  The authorization ID is specified in RFC 2222 and encoded in UTF-8. If the authenticating user has sufficient privilege and the server supports it, the server uses this ID after authentication for making all accesses and access checks. If the server does not support authorization ID, then authentication fails if the client specifies it.

Authentication-Info Header

The server sends an HTTP response with an Authentication-Info Header with Security Context Reference back to the client. This section describes the directives that make up an Authentication-Info Header.

AuthenticationInfo = “Authentication-Info” : auth-info

Auth-info = 1# (nextnonce=noncevalue | [qop=message-qop] | [rspauth=response-digest] | [cnonce=cnonce] | [nc=nonce-count])

Noncevalue

The nonce that the server requires the client to use for future authentication responses. This nonce is not supported by Digest SSP (wdigest.dll).

Message-QOP (Optional)

The quality of protection applied by the server.

Response-digest (Optional)

Supports mutual authentication. This authentication is provided mutually in that the server proves it knows the user’s secret information and not in that the server proves its identity.

Cnonce (Optional)

A unique, encoded value generated by the client for each challenge response and that is used to avoid chosen plaintext attacks, provide mutual authentication, and provide some message integrity protection. The nonce must be specified if a QOP directive is sent.

Nonce-count (optional)

The nonce count. The number of times the client has sent a challenge response by using the nonce. The nonce must be specified if a QOP directive is sent.

SASL

The Digest SASL mechanism defined in RFC 2831 describes the use of Digest Authentication as a SASL mechanism. Integrity protection on the application protocol messages is added as a new feature after the authentication exchange.

Quality of Protection and Ciphers

The quality of protection determines the level of security that is used when sending and receiving messages. The Digest SSP selects a level of integrity or confidentiality based on the requirements of the client and server.

When using Digest Authentication as a SASL mechanism, applications can specify that messages be kept confidential by using encryption. The server specifies the ciphers that it supports for encrypted messages, and the client selects a cipher from this list.

Quality of Protection

The quality of protection, identified by the QOP directive, is first specified by the server in the Digest Authentication challenge, and then confirmed by the client in the challenge response. If the client requires a quality of protection that the server does not support, the client must terminate the authentication.

The possible values for the QOP directive are described in the following table.

QOP Options

Ciphers

The following material is valid only when Digest is used as a SASL mechanism. Ciphers and encryption are not available for HTTP authentication by using Digest Authentication.

A Digest SASL challenge’s cipher directive contains a list of the ciphers supported by a server that requires confidential communications. The cipher directive can only be included if the QOP directive is set to “auth-conf.” The ciphers recognized by Digest Authentication are listed in the following table, from strongest to weakest.

Ciphers That Are Supported by Digest Authentication

When a server application requests confidentiality (qop=auth-conf) the Digest SSP generates a challenge that offers the client all of the ciphers that are installed on the server and supported by Digest Authentication. The Digest client selects the strongest available cipher.

Password Hashes

The use of precalculated hashes is a new feature that allows system operators to skip the use of reversible encrypted passwords on the domain controller. A precalculated hash is formed for a user when the user’s password is changed.

Active Directory stores the following password-related materials:

• NTLM hash created by the NTLM SSP

• Kerberos key created by the Kerberos SSP

• Digest hashes created by the Digest SSP

When account passwords are modified (during either account creation or password reset/change), Security Account Manager (SAM) requests the authentication packages so that it can provide updated credential information based on the new password.

When passwords are changed, credential update notifications are sent to the authentication packages that have registered for credential updates.

Digest Hashes

Digest Authentication verifies passwords by computing a hash of the account name, realm property, and password. The specific format is H(username:realm:password) where H() is the MD5 hash operation. As this form shows, the plaintext password is required to compute the MD5 hash. To use Digest Authentication in previous versions of Windows Server, reversible encryption has to be set on an account. This setting allows the security provider to compute the digest hash when it is authenticating a server request by using Digest Authentication. In Windows Server 2003, a new digest hash is created and stored in Active Directory when a password is modified on an account. This digest hash contains several pre-computed versions of the H(username:realm:password) hash and permits these hashes to be authenticated without requiring reversible encryption to be enabled on an account.

The specific, precomputed forms are:

Digest Hashes

Where NetBiosName is FlatDomainName\SamAccountName.

Because the SamAccountName, UPN, and NetBiosName can have mixed cases, additional hashes are computed with these in lower case, upper case, and the original case used when account created.

Note

• Because only three versions of the user name are hashed, other variants of the user name do not work. For example, user, USER, and User might be created, but if presented with UsEr authentication would fail.

During the authentication of a request from a server, the challenge response sent from the client is compared to the pre-computed hashes stored on the user account. If a match is found, the server is notified by the domain controller that the challenge response is valid. If no match is found, a check is made by the domain controller to see if Reversible Encryption is enabled for the user account; if it is enabled, the domain controller computes the Digest hash with the plaintext version of the account’s password, and a final validity test is performed by the domain controller on the challenge response.

Network Ports Used by Digest Authentication

Digest Authentication is not a network protocol. It uses the application protocol, so the port that Digest Authentication challenges and responses are sent by varies based on which application requests Digest Authentication and what port that application uses to communicate.

Related Information

The following resources contain additional information that is relevant to this section.

• RFC 2616 in the IETF RFC Database

• RFC 2617 in the IETF RFC Database

• RFC 2743 in the IETF RFC Database

• RFC 2744 in the IETF RFC Database

• RFC 2831 in the IETF RFC Database