<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<modulesynopsis>
+<!-- $LastChangedRevision$ -->
+
+<!--
+ Copyright 2002-2006 The Apache Software Foundation or its licensors, as
+ applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<modulesynopsis metafile="mod_auth_digest.xml.meta">
<name>mod_auth_digest</name>
<description>User authentication using MD5
<identifier>auth_digest_module</identifier>
<summary>
- <p>This module implements HTTP Digest Authentication. However, it
+ <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>
+<seealso><a href="../howto/auth.html">Authentication howto</a></seealso>
<section id="using"><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>
+ 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
+ <program>htdigest</program> tool.</p>
+
+ <example><title>Example:</title>
<Location /private/><br />
<indent>
AuthType Digest<br />
AuthName "private area"<br />
AuthDigestDomain /private/ http://mirror.my.dom/private2/<br />
- AuthDigestFile /web/auth/.digest_pw<br />
+ <br />
+ AuthDigestProvider file<br />
+ AuthUserFile /web/auth/.digest_pw<br />
Require valid-user<br />
</indent>
</Location>
</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 July 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> and <a
- href="http://www.mozilla.org">Mozilla</a>. Since digest
- authentication is not as widely implemented as basic
- authentication, you should use it only in controlled settings.</p>
+ <p>Digest authentication is more secure than Basic authentication,
+ but only works with supporting browsers. As of September 2004, major
+ browsers that support digest authentication include <a
+ href="http://www.w3.org/Amaya/">Amaya</a>, <a
+ href="http://konqueror.kde.org/">Konqueror</a>, <a
+ href="http://www.microsoft.com/windows/ie/">MS Internet Explorer</a>
+ for Mac OS X and Windows (although the Windows version fails when
+ used with a query string -- see "<a href="#msie" >Working with MS
+ Internet Explorer</a>" below for a workaround), <a
+ href="http://www.mozilla.org">Mozilla</a>, <a
+ href="http://channels.netscape.com/ns/browsers/download.jsp">
+ Netscape</a> 7, <a href="http://www.opera.com/">Opera</a>, and <a
+ href="http://www.apple.com/safari/">Safari</a>. <a
+ href="http://lynx.isc.org/">lynx</a> does <strong>not</strong>
+ support digest authentication. Since digest authentication is not as
+ widely implemented as basic authentication, you should use it only
+ in environments where all users will have supporting browsers.</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 <var>file-path</var></syntax>
-<contextlist><context>directory</context><context>.htaccess</context>
-</contextlist>
-<override>AuthConfig</override>
+<section id="msie"><title>Working with MS Internet Explorer</title>
+ <p>The Digest authentication implementation in current Internet
+ Explorer for Windows implementations has known issues, namely that
+ <code>GET</code> requests with a query string are not RFC compliant.
+ There are a few ways to work around this issue.</p>
+
+ <p>
+ The first way is to use <code>POST</code> requests instead of
+ <code>GET</code> requests to pass data to your program. This method
+ is the simplest approach if your application can work with this
+ limitation.
+ </p>
+
+ <p>Since version 2.0.51 Apache also provides a workaround in the
+ <code>AuthDigestEnableQueryStringHack</code> environment variable.
+ If <code>AuthDigestEnableQueryStringHack</code> is set for the
+ request, Apache will take steps to work around the MSIE bug and
+ remove the request URI from the digest comparison. Using this
+ method would look similar to the following.</p>
+
+ <example><title>Using Digest Authentication with MSIE:</title>
+ BrowserMatch "MSIE" AuthDigestEnableQueryStringHack=On
+ </example>
+
+ <p>See the <directive module="mod_setenvif">BrowserMatch</directive>
+ directive for more details on conditionally setting environment
+ variables</p>
+</section>
-<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. <var>File-path</var> 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 <var>file-path</var></syntax>
+<name>AuthDigestProvider</name>
+<description>Sets the authentication provider(s) for this location</description>
+<syntax>AuthDigestProvider <var>provider-name</var>
+[<var>provider-name</var>] ...</syntax>
+<default>AuthDigestProvider file</default>
<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). <var>File-path</var> 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>
+ <p>The <directive>AuthDigestProvider</directive> directive sets
+ which provider is used to authenticate the users for this location.
+ The default <code>file</code> provider is implemented
+ by the <module>mod_authn_file</module> module. Make sure
+ that the chosen provider module is present in the server.</p>
+
+ <p>See <module>mod_authn_dbm</module>, <module>mod_authn_file</module>,
+ and <module>mod_authn_dbd</module> for providers.</p>
</usage>
</directivesynopsis>
<usage>
<p>The <directive>AuthDigestQop</directive> directive determines
- the quality-of-protection to use. <code>auth</code> will only do
- authentication (username/password); <code>auth-int</code> is
+ 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
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
+ expires. <!-- Not implemented yet: If <var>seconds</var> is 0 then
the nonce may be used exactly once by the client. Note that while
one-time-nonces provide higher security against replay attacks,
they also have significant performance implications, as the
<override>AuthConfig</override>
<usage>
- <p><strong>Not implemented yet.</strong> <!--
- <P>The AuthDigestNonceFormat directive determines how the nonce is
- generated.
- -->
- </p>
+ <note>Not implemented yet.</note>
+ <!-- The AuthDigestNonceFormat directive determines how the nonce is
+ generated. -->
</usage>
</directivesynopsis>
Not implemented yet.
</note>
<!--
- <P>The AuthDigestNcCheck directive enables or disables the checking of the
- nonce-count sent by the server.
-
- <P>While recommended from a security standpoint, turning this directive
- On has one important performance implication. To check the nonce-count
- *all* requests (which have an Authorization header, irrespective of
- whether they require digest authentication) must be serialized through
- a critical section. If the server is handling a large number of
- requests which contain the Authorization header then this may noticeably
- impact performance.
+ <p>The AuthDigestNcCheck directive enables or disables the checking of the
+ nonce-count sent by the server.</p>
+
+ <p>While recommended from a security standpoint, turning this directive
+ On has one important performance implication. To check the nonce-count
+ *all* requests (which have an Authorization header, irrespective of
+ whether they require digest authentication) must be serialized through
+ a critical section. If the server is handling a large number of
+ requests which contain the Authorization header then this may noticeably
+ impact performance.</p>
-->
</usage>
</directivesynopsis>
<directivesynopsis>
<name>AuthDigestAlgorithm</name>
<description>Selects the algorithm used to calculate the challenge and
-response hases in digest authentication</description>
+response hashes in digest authentication</description>
<syntax>AuthDigestAlgorithm MD5|MD5-sess</syntax>
<default>AuthDigestAlgorithm MD5</default>
<contextlist><context>directory</context><context>.htaccess</context>
<code>MD5-sess</code> is not correctly implemented yet.
</note>
<!--
- <P>To use <EM>MD5-sess</EM> you must first code up the
- <VAR>get_userpw_hash()</VAR> function in <VAR>mod_auth_digest.c</VAR> .
+ <p>To use <code>MD5-sess</code> you must first code up the
+ <code>get_userpw_hash()</code> function in
+ <code>mod_auth_digest.c</code>.</p>
-->
</usage>
</directivesynopsis>
<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>
+ 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
- "AuthDigestNcCheck" is on.</p>
+ 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
</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>
projects / apache / blobdiff