From 3b8f5243f158e915579a49835d29b4abdd1dccad Mon Sep 17 00:00:00 2001 From: Joshua Slive Date: Thu, 28 Feb 2002 19:20:22 +0000 Subject: [PATCH] New xml mod_auth_digest docs. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@93649 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_auth_digest.html | 855 ++++++++++++++++----------- docs/manual/mod/mod_auth_digest.xml | 270 +++++++++ 2 files changed, 792 insertions(+), 333 deletions(-) create mode 100644 docs/manual/mod/mod_auth_digest.xml diff --git a/docs/manual/mod/mod_auth_digest.html b/docs/manual/mod/mod_auth_digest.html index cb4dcc26e9..26d5570c6f 100644 --- a/docs/manual/mod/mod_auth_digest.html +++ b/docs/manual/mod/mod_auth_digest.html @@ -1,89 +1,129 @@ - - - - - - - Apache module mod_auth_digest - - - - - - -

Module mod_auth_digest

- -

This module provides for user authentication using MD5 - Digest Authentication.

- -

Status: Experimental
- Source File: - mod_auth_digest.c
- Module Identifier: - auth_digest_module

- -

Summary

- -

This is an updated version of mod_digest. However, it has not been - extensively tested and is therefore marked experimental. If you - use this module, you must make sure to not use - mod_digest (because they share some of the same configuration - directives).

- -

Directives

- -

AuthDigestFile
AuthDigestGroupFile
AuthDigestQop
AuthDigestNonceLifetime
AuthDigestNonceFormat
AuthDigestNcCheck
AuthDigestAlgorithm
AuthDigestDomain

- -

See also: Require and Satisfy.

- -

Using Digest - Authentication

- -

Using MD5 Digest authentication is very simple. Simply set + + + + +mod_auth_digest - Apache HTTP Server + + + +

+
+
Apache HTTP Server Version 2.0
+
+
Apache Module mod_auth_digest
+ + + + +
+ + + + + + + + + + +
Description: +User authentication using MD5 + Digest Authentication. +
Status: Experimental
Module Identifier: auth_digest_module
+
+
Summary
+
+ +
This module implements HTTP Digest Authentication. However, it + has not been extensively tested and is therefore marked + experimental.
+ +
+
+See also: +
+
+
+AuthName +
+
+AuthType +
+
+Require +
+
+Satisfy +
+
+
Directives
+
+
+AuthDigestAlgorithm +
+
+AuthDigestDomain +
+
+AuthDigestFile +
+
+AuthDigestGroupFile +
+
+AuthDigestNcCheck +
+
+AuthDigestNonceFormat +
+
+AuthDigestNonceLifetime +
+
+AuthDigestQop +
+
+
Using Digest Authentication
+ + +
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:
-
-  <Location /private/>
-  AuthType Digest
-  AuthName "private area"
-  AuthDigestDomain /private/ http://mirror.my.dom/private2/
-  AuthDigestFile /web/auth/.digest_pw
-  Require valid-user
-  </Location>
-
-
Note: MD5 authentication provides a more +
+ + + + +
+ <Location /private/> + AuthType Digest + AuthName "private area" + AuthDigestDomain /private/ http://mirror.my.dom/private2/ + AuthDigestFile /web/auth/.digest_pw + Require valid-user + </Location> +
+
+ + +
+ + + + +
+
+Note +
+ +
MD5 authentication provides a more secure password system than Basic authentication, but only works with supporting browsers. As of this writing (October 2001), the only major browsers which support digest authentication are @@ -93,275 +133,424 @@ Therefore, we do not yet 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.
-
-
AuthDigestFile directive
- Syntax: AuthDigestFile - file-path
- Context: directory, - .htaccess
- Override: AuthConfig
- Status: Experimental
- Module: mod_auth_digest
- +
+
+ +
+
+AuthDigestAlgorithm Directive +
+ + + + +
+ + + + + + + + + + + + + + + + + + + + + + +
Description: Selects the algorithm used to calculate the challenge and +response hases in digest authentication
Syntax: +AuthDigestAlgorithm MD5|MD5-sess +
Default: AuthDigestAlgorithm MD5
Context: directory, .htaccess
Override: AuthConfig
Status: Experimental
Module: mod_auth_digest
+
+ + +
The AuthDigestAlgorithm directive + selects the algorithm used to calculate the challenge and response + hashes.
+ + +
+MD5-sess is not correctly implemented + yet. +
-
The AuthDigestFile directive sets the name of a textual file - containing the list of users and encoded passwords for digest - authentication. File-path is the absolute path to the - user file.
+ +
+
+AuthDigestDomain Directive +
+ + + + +
+ + + + + + + + + + + + + + + + + + + +
Description: URIs that are in the same protection space for digest +authentication
Syntax: +AuthDigestDomain URI [URI] ... +
Context: directory, .htaccess
Override: AuthConfig
Status: Experimental
Module: mod_auth_digest
+
+ + +
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.
+ + +
This directive should 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 every request 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.
-
The digest file uses a special format. Files in this format - can be created using the htdigest utility found in + +
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.
+ + +
+
+AuthDigestFile Directive +
+ + + + +
+ + + + + + + + + + + + + + + + + + + +
Description: Location of the text file containing the list +of users and encoded passwords for digest authentication
Syntax: +AuthDigestFile file-path + +
Context: directory, .htaccess
Override: AuthConfig
Status: Experimental
Module: mod_auth_digest
+
+ + +
The AuthDigestFile directive sets the + name of a textual file containing the list of users and encoded + passwords for digest authentication. File-path is the + absolute path to the user file.
+ + +
The digest file uses a special format. Files in this format + can be created using the htdigest utility found in the support/ subdirectory of the Apache distribution.
-
- -
AuthDigestGroupFile - directive
- Syntax: AuthDigestGroupFile - file-path
- Context: directory, - .htaccess
- Override: AuthConfig
- Status: Experimental
- Module: mod_auth_digest -
The AuthDigestGroupFile directive sets the name of a textual - file containing the list of groups and their members (user - names). File-path is the absolute path to the group - file.
- -
Each line of the group file contains a groupname followed by + +
+
+AuthDigestGroupFile Directive +
+ + + + +
+ + + + + + + + + + + + + + + + + + + +
Description: Name of the text file containing the list of groups +for digest authentication
Syntax: +AuthDigestGroupFile file-path + +
Context: directory, .htaccess
Override: AuthConfig
Status: Experimental
Module: mod_auth_digest
+
+ + +
The AuthDigestGroupFile directive sets + the name of a textual file containing the list of groups and their + members (user names). File-path is the absolute path to + the group file.
+ + +
Each line of the group file contains a groupname followed by a colon, followed by the member usernames separated by spaces. Example:
-
- mygroup: bob joe anne -
- Note that searching large text files is very - inefficient. -
Security: make sure that the AuthGroupFile is stored outside +
+ + + + +
mygroup: bob joe anne
+
+ + +
Note that searching large text files is very + inefficient.
+ + +
Security: make sure that the AuthGroupFile is stored outside the document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthGroupFile.
-
-
AuthDigestQop directive
- Syntax: AuthDigestQop - none|auth|auth-int [auth|auth-int]
- Default: AuthDigestQop - auth
- Context: directory, - .htaccess
- Override: AuthConfig
- Status: Experimental
- Module: mod_auth_digest + +
+
+AuthDigestNcCheck Directive +
+ + + + +
+ + + + + + + + + + + + + + + + + + + +
Description: Enables or disables checking of the nonce-count sent by the +server
Syntax: +AuthDigestNcCheck On|Off +
Default: AuthDigestNcCheck Off
Context: server config
Status: Experimental
Module: mod_auth_digest
+
+ + +
+Not implemented yet. + +
+ + +
+
+AuthDigestNonceFormat Directive +
+ + + + +
+ + + + + + + + + + + + + + + + + + + + + + +
Description: Determines how the nonce is generated
Syntax: +??? +
Default: ???
Context: directory, .htaccess
Override: AuthConfig
Status: Experimental
Module: mod_auth_digest
+
+ + +
+Not implemented yet. + +
+ + +
+
+AuthDigestNonceLifetime Directive +
+ + + + +
+ + + + + + + + + + + + + + + + + + + + + + +
Description: How long the server nonce is valid
Syntax: +AuthDigestNonceLifetime seconds + +
Default: AuthDigestNonceLifetime 300
Context: directory, .htaccess
Override: AuthConfig
Status: Experimental
Module: mod_auth_digest
+
+ + +
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 stale=true. If seconds 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 seconds is less than 0 then the nonce never + expires. +
-
The AuthDigestQop directive determines the - quality-of-protection to use. auth will only do + +
+
+AuthDigestQop Directive +
+ + + + +
+ + + + + + + + + + + + + + + + + + + + + + +
Description: Determines the quality-of-protection to use in digest +authentication
Syntax: +AuthDigestQop none|auth|auth-int [auth|auth-int] +
Default: AuthDigestQop auth
Context: directory, .htaccess
Override: AuthConfig
Status: Experimental
Module: mod_auth_digest
+
+ + +
The AuthDigestQop directive determines + the quality-of-protection to use. auth will only do authentication (username/password); auth-int is - authentication plus integrity checking (an MD5 hash of the - entity is also computed and checked); none will cause - the module to use the old RFC-2069 digest algorithm (which does - not include integrity checking). Both auth and - auth-int may be specified, in which the case the - browser will choose which of these to use. none should - only be used if the browser for some reason does not like the - challenge it receives otherwise.
- -
auth-int is not implemented + authentication plus integrity checking (an MD5 hash of the entity + is also computed and checked); none will cause the module + to use the old RFC-2069 digest algorithm (which does not include + integrity checking). Both auth and auth-int may + be specified, in which the case the browser will choose which of + these to use. none should only be used if the browser for + some reason does not like the challenge it receives otherwise.
+ + +
+auth-int is not implemented yet.
-
- -
AuthDigestNonceLifetime - directive
- Syntax: AuthDigestNonceLifetime - seconds
- Default: - AuthDigestNonceLifetime 300
- Context: directory, - .htaccess
- Override: AuthConfig
- Status: Experimental
- Module: mod_auth_digest - -
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 - stale=true. If seconds 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 seconds is less than 0 then the nonce - never expires. -
-
- -
AuthDigestNonceFormat - directive
- Syntax: AuthDigestNonceFormat - ???
- Default: - AuthDigestNonceFormat ???
- Context: directory, - .htaccess
- Override: AuthConfig
- Status: Experimental
- Module: mod_auth_digest - -
Not implemented yet. -
-
- -
AuthDigestNcCheck directive
- Syntax: AuthDigestNcCheck - On|Off
- Default: - AuthDigestNcCheck Off
- Context: server config
- Override: Not - applicable
- Status: Experimental
- Module: mod_auth_digest - -
Not implemented yet. -
-
- -
AuthDigestAlgorithm - directive
- Syntax: AuthDigestAlgorithm - MD5|MD5-sess
- Default: - AuthDigestAlgorithm MD5
- Context: directory, - .htaccess
- Override: AuthConfig
- Status: Experimental
- Module: mod_auth_digest -
The AuthDigestAlgorithm directive selects the algorithm used - to calculate the challenge and response hashes.
- -
MD5-sess is not correctly implemented - yet. -
-
- -
AuthDigestDomain directive
- Syntax: AuthDigestDomain - URI [URI] ...
- Context: directory, - .htaccess
- Override: AuthConfig
- Status: Experimental
- Module: mod_auth_digest - -
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.
- -
This directive should 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 every request 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.
- -
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. - -
- + +
+
Apache HTTP Server Version 2.0
+ +

+ - diff --git a/docs/manual/mod/mod_auth_digest.xml b/docs/manual/mod/mod_auth_digest.xml new file mode 100644 index 0000000000..3d3c544278 --- /dev/null +++ b/docs/manual/mod/mod_auth_digest.xml @@ -0,0 +1,270 @@ + + + +mod_auth_digest +User authentication using MD5 + Digest Authentication. +Experimental +mod_auth_digest.c +auth_digest_module + +
+
This module implements HTTP Digest Authentication. However, it + has not been extensively tested and is therefore marked + experimental.
+
+ +AuthName +AuthType +Require +Satisfy + +
Using Digest Authentication + +
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:
+ + <Location /private/>
+ AuthType Digest
+ AuthName "private area"
+ AuthDigestDomain /private/ http://mirror.my.dom/private2/
+ AuthDigestFile /web/auth/.digest_pw
+ Require valid-user
+ </Location> + + +Note +
MD5 authentication provides a more + secure password system than Basic authentication, but only + works with supporting browsers. As of this writing (October 2001), + the only major browsers which support digest authentication are + Opera 4.0, + MS Internet + Explorer 5.0 and Amaya. + Therefore, we do not yet 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.
+ +
+ + +AuthDigestFile +Location of the text file containing the list +of users and encoded passwords for digest authentication +AuthDigestFile file-path +directory.htaccess + +AuthConfig + + +
The AuthDigestFile directive sets the + name of a textual file containing the list of users and encoded + passwords for digest authentication. File-path is the + absolute path to the user file.
+ +
The digest file uses a special format. Files in this format + can be created using the htdigest utility found in + the support/ subdirectory of the Apache distribution.
+ + + + +AuthDigestGroupFile +Name of the text file containing the list of groups +for digest authentication +AuthDigestGroupFile file-path +directory.htaccess + +AuthConfig + + +
The AuthDigestGroupFile directive sets + the name of a textual file containing the list of groups and their + members (user names). File-path is the absolute path to + the group file.
+ +
Each line of the group file contains a groupname followed by + a colon, followed by the member usernames separated by spaces. + Example:
+ +mygroup: bob joe anne + +
Note that searching large text files is very + inefficient.
+ +
Security: make sure that the AuthGroupFile is stored outside + the document tree of the web-server; do not put it in + the directory that it protects. Otherwise, clients will be able + to download the AuthGroupFile.
+ + + + +AuthDigestQop +Determines the quality-of-protection to use in digest +authentication +AuthDigestQop none|auth|auth-int [auth|auth-int] +AuthDigestQop auth +directory.htaccess + +AuthConfig + + +
The AuthDigestQop directive determines + the quality-of-protection to use. auth will only do + authentication (username/password); auth-int is + authentication plus integrity checking (an MD5 hash of the entity + is also computed and checked); none will cause the module + to use the old RFC-2069 digest algorithm (which does not include + integrity checking). Both auth and auth-int may + be specified, in which the case the browser will choose which of + these to use. none should only be used if the browser for + some reason does not like the challenge it receives otherwise.
+ +
auth-int is not implemented + yet.
+ + + + +AuthDigestNonceLifetime +How long the server nonce is valid +AuthDigestNonceLifetime seconds +AuthDigestNonceLifetime 300 +directory.htaccess + +AuthConfig + + +
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 stale=true. If seconds 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 seconds is less than 0 then the nonce never + expires. +
+ + + + +AuthDigestNonceFormat +Determines how the nonce is generated +??? +??? +directory.htaccess + +AuthConfig + + +
Not implemented yet. +
+ + + + +AuthDigestNcCheck +Enables or disables checking of the nonce-count sent by the +server +AuthDigestNcCheck On|Off +AuthDigestNcCheck Off +server config + + +
Not implemented yet. +
+ + + + +AuthDigestAlgorithm +Selects the algorithm used to calculate the challenge and +response hases in digest authentication +AuthDigestAlgorithm MD5|MD5-sess +AuthDigestAlgorithm MD5 +directory.htaccess + +AuthConfig + + +
The AuthDigestAlgorithm directive + selects the algorithm used to calculate the challenge and response + hashes.
+ +
MD5-sess is not correctly implemented + yet. +
+ + + + +AuthDigestDomain +URIs that are in the same protection space for digest +authentication +AuthDigestDomain URI [URI] ... +directory.htaccess + +AuthConfig + + +
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.
+ +
This directive should 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 every request 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.
+ +
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.
+ + + + + -- 2.50.1