home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F278240_mod_auth_digest.xml < prev    next >
Extensible Markup Language  |  2004-08-05  |  15KB  |  367 lines
  1. <?xml version="1.0"?>
  2. <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  3. <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
  4. <!-- $Revision: 1.5.2.11 $ -->
  5.  
  6. <!--
  7.  Copyright 2002-2004 The Apache Software Foundation
  8.  
  9.  Licensed under the Apache License, Version 2.0 (the "License");
  10.  you may not use this file except in compliance with the License.
  11.  You may obtain a copy of the License at
  12.  
  13.      http://www.apache.org/licenses/LICENSE-2.0
  14.  
  15.  Unless required by applicable law or agreed to in writing, software
  16.  distributed under the License is distributed on an "AS IS" BASIS,
  17.  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18.  See the License for the specific language governing permissions and
  19.  limitations under the License.
  20. -->
  21.  
  22. <modulesynopsis metafile="mod_auth_digest.xml.meta">
  23.  
  24. <name>mod_auth_digest</name>
  25. <description>User authentication using MD5
  26.     Digest Authentication.</description>
  27. <status>Experimental</status>
  28. <sourcefile>mod_auth_digest.c</sourcefile>
  29. <identifier>auth_digest_module</identifier>
  30.  
  31. <summary>
  32.     <p>This module implements HTTP Digest Authentication. However, it
  33.     has not been extensively tested and is therefore marked
  34.     experimental.</p>
  35. </summary>
  36.  
  37. <seealso><directive module="core">AuthName</directive></seealso>
  38. <seealso><directive module="core">AuthType</directive></seealso>
  39. <seealso><directive module="core">Require</directive></seealso>
  40. <seealso><directive module="core">Satisfy</directive></seealso>
  41.  
  42. <section id="using"><title>Using Digest Authentication</title>
  43.  
  44.     <p>Using MD5 Digest authentication is very simple. Simply set
  45.     up authentication normally, using <code>AuthType Digest</code> and
  46.     <directive module="mod_auth_digest">AuthDigestFile</directive> instead
  47.     of the normal <code>AuthType Basic</code> and <directive
  48.     module="mod_auth">AuthUserFile</directive>; also, replace any <directive
  49.     module="mod_auth">AuthGroupFile</directive> with <directive
  50.     module="mod_auth_digest">AuthDigestGroupFile</directive>. Then add a
  51.     <directive module="mod_auth_digest">AuthDigestDomain</directive> directive
  52.     containing at least the root URI(s) for this protection space.</p>
  53.  
  54.     <p>Appropriate user (text) files can be created using the
  55.     <a href="../programs/htdigest.html">htdigest</a> tool.</p>
  56.  
  57.     <example><title>Example:</title>
  58.       <Location /private/><br />
  59.       <indent>
  60.         AuthType Digest<br />
  61.         AuthName "private area"<br />
  62.         AuthDigestDomain /private/ http://mirror.my.dom/private2/<br />
  63.         AuthDigestFile /web/auth/.digest_pw<br />
  64.         Require valid-user<br />
  65.       </indent>
  66.       </Location>
  67.     </example>
  68.  
  69.     <note><title>Note</title> 
  70.     <p>Digest authentication provides a more secure password system
  71.     than Basic authentication, but only works with supporting
  72.     browsers. As of November 2002, the major browsers that support digest
  73.     authentication are <a href="http://www.opera.com/">Opera</a>, <a
  74.     href="http://www.microsoft.com/windows/ie/">MS Internet
  75.     Explorer</a> (fails when used with a query string - see "<a href="#msie"
  76.     >Working with MS Internet Explorer</a>" below for a workaround), <a
  77.     href="http://www.w3.org/Amaya/">Amaya</a>, <a
  78.     href="http://www.mozilla.org">Mozilla</a> and <a
  79.     href="http://channels.netscape.com/ns/browsers/download.jsp"
  80.     >Netscape</a> since version 7. Since digest authentication is not
  81.     as widely implemented as basic authentication, you should use it only
  82.     in controlled environments.</p>
  83.     </note>
  84. </section>
  85.  
  86. <section id="msie"><title>Working with MS Internet Explorer</title>
  87.     <p>The Digest authentication implementation in current Internet
  88.     Explorer implementations has known issues, namely that <code>GET</code>
  89.     requests with a query string are not RFC compliant.  There are a
  90.     few ways to work around this issue.</p>
  91.  
  92.     <p>
  93.     The first way is to use <code>POST</code> requests instead of
  94.     <code>GET</code> requests to pass data to your program.  This method
  95.     is the simplest approach if your application can work with this
  96.     limitation.
  97.     </p>
  98.  
  99.     <p>Since version 2.0.51 Apache also provides a workaround in the
  100.     <code>AuthDigestEnableQueryStringHack</code> environment variable.
  101.     If <code>AuthDigestEnableQueryStringHack</code> is set for the
  102.     request, Apache will take steps to work around the MSIE bug and
  103.     remove the request URI from the digest comparison.  Using this
  104.     method would look similar to the following.</p>
  105.  
  106.     <example><title>Using Digest Authentication with MSIE:</title>
  107.     BrowserMatch "MSIE" AuthDigestEnableQueryStringHack=On
  108.     </example>
  109.  
  110.     <p>See the <directive module="mod_setenvif">BrowserMatch</directive>
  111.     directive for more details on conditionally setting environment
  112.     variables</p>
  113. </section>
  114.  
  115.  
  116. <directivesynopsis>
  117. <name>AuthDigestFile</name>
  118. <description>Location of the text file containing the list
  119. of users and encoded passwords for digest authentication</description>
  120. <syntax>AuthDigestFile <var>file-path</var></syntax>
  121. <contextlist><context>directory</context><context>.htaccess</context>
  122. </contextlist>
  123. <override>AuthConfig</override>
  124.  
  125. <usage>
  126.     <p>The <directive>AuthDigestFile</directive> directive sets the
  127.     name of a textual file containing the list of users and encoded
  128.     passwords for digest authentication. <var>File-path</var> is the
  129.     absolute path to the user file.</p>
  130.  
  131.     <p>The digest file uses a special format. Files in this format
  132.     can be created using the <a
  133.     href="../programs/htdigest.html">htdigest</a> utility found in
  134.     the <code>support/</code> subdirectory of the Apache distribution.</p>
  135. </usage>
  136. </directivesynopsis>
  137.  
  138. <directivesynopsis>
  139. <name>AuthDigestGroupFile</name>
  140. <description>Name of the text file containing the list of groups
  141. for digest authentication</description>
  142. <syntax>AuthDigestGroupFile <var>file-path</var></syntax>
  143. <contextlist><context>directory</context><context>.htaccess</context>
  144. </contextlist>
  145. <override>AuthConfig</override>
  146.  
  147. <usage>
  148.     <p>The <directive>AuthDigestGroupFile</directive> directive sets
  149.     the name of a textual file containing the list of groups and their
  150.     members (user names). <var>File-path</var> is the absolute path to
  151.     the group file.</p>
  152.  
  153.     <p>Each line of the group file contains a groupname followed by
  154.     a colon, followed by the member usernames separated by spaces.
  155.     Example:</p>
  156.  
  157.     <example>mygroup: bob joe anne</example>
  158.  
  159.     <p>Note that searching large text files is <em>very</em>
  160.     inefficient.</p>
  161.  
  162.     <note type="warning"><title>Security:</title>
  163.     <p>Make sure that the <directive>AuthGroupFile</directive> is stored
  164.     outside the document tree of the web-server; do <em>not</em> put it in
  165.     the directory that it protects. Otherwise, clients may be able
  166.     to download the <directive>AuthGroupFile</directive>.</p>
  167.     </note>
  168. </usage>
  169. </directivesynopsis>
  170.  
  171. <directivesynopsis>
  172. <name>AuthDigestQop</name>
  173. <description>Determines the quality-of-protection to use in digest
  174. authentication</description>
  175. <syntax>AuthDigestQop none|auth|auth-int [auth|auth-int]</syntax>
  176. <default>AuthDigestQop auth</default>
  177. <contextlist><context>directory</context><context>.htaccess</context>
  178. </contextlist>
  179. <override>AuthConfig</override>
  180.  
  181. <usage>
  182.     <p>The <directive>AuthDigestQop</directive> directive determines
  183.     the <dfn>quality-of-protection</dfn> to use. <code>auth</code> will only do
  184.     authentication (username/password); <code>auth-int</code> is
  185.     authentication plus integrity checking (an MD5 hash of the entity
  186.     is also computed and checked); <code>none</code> will cause the module
  187.     to use the old RFC-2069 digest algorithm (which does not include
  188.     integrity checking). Both <code>auth</code> and <code>auth-int</code> may
  189.     be specified, in which the case the browser will choose which of
  190.     these to use. <code>none</code> should only be used if the browser for
  191.     some reason does not like the challenge it receives otherwise.</p>
  192.  
  193.     <note>
  194.       <code>auth-int</code> is not implemented yet.
  195.     </note>
  196. </usage>
  197. </directivesynopsis>
  198.  
  199. <directivesynopsis>
  200. <name>AuthDigestNonceLifetime</name>
  201. <description>How long the server nonce is valid</description>
  202. <syntax>AuthDigestNonceLifetime <var>seconds</var></syntax>
  203. <default>AuthDigestNonceLifetime 300</default>
  204. <contextlist><context>directory</context><context>.htaccess</context>
  205. </contextlist>
  206. <override>AuthConfig</override>
  207.  
  208. <usage>
  209.     <p>The <directive>AuthDigestNonceLifetime</directive> directive
  210.     controls how long the server nonce is valid. When the client
  211.     contacts the server using an expired nonce the server will send
  212.     back a 401 with <code>stale=true</code>. If <var>seconds</var> is
  213.     greater than 0 then it specifies the amount of time for which the
  214.     nonce is valid; this should probably never be set to less than 10
  215.     seconds. If <var>seconds</var> is less than 0 then the nonce never
  216.     expires. <!-- Not implemented yet: If <var>seconds</var> is 0 then
  217.     the nonce may be used exactly once by the client. Note that while
  218.     one-time-nonces provide higher security against replay attacks,
  219.     they also have significant performance implications, as the
  220.     browser cannot pipeline or multiple connections for the
  221.     requests. Because browsers cannot easily detect that
  222.     one-time-nonces are being used, this may lead to browsers trying
  223.     to pipeline requests and receiving 401 responses for all but the
  224.     first request, requiring the browser to resend the requests. Note
  225.     also that the protection against reply attacks only makes sense
  226.     for dynamically generated content and things like POST requests;
  227.     for static content the attacker may already have the complete
  228.     response, so one-time-nonces do not make sense here.  -->
  229.     </p>
  230. </usage>
  231. </directivesynopsis>
  232.  
  233. <directivesynopsis>
  234. <name>AuthDigestNonceFormat</name>
  235. <description>Determines how the nonce is generated</description>
  236. <syntax>AuthDigestNonceFormat <var>format</var></syntax>
  237. <contextlist><context>directory</context><context>.htaccess</context>
  238. </contextlist>
  239. <override>AuthConfig</override>
  240.  
  241. <usage>
  242.     <note>Not implemented yet.</note>
  243.     <!-- The AuthDigestNonceFormat directive determines how the nonce is
  244.     generated. -->
  245. </usage>
  246. </directivesynopsis>
  247.  
  248. <directivesynopsis>
  249. <name>AuthDigestNcCheck</name>
  250. <description>Enables or disables checking of the nonce-count sent by the
  251. server</description>
  252. <syntax>AuthDigestNcCheck On|Off</syntax>
  253. <default>AuthDigestNcCheck Off</default>
  254. <contextlist><context>server config</context></contextlist>
  255.  
  256. <usage>
  257.     <note>
  258.       Not implemented yet.
  259.     </note>
  260.     <!--
  261.     <p>The AuthDigestNcCheck directive enables or disables the checking of the
  262.     nonce-count sent by the server.</p>
  263.  
  264.     <p>While recommended from a security standpoint, turning this directive
  265.     On has one important performance implication. To check the nonce-count
  266.     *all* requests (which have an Authorization header, irrespective of
  267.     whether they require digest authentication) must be serialized through
  268.     a critical section. If the server is handling a large number of
  269.     requests which contain the Authorization header then this may noticeably
  270.     impact performance.</p>
  271.      -->
  272. </usage>
  273. </directivesynopsis>
  274.  
  275. <directivesynopsis>
  276. <name>AuthDigestAlgorithm</name>
  277. <description>Selects the algorithm used to calculate the challenge and
  278. response hases in digest authentication</description>
  279. <syntax>AuthDigestAlgorithm MD5|MD5-sess</syntax>
  280. <default>AuthDigestAlgorithm MD5</default>
  281. <contextlist><context>directory</context><context>.htaccess</context>
  282. </contextlist>
  283. <override>AuthConfig</override>
  284.  
  285. <usage>
  286.     <p>The <directive>AuthDigestAlgorithm</directive> directive
  287.     selects the algorithm used to calculate the challenge and response
  288.     hashes.</p>
  289.  
  290.     <note>
  291.       <code>MD5-sess</code> is not correctly implemented yet.
  292.     </note>
  293.     <!--
  294.     <p>To use <code>MD5-sess</code> you must first code up the
  295.     <code>get_userpw_hash()</code> function in
  296.     <code>mod_auth_digest.c</code>.</p>
  297.     -->
  298. </usage>
  299. </directivesynopsis>
  300.  
  301. <directivesynopsis>
  302. <name>AuthDigestDomain</name>
  303. <description>URIs that are in the same protection space for digest
  304. authentication</description>
  305. <syntax>AuthDigestDomain <var>URI</var> [<var>URI</var>] ...</syntax>
  306. <contextlist><context>directory</context><context>.htaccess</context>
  307. </contextlist>
  308. <override>AuthConfig</override>
  309.  
  310. <usage>
  311.     <p>The <directive>AuthDigestDomain</directive> directive allows
  312.     you to specify one or more URIs which are in the same protection
  313.     space (<em>i.e.</em> use the same realm and username/password info).
  314.     The specified URIs are prefixes, <em>i.e.</em> the client will assume
  315.     that all URIs "below" these are also protected by the same
  316.     username/password. The URIs may be either absolute URIs (<em>i.e.</em>
  317.     inluding a scheme, host, port, etc) or relative URIs.</p>
  318.  
  319.     <p>This directive <em>should</em> always be specified and
  320.     contain at least the (set of) root URI(s) for this space.
  321.     Omitting to do so will cause the client to send the
  322.     Authorization header for <em>every request</em> sent to this
  323.     server. Apart from increasing the size of the request, it may
  324.     also have a detrimental effect on performance if <directive
  325.     module="mod_auth_digest">AuthDigestNcCheck</directive> is on.</p>
  326.  
  327.     <p>The URIs specified can also point to different servers, in
  328.     which case clients (which understand this) will then share
  329.     username/password info across multiple servers without
  330.     prompting the user each time.</p>
  331. </usage>
  332. </directivesynopsis>
  333.  
  334. <directivesynopsis>
  335. <name>AuthDigestShmemSize</name>
  336. <description>The amount of shared memory to allocate for keeping track
  337. of clients</description>
  338. <syntax>AuthDigestShmemSize <var>size</var></syntax>
  339. <default>AuthDigestShmemSize 1000</default>
  340. <contextlist><context>server config</context></contextlist>
  341.  
  342. <usage>
  343.     <p>The <directive>AuthDigestShmemSize</directive> directive defines
  344.     the amount of shared memory, that will be allocated at the server
  345.     startup for keeping track of clients. Note that the shared memory
  346.     segment cannot be set less than the space that is neccessary for
  347.     tracking at least <em>one</em> client. This value is dependant on your
  348.     system. If you want to find out the exact value, you may simply
  349.     set <directive>AuthDigestShmemSize</directive> to the value of
  350.     <code>0</code> and read the error message after trying to start the
  351.     server.</p>
  352.  
  353.     <p>The <var>size</var> is normally expressed in Bytes, but you
  354.     may let the number follow a <code>K</code> or an <code>M</code> to
  355.     express your value as KBytes or MBytes. For example, the following
  356.     directives are all equivalent:</p>
  357.  
  358.     <example>
  359.       AuthDigestShmemSize 1048576<br />
  360.       AuthDigestShmemSize 1024K<br />
  361.       AuthDigestShmemSize 1M
  362.     </example>
  363. </usage>
  364. </directivesynopsis>
  365.  
  366. </modulesynopsis>
  367.