mirror of
https://github.com/apache/httpd.git
synced 2025-05-17 15:21:13 +03:00
d56f872d3e
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@87879 13f79535-47bb-0310-9956-ffa450edef68
413 lines
13 KiB
HTML
413 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Apache module mod_auth_digest</TITLE>
|
|
</HEAD>
|
|
|
|
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
|
|
<BODY
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#000080"
|
|
ALINK="#FF0000"
|
|
>
|
|
<!--#include virtual="header.html" -->
|
|
<H1 ALIGN="CENTER">Module mod_auth_digest</H1>
|
|
|
|
<p>This module provides for user authentication using MD5 Digest
|
|
Authentication.</p>
|
|
|
|
<P><A
|
|
HREF="module-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Experimental
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#SourceFile"
|
|
REL="Help"
|
|
><STRONG>Source File:</STRONG></A> mod_auth_digest.c
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#ModuleIdentifier"
|
|
REL="Help"
|
|
><STRONG>Module Identifier:</STRONG></A> digest_auth_module
|
|
</P>
|
|
|
|
<h2>Summary</h2>
|
|
|
|
<P>This is an updated version of <A
|
|
HREF="mod_digest.html">mod_digest</A>. However, it has not been
|
|
extensively tested and is therefore marked experimental. If you use
|
|
this module, you must make sure to <em>not</em> use mod_digest
|
|
(because they share some of the same configuration directives).
|
|
|
|
<h2>Directives</h2>
|
|
|
|
<ul>
|
|
<LI><A HREF="#authdigestfile">AuthDigestFile</A>
|
|
<LI><A HREF="#authdigestgroupfile">AuthDigestGroupFile</A>
|
|
<LI><A HREF="#authdigestqop">AuthDigestQop</A>
|
|
<LI><A HREF="#authdigestnoncelifetime">AuthDigestNonceLifetime</A>
|
|
<LI><A HREF="#authdigestnonceformat">AuthDigestNonceFormat</A>
|
|
<LI><A HREF="#authdigestnccheck">AuthDigestNcCheck</A>
|
|
<LI><A HREF="#authdigestalgorithm">AuthDigestAlgorithm</A>
|
|
<LI><A HREF="#authdigestdomain">AuthDigestDomain</A>
|
|
</ul>
|
|
|
|
<p>See also: <a href="core.html#require">Require</a> and
|
|
<a href="core.html#satisfy">Satisfy</a>.
|
|
|
|
<H3><A NAME="usingdigest">Using Digest Authentication</A></H3>
|
|
|
|
<P>Using MD5 Digest authentication is very simple. Simply set up
|
|
authentication normally, using "AuthType Digest" and "AuthDigestFile"
|
|
instead of the normal "AuthType Basic" and "AuthUserFile"; also,
|
|
replace any "AuthGroupFile" with "AuthDigestGroupFile". Then add a
|
|
"AuthDigestDomain" directive containing at least the root URI(s) for
|
|
this protection space. Example:
|
|
|
|
<PRE>
|
|
<Location /private/>
|
|
AuthType Digest
|
|
AuthName "private area"
|
|
AuthDigestDomain /private/ http://mirror.my.dom/private2/
|
|
AuthDigestFile /web/auth/.digest_pw
|
|
Require valid-user
|
|
</Location>
|
|
</PRE>
|
|
|
|
<P><strong>Note:</strong> MD5 authentication provides a more secure
|
|
password system than Basic authentication, but only works with supporting
|
|
browsers. As of this writing (July 1999), the only major browsers which
|
|
support digest authentication are <A
|
|
HREF="http://www.microsoft.com/windows/ie/">Internet Explorer 5.0</A> and
|
|
<A HREF="http://www.w3.org/Amaya/">Amaya</A>. Therefore, we do not
|
|
recommend using this feature on a large Internet site. However, for
|
|
personal and intra-net use, where browser users can be controlled, it is
|
|
ideal.
|
|
|
|
|
|
<HR>
|
|
|
|
|
|
|
|
|
|
<H2><A NAME="authdigestfile">AuthDigestFile</A> directive</H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> AuthDigestFile <EM>filename</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> AuthConfig<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Experimental<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_auth_digest<BR>
|
|
|
|
<P>The AuthDigestFile directive sets the name of a textual file containing
|
|
the list of users and encoded passwords for digest authentication.
|
|
<EM>Filename</EM> is the absolute path to the user file.
|
|
|
|
<P>The digest file uses a special format. Files in this format can be
|
|
created using the <a href="../programs/htdigest.html">htdigest</a>
|
|
utility found in the support/ subdirectory of the Apache distribution.
|
|
|
|
<HR>
|
|
|
|
<H2><A NAME="authdigestgroupfile">AuthDigestGroupFile</A> directive</H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> AuthDigestGroupFile <EM>filename</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> AuthConfig<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Experimental<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_auth_digest
|
|
|
|
<P>The AuthDigestGroupFile directive sets the name of a textual file
|
|
containing the list of groups and their members (user names).
|
|
<EM>Filename</EM> is the absolute path to the group file.
|
|
|
|
<P>Each line of the group file contains a groupname followed by a colon,
|
|
followed by the member usernames separated by spaces. Example:
|
|
<BLOCKQUOTE><CODE>mygroup: bob joe anne</CODE></BLOCKQUOTE>
|
|
Note that searching large text files is <EM>very</EM> inefficient.
|
|
|
|
<P>Security: make sure that the AuthGroupFile is stored outside the
|
|
document tree of the web-server; do <EM>not</EM> put it in the directory
|
|
that it protects. Otherwise, clients will be able to download the
|
|
AuthGroupFile.
|
|
|
|
<HR>
|
|
|
|
<H2><A NAME="authdigestqop">AuthDigestQop</A> directive</H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> AuthDigestQop none|auth|auth-int
|
|
[auth|auth-int]<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> <CODE>AuthDigestQop auth</CODE><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> AuthConfig<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Experimental<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_auth_digest
|
|
|
|
<P>The AuthDigestQop directive determines the quality-of-protection to use.
|
|
<EM>auth</EM> will only do authentication (username/password);
|
|
<EM>auth-int</EM> is authentication plus integrity checking (an MD5 hash
|
|
of the entity is also computed and checked); <EM>none</EM> will cause the
|
|
module to use the old RFC-2069 digest algorithm (which does not include
|
|
integrity checking). Both <EM>auth</em> and <EM>auth-int</EM> may be
|
|
specified, in which the case the browser will choose which of these to
|
|
use. <EM>none</EM> should only be used if the browser for some reason
|
|
does not like the challenge it receives otherwise.
|
|
|
|
<P><STRONG><EM>auth-int</EM> is not implemented yet</STRONG>.
|
|
|
|
<HR>
|
|
|
|
<H2><A NAME="authdigestnoncelifetime">AuthDigestNonceLifetime</A>
|
|
directive</H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> AuthDigestNonceLifetime <EM>seconds</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> <CODE>AuthDigestNonceLifetime 300</CODE><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> AuthConfig<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Experimental<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_auth_digest
|
|
|
|
<P>The AuthDigestNonceLifetime directive controls how long the server
|
|
nonce is valid. When the client contacts the server using an expired
|
|
nonce the server will send back a 401 with <code>stale=true</code>. If
|
|
<EM>seconds</EM> 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. If <EM>seconds</EM> is less than 0 then
|
|
the nonce never expires.
|
|
|
|
<!-- Not implemented yet
|
|
If <EM>seconds</EM> is 0 then the nonce may be used exactly once
|
|
by the client. Note that while one-time-nonces provide higher security
|
|
against replay attacks, they also have significant performance
|
|
implications, as the browser cannot pipeline or multiple connections
|
|
for the requests. Because browsers cannot easily detect that
|
|
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 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.
|
|
-->
|
|
|
|
<HR>
|
|
<H2><A NAME="authdigestnonceformat">AuthDigestNonceFormat</A> directive</H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> AuthDigestNonceFormat <EM>???</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> <CODE>AuthDigestNonceFormat ???</CODE><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> AuthConfig<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Experimental<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_auth_digest
|
|
|
|
<P><STRONG>Not implemented yet.</STRONG>
|
|
<!--
|
|
<P>The AuthDigestNonceFormat directive determines how the nonce is
|
|
generated.
|
|
-->
|
|
|
|
<HR>
|
|
<H2><A NAME="authdigestnccheck">AuthDigestNcCheck</A> directive</H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> AuthDigestNcCheck On|Off<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> <CODE>AuthDigestNcCheck Off</CODE><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Experimental<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_auth_digest
|
|
|
|
<P><STRONG>Not implemented yet.</STRONG>
|
|
<!--
|
|
<P>The AuthDigestNcCheck directive enables or disables the checking of the
|
|
nonce-count sent by the server.
|
|
|
|
<P>While recommended from a security standpoint, turning this directive
|
|
On has one important performance implication. To check the nonce-count
|
|
*all* requests (which have an Authorization header, irrespective of
|
|
whether they require digest authentication) must be serialized through
|
|
a critical section. If the server is handling a large number of
|
|
requests which contain the Authorization header then this may noticeably
|
|
impact performance.
|
|
-->
|
|
|
|
<HR>
|
|
<H2><A NAME="authdigestalgorithm">AuthDigestAlgorithm</A> directive</H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> AuthDigestAlgorithm MD5|MD5-sess<BR>
|
|
<A
|
|
HREF="directive-dict.html#Default"
|
|
REL="Help"
|
|
><STRONG>Default:</STRONG></A> <CODE>AuthDigestAlgorithm MD5</CODE><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> AuthConfig<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Experimental<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_auth_digest
|
|
|
|
<P>The AuthDigestAlgorithm directive selects the algorithm used to calculate
|
|
the challenge and response hashes.
|
|
|
|
<P><STRONG><EM>MD5-sess</EM> is not correctly implemented yet</STRONG>.
|
|
<!--
|
|
<P>To use <EM>MD5-sess</EM> you must first code up the
|
|
<VAR>get_userpw_hash()</VAR> function in <VAR>mod_auth_digest.c</VAR> .
|
|
-->
|
|
|
|
<HR>
|
|
<H2><A NAME="authdigestdomain">AuthDigestDomain</A> directive</H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> AuthDigestDomain <EM>URI</em>
|
|
[<em>URI</em>] ...<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> AuthConfig<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Experimental<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_auth_digest
|
|
|
|
<P>The AuthDigestDomain directive allows you to specify one or more URIs
|
|
which are in the same protection space (i.e. use the same realm and
|
|
username/password info). The specified URIs are prefixes, i.e. the client
|
|
will assume that all URIs "below" these are also protected by the same
|
|
username/password. The URIs may be either absolute URIs (i.e. inluding a
|
|
scheme, host, port, etc) or relative URIs.
|
|
|
|
<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 "AuthDigestNcCheck" is on.
|
|
|
|
<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.
|
|
|
|
|
|
<!--#include virtual="footer.html" -->
|
|
</BODY>
|
|
</HTML>
|
|
|