1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>mod_auth_digest - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body> 17<div id="page-header"> 18<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 19<p class="apache">Apache HTTP Server Version 2.4</p> 20<img alt="" src="/images/feather.gif" /></div> 21<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 22<div id="path"> 23<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Modules</a></div> 24<div id="page-content"> 25<div id="preamble"><h1>Apache Module mod_auth_digest</h1> 26<div class="toplang"> 27<p><span>Available Languages: </span><a href="/en/mod/mod_auth_digest.html" title="English"> en </a> | 28<a href="/fr/mod/mod_auth_digest.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 29<a href="/ko/mod/mod_auth_digest.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p> 30</div> 31<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>User authentication using MD5 32 Digest Authentication</td></tr> 33<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> 34<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>auth_digest_module</td></tr> 35<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_auth_digest.c</td></tr></table> 36<h3>Summary</h3> 37 38 <p>This module implements HTTP Digest Authentication 39 (<a href="http://www.faqs.org/rfcs/rfc2617.html">RFC2617</a>), and 40 provides an alternative to <code class="module"><a href="/mod/mod_auth_basic.html">mod_auth_basic</a></code> where the 41 password is not transmitted as cleartext. However, this does 42 <strong>not</strong> lead to a significant security advantage over 43 basic authentication. On the other hand, the password storage on the 44 server is much less secure with digest authentication than with 45 basic authentication. Therefore, using basic auth and encrypting the 46 whole connection using <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> is a much better 47 alternative.</p> 48</div> 49<div id="quickview"><h3 class="directives">Directives</h3> 50<ul id="toc"> 51<li><img alt="" src="/images/down.gif" /> <a href="#authdigestalgorithm">AuthDigestAlgorithm</a></li> 52<li><img alt="" src="/images/down.gif" /> <a href="#authdigestdomain">AuthDigestDomain</a></li> 53<li><img alt="" src="/images/down.gif" /> <a href="#authdigestnoncelifetime">AuthDigestNonceLifetime</a></li> 54<li><img alt="" src="/images/down.gif" /> <a href="#authdigestprovider">AuthDigestProvider</a></li> 55<li><img alt="" src="/images/down.gif" /> <a href="#authdigestqop">AuthDigestQop</a></li> 56<li><img alt="" src="/images/down.gif" /> <a href="#authdigestshmemsize">AuthDigestShmemSize</a></li> 57</ul> 58<h3>Topics</h3> 59<ul id="topics"> 60<li><img alt="" src="/images/down.gif" /> <a href="#using">Using Digest Authentication</a></li> 61</ul><h3>See also</h3> 62<ul class="seealso"> 63<li><code class="directive"><a href="/mod/mod_authn_core.html#authname">AuthName</a></code></li> 64<li><code class="directive"><a href="/mod/mod_authn_core.html#authtype">AuthType</a></code></li> 65<li><code class="directive"><a href="/mod/mod_authz_core.html#require">Require</a></code></li> 66<li><a href="/howto/auth.html">Authentication howto</a></li> 67</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 68<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 69<div class="section"> 70<h2><a name="using" id="using">Using Digest Authentication</a></h2> 71 72 <p>To use MD5 Digest authentication, simply 73 change the normal <code>AuthType Basic</code> and 74 <code class="directive"><a href="/mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> 75 to <code>AuthType Digest</code> and 76 <code class="directive"><a href="#authdigestprovider">AuthDigestProvider</a></code>, 77 when setting up authentication, then add a 78 <code class="directive"><a href="#authdigestdomain">AuthDigestDomain</a></code> directive containing at least the root 79 URI(s) for this protection space.</p> 80 81 <p>Appropriate user (text) files can be created using the 82 <code class="program"><a href="/programs/htdigest.html">htdigest</a></code> tool.</p> 83 84 <div class="example"><h3>Example:</h3><pre class="prettyprint lang-config"><Location /private/> 85 AuthType Digest 86 AuthName "private area" 87 AuthDigestDomain /private/ http://mirror.my.dom/private2/ 88 89 AuthDigestProvider file 90 AuthUserFile /web/auth/.digest_pw 91 Require valid-user 92</Location></pre> 93</div> 94 95 <div class="note"><h3>Note</h3> 96 <p>Digest authentication was intended to be more secure than basic 97 authentication, but no longer fulfills that design goal. A 98 man-in-the-middle attacker can trivially force the browser to downgrade 99 to basic authentication. And even a passive eavesdropper can brute-force 100 the password using today's graphics hardware, because the hashing 101 algorithm used by digest authentication is too fast. Another problem is 102 that the storage of the passwords on the server is insecure. The contents 103 of a stolen htdigest file can be used directly for digest authentication. 104 Therefore using <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> to encrypt the whole connection is 105 strongly recommended.</p> 106 <p><code class="module"><a href="/mod/mod_auth_digest.html">mod_auth_digest</a></code> only works properly on platforms 107 where APR supports shared memory.</p> 108 </div> 109</div> 110<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 111<div class="directive-section"><h2><a name="AuthDigestAlgorithm" id="AuthDigestAlgorithm">AuthDigestAlgorithm</a> <a name="authdigestalgorithm" id="authdigestalgorithm">Directive</a></h2> 112<table class="directive"> 113<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Selects the algorithm used to calculate the challenge and 114response hashes in digest authentication</td></tr> 115<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDigestAlgorithm MD5|MD5-sess</code></td></tr> 116<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthDigestAlgorithm MD5</code></td></tr> 117<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 118<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 119<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 120<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_digest</td></tr> 121</table> 122 <p>The <code class="directive">AuthDigestAlgorithm</code> directive 123 selects the algorithm used to calculate the challenge and response 124 hashes.</p> 125 126 <div class="note"> 127 <code>MD5-sess</code> is not correctly implemented yet. 128 </div> 129 130 131</div> 132<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 133<div class="directive-section"><h2><a name="AuthDigestDomain" id="AuthDigestDomain">AuthDigestDomain</a> <a name="authdigestdomain" id="authdigestdomain">Directive</a></h2> 134<table class="directive"> 135<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>URIs that are in the same protection space for digest 136authentication</td></tr> 137<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDigestDomain <var>URI</var> [<var>URI</var>] ...</code></td></tr> 138<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 139<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 140<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 141<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_digest</td></tr> 142</table> 143 <p>The <code class="directive">AuthDigestDomain</code> directive allows 144 you to specify one or more URIs which are in the same protection 145 space (<em>i.e.</em> use the same realm and username/password info). 146 The specified URIs are prefixes; the client will assume 147 that all URIs "below" these are also protected by the same 148 username/password. The URIs may be either absolute URIs (<em>i.e.</em> 149 including a scheme, host, port, etc.) or relative URIs.</p> 150 151 <p>This directive <em>should</em> always be specified and 152 contain at least the (set of) root URI(s) for this space. 153 Omitting to do so will cause the client to send the 154 Authorization header for <em>every request</em> sent to this 155 server.</p> 156 157 <p>The URIs specified can also point to different servers, in 158 which case clients (which understand this) will then share 159 username/password info across multiple servers without 160 prompting the user each time. </p> 161 162</div> 163<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 164<div class="directive-section"><h2><a name="AuthDigestNonceLifetime" id="AuthDigestNonceLifetime">AuthDigestNonceLifetime</a> <a name="authdigestnoncelifetime" id="authdigestnoncelifetime">Directive</a></h2> 165<table class="directive"> 166<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>How long the server nonce is valid</td></tr> 167<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDigestNonceLifetime <var>seconds</var></code></td></tr> 168<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthDigestNonceLifetime 300</code></td></tr> 169<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 170<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 171<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 172<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_digest</td></tr> 173</table> 174 <p>The <code class="directive">AuthDigestNonceLifetime</code> directive 175 controls how long the server nonce is valid. When the client 176 contacts the server using an expired nonce the server will send 177 back a 401 with <code>stale=true</code>. If <var>seconds</var> is 178 greater than 0 then it specifies the amount of time for which the 179 nonce is valid; this should probably never be set to less than 10 180 seconds. If <var>seconds</var> is less than 0 then the nonce never 181 expires. 182 </p> 183 184</div> 185<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 186<div class="directive-section"><h2><a name="AuthDigestProvider" id="AuthDigestProvider">AuthDigestProvider</a> <a name="authdigestprovider" id="authdigestprovider">Directive</a></h2> 187<table class="directive"> 188<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the authentication provider(s) for this location</td></tr> 189<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDigestProvider <var>provider-name</var> 190[<var>provider-name</var>] ...</code></td></tr> 191<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthDigestProvider file</code></td></tr> 192<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 193<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 194<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 195<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_digest</td></tr> 196</table> 197 <p>The <code class="directive">AuthDigestProvider</code> directive sets 198 which provider is used to authenticate the users for this location. 199 The default <code>file</code> provider is implemented 200 by the <code class="module"><a href="/mod/mod_authn_file.html">mod_authn_file</a></code> module. Make sure 201 that the chosen provider module is present in the server.</p> 202 203 <p>See <code class="module"><a href="/mod/mod_authn_dbm.html">mod_authn_dbm</a></code>, <code class="module"><a href="/mod/mod_authn_file.html">mod_authn_file</a></code>, 204 <code class="module"><a href="/mod/mod_authn_dbd.html">mod_authn_dbd</a></code> and <code class="module"><a href="/mod/mod_authn_socache.html">mod_authn_socache</a></code> 205 for providers.</p> 206 207</div> 208<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 209<div class="directive-section"><h2><a name="AuthDigestQop" id="AuthDigestQop">AuthDigestQop</a> <a name="authdigestqop" id="authdigestqop">Directive</a></h2> 210<table class="directive"> 211<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines the quality-of-protection to use in digest 212authentication</td></tr> 213<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDigestQop none|auth|auth-int [auth|auth-int]</code></td></tr> 214<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthDigestQop auth</code></td></tr> 215<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 216<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 217<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 218<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_digest</td></tr> 219</table> 220 <p>The <code class="directive">AuthDigestQop</code> directive determines 221 the <dfn>quality-of-protection</dfn> to use. <code>auth</code> will 222 only do authentication (username/password); <code>auth-int</code> is 223 authentication plus integrity checking (an MD5 hash of the entity 224 is also computed and checked); <code>none</code> will cause the module 225 to use the old RFC-2069 digest algorithm (which does not include 226 integrity checking). Both <code>auth</code> and <code>auth-int</code> may 227 be specified, in which the case the browser will choose which of 228 these to use. <code>none</code> should only be used if the browser for 229 some reason does not like the challenge it receives otherwise.</p> 230 231 <div class="note"> 232 <code>auth-int</code> is not implemented yet. 233 </div> 234 235</div> 236<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 237<div class="directive-section"><h2><a name="AuthDigestShmemSize" id="AuthDigestShmemSize">AuthDigestShmemSize</a> <a name="authdigestshmemsize" id="authdigestshmemsize">Directive</a></h2> 238<table class="directive"> 239<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The amount of shared memory to allocate for keeping track 240of clients</td></tr> 241<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDigestShmemSize <var>size</var></code></td></tr> 242<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthDigestShmemSize 1000</code></td></tr> 243<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 244<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 245<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_digest</td></tr> 246</table> 247 <p>The <code class="directive">AuthDigestShmemSize</code> directive defines 248 the amount of shared memory, that will be allocated at the server 249 startup for keeping track of clients. Note that the shared memory 250 segment cannot be set less than the space that is necessary for 251 tracking at least <em>one</em> client. This value is dependent on your 252 system. If you want to find out the exact value, you may simply 253 set <code class="directive">AuthDigestShmemSize</code> to the value of 254 <code>0</code> and read the error message after trying to start the 255 server.</p> 256 257 <p>The <var>size</var> is normally expressed in Bytes, but you 258 may follow the number with a <code>K</code> or an <code>M</code> to 259 express your value as KBytes or MBytes. For example, the following 260 directives are all equivalent:</p> 261 262<pre class="prettyprint lang-config">AuthDigestShmemSize 1048576 263AuthDigestShmemSize 1024K 264AuthDigestShmemSize 1M</pre> 265 266 267</div> 268</div> 269<div class="bottomlang"> 270<p><span>Available Languages: </span><a href="/en/mod/mod_auth_digest.html" title="English"> en </a> | 271<a href="/fr/mod/mod_auth_digest.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 272<a href="/ko/mod/mod_auth_digest.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p> 273</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 274<script type="text/javascript"><!--//--><![CDATA[//><!-- 275var comments_shortname = 'httpd'; 276var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_auth_digest.html'; 277(function(w, d) { 278 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 279 d.write('<div id="comments_thread"><\/div>'); 280 var s = d.createElement('script'); 281 s.type = 'text/javascript'; 282 s.async = true; 283 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 284 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 285 } 286 else { 287 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 288 } 289})(window, document); 290//--><!]]></script></div><div id="footer"> 291<p class="apache">Copyright 2014 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 292<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 293if (typeof(prettyPrint) !== 'undefined') { 294 prettyPrint(); 295} 296//--><!]]></script> 297</body></html>
