You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by nd...@apache.org on 2002/12/12 07:59:34 UTC
cvs commit: httpd-2.0/docs/manual/mod mod_auth_digest.xml
nd 2002/12/11 22:59:34
Modified: docs/manual/mod Tag: APACHE_2_0_BRANCH mod_auth_digest.xml
Log:
- markup and reformatting
- add AuthDigestShmemSize description
Revision Changes Path
No revision
No revision
1.5.2.3 +78 -40 httpd-2.0/docs/manual/mod/mod_auth_digest.xml
Index: mod_auth_digest.xml
===================================================================
RCS file: /home/cvs/httpd-2.0/docs/manual/mod/mod_auth_digest.xml,v
retrieving revision 1.5.2.2
retrieving revision 1.5.2.3
diff -u -r1.5.2.2 -r1.5.2.3
--- mod_auth_digest.xml 6 Dec 2002 10:20:50 -0000 1.5.2.2
+++ mod_auth_digest.xml 12 Dec 2002 06:59:33 -0000 1.5.2.3
@@ -11,7 +11,7 @@
<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>
@@ -24,14 +24,19 @@
<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>
+ up authentication normally, using <code>AuthType Digest</code> and
+ <directive module="mod_auth_digest">AuthDigestFile</directive> instead
+ of the normal <code>AuthType Basic</code> and <directive
+ module="mod_auth">AuthUserFile</directive>; also, replace any <directive
+ module="mod_auth">AuthGroupFile</directive> with <directive
+ module="mod_auth_digest">AuthDigestGroupFile</directive>. Then add a
+ <directive module="mod_auth_digest">AuthDigestDomain</directive> directive
+ containing at least the root URI(s) for this protection space.</p>
- <example>
+ <p>Appropriate user (text) files can be created using the
+ <a href="../programs/htdigest.html">htdigest</a> tool.</p>
+
+ <example><title>Example:</title>
<Location /private/><br />
<indent>
AuthType Digest<br />
@@ -46,7 +51,7 @@
<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
+ 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
@@ -55,7 +60,7 @@
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 settings.</p>
+ in controlled environments.</p>
</note>
</section>
@@ -77,7 +82,7 @@
<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>
+ the <code>support/</code> subdirectory of the Apache distribution.</p>
</usage>
</directivesynopsis>
@@ -105,10 +110,12 @@
<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>
+ <note type="warning"><title>Security:</title>
+ <p>Make sure that the <directive>AuthGroupFile</directive> is stored
+ outside the document tree of the web-server; do <em>not</em> put it in
+ the directory that it protects. Otherwise, clients may be able
+ to download the <directive>AuthGroupFile</directive>.</p>
+ </note>
</usage>
</directivesynopsis>
@@ -157,7 +164,7 @@
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
@@ -183,11 +190,9 @@
<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>
@@ -204,16 +209,16 @@
Not implemented yet.
</note>
<!--
- <P>The AuthDigestNcCheck directive enables or disables the checking of the
- nonce-count sent by the server.
+ <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>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>
@@ -237,8 +242,9 @@
<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>
@@ -255,24 +261,56 @@
<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, <em>i.e.</em> 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>
+ 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>
+ 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>
+ 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 neccessary 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>