mod_sql_passwd
Many FTP sites use SQL databases for storing user accounts, including the
user name and password. And while the mod_sql
module provides
support for some formats for the passwords stored in SQL databases, many
sites have other formats which are not supported by mod_sql
.
These other formats often include MD5 or SHA1 passwords, base64-encoded
or hex-encoded, without the prefix which is required by
mod_sql
's "OpenSSL" SQLAuthType
.
The mod_sql_passwd
module provides support for some of these
other formats. When the mod_sql_passwd
module is enabled,
you can configure SQLAuthTypes
of "MD5", "SHA1", "SHA256", or
"SHA512", as well as the existing types supported by mod_sql
.
This module is contained in the mod_sql_passwd.c
file for
ProFTPD 1.3.x, and is not compiled by default. Installation
instructions are discussed here; a discussion
on usage is also available.
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).
The most current version of mod_sql_passwd
is distributed with
ProFTPD.
Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.
<VirtualHost>
, <Global>
The SQLPasswordEncoding
directive configures the encoding that
mod_sql_passwd
expects when handling password values retrieved
from a SQL database.
The following encoding values are currently supported:
If no SQLPasswordEncoding
directive is configured,
mod_sql_passwd
will use "hex" by default.
<VirtualHost>
, <Global>
The SQLPasswordEngine
directive enables or disables the module's
registered SQLAuthType
handlers.
<VirtualHost>
, <Global>
The SQLPasswordOptions
directive is used to configure various
behaviors of mod_sql_passwd
. Note: all of the configured
SQLPasswordOptions
parameters must appear on the same line
in the configuration; only the first SQLPassworOptions
directive
that appears in the configuration is used.
Example:
SQLPasswordOptions HashEncodeSalt HashEncodePassword
The following options are currently supported:
HashPassword
HashEncodePassword
HashSalt
HashEncodeSalt
See the transformations section for a fuller
description of how mod_sql_passwd
operates on the password and
salt data.
<VirtualHost>
, <Global>
The SQLPasswordRounds
directive configures the number of
rounds through which the password (and possibly salt) data will be hashed
and encoded. The count parameter must be greater than 1.
See the transformations section for a fuller
description of how mod_sql_passwd
operates on the password and
salt data.
<VirtualHost>
, <Global>
The SQLPasswordSaltFile
directive configures a file which contains
salt data. This salt will be added to the digest, along with the password
sent by the client. Note that the salt will be used for all users.
Since many editors will automatically add a newline when writing a file,
the mod_sql_passwd
file will automatically trim the last newline
in the salt data, if there is one. This means that if your salt must
end in a newline character, then your SQLPasswordSaltFile
must
contain "salt\n\n".
When using salted passwords, some systems will prepend the salt as a
prefix to the data, and others will append the salt as a suffix. The
optional second parameter to SQLPasswordSaltFile
controls how
this module will use the salt:
SQLPasswordSaltFile /path/to/salt Prependtells
mod_sql_passwd
to prepend the salt as a prefix, and:
SQLPasswordSaltFile /path/to/salt Appendwill cause the salt to be appended as a sufix. Note that the default behavior is to append the salt as a suffix.
If no SQLPasswordSaltFile
is configured, then no salting is done.
<VirtualHost>
, <Global>
The SQLPasswordUserSalt
directive configures a per-user
salt that will be added to the digest, along with the password sent by the
client.
If "name" is specified, then the per-user salt data will be the
name of the user logging in. Alternatively, you can configure a
SQLNamedQuery
which returns a single column of a single
row, containing a string to use as the salt data, e.g.:
SQLNamedQuery get-user-salt SELECT "salt FROM user_salts WHERE user_name = '%{0}'" SQLPasswordUserSalt sql:/get-user-salt
When using salted passwords, some systems will prepend the salt as a
prefix to the data, and others will append the salt as a suffix. The
optional second parameter to SQLPasswordUserSalt
controls how
this module will use the salt:
SQLPasswordUserSalt name Prependtells
mod_sql_passwd
to prepend the salt as a prefix, and:
SQLPasswordUserSalt name Appendwill cause the salt to be appended as a sufix. Note that the default behavior is to append the salt as a suffix.
mod_sql_passwd
module is distributed with ProFTPD. Simply
follow the normal steps for using third-party modules in proftpd. The
mod_sql_passwd
module requires OpenSSL support, so you must
use the --enable-openssl
configuration option.
NOTE: it is important that mod_sql_passwd
appear
after mod_sql
in your --with-modules
configure
option:
./configure --enable-openssl --with-modules=mod_sql:mod_sql_passwd ...To build
mod_sql_passwd
as a DSO module:
./configure --enable-dso --enable-openssl --with-shared=mod_sql_passwdThen follow the usual steps:
make make install
For those with an existing ProFTPD installation, you can use the
prxs
tool to add mod_sql_passwd
, as a DSO module, to
your existing server:
# prxs -c -i -d mod_sql_passwd.c
The following examples demonstrate how the mod_sql_passwd
can
be used.
To configure mod_sql_passwd
to handle MD5 passwords that are
base64-encoded, use:
<IfModule mod_sql_passwd.c> SQLPasswordEngine on SQLPasswordEncoding base64 </IfModule> <IfModule mod_sql.c> ... # Now that mod_sql_passwd is used, we can configure "MD5" as an # SQLAuthType that mod_sql will handle. SQLAuthTypes MD5 </IfModule>
To have mod_sql_passwd
to handle hex-encoded (and in
lowercase) passwords, use:
<IfModule mod_sql_passwd.c> SQLPasswordEngine on SQLPasswordEncoding hex </IfModule>
And if for some reason your database values are stored as hex values in uppercase, you would use:
<IfModule mod_sql_passwd.c> SQLPasswordEngine on SQLPasswordEncoding HEX </IfModule>
To use salted passwords, write the salt to use into a file, and configure
the
Processing of Password and Salt Data
Thus if we use a configuration like:
Using Salts
Let's show a configuration which uses a prepended salt:
Some sites will have even more complex requirements for how the data
processed by
Each of the following examples assumes the following configuration:
This option says that
This option says that
This option says that
This option says that
Of course, these various options can be combined:
Rounds
Using the above example case, you would configure
mod_sql_passwd
module to use it:
<IfModule mod_sql_passwd.c>
SQLPasswordEngine on
SQLPasswordEncoding hex
SQLPasswordSaltFile /path/to/salt
</IfModule>
The logical description of the processing that mod_sql_passwd
does can be expressed as:
ENCODE(HASH(data))
where data is comprised of the password, and possibly a salt. The
function ENCODE()
is determined by
SQLPasswordEncoding
, and
the function HASH()
by SQLAuthTypes
.
SQLAuthTypes MD5
SQLPasswordEncoding hex
Then mod_sql_passwd
performs the following processing:
hex(MD5(data))
in order to calculate the value that it will compare against the password
value stored for the authenticating client.
By default, the mod_sql_passwd
module uses the password, as
sent by the client, as the data on which to perform its processing.
In many cases, however, a salt is needed in addition to the password. The
SQLPasswordSaltFile
and
SQLPasswordUserSalt
directives
are used to tell mod_sql_passwd
that it should add a salt
to the data before processing it. These directives also specify whether the
salt should be prepended to the password, e.g.:
data = salt + password
or appended to the password, e.g.:
data = password + salt
SQLAuthTypes MD5
SQLPasswordEncoding hex
SQLPasswordSaltFile /path/to/salt.data Prepend
This means that mod_sql_passwd
would end up checking the
following computed value against the value in the database:
hex(MD5(salt + password))
mod_sql_passwd
need to be constructed. The salt
data may need to be hashed before being used with the password, or may need
to be hashed and encoded before use. Or maybe the password data needs
to be hashed before use with the salt, or hashed and encoded.
The SQLPasswordOptions
directive
supports options for supporting these use cases.
SQLAuthTypes MD5
SQLPasswordEncoding hex
SQLPasswordSaltFile /path/to/salt.data Prepend
Let's look at each of the SQLPasswordOptions
in turn:
HashPassword
mod_sql_passwd
should use the
HASH()
function on the password data before using it,
regardless of whether a salt is used or not. I.e.:
data = salt + HASH(password)
which assuming hex and MD5, means:
data = salt + MD5(password)
HashSalt
mod_sql_passwd
should use the
HASH()
function on the salt data before using it.
If no salt is used, this option is silently ignored. Thus:
data = HASH(salt) + password
which assuming hex and MD5, means:
data = MD5(salt) + password
HashEncodePassword
mod_sql_passwd
should use the
HASH()
function and then the ENCODE()
function
on the password data before using it. This option is only
useful when salts are also used. Thus:
data = salt + ENCODE(HASH(password))
which assuming hex and MD5, means:
data = salt + hex(MD5(password))
Note: If no salt is present, this option will be ignored. Without
a salt, this option is equivalent to adding another round of transformation,
which is not an obvious side effect.
HashEncodeSalt
mod_sql_passwd
should use the
HASH()
function and then the ENCODE()
function
on the salt data before using it. If no salt is used, this option is
silently ignored. Thus:
data = ENCODE(HASH(salt)) + password
which assuming hex and MD5, means:
data = hex(MD5(salt)) + password
SQLPasswordOptions HashEncodePassword HashEncodeSalt
which would cause the data on which mod_sql_passwd
operates to
be constructed like so:
data = ENCODE(HASH(salt)) + ENCODE(HASH(password))
data = hex(MD5(salt)) + hex(MD5(password))
For convenience, let's assume that the function TRANSFORM
encompasses the entire ENCODE(HASH())
operation:
TRANSFORM(data) = ENCODE(HASH(data))
Let's also assume that passwords are stored in your database using something
like this:
hex(MD5(hex(MD5(hex(MD5(data))))))
That means that the data value has gone through multiple rounds
of the TRANSFORM
function, e.g.:
TRANSFORM(TRANSFORM(TRANSFORM(data)))
In this case, there are 3 rounds of transformation:
for (i = 0; i < nrounds; i++)
data = TRANSFORM(data)
mod_sql_passwd
to perform multiple rounds of transformation using the
SQLPasswordRounds
directive,
like so:
SQLAuthTypes MD5
SQLPasswordEncoding hex
SQLPasswordRounds 3
The combination of SQLPasswordOptions
and
SQLPasswordRounds
means that quite few combinations of password
values can be supported by the mod_sql_passwd
module.
Author: $Author: castaglia $
Last Updated: $Date: 2011/01/08 01:45:02 $
© Copyright 2009-2011 TJ Saunders
All Rights Reserved