mod_gnutlsNote 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 themod_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.
Please contact Nikos Mavroyanopoulos <nmav at gnutls.org> with any questions, concerns, or suggestions regarding this module.
<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.
Example:
TLSCACertificateFile /etc/ftpd/ca-bundle.pem
If TLSCACertificateFile is not specified, the client verification
will not be possible.
<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. 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
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
<VirtualHost>, <Global>
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)
<VirtualHost>, <Global>
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.
<VirtualHost>, <Global>
How to put together a maclist parameter:
"SHA1" The SHA1 mac algorithm
"MD5" The MD5 mac algorithm
<VirtualHost>, <Global>
How to put together a compression list parameter:
"DEFLATE" The compression algorithm in ZLIB
"NULL" The null compression algorithm (no compression)
<VirtualHost>, <Global>
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.pemThe file parameter must be an absolute path. It is highly recommended to regenerate that file often.
<VirtualHost>, <Global>
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.pemThe file parameter must be an absolute path. It is highly recommended to regenerate that file often.
<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. 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
<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.
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
<VirtualHost>, <Global>
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
<VirtualHost>, <Global>
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
<VirtualHost>, <Global>
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
<VirtualHost>, <Global>
The TLSSRPPasswdConfFile directive points to the SRP password configuration file.
Example:
TLSSRPPasswdConfFile /etc/tpasswd.conf
<VirtualHost>, <Global>
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.
<VirtualHost>, <Global>
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.
<VirtualHost>, <Global>
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.
The server will still prompt for a password, and if the user's
.tlslogin does not exist, or does not contain the client's
certificate, then the server will fallback to using the password for
authentication.
AllowPerUserThis 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.
AllowUIDLogin
By default, mod_tls will ignore all the fields in the certificates
supplied by the user. If this option is enabled, mod_tls will check
in the certificate DN the UID (0.9.2342.19200300.100.1.1) field and if it matches
the given username the user will be considered authenticated. The server will still
prompt for a password, but it will be ignored. This option requires that the client's
certificate was verified for authenticity, which means that his certificate is signed
by a trusted authority. So the TLSVerifyClient directive must be turned on.
AllowSRPLogin
By default, mod_tls still requires that a user supply a
password for authentication, even if valid SRP authentication was performed.
If this option is enabled, mod_tls will check the SRP
username to obtain the user's identity and the user
will be considered authenticated once the TLS handshake has finished.
The server may still prompt for a password, but it will be ignored.
The SRP key exchange methods must be enabled in order for this
authentication method to work.
NoCertRequestSome 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 increases 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 |
GnuTLS version |
TLS_CLIENT_M_VERSION |
Client certificate version |
TLS_CLIENT_M_SERIAL |
Client certificate serial number (hex encoded) |
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_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 |
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.
<VirtualHost>, <Global>
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
<VirtualHost>, <Global>
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
<VirtualHost>, <Global>
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
<VirtualHost>, <Global>
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
<VirtualHost>, <Global>
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
<VirtualHost>, <Global>
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).
<VirtualHost>, <Global>
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
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
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.
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 installor 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