Gecko [ www.thearyasamaj.org ]

Name	Size	Permission
ftpasswd.html	14.61 KB	-rw-r--r--
ftpmail.html	8 KB	-rw-r--r--
ftpquota.html	10.9 KB	-rw-r--r--
index.html	9.04 KB	-rw-r--r--
mod_auth_otp.html	16.5 KB	-rw-r--r--
mod_ban.html	22.53 KB	-rw-r--r--
mod_copy.html	4.85 KB	-rw-r--r--
mod_ctrls_admin.html	15.05 KB	-rw-r--r--
mod_deflate.html	6.89 KB	-rw-r--r--
mod_digest.html	12.92 KB	-rw-r--r--
mod_dnsbl.html	6.1 KB	-rw-r--r--
mod_dynmasq.html	3.26 KB	-rw-r--r--
mod_exec.html	23.89 KB	-rw-r--r--
mod_geoip.html	17.06 KB	-rw-r--r--
mod_ifsession.html	11.02 KB	-rw-r--r--
mod_ifversion.html	4.96 KB	-rw-r--r--
mod_ldap.html	32.32 KB	-rw-r--r--
mod_load.html	2.97 KB	-rw-r--r--
mod_log_forensic.html	9.78 KB	-rw-r--r--
mod_qos.html	2.62 KB	-rw-r--r--
mod_quotatab.html	25.02 KB	-rw-r--r--
mod_quotatab_file.html	2.23 KB	-rw-r--r--
mod_quotatab_ldap.html	2.63 KB	-rw-r--r--
mod_quotatab_radius.html	2.08 KB	-rw-r--r--
mod_quotatab_sql.html	10.93 KB	-rw-r--r--
mod_radius.html	22.11 KB	-rw-r--r--
mod_ratio.html	6.99 KB	-rw-r--r--
mod_readme.html	2.69 KB	-rw-r--r--
mod_rewrite.html	30.06 KB	-rw-r--r--
mod_sftp.html	93.71 KB	-rw-r--r--
mod_sftp_pam.html	5.47 KB	-rw-r--r--
mod_sftp_sql.html	5.63 KB	-rw-r--r--
mod_shaper.html	23.28 KB	-rw-r--r--
mod_site_misc.html	5.81 KB	-rw-r--r--
mod_snmp.html	42.38 KB	-rw-r--r--
mod_sql.html	62.81 KB	-rw-r--r--
mod_sql_odbc.html	10.2 KB	-rw-r--r--
mod_sql_passwd.html	24.44 KB	-rw-r--r--
mod_sql_sqlite.html	2.95 KB	-rw-r--r--
mod_statcache.html	8.29 KB	-rw-r--r--
mod_tls.html	85.34 KB	-rw-r--r--
mod_tls_fscache.html	2.73 KB	-rw-r--r--
mod_tls_memcache.html	3.91 KB	-rw-r--r--
mod_tls_redis.html	3.6 KB	-rw-r--r--
mod_tls_shmcache.html	6.78 KB	-rw-r--r--
mod_unique_id.html	3.54 KB	-rw-r--r--
mod_wrap.html	12.38 KB	-rw-r--r--
mod_wrap2.html	24.83 KB	-rw-r--r--
mod_wrap2_file.html	4.69 KB	-rw-r--r--
mod_wrap2_redis.html	5.33 KB	-rw-r--r--
mod_wrap2_sql.html	8.33 KB	-rw-r--r--

Code Editor : mod_auth_otp.html

<!DOCTYPE html>
<html>
<head>
<title>ProFTPD module mod_auth_otp</title>
</head>

<hr>
<center>
<h2>ProFTPD module <code>mod_auth_otp</code></h2>
</center>
<hr>

The purpose of the <code>mod_auth_otp</code> module is to enable the use
of one-time-passwords (OTP) for proftpd authentication. There have
been multiple different OTP algorithms devised over the years; this module
implements the HOTP and TOTP algorithms. Note that <code>mod_auth_otp</code>
requires storage/retrieval for per-user shared keys and counters, and thus
this module currently requires mod_sql.

One-Time Password RFCs 
For those wishing to learn more about these one-time password algorithms, see:
<ul>
 <li><a href="http://www.faqs.org/rfcs/rfc4226.html">HOTP: An HMAC-Based One-Time Password Algorithm (RFC 4226)</a>
 <li><a href="http://www.faqs.org/rfcs/rfc6238.html">TOTP: Time-Based One-Time Password Algorithm(RFC 6238)</a>
</ul>
Note that <a href="http://en.wikipedia.org/wiki/Google_Authenticator"><code>Google Authenticator</code></a> is based on the TOTP algorithm;
<code>mod_auth_otp</code> thus enables use of Google Authenticator for ProFTPD
authentication.

Installation instructions are discussed <a href="#Installation">here</a>;
detailed notes on best practices for using this module are
<a href="#Usage">here</a>.

The most current version of <code>mod_auth_otp</code> is distributed with the
ProFTPD source code.

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

<h2>Author</h2>

Please contact TJ Saunders &lt;tj at castaglia.org&gt; with any
questions, concerns, or suggestions regarding this module.

<h2>Directives</h2>
<ul>
 <li><a href="#AuthOTPAlgorithm">AuthOTPAlgorithm</a>
 <li><a href="#AuthOTPEngine">AuthOTPEngine</a>
 <li><a href="#AuthOTPLog">AuthOTPLog</a>
 <li><a href="#AuthOTPOptions">AuthOTPOptions</a>
 <li><a href="#AuthOTPTable">AuthOTPTable</a>
 <li><a href="#AuthOTPTableLock">AuthOTPTableLock</a>
</ul>

<hr>
<h3><a name="AuthOTPAlgorithm">AuthOTPAlgorithm</a></h3>
Syntax: AuthOTPAlgorithm hotp|totp 
Default: AuthOTPAlgorithm totp 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_auth_otp 
Compatibility: 1.3.5rc4 and later

The <code>AuthOTPAlgorithm</code> directive configures which one-time password
algorithm will be used when calculating codes for connections to the virtual
host.

The supported algorithm names are:
<ul>
 <li><code>hotp</code> (counter-based codes)
 <li><code>totp</code> (time-based codes, using HMAC-SHA1)
 <li><code>totp-sha256</code> (time-based codes, using HMAC-SHA256)
 <li><code>totp-sha512</code> (time-based codes, using HMAC-SHA512)
</ul>
The default algorithm is "totp".

<hr>
<h3><a name="AuthOTPEngine">AuthOTPEngine</a></h3>
Syntax: AuthOTPEngine on|off 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_auth_otp 
Compatibility: 1.3.5rc4 and later

The <code>AuthOTPEngine</code> directive enables the handling of one-time
password codes for authentication, both for FTP/FTPS as well as SFTP/SCP
sessions. By default, use of one-time passwords is disabled.

<hr>
<h3><a name="AuthOTPLog">AuthOTPLog</a></h3>
Syntax: AuthOTPLog path|"none" 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_auth_otp 
Compatibility: 1.3.5rc4 and later

The <code>AuthOTPLog</code> directive is used to specify a log file for
<code>mod_auth_otp</code>'s reporting on a per-server basis. The path
parameter given must be the full path to the file to use for logging.

Note that this path must not be to a world-writable directory and,
unless <code>AllowLogSymlinks</code> is explicitly set to on
(generally a bad idea), the path must not be a symbolic link.

<hr>
<h3><a name="AuthOTPOptions">AuthOTPOptions</a></h3>
Syntax: AuthOTPOptions opt1 ... 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_auth_otp 
Compatibility: 1.3.5rc4 and later

The <code>AuthOTPOptions</code> directive is used to configure various optional
behavior of <code>mod_auth_otp</code>.

For example:
<pre>
 AuthOTPOptions StandardResponse
</pre>

The currently implemented options are:
<ul>
 <li><code>DisplayVerificationCode</code> 
 When <code>mod_auth_otp</code> prompts the user for the OTP code, it
 requests that the client not echo/display the verification code
 as it is entered by the user. In some cases, however, administrators
 may wish to have the OTP code be displayed. For these situations, use
 this option, e.g.:
 <pre>
 AuthOTPOptions DisplayVerificationCode
 </pre>
 </li>

<li><code>RequireTableEntry</code> 
 
 When <code>mod_auth_otp</code> requests information for a user from the
 <code>AuthOTPTable</code> and no information is found, it will normally
 allow other auth modules to handle the login attempt, even if
 <code>mod_auth_otp</code> is authoritative. This behavior allows
 for a seemless transition of your user base, provisioning users with
 shared keys/secrets for their one-time passwords as time allows.

However, there may be sites which require the use of one-time
 passwords; any login attempt which does not use a valid one-time
 password must be rejected. Thus the lack of an entry for a user
 in the <code>AuthOTPTable</code> is, for this policy, a fatal error and
 should be handled as such. For this kind of very secure configuration,
 use this option, in conjunction with the <code>AuthOrder</code>
 directive, e.g.:
 <pre>
 AuthOrder mod_auth_otp.c* ...
 AuthOTPOptions RequireTableEntry StandardResponse
 </pre>
 </li>

<li><code>StandardResponse</code> 
 
 When <code>mod_auth_otp</code> is handling FTP sessions, it will respond
 to a <code>USER</code> command with a response message indicating the
 expectation of a one-time password:
 <pre>
 331 One-time password required for user
 </pre>
 However, this change of the response message "leaks" information about
 the server configuration, i.e. that OTPs will be used. To
 tell <code>mod_auth_otp</code> to continue using the standard/normal
 response message, use this option.
 </li>
</ul>

<hr>
<h3><a name="AuthOTPTable">AuthOTPTable</a></h3>
Syntax: AuthOTPTable table-info 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_auth_otp 
Compatibility: 1.3.5rc4 and later

The <code>AuthOTPTable</code> directive configures the information necessary
for <code>mod_auth_otp</code> to retrieve the shared key/secret and current
counter, on a per-user basis; this directive is required for
<code>mod_auth_otp</code> to function. If <code>AuthOTPTable</code> is
not configured, <code>mod_auth_otp</code> will refuse to work.

The <code>mod_auth_otp</code> module currently expects/uses SQL tables for
retrieval/storage of its data on a per-user basis. Thus the
<code>AuthOTPTable</code> directives requires two separate
<code>SQLNamedQuery</code> directives: one for looking up the needed data,
the other for updating that data. The table-info parameter
encodes these <code>SQLNamedQuery</code> names like so:
<pre>
 SQLNamedQuery get-user-totp SELECT ...
 SQLNamedQuery update-user-totp UPDATE ...

AuthOTPTable sql:/get-user-totp/update-user-totp
</pre>
See the <a href="#Usage">usage</a> section for a more detailed example.

<hr>
<h3><a name="AuthOTPTableLock">AuthOTPTableLock</a></h3>
Syntax: AuthOTPTableLock path 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_auth_otp 
Compatibility: 1.3.5rc4 and later

The <code>AuthOTPTableLock</code> directive sets the path for a
synchronization lockfile which <code>mod_auth_otp</code> needs when updating
the <code>AuthOTPTable</code> for e.g. counter-based codes. Use of
<code>AuthOTPTableLock</code> is recommended, but not required.

If <code>AuthOTPTableLock</code> is used, it is strongly advised that
the configured path not be on an NFS (or any other network)
filesystem.

<hr>
<h2><a name="Usage">Usage</a></h2>

Note that the following examples assume the existing of an SQL table whose
schema looks like the following (using the SQLite schema syntax):
<pre>
 CREATE TABLE auth_otp (
 user TEXT PRIMARY KEY,
 secret TEXT,
 counter INTEGER
 );
</pre>

The <code>auth_otp.secret</code> column must contain the
base32-encoded shared key for the user. Why Base32-encoding? That
is what Google Authenticator expects/uses for its shared key storage; its
<code>google-authenticator</code> command-line tool generates a Base32-encoded
string for entering into the Google Authenticator app on your mobile device.

To get the base32-encoded shared key using <code>google-authenticator</code>:
<pre>
 $ ./google-authenticator
 Do you want authentication tokens to be time-based (y/n) y
 Here you will see generated QR code
 Your new secret key is: base32-encoded secret here
 ...
</pre>

Example Time-based (TOTP) Configuration 
<pre>
 &lt;IfModule mod_auth_otp.c&gt;
 AuthOTPEngine on

# Use time-based codes (TOTP)
    AuthOTPAlgorithm totp

AuthOTPTable sql:/get-user-totp/update-user-totp
  &lt;/IfModule&gt;

&lt;IfModule mod_sql.c&gt;
    ...

# Notice that for time-based counters, we do not need to retrieve
 # the auth_otp.counter column; the counter value is determined from the
 # system clock.
 SQLNamedQuery get-user-totp SELECT "secret FROM auth_otp WHERE user = \'%{0}\'"
 SQLNamedQuery update-user-totp UPDATE "counter = %{1} WHERE user = \'%{0}\'" auth_otp
 &lt;/IfModule&gt;
</pre>

Example Counter-based (HOTP) Configuration 
<pre>
 &lt;IfModule mod_auth_otp.c&gt;
 AuthOTPEngine on

# Use counter-based codes (HOTP)
    AuthOTPAlgorithm hotp

AuthOTPTable sql:/get-user-hotp/update-user-hotp
  &lt;/IfModule&gt;

&lt;IfModule mod_sql.c&gt;
 ...
 SQLNamedQuery get-user-hotp SELECT "secret, counter FROM auth_otp WHERE user = \'%{0}\'"
 SQLNamedQuery update-user-hotp UPDATE "counter = %{1} WHERE user = \'%{0}\'" auth_otp
 &lt;/IfModule&gt;
</pre>

Secure/Paranoid Configurations 
Security-conscious adminstrators may not want users to notice if/when they
have started expecting one-time passwords for their logins; not all users may
have been provisioned with the necessary shared key. To prevent
<code>mod_auth_otp</code> from "leaking" its presence/usage and instead to
continue using the standard FTP response messages, use the following in
your configuration for <code>mod_auth_otp</code>:
<pre>
 AuthOTPOption StandardResponse
</pre>

If, on the other hand, you have successfully provisioned all of your
users with OTP shared keys, and now require that all logins use a
one-time password (but still want to not leak this information), then
you would use:
<pre>
 # Make mod_auth_otp authoritative; if it fails to handle a login attempt,
 # that login attempt MUST fail.
 AuthOrder mod_auth_otp.c* ...

# Use the standard FTP response message, and fail the login if we find
 # a user that has not been provisioned.
 AuthOTPOptions RequireTableEntry StandardResponse
</pre>

SFTP/SCP Support 
One-time passwords can also be used for <code>mod_sftp</code> sessions,
i.e. for SFTP and SCP clients. The SSH RFCs define any non-standard
"password-like" authentication method as "keyboard-interactive". Thus to
use <code>mod_auth_otp</code> for your SFTP connections, simply include
both <code>mod_sftp</code> and <code>mod_auth_otp</code> in your build. That's
it.

Now, if you want <code>mod_sftp</code> to only try to use one-time
passwords (or public keys), and not normal passwords, then you might
use a <code>mod_sftp</code> configuration like this:
<pre>
 SFTPAuthMethods publickey keyboard-interactive
</pre>

Module Load Order and <code>mod_sftp</code> 
In order for <code>mod_auth_otp</code> to work its magic, it must
come after the <code>mod_sftp</code> module in the module load order.
To do this as a static module, you would use something like this when building
proftpd:
<pre>
 $ ./configure --with-modules=...:mod_sftp:mod_auth_otp:...
</pre>
ensuring that <code>mod_auth_otp</code> comes after <code>mod_sftp</code> in
your <code>--with-modules</code> list.

As a shared module, configuring <code>mod_auth_otp</code> to be after
<code>mod_sftp</code> is much easier. Your configuration will have a list
of <code>LoadModule</code> directives; make sure <code>mod_auth_otp</code>
appears after <code>mod_sftp</code>:
<pre>
 LoadModule mod_sftp.c
 ...
 LoadModule mod_auth_otp.c
 ...
</pre>
You will know if the module load ordering is wrong if you see the following
log message appear in your logs:
<pre>
 proftpd[87129]: mod_auth_otp/0.0: mod_sftp not loaded, skipping keyboard-interactive support
</pre>

Logging 
The <code>mod_auth_otp</code> module supports different forms of logging. The
main module logging is done via the <code>AuthOTPLog</code> directive. This
log is used for successes/failures. For example, if the user provides an OTP
code, but that user is not configured in the <code>AuthOTPTable</code>, you
would see a log message such as:
<pre>
 2016-01-18 12:35:46,725 mod_auth_otp/0.2[27192]: user 'foobar' has no OTP info in AuthOTPTable
 2016-01-18 12:36:47,152 mod_auth_otp/0.2[27192]: FAILED: user 'foobar' provided invalid OTP code
</pre>
If the user is provisioned in the <code>AuthOTPTable</code>, but the
OTP code is invalid, you would see just this message:
<pre>
 2016-01-18 12:40:09,500 mod_auth_otp/0.2[27235]: FAILED: user 'foobar' provided invalid OTP code
</pre>
And finally, for valid OTP codes, the following is logged:
<pre>
 2016-01-18 12:42:40,115 mod_auth_otp/0.2[27484]: SUCCESS: user 'foobar' provided valid OTP code
</pre>

For debugging purposes, the module also uses
<a href="http://www.proftpd.org/docs/howto/Tracing.html">trace logging</a>,
via the module-specific channels:
<ul>
 <li>auth_otp
</ul>
Thus for trace logging, to aid in debugging, you would use the following in
your <code>proftpd.conf</code>:
<pre>
 TraceLog /path/to/auth-trace.log
 Trace auth_otp:20
</pre>
This trace logging can generate large files; it is intended for debugging
use only, and should be removed from any production configuration.

Suggested Future Features 
The following lists the features I hope to add to <code>mod_auth_otp</code>,
according to need, demand, inclination, and time:
<ul>
 <li>Configurable number of digits in the expected code (currently hardcoded as 6)
 <li>Support "emergency recovery" codes
 <li>Support resynchronization with clients
</ul>

<a name="FAQ">
Frequently Asked Questions

<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_auth_otp</code> module is distributed with ProFTPD. Simply follow
the normal steps for using third-party modules in ProFTPD. For including
<code>mod_auth_otp</code> as a staticly linked module:
<pre>
 $ ./configure --enable-openssl --with-modules=mod_sql:mod_sql_sqlite:mod_auth_otp:...
</pre>
To build <code>mod_auth_otp</code> as a DSO module:
<pre>
 $ ./configure --enable-dso --enable-openssl --with-shared=mod_auth_otp:...
</pre>
Then follow the usual steps:
<pre>
 $ make
 $ make install
</pre>

</body>
</html>

${this.title}

Code Editor : mod_auth_otp.html