mod_tls
mod_tls.c
file for ProFTPD
1.3.x, and is not compiled by default. Installation
instructions are discussed here.
The most current version of mod_tls
is distributed with the
ProFTPD source code.
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).
Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.
2002-09-01: Thanks to Peter 'Luna' Runestig <peter at
runestig.com> for his original mod_tls
, upon which this version
is based. His module can be found here:
ftp://ftp.runestig.com/pub/proftpd-tls/
<VirtualHost>
, <Global>
The TLSCACertificateFile
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,
TLSCACertificatePath
.
Example:
TLSCACertificateFile /etc/ftpd/ca-bundle.pem
If neither TLSCACertificateFile
nor
TLSCACertificatePath
are specified, the following message will
appear in the TLSLog
:
using default OpenSSL verification locations (see $SSL_CERT_DIR)This means that the
SSL_CERT_DIR
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 TLSVerifyClient
is set to on; otherwise,
no client verification occurs.
See also: TLSCACertificatePath
<VirtualHost>
, <Global>
The TLSCACertificatePath
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, TLSCACertificateFile
.
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 hash-value.N. The
c_rehash
utility that comes with OpenSSL can be used to create
the necessary symlinks.
Example:
TLSCACertificatePath /etc/ftpd/ca/
If neither TLSCACertificateFile
nor
TLSCACertificatePath
are specified, the following message will
appear in the TLSLog
:
using default OpenSSL verification locations (see $SSL_CERT_DIR)This means that the
SSL_CERT_DIR
environment variable, if set,
will be used to determine the location of a CA certificate directory, to be
used when verifying clients.
See also: TLSCACertificateFile
<VirtualHost>
, <Global>
The TLSCARevocationFile
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, TLSCARevocationPath
.
Example:
TLSCARevocationFile /etc/ftpd/ca-crl-bundle.pem
See also: TLSCARevocationPath
<VirtualHost>
, <Global>
The TLSCARevocationPath
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,
TLSCARevocationFile
.
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 hash-value.N. The
c_rehash
utility that comes with OpenSSL can be used to create
the necessary symlinks.
Example:
TLSCARevocationPath /etc/ftpd/crl/
See also: TLSCARevocationFile
<VirtualHost>
, <Global>
The TLSCertificateChainFile
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.
(Certificate chain order 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.
If TLSCertificateChainFile
is not used, and
TLSCACertificatePath
is used, the certificate chain is built from
the certificates in that path. TLSCertificateChainFile
should be
used as an alternative to TLSCACertificatePath
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 TLSCACertificatePath
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 not what one expects.
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.
Example:
TLSCertificateChainFile /etc/ftpd/client-ca-list.pem
<VirtualHost>
, <Global>
Default cipher list is "DEFAULT:!ADH:!EXPORT:!DES".
How to put together a cipher list parameter:
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
Each item in the list may include a prefix modifier:
"+" 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)
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.
For example, all available ciphers not including ADH key exchange:
ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
All algorithms including ADH and export but excluding patented algorithms:
HIGH:MEDIUM:LOW:EXPORT56:EXP:ADH:!kRSA:!aRSA:!RC4:!RC2:!IDEA
The OpenSSL command
$ openssl ciphers -v <list of ciphers>may be used to list all of the ciphers and the order described by a specific <list of ciphers>.
The TLSControlsACLs
directive configures access lists of
users or groups who are allowed (or denied) the ability to
use the actions implemented by mod_tls
. The default
behavior is to deny everyone unless an ACL allowing access has been explicitly
configured.
If "allow" is used, then list, a comma-delimited list
of users or groups, can use the given actions; all
others are denied. If "deny" is used, then the list of
users or groups cannot use actions all others are
allowed. Multiple TLSControlsACLs
directives may be used to
configure ACLs for different control actions, and for both users and groups.
The actions provided by mod_tls
are
"sesscache clear" , "sesscache info", and
"sesscache remove".
Examples:
# Allow only user root to examine/update the external SSL session cache TLSControlsACLs all allow user root
<VirtualHost>
, <Global>
The TLSCryptoDevice
directive is used to configure
mod_tls
to use an OpenSSL "engine", a cryptographic module
that OpenSSL library can use for accelerated cryptographic support, or
HSM keys, etc.
To use all of the engines compiled into OpenSSL, use:
TLSCryptoDevice allOpenSSL 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, e.g.:
TLSCryptoDevice chil
The OpenSSL command
$ openssl enginemay be used to list all of the engine drivers supported by OpenSSL.
<VirtualHost>
, <Global>
The TLSDHParamFile
directive is used to configure a file that
contains pre-computed Diffie-Hellman (DH) group parameters. The
mod_tls
module will use these parameters when engaging in
Diffie-Hellman key exchanges.
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 TLSDHParamFile
. The dhparam
utility
that comes with OpenSSL may be used to generate an appropriate file for this
directive:
$ openssl dhparam -outform PEM -2 nbits >> dhparams.pem $ openssl dhparam -outform PEM -5 nbits >> dhparams.pemUsing either -2 or -5 as the generator is fine. The nbits value used should vary between 512 and 4096, inclusive.
The file parameter must be an absolute path.
Note that as of proftpd-1.3.6rc1
and later, for
Diffie-Hellman key exchanges, mod_tls
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 FAQ for a workaround for such
clients.
<VirtualHost>
, <Global>
The TLSDSACertificateFile
directive points to the PEM-encoded
file containing the DSA certificate file for the server and optionally also
the corresponding DSA private key file.
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 TLSPassPhraseProvider
directive can be used to supply a source for that passphrase.
Example:
TLSDSACertificateFile /etc/ftpd/server-dsa-cert.pem
<VirtualHost>
, <Global>
The TLSDSACertificateKeyFile
directive points to the PEM-encoded
private key file for the server. If the private key is not combined with the
certificate in the TLSDSACertificateFile
, use this additional
directive to point to the file with the standalone private key. When
TLSDSACertificateFile
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.
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.
Example:
TLSDSACertificateKeyFile /etc/ftpd/server-dsa-key.pem
<VirtualHost>
, <Global>
The TLSECCertificateFile
directive points to the PEM-encoded
file containing the EC certificate file for the server and optionally also
the corresponding EC private key file.
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 TLSPassPhraseProvider
directive can be used to supply a source for that passphrase.
Example:
TLSECCertificateFile /etc/ftpd/server-ec-cert.pem
<VirtualHost>
, <Global>
The TLSECCertificateKeyFile
directive points to the PEM-encoded
private key file for the server. If the private key is not combined with the
certificate in the TLSECCertificateFile
, use this additional
directive to point to the file with the standalone private key. When
TLSECCertificateFile
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.
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.
Example:
TLSECCertificateKeyFile /etc/ftpd/server-ec-key.pem
<VirtualHost>
, <Global>
The
The
The
Note that this path must not be to a world-writable directory and,
unless
The
Discussion
Normally, the
Sometimes, though, sites want 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, if a
This leaves the site in a case where it does not want to use
For these situations, then, the
The
Some FTPS clients use the support of ALPN/NPN as a heuristic for knowing when
to use TLS False Start, which can reduce the SSL/TLS handshake network latency. Initially
TLS clients used TLS False Start for any/all sites, but encountered
issues;
these clients (e.g. Chrome, Firefox, perhaps others) now only use
the TLS False Start optimization for ALPN/NPN-enabled SSL/TLS servers.
The
Example:
The currently implemented options are:
The
Note, however, that SSL/TLS session renegotiation requests that are
initiated by
By default,
This option affects how
Important: if
However,
The
Note that this option first appeared in
This option will cause
Sets the following environment variables, if applicable. Note that
doing so increases the memory size of the process quite a bit:
If OpenSSL-1.0.2 or later is used, then
Note that this option first appeared in
Note: As of
In order to prevent certain attacks (e.g. the so-called
"BEAST"
attack), the
Note that this protective countermeasure only applies to SSLv3 and TLSv1
sessions; it does not affect TLSv1.1 or TLSv1.2 sessions.
Added in ProFTPD 1.3.4rc4.
As of ProFTPD 1.3.3rc1,
To relax the requirement that the SSL session from the control connection
be reused for data connections, use the following in the proftpd.conf:
Sets the following environment variables, if applicable. These environment
variables are then avaiable for use, such as in
This option will cause the
Thus if the
This option will cause
This option will cause
The
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
Example:
The
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.
Example:
The
The key-info 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
To generate this shared key (which is just a randomly generated bit of data),
you can use:
Multiple
The
Since the protocol version used by
The allowed protocols are:
Note that the parameter "SSLv23" is supported as a legacy style for saying
"all versions".
All use of SSLv2 is disabled. SSLv2 should not be used. As of
In
The
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.
Example:
Note that the
The
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 ctrl followed by a number, greater than zero, in seconds.
Use data followed by a number, greater than zero, of kilobytes to
change the default data channel renegotiation threshhold. The timeout
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,
By default,
Use none to disable all renegotiation requirements.
Examples:
The
The on parameter enables SSL/TLS requirements on both control and
data channels; off disables the requirements on both channels.
Use ctrl and data to require SSL/TLS on either channel
individually.
Example:
It is also possible to configure a policy which rejects 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
The
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
Example:
The
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.
Example:
When choosing a cipher during an SSLv3 or TLSv1 handshake, normally the
client's ciphersuite preference is used. If the
For example:
The
The
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.
If the
The type and info 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
The optional timeout 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). Note that to
ensure that the session cache is aggressively pruned of expired
sessions, each FTP session, upon ending, will flush any expired
sessions from the session cache.
Use of SSL session caching can be disabled entirely by using:
The
By default,
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 count parameter. Note that there is a
minimum count (1) of ticket keys; attemping to specify a smaller count
is a configuration error.
The
The
When a session is resumed using a session ticket encrypted with an older
session ticket key (which has not yet expired), the
For control over the key expiration and generation schedule, use the
The
By default,
See also:
The
The type and info 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
The
The currently implemented options are:
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
The
Example:
The
The
The
The attribute can either be "CommonName" (to match the CN of the
client certificate to the requested
Examples:
Note that for the
See also:
The
See also:
The
Example:
The
By default, the
Another way of checking the validity of the client certificate is to use
the Online Certificate Status Protocol (OCSP), defined in
RFC 2560. To configure
the
See also:
The
The NoReverseDNS parameter tells
See also:
The
See also:
The
For example:
See also:
The
For example:
See also:
There is also a script,
A copy of the Draft describing FTP over SSL/TLS is included with the source
code for this module.
Logging
Frequently Asked Questions
Question: When I use a Java client to connect to my
To address this, you need to configure a custom 1024-bit DH parameter via the
You may need to specify the location of the OpenSSL header and library files
in your
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:
$ openssl ecparam -list_curves
TLSEngine
Syntax: TLSEngine on|off
Default: off
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSEngine
directive toggles the use of the SSL/TLS protocol
engine (e.g. mod_tls
). This is usually used inside a
<VirtualHost>
section to enable SSL/TLS sessions for a
particular virtual host. By default mod_tls
is disabled for both
the main server and all configured virtual hosts.
TLSLog
Syntax: TLSLog file
Default: None
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSLog
directive is used to specify a log file for
mod_tls
's reporting on a per-server basis. The file
parameter given must be the full path to the file to use for logging.
AllowLogSymlinks
is explicitly set to on
(generally a bad idea), the path must not be a symbolic link.
TLSMasqueradeAddress
Syntax: TLSMasqueradeAddress ip-address|dns-name|device-name
Default: None
Context: server config, <VirtualHost>
Module: mod_tls
Compatibility: 1.3.5rc2 and later
TLSMasqueradeAddress
directive functions exactly like the
MasqueradeAddress
, except that it applies only to FTPS sessions. (Note that if
both MasqueradeAddress
and
TLSMasqueradeAddress
are configured, then the
TLSMasqueradeAddress
directive will take precedence, but only
for FTPS sessions.)
Why is something like TLSMasqueradeAddress
needed? There are
cases where some sites run proftpd
within a restricted VLAN/DMZ,
with some sort of firewall/proxy/router device which handles FTP and FTPS
connections from the Internet to that proftpd
server:
client <---> firewall <---> load balancer <---> server
In many cases, the firewall/proxy/router device will look at the FTP responses
for the PASV
/EPSV
commands (in which
proftpd
may be sending its internal, non-public IP address), and
rewrite the responses to have the IP address of the firewall/proxy/router
device.
MasqueradeAddress
directive can be used for such
cases, so that proftpd
sends the configured address in the
PASV
/EPSV
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 cannot rewrite the response due to
the SSL/TLS protection.
PASV
/EPSV
response contains a public IP address, the
device will drop/break that FTP connection.
MasqueradeAddress
(so that the device can properly rewrite FTP
responses), which works -- but only for plain FTP sessions. Yet the site
does want to use MasqueradeAddress
-- but only for FTPS
sessions, since the device cannot rewrite FTPS responses.
TLSMasqueradeAddress
directive
can/should be used: it provides MasqueradeAddress
functionality,
but only for FTPS sessions.
TLSNextProtocol
Syntax: TLSNextProtocol on|off
Default: TLSNextProtocol on
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.6rc1 and later
TLSNextProtocol
directive toggles mod_tls
' support
for the ALPN (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 mod_tls
, that "next protocol" is always "ftp".
TLSOptions
Syntax: TLSOptions opt1 ...
Default: None
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSOptions
directive is used to configure various optional
behavior of mod_tls
.
TLSOptions iPAddressRequired StdEnvVars NoSessionReuseRequired
AllowClientRenegotiations
mod_tls
will reject any SSL/TLS session renegotiation
attempts by the client, in order to mitigate any issues arising from the
SSL/TLS session renegotiation vulnerability (CVE-2009-3555)
or SSL/TLS session renegotiation DoS (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.
Not recommended.
mod_tls
, via the
TLSRenegotiate
directive, are
still handled (depending on the OpenSSL version).
AllowDotLogin
mod_tls
still requires that a user supply a
password for authentication, even if a valid client certificate is
presented. If this option is enabled, mod_tls
will check
in the user's home directory for a .tlslogin
file, which
should contain one or more PEM-encoded certificates. If the certificate
presented by the client, if any, matches a certificate in this
.tlslogin
file, the user will be considered authenticated
and the server will not prompt for a password. If the user's
.tlslogin
does not exist, or does not contain the client's
certificate, then the server will fallback to requesting a password for
authentication.
AllowPerUser
mod_tls
evaluates any
TLSRequired
directives. Usually mod_tls
will reject any FTP commands, when TLSRequired on
or
TLSRequired ctrl
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,
before the USER and PASS commands. This means that
mod_tls
does not know the identity of the connecting client
when enforcing TLSRequired
. If this AllowPerUser
is used, mod_tls
will wait until after the PASS
command has been processed to enforce any TLSRequired
settings.
AllowPerUser
is used, even if
TLSRequired on
or TLSRequired ctrl
are in
effect, it will be possible for the connecting client to send
usernames and password unprotected before mod_tls
rejects the connection. This results in a slightly weaker security
policy enforcement; please consider carefully if this tradeoff is
acceptable for your site.
TLSRequired auth
and
TLSRequired auth+data
configurations will override the
AllowPerUser
option.
AllowWeakDH
mod_tls
will not use Diffie-Hellman groups of less
than 1024 bits, due to weaknesses
that can downgrade the security of an SSL/TLS session. If for any reason
your FTPS clients require smaller Diffie-Hellman groups, then
use this option.
proftpd-1.3.6rc1
.
CommonNameRequired
mod_tls
to perform checks on a client's
certificate once the SSL handshake has been completed: the client's
certificate will be searched for the CommonName
(CN) X509v3
value. Unless a CommonName
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
UseReverseDNS
is off, this option is automatically
disabled.
EnableDiags
Sets callbacks in the OpenSSL library such that a lot of
SSL/TLS protcol information is logged to the
TLSLog
file. This option is very
useful when debugging strange interactions with FTPS clients.
ExportCertData
TLS_SERVER_CERT
Server certificate, PEM-encoded
TLS_CLIENT_CERT
Client certificate, PEM-encoded
TLS_CLIENT_CERT_CHAINn
PEM-encoded certificates in client certificate chain
NoAutoECDH
mod_tls
will
attempt to automatically negotiate the best EC curve to use, when needed.
Use this option to disable that automatic behavior for any reason.
proftpd-1.3.6rc1
.
NoCertRequest
proftpd-1.3.6rc2
, this option is deprecated
and thus ignored. By default, mod_tls
will not send the
CertificateRequest
message to TLS clients during the handshake;
that message is only sent when client certificates will be verified
via the TLSVerifyClient
directive.
NoEmptyFragments
mod_tls
module was changed to use OpenSSL's
builtin countermeasure of inserting empty fragments. However, some browsers/clients may not handle
such empty fragments well. Use this NoEmptyFragaments
TLSOption in order to interoperate with such clients, with risk of losing
the protective countermeasure.
NoSessionReuseRequired
mod_tls
only accepts SSL/TLS data
connections that reuse the SSL session of the control connection, as a
security measure. Unfortunately, there are some clients (e.g.
curl) which do not reuse SSL sessions.
<IfModule mod_tls.c>
...
TLSOptions NoSessionReuseRequired
...
</IfModule>
StdEnvVars
LogFormat
s.
Note that doing so may increase the memory size of the process quite a bit:
FTPS
Present if FTP over SSL/TLS is being used
TLS_PROTOCOL
SSL protocol version (e.g. SSLv3, TLSv1)
TLS_SESSION_ID
Hex-encoded SSL session ID
TLS_CIPHER
Cipher specification name
TLS_CIPHER_EXPORT
Present if cipher is an export cipher
TLS_CIPHER_KEYSIZE_POSSIBLE
Number of cipher bits possible
TLS_CIPHER_KEYSIZE_USED
Number of cipher bits used
TLS_LIBRARY_VERSION
OpenSSL version
TLS_CLIENT_M_VERSION
Client certificate version
TLS_CLIENT_M_SERIAL
Client certificate serial number
TLS_CLIENT_S_DN
Subject DN of client certificate
TLS_CLIENT_S_DN_
x509Component of client certificate's Subject DN, where x509 is
a component of a X509 DN:
C,CN,D,I,G,L,O,OU,S,ST,T,UID,Email
TLS_CLIENT_I_DN
Issuer DN of client certificate
TLS_CLIENT_I_DN_
x509Component of client certificate's Issuer DN, where x509 is
a component of a X509 DN:
C,CN,D,I,G,L,O,OU,S,ST,T,UID,Email
TLS_CLIENT_V_START
Start time of client certificate validity
TLS_CLIENT_V_END
End time of client certificate validity
TLS_CLIENT_A_SIG
Client certificate's signature algorithm
TLS_CLIENT_A_KEY
Client certificate's public key algorithm
TLS_CLIENT_CERT
Client certificate, PEM-encoded
TLS_CLIENT_CERT_CHAINn
PEM-encoded certificates in client certificate chain
TLS_SERVER_M_VERSION
Server certificate version
TLS_SERVER_M_SERIAL
Server certificate serial number
TLS_SERVER_NAME
Server name requested via Server Name Indication (SNI), if present
TLS_SERVER_S_DN
Subject DN of server certificate
TLS_SERVER_S_DN_
x509Component of server certificate's Subject DN, where x509 is
a component of a X509 DN:
C,CN,D,I,G,L,O,OU,S,ST,T,UID,Email
TLS_SERVER_I_DN
Issuer DN of server certificate
TLS_SERVER_I_DN_
x509Component of server certificate's Issuer DN, where x509 is
a component of a X509 DN:
C,CN,D,I,G,L,O,OU,S,ST,T,UID,Email
TLS_SERVER_V_START
Start time of server certificate validity
TLS_SERVER_V_END
End time of server certificate validity
TLS_SERVER_A_SIG
Server certificate's signature algorithm
TLS_SERVER_A_KEY
Server certificate's public key algorithm
TLS_SERVER_CERT
Server certificate, PEM-encoded
UseImplicitSSL
mod_tls
module to handle all
connections as if they are SSL connections implicitly; the client does
not need to send the AUTH TLS
FTP command. This can
cause issues for FTPS clients which are expecting explicit FTPS, not
implicit FTPS.
UseImplicitSSL
option is used, you will want to
have a separate <VirtualHost>
section with
a different port number just for those clients which require/expect
implicit FTPS. For example:
<IfModule mod_tls.c>
<VirtualHost a.b.c.d>
TLSEngine on
TLSOptions UseImplicitSSL
# The "standard" implicit FTPS port is 990
Port 990
...
</VirtualHost>
</IfModule>
dNSNameRequired
mod_tls
to perform checks on a client's
certificate once the SSL handshake has been completed: the client's
certificate will be searched for the subjectAltName
X509v3
extension, and, in that extension, the dNSName
value will
be looked up. Unless a dNSName
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
UseReverseDNS
is off, this option is automatically
disabled.
iPAddressRequired
mod_tls
to perform checks on a client's
certificate once the SSL handshake has been completed: the client's
certificate will be searched for the subjectAltName
X509v3
extension, and, in that extension, the iPAddress
value will
be looked up. Unless an iPAddress
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.
TLSPKCS12File
Syntax: TLSPKCS12File file
Default: None
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.3rc1 and later
TLSPKCS12ile
directive points to the PKCS#12 file containing
the certificate file and its private key for the server.
TLSPassPhraseProvider
directive can be used to supply a source for that passphrase.
TLSPKCS12File /etc/ftpd/server-cert.p12
TLSPassPhraseProvider
Syntax: TLSPassPhraseProvider path
Default: None
Context: server config
Module: mod_tls
Compatibility: 1.3.1rc1 and later
TLSPassPhraseProvider
directive is used to specify an
external program which will be called, when mod_tls
starts up,
for each encrypted certificate key file. The program will be invoked with
two command-line arguments, passed on stdin
to the program:
servername:portnumber "RSA"|"DSA"
where servername:portnumber
indicates the
server using that encrypted certificate key, and "RSA"
or "DSA"
indicates the private key algorithm used
for that key. The program then must print the corresponding passphrase
for the key to stdout
.
TLSPassPhraseProvider /etc/ftpd/tls/get-passphrase
TLSPreSharedKey
Syntax: TLSPreSharedKey identity key-info
Default: None
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.6rc1 and later
TLSPreSharedKey
directive is used to configure a pre-shared
key (PSK), for use in
TLS-PSK ciphersuites. Each
PSK has an identity (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 TLSPreSharedKey
directive requires that the data be
hex-encoded, as indicated in the key-info parameter.
TLSPreSharedKey
directive
would be:
TLSPreSharedKey psk-name hex:/path/to/psk.key
The configured file cannot be world-readable or world-writable; the
mod_tls
module will skip/ignore such insecure permissions.
$ openssl rand 80 -out /path/to/identity.key -hex
Note that TLSPreSharedKey
requires at least 20 bytes of key data.
Have generated the random key data, tell mod_tls
to use it via:
TLSPreSharedKey identity hex:/path/to/identity.key
TLSPreSharedKey
directives can be used to configure
different PSKs for different identity names.
TLSProtocol
Syntax: TLSProtocol protocol1 ... protocolN
Default: TLSv1
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSProtocol
directive is used to configure the SSL/TLS
protocol versions that mod_tls
should use when establishing
SSL/TLS sessions. Clients can then only connect using the configured
protocol.
mod_tls
is set only once,
when the daemon starts, the TLSProtocol
directive is only allowed
in the "server config" context.
To support both SSLv3 and TLSv1, simply list both parameters for the
SSLv3
Allow only SSLv3
TLSv1
Allow only TLSv1
TLSv1.1
Allow only TLSv1.1
TLSv1.2
Allow only TLSv1.2
TLSProtocol
directive, e.g.:
TLSProtocol SSLv3 TLSv1
proftpd-1.3.6rc1
, SSLv3 support has been disabled as well.
proftpd-1.3.6rc2
and later, you can use the
TLSProtocol
directive in a different manner, to add
or subtract protocol support. For example, to enable all protocols
except SSLv3, you can use:
TLSProtocol ALL -SSLv3
Using the directive in this manner requires that "ALL" be the first
parameter, and that all protocols have either a +
(add) or -
(subtract) prefix. "ALL" will
always be expanded to all of the supported SSL/TLS protocols known by
mod_tls
and supported by OpenSSL
.
TLSRandomSeed
Syntax: TLSRandomSeed seed
Default: openssl-dir/.rnd
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSRandomSeed
directive configures the file that
mod_tls
will use for seeding the PRNG. seed must be an
absolute path.
TLSRandomSeed /etc/ftpd/server.rnd
TLSRandomSeed
directive is not used to
seed the entropy required by the OpenSSL library; that configuration
is OpenSSL-specific. Instead, the TLSRandomSeed
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.
TLSRenegotiate
Syntax: TLSRenegotiate ["ctrl" secs] ["data" Kbytes] ["timeout" secs]|["required" on|off]|"none"
Default: ctrl 14400 data 25165824 required true (for OpenSSL 0.9.7 or greater)
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSRenegotiate
directive is used to configure when SSL
renegotiations are to occur. Renegotiations, and thus this directive, are
only supported by mod_tls
if the version of OpenSSL installed
is 0.9.7 or greater.
mod_tls
will require that the client comply with the requested renegotiation
within the TLSRenegotiate
timeout. If, however, the client is
unwilling or unable to do so, and the daemon needs to support these clients,
set required to off. Doing so will cause renegotiations to
be requested, but not required.
mod_tls
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.
# Change renegotiations to occur on control channels after 1 hour
TLSRenegotiate ctrl 3600
# Change renegotiations to occur on data channels after 500 MB
TLSRenegotiate data 512000
# Change renegotiations so that they are not required, only requested
TLSRenegotiate required off
# Change only the timeout for renegotiations to be 5 minutes
TLSRenegotiate timeout 300
# Change all of the above renegotiation threshholds using one directive
TLSRenegotiate ctrl 3600 data 512000 required off timeout 300
# To disable renegotiations entirely
TLSRenegotiate none
TLSRequired
Syntax: TLSRequired on|off|ctrl|[!]data|auth|auth+[!]data
Default: off
Context: server config, <VirtualHost>
, <Global>
, <Anonymous>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSRequired
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.
# 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
The auth parameter requires that SSL/TLS be used on the control
channel, but only for authentication. To use this setting and
require SSL/TLS for data transfers, use the auth+data parameter,
e.g.:
# 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
This auth+data parameter allows a very specific security policy:
authentication via the USER
/PASS
commands
must 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 CCC
(Clear Command Channel) command, which in turn enables
SSL/TLS protected data transfers that are operate better with firewalls that
monitor the FTP control channel.
TLSRequired
directive can be set such that an FTPS client
requesting protection of the data channel, using the PROT
command,
will have that command refused. To configure such a policy, use one of
the following:
# If the client wishes to protect the control channel, allow it; but reject
# any attempt to protect the data channel
TLSRequired !data
# Require protection on the control channel, but reject protection of the
# data channel
TLSRequired ctrl+!data
# Require protection on the control channel for authentication (but not
# after), and reject protection of the data channel
TLSRequired auth+!data
TLSRSACertificateFile
Syntax: TLSRSACertificateFile file
Default: None
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSRSACertificateFile
directive points to the PEM-encoded
file containing the RSA certificate file for the server and optionally also
the corresponding RSA private key file.
TLSPassPhraseProvider
directive can be used to supply a source for that passphrase.
TLSRSACertificateFile /etc/ftpd/server-rsa-cert.pem
TLSRSACertificateKeyFile
Syntax: TLSRSACertificateKeyFile file
Default: None
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSRSACertificateKeyFile
directive points to the PEM-encoded
private key file for the server. If the private key is not combined with the
certificate in the TLSRSACertificateFile
, use this additional
directive to point to the file with the standalone private key. When
TLSRSACertificateFile
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.
TLSRSACertificateKeyFile /etc/ftpd/server-rsa-key.pem
TLSServerCipherPreference
Syntax: TLSServerCipherPreference on|off
Default: Off
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.5rc1 and later
TLSServerCipherPreference
directive is enabled, then the
server's ciphersuite preference will be used instead.
TLSServerCipherPreference on
TLSServerInfoFile
Syntax: TLSServerInfoFile file
Default: None
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.6rc2 and later
TLSServerInfoFile
directive uses the configured file
as custom TLS extensions. See the OpenSSL documentation for the SSL_CTX_use_serverinfo_file()
for more information.
TLSSessionCache
Syntax: TLSSessionCache "off"|type:/info [timeout]
Default: None
Context: server config
Module: mod_tls
Compatibility: 1.3.3rc1 and later
TLSSessionCache
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.
TLSSessionCache
directive is not used, then
OpenSSL's default internal SSL session caching will be used. Thus multiple
SSL sessions to the same server process (e.g. 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 (e.g. for downloading large
files), you may need to configure a longer cache lifetime using:
# Configure OpenSSL's internal caching to be 1800 seconds (30 minutes)
TLSSessionCache internal: 1800
mod_tls_shmcache
documentation.
TLSSessionCache off
TLSSessionTicketKeys
Syntax: TLSSessionTicketKeys [age secs] [count number]
Default: TLSSessionTicketKeys age 12h count 25
Context: server config
Module: mod_tls
Compatibility: 1.3.6rc2 and later
TLSSessionTicketKeys
directive can be used to control how
often mod_tls
generates new session ticket keys (assuming that
TLSSessionTickets
is enabled),
and how many ticket keys will be kept in one time in memory.
mod_tls
expires a session ticket key after 12 hours;
this can be changed using the age parameter, to specify a maximum
age. Note that the minimum key age is 60 seconds.
TLSSessionTickets
Syntax: TLSSessionTickets on|off
Default: off
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.6rc2 and later
TLSSessionTickets
directive enables the use of TLS
"session tickets" (see RFC 5077), which allow for session resumption, similar to TLS session caching.
mod_tls
module does not support configuration/use of
a static session ticket key, unlike Apache or nginx. Instead,
mod_tls
always 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.
mod_tls
will
honor that session ticket, but will also renew 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.
TLSSessionTicketKeys
directive.
TLSStapling
Syntax: TLStapling on|off
Default: off
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.6rc2 and later
TLSStapling
directive enables
OCSP stapling,
as defined by the "Certificate Status Request" TLS extension
(RFC 6066). If
TLSStapling
is enabled, and the certificate status request
extension is used by the SSL/TLS client, then mod_tls
will
include an OCSP response for the server certificate, in the TLS handshake.
TLSStapling
is off, but will automatically
be enabled if a TLSStaplingCache
is configured.
TLSStaplingCache
,
TLSStaplingOptions
,
TLSStaplingResponder
, and
TLSStaplingTimeout
TLSStaplingCache
Syntax: TLStaplingCache type:/info
Default: None
Context: server config
Module: mod_tls
Compatibility: 1.3.6rc2 and later
TLSStaplingCache
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
TLSStapling
is enabled.
mod_tls_fscache
documentation,
or see mod_tls_shmcache
for
a shared memory-based OCSP response cache, or
mod_tls_memcache
for using
memcached servers as an OCSP response cache.
TLSStaplingOptions
Syntax: TLStaplingOptions opt1 ...
Default: None
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.6rc2 and later
TLSStaplingOptions
directive configures various optional
behaviors of mod_tls
when querying OCSP responders.
NoNonce
mod_tls
to not include a nonce in its OCSP request
(and not expect to see that nonce in the OCSP response), use this option:
# Many OCSP responders pregenerate their responses, and thus cannot
# include nonces in the response.
TLSStaplingOptions NoNonce
TLSStaplingResponder
Syntax: TLStaplingResponder url
Default: none
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.6rc2 and later
TLSStaplingResponder
directive overrides the URL of the OCSP
responder specified in the “Authority Information Access” certificate extension.
# Use our own custom OCSP responder
TLSStaplingResponder http://gw.example.com/ocsp/
TLSStaplingTimeout
Syntax: TLStaplingTimeout secs
Default: 10s
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.6rc2 and later
TLSStaplingTimeout
directive sets the timeout for queries
to OCSP responders when TLSStapling
is enabled, and
mod_tls
is querying a responder for OCSP stapling purposes.
TLSTimeoutHandshake
Syntax: TLSTimeoutHandshake seconds
Default: 300
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.9rc1 and later
TLSTimeoutHandshake
directive configures the maximum number
of seconds for mod_tls
to accept an SSL/TLS handshake. If set to
zero, mod_tls
will wait forever for a handshake to complete. The
default is 300 seconds (five minutes).
TLSUserName
Syntax: TLSUserName attribute
Default: off
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.5rc2 and later
TLSUserName
directive configures which attribute
of a client certificate to match against the name provided by the FTPS client
in its USER
command. If the certificate attribute
value matches the USER
name, the user is considered to be
authenticated without requiring that password be sent over the network.
USER
name),
"EmailSubjAltName" (to match any Email Subject Alternative Names (SANs)
to the requested USER
name), or a custom OID.
# Match the CN
TLSUserName CommonName
# Match any Email SANs
TLSUserName EmailSubjAltName
# Match specific (custom) OID
TLSUserName 1.2.3.4.5
TLSUserName
directive to be effective,
mod_tls
has to be configured to request that clients provide
certificates, i.e.:
# Verify clients
TLSVerifyClient optional
# and possibly verify the user based on the client certs
TLSUserName CommonName
TLSVerifyClient
TLSVerifyClient
Syntax: TLSVerifyClient on|off|optional
Default: off
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSVerifyClient
directive configures how mod_tls
handles certificates presented by clients. If off, the module
will not request the client certificate while establishing an SSL/TLS session.
If on, the module will verify a client's certificate and, furthermore,
will fail all SSL handshake attempts unless the client presents a
certificate when the server requests one. If optional, then
mod_tls
will request that a client send its certificate,
but will not fail the handshake if the client fails to provide a certificate.
TLSOptions
TLSVerifyDepth
Syntax: TLSVerifyDepth depth
Default: 9
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later
TLSVerifyDepth
directive sets how deeply mod_tls
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.e. 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.e. the CA's certificate is
under TLSCACertificatePath
), etc.
TLSVerifyDepth 10
TLSVerifyOrder
Syntax: TLSVerifyOrder crl|ocsp
Default: crl
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.2rc1 and later
TLSVerifyOrder
directive configures how the
mod_tls
will verify the certificates presented by clients, if
at all. Unless TLSVerifyClient
is on, the
TLSVerifyOrder
directive is not needed.
mod_tls
module will include any CRLs (Certificate
Revocation List) that may have been configured via the
TLSCARevocationFile
and/or TLSCARevocationPath
directives. This default behavior is the equivalent of configuring the
TLSVerifyOrder
to use CRLs, e.g.:
TLSVerifyOrder crl
mod_tls
module to use OCSP when verifying, use:
TLSVerifyOrder ocsp
Note that at is possible for mod_tls
to use both CRLs and
OCSP when verifying certificates. Simply use TLSVerifyOrder
to configure the order in which mod_tls
should use the various
verification mechanisms:
TLSVerifyOrder ocsp crl
Verification ends when a mechanism can successfully verify the certificate.
TLSCARevocationFile
,
TLSCARevocationPath
TLSVerifyServer
Syntax: TLSVerifyServer on|off|NoReverseDNS
Default: on
Context: server config, <VirtualHost>
, <Global>
Module: mod_tls
Compatibility: 1.3.5rc4 and later
TLSVerifyServer
directive configures how mod_tls
handles certificates presented by other servers, during a secure
site-to-site (a.k.a. "secure FXP") transfer. If off, the
module will accept the certificate and establish an SSL/TLS session, but will
not verify the certificate. If on, the module will verify a
server's certificate and, furthermore, will fail all SSL handshake attempts
unless the server presents a valid certificate.
mod_tls
to validate
the server's certificate, but to only validate it based on IP address,
rather than using DNS names (for e.g. CommonName (CN) and DNS
SubjectAltName (SAN) checks). The recommended certificate validation
techniques use DNS names, so using NoReverseDNS 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.
TLSVerifyClient
,
TLSVerifyDepth
Control Actions
Syntax: ftpdctl tls sesscache cleartls sesscache clear
Purpose: Clears all cached sessions from the SSL session cache
tls sesscache clear
action is used to clear all cached
sessions, whether they have expired or not, from the configured external
SSL session cache. For example:
# ftpdctl tls sesscache clear
ftpdctl: tls sesscache: cleared 1 session from 'shm' session cache
TLSSessionCache
Syntax: ftpdctl tls sesscache info [-v]tls sesscache info
Purpose: Displays status of session cache
tls sesscache info
action is used to display information
about the configured external SSL session cache. If the optional -v
command-line option is used, then information about each cached session
will also be displayed.
# 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-----
TLSSessionCache
Syntax: ftpdctl tls sesscache removetls sesscache remove
Purpose: Removes the external SSL session cache
tls sesscache remove
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.
# ftpdctl tls sesscache remove
ftpdctl: tls sesscache: removed 'shm' session cache
TLSSessionCache
Usage
Much of the documentation for Apache's mod_ssl
, concerning
certificates, OpenSSL usage, etc applies to this module as well:
http://httpd.apache.org/docs/2.4/mod/mod_ssl.html
The OpenSSL documentation, and its
FAQ, are recommended as
well:
http://www.openssl.org/docs/
cert-tool
, that can help in the creation
of certificates. See cert-tool --help
for usage information:
http://www.castaglia.org/openssl/contrib/cert-tool
The mod_tls
module supports trace logging, via the module-specific log channels:
Thus for trace logging, to aid in debugging, you would use the following in
your proftpd.conf
:
TraceLog /path/to/ftpd/trace.log
Trace tls:20
This trace logging can generate large files; it is intended for debugging use
only, and should be removed from any production configuration.
proftpd
server using FTPS, it fails with exceptions such as:
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)
How can I fix this?
Answer: This happens because mod_tls
tries
to use longer DH parameter lengths when it can, but not all clients support
longer DH parameter lengths.
TLSDHParamFile
directive. You
can generate a custom DH parameter using openssl dhparam
,
e.g.:
$ openssl dhparam -outform PEM -5 1024 > dh1024.pem
Alternatively, you can append the following standard 1024-bit DH parameters
from RFC 2409, section 6.2,
into a dh1024.pem
file:
-----BEGIN DH PARAMETERS-----
MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR
Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL
/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC
-----END DH PARAMETERS-----
Then tell mod_tls
to use that DH parameter:
# Use 1024-bit DH parameters for the Java clients
TLSDHParamFile /path/to/dh1024.pem
Installation
The mod_tls
module is distributed with ProFTPD. Simply follow
the normal steps for using third-party modules in proftpd:
./configure --with-modules=mod_tls
make
make install
Alternatively, mod_tls
can be built as a DSO module:
./configure --enable-dso --with-shared=mod_tls ...
Then follow the usual steps:
make
make install
configure command, e.g.:
./configure --with-modules=mod_tls \
--with-includes=/usr/local/openssl \
--with-libraries=/usr/local/openssl
© Copyright 2002-2016 TJ Saunders
All Rights Reserved