From 902fbd0c27de22e47bbfa5234686f6150505ebf9 Mon Sep 17 00:00:00 2001
From: Rainer Jung
Date: Wed, 12 Dec 2012 14:13:44 +0000
Subject: [PATCH] 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
---
docs/manual/misc/password_encryptions.xml | 33 ++++++---
docs/manual/mod/mod_authn_dbm.xml | 6 +-
docs/manual/programs/dbmmanage.xml | 4 ++
docs/manual/programs/htdbm.xml | 88 ++++++++++++++++-------
docs/manual/programs/htpasswd.xml | 56 +++++++++++----
5 files changed, 136 insertions(+), 51 deletions(-)
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
--
2.40.0