<!-- $Id: mod_tls.html,v 1.11 2006/09/11 18:42:38 castaglia Exp $ -->
<!-- $Source: /cvsroot/proftp/proftpd/doc/contrib/mod_tls.html,v $ -->
<html>
<head>
<title>ProFTPD module mod_tls</title>
</head>
<body bgcolor=white>
<hr>
<center>
<h2><b>ProFTPD module <code>mod_tls</code></b></h2>
</center>
<hr><br>
This module is contained in the <code>mod_tls.c</code> file for ProFTPD
1.2.<i>x</i>, and is not compiled by default. Installation instructions
are discussed <a href="#Installation">here</a>.
<p>
The most current version of <code>mod_tls</code> is distributed with the
ProFTPD source code.
<p>
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/).
<p>
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).
<h2>Author</h2>
<p>
Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any
questions, concerns, or suggestions regarding this module.
<h2>Thanks</h2>
<p>
<i>2002-09-01</i>: Thanks to Peter 'Luna' Runestig <peter <i>at</i>
runestig.com> for his original <code>mod_tls</code>, upon which this version
is based. His module can be found here:
<pre>
<a href="ftp://ftp.runestig.com/pub/proftpd-tls/">ftp://ftp.runestig.com/pub/proftpd-tls/</a>
</pre>
<h2>Directives</h2>
<ul>
<li><a href="#TLSCACertificateFile">TLSCACertificateFile</a>
<li><a href="#TLSCACertificatePath">TLSCACertificatePath</a>
<li><a href="#TLSCARevocationFile">TLSCARevocationFile</a>
<li><a href="#TLSCARevocationPath">TLSCARevocationPath</a>
<li><a href="#TLSCertificateChainFile">TLSCertificateChainFile</a>
<li><a href="#TLSCipherSuite">TLSCipherSuite</a>
<li><a href="#TLSCryptoDevice">TLSCryptoDevice</a>
<li><a href="#TLSDHParamFile">TLSDHParamFile</a>
<li><a href="#TLSDSACertificateFile">TLSDSACertificateFile</a>
<li><a href="#TLSDSACertificateKeyFile">TLSDSACertificateKeyFile</a>
<li><a href="#TLSEngine">TLSEngine</a>
<li><a href="#TLSLog">TLSLog</a>
<li><a href="#TLSOptions">TLSOptions</a>
<li><a href="#TLSPassPhraseProvider">TLSPassPhraseProvider</a>
<li><a href="#TLSProtocol">TLSProtocol</a>
<li><a href="#TLSRandomSeed">TLSRandomSeed</a>
<li><a href="#TLSRenegotiate">TLSRenegotiate</a>
<li><a href="#TLSRequired">TLSRequired</a>
<li><a href="#TLSRSACertificateFile">TLSRSACertificateFile</a>
<li><a href="#TLSRSACertificateKeyFile">TLSRSACertificateKeyFile</a>
<li><a href="#TLSTimeoutHandshake">TLSTimeoutHandshake</a>
<li><a href="#TLSVerifyClient">TLSVerifyClient</a>
<li><a href="#TLSVerifyDepth">TLSVerifyDepth</a>
</ul>
<hr>
<h2><a name="TLSCACertificateFile">TLSCACertificateFile</a></h2>
<strong>Syntax:</strong> TLSCACertificateFile <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSCACertificateFile</code> directive configures one file where you
can assemble the certificates of Certification Authorities (CA) for your
clients. The CA certificates in the file are then used to verify client
certificates, if presented. Such a file is merely the concatenation of the
various PEM-encoded CA certificates, in order of preference. This directive
can be used in addition to, or as an alternative for,
<code>TLSCACertificatePath</code>.
<p>
Example:
<pre>
TLSCACertificateFile /etc/ftpd/ca-bundle.pem
</pre>
<p>
If neither <code>TLSCACertificateFile</code> nor
<code>TLSCACertificatePath</code> are specified, the following message will
appear in the <code>TLSLog</code>:
<pre>
using default OpenSSL verification locations (see $SSL_CERT_DIR)
</pre>
This means that the <code>SSL_CERT_DIR</code> environment variable, if set,
will be used to determine the location of a CA certificate directory, to be
used when verifying clients. Note, though, that this directive is only
meaningful if <code>TLSVerifyClient</code> is set to <em>on</em>; otherwise,
no client verification occurs.
<p>
See also: <a href="#TLSCACertificatePath"><code>TLSCACertificatePath</code></a>
<p>
<hr>
<h2><a name="TLSCACertificatePath">TLSCACertificatePath</a></h2>
<strong>Syntax:</strong> TLSCACertificatePath <em>directory</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSCACertificatePath</code> directive sets the directory for the
certificates of Certification Authorities (CAs) for your clients. These are
used to verify the client certificates presented. This directive may be used
in addition to, or as alternative for, <code>TLSCACertificateFile</code>.
<p>
The files in the configured directory have to be PEM-encoded, and are accessed
through hash filenames. This means one cannot simply place the CA certificates
there: one also has to create symbolic links named <i>hash-value</i>.N. The
<code>c_rehash</code> utility that comes with OpenSSL can be used to create
the necessary symlinks.
<p>
Example:
<pre>
TLSCACertificatePath /etc/ftpd/ca/
</pre>
<p>
If neither <code>TLSCACertificateFile</code> nor
<code>TLSCACertificatePath</code> are specified, the following message will
appear in the <code>TLSLog</code>:
<pre>
using default OpenSSL verification locations (see $SSL_CERT_DIR)
</pre>
This means that the <code>SSL_CERT_DIR</code> environment variable, if set,
will be used to determine the location of a CA certificate directory, to be
used when verifying clients.
<p>
See also: <a href="#TLSCACertificateFile"><code>TLSCACertificateFile</code></a>
<p>
<hr>
<h2><a name="TLSCARevocationFile">TLSCARevocationFile</a></h2>
<strong>Syntax:</strong> TLSCARevocationFile <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSCARevocationFile</code> directive configures one file that can
contain the Certificate Revocation Lists (CRL) of Certification Authorities
(CA) for your clients. These CRLs are used during the verification of client
certificates, if presented. Such a file is merely the concatenation of the
various PEM-encoded CRL files, in order of preference. This directive can be
used in addition to, or as an alternative for, <code>TLSCARevocationPath</code>.
<p>
Example:
<pre>
TLSCARevocationFile /etc/ftpd/ca-crl-bundle.pem
</pre>
<p>
See also: <a href="#TLSCARevocationPath"><code>TLSCARevocationPath</code></a>
<p>
<hr>
<h2><a name="TLSCARevocationPath">TLSCARevocationPath</a></h2>
<strong>Syntax:</strong> TLSCARevocationPath <em>directory</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSCARevocationPath</code> directive sets the directory for the
Certificate Revocation Lists (CRL) of Certification Authorities (CAs) for your
clients. These are used during the verification of client certificates, if
presented. This directive may be used in addition to, or as alternative for,
<code>TLSCARevocationFile</code>.
<p>
The files in the configured directory have to be PEM-encoded, and are accessed
through hash filenames. This means one cannot simply place the CRLs there:
one also has to create symbolic links named <i>hash-value</i>.N. The
<code>c_rehash</code> utility that comes with OpenSSL can be used to create
the necessary symlinks.
<p>
Example:
<pre>
TLSCARevocationPath /etc/ftpd/crl/
</pre>
<p>
See also: <a href="#TLSCARevocationFile"><code>TLSCARevocationFile</code></a>
<p>
<hr>
<h2><a name="TLSCertificateChainFile">TLSCertificateChainFile</a></h2>
<strong>Syntax:</strong> TLSCertificateChainFile <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSCertificateChainFile</code> directive sets the optional
all-in-one file where you can assemble the certificates of Certification
Authorities (CA) which form the certificate chain of the server certificate.
This starts with the issuing CA certificate of the server certificate and can
range up to the root CA certificate. Such a file is simply the concatenation
of the various PEM-encoded CA Certificate files in certificate chain order.
(<em>Certificate chain order</em> means that the list must be sorted starting
with the subject's certificate (actual server certificate), followed by
intermediate CA certificates if applicable, and ending at the highest level
root CA.) This server certificate chain is sent to the client, in addition to
the server's certificate.
<p>
If <code>TLSCertificateChainFile</code> is not used, and
<code>TLSCACertificatePath</code> is used, the certificate chain is built from
the certificates in that path. <code>TLSCertificateChainFile</code> should be
used as an alternative to <code>TLSCACertificatePath</code> for explicitly
constructing the server certificate chain. It is especially useful to avoid
conflicts with CA certificates when using client authentication. For although
placing a CA certificate of the server certificate chain into
the <code>TLSCACertificatePath</code> has the same effect for the certificate
chain construction, it has the side-effect that client certificates issued by
this same CA certificate are also accepted on client authentication. This
is usually <i>not</i> what one expects.
<p>
Be careful: providing the certificate chain works only if you are using a
single (either RSA or DSA) based server certificate. If you are using a coupled
RSA+DSA certificate pair, this will work only if actually both certificates
use the same certificate chain. Otherwise, clients will become confused.
<p>
Example:
<pre>
TLSCertificateChainFile /etc/ftpd/client-ca-list.pem
</pre>
<p>
<hr>
<h2><a name="TLSCipherSuite">TLSCipherSuite</a></h2>
<strong>Syntax:</strong> TLSCipherSuite <em>cipher-list</em><br>
<strong>Default:</strong> ALL:!ADH<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
Default cipher list is "ALL:!ADH".
<p>
How to put together a <em>cipher list</em> parameter:
<pre>
Key Exchange Algorithms:
"kRSA" RSA key exchange
"kDHr" Diffie-Hellman key exchange (key from RSA cert)
"kDHd" Diffie-Hellman key exchange (key from DSA cert)
"kEDH' Ephemeral Diffie-Hellman key exchange (temporary key)
Authentication Algorithm:
"aNULL" No authentication
"aRSA" RSA authentication
"aDSS" DSS authentication
"aDH" Diffie-Hellman authentication
Cipher Encoding Algorithm:
"eNULL" No encodiing
"DES" DES encoding
"3DES" Triple DES encoding
"RC4" RC4 encoding
"RC2" RC2 encoding
"IDEA" IDEA encoding
MAC Digest Algorithm:
"MD5" MD5 hash function
"SHA1" SHA1 hash function
"SHA" SHA hash function (should not be used)
Aliases:
"ALL" all ciphers
"SSLv2" all SSL version 2.0 ciphers (should not be used)
"SSLv3" all SSL version 3.0 ciphers
"EXP" all export ciphers (40-bit)
"EXPORT56" all export ciphers (56-bit)
"LOW" all low strength ciphers (no export)
"MEDIUM" all ciphers with 128-bit encryption
"HIGH" all ciphers using greater than 128-bit encryption
"RSA" all ciphers using RSA key exchange
"DH" all ciphers using Diffie-Hellman key exchange
"EDH" all ciphers using Ephemeral Diffie-Hellman key exchange
"ADH" all ciphers using Anonymous Diffie-Hellman key exchange
"DSS" all ciphers using DSS authentication
"NULL" all ciphers using no encryption
</pre>
<p>
Each item in the list may include a prefix modifier:
<pre>
"+" move cipher(s) to the current location in the list
"-" remove cipher(s) from the list (may be added again by a
subsequent list entry)
"!" kill cipher from the list (it may not be added again by a
subsequent list entry)
</pre>
<p>
If no modifier is specified the entry is added to the list at the current
position. "+" may also be used to combine tags to specify entries
such as "RSA+RC4" describes all ciphers that use both RSA and RC4.
<p>
For example, all available ciphers not including ADH key exchange:
<pre>
ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
</pre>
<p>
All algorithms including ADH and export but excluding patented algorithms:
<pre>
HIGH:MEDIUM:LOW:EXPORT56:EXP:ADH:!kRSA:!aRSA:!RC4:!RC2:!IDEA
</pre>
<p>
The OpenSSL command
<pre>
openssl ciphers -v <em><list of ciphers></em>
</pre>
may be used to list all of the ciphers and the order described by a specific
<em><list of ciphers></em>.
<p>
<hr>
<h2><a name="TLSCryptoDevice">TLSCryptoDevice</a></h2>
<strong>Syntax:</strong> TLSCryptoDevice <em>driver|"all"|"none"</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.3.1rc1 and later
<p>
The <code>TLSCryptoDevice</code> directive is used to configure
<code>mod_tls</code> to use an OpenSSL "engine", a cryptographic module
that OpenSSL library can use for accelerated cryptographic support, or
HSM keys, <i>etc</i>.
<p>
To use all of the engines compiled into OpenSSL, use:
<pre>
TLSCryptoDevice all
</pre>
OpenSSL will find, from the list of supported engines, the first one
usable, if any. If no usable engines are found, OpenSSL will default to
its normal software implementation. If a specific engine is desired as
the default engine to use, specify the engine name, <i>e.g.</i>:
<pre>
TLSCryptoDevice chil
</pre>
<p>
The OpenSSL command
<pre>
openssl engine
</pre>
may be used to list all of the engine drivers supported by OpenSSL.
<p>
<hr>
<h2><a name="TLSDHParamFile">TLSDHParamFile</a></h2>
<strong>Syntax:</strong> TLSDHParamFile <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSDHParamFile</code> directive is used to configure a file that
<code>mod_tls</code> will use when engaging in a Diffie-Hellman key exchange.
Such a key exchange can be computationally intensive, in terms for parameter
generation; to help speed up the process, the parameters used may be generated
in advance, and stored in a file. The <code>dhparam</code> utility that comes
with OpenSSL may be used to generate an appropriate file for this directive.
The <em>file</em> parameter must be an absolute path.
<p>
<hr>
<h2><a name="TLSDSACertficateFile">TLSDSACertficateFile</a></h2>
<strong>Syntax:</strong> TLSDSACertificateFile <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSDSACertificateFile</code> directive points to the PEM-encoded
file containing the DSA certificate file for the server and optionally also
the corresponding DSA private key file.
<p>
If the contained private key is encrypted, the administrator will be
prompted for the passphrase when the daemon starts up, and when the daemon
is restarted.
<p>
Example:
<pre>
TLSDSACertificateFile /etc/ftpd/server-dsa-cert.pem
</pre>
<p>
<hr>
<h2><a name="TLSDSACertificateKeyFile">TLSDSACertificateKeyFile</a></h2>
<strong>Syntax:</strong> TLSDSACertificateKeyFile <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSDSACertificateKeyFile</code> directive points to the PEM-encoded
private key file for the server. If the private key is not combined with the
certificate in the <code>TLSDSACertificateFile</code>, use this additional
directive to point to the file with the standalone private key. When
<code>TLSDSACertificateFile</code> is used and the file contains both the
certificate and the private key, this directive need not be used. However,
this practice is strongly discouraged. Instead we recommend you to separate
the certificate and the private key.
<p>
If the contained private key is encrypted, the administrator will be
prompted for the passphrase when the daemon starts up, and when the daemon
is restarted.
<p>
Example:
<pre>
TLSDSACertificateKeyFile /etc/ftpd/server-dsa-key.pem
</pre>
<p>
<hr>
<h2><a name="TLSEngine">TLSEngine</a></h2>
<strong>Syntax:</strong> TLSEngine <em>on|off</em><br>
<strong>Default:</strong> off<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSEngine</code> directive toggles the use of the SSL/TLS protocol
engine (<i>e.g.</i> <code>mod_tls</code>). This is usually used inside a
<code><VirtualHost></code> section to enable SSL/TLS sessions for a
particular virtual host. By default <code>mod_tls</code> is disabled for both
the main server and all configured virtual hosts.
<p>
<hr>
<h2><a name="TLSLog">TLSLog</a></h2>
<strong>Syntax:</strong> TLSLog <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSLog</code> directive is used to specify a log file for
<code>mod_tls</code>'s reporting on a per-server basis. The <em>file</em>
parameter given must be the full path to the file to use for logging.
<p>
<hr>
<h2><a name="TLSOptions">TLSOptions</a></h2>
<strong>Syntax:</strong> TLSOptions <em>opt1 ...</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSOptions</code> directive is used to configure various optional
behavior of <code>mod_tls</code>.
<p>
Example:
<pre>
TLSOptions iPAddressRequired StdEnvVars
</pre>
<p>
The currently implemented options are:
<ul>
<li><code>AllowDotLogin</code><br>
<p>
By default, <code>mod_tls</code> still requires that a user supply a
password for authentication, even if a valid client certificate is
presented. If this option is enabled, <code>mod_tls</code> will check
in the user's home directory for a <code>.tlslogin</code> file, which
should contain one or more PEM-encoded certificates. If the certificate
presented by the client, if any, matches a certificate in this
<code>.tlslogin</code> file, the user will be considered authenticated
and the server will not prompt for a password. If the user's
<code>.tlslogin</code> does not exist, or does not contain the client's
certificate, then the server will fallback to requesting a password for
authentication.
<p>
<li><code>AllowPerUser</code><br>
<p>
This option affects how <code>mod_tls</code> evaluates any
<code>TLSRequired</code> directives. Usually <code>mod_tls</code>
will reject any FTP commands, when <code>TLSRequired on</code> or
<code>TLSRequired ctrl</code> is in effect, if the client has not
successfully negotiated a SSL/TLS handshake. The FTPS specification
requires that the SSL/TLS handshake occur, via the AUTH FTP command,
<i>before</i> the USER and PASS commands. This means that
<code>mod_tls</code> does not know the identity of the connecting client
when enforcing <code>TLSRequired</code>. If this <code>AllowPerUser</code>
is used, <code>mod_tls</code> will wait until after the <code>PASS</code>
command has been processed to enforce any <code>TLSRequired</code>
settings.
<p>
<b>Important</b>: if <code>AllowPerUser</code> is used, even if
<code>TLSRequired on</code> or <code>TLSRequired ctrl</code> are in
effect, it will be possible for the connecting client to send
usernames and passsword <i>unprotected</i> before <code>mod_tls</code>
rejects the connection. This results in a slightly weaker security
policy enforcement; please consider carefully if this tradeoff is
acceptable for your site.
<p>
However, <code>TLSRequired auth</code> and
<code>TLSRequired auth+data</code> configurations will override the
<code>AllowPerUser</code> option.
<p>
<li><code>ExportCertData</code><br>
<p>
Sets the following environment variables, if applicable. Note that
doing so increases the memory size of the process quite a bit:
<table border=1>
<tr>
<td><code>TLS_SERVER_CERT</code></td>
<td>Server certificate, PEM-encoded</td>
</tr>
<tr>
<td><code>TLS_CLIENT_CERT</code></td>
<td>Client certificate, PEM-encoded</td>
</tr>
<tr>
<td><code>TLS_CLIENT_CERT_CHAIN<i>n</i></code></td>
<td>PEM-encoded certificates in client certificate chain</td>
</tr>
</table>
<p>
<li><code>NoCertRequest</code><br>
<p>
Some FTP clients are known to be buggy when handling a server's certificate
request. This option causes the server not to include such a request
during an SSL handshake.
<p>
<li><code>StdEnvVars</code><br>
<p>
Sets the following environment variables, if applicable. These environment
variables are then avaiable for use, such as in <code>LogFormat</code>s.
Note that doing so may increase the memory size of the process quite a bit:
<table border=1>
<tr>
<td><code>FTPS</code></td>
<td>Present if FTP over SSL/TLS is being used</td>
</tr>
<tr>
<td><code>TLS_PROTOCOL</code></td>
<td>SSL protocol version (<i>e.g.</i> SSLv3, TLSv1)</td>
</tr>
<tr>
<td><code>TLS_SESSION_ID</code></td>
<td>Hex-encoded SSL session ID</td>
</tr>
<tr>
<td><code>TLS_CIPHER</code></td>
<td>Cipher specification name</td>
</tr>
<tr>
<td><code>TLS_CIPHER_EXPORT</code></td>
<td>Present if cipher is an export cipher</td>
</tr>
<tr>
<td><code>TLS_CIPHER_KEYSIZE_POSSIBLE</code></td>
<td>Number of cipher bits possible</td>
</tr>
<tr>
<td><code>TLS_CIPHER_KEYSIZE_USED</code></td>
<td>Number of cipher bits used</td>
</tr>
<tr>
<td><code>TLS_LIBRARY_VERSION</code></td>
<td>OpenSSL version</td>
</tr>
<tr>
<td><code>TLS_CLIENT_M_VERSION</code></td>
<td>Client certificate version</td>
</tr>
<tr>
<td><code>TLS_CLIENT_M_SERIAL</code></td>
<td>Client certificate serial number</td>
</tr>
<tr>
<td><code>TLS_CLIENT_S_DN</code></td>
<td>Subject DN of client certificate</td>
</tr>
<tr>
<td><code>TLS_CLIENT_S_DN_</code><i>x509<i></td>
<td>Component of client certificate's Subject DN, where <i>x509</i> is
a component of a X509 DN:<br>
C,CN,D,I,G,L,O,OU,S,ST,T,UID,Email</td>
</tr>
<tr>
<td><code>TLS_CLIENT_I_DN</code></td>
<td>Issuer DN of client certificate</td>
</tr>
<tr>
<td><code>TLS_CLIENT_I_DN_</code><i>x509</i></td>
<td>Component of client certificate's Issuer DN, where <i>x509</i> is
a component of a X509 DN:<br>
C,CN,D,I,G,L,O,OU,S,ST,T,UID,Email</td>
</tr>
<tr>
<td><code>TLS_CLIENT_V_START</code></td>
<td>Start time of client certificate validity</td>
</tr>
<tr>
<td><code>TLS_CLIENT_V_END</code></td>
<td>End time of client certificate validity</td>
</tr>
<tr>
<td><code>TLS_CLIENT_A_SIG</code></td>
<td>Client certificate's signature algorithm</td>
</tr>
<tr>
<td><code>TLS_CLIENT_A_KEY</code></td>
<td>Client certificate's public key algorithm</td>
</tr>
<tr>
<td><code>TLS_CLIENT_CERT</code>
<td>Client certificate, PEM-encoded</td>
</tr>
<tr>
<td><code>TLS_CLIENT_CERT_CHAIN<i>n</i></code></td>
<td>PEM-encoded certificates in client certificate chain</td>
</tr>
<tr>
<td><code>TLS_SERVER_M_VERSION</code></td>
<td>Server certificate version</td>
</tr>
<tr>
<td><code>TLS_SERVER_M_SERIAL</code></td>
<td>Server certificate serial number</td>
</tr>
<tr>
<td><code>TLS_SERVER_S_DN</code></td>
<td>Subject DN of server certificate</td>
</tr>
<tr>
<td><code>TLS_SERVER_S_DN_</code><i>x509<i></td>
<td>Component of server certificate's Subject DN, where <i>x509</i> is
a component of a X509 DN:<br>
C,CN,D,I,G,L,O,OU,S,ST,T,UID,Email</td>
</tr>
<tr>
<td><code>TLS_SERVER_I_DN</code></td>
<td>Issuer DN of server certificate</td>
</tr>
<tr>
<td><code>TLS_SERVER_I_DN_</code><i>x509</i></td>
<td>Component of server certificate's Issuer DN, where <i>x509</i> is
a component of a X509 DN:<br>
C,CN,D,I,G,L,O,OU,S,ST,T,UID,Email</td>
</tr>
<tr>
<td><code>TLS_SERVER_V_START</code></td>
<td>Start time of server certificate validity</td>
</tr>
<tr>
<td><code>TLS_SERVER_V_END</code></td>
<td>End time of server certificate validity</td>
</tr>
<tr>
<td><code>TLS_SERVER_A_SIG</code></td>
<td>Server certificate's signature algorithm</td>
</tr>
<tr>
<td><code>TLS_SERVER_A_KEY</code></td>
<td>Server certificate's public key algorithm</td>
</tr>
<tr>
<td><code>TLS_SERVER_CERT</code></td>
<td>Server certificate, PEM-encoded</td>
</tr>
</table>
<p>
<li><code>dNSNameRequired</code><br>
<p>
This option will cause <code>mod_tls</code> to perform checks on a client's
certificate once the SSL handshake has been completed: the client's
certificate will be searched for the <code>subjectAltName</code> X509v3
extension, and, in that extension, the <code>dNSName</code> value will
be looked up. Unless a <code>dNSName</code> value is present, and the
value matches the DNS name to which the client's IP address resolves,
the SSL session is closed. This check is only performed during
SSL handshakes on the control channel. Note that if
<code>UseReverseDNS</code> is <em>off</em>, this option is automatically
disabled.
<p>
<li><code>iPAddressRequired</code><br>
<p>
This option will cause <code>mod_tls</code> to perform checks on a client's
certificate once the SSL handshake has been completed: the client's
certificate will be searched for the <code>subjectAltName</code> X509v3
extension, and, in that extension, the <code>iPAddress</code> value will
be looked up. Unless an <code>iPAddress</code> value is present, and the
value matches the IP address of the client, the SSL session is closed.
This check is only performed during SSL handshakes on the control channel.
</ul>
<p>
<hr>
<h2><a name="TLSPassPhraseProvider">TLSPassPhraseProvider</a></h2>
<strong>Syntax:</strong> TLSPassPhraseProvider <em>path</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.3.1rc1 and later
<p>
The <code>TLSPassPhraseProvider</code> directive is used to specify an
external program which will be called, when <code>mod_tls</code> starts up,
for each encrypted certificate key file. The program will be invoked with
two command-line arguments, passed on <code>stdin</code> to the program:
<pre>
<em>servername</em>:<em>portnumber</em> "RSA"|"DSA"
</pre>
where <code><em>servername</em>:<em>portnumber</em></code> indicates the
server using that encrypted certificate key, and <code>"RSA"</code>
or <code>"DSA"</code> indicates the private key algorithm used
for that key. The program then must print the corresponding passphrase
for the key to <code>stdout</code>.
<p>
The intent is that this external program can perform any security checks
necessary, to make sure that the system is not compromised by an attacker,
and only when these checks pass successfully will the passphrase be provided.
These security checks, and the way the passphrase is determined, can be as
complex as you like.
<p>
Example:
<pre>
TLSPassPhraseProvider /etc/ftpd/tls/get-passphrase
</pre>
<p>
<hr>
<h2><a name="TLSProtocol">TLSProtocol</a></h2>
<strong>Syntax:</strong> TLSProtocol <em>protocol</em><br>
<strong>Default:</strong> SSLv23<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSProtocol</code> directive is used to configure the SSL/TLS
protocol versions that <code>mod_tls</code> should use when establishing
SSL/TLS sessions. Clients can then only connect using the configured
protocol.
<p>
Since the protocol version used by <code>mod_tls</code> is set only once,
when the daemon starts, the <code>TLSProtocol</code> directive is only allowed
in the "server config" context.
<p>
The allowed protocols are:
<p>
<table>
<tr>
<td><code>SSLv23</code></td>
<td>Compatibility mode, used to allow both SSLv3 and TLSv1</td>
</tr>
<tr>
<td><code>SSLv3</code></td>
<td>Allow only SSLv3</td>
</tr>
<tr>
<td><code>TLSv1</code></td>
<td>Allow only TLSv1</td>
</tr>
</table>
<p>
All use of SSLv2 is disabled. SSLv2 <b>should not</b> be used.
<p>
<hr>
<h2><a name="TLSRandomSeed">TLSRandomSeed</a></h2>
<strong>Syntax:</strong> TLSRandomSeed <em>seed</em><br>
<strong>Default:</strong> <i>openssl-dir</i><code>/.rnd</code><br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code
><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSRandomSeed</code> directive configures the file that
<code>mod_tls</code> will use for seeding the PRNG. <em>seed</em> must be an
absolute path.
<p>
When the daemon shuts down, any random data left will be written out to the
random seed file, so that that data may be used for seeding when the daemon
is started again.
<p>
Example:
<pre>
TLSRandomSeed /etc/ftpd/server.rnd
</pre>
<p>
Note that the <code>TLSRandomSeed</code> directive is <b>not</b> used to
seed the entropy required by the OpenSSL library; that configuration
is OpenSSL-specific. Instead, the <code>TLSRandomSeed</code> file can
be thought of a cache file for the unused entropy, to be used to help
speed up entropy gathering when the daemon starts up again.
<p>
<hr>
<h2><a name="TLSRenegotiate">TLSRenegotiate</a></h2>
<strong>Syntax:</strong> TLSRenegotiate <em>["ctrl" secs] ["data" Kbytes] ["timeout" secs]|["required" on|off]|"none"</em><br>
<strong>Default:</strong> ctrl 14400 data 25165824 required true <i>(for OpenSSL 0.9.7 or greater)</i><br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSRenegotiate</code> directive is used to configure when SSL
renegotiations are to occur. Renegotiations, and thus this directive, are
only supported by <code>mod_tls</code> if the version of OpenSSL installed
is 0.9.7 or greater.
<p>
If supported, renegotiations will occur on control channels that have been
established for four hours by default, and on data channels that have
transferred over one gigabyte of data by default. When renegotiations are
requested, the client is given a timeout of 30 seconds, by default, to perform
the renegotiation. To change the default control channel renegotiation
timeout, use <em>ctrl</em> followed by a number, greater than zero, in seconds.
Use <em>data</em> followed by a number, greater than zero, of kilobytes to
change the default data channel renegotiation threshhold. The <em>timeout</em>
parameter, followed by a positive number of seconds, is used to change the
length of time given to a client to complete a requested renegotiation, after
which the SSL session will be shutdown. By default, <code>mod_tls</code>
will <b>require</b> that the client comply with the requested renegotiation
within the <code>TLSRenegotiate</code> timeout. If, however, the client is
unwilling or unable to do so, and the daemon needs to support these clients,
set <em>required</em> to <i>off</i>. Doing so will cause renegotiations to
be requested, but not required.
<p>
By default, <code>mod_tls</code> will perform renegotiations if supported, on
the control channel after 4 hours, and on the data channel after one gigabyte
of transferred data. The default timeout for a renegotiation is 30 seconds.
<p>
Use <em>none</em> to disable all renegotiation requirements.
<p>
Examples:
<pre>
# Change renegotiations to occur on control channels after 1 hour
TLSRenegotiate ctrl 3600
# Change renegotiations to occur on data channels after 500 MB
TLSRenegotiate data 512000
# Change renegotiations so that they are not required, only requested
TLSRenegotiate required off
# Change only the timeout for renegotiations to be 5 minutes
TLSRenegotiate timeout 300
# Change all of the above renegotiation threshholds using one directive
TLSRenegotiate ctrl 3600 data 512000 required off timeout 300
# To disable renegotiations entirely
TLSRenegotiate none
</pre>
<p>
<hr>
<h2><a name="TLSRequired">TLSRequired</a></h2>
<strong>Syntax:</strong> TLSRequired <em>on|off|ctrl|data|auth|auth+data</em><br>
<strong>Default:</strong> off<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code>, <code><Anonymous></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSRequired</code> directive is used to define a basic security
policy, one that dictates whether the control channel, or data channel, or
both, of an FTP session must occur over SSL/TLS.
<p>
The <em>on</em> parameter enables SSL/TLS requirements on both control and
data channels; <em>off</em> disables the requirements on both channels.
Use <em>ctrl</em> and <em>data</em> to require SSL/TLS on either channel
individually.
<p>
Example:
<pre>
# Require SSL/TLS on the control channel, so that passwords are not sent
# in the clear.
TLSRequired ctrl
# Require SSL/TLS on both channels.
TLSRequired on
</pre>
The <em>auth</em> parameter requires that SSL/TLS be used on the control
channel, but only for authentication. To use this setting <i>and</i>
require SSL/TLS for data transfers, use the <em>auth+data</em> parameter,
<i>e.g.</i>:
<pre>
# Allow the client to use the CCC command to remove SSL/TLS from the
# control channel, but only after authentication has been performed.
# Still enforce the policy of using SSL/TLS for data transfers.
#
# Note that if we did not need to protect data transfers, we would
# set 'TLSRequired auth' instead of using 'TLSRequired auth+data'.
TLSRequired auth+data
</pre>
This <em>auth+data</em> parameter allows a very specific security policy:
authentication via the <code>USER</code>/<code>PASS</code> commands
<b>must</b> be protected via SSL/TLS, as must the data channel, but after
authenticating, the client can request that protection be removed from the
control channel. This policy allows clients to use the <code>CCC</code>
(<b>C</b>lear <b>C</b>ommand <b>C</b>hannel) command, which in turn enables
SSL/TLS protected data transfers that are operate better with firewalls that
monitor the FTP control channel.
<p>
<hr>
<h2><a name="TLSRSACertificateFile">TLSRSACertificateFile</a></h2>
<strong>Syntax:</strong> TLSRSACertificateFile <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
<p>
The <code>TLSRSACertificateFile</code> directive points to the PEM-encoded
file containing the RSA certificate file for the server and optionally also
the corresponding RSA private key file.
<p>
If the contained private key is encrypted, the administrator will be
prompted for the passphrase when the daemon starts up, and when the daemon
is restarted.
<p>
Example:
<pre>
TLSRSACertificateFile /etc/ftpd/server-rsa-cert.pem
</pre>
<p>
<hr>
<h2><a name="TLSRSACertificateKeyFile">TLSRSACertificateKeyFile</a></h2>
<strong>Syntax:</strong> TLSRSACertificateKeyFile <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSRSACertificateKeyFile</code> directive points to the PEM-encoded
private key file for the server. If the private key is not combined with the
certificate in the <code>TLSRSACertificateFile</code>, use this additional
directive to point to the file with the standalone private key. When
<code>TLSRSACertificateFile</code> is used and the file contains both the
certificate and the private key, this directive need not be used. However,
this practice is strongly discouraged. Instead we recommend you to separate
the certificate and the private key.
<p>
If the contained private key is encrypted, the administrator will be
prompted for the passphrase when the daemon starts up, and when the daemon
is restarted.
<p>
Example:
<pre>
TLSRSACertificateKeyFile /etc/ftpd/server-rsa-key.pem
</pre>
<p>
<hr>
<h2><a name="TLSTimeoutHandshake">TLSTimeoutHandshake</a></h2>
<strong>Syntax:</strong> TLSTimeoutHandshake <em>seconds</em><br>
<strong>Default:</strong> 300<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.9rc1 and later
<p>
The <code>TLSTimeoutHandshake</code> directive configures the maximum number
of seconds for <code>mod_tls</code> to accept an SSL/TLS handshake. If set to
zero, <code>mod_tls</code> will wait forever for a handshake to complete. The
default is 300 seconds (five minutes).
<p>
<hr>
<h2><a name="TLSVerifyClient">TLSVerifyClient</a></h2>
<strong>Syntax:</strong> TLSVerifyClient <em>on|off</em><br>
<strong>Default:</strong> off<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSVerifyClient</code> directive configures how <code>mod_tls</code>
handles certificates presented by clients. If <em>off</em>, the module
will accept the certificate and establish an SSL/TLS session, but will not
verify the certificate. If <em>on</em>, the module will verify a client's
certificate and, furthermore, will fail all SSL handshake attempts <b>unless</b>
the client presents a certificate when the server requests one. Note that the
server can be configured to <i>not</i> request a client certificate via
the <code>TLSOptions</code> directive's "NoCertRequest" parameter.
<p>
See also: <a href="#TLSOptions"><code>TLSOptions</code></a>
<p>
<hr>
<h2><a name="TLSVerifyDepth">TLSVerifyDepth</a></h2>
<strong>Syntax:</strong> TLSVerifyDepth <em>depth</em><br>
<strong>Default:</strong> 9<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_tls<br>
<strong>Compatibility:</strong> 1.2.7rc1 and later
<p>
The <code>TLSVerifyDepth</code> directive sets how deeply <code>mod_tls</code>
should verify before deciding that the client does not have a valid
certificate. The depth actually is the maximum number of intermediate
certificate issuers, <i>i.e.</i> the number of CA certificates which are
allowed to be followed while verifying the client certificate. A depth of 0
means that only self-signed client certificates are accepted, a depth of 1
means the client certificate can be self-signed or has to be signed by a CA
which is directly known to the server (<i>i.e.</i> the CA's certificate is
under <code>TLSCACertificatePath</code>), etc.
<p>
Example:
<pre>
TLSVerifyDepth 10
</pre>
<p>
<hr>
<h2><a name="Usage">Usage</a></h2>
Much of the documentation for Apache's <code>mod_ssl</code>, concerning
certificates, OpenSSL usage, <i>etc</i> applies to this module as well:
<pre>
<a href="http://www.modssl.org/docs/2.7/">http://www.modssl.org/docs/2.7/</a>
</pre>
The OpenSSL documentation, and its
<a href="http://www.openssl.org/support/faq.cgi">FAQ</a>, are recommended as
well:
<pre>
<a href="http://www.openssl.org/docs/">http://www.openssl.org/docs/</a>
</pre>
<p>
There is also a script, <code>cert-tool</code>, that can help in the creation
of certificates. See <code>cert-tool --help</code> for usage information:
<pre>
<a href="http://www.castaglia.org/openssl/contrib/cert-tool">http://www.castaglia.org/openssl/contrib/cert-tool</a>
</pre>
<p>
A copy of the Draft describing FTP over SSL/TLS is included with the source
code for this module.
<p>
<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_tls</code> module is distributed with ProFTPD. Simply follow
the normal steps for using third-party modules in proftpd:
<pre>
./configure --with-modules=mod_tls
make
make install
</pre>
You may need to specify the location of the OpenSSL header and library files
in your <code>configure</i> command, <i>e.g.</i>:
<pre>
./configure --with-modules=mod_tls \
--with-includes=/usr/local/openssl \
--with-libraries=/usr/local/openssl
</pre>
<p>
<hr><br>
Author: <i>$Author: castaglia $</i><br>
Last Updated: <i>$Date: 2006/09/11 18:42:38 $</i><br>
<br><hr>
<font size=2><b><i>
© Copyright 2002-2003 TJ Saunders<br>
All Rights Reserved<br>
</i></b></font>
<hr><br>
</body>
</html>
