granicus.if.org Git - apache/blob - docs/manual/mod/mod_auth_digest.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <modulesynopsis>
   5
   6 <name>mod_auth_digest</name>
   7 <description>User authentication using MD5
   8     Digest Authentication.</description>
   9 <status>Experimental</status>
  10 <sourcefile>mod_auth_digest.c</sourcefile>
  11 <identifier>auth_digest_module</identifier>
  12
  13 <summary>
  14     <p>This module implements HTTP Digest Authentication.  However, it
  15     has not been extensively tested and is therefore marked
  16     experimental.</p>
  17 </summary>
  18
  19 <seealso><directive module="core">AuthName</directive></seealso>
  20 <seealso><directive module="core">AuthType</directive></seealso>
  21 <seealso><directive module="core">Require</directive></seealso>
  22 <seealso><directive module="core">Satisfy</directive></seealso>
  23
  24 <section id="using"><title>Using Digest Authentication</title>
  25
  26     <p>Using MD5 Digest authentication is very simple. Simply set
  27     up authentication normally, using "AuthType Digest" and
  28     "AuthDigestFile" instead of the normal "AuthType Basic" and
  29     "AuthUserFile"; also, replace any "AuthGroupFile" with
  30     "AuthDigestGroupFile". Then add a "AuthDigestDomain" directive
  31     containing at least the root URI(s) for this protection space.
  32     Example:</p>
  33
  34     <example>
  35       &lt;Location /private/&gt;<br />
  36       <indent>
  37         AuthType Digest<br />
  38         AuthName "private area"<br />
  39         AuthDigestDomain /private/ http://mirror.my.dom/private2/<br />
  40         AuthDigestFile /web/auth/.digest_pw<br />
  41         Require valid-user<br />
  42       </indent>
  43       &lt;/Location&gt;
  44     </example>
  45
  46     <note><title>Note</title>
  47     <p>Digest authentication provides a more secure password system
  48     than Basic authentication, but only works with supporting
  49     browsers. As of July 2002, the major browsers that support digest
  50     authentication are <a href="http://www.opera.com/">Opera</a>, <a
  51     href="http://www.microsoft.com/windows/ie/">MS Internet
  52     Explorer</a> (fails when used with a query string), <a
  53     href="http://www.w3.org/Amaya/">Amaya</a> and <a
  54     href="http://www.mozilla.org">Mozilla</a>.  Since digest
  55     authentication is not as widely implemented as basic
  56     authentication, you should use it only in controlled settings.</p>
  57     </note>
  58 </section>
  59
  60 <directivesynopsis>
  61 <name>AuthDigestFile</name>
  62 <description>Location of the text file containing the list
  63 of users and encoded passwords for digest authentication</description>
  64 <syntax>AuthDigestFile <var>file-path</var></syntax>
  65 <contextlist><context>directory</context><context>.htaccess</context>
  66 </contextlist>
  67 <override>AuthConfig</override>
  68
  69 <usage>
  70     <p>The <directive>AuthDigestFile</directive> directive sets the
  71     name of a textual file containing the list of users and encoded
  72     passwords for digest authentication. <var>File-path</var> is the
  73     absolute path to the user file.</p>
  74
  75     <p>The digest file uses a special format. Files in this format
  76     can be created using the <a
  77     href="../programs/htdigest.html">htdigest</a> utility found in
  78     the support/ subdirectory of the Apache distribution.</p>
  79 </usage>
  80 </directivesynopsis>
  81
  82 <directivesynopsis>
  83 <name>AuthDigestGroupFile</name>
  84 <description>Name of the text file containing the list of groups
  85 for digest authentication</description>
  86 <syntax>AuthDigestGroupFile <var>file-path</var></syntax>
  87 <contextlist><context>directory</context><context>.htaccess</context>
  88 </contextlist>
  89 <override>AuthConfig</override>
  90
  91 <usage>
  92     <p>The <directive>AuthDigestGroupFile</directive> directive sets
  93     the name of a textual file containing the list of groups and their
  94     members (user names). <var>File-path</var> is the absolute path to
  95     the group file.</p>
  96
  97     <p>Each line of the group file contains a groupname followed by
  98     a colon, followed by the member usernames separated by spaces.
  99     Example:</p>
 100
 101     <example>mygroup: bob joe anne</example>
 102
 103     <p>Note that searching large text files is <em>very</em>
 104     inefficient.</p>
 105
 106     <p>Security: make sure that the AuthGroupFile is stored outside
 107     the document tree of the web-server; do <em>not</em> put it in
 108     the directory that it protects. Otherwise, clients will be able
 109     to download the AuthGroupFile.</p>
 110 </usage>
 111 </directivesynopsis>
 112
 113 <directivesynopsis>
 114 <name>AuthDigestQop</name>
 115 <description>Determines the quality-of-protection to use in digest
 116 authentication</description>
 117 <syntax>AuthDigestQop none|auth|auth-int [auth|auth-int]</syntax>
 118 <default>AuthDigestQop auth</default>
 119 <contextlist><context>directory</context><context>.htaccess</context>
 120 </contextlist>
 121 <override>AuthConfig</override>
 122
 123 <usage>
 124     <p>The <directive>AuthDigestQop</directive> directive determines
 125     the quality-of-protection to use. <code>auth</code> will only do
 126     authentication (username/password); <code>auth-int</code> is
 127     authentication plus integrity checking (an MD5 hash of the entity
 128     is also computed and checked); <code>none</code> will cause the module
 129     to use the old RFC-2069 digest algorithm (which does not include
 130     integrity checking). Both <code>auth</code> and <code>auth-int</code> may
 131     be specified, in which the case the browser will choose which of
 132     these to use. <code>none</code> should only be used if the browser for
 133     some reason does not like the challenge it receives otherwise.</p>
 134
 135     <note>
 136       <code>auth-int</code> is not implemented yet.
 137     </note>
 138 </usage>
 139 </directivesynopsis>
 140
 141 <directivesynopsis>
 142 <name>AuthDigestNonceLifetime</name>
 143 <description>How long the server nonce is valid</description>
 144 <syntax>AuthDigestNonceLifetime <var>seconds</var></syntax>
 145 <default>AuthDigestNonceLifetime 300</default>
 146 <contextlist><context>directory</context><context>.htaccess</context>
 147 </contextlist>
 148 <override>AuthConfig</override>
 149
 150 <usage>
 151     <p>The <directive>AuthDigestNonceLifetime</directive> directive
 152     controls how long the server nonce is valid. When the client
 153     contacts the server using an expired nonce the server will send
 154     back a 401 with <code>stale=true</code>. If <var>seconds</var> is
 155     greater than 0 then it specifies the amount of time for which the
 156     nonce is valid; this should probably never be set to less than 10
 157     seconds. If <var>seconds</var> is less than 0 then the nonce never
 158     expires. <!-- Not implemented yet If <var>seconds</var> is 0 then
 159     the nonce may be used exactly once by the client. Note that while
 160     one-time-nonces provide higher security against replay attacks,
 161     they also have significant performance implications, as the
 162     browser cannot pipeline or multiple connections for the
 163     requests. Because browsers cannot easily detect that
 164     one-time-nonces are being used, this may lead to browsers trying
 165     to pipeline requests and receiving 401 responses for all but the
 166     first request, requiring the browser to resend the requests. Note
 167     also that the protection against reply attacks only makes sense
 168     for dynamically generated content and things like POST requests;
 169     for static content the attacker may already have the complete
 170     response, so one-time-nonces do not make sense here.  -->
 171     </p>
 172 </usage>
 173 </directivesynopsis>
 174
 175 <directivesynopsis>
 176 <name>AuthDigestNonceFormat</name>
 177 <description>Determines how the nonce is generated</description>
 178 <syntax>AuthDigestNonceFormat <var>format</var></syntax>
 179 <contextlist><context>directory</context><context>.htaccess</context>
 180 </contextlist>
 181 <override>AuthConfig</override>
 182
 183 <usage>
 184     <p><strong>Not implemented yet.</strong> <!--
 185             <P>The AuthDigestNonceFormat directive determines how the nonce is
 186             generated.
 187             -->
 188     </p>
 189 </usage>
 190 </directivesynopsis>
 191
 192 <directivesynopsis>
 193 <name>AuthDigestNcCheck</name>
 194 <description>Enables or disables checking of the nonce-count sent by the
 195 server</description>
 196 <syntax>AuthDigestNcCheck On|Off</syntax>
 197 <default>AuthDigestNcCheck Off</default>
 198 <contextlist><context>server config</context></contextlist>
 199
 200 <usage>
 201     <note>
 202       Not implemented yet.
 203     </note>
 204     <!--
 205             <P>The AuthDigestNcCheck directive enables or disables the checking of the
 206             nonce-count sent by the server.
 207
 208             <P>While recommended from a security standpoint, turning this directive
 209             On has one important performance implication. To check the nonce-count
 210             *all* requests (which have an Authorization header, irrespective of
 211             whether they require digest authentication) must be serialized through
 212             a critical section. If the server is handling a large number of
 213             requests which contain the Authorization header then this may noticeably
 214             impact performance.
 215      -->
 216 </usage>
 217 </directivesynopsis>
 218
 219 <directivesynopsis>
 220 <name>AuthDigestAlgorithm</name>
 221 <description>Selects the algorithm used to calculate the challenge and
 222 response hases in digest authentication</description>
 223 <syntax>AuthDigestAlgorithm MD5|MD5-sess</syntax>
 224 <default>AuthDigestAlgorithm MD5</default>
 225 <contextlist><context>directory</context><context>.htaccess</context>
 226 </contextlist>
 227 <override>AuthConfig</override>
 228
 229 <usage>
 230     <p>The <directive>AuthDigestAlgorithm</directive> directive
 231     selects the algorithm used to calculate the challenge and response
 232     hashes.</p>
 233
 234     <note>
 235       <code>MD5-sess</code> is not correctly implemented yet.
 236     </note>
 237     <!--
 238             <P>To use <EM>MD5-sess</EM> you must first code up the
 239             <VAR>get_userpw_hash()</VAR> function in <VAR>mod_auth_digest.c</VAR> .
 240     -->
 241 </usage>
 242 </directivesynopsis>
 243
 244 <directivesynopsis>
 245 <name>AuthDigestDomain</name>
 246 <description>URIs that are in the same protection space for digest
 247 authentication</description>
 248 <syntax>AuthDigestDomain <var>URI</var> [<var>URI</var>] ...</syntax>
 249 <contextlist><context>directory</context><context>.htaccess</context>
 250 </contextlist>
 251 <override>AuthConfig</override>
 252
 253 <usage>
 254     <p>The <directive>AuthDigestDomain</directive> directive allows
 255     you to specify one or more URIs which are in the same protection
 256     space (i.e. use the same realm and username/password info). The
 257     specified URIs are prefixes, i.e. the client will assume that all
 258     URIs "below" these are also protected by the same
 259     username/password. The URIs may be either absolute URIs
 260     (i.e. inluding a scheme, host, port, etc) or relative URIs.</p>
 261
 262     <p>This directive <em>should</em> always be specified and
 263     contain at least the (set of) root URI(s) for this space.
 264     Omitting to do so will cause the client to send the
 265     Authorization header for <em>every request</em> sent to this
 266     server. Apart from increasing the size of the request, it may
 267     also have a detrimental effect on performance if
 268     "AuthDigestNcCheck" is on.</p>
 269
 270     <p>The URIs specified can also point to different servers, in
 271     which case clients (which understand this) will then share
 272     username/password info across multiple servers without
 273     prompting the user each time. </p>
 274 </usage>
 275 </directivesynopsis>
 276
 277 </modulesynopsis>