ProFTPD module mod_gnutls



Note that I am not interested any more in supporting and extending the module. If you use it you are on your own.

This module is contained in the mod_gnutls.c file for ProFTPD 1.2, and is not compiled by default. Installation instructions are discussed here.

The mod_gnutls module is an alternative to the distributed TLS module, which uses GnuTLS instead, and takes advantage of the TLS-SRP and TLS with OpenPGP keys features of GnuTLS. The new features are discussed here.

The most current version of mod_gnutls can be found here. Currently it is not distributed with the ProFTPD source code.

Author

Please contact Nikos Mavroyanopoulos <nmav at gnutls.org> with any questions, concerns, or suggestions regarding this module.

Thanks

Directives


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.

Example:

  TLSCACertificateFile /etc/ftpd/ca-bundle.pem

If TLSCACertificateFile is not specified, the client verification will not be possible.


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. The CRL files will not be checked for authenticity. Use the gnutls' certtool utility for that.

certtool --verify-crl --infile crl.pem --cafile ca.pem

Example:

  TLSCARevocationFile /etc/ftpd/ca-crl-bundle.pem


TLSProtocol

Syntax: TLSProtocol protocol-list
Default: TLSv1 SSLv3
Context: server config
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.

How to put together a protocol list parameter:

    "TLSv1"          The TLS protocol version 1.0
    "TLSv1.1"        The TLS protocol version 1.1
    "SSLv3"          The SSL protocol version 3.0


TLSCiphers

Syntax: TLSCiphers cipher-list
Default: AES-256 AES-128 ARCFOUR-128 3DES
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

How to put together a cipher list parameter:

    "AES-256"       The AES cipher with 256 bit key size
    "AES-128"       The AES cipher with 128 bit key size
    "3DES"          The 3DES cipher
    "ARCFOUR-128"   The ARCFOUR (RC4) cipher with 128 bit key size
    "ARCFOUR-40"    The ARCFOUR (RC4) cipher with 40 bit key size (export cipher)


TLSKeyExchange

Syntax: TLSKeyExchange kx-list
Default: RSA DHE-RSA DHE-DSS SRP-DSS SRP-RSA
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

How to put together a kx list parameter:

    "RSA"          The RSA key exchange method. The private key is used for encryption.
    "DHE-RSA"      The DHE-RSA key exchange method. The private key is used for signing.
    "DHE-DSS"      The DHE-DSS key exchange method. The private key is used for signing.
    "RSA-EXPORT"   The exportable (weak) RSA key exchange method. The private key is used for signing (if it is over 512 bits).
    "ANON-DH"      The ANON-DH key exchange method. This is an anonymous key exchange. Vulnerable to man in the middle attacks.
    "SRP-RSA"      The SRP-RSA key exchange method. Client is authenticated with the SRP password, the server with an RSA certificate.
    "SRP-DSS"      The SRP-DSS key exchange method. Client is authenticated with the SRP password, the server with a DSS certificate.
    "SRP"          The SRP key exchange method. Client is authenticated with the SRP password.


TLSMAC

Syntax: TLSMAC mac-list
Default: SHA1 MD5
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

How to put together a maclist parameter:

    "SHA1"        The SHA1 mac algorithm
    "MD5"         The MD5 mac algorithm


TLSCompression

Syntax: TLSCompression comp-list
Default: DEFLATE NULL
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

How to put together a compression list parameter:

    "DEFLATE"    The compression algorithm in ZLIB
    "NULL"       The null compression algorithm (no compression)


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 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 certtool utility that comes with GnuTLS may be used to generate an appropriate file for this directive.

certtool --generate-dh-params --bits 1024 --outfile /test/server/dh.pem
The file parameter must be an absolute path. It is highly recommended to regenerate that file often.


TLSRSAParamFile

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

The TLSRSAParamFile directive is used to configure a file that mod_tls will use when engaging in a RSA-EXPORT key exchange. Such a key exchange can be computationally intensive, in terms for parameter generation; to speed up the process, the parameters used may be generated in advance, and stored in a file. The certtool utility that comes with GnuTLS may be used to generate an appropriate file for this directive.

certtool --generate-privkey --bits 512 --outfile /test/server/rsa.pem
The file parameter must be an absolute path. It is highly recommended to regenerate that file often.


TLSDSACertificateFile

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. This directive does not really require the key to be a DSA one. It can be any alternative key (ie. an RSA key marked as signature-only).

The contained private key must not be encrypted or it will not be read. The necessary alternative, at this point, is to use very strict file permissions (e.g. root read-only) on the certificate file.

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.

The contained private key must not be encrypted or it will not be read. The necessary alternative, at this point, is to use very strict file permissions (e.g. root read-only) on the certificate file.

Example:

  TLSDSACertificateKeyFile /etc/ftpd/server-dsa-key.pem


TLSPGPCertificateFile

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

The TLSPGPCertificateFile directive points to the Base64-encoded file containing the PGP certificate file for the server and optionally also the corresponding PGP private key file.

The contained private key must not be encrypted or it will not be read. The necessary alternative, at this point, is to use very strict file permissions (e.g. root read-only) on the certificate file.

Example:

  TLSPGPCertificateFile /etc/ftpd/server-pgp-cert.asc


TLSPGPCertificateKeyFile

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

The TLSPGPCertificateKeyFile directive points to the Base64-encoded private key file for the server. If the private key is not combined with the certificate in the TLSPGPCertificateFile, use this additional directive to point to the file with the standalone private key. When TLSPGPCertificateFile 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.

The contained private key must not be encrypted or it will not be read. The necessary alternative, at this point, is to use very strict file permissions (e.g. root read-only) on the certificate file.

Example:

  TLSPGPCertificateKeyFile /etc/ftpd/server-pgp-key.asc


TLSSRPPasswdFile

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

The TLSSRPPasswdFile directive points to the SRP password file. The users listed in the SRP password file must exist in the system.

Example:

  TLSSRPPasswdFile /etc/tpasswd


TLSSRPPasswdConfFile

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

The TLSSRPPasswdConfFile directive points to the SRP password configuration file.

Example:

  TLSSRPPasswdConfFile /etc/tpasswd.conf


TLSEngine

Syntax: TLSEngine on|off
Default: None
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.


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.

Example:

  TLSOptions iPAddressRequired StdEnvVars

The currently implemented options are:


TLSLoginFile

Syntax: TLSLoginFile file
Default: .tlslogin
Context: server config, <VirtualHost>, <Global>
Module: mod_tls
Compatibility: 1.2.7rc1 and later

The TLSLoginFile directive is used to set the default file to read a user's certificate from. This file will be used if the TLSLogin option has been set.

Example:

  TLSLoginFile .tlslogin


TLSRenegotiate

Syntax: TLSRenegotiate ["ctrl" secs] ["data" Kbytes] ["timeout" secs]|["required" on|off]|"none"
Default: None
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 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
Default: None
Context: server config, <VirtualHost>, <Global>
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


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 or chain for the server and optionally also the corresponding RSA private key file.

The contained private key must not be encrypted or it will not be read. The necessary alternative, at this point, is to use very strict file permissions (e.g. root read-only) on the certificate file.

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.

The contained private key must not be encrypted or it will not be read. The necessary alternative, at this point, is to use very strict file permissions (e.g. root read-only) on the certificate file.

Example:

  TLSRSACertificateKeyFile /etc/ftpd/server-rsa-key.pem


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


TLSVerifyClient

Syntax: TLSVerifyClient on|off
Default: None
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 on. Note that the server can be configured to not request a client certificate via the TLSOptions directive's "NoCertRequest" parameter.

See also: TLSOptions



Usage

This module supports all the TLS authentication methods such as X.509 certificates and anonymous authentication. Some other authentication methods, available in GnuTLS, can also be enabled. These are discussed below.

TLS-SRP
The SRP exchange convinces each side that the other side knows the same password, without requiring either side to give the password away to the other. So even if you connect to a host where its certificate path could not be verified, you can be a least sure that the host knows your password. This is a TLS extension discussed in draft-ietf-tls-srp-06.txt.

This of course requires the server to hold client's SRP verifiers. See the gnutls' documentation and the srptool program for more information.

TLS with OpenPGP keys
TLS can be used either with X.509 certificate authentication or with OpenPGP key authentication. The latter requires a compliant client that understands TLS extensions. This TLS extension is discussed in draft-ietf-tls-openpgp-keys-05.txt. See also the gnutls' documentation for more information.

The GnuTLS documentation is available at www.gnutls.org.

ftp clients that support both TLS-SRP and TLS with openpgp keys, are the ftp-tls and the FEG inetutils ftp.

The certtool program included in the gnutls distribution, can be used for certificate generation.

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



Installation

The mod_gnutls module is not distributed with ProFTPD. To compile it you need to overwrite the mod_tls.c module in the contrib directory with mod_gnutls.c.

The simply follow the normal steps for using third-party modules in proftpd:

  ./configure --with-modules=mod_tls
  make
  make install
or if the GnuTLS libraries are installed in /usr/local/lib try
  export LDFLAGS=-L/usr/local/lib 
  export CFLAGS=-I/usr/local/include 
  ./configure --with-modules=mod_tls
  make
  make install



Author: $Author: nmav $
Last Updated: $Date: 2005$


© Copyright 2004,2005 Nikos Mavroyanopoulos
All Rights Reserved