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

Compilation & Installation

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

This 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=PATH

Path to APR Utility Library config tool (apu-1-config)

--help

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

Integration

To activate mod_gnutls just add the following line to your httpd.conf and restart Apache:

LoadModule gnutls_module modules/mod_gnutls.so

Configuration Directives

General Options

GnuTLSEnable

Enable GnuTLS for this virtual host

GnuTLSEnable [on|off]

Default: off
Context: virtual host

This directive enables SSL/TLS Encryption for a Virtual Host.

GnuTLSCache

Configure TLS Session Cache

GnuTLSCache [dbm|gdbm|memcache|none] [PATH|SERVERLIST|-]

Default: GnuTLSCache none
Context: server config

This directive configures the TLS Session Cache for mod_gnutls. This could be shared between machines of different architectures. If a DBM cache is used, access is serialized using the gnutls-cache mutex. Which DBM types are available is part of the APR (Apache Portable Runtime) compile time configuration.

dbm (Requires Berkeley DBM)

Uses the Berkeley DB backend of APR DBM to cache TLS Session data.

The argument is a relative or absolute path to be used as the DBM Cache file. This is compatible with most operating systems.

gdbm (Requires GDBM)

Uses the GDBM backend of APR DBM to cache TLS Session data.

The argument is a relative or absolute path to be used as the DBM Cache file.

memcache

Uses memcached server(s) to cache TLS Session data.

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.

none

Turns off all caching of TLS 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.

GnuTLSCacheTimeout

Timeout for TLS Session Cache expiration

GnuTLSCacheTimeout SECONDS

Default: GnuTLSCacheTimeout 300
Context: server config

Sets the timeout for TLS Session Cache entries expiration. This value is also used for OCSP responses if they do not contain a nextUpdate time.

GnuTLSSessionTickets

Enable Session Tickets for the server

GnuTLSSessionTickets [on|off]

Default: off
Context: server config, virtual host

To avoid storing data for TLS session resumption the server can provide clients with tickets, to use on return. Tickets are an alternative to using a session cache, mostly used for busy servers with limited storage. For a pool of servers this option is not recommended since the tickets are bound to the issuing server only.

If this option is set in the global configuration, virtual hosts without a GnuTLSSessionTickets setting will use the global setting.

Warning: Currently the master key that protects the tickets is generated only on server start, and there is no mechanism to roll over the key. If session tickets are enabled it is highly recommened to restart the server regularly to protect past sessions in case an attacker gains access to server memory.

GnuTLSClientVerify

Enable Client Certificate Verification

GnuTLSClientVerify [ignore|request|require]

Default: ignore
Context: server config, virtual host, directory, .htaccess

This directive controls the use of TLS Client Certificate Authentication. If used in the .htaccess context, it can force TLS re-negotiation.

ignore

mod_gnutls will ignore the contents of any TLS Client Certificates sent. It will not request that the client sends a certificate.

request

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

require

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

GnuTLSDHFile

Set to the PKCS #3 encoded Diffie Hellman parameters

GnuTLSDHFile FILEPATH

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

GnuTLSPriorities

Set the allowed protocol versions, ciphers, key exchange algorithms, MACs and compression methods

GnuTLSPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N

Default: none
Context: server config, virtual host

Takes a colon separated list of protocol version, 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.

Please refer to the GnuTLS documentation for details. A few commonly used sets are listed below, note that their exact meaning may change with GnuTLS versions.

PERFORMANCE

A list with all the secure cipher combinations sorted in terms of performance.

NORMAL

A list with all the secure cipher combinations sorted with respect to security margin (subjective term).

SECURE128

A list with all the secure cipher suites that offer a security level of 128-bit or more.

PFS

Only cipher suites offering perfect forward secrecy (ECDHE and DHE), sorted by security margin.

You can add or remove algorithms using the + and ! prefixes respectively. For example, in order to use the NORMAL set but disable TLS 1.0 and 1.1 you can use the string NORMAL:!VERS-TLS1.0:!VERS-TLS1.1.

You can find a list of all supported Ciphers, Versions, MACs, etc. by running gnutls-cli --list.

GnuTLSP11Module

Load this PKCS #11 module.

GnuTLSP11Module PATH_TO_LIBRARY

Default: none
Context: server config

Load this PKCS #11 provider module, instead of the system defaults. May occur multiple times to load multiple modules.

GnuTLSPIN

Set the PIN to be used to access encrypted key files or PKCS #11 objects.

GnuTLSPIN XXXXXX

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

GnuTLSSRKPIN

Set the SRK PIN to be used to access the TPM.

GnuTLSSRKPIN XXXXXX

Default: none
Context: server config, virtual host

Takes a string to be used as a PIN for the protected objects in the TPM module.

GnuTLSExportCertificates

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

X.509 Certificate Authentication

GnuTLSCertificateFile

Set to the PEM Encoded Server Certificate

GnuTLSCertificateFile FILEPATH

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

GnuTLSKeyFile

Set to the PEM Encoded Server Private Key

GnuTLSKeyFile FILEPATH

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

GnuTLSClientCAFile

Set the PEM encoded Certificate Authority list to use for X.509 base client authentication

GnuTLSClientCAFile FILEPATH

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

OpenPGP Certificate Authentication

GnuTLSPGPCertificateFile

Set to a base64 Encoded Server OpenPGP Certificate

GnuTLSPGPCertificateFile FILEPATH

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

GnuTLSPGPKeyFile

Set to the Server OpenPGP Secret Key

GnuTLSPGPKeyFile FILEPATH

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

GnuTLSPGPKeyringFile

Set to a base64 Encoded key ring

GnuTLSPGPKeyringFile FILEPATH

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

SRP Authentication

GnuTLSSRPPasswdFile

Set to the SRP password file for SRP ciphersuites

GnuTLSSRPPasswdFile FILEPATH

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

GnuTLSSRPPasswdConfFile

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

TLS Proxy Configuration

GnuTLSProxyEngine

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

GnuTLSProxyCAFile

Set to the PEM encoded Certificate Authority Certificate

GnuTLSProxyCAFile FILEPATH

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

GnuTLSProxyCRLFile

Set to the PEM encoded Certificate Revocation List

GnuTLSProxyCRLFile FILEPATH

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

GnuTLSProxyCertificateFile

Set to the PEM encoded Client Certificate

GnuTLSProxyCertificateFile FILEPATH

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

GnuTLSProxyKeyFile

Set to the PEM encoded Private Key

GnuTLSProxyKeyFile FILEPATH

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

GnuTLSProxyPriorities

Set the allowed ciphers, key exchange algorithms, MACs and compression methods for proxy connections

GnuTLSProxyPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N

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

OCSP Stapling Configuration

GnuTLSOCSPStapling

Enable OCSP stapling for this (virtual) host.

GnuTLSOCSPStapling [On|Off]

Default: off
Context: server config, virtual host

OCSP stapling, formally known as the TLS Certificate Status Request extension, allows the server to provide the client with an OCSP response for its certificate during the handshake. This way the client does not have to send an OCSP request to the CA to check the certificate status, which offers privacy and performance advantages.

Using OCSP stapling has a few requirements:

• Caching OCSP responses requires a cache, so GnuTLSCache must not be none.
• GnuTLSCertificateFile must contain the issuer CA certificate in addition to the server certificate so responses can be verified.
• The certificate must either contain an OCSP access URI using HTTP, or GnuTLSOCSPResponseFile must be set.

OCSP cache updates are serialized using the gnutls-ocsp mutex.

GnuTLSOCSPCheckNonce

Check the nonce in OCSP responses?

GnuTLSOCSPCheckNonce [On|Off]

Default: on
Context: server config, virtual host

Some CAs refuse to send nonces in their OCSP responses, probably because that way they can cache responses. If your CA is one of them you can use this flag to disable nonce verification. Note that mod_gnutls will send a nonce either way.

GnuTLSOCSPResponseFile

Read the OCSP response for stapling from this file instead of sending a request over HTTP.

GnuTLSOCSPResponseFile /path/to/response.der

Default: empty
Context: server config, virtual host

The response file must be updated externally, for example using a cron job. This option is an alternative to the server fetching OCSP responses over HTTP. Reasons to use this option include:

• Performing OCSP requests separate from the web server, to prevent slow responses from stalling handshakes.
• The issuer CA uses an access method other than HTTP.
• Testing

You can use a GnuTLS ocsptool command like the following to create and update the response file:

ocsptool --ask --nonce --load-issuer ca_cert.pem \
    --load-cert server_cert.pem --outfile ocsp_response.der

Additional error checking is highly recommended. You may have to remove the --nonce option if the OCSP responder of your CA does not support nonces.

GnuTLSOCSPCacheTimeout

Cache timeout for OCSP responses

GnuTLSOCSPCacheTimeout SECONDS

Default: 3600
Context: server config, virtual host

Cached OCSP responses will be refreshed after the configured number of seconds. How long this timeout should reasonably be depends on your CA, namely how often its OCSP responder is updated and how long responses are valid. Note that a response will not be cached beyond its lifetime as denoted in the nextUpdate field of the response.

GnuTLSOCSPFailureTimeout

Wait this many seconds before retrying a failed OCSP request.

GnuTLSOCSPFailureTimeout SECONDS

Default: 300
Context: server config, virtual host

Retries of failed OCSP requests must be rate limited to avoid overloading both the server using mod_gnutls and the CA's OCSP responder. A shorter value increases the load on both sides, a longer one means that stapling will remain disabled for longer after a failed request.

GnuTLSOCSPSocketTimeout

Timeout for TCP sockets used to send OCSP requests

GnuTLSOCSPFailureTimeout SECONDS

Default: 6
Context: server config, virtual host

Stalled OCSP requests must time out after a while to prevent stalling the server too much. However, if the timeout is too short requests may fail with a slow OCSP responder or high latency network connection. This parameter allows you to adjust the timeout if necessary.

Note that this is not an upper limit for the completion of an OCSP request but a socket timeout. The connection will time out if there is no activity (successful send or receive) at all for the configured time.

Configuration Examples

Simple Standard TLS Example

The following is an example of simple TLS 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

 # Without SNI you need one IP Address per-site.
 Listen 192.0.2.1:443
 Listen 192.0.2.2:443
 Listen 192.0.2.3:443
 Listen 192.0.2.4:443

 <VirtualHost 192.0.2.1:443>
     GnuTLSEnable on
     GnuTLSPriorities SECURE128
     DocumentRoot /www/site1.example.com/html
     ServerName site1.example.com:443
     GnuTLSCertificateFile conf/tls/site1.crt
     GnuTLSKeyFile conf/tls/site1.key
 </VirtualHost>

 <VirtualHost 192.0.2.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/tls/tpasswd.site2
     GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site2.conf
 </VirtualHost>

 <VirtualHost 192.0.2.3:443>
     # This server enables SRP, OpenPGP and X.509 authentication.
     GnuTLSEnable on
     GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS:+CTYPE-OPENPGP
     DocumentRoot /www/site3.example.com/html
     ServerName site3.example.com:443
     GnuTLSCertificateFile conf/tls/site3.crt
     GnuTLSKeyFile conf/tls/site3.key
     GnuTLSClientVerify ignore
     GnuTLSPGPCertificateFile conf/tls/site3.pub.asc
     GnuTLSPGPKeyFile conf/tls/site3.sec.asc
     GnuTLSSRPPasswdFile conf/tls/tpasswd.site3
     GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site3.conf
 </VirtualHost>

 <VirtualHost 192.0.2.4:443>
     GnuTLSEnable on
     # %COMPAT disables some security features to enable maximum
     # compatibility with clients. Don't use this if you need strong
     # security.
     GnuTLSPriorities NORMAL:%COMPAT
     DocumentRoot /www/site4.example.com/html
     ServerName site4.example.com:443
     GnuTLSCertificateFile conf/tls/site4.crt
     GnuTLSKeyFile conf/tls/site4.key
 </VirtualHost>

Server Name Indication Example

mod_gnutls supports "Server Name Indication", as specified in RFC 3546. This allows hosting many TLS websites with a single IP address. All recent browsers support this standard. Here is an example using SNI:

 # Load the module into Apache.
 LoadModule gnutls_module modules/mod_gnutls.so

 # SNI allows hosting multiple sites using one IP address. This
 # could also be 'Listen *:443', just like '*:80' is common for
 # non-HTTPS
 Listen 198.51.100.1:443

 <VirtualHost _default_:443>
     GnuTLSEnable on
     GnuTLSSessionTickets on
     GnuTLSPriorities NORMAL
     DocumentRoot /www/site1.example.com/html
     ServerName site1.example.com:443
     GnuTLSCertificateFile conf/tls/site1.crt
     GnuTLSKeyFile conf/tls/site1.key
 </VirtualHost>

 <VirtualHost _default_:443>
     GnuTLSEnable on
     GnuTLSPriorities NORMAL
     DocumentRoot /www/site2.example.com/html
     ServerName site2.example.com:443
     GnuTLSCertificateFile conf/tls/site2.crt
     GnuTLSKeyFile conf/tls/site2.key
 </VirtualHost>

 <VirtualHost _default_:443>
     GnuTLSEnable on
     GnuTLSPriorities NORMAL
     DocumentRoot /www/site3.example.com/html
     ServerName site3.example.com:443
     GnuTLSCertificateFile conf/tls/site3.crt
     GnuTLSKeyFile conf/tls/site3.key
 </VirtualHost>

 <VirtualHost _default_:443>
     GnuTLSEnable on
     GnuTLSPriorities NORMAL
     DocumentRoot /www/site4.example.com/html
     ServerName site4.example.com:443
     GnuTLSCertificateFile conf/tls/site4.crt
     GnuTLSKeyFile conf/tls/site4.key
 </VirtualHost>

OCSP Stapling Example

This example uses an X.509 server certificate. The server will fetch OCSP responses from the responder listed in the certificate and store them im a memcached cache shared with another server.

 # Load the module into Apache.
 LoadModule gnutls_module modules/mod_gnutls.so
 GnuTLSCache memcache "192.0.2.1:11211 192.0.2.2:11211"
 GnuTLSCacheTimeout 600

 Listen 192.0.2.1:443

 <VirtualHost _default_:443>
     GnuTLSEnable          On
     GnuTLSPriorities      NORMAL
     DocumentRoot          /www/site1.example.com/html
     ServerName            site1.example.com:443
     GnuTLSCertificateFile conf/tls/site1.crt
     GnuTLSKeyFile         conf/tls/site1.key
     GnuTLSPriorities      NORMAL
     GnuTLSOCSPStapling    On
 </VirtualHost>

Environment Variables

mod_gnutls exports the following environment variables to scripts. These are compatible with mod_ssl.

HTTPS

Can be on or off

SSL_VERSION_LIBRARY

The version of the GnuTLS library

SSL_VERSION_INTERFACE

The version of this module

SSL_PROTOCOL

The SSL or TLS protocol name (such as TLS 1.0 etc.)

SSL_CIPHER

The SSL or TLS cipher suite name

SSL_COMPRESS_METHOD

The negotiated compression method (NULL or DEFLATE)

SSL_SRP_USER

The SRP username used for authentication (only set when GnuTLSSRPPasswdFile and GnuTLSSRPPasswdConfFile are configured).

SSL_CIPHER_USEKEYSIZE & SSL_CIPHER_ALGKEYSIZE

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

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

True or False. Whether the cipher suite negotiated is an export one.

SSL_SESSION_ID

The session ID negotiated in this session. Can be the same during client reloads.

SSL_CLIENT_V_REMAIN

The number of days until the client's certificate is expired.

SSL_CLIENT_V_START

The activation time of client's certificate.

SSL_CLIENT_V_END

The expiration time of client's certificate.

SSL_CLIENT_S_DN

The distinguished name of client's certificate in RFC2253 format.

SSL_CLIENT_I_DN

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

The serial number of the server's certificate.

SSL_SERVER_M_VERSION

The version of the server's certificate.

SSL_SERVER_A_SIG

The algorithm used for the signature in server's certificate.

SSL_SERVER_A_KEY

The public key algorithm in server's certificate.

SSL_SERVER_CERT

The PEM-encoded (X.509) or ASCII-armored (OpenPGP) server certificate (see the GnuTLSExportCertificates directive).

SSL_SERVER_CERT_TYPE

The certificate type can be X.509 or OPENPGP.

SSL_CLIENT_CERT

The PEM-encoded (X.509) or ASCII-armored (OpenPGP) client certificate (see the GnuTLSExportCertificates directive).

SSL_CLIENT_CERT_TYPE

The certificate type can be X.509 or OPENPGP.