httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From n.@apache.org
Subject cvs commit: httpd-2.0/docs/manual/mod mod_auth_digest.xml
Date Thu, 12 Dec 2002 06:59:34 GMT
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>
         &lt;Location /private/&gt;<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>
   
  
  
  

Mime
View raw message