## ProFTPD module `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.

## Author

Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.

## Directives

- SQLPasswordEncoding
- SQLPasswordEngine
- SQLPasswordSaltFile
- SQLPasswordUserSalt

## SQLPasswordEncoding

Syntax: SQLPasswordEncoding encoding
Default: hex
Context: "server config", `<VirtualHost>`, `<Global>`
Module: mod_sql_passwd
Compatibility: 1.3.3rc2 and later

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:

- base64
- hex (for lowercase hex values)
- HEX (for uppercase hex values)

If no `SQLPasswordEncoding` directive is configured, `mod_sql_passwd` will use "hex" by default.

## SQLPasswordEngine

Syntax: SQLPasswordEngine on|off
Default: off
Context: "server config", `<VirtualHost>`, `<Global>` Module: mod_sql_passwd
Compatibility: 1.3.3rc2 and later

The `SQLPasswordEngine` directive enables or disables the module's registered `SQLAuthType` handlers.

## SQLPasswordSaltFile

Syntax: SQLPasswordSaltFile path|"none" ["prepend"|"append"]
Default: none
Context: "server config", `<VirtualHost>`, `<Global>` Module: mod_sql_passwd
Compatibility: 1.3.3rc2 and later

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 prepend

tells `mod_sql_passwd` to prepend the salt as a prefix, and:

      SQLPasswordSaltFile /path/to/salt append

will 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.

## SQLPasswordUserSalt

Syntax: SQLPasswordUserSalt "name"|source ["prepend"|"append"]
Default: none
Context: "server config", `<VirtualHost>`, `<Global>` Module: mod_sql_passwd
Compatibility: 1.3.3 and later

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 prepend

tells `mod_sql_passwd` to prepend the salt as a prefix, and:

      SQLPasswordUserSalt name append

will cause the salt to be appended as a sufix. Note that the default behavior is to append the salt as a suffix.

## Installation

The `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_passwd

Then 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

## Usage

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 `mod_sql_passwd`module to use it:``

      <IfModule mod_sql_passwd.c>
        SQLPasswordEngine on
        SQLPasswordEncoding hex
        SQLPasswordSaltFile /path/to/salt
      </IfModule>

Author: $Author: castaglia $
Last Updated: $Date: 2010/02/01 19:30:13 $

© Copyright 2009-2010 TJ Saunders
All Rights Reserved