Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

# Apache Module mod_tls

Available Languages: en

Description: | TLS v1.2 and v1.3 implemented in memory-safe Rust via the rustls library
Status: | Experimental
Module Identifier: | tls_module
Source File: | mod_tls.c
Compatibility: | Available in version 2.4.52 and later

### Summary

mod_tls is an alternative to `mod_ssl` for providing https to a server. It's feature set is a subset, described in more detail below. It can be used as a companion to `mod_ssl`, e.g. both modules can be loaded at the same time.

mod_tls, being written in C, used the Rust implementation of TLS named rustls via its C interface rustls-ffi. This gives memory safe cryptography and protocol handling at comparable performance.

It can be configured for frontend and backend connections. The configuration directive have been kept mostly similar to `mod_ssl` ones.

### Topics

- TLS in a VirtualHost context
- Feature Comparison with mod_ssl
- TLS Protocols
- TLS Ciphers
- Virtual Hosts
- ACME Certificates
- OCSP Stapling
- TLS Variables
- Client Certificates

### Directives

### Bugfix checklist

- httpd changelog
- Known issues
- Report a bug

### See also

- Comments

## TLS in a VirtualHost context

    Listen 443
    TLSEngine 443

    <VirtualHost *:443>
      ServerName example.net
      TLSCertificate file_with_certificate.pem file_with_key.pem
      ...
    </VirtualHost>

The above is a minimal configuration. Instead of enabling mod_tls in every virtual host, the port for incoming TLS connections is specified.

You cannot mix virtual hosts with `mod_ssl` and mod_tls on the same port. It's either or. SNI and ALPN are supported. You may use several virtual hosts on the same port and a mix of protocols like http/1.1 and h2.

## Feature Comparison with mod_ssl

The table below gives a comparison of feature between `mod_ssl` and mod_tls. If a feature of `mod_ssl` is no listed here, it is not supported by mod_tls. The one difference, probably most relevant is the lack for client certificate support in the current version of mod_tls.

Feature | mod_ssl | mod_tls | Comment
--- | --- | --- | ---
Frontend TLS | yes | yes |
Backend TLS | yes | yes |
TLS v1.3 | yes* | yes | *)with recent OpenSSL
TLS v1.2 | yes | yes |
TLS v1.0 | yes* | no | *)if enabled in OpenSSL
SNI Virtual Hosts | yes | yes |
Client Certificates | yes | no |
Machine Certificates for Backend | yes | yes |
OCSP Stapling | yes | yes* | *)via `mod_md`
Backend OCSP check | yes | no* | *)stapling will be verified
TLS version to allow | min-max | min |
TLS ciphers | exclusive list | preferred/suppressed |
TLS cipher ordering | client/server | client/server |
TLS sessions | yes | yes |
SNI strictness | default no | default yes |
Option EnvVars | exhaustive | limited* | *)see var list
Option ExportCertData | client+server | server |
Backend CA | file/dir | file |
Revocation CRLs | yes | no |
TLS Renegotiation | yes* | no | *)in TLS v1.2
Encrypted Cert Keys | yes | no |

## TLS Protocols

mod_tls supports TLS protocol version 1.2 and 1.3. Should there ever be a version 1.4 and `rustls` supports it, it will be available as well.

In mod_tls, you configure the minimum version to use, never the maximum:

    TLSProtocol TLSv1.3+

This allows only version 1.3 and whatever may be its successor one day when talking to your server or to a particular virtual host.

## TLS Ciphers

The list of TLS ciphers supported in the `rustls` library, can be found here. All TLS v1.3 ciphers are supported. For TLS v1.2, only ciphers that rustls considers secure are available.

mod_tls supports the following names for TLS ciphers:

1. The IANA assigned name which uses `_` to separate parts. Example: `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`
2. The OpenSSL name, using `-` as separator (for 1.2). Example: `ECDHE-ECDSA-AES256-SHA384`. Such names often appear in documentation. `mod_tls` defines them for all TLS v1.2 ciphers. For TLS v1.3 ciphers, names starting with `TLS13_` are also supported.
3. The IANA assigned identifier, which is a 16-bit numeric value. Example: `0xc024`. You can use this in configurations as `TLS_CIPHER_0xc024`.

You can configure a preference for ciphers, which means they will be used for clients that support them. If you do not configure a preference, `rustls` will use the one that it considers best. This is recommended.

Should you nevertheless have the need to prefer one cipher over another, you may configure it like this:

    TLSCiphersPrefer ECDHE-ECDSA-AES256-SHA384
    # or several
    TLSCiphersPrefer ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305

If you name a cipher that is unknown, the configuration will fail. If you name a cipher is not supported by `rustls` (or no longer supported in an updated version of `rustls` for security reasons), mod_tls will log a `WARNING`, but continue to work.

A similar mechanism exists, if you want to disable a particular cipher:

    TLSCipherSuppress ECDHE-ECDSA-AES256-SHA384

A suppressed cipher will not longer be used. If you name a cipher that is unknown, the configuration will fail. If you name a cipher is not supported by `rustls` (or no longer supported in an updated version of `rustls` for security reasons), mod_tls will log a `WARNING`, but continue to work.

## Virtual Hosts

mod_tls uses the SNI (Server Name Indicator) to select one of the configured virtual hosts that match the port being served. Should the client not provide an SNI, the first configured virtual host will be selected. If the client does provide an SNI (as all today's clients do), it must match one virtual host (`ServerName` or `ServerAlias`) or the connection will fail.

As with `mod_ssl`, you may specify ciphers and protocol versions for the base server (global) and/or individual virtual hosts that are selected via SNI by the client.

    Listen 443
    TLSEngine 443

    <VirtualHost *:443>
      ServerName example1.net
      TLSCertificate example1-cert.pem
      ...
    </VirtualHost>

    <VirtualHost *:443>
      ServerName example2.net
      TLSCertificate example2-cert.pem
      ...
      TLSProtocol v1.3+
    </VirtualHost>

The example above show different TLS settings for virtual hosts on the same port. This is supported. `example1` can be contacted via all TLS versions and `example2` only allows v1.3 or later.

## ACME Certificates

ACME certificates via `mod_md` are supported, just as for `mod_ssl`. A minimal configuration:

    Listen 443
    TLSEngine 443
    MDomain example.net

    <VirtualHost *:443>
      ServerName example.net
      ...
    </VirtualHost>

## OCSP Stapling

mod_tls has no own implementation to retrieve OCSP information for a certificate. However, it will use such for Stapling if it is provided by `mod_md`. See `mod_md`'s documentation on how to enable this.

## TLS Variables

Via the directive `TLSOptions`, several variables are placed into the environment of requests and can be inspected, for example in a CGI script.

The variable names are given by `mod_ssl`. Note that these are only a subset of the many variables that `mod_ssl` exposes.

Variable | TLSOption | Description
--- | --- | ---
SSL_TLS_SNI | * | the server name indicator (SNI) send by the client
SSL_PROTOCOL | * | the TLS protocol negotiated
SSL_CIPHER | * | the name of the TLS cipher negotiated
SSL_VERSION_INTERFACE | StdEnvVars | the module version
SSL_VERSION_LIBRARY | StdEnvVars | the rustls-ffi version
SSL_SECURE_RENEG | StdEnvVars | always `false`
SSL_COMPRESS_METHOD | StdEnvVars | always `false`
SSL_CIPHER_EXPORT | StdEnvVars | always `false`
SSL_CLIENT_VERIFY | StdEnvVars | always `false`
SSL_SESSION_RESUMED | StdEnvVars | either `Resumed` if a known TLS session id was presented by the client or `Initial` otherwise
SSL_SERVER_CERT | ExportCertData | the selected server certificate in PEM format

The variable `SSL_SESSION_ID` is intentionally not supported as it contains sensitive information.

## Client Certificates

While `rustls` supports client certificates in principle, parts of the infrastructure to make use of these in a server are not offered.

Among these features are: revocation lists, inspection of certificate extensions and the matched issuer chain for OCSP validation. Without these, revocation of client certificates is not possible. Offering authentication without revocation is not considered an option.

Work will continue on this and client certificate support may become available in a future release.

## TLSCertificate Directive

Description: | adds a certificate and key (PEM encoded) to a server/virtual host.
Syntax: | `TLSCertificate cert_file [key_file]`
Context: | server config, virtual host
Status: | Experimental
Module: | mod_tls

If you do not specify a separate key file, the key is assumed to also be found in the first file. You may add more than one certificate to a server/virtual host. The first certificate suitable for a client is then chosen.

The path can be specified relative to the server root.

## TLSCiphersPrefer Directive

Description: | defines ciphers that are preferred.
Syntax: | `TLSCiphersPrefer cipher(-list)`
Context: | server config, virtual host
Status: | Experimental
Module: | mod_tls

This will not disable any ciphers supported by `rustls`. If you specify a cipher that is completely unknown, the configuration will fail. If you specify a cipher that is known but not supported by `rustls`, a warning will be logged but the server will continue.

### Example

    TLSCiphersPrefer ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305

The example gives 2 ciphers preference over others, in the order they are mentioned.

## TLSCiphersSuppress Directive

Description: | defines ciphers that are not to be used.
Syntax: | `TLSCiphersSuppress cipher(-list)`
Context: | server config, virtual host
Status: | Experimental
Module: | mod_tls

This will not disable any unmentioned ciphers supported by `rustls`. If you specify a cipher that is completely unknown, the configuration will fail. If you specify a cipher that is known but not supported by `rustls`, a warning will be logged but the server will continue.

### Example

    TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305

The example removes a cipher for use in connections.

## TLSEngine Directive

Description: | defines on which address+port the module shall handle incoming connections.
Syntax: | `TLSEngine [address:]port`
Context: | server config
Status: | Experimental
Module: | mod_tls

This is set on a global level, not in individual `<VirtualHost>`s. It will affect all `<VirtualHost>` that match the specified address/port. You can use `TLSEngine` several times to use more than one address/port.

### Example

    TLSEngine 443

The example tells mod_tls to handle incoming connection on port 443 for all listeners.

## TLSHonorClientOrder Directive

Description: | determines if the order of ciphers supported by the client is honored
Syntax: | `TLSHonorClientOrder on|off`
Default: | `TLSHonorClientOrder on`
Context: | server config, virtual host
Status: | Experimental
Module: | mod_tls

`TLSHonorClientOrder` determines if the order of ciphers supported by the client is honored.

## TLSOptions Directive

Description: | enables SSL variables for requests.
Syntax: | `TLSOptions [+|-]option`
Context: | server config, virtual host, directory, .htaccess
Status: | Experimental
Module: | mod_tls

`TLSOptions` is analog to `SSLOptions` in `mod_ssl`. It can be set per directory/location and `option` can be:

- `StdEnvVars`: adds more variables to the requests environment, as forwarded for example to CGI processing and other applications.
- `ExportCertData`: adds certificate related variables to the request environment.
- `Defaults`: resets all options to their default values.

Adding variables to a request environment adds overhead, especially when certificates need to be inspected and fields extracted. Therefore most variables are not set by default.

You can configure `TLSOptions` per location or generally on a server/virtual host. Prefixing an option with `-` disables this option while leaving others unchanged. A `+` prefix is the same as writing the option without one.

The `Defaults` value can be used to reset any options that are inherited from other locations or the virtual host/server.

### Example

    <Location /myplace/app>
      TLSOptions Defaults StdEnvVars
      ...
    </Location>

## TLSProtocol Directive

Description: | specifies the minimum version of the TLS protocol to use.
Syntax: | `TLSProtocol version+`
Default: | `TLSProtocol v1.2+`
Context: | server config, virtual host
Status: | Experimental
Module: | mod_tls

The default is `v1.2+`. Settings this to `v1.3+` would disable TLSv1.2.

## TLSProxyCA Directive

Description: | sets the root certificates to validate the backend server with.
Syntax: | `TLSProxyCA file.pem`
Context: | server config, virtual host, proxy section
Status: | Experimental
Module: | mod_tls

## TLSProxyCiphersPrefer Directive

Description: | defines ciphers that are preferred for a proxy connection.
Syntax: | `TLSProxyCiphersPrefer cipher(-list)`
Context: | server config, virtual host, proxy section
Status: | Experimental
Module: | mod_tls

This will not disable any ciphers supported by `rustls`. If you specify a cipher that is completely unknown, the configuration will fail. If you specify a cipher that is known but not supported by `rustls`, a warning will be logged but the server will continue.

## TLSProxyCiphersSuppress Directive

Description: | defines ciphers that are not to be used for a proxy connection.
Syntax: | `TLSProxyCiphersSuppress cipher(-list)`
Context: | server config, virtual host, proxy section
Status: | Experimental
Module: | mod_tls

This will not disable any unmentioned ciphers supported by `rustls`. If you specify a cipher that is completely unknown, the configuration will fail. If you specify a cipher that is known but not supported by `rustls`, a warning will be logged but the server will continue.

## TLSProxyEngine Directive

Description: | enables TLS for backend connections.
Syntax: | `TLSProxyEngine on|off`
Context: | server config, virtual host, proxy section
Status: | Experimental
Module: | mod_tls

`TLSProxyEngine` is analog to `SSLProxyEngine` in `mod_ssl`.

This can be used in a server/virtual host or `<Proxy>` section to enable the module for outgoing connections using `mod_proxy`.

## TLSProxyMachineCertificate Directive

Description: | adds a certificate and key file (PEM encoded) to a proxy setup.
Syntax: | `TLSProxyMachineCertificate cert_file [key_file]`
Context: | server config, virtual host, proxy section
Status: | Experimental
Module: | mod_tls

The certificate is used to authenticate against a proxied backend server.

If you do not specify a separate key file, the key is assumed to also be found in the first file. You may add more than one certificate to a proxy setup. The first certificate suitable for a proxy connection to a backend is then chosen by `rustls`.

The path can be specified relative to the server root.

## TLSProxyProtocol Directive

Description: | specifies the minimum version of the TLS protocol to use in proxy connections.
Syntax: | `TLSProxyProtocol version+`
Default: | `TLSProxyProtocol v1.2+`
Context: | server config, virtual host, proxy section
Status: | Experimental
Module: | mod_tls

The default is `v1.2+`. Settings this to `v1.3+` would disable TLSv1.2.

## TLSSessionCache Directive

Description: | specifies the cache for TLS session resumption.
Syntax: | `TLSSessionCache cache-spec`
Context: | server config
Status: | Experimental
Module: | mod_tls

This uses a cache on the server side to allow clients to resume connections.

You can set this to `none` or define a cache as in the `SSLSessionCache` directive of `mod_ssl`.

If not configured, `mod_tls` will try to create a shared memory cache on its own, using `shmcb:tls/session-cache` as specification. Should that fail, a warning is logged, but the server continues.

## TLSStrictSNI Directive

Description: | enforces exact matches of client server indicators (SNI) against host names.
Syntax: | `TLSStrictSNI on|off`
Default: | `TLSStrictSNI on`
Context: | server config
Status: | Experimental
Module: | mod_tls

Client connections using SNI will be unsuccessful if no match is found.

Available Languages: en

## Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our mailing lists.