<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

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

<modulesynopsis metafile="mod_auth_digest.xml.meta">

<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 id="using"><title>Using Digest Authentication</title>

<p>Using MD5 Digest authentication is very simple. Simply set

up authentication normally, using <code>AuthType Digest</code> and

<directive module="mod_auth_digest">AuthDigestProvider</directive>

instead of the normal <code>AuthType Basic</code> and

<directive module="mod_auth_basic">AuthBasicProvider</directive>.

Then add a <directive module="mod_auth_digest"

>AuthDigestDomain</directive> directive containing at least the root

URI(s) for this protection space.</p>

<p>Appropriate user (text) files can be created using the

<a href="/programs/htdigest.html">htdigest</a> tool.</p>

<example><title>Example:</title>

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

<indent>

AuthType Digest<br />

AuthName "private area"<br />

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

<br />

AuthDigestProvider file<br />

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

Require valid-user<br />

</indent>

&lt;/Location&gt;

</example>

<note><title>Note</title>

<p>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 <a href="http://www.opera.com/">Opera</a>, <a

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

Explorer</a> (fails when used with a query string), <a

href="http://www.w3.org/Amaya/">Amaya</a>, <a

href="http://www.mozilla.org">Mozilla</a> and <a

href="http://channels.netscape.com/ns/browsers/download.jsp"

>Netscape</a> since version 7. Since digest

authentication is not as widely implemented as basic

authentication, you should use it only in controlled environments.</p>

</note>

</section>

<directivesynopsis>

<name>AuthDigestProvider</name>

<description>Sets the authentication provider(s) for this location</description>

<syntax>AuthDigestProvider On|Off|<var>provider-name</var>

[<var>provider-name</var>] ...</syntax>

<default>AuthDigestProvider On</default>

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

</contextlist>

<override>AuthConfig</override>

<usage>

<p>The <directive>AuthDigestProvider</directive> directive sets

which provider is used to authenticate the users for this location.

Setting the value to <code>On</code> will choose the default provider

(<code>file</code>). Since the <code>file</code> provider is implemented

by the <module>mod_authn_file</module> module, you have to make sure,

that the module is present in the server.</p>

<p>See <module>mod_authn_dbm</module> and <module>mod_authn_file</module>

for providers.</p>

<p>The value <code>Off</code> clears the provider list and sets it back

to the default.</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 <dfn>quality-of-protection</dfn> to use. <code>auth</code> will

only do authentication (username/password); <code>auth-int</code> is

authentication plus integrity checking (an MD5 hash of the entity

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

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

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

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

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

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

<note>

<code>auth-int</code> is not implemented yet.

</note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestNonceLifetime</name>

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

<syntax>AuthDigestNonceLifetime <var>seconds</var></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 <var>seconds</var> 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 <var>seconds</var> is less than 0 then the nonce never

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

</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestNonceFormat</name>

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

<syntax>AuthDigestNonceFormat <var>format</var></syntax>

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

</contextlist>

<override>AuthConfig</override>

<usage>

<note>Not implemented yet.</note>

<!-- The AuthDigestNonceFormat directive determines how the nonce is

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

<note>

Not implemented yet.

</note>

<!--

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestAlgorithm</name>

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

response hashes 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>

<note>

<code>MD5-sess</code> is not correctly implemented yet.

</note>

<!--

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDigestDomain</name>

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

authentication</description>

<syntax>AuthDigestDomain <var>URI</var> [<var>URI</var>] ...</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 (<em>i.e.</em> 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 (<em>i.e.</em>

including 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 <directive

module="mod_auth_digest">AuthDigestNcCheck</directive> 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>

<directivesynopsis>

<name>AuthDigestShmemSize</name>

<description>The amount of shared memory to allocate for keeping track

of clients</description>

<syntax>AuthDigestShmemSize <var>size</var></syntax>

<default>AuthDigestShmemSize 1000</default>

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

<usage>

<p>The <directive>AuthDigestShmemSize</directive> 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 <em>one</em> client. This value is dependant on your

system. If you want to find out the exact value, you may simply

set <directive>AuthDigestShmemSize</directive> to the value of

<code>0</code> and read the error message after trying to start the

server.</p>

<p>The <var>size</var> is normally expressed in Bytes, but you

may let the number follow a <code>K</code> or an <code>M</code> to

express your value as KBytes or MBytes. For example, the following

directives are all equivalent:</p>

<example>

AuthDigestShmemSize 1048576<br />

AuthDigestShmemSize 1024K<br />

AuthDigestShmemSize 1M

</example>

</usage>

</directivesynopsis>

</modulesynopsis>