<?xml version="1.0"?>

<?xml-stylesheet type="text/xsl" href="/style/manual.xsl"?>

<modulesynopsis>

<name>mod_auth_digest</name>

<description>User authentication using MD5

Digest Authentication.</description>

<status>Experimental</status>

<sourcefile>mod_auth_digest.c</sourcefile>

<identifier>auth_digest_module</identifier>

<summary>

<p>This module implements HTTP Digest Authentication. However, it

has not been extensively tested and is therefore marked

experimental.</p>

</summary>

<seealso><directive module="core">AuthName</directive></seealso>

<seealso><directive module="core">AuthType</directive></seealso>

<seealso><directive module="core">Require</directive></seealso>

<seealso><directive module="core">Satisfy</directive></seealso>

<section><title>Using Digest Authentication</title>

<p>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.

Example:</p>

<example>

&lt;Location /private/&gt;<br />

AuthType Digest<br />

AuthName "private area"<br />

AuthDigestDomain /private/ http://mirror.my.dom/private2/<br />

AuthDigestFile /web/auth/.digest_pw<br />

Require valid-user<br />

&lt;/Location&gt;

</example>

<note><title>Note</title>

<p>MD5 authentication provides a more

secure password system than Basic authentication, but only

works with supporting browsers. As of this writing (October 2001),

the only major browsers which support digest authentication are

<a href="http://www.opera.com/">Opera 4.0</a>,

<a href="http://www.microsoft.com/windows/ie/">MS Internet

Explorer 5.0</a> and <a href="http://www.w3.org/Amaya/">Amaya</a>.

Therefore, we do not yet recommend using this feature on a large

Internet site. However, for personal and intra-net use, where

browser users can be controlled, it is ideal.</p>

</note>

</section>

<directivesynopsis>

<name>AuthDigestFile</name>

<description>Location of the text file containing the list

of users and encoded passwords for digest authentication</description>

<syntax>AuthDigestFile <em>file-path</em></syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>The <directive>AuthDigestFile</directive> directive sets the

name of a textual file containing the list of users and encoded

passwords for digest authentication. <em>File-path</em> is the

absolute path to the user file.</p>

<p>The digest file uses a special format. Files in this format

can be created using the <a

href="/programs/htdigest.html">htdigest</a> utility found in

the support/ subdirectory of the Apache distribution.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestGroupFile</name>

<description>Name of the text file containing the list of groups

for digest authentication</description>

<syntax>AuthDigestGroupFile <em>file-path</em></syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>The <directive>AuthDigestGroupFile</directive> directive sets

the name of a textual file containing the list of groups and their

members (user names). <em>File-path</em> is the absolute path to

the group file.</p>

<p>Each line of the group file contains a groupname followed by

a colon, followed by the member usernames separated by spaces.

Example:</p>

<example>mygroup: bob joe anne</example>

<p>Note that searching large text files is <em>very</em>

inefficient.</p>

<p>Security: make sure that the AuthGroupFile is stored outside

the document tree of the web-server; do <em>not</em> put it in

the directory that it protects. Otherwise, clients will be able

to download the AuthGroupFile.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestQop</name>

<description>Determines the quality-of-protection to use in digest

authentication</description>

<syntax>AuthDigestQop none|auth|auth-int [auth|auth-int]</syntax>

<default>AuthDigestQop auth</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>The <directive>AuthDigestQop</directive> directive determines

the quality-of-protection to use. <em>auth</em> will only do

authentication (username/password); <em>auth-int</em> is

authentication plus integrity checking (an MD5 hash of the entity

is also computed and checked); <em>none</em> will cause the module

to use the old RFC-2069 digest algorithm (which does not include

integrity checking). Both <em>auth</em> and <em>auth-int</em> may

be specified, in which the case the browser will choose which of

these to use. <em>none</em> should only be used if the browser for

some reason does not like the challenge it receives otherwise.</p>

<p><strong><em>auth-int</em> is not implemented

yet</strong>.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestNonceLifetime</name>

<description>How long the server nonce is valid</description>

<syntax>AuthDigestNonceLifetime <em>seconds</em></syntax>

<default>AuthDigestNonceLifetime 300</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>The <directive>AuthDigestNonceLifetime</directive> 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 <code>stale=true</code>. If <em>seconds</em> 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 <em>seconds</em> is less than 0 then the nonce never

expires. <!-- Not implemented yet If <EM>seconds</EM> is 0 then

</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestNonceFormat</name>

<description>Determines how the nonce is generated</description>

<syntax>???</syntax>

<default>???</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p><strong>Not implemented yet.</strong> <!--

</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestNcCheck</name>

<description>Enables or disables checking of the nonce-count sent by the

server</description>

<syntax>AuthDigestNcCheck On|Off</syntax>

<default>AuthDigestNcCheck Off</default>

<contextlist><context>server config</context></contextlist>

<usage>

<p><strong>Not implemented yet.</strong> <!--

</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestAlgorithm</name>

<description>Selects the algorithm used to calculate the challenge and

response hases in digest authentication</description>

<syntax>AuthDigestAlgorithm MD5|MD5-sess</syntax>

<default>AuthDigestAlgorithm MD5</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>The <directive>AuthDigestAlgorithm</directive> directive

selects the algorithm used to calculate the challenge and response

hashes.</p>

<p><strong><em>MD5-sess</em> is not correctly implemented

yet</strong>. <!--

</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestDomain</name>

<description>URIs that are in the same protection space for digest

authentication</description>

<syntax>AuthDigestDomain <em>URI</em> [<em>URI</em>] ...</syntax>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>AuthConfig</override>

<usage>

<p>The <directive>AuthDigestDomain</directive> 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. inluding a scheme, host, port, etc) or relative URIs.</p>

<p>This directive <em>should</em> 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 <em>every request</em> 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.</p>

<p>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. </p>

</usage>

</directivesynopsis>

</modulesynopsis>