⚝
One Hat Cyber Team
⚝
Your IP:
216.73.216.50
Server IP:
41.128.143.86
Server:
Linux host.raqmix.cloud 6.8.0-1025-azure #30~22.04.1-Ubuntu SMP Wed Mar 12 15:28:20 UTC 2025 x86_64
Server Software:
Apache
PHP Version:
8.3.23
Buat File
|
Buat Folder
Eksekusi
Dir :
~
/
usr
/
share
/
doc
/
psa-proftpd
/
contrib
/
View File Name :
mod_tls.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>