mod_gnutls ManualGnuTLSEnableGnuTLSCacheGnuTLSCacheTimeoutGnuTLSSessionTicketsGnuTLSCertificateFileGnuTLSKeyFileGnuTLSPGPCertificateFileGnuTLSPGPKeyFileGnuTLSClientVerifyGnuTLSClientCAFileGnuTLSPGPKeyringFileGnuTLSDHFileGnuTLSSRPPasswdFileGnuTLSSRPPasswdConfFileGnuTLSPrioritiesGnuTLSP11ModuleGnuTLSPINGnuTLSSRKPINGnuTLSExportCertificatesGnuTLSProxyEngineGnuTLSProxyCAFileGnuTLSProxyCRLFileGnuTLSProxyCertificateFileGnuTLSProxyKeyFileGnuTLSProxyPrioritiesHTTPSSSL_VERSION_LIBRARYSSL_VERSION_INTERFACESSL_PROTOCOLSSL_CIPHERSSL_COMPRESS_METHODSSL_SRP_USERSSL_CIPHER_USEKEYSIZE & SSL_CIPHER_ALGKEYSIZESSL_DH_PRIME_BITSSSL_CIPHER_EXPORTSSL_SESSION_IDSSL_CLIENT_V_REMAINSSL_CLIENT_V_STARTSSL_CLIENT_V_ENDSSL_CLIENT_S_DNSSL_CLIENT_I_DNSSL_CLIENT_S_AN%SSL_SERVER_M_SERIALSSL_SERVER_M_VERSIONSSL_SERVER_A_SIGSSL_SERVER_A_KEYSSL_SERVER_CERTSSL_SERVER_CERT_TYPESSL_CLIENT_CERTSSL_CLIENT_CERT_TYPEmod_gnutls is a module for the Apache web server that provides HTTPS (HTTP over Transport Layer Security (TLS) or the older Secure Sockets Layer (SSL)) using the GnuTLS library. More information about the module can be found at the project's website.
mod_gnutls uses the ./configure && make && make install mechanism common to many Open Source programs. Most of the dirty work is handled by either ./configure or Apache's apxs utility. If you have built Apache modules before, there shouldn't be any surprises for you.
The interesting options you can pass to configure are:
--with-apxs=PATHThis option is used to specify the location of the apxs utility that was installed as part of apache. Specify the location of the binary, not the directory it is located in.
--with-apu-config=PATHPath to APR Utility Library config tool (apu-1-config)
--helpProvides a list of all available configure options.
It is recommended to run make check before installation. If your system doesn't have a loopback device with IPv6 and IPv4 support or localhost does not resolve to at least one of [::1] and 127.0.0.1, you may have to set the TEST_HOST or TEST_IP environment variables when running ./configure to make the test suite work correctly.
To activate mod_gnutls just add the following line to your httpd.conf and restart Apache:
LoadModule gnutls_module modules/mod_gnutls.soGnuTLSEnableEnable GnuTLS for this virtual host
GnuTLSEnable [on|off]Default: off
Context: virtual host
This directive enables SSL/TLS Encryption for a Virtual Host.
GnuTLSCacheConfigure SSL Session Cache
GnuTLSCache [dbm|gdbm|memcache|none] [PATH|SERVERLIST|-]Default: GnuTLSCache none
Context: server config
This directive configures the SSL Session Cache for mod_gnutls. This could be shared between machines of different architectures.
dbm (Requires Berkeley DBM)Uses the default Berkeley DB backend of APR DBM to cache SSL Sessions results. The argument is a relative or absolute path to be used as the DBM Cache file. This is compatible with most operating systems, but needs the Apache Runtime to be compiled with Berkeley DBM support.
gdbmUses the GDBM backend of APR DBM to cache SSL Sessions results.
The argument is a relative or absolute path to be used as the DBM Cache file. This is the recommended option.
memcacheUses a memcached server to cache the SSL Session.
The argument is a space separated list of servers. If no port number is supplied, the default of 11211 is used. This can be used to share a session cache between all servers in a cluster.
noneTurns off all caching of SSL Sessions.
This can significantly reduce the performance of mod_gnutls since even followup connections by a client must renegotiate parameters instead of reusing old ones. This is the default, since it requires no configuration.
GnuTLSCacheTimeoutTimeout for SSL Session Cache expiration
GnuTLSCacheTimeout SECONDSDefault: GnuTLSCacheTimeout 300
Context: server config
Sets the timeout for SSL Session Cache entries expiration. This directive is valid even if Session Tickets are used, and indicates the expiration time of the ticket in seconds.
GnuTLSSessionTicketsEnable Session Tickets for the server
GnuTLSSessionTickets [on|off]Default: off
Context: server config, virtual host
To avoid storing data for TLS session resumption it is allowed to provide client with a ticket, to use on return. Use for servers with limited storage, and don't combine with GnuTLSCache. For a pool of servers this option is not recommended since the tickets are unique for the issuing server only.
GnuTLSCertificateFileSet to the PEM Encoded Server Certificate
GnuTLSCertificateFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to a PEM-encoded X.509 certificate to use as this Server's End Entity (EE) certificate. If you need to supply certificates for intermediate Certificate Authorities (iCAs), they should be listed in sequence in the file, from EE to the iCA closest to the root CA. Optionally, you can also include the root CA's certificate as the last certificate in the list.
Since version 0.7 this can be a PKCS #11 URL.
GnuTLSKeyFileSet to the PEM Encoded Server Private Key
GnuTLSKeyFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to the Server Private Key. Set GnuTLSPIN if the key file is encrypted.
Since version 0.7 this can be a PKCS #11 URL.
Security Warning:
This private key must be protected. It is read while Apache is still running as root, and does not need to be readable by the nobody or apache user.
GnuTLSPGPCertificateFileSet to a base64 Encoded Server OpenPGP Certificate
GnuTLSPGPCertificateFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to a base64 Encoded OpenPGP Certificate to use as this Server's Certificate.
GnuTLSPGPKeyFileSet to the Server OpenPGP Secret Key
GnuTLSPGPKeyFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to the Server Private Key. This key cannot currently be password protected.
Security Warning:
This private key must be protected. It is read while Apache is still running as root, and does not need to be readable by the nobody or apache user.
GnuTLSClientVerifyEnable Client Certificate Verification
GnuTLSClientVerify [ignore|request|require]
Default: ignore
Context: server config, virtual host, directory, .htaccess
This directive controls the use of SSL Client Certificate Authentication. If used in the .htaccess context, it can force TLS re-negotiation.
ignoremod_gnutls will ignore the contents of any SSL Client Certificates sent. It will not request that the client sends a certificate.
requestThe client certificate will be requested, but not required. The Certificate will be validated if sent. The output of the validation status will be stored in the SSL_CLIENT_VERIFY environment variable and can be SUCCESS, FAILED or NONE.
requireA Client certificate will be required. Any requests without a valid client certificate will be denied. The SSL_CLIENT_VERIFY environment variable will only be set to SUCCESS.
GnuTLSClientCAFileSet to the PEM Encoded Certificate Authority Certificate
GnuTLSClientCAFile FILEPATHDefault: none Context: server config, virtual host
Takes an absolute or relative path to a PEM Encoded Certificate to use as a Certificate Authority with Client Certificate Authentication. This file may contain a list of trusted authorities.
GnuTLSPGPKeyringFileSet to a base64 Encoded key ring
GnuTLSPGPKeyringFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to a base64 Encoded Certificate list (key ring) to use as a means of verification of Client Certificates. This file should contain a list of trusted signers.
GnuTLSDHFileSet to the PKCS #3 encoded Diffie Hellman parameters
GnuTLSDHFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to a PKCS #3 encoded DH parameters.Those are used when the DHE key exchange method is enabled. You can generate this file using certtool --generate-dh-params --bits 2048. If not set mod_gnutls will use the included parameters.
GnuTLSSRPPasswdFileSet to the SRP password file for SRP ciphersuites
GnuTLSSRPPasswdFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to an SRP password file. This is the same format as used in libsrp. You can generate such file using the command srptool --passwd /etc/tpasswd --passwd-conf /etc/tpasswd.conf -u test to set a password for user test. This password file holds the username, a password verifier and the dependency to the SRP parameters.
GnuTLSSRPPasswdConfFileSet to the SRP password.conf file for SRP ciphersuites
GnuTLSSRPPasswdConfFile FILEPATH Default: none
Context: server config, virtual host
Takes an absolute or relative path to an SRP password.conf file. This is the same format as used in libsrp. You can generate such file using the command srptool --create-conf /etc/tpasswd.conf. This file holds the SRP parameters and is associate with the password file (the verifiers depends on these parameters).
GnuTLSPrioritiesSet the allowed ciphers, key exchange algorithms, MACs and compression methods
GnuTLSPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_NDefault: none
Context: server config, virtual host
Takes a semi-colon separated list of ciphers, key exchange methods Message authentication codes and compression methods to enable. The allowed keywords are specified in the gnutls_priority_init() function of GnuTLS.
Full details can be found at the GnuTLS documentation. In brief you can specify a set of ciphersuites from the choices:
NONEThe empty list.
EXPORTA list with all the supported cipher combinations including the EXPORT strength algorithms.
PERFORMANCEA list with all the secure cipher combinations sorted in terms of performance.
NORMALA list with all the secure cipher combinations sorted with respect to security margin (subjective term).
SECUREA list with all the secure cipher combinations including the 256-bit ciphers sorted with respect to security margin.
Additionally you can add or remove algorithms using the + and ! prefixes respectively.
For example, in order to disable the ARCFOUR cipher from the NORMAL set you can use the string NORMAL:!ARCFOUR-128
Other options such as the protocol version and the compression method can be specified using the VERS- and COMP- prefixes.
So in order to remove or add a specific TLS version from the NORMAL set, use NORMAL:!VERS-SSL3.0. And to enable zlib compression use NORMAL:+COMP-DEFLATE.
However it is recommended not to add compression at this level. With the NONE set, in order to be usable, you have to specify a complete set of combinations of protocol versions, cipher algorithms (AES-128-CBC), key exchange algorithms (RSA), message authentication codes (SHA1) and compression methods (COMP-NULL).
You can find a list of all supported Ciphers, Versions, MACs, etc. by running gnutls-cli --list.
The special keyword %COMPAT will disable some security features such as protection against statistical attacks to ciphertext data in order to achieve maximum compatibility (some broken mobile clients need this).
GnuTLSP11ModuleLoad this PKCS #11 module.
GnuTLSP11Module PATH_TO_LIBRARYDefault: none
Context: server config
Load this PKCS #11 provider module, instead of the system defaults. May occur multiple times to load multiple modules.
GnuTLSPINSet the PIN to be used to access encrypted key files or PKCS #11 objects.
GnuTLSPIN XXXXXXDefault: none
Context: server config, virtual host
Takes a string to be used as a PIN for the protected objects in a security module, or as a key to be used to decrypt PKCS #8, PKCS #12, or openssl encrypted keys.
GnuTLSSRKPINSet the SRK PIN to be used to unlaccess the TPM.
GnuTLSSRKPIN XXXXXXDefault: none
Context: server config, virtual host
Takes a string to be used as a PIN for the protected objects in the TPM module.
GnuTLSExportCertificatesExport the PEM encoded certificates to CGIs
GnuTLSExportCertificates [off|on|SIZE]Default: off
Context: server config, virtual host
This directive configures exporting the full certificates of the server and the client to CGI scripts via the SSL_SERVER_CERT and SSL_CLIENT_CERT environment variables. The exported certificates will be PEM-encoded (if X.509) or ASCII-armored (if OpenPGP) up to the size given. The type of the certificate will be exported in SSL_SERVER_CERT_TYPE and SSL_CLIENT_CERT_TYPE.
SIZE should be an integer number of bytes, or may be written with a trailing K to indicate kibibytes. off means the same thing as 0, in which case the certificates will not be exported to the environment. on is an alias for 16K. If a non-zero size is specified for this directive, but a certificate is too large to fit in the buffer, then the corresponding environment variable will contain the fixed string GNUTLS_CERTIFICATE_SIZE_LIMIT_EXCEEDED.
With GnuTLSExportCertificates enabled, mod_gnutls exports the same environment variables to the CGI process as mod_ssl.
GnuTLSProxyEngineEnable TLS proxy connections for this virtual host
GnuTLSProxyEngine [on|off]Default: off
Context: virtual host
This directive enables support for TLS proxy connections for a virtual host.
GnuTLSProxyCAFileSet to the PEM encoded Certificate Authority Certificate
GnuTLSProxyCAFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to a PEM encoded certificate to use as a Certificate Authority when verifying certificates provided by proxy back end servers. This file may contain a list of trusted authorities. If not set, verification of TLS back end servers will always fail due to lack of a trusted CA.
GnuTLSProxyCRLFileSet to the PEM encoded Certificate Revocation List
GnuTLSProxyCRLFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to a PEM encoded Certificate Revocation List to use when verifying certificates provided by proxy back end servers. The file may contain a list of CRLs.
GnuTLSProxyCertificateFileSet to the PEM encoded Client Certificate
GnuTLSProxyCertificateFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to a PEM encoded X.509 certificate to use as this Server's End Entity (EE) client certificate for TLS client authentication in proxy TLS connections. If you need to supply certificates for intermediate Certificate Authorities (iCAs), they should be listed in sequence in the file, from EE to the iCA closest to the root CA. Optionally, you can also include the root CA's certificate as the last certificate in the list.
If not set, TLS client authentication will be disabled for TLS proxy connections. If set, GnuTLSProxyKeyFile must be set as well to provide the matching private key.
GnuTLSProxyKeyFileSet to the PEM encoded Private Key
GnuTLSProxyKeyFile FILEPATHDefault: none
Context: server config, virtual host
Takes an absolute or relative path to the Private Key matching the certificate configured using the GnuTLSProxyCertificateFile directive. This key cannot currently be password protected.
Security Warning:
This private key must be protected. It is read while Apache is still running as root, and does not need to be readable by the nobody or apache user.
GnuTLSProxyPrioritiesSet the allowed ciphers, key exchange algorithms, MACs and compression methods for proxy connections
GnuTLSProxyPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_NDefault: none
Context: server config, virtual host
This option is used to set the allowed ciphers, key exchange algorithms, MACs and compression methods for proxy connections. It takes the same parameters as GnuTLSPriorities. Required if GnuTLSProxyEngine is On.
The following is an example of standard SSL Hosting, using one IP Addresses for each virtual host
# Load the module into Apache.
LoadModule gnutls_module modules/mod_gnutls.so
GnuTLSCache gdbm /var/cache/www-tls-cache
GnuTLSCacheTimeout 500
# With normal SSL Websites, you need one IP Address per-site.
Listen 1.2.3.1:443
Listen 1.2.3.2:443
Listen 1.2.3.3:443
Listen 1.2.3.4:443
<VirtualHost 1.2.3.1:443>
GnuTLSEnable on
GnuTLSPriorities NONE:+AES-128-CBC:+3DES-CBC:+ARCFOUR-128:+RSA:+DHE-RSA:+DHE-DSS:+SHA1:+MD5:+COMP-NULL
DocumentRoot /www/site1.example.com/html
ServerName site1.example.com:443
GnuTLSCertificateFile conf/ssl/site1.crt
GnuTLSKeyFile conf/ss/site1.key
</VirtualHost>
<VirtualHost 1.2.3.2:443>
# This virtual host enables SRP authentication
GnuTLSEnable on
GnuTLSPriorities NORMAL:+SRP
DocumentRoot /www/site2.example.com/html
ServerName site2.example.com:443
GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2
GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf
</VirtualHost>
<VirtualHost 1.2.3.3:443>
# This server enables SRP, OpenPGP and X.509 authentication.
GnuTLSEnable on
GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
DocumentRoot /www/site3.example.com/html
ServerName site3.example.com:443
GnuTLSCertificateFile conf/ssl/site3.crt
GnuTLSKeyFile conf/ss/site3.key
GnuTLSClientVerify ignore
GnuTLSPGPCertificateFile conf/ss/site3.pub.asc
GnuTLSPGPKeyFile conf/ss/site3.sec.asc
GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3
GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf
</VirtualHost>
<VirtualHost 1.2.3.4:443>
GnuTLSEnable on
# %COMPAT disables some security features to enable maximum compatibility with clients.
GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT
DocumentRoot /www/site4.example.com/html
ServerName site4.example.com:443
GnuTLSCertificateFile conf/ssl/site4.crt
GnuTLSKeyFile conf/ss/site4.key
</VirtualHost>mod_gnutls can also use "Server Name Indication", as specified in RFC 3546. This allows hosting many SSL Websites, with a Single IP Address. Currently all the recent browsers support this standard. Here is an example, using SNI: ` `
# Load the module into Apache.
LoadModule gnutls_module modules/mod_gnutls.so
# With normal SSL Websites, you need one IP Address per-site.
Listen 1.2.3.1:443
# This could also be 'Listen *:443',
# just like '*:80' is common for non-https
# No caching. Enable session tickets. Timeout is still used for
# ticket expiration.
GnuTLSCacheTimeout 600
# This tells apache, that for this IP/Port combination, we want to use
# Name Based Virtual Hosting. In the case of Server Name Indication,
# it lets mod_gnutls pick the correct Server Certificate.
NameVirtualHost 1.2.3.1:443
<VirtualHost 1.2.3.1:443>
GnuTLSEnable on
GnuTLSSessionTickets on
GnuTLSPriorities NORMAL
DocumentRoot /www/site1.example.com/html
ServerName site1.example.com:443
GnuTLSCertificateFile conf/ssl/site1.crt
GnuTLSKeyFile conf/ss/site1.key
</VirtualHost>
<VirtualHost 1.2.3.1:443>
GnuTLSEnable on
GnuTLSPriorities NORMAL
DocumentRoot /www/site2.example.com/html
ServerName site2.example.com:443
GnuTLSCertificateFile conf/ssl/site2.crt
GnuTLSKeyFile conf/ss/site2.key
</VirtualHost>
<VirtualHost 1.2.3.1:443>
GnuTLSEnable on
GnuTLSPriorities NORMAL
DocumentRoot /www/site3.example.com/html
ServerName site3.example.com:443
GnuTLSCertificateFile conf/ssl/site3.crt
GnuTLSKeyFile conf/ss/site3.key
</VirtualHost>
<VirtualHost 1.2.3.1:443>
GnuTLSEnable on
GnuTLSPriorities NORMAL
DocumentRoot /www/site4.example.com/html
ServerName site4.example.com:443
GnuTLSCertificateFile conf/ssl/site4.crt
GnuTLSKeyFile conf/ss/site4.key
</VirtualHost>mod_gnutls by default uses conservative settings for the server. You can fine tune the configuration to reduce the load on a busy server. The following examples do exactly this:
# Load the module into Apache.
LoadModule gnutls_module modules/mod_gnutls.so
# Using 4 memcache servers to distribute the SSL Session Cache.
GnuTLSCache memcache "mc1.example.com mc2.example.com mc3.example.com mc4.example.com"
GnuTLSCacheTimeout 600
Listen 1.2.3.1:443
NameVirtualHost 1.2.3.1:443
<VirtualHost 1.2.3.1:443>
GnuTLSEnable on
# Here we disable the Perfect forward secrecy ciphersuites (DHE)
# and disallow AES-256 since AES-128 is just fine.
GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT
DocumentRoot /www/site1.example.com/html
ServerName site1.example.com:443
GnuTLSCertificateFile conf/ssl/site1.crt
GnuTLSKeyFile conf/ss/site1.key
</VirtualHost>
<VirtualHost 1.2.3.1:443>
GnuTLSEnable on
# Here we instead of disabling the DHE ciphersuites we use
# Diffie Hellman parameters of smaller size than the default (2048 bits).
# Using small numbers from 768 to 1024 bits should be ok once they are
# regenerated every few hours.
# Use "certtool --generate-dh-params --bits 1024" to get those
GnuTLSDHFile /etc/apache2/dh.params
GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT
DocumentRoot /www/site2.example.com/html
ServerName site2.example.com:443
GnuTLSCertificateFile conf/ssl/site2.crt
GnuTLSKeyFile conf/ss/site2.key
</VirtualHost>mod_gnutls exports the following environment variables to scripts. These are compatible with mod_ssl.
HTTPSCan be on or off
SSL_VERSION_LIBRARYThe version of the GnuTLS library
SSL_VERSION_INTERFACEThe version of this module
SSL_PROTOCOLThe SSL or TLS protocol name (such as TLS 1.0 etc.)
SSL_CIPHERThe SSL or TLS cipher suite name
SSL_COMPRESS_METHODThe negotiated compression method (NULL or DEFLATE)
SSL_SRP_USERThe SRP username used for authentication (only set when GnuTLSSRPPasswdFile and GnuTLSSRPPasswdConfFile are configured).
SSL_CIPHER_USEKEYSIZE & SSL_CIPHER_ALGKEYSIZEThe number if bits used in the used cipher algorithm.
This does not fully reflect the security level since the size of RSA or DHE key exchange parameters affect the security level too.
SSL_DH_PRIME_BITSThe number if bits in the modulus for the DH group, if DHE or static DH is used.
This will not be set if DH is not used.
SSL_CIPHER_EXPORTTrue or False. Whether the cipher suite negotiated is an export one.
SSL_SESSION_IDThe session ID negotiated in this session. Can be the same during client reloads.
SSL_CLIENT_V_REMAINThe number of days until the client's certificate is expired.
SSL_CLIENT_V_STARTThe activation time of client's certificate.
SSL_CLIENT_V_ENDThe expiration time of client's certificate.
SSL_CLIENT_S_DNThe distinguished name of client's certificate in RFC2253 format.
SSL_CLIENT_I_DNThe SSL or TLS cipher suite name
SSL_CLIENT_S_AN%These will contain the alternative names of the client certificate (% is a number starting from zero).
The values will be prepended by DNSNAME:, RFC822NAME: or URI: depending on the type.
If it is not supported the value UNSUPPORTED will be set.
SSL_SERVER_M_SERIALThe serial number of the server's certificate.
SSL_SERVER_M_VERSIONThe version of the server's certificate.
SSL_SERVER_A_SIGThe algorithm used for the signature in server's certificate.
SSL_SERVER_A_KEYThe public key algorithm in server's certificate.
SSL_SERVER_CERTThe PEM-encoded (X.509) or ASCII-armored (OpenPGP) server certificate (see the GnuTLSExportCertificates directive).
SSL_SERVER_CERT_TYPEThe certificate type can be X.509 or OPENPGP.
SSL_CLIENT_CERTThe PEM-encoded (X.509) or ASCII-armored (OpenPGP) client certificate (see the GnuTLSExportCertificates directive).
SSL_CLIENT_CERT_TYPEThe certificate type can be X.509 or OPENPGP.