ProFTPD module mod_tls



This module is contained in the 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).

Author

Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.

Thanks

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/

Directives

Control Actions


TLSCACertificateFile

Syntax: TLSCACertificateFile file
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

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


TLSCACertificatePath

Syntax: TLSCACertificatePath directory
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

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


TLSCARevocationFile

Syntax: TLSCARevocationFile file
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

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


TLSCARevocationPath

Syntax: TLSCARevocationPath directory
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

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


TLSCertificateChainFile

Syntax: TLSCertificateChainFile file
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

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

Note: If you use the NoCertRequest TLSOption, then any configured TLSCertificateChainFile directive will be ignored. It is a waste of time to construct a certificate chain to send to the client if the server does not request that the client send a certificate to be verified.


TLSCipherSuite

Syntax: TLSCipherSuite cipher-list
Default: DEFAULT:!EXPORT:!DES
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

Default cipher list is "DEFAULT:!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
    "SHA"       SHA hash function (should not be used)

  Aliases:
    "ALL"       all ciphers
    "SSLv2"     all SSL version 2.0 ciphers (should not be used)
    "SSLv3"     all SSL version 3.0 ciphers
    "EXP"       all export ciphers (40-bit)
    "EXPORT56"  all export ciphers (56-bit)
    "LOW"       all low strength ciphers (no export)
    "MEDIUM"    all ciphers with 128-bit encryption
    "HIGH"      all ciphers using greater than 128-bit encryption
    "RSA"       all ciphers using RSA key exchange
    "DH"        all ciphers using Diffie-Hellman key exchange
    "EDH"       all ciphers using Ephemeral Diffie-Hellman key exchange
    "ADH"       all ciphers using Anonymous Diffie-Hellman key exchange
    "DSS"       all ciphers using DSS authentication
    "NULL"      all ciphers using no encryption

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


TLSControlsACLs

Syntax: TLSControlsACLs actions|"all" "allow"|"deny" "user"|"group" list
Default: None
Context: server config
Module: mod_tls
Compatibility: 1.3.3rc1 and later

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


TLSCryptoDevice

Syntax: TLSCryptoDevice driver|"all"|"none"
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.3.1rc1 and later

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 all
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, e.g.:
  TLSCryptoDevice chil

The OpenSSL command

  openssl engine
may be used to list all of the engine drivers supported by OpenSSL.


TLSDHParamFile

Syntax: TLSDHParamFile file
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

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.pem
Using 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.


TLSDSACertficateFile

Syntax: TLSDSACertificateFile file
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

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


TLSDSACertificateKeyFile

Syntax: TLSDSACertificateKeyFile file
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

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


TLSECCertficateFile

Syntax: TLSECCertificateFile file
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.3.5rc4 and later

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


TLSECCertificateKeyFile

Syntax: TLSECCertificateKeyFile file
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.3.5rc4 and later

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


TLSEngine

Syntax: TLSEngine on|off
Default: off
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

The 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

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

Note that this path must not be to a world-writable directory and, unless 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

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

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

Normally, the 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.

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 PASV/EPSV response contains a public IP address, the device will drop/break that FTP connection.

This leaves the site in a case where it does not want to use 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.

For these situations, then, the TLSMasqueradeAddress directive can/should be used: it provides MasqueradeAddress functionality, but only for FTPS sessions.


TLSOptions

Syntax: TLSOptions opt1 ...
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

The TLSOptions directive is used to configure various optional behavior of mod_tls. Note: all of the configured TLSOptions parameters must appear on the same line in the configuration; only the first TLSOptions directive that appears in the configuration is used.

Example:

  TLSOptions iPAddressRequired StdEnvVars NoSessionReuseRequired

The currently implemented options are:


TLSPKCS12File

Syntax: TLSPKCS12File file
Default: None
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.3.3rc1 and later

The TLSPKCS12ile directive points to the PKCS#12 file containing the certificate file and its private key for the server.

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 TLSPassPhraseProvider directive can be used to supply a source for that passphrase.

Example:

  TLSPKCS12File /etc/ftpd/server-cert.p12


TLSPassPhraseProvider

Syntax: TLSPassPhraseProvider path
Default: None
Context: server config
Module: mod_tls
Compatibility: 1.3.1rc1 and later

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

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:

  TLSPassPhraseProvider /etc/ftpd/tls/get-passphrase


TLSProtocol

Syntax: TLSProtocol protocol1 ... protocolN
Default: SSLv3 TLSv1
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

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

Since the protocol version used by mod_tls is set only once, when the daemon starts, the TLSProtocol directive is only allowed in the "server config" context.

The allowed protocols are:

SSLv3 Allow only SSLv3
TLSv1 Allow only TLSv1
TLSv1.1 Allow only TLSv1.1
TLSv1.2 Allow only TLSv1.2
To support both SSLv3 and TLSv1, simply list both parameters for the TLSProtocol directive, e.g.:

  TLSProtocol SSLv3 TLSv1

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.


TLSRandomSeed

Syntax: TLSRandomSeed seed
Default: openssl-dir/.rnd
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

The TLSRandomSeed directive configures the file that mod_tls will use for seeding the PRNG. seed must be an absolute path.

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:

  TLSRandomSeed /etc/ftpd/server.rnd

Note that the 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

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

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

By default, 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.

Use none to disable all renegotiation requirements.

Examples:

    # 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

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

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:

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

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

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

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:

  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

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

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:

  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

When choosing a cipher during an SSLv3 or TLSv1 handshake, normally the client's ciphersuite preference is used. If the TLSServerCipherPreference directive is enabled, then the server's ciphersuite preference will be used instead.

For example:

  TLSServerCipherPreference on


TLSSessionCache

Syntax: TLSSessionCache "off"|type:/info [timeout]
Default: None
Context: server config
Module: mod_tls
Compatibility: 1.3.3rc1 and later

The TLSSessionCache directive configures an external SSL session cache, which can be used for storing and shared SSL sessions across multiple processes. An external SSL session cache is an optional facility which speeds up parallel FTPS session connections.

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

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 mod_tls_shmcache documentation.

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

Use of SSL session caching can be disabled entirely by using:

  TLSSessionCache off


TLSTimeoutHandshake

Syntax: TLSTimeoutHandshake seconds
Default: 300
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.9rc1 and later

The 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

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

The attribute can either be "CommonName" (to match the CN of the client certificate to the requested USER name), "EmailSubjAltName" (to match any Email Subject Alternative Names (SANs) to the requested USER name), or a custom OID.

Examples:

  # Match the CN
  TLSUserName CommonName 

  # Match any Email SANs
  TLSUserName EmailSubjAltName

  # Match specific (custom) OID
  TLSUserName 1.2.3.4.5 

Note that for the TLSUserName directive to be effective, mod_tls has to be configured to request that clients provide certificates, i.e.:

  # Verify clients
  TLSVerifyClient on

  # and possibly verify the user based on the client certs
  TLSUserName CommonName

See also: TLSVerifyClient


TLSVerifyClient

Syntax: TLSVerifyClient on|off
Default: off
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

The TLSVerifyClient directive configures how mod_tls handles certificates presented by clients. 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 client's certificate and, furthermore, will fail all SSL handshake attempts unless the client presents a certificate when the server requests one. Note that the server can be configured to not request a client certificate via the TLSOptions directive's "NoCertRequest" parameter.

See also: TLSOptions


TLSVerifyDepth

Syntax: TLSVerifyDepth depth
Default: 9
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

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

Example:

  TLSVerifyDepth 10


TLSVerifyOrder

Syntax: TLSVerifyOrder crl|ocsp
Default: crl
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.3.2rc1 and later

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

By default, the 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

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

See also: TLSCARevocationFile, TLSCARevocationPath


TLSVerifyServer

Syntax: TLSVerifyServer on|off|NoReverseDNS
Default: on
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.3.5rc4 and later

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

The NoReverseDNS parameter tells 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.

See also: TLSVerifyClient, TLSVerifyDepth


Control Actions


tls sesscache clear

Syntax: ftpdctl tls sesscache clear
Purpose: Clears all cached sessions from the SSL session cache

The 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

See also: TLSSessionCache


tls sesscache info

Syntax: ftpdctl tls sesscache info [-v]
Purpose: Displays status of session cache

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

For example:

  # 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-----

See also: TLSSessionCache


tls sesscache remove

Syntax: ftpdctl tls sesscache remove
Purpose: Removes the external SSL session cache

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

For example:

  # ftpdctl tls sesscache remove
  ftpdctl: tls sesscache: removed 'shm' session cache

See also: TLSSessionCache


Usage

Much of the documentation for Apache's mod_ssl, concerning certificates, OpenSSL usage, etc applies to this module as well:
  http://www.modssl.org/docs/2.7/
The OpenSSL documentation, and its FAQ, are recommended as well:
  http://www.openssl.org/docs/

There is also a script, 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

A copy of the Draft describing FTP over SSL/TLS is included with the source code for this module.


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

You may need to specify the location of the OpenSSL header and library files in your configure command, e.g.:

 ./configure --with-modules=mod_tls \
    --with-includes=/usr/local/openssl \
    --with-libraries=/usr/local/openssl



Author: $Author: castaglia $
Last Updated: $Date: 2013/12/09 23:15:16 $

© Copyright 2002-2013 TJ Saunders
All Rights Reserved