<!-- $LastChangedRevision$ -->
<!--
- Copyright 2002-2005 The Apache Software Foundation or its licensors, as
- applicable.
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
<name>mod_auth_digest</name>
<description>User authentication using MD5
- Digest Authentication.</description>
-<status>Experimental</status>
+ Digest Authentication</description>
+<status>Extension</status>
<sourcefile>mod_auth_digest.c</sourcefile>
<identifier>auth_digest_module</identifier>
<summary>
- <p>This module implements HTTP Digest Authentication. However, it
- has not been extensively tested and is therefore marked
- experimental.</p>
+ <p>This module implements HTTP Digest Authentication
+ (<a href="http://www.faqs.org/rfcs/rfc2617.html">RFC2617</a>), and
+ provides an alternative to <module>mod_auth_basic</module> where the
+ password is not transmitted as cleartext. However, this does
+ <strong>not</strong> lead to a significant security advantage over
+ basic authentication. On the other hand, the password storage on the
+ server is much less secure with digest authentication than with
+ basic authentication. Therefore, using basic auth and encrypting the
+ whole connection using <module>mod_ssl</module> is a much better
+ alternative.</p>
</summary>
-<seealso><directive module="core">AuthName</directive></seealso>
-<seealso><directive module="core">AuthType</directive></seealso>
-<seealso><directive module="core">Require</directive></seealso>
-<seealso><directive module="core">Satisfy</directive></seealso>
+<seealso><directive module="mod_authn_core">AuthName</directive></seealso>
+<seealso><directive module="mod_authn_core">AuthType</directive></seealso>
+<seealso><directive module="mod_authz_core">Require</directive></seealso>
+<seealso><a href="../howto/auth.html">Authentication howto</a></seealso>
<section id="using"><title>Using Digest Authentication</title>
- <p>Using MD5 Digest authentication is very simple. Simply set
- up authentication normally, using <code>AuthType Digest</code> and
- <directive module="mod_auth_digest">AuthDigestProvider</directive>
- instead of the normal <code>AuthType Basic</code> and
- <directive module="mod_auth_basic">AuthBasicProvider</directive>.
- Then add a <directive module="mod_auth_digest"
- >AuthDigestDomain</directive> directive containing at least the root
- URI(s) for this protection space.</p>
-
- <p>Appropriate user (text) files can be created using the
- <program>htdigest</program> tool.</p>
+ <p>To use MD5 Digest authentication, configure the location to be
+ protected as shown in the below example:</p>
<example><title>Example:</title>
- <Location /private/><br />
- <indent>
- AuthType Digest<br />
- AuthName "private area"<br />
- AuthDigestDomain /private/ http://mirror.my.dom/private2/<br />
- <br />
- AuthDigestProvider file<br />
- AuthUserFile /web/auth/.digest_pw<br />
- Require valid-user<br />
- </indent>
- </Location>
+ <highlight language="config">
+<Location "/private/">
+ AuthType Digest
+ AuthName "private area"
+ AuthDigestDomain "/private/" "http://mirror.my.dom/private2/"
+
+ AuthDigestProvider file
+ AuthUserFile "/web/auth/.digest_pw"
+ Require valid-user
+</Location>
+ </highlight>
</example>
- <note><title>Note</title>
- <p>Digest authentication is more secure than Basic authentication,
- but only works with supporting browsers. As of September 2004, major
- browsers that support digest authentication include <a
- href="http://www.w3.org/Amaya/">Amaya</a>, <a
- href="http://konqueror.kde.org/">Konqueror</a>, <a
- href="http://www.microsoft.com/windows/ie/">MS Internet Explorer</a>
- for Mac OS X and Windows (although the Windows version fails when
- used with a query string -- see "<a href="#msie" >Working with MS
- Internet Explorer</a>" below for a workaround), <a
- href="http://www.mozilla.org">Mozilla</a>, <a
- href="http://channels.netscape.com/ns/browsers/download.jsp">
- Netscape</a> 7, <a href="http://www.opera.com/">Opera</a>, and <a
- href="http://www.apple.com/safari/">Safari</a>. <a
- href="http://lynx.isc.org/">lynx</a> does <strong>not</strong>
- support digest authentication. Since digest authentication is not as
- widely implemented as basic authentication, you should use it only
- in environments where all users will have supporting browsers.</p>
+ <p><directive module="mod_auth_digest">AuthDigestDomain</directive>
+ should list the locations that will be protected by this
+ configuration.</p>
+
+ <p>The pasword file referenced in the <directive
+ module="mod_auth_digest">AuthUserFile</directive> directive may be
+ created and managed using the <program>htdigest</program> tool.</p>
+
+
+ <note><title>Note</title>
+ <p>Digest authentication was intended to be more secure than basic
+ authentication, but no longer fulfills that design goal. A
+ man-in-the-middle attacker can trivially force the browser to downgrade
+ to basic authentication. And even a passive eavesdropper can brute-force
+ the password using today's graphics hardware, because the hashing
+ algorithm used by digest authentication is too fast. Another problem is
+ that the storage of the passwords on the server is insecure. The contents
+ of a stolen htdigest file can be used directly for digest authentication.
+ Therefore using <module>mod_ssl</module> to encrypt the whole connection is
+ strongly recommended.</p>
+ <p><module>mod_auth_digest</module> only works properly on platforms
+ where APR supports shared memory.</p>
</note>
</section>
-<section id="msie"><title>Working with MS Internet Explorer</title>
- <p>The Digest authentication implementation in current Internet
- Explorer for Windows implementations has known issues, namely that
- <code>GET</code> requests with a query string are not RFC compliant.
- There are a few ways to work around this issue.</p>
-
- <p>
- The first way is to use <code>POST</code> requests instead of
- <code>GET</code> requests to pass data to your program. This method
- is the simplest approach if your application can work with this
- limitation.
- </p>
-
- <p>Since version 2.0.51 Apache also provides a workaround in the
- <code>AuthDigestEnableQueryStringHack</code> environment variable.
- If <code>AuthDigestEnableQueryStringHack</code> is set for the
- request, Apache will take steps to work around the MSIE bug and
- remove the request URI from the digest comparison. Using this
- method would look similar to the following.</p>
-
- <example><title>Using Digest Authentication with MSIE:</title>
- BrowserMatch "MSIE" AuthDigestEnableQueryStringHack=On
- </example>
-
- <p>See the <directive module="mod_setenvif">BrowserMatch</directive>
- directive for more details on conditionally setting environment
- variables</p>
-</section>
-
<directivesynopsis>
<name>AuthDigestProvider</name>
<description>Sets the authentication provider(s) for this location</description>
-<syntax>AuthDigestProvider On|Off|<var>provider-name</var>
+<syntax>AuthDigestProvider <var>provider-name</var>
[<var>provider-name</var>] ...</syntax>
-<default>AuthDigestProvider On</default>
+<default>AuthDigestProvider file</default>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>
<usage>
- <p>The <directive>AuthDigestProvider</directive> directive sets
+ <p>The <directive>AuthDigestProvider</directive> directive sets
which provider is used to authenticate the users for this location.
- Setting the value to <code>On</code> will choose the default provider
- (<code>file</code>). Since the <code>file</code> provider is implemented
- by the <module>mod_authn_file</module> module, you have to make sure,
- that the module is present in the server.</p>
+ The default <code>file</code> provider is implemented
+ by the <module>mod_authn_file</module> module. Make sure
+ that the chosen provider module is present in the server.</p>
- <p>See <module>mod_authn_dbm</module> and <module>mod_authn_file</module>
+ <p>See <module>mod_authn_dbm</module>, <module>mod_authn_file</module>,
+ <module>mod_authn_dbd</module> and <module>mod_authn_socache</module>
for providers.</p>
-
- <p>The value <code>Off</code> clears the provider list and sets it back
- to the default.</p>
</usage>
</directivesynopsis>
one-time-nonces are being used, this may lead to browsers trying
to pipeline requests and receiving 401 responses for all but the
first request, requiring the browser to resend the requests. Note
- also that the protection against reply attacks only makes sense
+ also that the protection against replay attacks only makes sense
for dynamically generated content and things like POST requests;
for static content the attacker may already have the complete
response, so one-time-nonces do not make sense here. -->
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 necessary for
- tracking at least <em>one</em> client. This value is dependant on your
+ tracking at least <em>one</em> client. This value is dependent 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
+ may follow the number with 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>
+<highlight language="config">
+AuthDigestShmemSize 1048576
+AuthDigestShmemSize 1024K
+AuthDigestShmemSize 1M
+ </highlight>
</usage>
</directivesynopsis>
projects / apache / blobdiff