You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by rj...@apache.org on 2012/12/12 16:05:33 UTC
svn commit: r1420732 - in /httpd/httpd/branches/2.4.x: ./ docs/manual/
docs/manual/misc/ docs/manual/mod/ docs/manual/programs/
Author: rjung
Date: Wed Dec 12 15:05:27 2012
New Revision: 1420732
URL: http://svn.apache.org/viewvc?rev=1420732&view=rev
Log:
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.
Backport of r1420686 from turnk.
Modified:
httpd/httpd/branches/2.4.x/ (props changed)
httpd/httpd/branches/2.4.x/docs/manual/ (props changed)
httpd/httpd/branches/2.4.x/docs/manual/misc/password_encryptions.xml
httpd/httpd/branches/2.4.x/docs/manual/mod/ (props changed)
httpd/httpd/branches/2.4.x/docs/manual/mod/mod_authn_dbm.xml
httpd/httpd/branches/2.4.x/docs/manual/programs/dbmmanage.xml
httpd/httpd/branches/2.4.x/docs/manual/programs/htdbm.xml
httpd/httpd/branches/2.4.x/docs/manual/programs/htpasswd.xml
Propchange: httpd/httpd/branches/2.4.x/
------------------------------------------------------------------------------
Merged /httpd/httpd/trunk:r1420686
Propchange: httpd/httpd/branches/2.4.x/docs/manual/
------------------------------------------------------------------------------
Merged /httpd/httpd/trunk/docs/manual:r1420686
Modified: httpd/httpd/branches/2.4.x/docs/manual/misc/password_encryptions.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/misc/password_encryptions.xml?rev=1420732&r1=1420731&r2=1420732&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/misc/password_encryptions.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/misc/password_encryptions.xml Wed Dec 12 15:05:27 2012
@@ -32,20 +32,15 @@
<section id="basic"><title>Basic Authentication</title>
- <p>There are four formats that Apache recognizes for basic-authentication
+ <p>There are five formats that Apache recognizes for basic-authentication
passwords. Note that not all formats work on every platform:</p>
<dl>
- <dt>PLAIN TEXT (i.e. <em>unencrypted</em>)</dt>
- <dd>Windows & Netware only.</dd>
-
- <dt>CRYPT</dt>
- <dd>Unix only. Uses the traditional Unix <code>crypt(3)</code> function
- with a randomly-generated 32-bit salt (only 12 bits used) and the first 8
- characters of the password.</dd>
-
- <dt>SHA1</dt>
- <dd>"{SHA}" + Base64-encoded SHA-1 digest of the password.</dd>
+ <dt>bcrypt</dt>
+ <dd>"$2y$" + the result of the crypt_blowfish algorithm.
+ See the APR source file
+ <a href="http://svn.apache.org/viewvc/apr/apr/trunk/crypto/crypt_blowfish.c?view=markup">crypt_blowfish.c</a>
+ for the details of the algorithm.</dd>
<dt>MD5</dt>
<dd>"$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
<a href="http://svn.apache.org/viewvc/apr/apr/trunk/crypto/apr_md5.c?view=markup">apr_md5.c</a>
for the details of the algorithm.</dd>
+
+ <dt>SHA1</dt>
+ <dd>"{SHA}" + Base64-encoded SHA-1 digest of the password. Insecure.</dd>
+
+ <dt>CRYPT</dt>
+ <dd>Unix only. Uses the traditional Unix <code>crypt(3)</code> function
+ with a randomly-generated 32-bit salt (only 12 bits used) and the first 8
+ characters of the password. Insecure.</dd>
+
+ <dt>PLAIN TEXT (i.e. <em>unencrypted</em>)</dt>
+ <dd>Windows & Netware only. Insecure.</dd>
</dl>
<section><title>Generating values with htpasswd</title>
+ <example><title>bcrypt</title>
+ $ htpasswd -nbB myName myPassword<br />
+ myName:$2y$05$c4WoMPo3SXsafkva.HHa6uXQZWr7oboPiC2bT/r7q1BB8I2s0BRqC
+ </example>
+
<example><title>MD5</title>
$ htpasswd -nbm myName myPassword<br />
myName:$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/
Propchange: httpd/httpd/branches/2.4.x/docs/manual/mod/
------------------------------------------------------------------------------
Merged /httpd/httpd/trunk/docs/manual/mod:r1420686
Modified: httpd/httpd/branches/2.4.x/docs/manual/mod/mod_authn_dbm.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/mod/mod_authn_dbm.xml?rev=1420732&r1=1420731&r2=1420732&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/mod/mod_authn_dbm.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/mod/mod_authn_dbm.xml Wed Dec 12 15:05:27 2012
@@ -51,6 +51,8 @@
<seealso>
<directive module="mod_auth_digest">AuthDigestProvider</directive>
</seealso>
+<seealso><program>htpasswd</program></seealso>
+<seealso><program>htdbm</program></seealso>
<seealso><a href="../misc/password_encryptions.html">Password Formats</a></seealso>
<directivesynopsis>
@@ -98,7 +100,9 @@ passwords for authentication</descriptio
<p>A perl script called
<program>dbmmanage</program> is included with
Apache. This program can be used to create and update DBM
- format password files for use with this module.</p>
+ format password files for use with this module. Another
+ tool for maintaining the DBM files is the included program
+ <program>htdbm</program>.</p>
</usage>
</directivesynopsis>
Modified: httpd/httpd/branches/2.4.x/docs/manual/programs/dbmmanage.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/programs/dbmmanage.xml?rev=1420732&r1=1420731&r2=1420732&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/programs/dbmmanage.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/programs/dbmmanage.xml Wed Dec 12 15:05:27 2012
@@ -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 <program>htpasswd</program>.</p>
+ <p>Another tool to maintain a DBM password database is
+ <program>htdbm</program>.</p>
+
<p>This manual page only lists the command line arguments. For details of
the directives necessary to configure user authentication in
<program>httpd</program> see the httpd manual, which is part of
@@ -41,6 +44,7 @@
href="http://httpd.apache.org/">http://httpd.apache.org/</a>.</p>
</summary>
<seealso><program>httpd</program></seealso>
+<seealso><program>htdbm</program></seealso>
<seealso><module>mod_authn_dbm</module></seealso>
<seealso><module>mod_authz_dbm</module></seealso>
Modified: httpd/httpd/branches/2.4.x/docs/manual/programs/htdbm.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/programs/htdbm.xml?rev=1420732&r1=1420731&r2=1420732&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/programs/htdbm.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/programs/htdbm.xml Wed Dec 12 15:05:27 2012
@@ -38,33 +38,40 @@
<section id="synopsis"><title>Synopsis</title>
<p><code><strong>htdbm</strong>
[ -<strong>T</strong><var>DBTYPE</var> ]
+ [ -<strong>i</strong> ]
[ -<strong>c</strong> ]
[ -<strong>m</strong> |
+ -<strong>B</strong> |
-<strong>d</strong> |
- -<strong>p</strong> |
- -<strong>s</strong> ]
+ -<strong>s</strong> |
+ -<strong>p</strong> ]
+ [ -<strong>C</strong> <var>cost</var> ]
[ -<strong>t</strong> ]
[ -<strong>v</strong> ]
- [ -<strong>x</strong> ]
<var>filename</var> <var>username</var></code></p>
<p><code><strong>htdbm</strong> -<strong>b</strong>
[ -<strong>T</strong><var>DBTYPE</var> ]
[ -<strong>c</strong> ]
[ -<strong>m</strong> |
+ -<strong>B</strong> |
-<strong>d</strong> |
- -<strong>p</strong> |
- -<strong>s</strong> ]
+ -<strong>s</strong> |
+ -<strong>p</strong> ]
+ [ -<strong>C</strong> <var>cost</var> ]
[ -<strong>t</strong> ]
[ -<strong>v</strong> ]
<var>filename</var> <var>username</var> <var>password</var></code></p>
<p><code><strong>htdbm</strong> -<strong>n</strong>
+ [ -<strong>i</strong> ]
[ -<strong>c</strong> ]
[ -<strong>m</strong> |
+ -<strong>B</strong> |
-<strong>d</strong> |
- -<strong>p</strong> |
- -<strong>s</strong> ]
+ -<strong>s</strong> |
+ -<strong>p</strong> ]
+ [ -<strong>C</strong> <var>cost</var> ]
[ -<strong>t</strong> ]
[ -<strong>v</strong> ]
<var>username</var></code></p>
@@ -72,20 +79,25 @@
<p><code><strong>htdbm</strong> -<strong>nb</strong>
[ -<strong>c</strong> ]
[ -<strong>m</strong> |
+ -<strong>B</strong> |
-<strong>d</strong> |
- -<strong>p</strong> |
- -<strong>s</strong> ]
+ -<strong>s</strong> |
+ -<strong>p</strong> ]
+ [ -<strong>C</strong> <var>cost</var> ]
[ -<strong>t</strong> ]
[ -<strong>v</strong> ]
<var>username</var> <var>password</var></code></p>
<p><code><strong>htdbm</strong> -<strong>v</strong>
[ -<strong>T</strong><var>DBTYPE</var> ]
+ [ -<strong>i</strong> ]
[ -<strong>c</strong> ]
[ -<strong>m</strong> |
+ -<strong>B</strong> |
-<strong>d</strong> |
- -<strong>p</strong> |
- -<strong>s</strong> ]
+ -<strong>s</strong> |
+ -<strong>p</strong> ]
+ [ -<strong>C</strong> <var>cost</var> ]
[ -<strong>t</strong> ]
[ -<strong>v</strong> ]
<var>filename</var> <var>username</var></code></p>
@@ -94,19 +106,17 @@
[ -<strong>T</strong><var>DBTYPE</var> ]
[ -<strong>c</strong> ]
[ -<strong>m</strong> |
+ -<strong>B</strong> |
-<strong>d</strong> |
- -<strong>p</strong> |
- -<strong>s</strong> ]
+ -<strong>s</strong> |
+ -<strong>p</strong> ]
+ [ -<strong>C</strong> <var>cost</var> ]
[ -<strong>t</strong> ]
[ -<strong>v</strong> ]
<var>filename</var> <var>username</var> <var>password</var></code></p>
<p><code><strong>htdbm</strong> -<strong>x</strong>
[ -<strong>T</strong><var>DBTYPE</var> ]
- [ -<strong>m</strong> |
- -<strong>d</strong> |
- -<strong>p</strong> |
- -<strong>s</strong> ]
<var>filename</var> <var>username</var></code></p>
<p><code><strong>htdbm</strong> -<strong>l</strong>
@@ -120,7 +130,10 @@
<dd>Use batch mode; <em>i.e.</em>, get the password from the command line
rather than prompting for it. This option should be used with extreme care,
since <strong>the password is clearly visible</strong> on the command
- line.</dd>
+ line. For script use see the <code>-i</code> option.</dd>
+
+ <dt><code>-i</code></dt>
+ <dd>Read the password from stdin without verification (for script usage).</dd>
<dt><code>-c</code></dt>
<dd>Create the <var>passwdfile</var>. If <var>passwdfile</var> already
@@ -137,15 +150,26 @@
<dd>Use MD5 encryption for passwords. On Windows and Netware, this is
the default.</dd>
+ <dt><code>-B</code></dt>
+ <dd>Use bcrypt encryption for passwords. This is currently considered to
+ be very secure.</dd>
+
+ <dt><code>-C</code></dt>
+ <dd>This flag is only allowed in combination with <code>-B</code> (bcrypt
+ encryption). It sets the computing time used for the bcrypt algorithm
+ (higher is more secure but slower, default: 5, valid: 4 to 31).</dd>
+
<dt><code>-d</code></dt>
<dd>Use <code>crypt()</code> encryption for passwords. The default on all
platforms but Windows and Netware. Though possibly supported by
<code>htdbm</code> on all platforms, it is not supported by the
- <program>httpd</program> server on Windows and Netware.</dd>
+ <program>httpd</program> server on Windows and Netware.
+ This algorithm is <strong>insecure</strong> by today's standards.</dd>
<dt><code>-s</code></dt>
<dd>Use SHA encryption for passwords. Facilitates migration from/to Netscape
- servers using the LDAP Directory Interchange Format (ldif).</dd>
+ servers using the LDAP Directory Interchange Format (ldif).
+ This algorithm is <strong>insecure</strong> by today's standards.</dd>
<dt><code>-p</code></dt>
<dd>Use plaintext passwords. Though <code>htdbm</code> will support
@@ -156,12 +180,6 @@
<dd>Print each of the usernames and comments from the database on
stdout.</dd>
- <dt><code>-t</code></dt>
- <dd>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.</dd>
-
<dt><code>-v</code></dt>
<dd>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 @@
<dd>Delete user. If the username exists in the specified DBM file, it
will be deleted.</dd>
+ <dt><code>-t</code></dt>
+ <dd>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.</dd>
+
<dt><code><var>filename</var></code></dt>
<dd>The filename of the DBM format file. Usually without the extension
<code>.db</code>, <code>.pag</code>, or <code>.dir</code>. If
@@ -257,6 +281,18 @@
<p>The use of the <code>-b</code> option is discouraged, since when it is
used the unencrypted password appears on the command line.</p>
+
+ <p>When using the <code>crypt()</code> 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.</p>
+
+ <p>The SHA encryption format does not use salting: for a given password,
+ there is only one encrypted representation. The <code>crypt()</code> and
+ MD5 formats permute the representation by prepending a random salt string,
+ to make dictionary attacks against the passwords more difficult.</p>
+
+ <p>The SHA and <code>crypt()</code> formats are insecure by today's
+ standards.</p>
</section>
<section id="restrictions"><title>Restrictions</title>
Modified: httpd/httpd/branches/2.4.x/docs/manual/programs/htpasswd.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/programs/htpasswd.xml?rev=1420732&r1=1420731&r2=1420732&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/programs/htpasswd.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/programs/htpasswd.xml Wed Dec 12 15:05:27 2012
@@ -36,13 +36,16 @@
just the users listed in the files created by <code>htpasswd</code>. 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 <program>dbmmanage</program>.</p>
+ stores, though. To use a DBM database see <program>dbmmanage</program> or
+ <program>htdbm</program>.</p>
- <p><code>htpasswd</code> encrypts passwords using either a version of MD5
- modified for Apache, or the system's <code>crypt()</code> routine. Files
- managed by <code>htpasswd</code> 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 <code>crypt()</code>.</p>
+ <p><code>htpasswd</code> encrypts passwords using either bcrypt,
+ a version of MD5 modified for Apache, SHA1, or the system's
+ <code>crypt()</code> routine. Files
+ managed by <code>htpasswd</code> 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 <code>crypt()</code>.</p>
<p>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/</a>.</p>
</summary>
<seealso><program>httpd</program></seealso>
+<seealso><program>htdbm</program></seealso>
<seealso>The scripts in support/SHA1 which come with the
distribution.</seealso>
<section id="synopsis"><title>Synopsis</title>
<p><code><strong>htpasswd</strong>
[ -<strong>c</strong> ]
- [ -<strong>m</strong> ]
- [ -<strong>D</strong> ] <var>passwdfile</var> <var>username</var></code></p>
+ [ -<strong>i</strong> ]
+ [ -<strong>m</strong> |
+ -<strong>B</strong> |
+ -<strong>d</strong> |
+ -<strong>s</strong> |
+ -<strong>p</strong> ]
+ [ -<strong>C</strong> <var>cost</var> ]
+ [ -<strong>D</strong> ] <var>passwdfile</var> <var>username</var></code></p>
<p><code><strong>htpasswd</strong> -<strong>b</strong>
[ -<strong>c</strong> ]
[ -<strong>m</strong> |
+ -<strong>B</strong> |
-<strong>d</strong> |
- -<strong>p</strong> |
- -<strong>s</strong> ]
+ -<strong>s</strong> |
+ -<strong>p</strong> ]
+ [ -<strong>C</strong> <var>cost</var> ]
[ -<strong>D</strong> ] <var>passwdfile</var> <var>username</var>
<var>password</var></code></p>
<p><code><strong>htpasswd</strong> -<strong>n</strong>
+ [ -<strong>i</strong> ]
[ -<strong>m</strong> |
+ -<strong>B</strong> |
-<strong>d</strong> |
-<strong>s</strong> |
- -<strong>p</strong> ] <var>username</var></code></p>
+ -<strong>p</strong> ]
+ [ -<strong>C</strong> <var>cost</var> ] <var>username</var></code></p>
<p><code><strong>htpasswd</strong> -<strong>nb</strong>
[ -<strong>m</strong> |
+ -<strong>B</strong> |
-<strong>d</strong> |
-<strong>s</strong> |
- -<strong>p</strong> ] <var>username</var> <var>password</var></code></p>
+ -<strong>p</strong> ]
+ [ -<strong>C</strong> <var>cost</var> ] <var>username</var>
+ <var>password</var></code></p>
</section>
<section id="options"><title>Options</title>
@@ -88,7 +106,10 @@ distribution.</seealso>
<dd>Use batch mode; <em>i.e.</em>, get the password from the command line
rather than prompting for it. This option should be used with extreme care,
since <strong>the password is clearly visible</strong> on the command
- line.</dd>
+ line. For script use see the <code>-i</code> option.</dd>
+
+ <dt><code>-i</code></dt>
+ <dd>Read the password from stdin without verification (for script usage).</dd>
<dt><code>-c</code></dt>
<dd>Create the <var>passwdfile</var>. If <var>passwdfile</var> already
@@ -105,6 +126,15 @@ distribution.</seealso>
<dt><code>-m</code></dt>
<dd>Use MD5 encryption for passwords. This is the default.</dd>
+ <dt><code>-B</code></dt>
+ <dd>Use bcrypt encryption for passwords. This is currently considered to
+ be very secure.</dd>
+
+ <dt><code>-C</code></dt>
+ <dd>This flag is only allowed in combination with <code>-B</code> (bcrypt
+ encryption). It sets the computing time used for the bcrypt algorithm
+ (higher is more secure but slower, default: 5, valid: 4 to 31).</dd>
+
<dt><code>-d</code></dt>
<dd>Use <code>crypt()</code> encryption for passwords. This is not
supported by the <program>httpd</program> server on Windows and