Apache Module mod_auth_digest

Available Languages: en | fr | ko

Description:	User authentication using MD5 Digest Authentication
Status:	Extension
Module Identifier:	auth_digest_module
Source File:	mod_auth_digest.c

Summary

This module implements HTTP Digest Authentication (RFC 2617), an alternative to the Basic authentication provided by mod_auth_basic in which the password is not sent over the network in cleartext.

Basic and Digest are both authentication schemes only: they establish who the client is, and do nothing for the confidentiality or integrity of the request and response themselves. Over an unencrypted connection the contents of every request and response are exposed with either scheme; Digest's one advantage is that the password is not among them. Digest is therefore not a substitute for a connection secured with mod_ssl, which protects the credentials and the data alike, and that one advantage has limits of its own (see the note below).

Topics

Using Digest Authentication

Bugfix checklist

Using Digest Authentication ¶

To use MD5 Digest authentication, configure the location to be protected as shown in the below example:

Example:

<Location "/private/">
    AuthType Digest
    AuthName "private area"
    AuthDigestDomain "/private/" "http://mirror.my.dom/private2/"

    AuthDigestProvider file
    AuthUserFile "/web/auth/.digest_pw"
    Require valid-user
</Location>

AuthDigestDomain should list the locations that will be protected by this configuration.

The password file referenced in the AuthUserFile directive may be created and managed using the htdigest tool.

Note

Digest authentication's one advantage over Basic, keeping the password off the wire, is conditional. If the client will silently fall back to Basic when challenged, an active attacker can strip the Digest challenge and offer Basic instead, and the browser then sends the password in cleartext; a passive eavesdropper can mount an offline brute-force attack on a captured response, which the fast MD5 hash does little to slow; and if the htdigest file is stolen its stored hashes can be replayed to authenticate to that realm directly, without the password itself being recovered. Encrypt the whole connection with mod_ssl instead.

mod_auth_digest requires an APR built with shared memory support, and is not built without it.

AuthDigestAlgorithm Directive ¶

Description:	Selects the algorithm used to calculate the challenge and response hashes in Digest authentication
Syntax:	`AuthDigestAlgorithm MD5`
Default:	`AuthDigestAlgorithm MD5`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Extension
Module:	mod_auth_digest

The AuthDigestAlgorithm directive selects the algorithm used to calculate the challenge and response hashes. Only MD5 is supported.

AuthDigestDomain Directive ¶

Description:	URIs that are in the same protection space for Digest authentication
Syntax:	`AuthDigestDomain URI [URI] ...`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Extension
Module:	mod_auth_digest

The AuthDigestDomain directive allows you to specify one or more URIs which are in the same protection space (i.e. use the same realm and username/password info). The specified URIs are prefixes; the client will assume that all URIs "below" these are also protected by the same username/password. The URIs may be either absolute URIs (i.e. including a scheme, host, port, etc.) or relative URIs.

This directive should always be specified and contain at least the (set of) root URI(s) for this space. Omitting to do so will cause the client to send the Authorization header for every request sent to this server. Apart from increasing the size of the request, it may also have a detrimental effect on performance if AuthDigestNcCheck is on.

The URIs specified can also point to different servers, in which case clients (which understand this) will then share username/password info across multiple servers without prompting the user each time.

AuthDigestNcCheck Directive ¶

Description:	Enables or disables checking of the nonce-count sent by the client
Syntax:	`AuthDigestNcCheck On\|Off`
Default:	`AuthDigestNcCheck Off`
Context:	server config, virtual host, directory, .htaccess
Override:	AuthConfig
Status:	Extension
Module:	mod_auth_digest

The AuthDigestNcCheck directive enables or disables the verification of the nonce-count value sent by the client. The nonce-count is a sequential counter that the client increments with each request using the same nonce. Checking it helps detect replay attacks.

This feature requires shared memory support on the platform. If shared memory is not available and this directive is set to On, the server will return an error at startup.

While recommended from a security standpoint, enabling this directive has a performance implication: all requests carrying an Authorization header must be serialized through a critical section in order to safely compare nonce-count values. On high-traffic servers this may be noticeable.

AuthDigestNonceLifetime Directive ¶

Description:	How long the server nonce is valid
Syntax:	`AuthDigestNonceLifetime seconds`
Default:	`AuthDigestNonceLifetime 300`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Extension
Module:	mod_auth_digest

The AuthDigestNonceLifetime directive controls how long the server nonce is valid. When the client contacts the server using an expired nonce the server sends back a 401 with stale=true, and an RFC-compliant client retries with a fresh nonce without prompting the user.

If seconds is greater than 0 then it specifies the amount of time for which the nonce is valid; this should probably never be set to less than 10 seconds.
If seconds is 0 then the nonce may be used exactly once. The server supplies the next nonce in the Authentication-Info header of each response so the client can continue; a client which reuses a nonce is answered with stale=true and retries. One-time nonces give stronger protection against replaying a captured request, but the client cannot pipeline requests, and one that does receives a 401 for all but the first and has to resend them. The protection is worth this cost mainly for requests that change server state or return content which varies over time; replaying a request for unchanging content that the eavesdropper already captured in full gains nothing.
If seconds is less than 0 then the nonce never expires.

AuthDigestProvider Directive ¶

Description:	Sets the authentication provider(s) for this location
Syntax:	`AuthDigestProvider provider-name [provider-name] ...`
Default:	`AuthDigestProvider file`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Extension
Module:	mod_auth_digest

The AuthDigestProvider directive sets which provider is used to authenticate the users for this location. The default file provider is implemented by the mod_authn_file module. Make sure that the chosen provider module is present in the server.

See mod_authn_dbm, mod_authn_file, mod_authn_dbd and mod_authn_socache for providers.

AuthDigestQop Directive ¶

Description:	Determines the quality-of-protection to use in Digest authentication
Syntax:	`AuthDigestQop auth`
Default:	`AuthDigestQop auth`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Extension
Module:	mod_auth_digest

The AuthDigestQop directive determines the quality-of-protection to use. Only auth (authentication) is supported, and it is the default, so this directive no longer has any effect and is retained only for compatibility.

Earlier releases also accepted none (the RFC 2069 Digest scheme, without a quality-of-protection). It has been removed: a request whose qop is missing or not auth is now rejected.

AuthDigestShmemSize Directive ¶

Description:	The amount of shared memory to allocate for keeping track of clients
Syntax:	`AuthDigestShmemSize size`
Default:	`AuthDigestShmemSize 8192`
Context:	server config
Status:	Extension
Module:	mod_auth_digest

The AuthDigestShmemSize directive defines the amount of shared memory, that will be allocated at the server startup for keeping track of clients. Note that the shared memory segment cannot be set less than the space that is necessary for tracking at least one client. This value is dependent on your system. If you want to find out the exact value, you may simply set AuthDigestShmemSize to the value of 0 and read the error message after trying to start the server.

The default holds roughly 140 clients. A client which is discarded to make room for another is not denied access: it is issued a new nonce with stale=true, which costs it one extra request. Note that a request which does not authenticate also takes an entry, since the challenge sent back to it carries the identifier the client is tracked by.

The size is normally expressed in Bytes, but you may follow the number with a K or an M to express your value as KBytes or MBytes. For example, the following directives are all equivalent:

AuthDigestShmemSize 1048576
AuthDigestShmemSize 1024K
AuthDigestShmemSize 1M