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

• TLSCACertificateFile
• TLSCACertificatePath
• TLSCARevocationFile
• TLSCARevocationPath
• TLSCertificateChainFile
• TLSCipherSuite
• TLSCryptoDevice
• TLSDHParamFile
• TLSDSACertificateFile
• TLSDSACertificateKeyFile
• TLSEngine
• TLSLog
• TLSOptions
• TLSPassPhraseProvider
• TLSProtocol
• TLSRandomSeed
• TLSRenegotiate
• TLSRequired
• TLSRSACertificateFile
• TLSRSACertificateKeyFile
• TLSTimeoutHandshake
• TLSVerifyClient
• TLSVerifyDepth

TLSCACertificateFile

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)

See also: TLSCACertificatePath

TLSCACertificatePath

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)

See also: TLSCACertificateFile

TLSCARevocationFile

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

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

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

TLSCipherSuite

Default cipher list is "ALL:!ADH".

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>

TLSCryptoDevice

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

  TLSCryptoDevice chil

The OpenSSL command

  openssl engine

TLSDHParamFile

The TLSDHParamFile directive is used to configure a file that mod_tls will use when engaging in a Diffie-Hellman key exchange. Such a key exchange can be computationally intensive, in terms for parameter generation; to help speed up the process, the parameters used may be generated in advance, and stored in a file. The dhparam utility that comes with OpenSSL may be used to generate an appropriate file for this directive. The file parameter must be an absolute path.

TLSDSACertficateFile

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.

Example:

  TLSDSACertificateFile /etc/ftpd/server-dsa-cert.pem

TLSDSACertificateKeyFile

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

TLSEngine

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

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.

TLSOptions

The TLSOptions directive is used to configure various optional behavior of mod_tls.

Example:

  TLSOptions iPAddressRequired StdEnvVars

The currently implemented options are:

• AllowDotLogin
  

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

  This option affects how 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.

  Important: if 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 passsword 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.

  However, TLSRequired auth and TLSRequired auth+data configurations will override the AllowPerUser option.

• ExportCertData
  

  Sets the following environment variables, if applicable. Note that doing so increases the memory size of the process quite a bit:

  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

• NoCertRequest
  

  Some FTP clients are known to be buggy when handling a server's certificate request. This option causes the server not to include such a request during an SSL handshake.

• StdEnvVars
  

  Sets the following environment variables, if applicable. These environment variables are then avaiable for use, such as in LogFormats. 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_x509	Component 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_x509	Component 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_S_DN	Subject DN of server certificate
  TLS_SERVER_S_DN_x509	Component 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_x509	Component 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

• dNSNameRequired
  

  This option will cause 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
  

  This option will cause 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.

TLSPassPhraseProvider

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"

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

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:

SSLv23	Compatibility mode, used to allow both SSLv3 and TLSv1
SSLv3	Allow only SSLv3
TLSv1	Allow only TLSv1

All use of SSLv2 is disabled. SSLv2 should not be used.

TLSRandomSeed

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

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

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

  # 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

TLSRSACertificateFile

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.

Example:

  TLSRSACertificateFile /etc/ftpd/server-rsa-cert.pem

TLSRSACertificateKeyFile

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

TLSTimeoutHandshake

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

TLSVerifyClient

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

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

Usage

  http://www.modssl.org/docs/2.7/

  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

  ./configure --with-modules=mod_tls
  make
  make install

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