mod_auth_digest.xml revision 70ce08850895485160d91d333b5a487ee2f80fbc
967e5f3c25249c779575864692935627004d3f9eChristian Maeder<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
f11f713bebd8e1e623a0a4361065df256033de47Christian Maeder<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
97018cf5fa25b494adffd7e9b4e87320dae6bf47Christian Maeder<!-- $Revision$ -->
967e5f3c25249c779575864692935627004d3f9eChristian Maeder Copyright 2002-2004 The Apache Software Foundation
f3a94a197960e548ecd6520bb768cb0d547457bbChristian Maeder Licensed under the Apache License, Version 2.0 (the "License");
717686b54b9650402e2ebfbaadf433eab8ba5171Christian Maeder you may not use this file except in compliance with the License.
717686b54b9650402e2ebfbaadf433eab8ba5171Christian Maeder You may obtain a copy of the License at
967e5f3c25249c779575864692935627004d3f9eChristian Maeder Unless required by applicable law or agreed to in writing, software
967e5f3c25249c779575864692935627004d3f9eChristian Maeder distributed under the License is distributed on an "AS IS" BASIS,
fd896e2068ad7e50aed66ac18c3720ea7ff2619fChristian Maeder WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
650bafe7709533bc5f82bb9daf8fa06f431cd963Christian Maeder See the License for the specific language governing permissions and
9cb4aa4ea6685489a38f9b609f5dbe5d37f25bc7Christian Maeder limitations under the License.
8b9fda012e5ee53b7b2320c0638896a0ff6e99f3Christian Maeder<modulesynopsis metafile="mod_auth_digest.xml.meta">
fd896e2068ad7e50aed66ac18c3720ea7ff2619fChristian Maeder<description>User authentication using MD5
967e5f3c25249c779575864692935627004d3f9eChristian Maeder Digest Authentication.</description>
717686b54b9650402e2ebfbaadf433eab8ba5171Christian Maeder <p>This module implements HTTP Digest Authentication. However, it
967e5f3c25249c779575864692935627004d3f9eChristian Maeder has not been extensively tested and is therefore marked
0a8ea95bcf0e3f84fed0b725c049ec2a956a4a28Christian Maeder experimental.</p>
07b72edb610ee53b4832d132e96b0a3d8423f8ebChristian Maeder<seealso><directive module="core">AuthName</directive></seealso>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder<seealso><directive module="core">AuthType</directive></seealso>
4fb19f237193a3bd6778f8aee3b6dd8da5856665Christian Maeder<seealso><directive module="core">Require</directive></seealso>
7a879b08ae0ca30006f9be887a73212b07f10204Christian Maeder<seealso><directive module="core">Satisfy</directive></seealso>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder<section id="using"><title>Using Digest Authentication</title>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder <p>Using MD5 Digest authentication is very simple. Simply set
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder up authentication normally, using <code>AuthType Digest</code> and
6e39bfd041946fce4982ac89834be73fd1bfb39aChristian Maeder <directive module="mod_auth_digest">AuthDigestProvider</directive>
e1839fb37a3a2ccd457464cb0dcc5efd466dbe22Christian Maeder instead of the normal <code>AuthType Basic</code> and
62ecb1e7f8fd9573eea8369657de12c7bf9f4f25Christian Maeder <directive module="mod_auth_basic">AuthBasicProvider</directive>.
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder Then add a <directive module="mod_auth_digest"
5e26bfc8d7b18cf3a3fa7b919b4450fb669f37a5Christian Maeder >AuthDigestDomain</directive> directive containing at least the root
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder URI(s) for this protection space.</p>
d5c415f6373274fed04d83b9322891f3b82e9c26Christian Maeder <p>Appropriate user (text) files can be created using the
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder <a href="/programs/htdigest.html">htdigest</a> tool.</p>
5e26bfc8d7b18cf3a3fa7b919b4450fb669f37a5Christian Maeder <Location /private/><br />
e7ce154edb906685b3fa7f6c0a764e18a4658068Christian Maeder AuthType Digest<br />
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder AuthName "private area"<br />
717686b54b9650402e2ebfbaadf433eab8ba5171Christian Maeder AuthDigestDomain /private/ http://mirror.my.dom/private2/<br />
d48085f765fca838c1d972d2123601997174583dChristian Maeder AuthDigestProvider file<br />
717686b54b9650402e2ebfbaadf433eab8ba5171Christian Maeder Require valid-user<br />
d48085f765fca838c1d972d2123601997174583dChristian Maeder </Location>
717686b54b9650402e2ebfbaadf433eab8ba5171Christian Maeder <p>Digest authentication is more secure than Basic authentication,
e7ce154edb906685b3fa7f6c0a764e18a4658068Christian Maeder but only works with supporting browsers. As of September 2004, major
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder browsers that support digest authentication include <a
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder href="http://www.w3.org/Amaya/">Amaya</a>, <a
e1839fb37a3a2ccd457464cb0dcc5efd466dbe22Christian Maeder href="http://konqueror.kde.org/">Konqueror</a>, <a
e7ce154edb906685b3fa7f6c0a764e18a4658068Christian Maeder href="http://www.microsoft.com/windows/ie/">MS Internet Explorer</a>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder for Mac OS X and Windows (although the Windows version fails when
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder used with a query string -- see "<a href="#msie" >Working with MS
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder Internet Explorer</a>" below for a workaround), <a
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder href="http://www.mozilla.org">Mozilla</a>, <a
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder href="http://channels.netscape.com/ns/browsers/download.jsp">
e7ce154edb906685b3fa7f6c0a764e18a4658068Christian Maeder Netscape</a> 7, <a href="http://www.opera.com/">Opera</a>, and <a
4fb19f237193a3bd6778f8aee3b6dd8da5856665Christian Maeder href="http://www.apple.com/safari/">Safari</a>. <a
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder href="http://lynx.isc.org/">lynx</a> does <strong>not</strong>
c66a930944d9e4d64a8f0f38c748fdad0831ff87Christian Maeder support digest authentication. Since digest authentication is not as
f11f713bebd8e1e623a0a4361065df256033de47Christian Maeder widely implemented as basic authentication, you should use it only
0a8ea95bcf0e3f84fed0b725c049ec2a956a4a28Christian Maeder in environments where all users will have supporting browsers.</p>
967e5f3c25249c779575864692935627004d3f9eChristian Maeder<section id="msie"><title>Working with MS Internet Explorer</title>
83814002b4922114cbe7e9ba728472a0bf44aac5Christian Maeder <p>The Digest authentication implementation in current Internet
dedabc954aa15f6ad0764472a9434dc6dafe3db2Christian Maeder Explorer for Windows implementations has known issues, namely that
e1839fb37a3a2ccd457464cb0dcc5efd466dbe22Christian Maeder <code>GET</code> requests with a query string are not RFC compliant.
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder There are a few ways to work around this issue.</p>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder The first way is to use <code>POST</code> requests instead of
e1839fb37a3a2ccd457464cb0dcc5efd466dbe22Christian Maeder <code>GET</code> requests to pass data to your program. This method
47355d1ba4e212c5fd34c089f71a319cde53c4c8Christian Maeder is the simplest approach if your application can work with this
47355d1ba4e212c5fd34c089f71a319cde53c4c8Christian Maeder <p>Since version 2.0.51 Apache also provides a workaround in the
47355d1ba4e212c5fd34c089f71a319cde53c4c8Christian Maeder <code>AuthDigestEnableQueryStringHack</code> environment variable.
47355d1ba4e212c5fd34c089f71a319cde53c4c8Christian Maeder If <code>AuthDigestEnableQueryStringHack</code> is set for the
47355d1ba4e212c5fd34c089f71a319cde53c4c8Christian Maeder request, Apache will take steps to work around the MSIE bug and
47355d1ba4e212c5fd34c089f71a319cde53c4c8Christian Maeder remove the request URI from the digest comparison. Using this
a89e661aad28f1b39f4fc9f9f9a4d46074234123Christian Maeder method would look similar to the following.</p>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder <example><title>Using Digest Authentication with MSIE:</title>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder BrowserMatch "MSIE" AuthDigestEnableQueryStringHack=On
47355d1ba4e212c5fd34c089f71a319cde53c4c8Christian Maeder <p>See the <directive module="mod_setenvif">BrowserMatch</directive>
47355d1ba4e212c5fd34c089f71a319cde53c4c8Christian Maeder directive for more details on conditionally setting environment
47355d1ba4e212c5fd34c089f71a319cde53c4c8Christian Maeder variables</p>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder<directivesynopsis>
dedabc954aa15f6ad0764472a9434dc6dafe3db2Christian Maeder<description>Sets the authentication provider(s) for this location</description>
a89e661aad28f1b39f4fc9f9f9a4d46074234123Christian Maeder<syntax>AuthDigestProvider On|Off|<var>provider-name</var>
7221c71b38c871ce66eee4537cb681d468308dfbChristian Maeder<contextlist><context>directory</context><context>.htaccess</context>
7221c71b38c871ce66eee4537cb681d468308dfbChristian Maeder</contextlist>
42c01284bba8d7c8d995c8dfb96ace57d28ed1bcTill Mossakowski <p>The <directive>AuthDigestProvider</directive> directive sets
842eedc62639561781b6c33533d1949693ef6cc5Christian Maeder which provider is used to authenticate the users for this location.
842eedc62639561781b6c33533d1949693ef6cc5Christian Maeder Setting the value to <code>On</code> will choose the default provider
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder (<code>file</code>). Since the <code>file</code> provider is implemented
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder by the <module>mod_authn_file</module> module, you have to make sure,
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder that the module is present in the server.</p>
bfa9e03532243ceb487f0384d0f6a447f1ce7670Till Mossakowski <p>See <module>mod_authn_dbm</module> and <module>mod_authn_file</module>
967e5f3c25249c779575864692935627004d3f9eChristian Maeder for providers.</p>
967e5f3c25249c779575864692935627004d3f9eChristian Maeder <p>The value <code>Off</code> clears the provider list and sets it back
dedabc954aa15f6ad0764472a9434dc6dafe3db2Christian Maeder to the default.</p>
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder</directivesynopsis>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder<directivesynopsis>
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder<description>Determines the quality-of-protection to use in digest
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maederauthentication</description>
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder<syntax>AuthDigestQop none|auth|auth-int [auth|auth-int]</syntax>
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder<contextlist><context>directory</context><context>.htaccess</context>
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder</contextlist>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder <p>The <directive>AuthDigestQop</directive> directive determines
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder the <dfn>quality-of-protection</dfn> to use. <code>auth</code> will
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder only do authentication (username/password); <code>auth-int</code> is
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder authentication plus integrity checking (an MD5 hash of the entity
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder is also computed and checked); <code>none</code> will cause the module
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder to use the old RFC-2069 digest algorithm (which does not include
4ef2a978e66e2246ff0b7f00c77deb7aabb28b8eChristian Maeder integrity checking). Both <code>auth</code> and <code>auth-int</code> may
4ef2a978e66e2246ff0b7f00c77deb7aabb28b8eChristian Maeder be specified, in which the case the browser will choose which of
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder these to use. <code>none</code> should only be used if the browser for
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder some reason does not like the challenge it receives otherwise.</p>
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder <code>auth-int</code> is not implemented yet.
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder</directivesynopsis>
4ef2a978e66e2246ff0b7f00c77deb7aabb28b8eChristian Maeder<directivesynopsis>
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder<description>How long the server nonce is valid</description>
ee9eddfa6953868fd6fbaff0d9ff68675a13675aChristian Maeder<syntax>AuthDigestNonceLifetime <var>seconds</var></syntax>
2ac1742771a267119f1d839054b5e45d0a468085Christian Maeder<default>AuthDigestNonceLifetime 300</default>
2ac1742771a267119f1d839054b5e45d0a468085Christian Maeder<contextlist><context>directory</context><context>.htaccess</context>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder</contextlist>
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder <p>The <directive>AuthDigestNonceLifetime</directive> directive
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder controls how long the server nonce is valid. When the client
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder contacts the server using an expired nonce the server will send
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder back a 401 with <code>stale=true</code>. If <var>seconds</var> is
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder greater than 0 then it specifies the amount of time for which the
4fb19f237193a3bd6778f8aee3b6dd8da5856665Christian Maeder nonce is valid; this should probably never be set to less than 10
2ac1742771a267119f1d839054b5e45d0a468085Christian Maeder seconds. If <var>seconds</var> is less than 0 then the nonce never
2ac1742771a267119f1d839054b5e45d0a468085Christian Maeder expires. <!-- Not implemented yet: If <var>seconds</var> is 0 then
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder the nonce may be used exactly once by the client. Note that while
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder one-time-nonces provide higher security against replay attacks,
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder they also have significant performance implications, as the
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder browser cannot pipeline or multiple connections for the
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder requests. Because browsers cannot easily detect that
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder one-time-nonces are being used, this may lead to browsers trying
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder to pipeline requests and receiving 401 responses for all but the
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder first request, requiring the browser to resend the requests. Note
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder also that the protection against reply attacks only makes sense
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder for dynamically generated content and things like POST requests;
deb7bff126ec547bd812d0c8683ad6e785a45abbChristian Maeder for static content the attacker may already have the complete
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder response, so one-time-nonces do not make sense here. -->
967e5f3c25249c779575864692935627004d3f9eChristian Maeder</directivesynopsis>
4ef2a978e66e2246ff0b7f00c77deb7aabb28b8eChristian Maeder<directivesynopsis>
83814002b4922114cbe7e9ba728472a0bf44aac5Christian Maeder<description>Determines how the nonce is generated</description>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder<syntax>AuthDigestNonceFormat <var>format</var></syntax>
dedabc954aa15f6ad0764472a9434dc6dafe3db2Christian Maeder<contextlist><context>directory</context><context>.htaccess</context>
97ee7048e63953c5617342ce38c30cbcb35cc0beChristian Maeder</contextlist>
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder <!-- The AuthDigestNonceFormat directive determines how the nonce is
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maeder generated. -->
dedabc954aa15f6ad0764472a9434dc6dafe3db2Christian Maeder</directivesynopsis>
588c0c022a0f4e129a89c3bc569daf6a835e182dChristian Maeder<directivesynopsis>
4fb19f237193a3bd6778f8aee3b6dd8da5856665Christian Maeder<description>Enables or disables checking of the nonce-count sent by the
2dfc7b04f2db681992ca04175f2beb0f127c9844Christian Maederserver</description>
07b72edb610ee53b4832d132e96b0a3d8423f8ebChristian Maeder<contextlist><context>server config</context></contextlist>
<code>mod_auth_digest.c</code>.</p>