docs/manual/mod/mod_auth_digest.xml

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 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

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<modulesynopsis metafile="mod_auth_digest.xml.meta">

<name>mod_auth_digest</name>
<description>User authentication using MD5
    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
    (<rfc>2617</rfc>), an alternative to the Basic authentication provided
    by <module>mod_auth_basic</module> in which the password is not sent
    over the network in cleartext.</p>

    <p>Basic and Digest are both authentication schemes only: they
    establish who the client is, and do nothing for the confidentiality or
    integrity of the request and response themselves. Over an unencrypted
    connection the contents of every request and response are exposed with
    either scheme; Digest's one advantage is that the password is not among
    them. Digest is therefore not a substitute for a connection secured
    with <module>mod_ssl</module>, which protects the credentials and the
    data alike, and that one advantage has limits of its own (see the note
    below).</p>
</summary>

<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>To use MD5 Digest authentication, configure the location to be
    protected as shown in the below example:</p>

    <example><title>Example:</title>
    <highlight language="config">
&lt;Location "/private/"&gt;
    AuthType Digest
    AuthName "private area"
    AuthDigestDomain "/private/" "http://mirror.my.dom/private2/"

    AuthDigestProvider file
    AuthUserFile "/web/auth/.digest_pw"
    Require valid-user
&lt;/Location&gt;
      </highlight>
    </example>

    <p><directive module="mod_auth_digest">AuthDigestDomain</directive>
    should list the locations that will be protected by this
    configuration.</p>

    <p>The password 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's one advantage over Basic, keeping the
    password off the wire, is conditional. If the client will silently fall
    back to Basic when challenged, an active attacker can
    strip the Digest challenge and offer Basic instead, and the browser
    then sends the password in cleartext; a passive eavesdropper can mount
    an offline brute-force attack on a captured response, which the fast
    MD5 hash does little to slow; and if the <program>htdigest</program>
    file is stolen its stored hashes can be replayed to authenticate to
    that realm directly, without the password itself being recovered.
    Encrypt the whole connection with <module>mod_ssl</module> instead.</p>
    <p><module>mod_auth_digest</module> requires an APR built with shared
    memory support, and is not built without it.</p>
    </note>
</section>


<directivesynopsis>
<name>AuthDigestProvider</name>
<description>Sets the authentication provider(s) for this location</description>
<syntax>AuthDigestProvider <var>provider-name</var>
[<var>provider-name</var>] ...</syntax>
<default>AuthDigestProvider file</default>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p>The <directive>AuthDigestProvider</directive> directive sets
    which provider is used to authenticate the users for this location.
    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>, <module>mod_authn_file</module>,
    <module>mod_authn_dbd</module> and <module>mod_authn_socache</module>
    for providers.</p>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>AuthDigestQop</name>
<description>Determines the quality-of-protection to use in Digest
authentication</description>
<syntax>AuthDigestQop auth</syntax>
<default>AuthDigestQop auth</default>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p>The <directive>AuthDigestQop</directive> directive determines the
    <dfn>quality-of-protection</dfn> to use. Only <code>auth</code>
    (authentication) is supported, and it is the default, so this
    directive no longer has any effect and is retained only for
    compatibility.</p>

    <note>Earlier releases also accepted <code>none</code> (the RFC 2069
    Digest scheme, without a quality-of-protection). It has been removed:
    a request whose <code>qop</code> is missing or not <code>auth</code>
    is now rejected.</note>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>AuthDigestNonceLifetime</name>
<description>How long the server nonce is valid</description>
<syntax>AuthDigestNonceLifetime <var>seconds</var></syntax>
<default>AuthDigestNonceLifetime 300</default>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p>The <directive>AuthDigestNonceLifetime</directive> directive
    controls how long the server nonce is valid. When the client contacts
    the server using an expired nonce the server sends back a 401 with
    <code>stale=true</code>, and an RFC-compliant client retries with a
    fresh nonce without prompting the user.</p>

    <ul>
      <li>If <var>seconds</var> is greater than 0 then it specifies the
      amount of time for which the nonce is valid; this should probably
      never be set to less than 10 seconds.</li>

      <li>If <var>seconds</var> is 0 then the nonce may be used exactly
      once. The server supplies the next nonce in the
      <code>Authentication-Info</code> header of each response so the
      client can continue; a client which reuses a nonce is answered with
      <code>stale=true</code> and retries. One-time nonces give stronger
      protection against replaying a captured request, but the client
      cannot pipeline requests, and one that does receives a 401 for all
      but the first and has to resend them. The protection is worth this
      cost mainly for requests that change server state or return content
      which varies over time; replaying a request for unchanging content
      that the eavesdropper already captured in full gains nothing.</li>

      <li>If <var>seconds</var> is less than 0 then the nonce never
      expires.</li>
    </ul>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>AuthDigestNcCheck</name>
<description>Enables or disables checking of the nonce-count sent by the
client</description>
<syntax>AuthDigestNcCheck On|Off</syntax>
<default>AuthDigestNcCheck Off</default>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
<override>AuthConfig</override>

<usage>
    <p>The <directive>AuthDigestNcCheck</directive> directive enables or
    disables the verification of the nonce-count value sent by the client.
    The nonce-count is a sequential counter that the client increments with
    each request using the same nonce. Checking it helps detect replay
    attacks.</p>

    <p>This feature requires shared memory support on the platform.
    If shared memory is not available and this directive is set to
    <code>On</code>, the server will return an error at startup.</p>

    <p>While recommended from a security standpoint, enabling this
    directive has a performance implication: all requests carrying an
    <code>Authorization</code> header must be serialized through a
    critical section in order to safely compare nonce-count values.
    On high-traffic servers this may be noticeable.</p>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>AuthDigestAlgorithm</name>
<description>Selects the algorithm used to calculate the challenge and
response hashes in Digest authentication</description>
<syntax>AuthDigestAlgorithm MD5</syntax>
<default>AuthDigestAlgorithm MD5</default>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p>The <directive>AuthDigestAlgorithm</directive> directive
    selects the algorithm used to calculate the challenge and response
    hashes. Only <code>MD5</code> is supported.</p>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>AuthDigestDomain</name>
<description>URIs that are in the same protection space for Digest
authentication</description>
<syntax>AuthDigestDomain <var>URI</var> [<var>URI</var>] ...</syntax>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
<override>AuthConfig</override>

<usage>
    <p>The <directive>AuthDigestDomain</directive> directive allows
    you to specify one or more URIs which are in the same protection
    space (<em>i.e.</em> use the same realm and username/password info).
    The specified URIs are prefixes; the client will assume
    that all URIs "below" these are also protected by the same
    username/password. The URIs may be either absolute URIs (<em>i.e.</em>
    including a scheme, host, port, etc.) or relative URIs.</p>

    <p>This directive <em>should</em> always be specified and
    contain at least the (set of) root URI(s) for this space.
    Omitting to do so will cause the client to send the
    Authorization header for <em>every request</em> sent to this
    server. Apart from increasing the size of the request, it may
    also have a detrimental effect on performance if <directive
    module="mod_auth_digest">AuthDigestNcCheck</directive> is on.</p>

    <p>The URIs specified can also point to different servers, in
    which case clients (which understand this) will then share
    username/password info across multiple servers without
    prompting the user each time. </p>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>AuthDigestShmemSize</name>
<description>The amount of shared memory to allocate for keeping track
of clients</description>
<syntax>AuthDigestShmemSize <var>size</var></syntax>
<default>AuthDigestShmemSize 8192</default>
<contextlist><context>server config</context></contextlist>

<usage>
    <p>The <directive>AuthDigestShmemSize</directive> directive defines
    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 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 default holds roughly 140 clients. A client which is discarded
    to make room for another is not denied access: it is issued a new
    nonce with <code>stale=true</code>, which costs it one extra request.
    Note that a request which does not authenticate also takes an entry,
    since the challenge sent back to it carries the identifier the client
    is tracked by.</p>

    <p>The <var>size</var> is normally expressed in Bytes, but you
    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>

<highlight language="config">
AuthDigestShmemSize 1048576
AuthDigestShmemSize 1024K
AuthDigestShmemSize 1M
    </highlight>
</usage>
</directivesynopsis>

</modulesynopsis>