From: Rainer Jung Date: Wed, 12 Dec 2012 14:13:44 +0000 (+0000) Subject: Docs update concerning recent htpasswd and htdbm X-Git-Tag: 2.5.0-alpha~6021 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=902fbd0c27de22e47bbfa5234686f6150505ebf9;p=apache Docs update concerning recent htpasswd and htdbm additions. Add some cross refernces between dbmmanage and htdbm. Update man page for htdbm and htpasswd. Add bcrypt info to misc/password_encryptions. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1420686 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/misc/password_encryptions.xml b/docs/manual/misc/password_encryptions.xml index fa6fc4e4ea..63df11a8dc 100644 --- a/docs/manual/misc/password_encryptions.xml +++ b/docs/manual/misc/password_encryptions.xml @@ -32,20 +32,15 @@
Basic Authentication -

There are four formats that Apache recognizes for basic-authentication +

There are five formats that Apache recognizes for basic-authentication passwords. Note that not all formats work on every platform:

-
PLAIN TEXT (i.e. unencrypted)
-
Windows & Netware only.
- -
CRYPT
-
Unix only. Uses the traditional Unix crypt(3) function - with a randomly-generated 32-bit salt (only 12 bits used) and the first 8 - characters of the password.
- -
SHA1
-
"{SHA}" + Base64-encoded SHA-1 digest of the password.
+
bcrypt
+
"$2y$" + the result of the crypt_blowfish algorithm. + See the APR source file + crypt_blowfish.c + for the details of the algorithm.
MD5
"$apr1$" + the result of an Apache-specific algorithm using an @@ -53,10 +48,26 @@ random 32-bit salt and the password. See the APR source file apr_md5.c for the details of the algorithm.
+ +
SHA1
+
"{SHA}" + Base64-encoded SHA-1 digest of the password. Insecure.
+ +
CRYPT
+
Unix only. Uses the traditional Unix crypt(3) function + with a randomly-generated 32-bit salt (only 12 bits used) and the first 8 + characters of the password. Insecure.
+ +
PLAIN TEXT (i.e. unencrypted)
+
Windows & Netware only. Insecure.
Generating values with htpasswd + bcrypt + $ htpasswd -nbB myName myPassword
+ myName:$2y$05$c4WoMPo3SXsafkva.HHa6uXQZWr7oboPiC2bT/r7q1BB8I2s0BRqC + + MD5 $ htpasswd -nbm myName myPassword
myName:$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/ diff --git a/docs/manual/mod/mod_authn_dbm.xml b/docs/manual/mod/mod_authn_dbm.xml index 37989c3be0..6721ba8170 100644 --- a/docs/manual/mod/mod_authn_dbm.xml +++ b/docs/manual/mod/mod_authn_dbm.xml @@ -51,6 +51,8 @@ AuthDigestProvider +htpasswd +htdbm Password Formats @@ -98,7 +100,9 @@ passwords for authentication

A perl script called dbmmanage is included with Apache. This program can be used to create and update DBM - format password files for use with this module.

+ format password files for use with this module. Another + tool for maintaining the DBM files is the included program + htdbm.

 diff --git a/docs/manual/programs/dbmmanage.xml b/docs/manual/programs/dbmmanage.xml index f3d1d38063..b40fbe0d9f 100644 --- a/docs/manual/programs/dbmmanage.xml +++ b/docs/manual/programs/dbmmanage.xml @@ -34,6 +34,9 @@ program can only be used when the usernames are stored in a DBM file. To use a flat-file database see htpasswd.

+

Another tool to maintain a DBM password database is + htdbm.

+

This manual page only lists the command line arguments. For details of the directives necessary to configure user authentication in httpd see the httpd manual, which is part of @@ -41,6 +44,7 @@ href="http://httpd.apache.org/">http://httpd.apache.org/.

httpd +htdbm mod_authn_dbm mod_authz_dbm diff --git a/docs/manual/programs/htdbm.xml b/docs/manual/programs/htdbm.xml index 5cc2c313de..79d08b6f84 100644 --- a/docs/manual/programs/htdbm.xml +++ b/docs/manual/programs/htdbm.xml @@ -38,33 +38,40 @@
Synopsis

htdbm [ -TDBTYPE ] + [ -i ] [ -c ] [ -m | + -B | -d | - -p | - -s ] + -s | + -p ] + [ -C cost ] [ -t ] [ -v ] - [ -x ] filename username

htdbm -b [ -TDBTYPE ] [ -c ] [ -m | + -B | -d | - -p | - -s ] + -s | + -p ] + [ -C cost ] [ -t ] [ -v ] filename username password

htdbm -n + [ -i ] [ -c ] [ -m | + -B | -d | - -p | - -s ] + -s | + -p ] + [ -C cost ] [ -t ] [ -v ] username

@@ -72,20 +79,25 @@

htdbm -nb [ -c ] [ -m | + -B | -d | - -p | - -s ] + -s | + -p ] + [ -C cost ] [ -t ] [ -v ] username password

htdbm -v [ -TDBTYPE ] + [ -i ] [ -c ] [ -m | + -B | -d | - -p | - -s ] + -s | + -p ] + [ -C cost ] [ -t ] [ -v ] filename username

@@ -94,19 +106,17 @@ [ -TDBTYPE ] [ -c ] [ -m | + -B | -d | - -p | - -s ] + -s | + -p ] + [ -C cost ] [ -t ] [ -v ] filename username password

htdbm -x [ -TDBTYPE ] - [ -m | - -d | - -p | - -s ] filename username

htdbm -l @@ -120,7 +130,10 @@

Use batch mode; i.e., get the password from the command line rather than prompting for it. This option should be used with extreme care, since the password is clearly visible on the command - line.
+ line. For script use see the -i option. + +
-i
+
Read the password from stdin without verification (for script usage).
-c
Create the passwdfile. If passwdfile already @@ -137,15 +150,26 @@
Use MD5 encryption for passwords. On Windows and Netware, this is the default.
+
-B
+
Use bcrypt encryption for passwords. This is currently considered to + be very secure.
+ +
-C
+
This flag is only allowed in combination with -B (bcrypt + encryption). It sets the computing time used for the bcrypt algorithm + (higher is more secure but slower, default: 5, valid: 4 to 31).
+
-d
Use crypt() encryption for passwords. The default on all platforms but Windows and Netware. Though possibly supported by htdbm on all platforms, it is not supported by the - httpd server on Windows and Netware.
+ httpd server on Windows and Netware. + This algorithm is insecure by today's standards.
-s
Use SHA encryption for passwords. Facilitates migration from/to Netscape - servers using the LDAP Directory Interchange Format (ldif).
+ servers using the LDAP Directory Interchange Format (ldif). + This algorithm is insecure by today's standards.
-p
Use plaintext passwords. Though htdbm will support @@ -156,12 +180,6 @@
Print each of the usernames and comments from the database on stdout.
-
-t
-
Interpret the final parameter as a comment. When this option is - specified, an additional string can be appended to the command line; this - string will be stored in the "Comment" field of the database, associated - with the specified username.
-
-v
Verify the username and password. The program will print a message indicating whether the supplied password is valid. If the password is @@ -171,6 +189,12 @@
Delete user. If the username exists in the specified DBM file, it will be deleted.
+
-t
+
Interpret the final parameter as a comment. When this option is + specified, an additional string can be appended to the command line; this + string will be stored in the "Comment" field of the database, associated + with the specified username.
+
filename
The filename of the DBM format file. Usually without the extension .db, .pag, or .dir. If @@ -257,6 +281,18 @@

The use of the -b option is discouraged, since when it is used the unencrypted password appears on the command line.

+ +

When using the crypt() algorithm, note that only the first + 8 characters of the password are used to form the password. If the supplied + password is longer, the extra characters will be silently discarded.

+ +

The SHA encryption format does not use salting: for a given password, + there is only one encrypted representation. The crypt() and + MD5 formats permute the representation by prepending a random salt string, + to make dictionary attacks against the passwords more difficult.

+ +

The SHA and crypt() formats are insecure by today's + standards.

Restrictions diff --git a/docs/manual/programs/htpasswd.xml b/docs/manual/programs/htpasswd.xml index b254e141d4..adf3348540 100644 --- a/docs/manual/programs/htpasswd.xml +++ b/docs/manual/programs/htpasswd.xml @@ -36,13 +36,16 @@ just the users listed in the files created by htpasswd. This program can only manage usernames and passwords stored in a flat-file. It can encrypt and display password information for use in other types of data - stores, though. To use a DBM database see dbmmanage.

+ stores, though. To use a DBM database see dbmmanage or + htdbm.

-

htpasswd encrypts passwords using either a version of MD5 - modified for Apache, or the system's crypt() routine. Files - managed by htpasswd may contain both types of passwords; some - user records may have MD5-encrypted passwords while others in the same file - may have passwords encrypted with crypt().

+

htpasswd encrypts passwords using either bcrypt, + a version of MD5 modified for Apache, SHA1, or the system's + crypt() routine. Files + managed by htpasswd may contain a mixture of different encoding + types of passwords; some + user records may have bcrypt or MD5-encrypted passwords while others in the + same file may have passwords encrypted with crypt().

This manual page only lists the command line arguments. For details of the directives necessary to configure user authentication in @@ -51,35 +54,50 @@ >http://httpd.apache.org/.

httpd +htdbm The scripts in support/SHA1 which come with the distribution.
Synopsis

htpasswd [ -c ] - [ -m ] - [ -D ] passwdfile username

+ [ -i ] + [ -m | + -B | + -d | + -s | + -p ] + [ -C cost ] + [ -D ] passwdfile username

htpasswd -b [ -c ] [ -m | + -B | -d | - -p | - -s ] + -s | + -p ] + [ -C cost ] [ -D ] passwdfile username password

htpasswd -n + [ -i ] [ -m | + -B | -d | -s | - -p ] username

+ -p ] + [ -C cost ] username

htpasswd -nb [ -m | + -B | -d | -s | - -p ] username password

+ -p ] + [ -C cost ] username + password

Options @@ -88,7 +106,10 @@ distribution.
Use batch mode; i.e., get the password from the command line rather than prompting for it. This option should be used with extreme care, since the password is clearly visible on the command - line.
+ line. For script use see the -i option. + +
-i
+
Read the password from stdin without verification (for script usage).
-c
Create the passwdfile. If passwdfile already @@ -105,6 +126,15 @@ distribution.
-m
Use MD5 encryption for passwords. This is the default.
+
-B
+
Use bcrypt encryption for passwords. This is currently considered to + be very secure.
+ +
-C
+
This flag is only allowed in combination with -B (bcrypt + encryption). It sets the computing time used for the bcrypt algorithm + (higher is more secure but slower, default: 5, valid: 4 to 31).
+
-d
Use crypt() encryption for passwords. This is not supported by the httpd server on Windows and