Apache Module mod_auth_digest

Available Languages: en | + ko

+ + + +

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

Summary

+ +

This module implements HTTP Digest Authentication. However, it + has not been extensively tested and is therefore marked + experimental.

Topics

Using Digest Authentication
Working with MS Internet Explorer

Using Digest Authentication

+ +

Using MD5 Digest authentication is very simple. Simply set + up authentication normally, using AuthType Digest and + AuthDigestFile instead + of the normal AuthType Basic and AuthUserFile; also, replace any AuthGroupFile with AuthDigestGroupFile. Then add a + AuthDigestDomain directive + containing at least the root URI(s) for this protection space.

+ +

Appropriate user (text) files can be created using the + htdigest tool.

+ +

Example:

+ <Location /private/> + + AuthType Digest + AuthName "private area" + AuthDigestDomain /private/ http://mirror.my.dom/private2/ + AuthDigestFile /web/auth/.digest_pw + Require valid-user + + </Location> +

+ +

Note

Digest authentication provides a more secure password system + than Basic authentication, but only works with supporting + browsers. As of November 2002, the major browsers that support digest + authentication are Opera, MS Internet + Explorer (fails when used with a query string - see "Working with MS Internet Explorer" below for a workaround), Amaya, Mozilla and Netscape since version 7. Since digest authentication is not + as widely implemented as basic authentication, you should use it only + in controlled environments.

Working with MS Internet Explorer

The Digest authentication implementation in previous Internet + Explorer for Windows versions (5 and 6) had issues, namely that + GET requests with a query string were not RFC compliant. + There are a few ways to work around this issue.

+ +

+ The first way is to use POST requests instead of + GET requests to pass data to your program. This method + is the simplest approach if your application can work with this + limitation. +

+ +

Since version 2.0.51 Apache also provides a workaround in the + AuthDigestEnableQueryStringHack environment variable. + If AuthDigestEnableQueryStringHack is set for the + request, Apache will take steps to work around the MSIE bug and + remove the query string from the digest comparison. Using this + method would look similar to the following.

+ +

Using Digest Authentication with MSIE:

+ BrowserMatch "MSIE" AuthDigestEnableQueryStringHack=On +

+ +

This workaround is not necessary for MSIE 7, though enabling it does + not cause any compatibility issues or significant overhead.

+ +

See the BrowserMatch + directive for more details on conditionally setting environment + variables

AuthDigestAlgorithm Directive

+ + + + + + + + +

Description:	Selects the algorithm used to calculate the challenge and +response hases in digest authentication
Syntax:	`AuthDigestAlgorithm MD5\|MD5-sess`
Default:	`AuthDigestAlgorithm MD5`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Experimental
Module:	mod_auth_digest

The AuthDigestAlgorithm directive + selects the algorithm used to calculate the challenge and response + hashes.

+ +

+ MD5-sess is not correctly implemented yet. +

+ + +

AuthDigestDomain Directive

+ + + + + + + +

Description:	URIs that are in the same protection space for digest +authentication
Syntax:	`AuthDigestDomain URI [URI] ...`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Experimental
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, i.e. 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.

+ +

AuthDigestFile Directive

+ + + + + + + +

Description:	Location of the text file containing the list +of users and encoded passwords for digest authentication
Syntax:	`AuthDigestFile file-path`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Experimental
Module:	mod_auth_digest

The AuthDigestFile directive sets the + name of a textual file containing the list of users and encoded + passwords for digest authentication. File-path is the + absolute path to the user file.

+ +

The digest file uses a special format. Files in this format + can be created using the htdigest utility found in + the support/ subdirectory of the Apache distribution.

+ +

AuthDigestGroupFile Directive

+ + + + + + + +

Description:	Name of the text file containing the list of groups +for digest authentication
Syntax:	`AuthDigestGroupFile file-path`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Experimental
Module:	mod_auth_digest

The AuthDigestGroupFile directive sets + the name of a textual file containing the list of groups and their + members (user names). File-path is the absolute path to + the group file.

+ +

Each line of the group file contains a groupname followed by + a colon, followed by the member usernames separated by spaces. + Example:

+ +

mygroup: bob joe anne

+ +

Note that searching large text files is very + inefficient.

+ +

Security:

Make sure that the AuthGroupFile is stored + outside the document tree of the web-server; do not put it in + the directory that it protects. Otherwise, clients may be able + to download the AuthGroupFile.

+ +

AuthDigestNcCheck Directive

+ + + + + + + +

Description:	Enables or disables checking of the nonce-count sent by the +server
Syntax:	`AuthDigestNcCheck On\|Off`
Default:	`AuthDigestNcCheck Off`
Context:	server config
Status:	Experimental
Module:	mod_auth_digest

+ Not implemented yet. +

+ + +

AuthDigestNonceFormat Directive

+ + + + + + + +

Description:	Determines how the nonce is generated
Syntax:	`AuthDigestNonceFormat format`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Experimental
Module:	mod_auth_digest

Not implemented yet.

+ + +

AuthDigestNonceLifetime Directive

+ + + + + + + + +

Description:	How long the server nonce is valid
Syntax:	`AuthDigestNonceLifetime seconds`
Default:	`AuthDigestNonceLifetime 300`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Experimental
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 will send + back a 401 with stale=true. 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 less than 0 then the nonce never + expires. +

+ +

AuthDigestQop Directive

+ + + + + + + + +

Description:	Determines the quality-of-protection to use in digest +authentication
Syntax:	`AuthDigestQop none\|auth\|auth-int [auth\|auth-int]`
Default:	`AuthDigestQop auth`
Context:	directory, .htaccess
Override:	AuthConfig
Status:	Experimental
Module:	mod_auth_digest

The AuthDigestQop directive determines + the quality-of-protection to use. auth will only do + authentication (username/password); auth-int is + authentication plus integrity checking (an MD5 hash of the entity + is also computed and checked); none will cause the module + to use the old RFC-2069 digest algorithm (which does not include + integrity checking). Both auth and auth-int may + be specified, in which the case the browser will choose which of + these to use. none should only be used if the browser for + some reason does not like the challenge it receives otherwise.

+ +

+ auth-int is not implemented yet. +

+ +

AuthDigestShmemSize Directive

+ + + + + + + +

Description:	The amount of shared memory to allocate for keeping track +of clients
Syntax:	`AuthDigestShmemSize size`
Default:	`AuthDigestShmemSize 1000`
Context:	server config
Status:	Experimental
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 neccessary for + tracking at least one client. This value is dependant 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 size is normally expressed in Bytes, but you + may let the number follow 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 +

+ +

Apache Module mod_auth_digest

Summary

Directives

Topics

See also

Example:

Note

Using Digest Authentication with MSIE:

Security: