2418 lines
91 KiB
HTML
2418 lines
91 KiB
HTML
<!DOCTYPE html>
|
|
<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>
|
|
|
|
<p>
|
|
The <code>mod_tls</code> module implements FTP over SSL/TLS, known as FTPS.
|
|
|
|
<p>
|
|
This module is contained in the <code>mod_tls.c</code> file for ProFTPD
|
|
1.3.<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="#TLSControlsACLs">TLSControlsACLs</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="#TLSECCertificateFile">TLSECACertificateFile</a>
|
|
<li><a href="#TLSECCertificateKeyFile">TLSECCertificateKeyFile</a>
|
|
<li><a href="#TLSECDHCurve">TLSECDHCurve</a>
|
|
<li><a href="#TLSEngine">TLSEngine</a>
|
|
<li><a href="#TLSLog">TLSLog</a>
|
|
<li><a href="#TLSMasqueradeAddress">TLSMasqueradeAddress</a>
|
|
<li><a href="#TLSNextProtocol">TLSNextProtocol</a>
|
|
<li><a href="#TLSOptions">TLSOptions</a>
|
|
<li><a href="#TLSPKCS12File">TLSPKCS12File</a>
|
|
<li><a href="#TLSPassPhraseProvider">TLSPassPhraseProvider</a>
|
|
<li><a href="#TLSPreSharedKey">TLSPreSharedKey</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="#TLSServerCipherPreference">TLSServerCipherPreference</a>
|
|
<li><a href="#TLSServerInfoFile">TLSServerInfoFile</a>
|
|
<li><a href="#TLSSessionCache">TLSSessionCache</a>
|
|
<li><a href="#TLSSessionTicketKeys">TLSSessionTicketKeys</a>
|
|
<li><a href="#TLSSessionTickets">TLSSessionTickets</a>
|
|
<li><a href="#TLSStapling">TLSStapling</a>
|
|
<li><a href="#TLSStaplingCache">TLSStaplingCache</a>
|
|
<li><a href="#TLSStaplingOptions">TLSStaplingOptions</a>
|
|
<li><a href="#TLSStaplingResponder">TLSStaplingResponder</a>
|
|
<li><a href="#TLSStaplingTimeout">TLSStaplingTimeout</a>
|
|
<li><a href="#TLSTimeoutHandshake">TLSTimeoutHandshake</a>
|
|
<li><a href="#TLSUserName">TLSUserName</a>
|
|
<li><a href="#TLSVerifyClient">TLSVerifyClient</a>
|
|
<li><a href="#TLSVerifyDepth">TLSVerifyDepth</a>
|
|
<li><a href="#TLSVerifyOrder">TLSVerifyOrder</a>
|
|
<li><a href="#TLSVerifyServer">TLSVerifyServer</a>
|
|
</ul>
|
|
|
|
<h2>Control Actions</h2>
|
|
<ul>
|
|
<li><a href="#tls_sesscache_clear"><code>tls sesscache clear</code></a>
|
|
<li><a href="#tls_sesscache_info"><code>tls sesscache info</code></a>
|
|
<li><a href="#tls_sesscache_remove"><code>tls sesscache remove</code></a>
|
|
</ul>
|
|
|
|
<hr>
|
|
<h3><a name="TLSCACertificateFile">TLSCACertificateFile</a></h3>
|
|
<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> or
|
|
<em>optional</em>; otherwise, no client verification occurs.
|
|
|
|
<p>
|
|
See also: <a href="#TLSCACertificatePath"><code>TLSCACertificatePath</code></a>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSCACertificatePath">TLSCACertificatePath</a></h3>
|
|
<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>
|
|
<h3><a name="TLSCARevocationFile">TLSCARevocationFile</a></h3>
|
|
<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>
|
|
<h3><a name="TLSCARevocationPath">TLSCARevocationPath</a></h3>
|
|
<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>
|
|
<h3><a name="TLSCertificateChainFile">TLSCertificateChainFile</a></h3>
|
|
<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>
|
|
<h3><a name="TLSCipherSuite">TLSCipherSuite</a></h3>
|
|
<strong>Syntax:</strong> TLSCipherSuite <em>[protocol] cipher-list</em><br>
|
|
<strong>Default:</strong> DEFAULT:!ADH:!EXPORT:!DES<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>
|
|
Sets the list of SSL/TLS ciphersuites for use. Default cipher list is
|
|
"DEFAULT:!ADH:!EXPORT:!DES".
|
|
|
|
<p>
|
|
<b>Note</b> that <code>mod_tls</code> will automatically <i>prepend</i> the
|
|
configured <em>cipher-list</em> with "!EXPORT", in order to <i>prevent</i> the
|
|
use of the insecure "export grade" ciphers.
|
|
|
|
<p>
|
|
If the SSL library supports TLSv1.3 (<i>e.g.</i> OpenSSL-1.1.1 and later), the
|
|
<em>protocol specifier</em> "TLSv1.3" can be used to configure the cipher
|
|
suites for that protocol:
|
|
<pre>
|
|
TLSProtocol TLSv1.2 TLSv1.3
|
|
|
|
# Configure ciphersuites for TLSv1.2 and older protocols
|
|
TLSCipherSuite TLSv1.2 ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:...
|
|
|
|
# Configure TLSv1.3 ciphersuites separately
|
|
TLSCipherSuite TLSv1.3 TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256
|
|
</pre>
|
|
|
|
<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
|
|
"SHA256" SHA-256 hash function
|
|
"SHA384" SHA-384 hash function
|
|
"SHA512" SHA-512 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
|
|
"TLSv1" all TLS version 1.0 ciphers
|
|
"ECDH" all ciphers using Elliptic Curve Diffie-Hellman key exchange
|
|
"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>
|
|
<h3><a name="TLSControlsACLs">TLSControlsACLs</a></h3>
|
|
<strong>Syntax:</strong> TLSControlsACLs <em>actions|"all" "allow"|"deny" "user"|"group" list</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config<br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.3rc1 and later
|
|
|
|
<p>
|
|
The <code>TLSControlsACLs</code> directive configures access lists of
|
|
<em>users</em> or <em>groups</em> who are allowed (or denied) the ability to
|
|
use the <em>actions</em> implemented by <code>mod_tls</code>. The default
|
|
behavior is to deny everyone unless an ACL allowing access has been explicitly
|
|
configured.
|
|
|
|
<p>
|
|
If "allow" is used, then <em>list</em>, a comma-delimited list
|
|
of <em>users</em> or <em>groups</em>, can use the given <em>actions</em>; all
|
|
others are denied. If "deny" is used, then the <em>list</em> of
|
|
<em>users</em> or <em>groups</em> cannot use <em>actions</em> all others are
|
|
allowed. Multiple <code>TLSControlsACLs</code> directives may be used to
|
|
configure ACLs for different control actions, and for both users and groups.
|
|
|
|
<p>
|
|
The <em>actions</em> provided by <code>mod_tls</code> are
|
|
"sesscache clear" , "sesscache info", and
|
|
"sesscache remove".
|
|
|
|
<p>
|
|
Examples:
|
|
<pre>
|
|
# Allow only user root to examine/update the external SSL session cache
|
|
TLSControlsACLs all allow user root
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSCryptoDevice">TLSCryptoDevice</a></h3>
|
|
<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>
|
|
<h3><a name="TLSDHParamFile">TLSDHParamFile</a></h3>
|
|
<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
|
|
contains pre-computed Diffie-Hellman (DH) group parameters. The
|
|
<code>mod_tls</code> module will use these parameters when engaging in
|
|
Diffie-Hellman key exchanges.
|
|
|
|
<p>
|
|
Such key exchanges can be computationally intensive, in terms for parameter
|
|
generation. To help speed up the process and avoid latency for Diffie-Hellman
|
|
key exchanges, the DH group parameters used may be generated in advance, and
|
|
stored in a <code>TLSDHParamFile</code>. The <code>dhparam</code> utility
|
|
that comes with OpenSSL may be used to generate an appropriate file for this
|
|
directive:
|
|
<pre>
|
|
$ openssl dhparam -outform PEM -2 <i>nbits</i> >> dhparams.pem
|
|
$ openssl dhparam -outform PEM -5 <i>nbits</i> >> dhparams.pem
|
|
</pre>
|
|
Using either -2 or -5 as the generator is fine. The <em>nbits</em> value used
|
|
should vary between 512 and 4096, inclusive.
|
|
|
|
<p>
|
|
The <em>file</em> parameter must be an absolute path.
|
|
|
|
<p>
|
|
<b>Note</b> that as of <code>proftpd-1.3.6rc1</code> and later, for
|
|
Diffie-Hellman key exchanges, <code>mod_tls</code> will generate DH parameters
|
|
that match the size of the server certificate's RSA/DSA key. Some clients,
|
|
such as Java 7 (and earlier) code, cannot handle DH parameter lengths greater
|
|
than 1024 bits; see this <a href="#TLSJavaDH">FAQ</a> for a workaround for such
|
|
clients.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSDSACertficateFile">TLSDSACertficateFile</a></h3>
|
|
<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. Alternatively, the <code>TLSPassPhraseProvider</code>
|
|
directive can be used to supply a source for that passphrase.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
TLSDSACertificateFile /etc/ftpd/server-dsa-cert.pem
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSDSACertificateKeyFile">TLSDSACertificateKeyFile</a></h3>
|
|
<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>
|
|
<h3><a name="TLSECCertificateFile">TLSECCertificateFile</a></h3>
|
|
<strong>Syntax:</strong> TLSECCertificateFile <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.3.5rc4 and later
|
|
|
|
<p>
|
|
The <code>TLSECCertificateFile</code> directive points to the PEM-encoded
|
|
file containing the EC certificate file for the server and optionally also
|
|
the corresponding EC 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. Alternatively, the <code>TLSPassPhraseProvider</code>
|
|
directive can be used to supply a source for that passphrase.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
TLSECCertificateFile /etc/ftpd/server-ec-cert.pem
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSECCertificateKeyFile">TLSECCertificateKeyFile</a></h3>
|
|
<strong>Syntax:</strong> TLSECCertificateKeyFile <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.3.5rc4 and later
|
|
|
|
<p>
|
|
The <code>TLSECCertificateKeyFile</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>TLSECCertificateFile</code>, use this additional
|
|
directive to point to the file with the standalone private key. When
|
|
<code>TLSECCertificateFile</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>
|
|
TLSECCertificateKeyFile /etc/ftpd/server-ec-key.pem
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSECDHCurve">TLSECDHCurve</a></h3>
|
|
<strong>Syntax:</strong> TLSECDHCurve <em>curve</em><br>
|
|
<strong>Default:</strong> TLSECDHCurve prime256v1<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.6rc1 and later
|
|
|
|
<p>
|
|
The <code>TLSECDHCurve</code> directive specifies the EC curve to use for
|
|
ECDHE ciphers. To see the full list of curves supported by your OpenSSL
|
|
library, use:
|
|
<pre>
|
|
$ openssl ecparam -list_curves
|
|
</pre>
|
|
|
|
<p>
|
|
If you are using OpenSSL 1.0.2 or later, then you can specify multiple curve
|
|
names as a colon-separated list, <i>e.g.</i>:
|
|
<pre>
|
|
TLSECDHCurve secp521r1:prime256v1
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSEngine">TLSEngine</a></h3>
|
|
<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>
|
|
<h3><a name="TLSLog">TLSLog</a></h3>
|
|
<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>
|
|
Note that this path must <b>not</b> be to a world-writable directory and,
|
|
unless <code>AllowLogSymlinks</code> is explicitly set to <em>on</em>
|
|
(generally a bad idea), the path must <b>not</b> be a symbolic link.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSMasqueradeAddress">TLSMasqueradeAddress</a></h3>
|
|
<strong>Syntax:</strong> TLSMasqueradeAddress <em>ip-address|dns-name|device-name</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code><br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.5rc2 and later
|
|
|
|
<p>
|
|
The <code>TLSMasqueradeAddress</code> directive functions exactly like the
|
|
<a href="../modules/mod_core.html#MasqueradeAddress"><code>MasqueradeAddress</code></a>, except that it applies <b>only to FTPS sessions</b>. (Note that if
|
|
<em>both</em> <code>MasqueradeAddress</code> <b>and</b>
|
|
<code>TLSMasqueradeAddress</code> are configured, then the
|
|
<code>TLSMasqueradeAddress</code> directive will take precedence, but only
|
|
for FTPS sessions.)
|
|
|
|
<p>
|
|
<b><i>Discussion</i></b><br>
|
|
Why is something like <code>TLSMasqueradeAddress</code> needed? There are
|
|
cases where some sites run <code>proftpd</code> within a restricted VLAN/DMZ,
|
|
with some sort of firewall/proxy/router device which handles FTP and FTPS
|
|
connections from the Internet to that <code>proftpd</code> server:
|
|
<pre>
|
|
<i>client</i> <---> <i>firewall</i> <---> <i>load balancer</i> <---> <i>server</i>
|
|
</pre>
|
|
In many cases, the firewall/proxy/router device will look at the FTP responses
|
|
for the <code>PASV</code>/<code>EPSV</code> commands (in which
|
|
<code>proftpd</code> may be sending its internal, non-public IP address), and
|
|
rewrite the responses to have the IP address of the firewall/proxy/router
|
|
device.
|
|
|
|
<p>
|
|
Normally, the <code>MasqueradeAddress</code> directive can be used for such
|
|
cases, so that <code>proftpd</code> sends the configured address in the
|
|
<code>PASV</code>/<code>EPSV</code> responses. With that configuration,
|
|
the firewall/proxy/router device will not need to rewrite the responses.
|
|
And this approach works for FTPS sessions as well, where the
|
|
firewall/proxy/router device <b><i>cannot</i></b> rewrite the response due to
|
|
the SSL/TLS protection.
|
|
|
|
<p>
|
|
Sometimes, though, sites <b>want</b> their firewall/proxy/router device to be
|
|
able to properly rewrite FTP responses. But due to bugs/implementation details
|
|
in the firewall/proxy/router devices, <i>if</i> a
|
|
<code>PASV</code>/<code>EPSV</code> response contains a public IP address, the
|
|
device will drop/break that FTP connection.
|
|
|
|
<p>
|
|
This leaves the site in a case where it does <b>not</b> want to use
|
|
<code>MasqueradeAddress</code> (so that the device can properly rewrite FTP
|
|
responses), which works -- but only for plain FTP sessions. Yet the site
|
|
<b>does</b> want to use <code>MasqueradeAddress</code> -- but only for FTPS
|
|
sessions, since the device cannot rewrite FTPS responses.
|
|
|
|
<p>
|
|
For these situations, then, the <code>TLSMasqueradeAddress</code> directive
|
|
can/should be used: it provides <code>MasqueradeAddress</code> functionality,
|
|
but only for FTPS sessions.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSNextProtocol">TLSNextProtocol</a></h3>
|
|
<strong>Syntax:</strong> TLSNextProtocol <em>on|off</em><br>
|
|
<strong>Default:</strong> TLSNextProtocol on<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.6rc1 and later
|
|
|
|
<p>
|
|
The <code>TLSNextProtocol</code> directive toggles <code>mod_tls</code>' support
|
|
for the <a href="http://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation">ALPN</a> (and NPN) TLS extensions. These extensions are used to negotiate
|
|
the "next protocol" that will be once the SSL/TLS session is established; in
|
|
the case of <code>mod_tls</code>, that "next protocol" is <b>always</b> "ftp".
|
|
|
|
<p>
|
|
Some FTPS clients use the support of ALPN/NPN as a heuristic for knowing when
|
|
to use <a href="https://technotes.googlecode.com/git/falsestart.html">TLS False Start</a>, which can reduce the SSL/TLS handshake network latency. Initially
|
|
TLS clients used TLS False Start for any/all sites, but encountered
|
|
<a href="https://www.imperialviolet.org/2012/04/11/falsestart.html">issues</a>;
|
|
these clients (<i>e.g.</i> Chrome, Firefox, perhaps others) now only use
|
|
the TLS False Start optimization for ALPN/NPN-enabled SSL/TLS servers.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSOptions">TLSOptions</a></h3>
|
|
<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 NoSessionReuseRequired
|
|
</pre>
|
|
|
|
<p>
|
|
The currently implemented options are:
|
|
<ul>
|
|
<li><code>AllowClientRenegotiations</code><br>
|
|
<p>
|
|
The <code>mod_tls</code> will reject any SSL/TLS session renegotiation
|
|
attempts by the client, in order to mitigate any issues arising from the
|
|
<a href="http://www.educatedguesswork.org/2009/11/understanding_the_tls_renegoti.html">SSL/TLS session renegotiation vulnerability</a> (CVE-2009-3555)
|
|
or <a href="http://www.ietf.org/mail-archive/web/tls/current/msg07553.html">SSL/TLS session renegotiation DoS</a> (CVE-2011-1473). If, however, your
|
|
particular site or clients absolutely require support for client-initiated
|
|
SSL/TLS session renegotiations, then this option can be used.
|
|
<b>Not recommended.</b>
|
|
|
|
<p>
|
|
Note, however, that SSL/TLS session renegotiation requests that are
|
|
initiated by <code>mod_tls</code>, via the
|
|
<a href="#TLSRenegotiate"><code>TLSRenegotiate</code></a> directive, are
|
|
still handled (depending on the OpenSSL version).
|
|
</li>
|
|
|
|
<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 password <i>unprotected</i> before <code>mod_tls</code>
|
|
rejects the connection; those credentials could be intercepted and/or
|
|
manipulated before they reach the server. This results in a 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>AllowWeakDH</code><br>
|
|
<p>
|
|
The <code>mod_tls</code> will not use Diffie-Hellman groups of less
|
|
than 1024 bits, due to <a href="https://www.weakdh.org">weaknesses</a>
|
|
that can downgrade the security of an SSL/TLS session. If for any reason
|
|
your FTPS clients <b>require</b> smaller Diffie-Hellman groups, then
|
|
use this option.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.6rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>AllowWeakSecurity</code>
|
|
<p>
|
|
Sets the cryptographic security level to "zero", meaning that any/all
|
|
ciphers and key sizes are permitted. This option allows for operations
|
|
with <i>e.g.</i> CAs with weak messages digests, but is
|
|
<b>not recommended</b>. Use only when necessary.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.8rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>CommonNameRequired</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>CommonName</code> (CN) X509v3
|
|
value. Unless a <code>CommonName</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>EnableDiags</code><br>
|
|
Sets callbacks in the OpenSSL library such that <b>a lot</b> of
|
|
SSL/TLS protocol information is logged to the
|
|
<a href="#TLSLog"><code>TLSLog</code></a> file. This option is very
|
|
useful when debugging strange interactions with FTPS clients.
|
|
|
|
<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 summary="TLS Environment Variables">
|
|
<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>IgnoreSNI</code><br>
|
|
<p>
|
|
If the TLS client use the <a href="https://en.wikipedia.org/wiki/Server_Name_Indication">SNI</a> (Server Name Indication) as part of the TLS handshake,
|
|
then <code>mod_tls</code> will attempt to use a name-based
|
|
<code><VirtualHost></code> matching that name, if found. Use this
|
|
option to disable this behavior for any reason.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.7rc3</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>NoAutoECDH</code><br>
|
|
<p>
|
|
If OpenSSL-1.0.2 or later is used, then <code>mod_tls</code> will
|
|
attempt to automatically negotiate the best EC curve to use, when needed.
|
|
Use this option to disable that automatic behavior for any reason.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.6rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>NoEmptyFragments</code><br>
|
|
<p>
|
|
In order to prevent certain attacks (<i>e.g.</i> the so-called
|
|
<a href="http://www.kb.cert.org/vuls/id/864643">"BEAST"
|
|
attack</a>), the <code>mod_tls</code> module was changed to use OpenSSL's
|
|
builtin countermeasure of inserting <a href="http://www.openssl.org/~bodo/tls-cbc.txt">empty fragments</a>. However, some browsers/clients may not handle
|
|
such empty fragments well. Use this <code>NoEmptyFragments</code>
|
|
TLSOption in order to interoperate with such clients, with risk of losing
|
|
the protective countermeasure.
|
|
|
|
<p>
|
|
Note that this protective countermeasure only applies to SSLv3 and TLSv1
|
|
sessions; it does not affect TLSv1.1 or TLSv1.2 sessions.
|
|
|
|
<p>
|
|
Added in ProFTPD 1.3.4rc4.
|
|
|
|
<p>
|
|
<li><code>NoSessionReuseRequired</code><br>
|
|
<p>
|
|
As of ProFTPD 1.3.3rc1, <code>mod_tls</code> only accepts SSL/TLS data
|
|
connections that reuse the SSL session of the control connection, as a
|
|
security measure. Unfortunately, there are some clients (<i>e.g.</i>
|
|
curl) which do not reuse SSL sessions.
|
|
|
|
<p>
|
|
To relax the requirement that the SSL session from the control connection
|
|
be reused for data connections, use the following in the proftpd.conf:
|
|
<pre>
|
|
<IfModule mod_tls.c>
|
|
...
|
|
TLSOptions NoSessionReuseRequired
|
|
...
|
|
</IfModule>
|
|
</pre>
|
|
|
|
<p>
|
|
<li><code>StdEnvVars</code><br>
|
|
<p>
|
|
Sets the following environment variables, if applicable. These environment
|
|
variables are then available 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 summary="Standard Environment Variables">
|
|
<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_NAME</code></td>
|
|
<td>Server name requested via Server Name Indication (SNI), if present</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>UseImplicitSSL</code><br>
|
|
<p>
|
|
This option will cause the <code>mod_tls</code> module to handle <b>all</b>
|
|
connections as if they are SSL connections implicitly; the client does
|
|
<i>not</i> need to send the <code>AUTH TLS</code> FTP command. This can
|
|
cause issues for FTPS clients which are expecting explicit FTPS, not
|
|
implicit FTPS.
|
|
|
|
<p>
|
|
Thus if the <code>UseImplicitSSL</code> option is used, you will want to
|
|
have a separate <code><VirtualHost></code> section with
|
|
a different port number just for those clients which require/expect
|
|
implicit FTPS. For example:
|
|
<pre>
|
|
<IfModule mod_tls.c>
|
|
<VirtualHost a.b.c.d>
|
|
TLSEngine on
|
|
TLSOptions UseImplicitSSL
|
|
|
|
# The "standard" implicit FTPS port is 990
|
|
Port 990
|
|
...
|
|
</VirtualHost>
|
|
</IfModule>
|
|
</pre>
|
|
|
|
<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>
|
|
<h3><a name="TLSPKCS12File">TLSPKCS12File</a></h3>
|
|
<strong>Syntax:</strong> TLSPKCS12File <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.3.3rc1 and later
|
|
|
|
<p>
|
|
The <code>TLSPKCS12ile</code> directive points to the PKCS#12 file containing
|
|
the certificate file and its private key for the server.
|
|
|
|
<p>
|
|
If the PKCS#12 file is protected with a passphrase, the administrator will
|
|
be prompted for the passphrase when the daemon starts up, and when the daemon
|
|
is restarted. Alternatively, the <code>TLSPassPhraseProvider</code>
|
|
directive can be used to supply a source for that passphrase.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
TLSPKCS12File /etc/ftpd/server-cert.p12
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSPassPhraseProvider">TLSPassPhraseProvider</a></h3>
|
|
<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>
|
|
<h3><a name="TLSPreSharedKey">TLSPreSharedKey</a></h3>
|
|
<strong>Syntax:</strong> TLSPreSharedKey <em>identity</em> <em>key-info</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.6rc1 and later
|
|
|
|
<p>
|
|
The <code>TLSPreSharedKey</code> directive is used to configure a <em>pre-shared
|
|
key</em> (PSK), for use in
|
|
<a href="http://en.wikipedia.org/wiki/TLS-PSK">TLS-PSK</a> ciphersuites. Each
|
|
PSK has an <em>identity</em> (a string/name used by clients to request the use
|
|
of that PSK), and the actual key data. The key data may be encoded in different
|
|
ways; the <code>TLSPreSharedKey</code> directive requires that the data be
|
|
hex-encoded, as indicated in the <em>key-info</em> parameter.
|
|
|
|
<p>
|
|
The <em>key-info</em> parameter is comprised of: the type of encoding used for
|
|
the key data, and the full path to the key file. Only "hex" encoding is
|
|
supported right now. Thus an example <code>TLSPreSharedKey</code> directive
|
|
would be:
|
|
<pre>
|
|
TLSPreSharedKey psk-name hex:/path/to/psk.key
|
|
</pre>
|
|
The configured file <b>cannot be world-readable or world-writable</b>; the
|
|
<code>mod_tls</code> module will skip/ignore such insecure permissions.
|
|
|
|
<p>
|
|
To generate this shared key (which is just a randomly generated bit of data),
|
|
you can use:
|
|
<pre>
|
|
$ openssl rand 80 -out /path/to/identity.key -hex
|
|
</pre>
|
|
Note that <code>TLSPreSharedKey</code> requires at least 20 bytes of key data.
|
|
Have generated the random key data, tell <code>mod_tls</code> to use it via:
|
|
<pre>
|
|
TLSPreSharedKey identity hex:/path/to/identity.key
|
|
</pre>
|
|
|
|
<p>
|
|
Multiple <code>TLSPreSharedKey</code> directives can be used to configure
|
|
different PSKs for different identity names.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSProtocol">TLSProtocol</a></h3>
|
|
<strong>Syntax:</strong> TLSProtocol <em>protocol1</em> ... <em>protocolN</em><br>
|
|
<strong>Default:</strong> TLSv1<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>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 summary="TLS Protocol Versions">
|
|
<tr>
|
|
<td><code>SSLv3</code></td>
|
|
<td>Allow only SSLv3</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>TLSv1</code></td>
|
|
<td>Allow only TLSv1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>TLSv1.1</code></td>
|
|
<td>Allow only TLSv1.1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>TLSv1.2</code></td>
|
|
<td>Allow only TLSv1.2</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>TLSv1.3</code></td>
|
|
<td>Allow only TLSv1.3</td>
|
|
</tr>
|
|
|
|
</table>
|
|
To support both SSLv3 and TLSv1, simply list both parameters for the
|
|
<code>TLSProtocol</code> directive, <i>e.g.</i>:
|
|
<pre>
|
|
TLSProtocol SSLv3 TLSv1
|
|
</pre>
|
|
|
|
<p>
|
|
Note that the parameter "SSLv23" is supported as a legacy style for saying
|
|
"all versions".
|
|
|
|
<p>
|
|
All use of SSLv2 is disabled. SSLv2 <b>should not</b> be used. As of
|
|
<code>proftpd-1.3.6rc1</code>, SSLv3 support has been disabled as well.
|
|
|
|
<p>
|
|
In <code>proftpd-1.3.6rc2</code> and later, you can use the
|
|
<code>TLSProtocol</code> directive in a different manner, to <em>add</em>
|
|
or <em>subtract</em> protocol support. For example, to enable all protocols
|
|
<b>except</b> SSLv3, you can use:
|
|
<pre>
|
|
TLSProtocol ALL -SSLv3
|
|
</pre>
|
|
Using the directive in this manner requires that "ALL" be the <b>first</b>
|
|
parameter, <i>and</i> that all protocols have either a <code>+</code>
|
|
(<em>add</em>) or <code>-</code> (<em>subtract</em>) prefix. "ALL" will
|
|
always be expanded to all of the supported SSL/TLS protocols known by
|
|
<code>mod_tls</code> and supported by <code>OpenSSL</code>.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSRandomSeed">TLSRandomSeed</a></h3>
|
|
<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>
|
|
<h3><a name="TLSRenegotiate">TLSRenegotiate</a></h3>
|
|
<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/TLS
|
|
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 threshold. 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>
|
|
In OpenSSL 0.9.8l and later, SSL/TLS session renegotiations are automatically
|
|
disabled. In order to use renegotiations as configured by the
|
|
<code>TLSRenegotiate</code> directive, you must <i>also</i> explicitly allow
|
|
them via:
|
|
<pre>
|
|
# Allow renegotiations (not recommended; see CVE-2009-3555, CVE-2011-1473)
|
|
TLSOptions AllowClientRenegotiations
|
|
</pre>
|
|
|
|
<p>
|
|
The TLSv1.3 protocol does not support renegotiations, but it <i>does</i> support
|
|
updating the session keys, which is the primary goal/function of the
|
|
<code>TLSRenegotiate</code> directive. Thus using OpenSSL 1.1.1 and later,
|
|
key updates will be requested for control and data sessions for TLSv1.3
|
|
sessions.
|
|
|
|
<p>
|
|
Use <em>none</em> to explicitly disable all renegotiation requirements.
|
|
|
|
<p>
|
|
Examples:
|
|
<pre>
|
|
# Allow renegotiations
|
|
TLSOptions AllowClientRenegotiations
|
|
|
|
# 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 thresholds using one directive
|
|
TLSRenegotiate ctrl 3600 data 512000 required off timeout 300
|
|
|
|
# To disable renegotiations entirely
|
|
TLSRenegotiate none
|
|
</pre>
|
|
|
|
<p>
|
|
<b>Note</b> that in ProFTPD 1.3.8rc2 and later, the <em>default</em> behavior
|
|
of <code>TLSRenegotiate</code> changed, such that <code>mod_tls</code> will
|
|
not request SSL/TLS renegotiations <em>at all</em> for control <i>or</i>
|
|
data connections. If renegotiations are <i>explicitly</i> configured via
|
|
<code>TLSRenegotiate</code>, they will be used.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSRequired">TLSRequired</a></h3>
|
|
<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>
|
|
It is <i>also</i> possible to configure a policy which <i>rejects</i> use
|
|
of SSL/TLS for protecting the data channel. Some sites may wish to use
|
|
such a policy in order to protect the control channels of their clients, but
|
|
to prevent the data transfers from consuming too much CPU. The
|
|
<code>TLSRequired</code> directive can be set such that an FTPS client
|
|
requesting protection of the data channel, using the <code>PROT</code> command,
|
|
will have that command refused. To configure such a policy, use one of
|
|
the following:
|
|
<pre>
|
|
# If the client wishes to protect the control channel, allow it; but reject
|
|
# any attempt to protect the data channel
|
|
TLSRequired !data
|
|
|
|
# <b>Require</b> protection on the control channel, but reject protection of the
|
|
# data channel
|
|
TLSRequired ctrl+!data
|
|
|
|
# <b>Require</b> protection on the control channel for <i>authentication</i> (but not
|
|
# after), and reject protection of the data channel
|
|
TLSRequired auth+!data
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSRSACertificateFile">TLSRSACertificateFile</a></h3>
|
|
<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>
|
|
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. Alternatively, the <code>TLSPassPhraseProvider</code>
|
|
directive can be used to supply a source for that passphrase.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
TLSRSACertificateFile /etc/ftpd/server-rsa-cert.pem
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSRSACertificateKeyFile">TLSRSACertificateKeyFile</a></h3>
|
|
<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>
|
|
<h3><a name="TLSServerCipherPreference">TLSServerCipherPreference</a></h3>
|
|
<strong>Syntax:</strong> TLSServerCipherPreference <em>on|off</em><br>
|
|
<strong>Default:</strong> Depends<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.5rc1 and later
|
|
|
|
<p>
|
|
When choosing a cipher during an SSLv3 or TLSv1 handshake, normally the
|
|
<i>client's</i> ciphersuite preference is used. If the
|
|
<code>TLSServerCipherPreference</code> directive is enabled, then the
|
|
<i>server's</i> ciphersuite preference will be used instead.
|
|
|
|
<p>
|
|
For example:
|
|
<pre>
|
|
TLSServerCipherPreference on
|
|
</pre>
|
|
|
|
<p>
|
|
Note that starting with ProFTPD 1.3.7rc1, <code>TLSServerCipherPreference</code>
|
|
is <em>enabled</em> by default.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSServerInfoFile">TLSServerInfoFile</a></h3>
|
|
<strong>Syntax:</strong> TLSServerInfoFile <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.3.6rc2 and later
|
|
|
|
<p>
|
|
The <code>TLSServerInfoFile</code> directive uses the configured <em>file</em>
|
|
as custom TLS extensions. See the OpenSSL documentation for the <a href="https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_serverinfo_file.html"><code>SSL_CTX_use_serverinfo_file()</code></a> for more information.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSSessionCache">TLSSessionCache</a></h3>
|
|
<strong>Syntax:</strong> TLSSessionCache <em>"off"|type:/info [timeout]</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config<br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.3rc1 and later
|
|
|
|
<p>
|
|
The <code>TLSSessionCache</code> directive configures an external SSL session
|
|
cache, which can be used for storing and sharing SSL sessions across multiple
|
|
processes. An external SSL session cache is an optional facility which speeds
|
|
up parallel FTPS session connections.
|
|
|
|
<p>
|
|
Modern FTP clients often create multiple simultaneous connections to an FTP
|
|
server, for downloading different chunks of data in parallel. Each FTP
|
|
connection will be handled by a different server process, and each one
|
|
will be required to perform a full SSL/TLS handshake. By using an
|
|
external SSL session cache, a cached SSL session can be "resumed" by the
|
|
client, which avoids the expensive portions of the handshake. FTPS clients
|
|
which cache the SSL session locally can also attempt to resume that cached
|
|
session at a later date; if the server still has that same session cached,
|
|
the FTPS client can again avoid the expensive portions of the handshake and
|
|
resume its previous SSL session.
|
|
|
|
<p>
|
|
If the <code>TLSSessionCache</code> directive is <i>not</i> used, then
|
|
OpenSSL's default internal SSL session caching will be used. Thus multiple
|
|
SSL sessions to the same server process (<i>e.g.</i> for FTP data transfers)
|
|
will benefit from the speedup, but parallel simultaneous FTP connections from
|
|
the same FTPS client will each need to perform the full SSL/TLS handshake.
|
|
By default, OpenSSL caches SSL sessions for 300 seconds (5 minutes). If
|
|
your FTP sessions last longer than this (<i>e.g.</i> for downloading large
|
|
files), you may need to configure a longer cache lifetime using:
|
|
<pre>
|
|
# Configure OpenSSL's internal caching to be 1800 seconds (30 minutes)
|
|
TLSSessionCache internal: 1800
|
|
</pre>
|
|
|
|
<p>
|
|
The <em>type</em> and <em>info</em> parameters all depend on the module
|
|
implementing the external SSL session cache being configured. For example,
|
|
for using a shared memory external SSL session cache, see the
|
|
<a href="mod_tls_shmcache.html"><code>mod_tls_shmcache</code></a> documentation.
|
|
|
|
<p>
|
|
The optional <em>timeout</em> parameters sets the time-to-live, in seconds, for
|
|
the SSL session datal stored in the external SSL session cache. It can be set
|
|
as low as 15 for testing, but should be set to higher values like 600 in real
|
|
life. The default timeout is 1800 seconds (30 minutes). <b>Note</b> that to
|
|
ensure that the session cache is <em>aggressively</em> pruned of expired
|
|
sessions, <b>each</b> FTP session, upon ending, will flush <b>any</b> expired
|
|
sessions from the session cache.
|
|
|
|
<p>
|
|
Use of SSL session caching can be disabled entirely by using:
|
|
<pre>
|
|
TLSSessionCache off
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSSessionTicketKeys">TLSSessionTicketKeys</a></h3>
|
|
<strong>Syntax:</strong> TLSSessionTicketKeys [age <em>secs</em>] [count <em>number</em>]<br>
|
|
<strong>Default:</strong> TLSSessionTicketKeys age 12h count 25<br>
|
|
<strong>Context:</strong> server config</br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.6rc2 and later
|
|
|
|
<p>
|
|
The <code>TLSSessionTicketKeys</code> directive can be used to control how
|
|
often <code>mod_tls</code> generates new session ticket keys (assuming that
|
|
<a href="#TLSSessionTickets"><code>TLSSessionTickets</code></a> is enabled),
|
|
and how many ticket keys will be kept in one time in memory.
|
|
|
|
<p>
|
|
By default, <code>mod_tls</code> expires a session ticket key after 12 hours;
|
|
this can be changed using the <em>age</em> parameter, to specify a maximum
|
|
age. <b>Note</b> that the <i>minimum</i> key age is 60 seconds.
|
|
|
|
<p>
|
|
Only a maximum of 25 session ticket keys will be kept in memory by default;
|
|
older/expired keys will be destroyed. This maximum count of keys can
|
|
be changed using the <em>count</em> parameter. <b>Note</b> that there is a
|
|
minimum count (1) of ticket keys; attempting to specify a smaller <em>count</em>
|
|
is a configuration error.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSSessionTickets">TLSSessionTickets</a></h3>
|
|
<strong>Syntax:</strong> TLSSessionTickets <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.3.6rc2 and later
|
|
|
|
<p>
|
|
The <code>TLSSessionTickets</code> directive enables the use of TLS
|
|
"session tickets" (see <a href="http://www.faqs.org/rfcs/rfc5077.html">RFC 5077</a>), which allow for session resumption, similar to TLS session caching.
|
|
|
|
<p>
|
|
The <code>mod_tls</code> module does <b>not</b> support configuration/use of
|
|
a static session ticket <em>key</em>, unlike Apache or nginx. Instead,
|
|
<code>mod_tls</code> <i>always</i> randomly generates its own session ticket
|
|
keys. These keys are only kept in memory, and are automatically generated
|
|
on a schedule; older keys are destroyed automatically.
|
|
|
|
<p>
|
|
When a session is resumed using a session ticket encrypted with an older
|
|
session ticket key (which has not yet expired), the <code>mod_tls</code> will
|
|
honor that session ticket, <i>but</i> will also <b>renew</b> the encryption
|
|
of the session ticket using a newer session ticket key. Session tickets
|
|
encrypted with keys which have expired will not be honored, and a full TLS
|
|
handshake will occur.
|
|
|
|
<p>
|
|
For control over the key expiration and generation schedule, use the
|
|
<a href="#TLSSessionTicketKeys"><code>TLSSessionTicketKeys</code></a>
|
|
directive.
|
|
|
|
<p>
|
|
<b>Note</b>: TLSv1.3 sessions <b>require</b> the use of session tickets,
|
|
as the protocol favors stateless tickets <i>versus</i> stateful server-side
|
|
session IDs for session resumption. Thus for TLSv1.3 sessions, the
|
|
<code>TLSSessionTickets</code> directive is <i>ignored</i>, and session
|
|
tickets are supported.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSStapling">TLSStapling</a></h3>
|
|
<strong>Syntax:</strong> TLSStapling <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.3.6rc2 and later
|
|
|
|
<p>
|
|
The <code>TLSStapling</code> directive enables
|
|
<a href="https://en.wikipedia.org/wiki/OCSP_stapling">OCSP stapling</a>,
|
|
as defined by the "Certificate Status Request" TLS extension
|
|
(<a href="http://www.faqs.org/rfcs/rfc6066.html">RFC 6066</a>). If
|
|
<code>TLSStapling</code> is enabled, <b>and</b> the certificate status request
|
|
extension is used by the SSL/TLS client, then <code>mod_tls</code> will
|
|
include an OCSP response for the server certificate, in the TLS handshake.
|
|
|
|
<p>
|
|
By default, <code>TLSStapling</code> is <em>off</em>, but will automatically
|
|
be enabled if a <a href="#TLSStaplingCache"><code>TLSStaplingCache</code></a>
|
|
is configured.
|
|
|
|
<p>
|
|
See also: <a href="#TLSStaplingCache"><code>TLSStaplingCache</code></a>,
|
|
<a href="#TLSStaplingOptions"><code>TLSStaplingOptions</code></a>,
|
|
<a href="#TLSStaplingResponder"><code>TLSStaplingResponder</code></a>, and
|
|
<a href="#TLSStaplingTimeout"><code>TLSStaplingTimeout</code></a>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSStaplingCache">TLSStaplingCache</a></h3>
|
|
<strong>Syntax:</strong> TLSStaplingCache <em>type:/info</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config<br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.6rc2 and later
|
|
|
|
<p>
|
|
The <code>TLSStaplingCache</code> directive configures an external OCSP response
|
|
cache, which can be used for storing and sharing OCSP responses across multiple
|
|
processes. An external OCSP response cache is an optional facility which
|
|
speeds up TLS handshakes when
|
|
<a href="#TLSStapling"><code>TLSStapling</code></a> is enabled.
|
|
|
|
<p>
|
|
The <em>type</em> and <em>info</em> parameters all depend on the module
|
|
implementing the external OCSP response cache being configured. For example,
|
|
for using a filesystem-based external OCSP response cache, see the
|
|
<a href="mod_tls_fscache.html"><code>mod_tls_fscache</code></a> documentation,
|
|
or see <a href="mod_tls_shmcache.html"><code>mod_tls_shmcache</code></a> for
|
|
a shared memory-based OCSP response cache, or
|
|
<a href="mod_tls_memcache.html"><code>mod_tls_memcache</code></a> for using
|
|
memcached servers as an OCSP response cache.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSStaplingOptions">TLSStaplingOptions</a></h3>
|
|
<strong>Syntax:</strong> TLSStaplingOptions <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.3.6rc2 and later
|
|
|
|
<p>
|
|
The <code>TLSStaplingOptions</code> directive configures various optional
|
|
behaviors of <code>mod_tls</code> when querying OCSP responders.
|
|
|
|
<p>
|
|
The currently implemented options are:
|
|
<ul>
|
|
<li><code>NoFakeTryLater</code><br>
|
|
<p>
|
|
If the TLS client requests a stapled OCSP response, yet <code>mod_tls</code>
|
|
cannot provide one (<i>e.g.</i> due to inability to contact the OCSP
|
|
responder), the module will provide a fake <code>tryLater</code> OCSP
|
|
response. Some client implementations, however, have trouble with such
|
|
fake OCSP responses; use this option to disable the use of such fake OCSP
|
|
response:
|
|
<pre>
|
|
# Skip using a fake tryLater OCSP response, if we cannot obtain one from
|
|
# an OCSP responder
|
|
TLSStaplingOptions NoFakeTryLater
|
|
</pre>
|
|
<b>However</b>, a fake <code>tryLater</code> OCSP response <b>might still
|
|
be emitted</b>, even if this option is used, if the server certificate
|
|
in question bears the "must staple" TLS feature; see
|
|
<a href="https://tools.ietf.org/html/rfc7633#section-3">RFC 7633</a>. In
|
|
such cases, <code>mod_tls</code> is <em>required</em> to staple an OCSP
|
|
response.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.7rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>NoNonce</code><br>
|
|
<p>
|
|
To defend against replay attacks of OCSP responses, the protocol allows
|
|
for a nonce to be included in the request; this nonce is then expected
|
|
to be in the OCSP response. However, many OCSP responders pre-generate
|
|
the OCSP responses, as it less computationally expensive to do so. Thus
|
|
to tell <code>mod_tls</code> to not include a nonce in its OCSP request
|
|
(and not expect to see that nonce in the OCSP response), use this option:
|
|
<pre>
|
|
# Many OCSP responders pregenerate their responses, and thus cannot
|
|
# include nonces in the response.
|
|
TLSStaplingOptions NoNonce
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSStaplingResponder">TLSStaplingResponder</a></h3>
|
|
<strong>Syntax:</strong> TLSStaplingResponder <em>url</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.6rc2 and later
|
|
|
|
<p>
|
|
The <code>TLSStaplingResponder</code> directive overrides the URL of the OCSP
|
|
responder specified in the "Authority Information Access" certificate extension.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
# Use our own custom OCSP responder
|
|
TLSStaplingResponder http://gw.example.com/ocsp/
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSStaplingTimeout">TLSStaplingTimeout</a></h3>
|
|
<strong>Syntax:</strong> TLSStaplingTimeout <em>secs</em><br>
|
|
<strong>Default:</strong> 10s<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.6rc2 and later
|
|
|
|
<p>
|
|
The <code>TLSStaplingTimeout</code> directive sets the timeout for queries
|
|
to OCSP responders when <code>TLSStapling</code> is enabled, and
|
|
<code>mod_tls</code> is querying a responder for OCSP stapling purposes.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSTimeoutHandshake">TLSTimeoutHandshake</a></h3>
|
|
<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>
|
|
<h3><a name="TLSUserName">TLSUserName</a></h3>
|
|
<strong>Syntax:</strong> TLSUserName <em>attribute</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.3.5rc2 and later
|
|
|
|
<p>
|
|
The <code>TLSUserName</code> directive configures which <em>attribute</em>
|
|
of a client certificate to match against the name provided by the FTPS client
|
|
in its <code>USER</code> command. If the certificate <em>attribute</em>
|
|
value matches the <code>USER</code> name, the user is considered to be
|
|
authenticated <b>without requiring that password be sent over the network</b>.
|
|
|
|
<p>
|
|
The <em>attribute</em> can either be "CommonName" (to match the CN of the
|
|
client certificate to the requested <code>USER</code> name),
|
|
"EmailSubjAltName" (to match <b>any</b> Email Subject Alternative Names (SANs)
|
|
to the requested <code>USER</code> name), or a custom OID.
|
|
|
|
<p>
|
|
Examples:
|
|
<pre>
|
|
# Match the CN
|
|
TLSUserName CommonName
|
|
|
|
# Match any Email SANs
|
|
TLSUserName EmailSubjAltName
|
|
|
|
# Match specific (custom) OID
|
|
TLSUserName 1.2.3.4.5
|
|
</pre>
|
|
|
|
<p>
|
|
Note that for the <code>TLSUserName</code> directive to be effective,
|
|
<code>mod_tls</code> has to be configured to request that clients provide
|
|
certificates, <i>i.e.</i>:
|
|
<pre>
|
|
# Verify clients
|
|
TLSVerifyClient optional
|
|
|
|
# and possibly verify the user based on the client certs
|
|
TLSUserName CommonName
|
|
</pre>
|
|
|
|
<p>
|
|
See also: <a href="#TLSVerifyClient"><code>TLSVerifyClient</code></a>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSVerifyClient">TLSVerifyClient</a></h3>
|
|
<strong>Syntax:</strong> TLSVerifyClient <em>on|off|optional</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 not request the client certificate while establishing an SSL/TLS session.
|
|
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. If <em>optional</em>, then
|
|
<code>mod_tls</code> will <i>request</i> that a client send its certificate,
|
|
but will not fail the handshake if the client fails to provide a certificate.
|
|
|
|
<p>
|
|
See also: <a href="#TLSOptions"><code>TLSOptions</code></a>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSVerifyDepth">TLSVerifyDepth</a></h3>
|
|
<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>
|
|
<h3><a name="TLSVerifyOrder">TLSVerifyOrder</a></h3>
|
|
<strong>Syntax:</strong> TLSVerifyOrder <em>crl|ocsp</em><br>
|
|
<strong>Default:</strong> crl<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc1 and later
|
|
|
|
<p>
|
|
The <code>TLSVerifyOrder</code> directive configures how the
|
|
<code>mod_tls</code> will verify the certificates presented by clients, if
|
|
at all. Unless <code>TLSVerifyClient</code> is <em>on</em>, the
|
|
<code>TLSVerifyOrder</code> directive is not needed.
|
|
|
|
<p>
|
|
By default, the <code>mod_tls</code> module will include any CRLs (Certificate
|
|
Revocation List) that may have been configured via the
|
|
<code>TLSCARevocationFile</code> and/or <code>TLSCARevocationPath</code>
|
|
directives. This default behavior is the equivalent of configuring the
|
|
<code>TLSVerifyOrder</code> to use CRLs, <i>e.g.</i>:
|
|
<pre>
|
|
TLSVerifyOrder crl
|
|
</pre>
|
|
|
|
<p>
|
|
Another way of checking the validity of the client certificate is to use
|
|
the Online Certificate Status Protocol (OCSP), defined in
|
|
<a href="http://www.faqs.org/rfcs/rfc2560.html">RFC 2560</a>. To configure
|
|
the <code>mod_tls</code> module to use OCSP when verifying, use:
|
|
<pre>
|
|
TLSVerifyOrder ocsp
|
|
</pre>
|
|
Note that at is possible for <code>mod_tls</code> to use both CRLs <i>and</i>
|
|
OCSP when verifying certificates. Simply use <code>TLSVerifyOrder</code>
|
|
to configure the order in which <code>mod_tls</code> should use the various
|
|
verification mechanisms:
|
|
<pre>
|
|
TLSVerifyOrder ocsp crl
|
|
</pre>
|
|
Verification ends when a mechanism can successfully verify the certificate.
|
|
|
|
<p>
|
|
See also: <a href="#TLSCARevocationFile"><code>TLSCARevocationFile</code></a>,
|
|
<a href="#TLSCARevocationPath"><code>TLSCARevocationPath</code></a>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="TLSVerifyServer">TLSVerifyServer</a></h3>
|
|
<strong>Syntax:</strong> TLSVerifyServer <em>on|off|NoReverseDNS</em><br>
|
|
<strong>Default:</strong> on<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_tls<br>
|
|
<strong>Compatibility:</strong> 1.3.5rc4 and later
|
|
|
|
<p>
|
|
The <code>TLSVerifyServer</code> directive configures how <code>mod_tls</code>
|
|
handles certificates presented by <em>other servers</em>, during a secure
|
|
site-to-site (<i>a.k.a.</i> "secure FXP") transfer. If <em>off</em>, the
|
|
module will accept the certificate and establish an SSL/TLS session, but will
|
|
<b>not</b> verify the certificate. If <em>on</em>, the module will verify a
|
|
server's certificate and, furthermore, will fail all SSL handshake attempts
|
|
<b>unless</b> the server presents a valid certificate.
|
|
|
|
<p>
|
|
The <em>NoReverseDNS</em> parameter tells <code>mod_tls</code> to validate
|
|
the server's certificate, <b>but</b> to only validate it based on IP address,
|
|
rather than using DNS names (for <i>e.g.</i> CommonName (CN) and DNS
|
|
SubjectAltName (SAN) checks). The recommended certificate validation
|
|
techniques use DNS names, so using <em>NoReverseDNS</em> performs less
|
|
strict validations. Unfortunately, in most secure site-to-site transfers,
|
|
this setting may be required since FTP site-to-site transfers send IP
|
|
addresses, not DNS names, in the command which establish the data transfer.
|
|
|
|
<p>
|
|
See also: <a href="#TLSVerifyClient"><code>TLSVerifyClient</code></a>,
|
|
<a href="#TLSVerifyDepth"><code>TLSVerifyDepth</code></a>
|
|
|
|
<p>
|
|
<hr>
|
|
<h2>Control Actions</h2>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="tls_sesscache_clear"><code>tls sesscache clear</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl tls sesscache clear<br>
|
|
<strong>Purpose:</strong> Clears all cached sessions from the SSL session cache<br>
|
|
|
|
<p>
|
|
The <code>tls sesscache clear</code> action is used to clear all cached
|
|
sessions, whether they have expired or not, from the configured external
|
|
SSL session cache. For example:
|
|
<pre>
|
|
# ftpdctl tls sesscache clear
|
|
ftpdctl: tls sesscache: cleared 1 session from 'shm' session cache
|
|
</pre>
|
|
|
|
<p>
|
|
See also: <a href="#TLSSessionCache"><code>TLSSessionCache</code></a>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="tls_sesscache_info"><code>tls sesscache info</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl tls sesscache info <em>[-v]</em><br>
|
|
<strong>Purpose:</strong> Displays status of session cache<br>
|
|
|
|
<p>
|
|
The <code>tls sesscache info</code> action is used to display information
|
|
about the configured external SSL session cache. If the optional <em>-v</em>
|
|
command-line option is used, then information about each cached session
|
|
will also be displayed.
|
|
|
|
<p>
|
|
For example:
|
|
<pre>
|
|
# ftpdctl tls sesscache info -v
|
|
ftpdctl: Shared memory (shm) SSL session cache provided by mod_tls_shmcache/0.1
|
|
ftpdctl:
|
|
ftpdctl: Shared memory segment ID: 589824
|
|
ftpdctl: Shared memory segment size: 1576960 bytes
|
|
ftpdctl: Shared memory cache created on: Mon Mar 9 21:18:05 2009
|
|
ftpdctl: Shared memory attach count: 1
|
|
ftpdctl:
|
|
ftpdctl: Max session cache size: 153
|
|
ftpdctl: Current session cache size: 1
|
|
ftpdctl:
|
|
ftpdctl: Cache lifetime hits: 0
|
|
ftpdctl: Cache lifetime misses: 0
|
|
ftpdctl:
|
|
ftpdctl: Cache lifetime sessions stored: 1
|
|
ftpdctl: Cache lifetime sessions deleted: 0
|
|
ftpdctl: Cache lifetime sessions expired: 0
|
|
ftpdctl:
|
|
ftpdctl: Cache lifetime errors handling sessions in cache: 0
|
|
ftpdctl: Cache lifetime sessions exceeding max entry size: 0
|
|
ftpdctl:
|
|
ftpdctl: Cached sessions:
|
|
ftpdctl: -----BEGIN SSL SESSION PARAMETERS-----
|
|
ftpdctl: Session ID: A9BB647E236BAB0EF128FE9EAD2ABEC6F8E65C9EB8F050A07D1F0F66EC3019DC
|
|
ftpdctl: Session ID Context: 00000000
|
|
ftpdctl: Protocol: TLSv1
|
|
ftpdctl: Started: Mon Mar 9 21:19:20 2009
|
|
ftpdctl: Expires: Tue Mar 10 21:19:20 2009 (86400 secs)
|
|
ftpdctl: -----END SSL SESSION PARAMETERS-----
|
|
</pre>
|
|
|
|
<p>
|
|
See also: <a href="#TLSSessionCache"><code>TLSSessionCache</code></a>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="tls_sesscache_remove"><code>tls sesscache remove</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl tls sesscache remove<br>
|
|
<strong>Purpose:</strong> Removes the external SSL session cache<br>
|
|
|
|
<p>
|
|
The <code>tls sesscache remove</code> action is used to remove the
|
|
external SSL session cache entirely. Depending on the actual module providing
|
|
the session cache, this may or may not be implemented.
|
|
|
|
<p>
|
|
For example:
|
|
<pre>
|
|
# ftpdctl tls sesscache remove
|
|
ftpdctl: tls sesscache: removed 'shm' session cache
|
|
</pre>
|
|
|
|
<p>
|
|
See also: <a href="#TLSSessionCache"><code>TLSSessionCache</code></a>
|
|
|
|
<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://httpd.apache.org/docs/2.4/mod/mod_ssl.html">http://httpd.apache.org/docs/2.4/mod/mod_ssl.html</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>
|
|
<b>Logging</b><br>
|
|
The <code>mod_tls</code> module supports <a href="../howto/Tracing.html">trace logging</a>, via the module-specific log channels:
|
|
<ul>
|
|
<li>tls
|
|
</ul>
|
|
Thus for trace logging, to aid in debugging, you would use the following in
|
|
your <code>proftpd.conf</code>:
|
|
<pre>
|
|
TraceLog /path/to/ftpd/trace.log
|
|
Trace tls:20
|
|
</pre>
|
|
This trace logging can generate large files; it is intended for debugging use
|
|
only, and should be removed from any production configuration.
|
|
|
|
<p>
|
|
<b>Note Variables</b><br>
|
|
The <code>mod_tls</code> module provides the following <em>notes</em>, for use
|
|
via the <code>%{note:...}</code> syntax:
|
|
<ul>
|
|
<li><code>FTPS</code>
|
|
<li><code>TLS_PROTOCOL</code>
|
|
<li><code>TLS_CIPHER</code>
|
|
<li><code>TLS_LIBRARY_VERSION</code>
|
|
</ul>
|
|
These <em>notes</em> are similar to the environment variables provided when
|
|
<code>TLSOptions StdEnvVars</code> is used.
|
|
|
|
<p><a name="FAQ">
|
|
<b>Frequently Asked Questions</b><br>
|
|
|
|
<p><a name="TLSJavaDH">
|
|
<font color=red>Question</font>: When I use a Java client to connect to my
|
|
<code>proftpd</code> server using FTPS, it fails with exceptions such as:
|
|
<pre>
|
|
java.lang.RuntimeException: Could not generate DH keypair and java.security.InvalidAlgorithmParameterException: Prime size must be multiple of 64, and can only range from 512 to 1024 (inclusive)
|
|
</pre>
|
|
How can I fix this?<br>
|
|
<font color=blue>Answer</font>: This happens because <code>mod_tls</code> tries
|
|
to use longer DH parameter lengths when it can, but not all clients support
|
|
longer DH parameter lengths.
|
|
|
|
<p>
|
|
To address this, you need to configure a custom 1024-bit DH parameter via the
|
|
<a href="#TLSDHParamFile"><code>TLSDHParamFile</code></a> directive. You
|
|
can generate a custom DH parameter using <code>openssl dhparam</code>,
|
|
<i>e.g.</i>:
|
|
<pre>
|
|
$ openssl dhparam -outform PEM -5 1024 > dh1024.pem
|
|
</pre>
|
|
Alternatively, you can append the following standard 1024-bit DH parameters
|
|
from <a href="http://www.faqs.org/rfcs/rfc2409">RFC 2409</a>, section 6.2,
|
|
into a <code>dh1024.pem</code> file:
|
|
<pre>
|
|
-----BEGIN DH PARAMETERS-----
|
|
MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR
|
|
Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL
|
|
/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC
|
|
-----END DH PARAMETERS-----
|
|
</pre>
|
|
Then tell <code>mod_tls</code> to use that DH parameter:
|
|
<pre>
|
|
# Use 1024-bit DH parameters for the Java clients
|
|
TLSDHParamFile /path/to/dh1024.pem
|
|
</pre>
|
|
|
|
<p><a name="TLSNoCipherMatch">
|
|
<font color=red>Question</font>: I tried to configure a specific ciphersuite
|
|
using <code>TLSCipherSuite</code>, but ProFTPD fails on startup with this error:
|
|
<pre>
|
|
fatal: TLSCipherSuite: unable to use configured TLSCipherSuite '!EXPORT:MYCIPHER':
|
|
(1) error:1410D0B9:SSL routines:SSL_CTX_set_cipher_list:no cipher match on line 16 of '/etc/proftpd/tls.conf'
|
|
</pre>
|
|
<font color=blue>Answer</font>: This error indicates that the version of OpenSSL
|
|
does not recognize/support one of the ciphers that you configured in your
|
|
<code>TLSCipherSuite</code> list. Unfortunately the OpenSSL error reporting
|
|
does not pinpoint <i>which</i> is the offending ciphersuite; experimenting
|
|
with your cipher list will reveal which ones are problematic.
|
|
|
|
<p><a name="TLSRequiredNoPassword">
|
|
<font color=red>Question</font>: I want to require TLS for most users, but not
|
|
all of them. When TLS is required for a user, and they have not performed
|
|
the TLS handshake, I want to prevent them from sending their password in
|
|
plaintext. Is this possible?<br>
|
|
<font color=blue>Answer</font>: Yes, this is possible with the
|
|
<code>mod_ifsession</code> module:
|
|
<pre>
|
|
<IfModule mod_tls.c>
|
|
TLSEngine on
|
|
...
|
|
TLSRequired on
|
|
TLSOptions AllowPerUser
|
|
</IfModule>
|
|
|
|
<IfModule mod_ifsession.c>
|
|
# This is required for this use case
|
|
IfSessionOptions PerUnauthenticatedUser
|
|
|
|
<IfUser ftp>
|
|
TLSRequired off
|
|
</IfUser>
|
|
</IfModule>
|
|
</pre>
|
|
|
|
<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>
|
|
Alternatively, <code>mod_tls</code> can be built as a DSO module:
|
|
<pre>
|
|
$ ./configure --enable-dso --with-shared=mod_tls ...
|
|
</pre>
|
|
Then follow the usual steps:
|
|
<pre>
|
|
$ make
|
|
$ make install
|
|
</pre>
|
|
|
|
<p>
|
|
You may need to specify the location of the OpenSSL header and library files
|
|
in your <code>configure</code> command, <i>e.g.</i>:
|
|
<pre>
|
|
$ ./configure --with-modules=mod_tls \
|
|
--with-includes=/usr/local/openssl \
|
|
--with-libraries=/usr/local/openssl
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<font size=2><b><i>
|
|
© Copyright 2002-2023 TJ Saunders<br>
|
|
All Rights Reserved<br>
|
|
</i></b></font>
|
|
<hr>
|
|
|
|
</body>
|
|
</html>
|