From fe39ffb8b90ae4e002ed73fe98617cd590abb467 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 08:33:50 +0200 Subject: Adding upstream version 2.4.56. Signed-off-by: Daniel Baumann --- docs/manual/mod/mod_tls.html.en | 663 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 663 insertions(+) create mode 100644 docs/manual/mod/mod_tls.html.en (limited to 'docs/manual/mod/mod_tls.html.en') diff --git a/docs/manual/mod/mod_tls.html.en b/docs/manual/mod/mod_tls.html.en new file mode 100644 index 0000000..9b7ccc4 --- /dev/null +++ b/docs/manual/mod/mod_tls.html.en @@ -0,0 +1,663 @@ + + + + + +mod_tls - Apache HTTP Server Version 2.4 + + + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.4

+
+
<-
+ +
+

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

+
+ +
top
+
+

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

+
top
+
+

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

+ + + + + + + + + + + + + + + + + + + + + + + +
Featuremod_sslmod_tlsComment
Frontend TLSyesyes
Backend TLSyesyes
TLS v1.3yes*yes*)with recent OpenSSL
TLS v1.2yesyes
TLS v1.0yes*no*)if enabled in OpenSSL
SNI Virtual Hostsyesyes
Client Certificatesyesno
Machine Certificates for Backendyesyes
OCSP Staplingyesyes**)via mod_md
Backend OCSP checkyesno**)stapling will be verified
TLS version to allowmin-maxmin
TLS ciphersexclusive listpreferred/suppressed
TLS cipher orderingclient/serverclient/server
TLS sessionsyesyes
SNI strictnessdefault nodefault yes
Option EnvVarsexhaustivelimited**)see var list
Option ExportCertDataclient+serverserver
Backend CAfile/dirfile
Revocation CRLsyesno
TLS Renegotiationyes*no*)in TLS v1.2
Encrypted Cert Keysyesno
+

+

+
top
+
+

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

+
top
+
+

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. +
  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. +
  3. + The IANA assigned identifier, + which is a 16-bit numeric value. Example: 0xc024. + You can use this in configurations as TLS_CIPHER_0xc024. +
    4. +
+

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

+
top
+
+

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

+
top
+
+

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>
+ +
top
+
+

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

+
top
+
+

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

+ + + + + + + + + + + + + +
VariableTLSOptionDescription
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_INTERFACEStdEnvVarsthe module version
SSL_VERSION_LIBRARYStdEnvVarsthe rustls-ffi version
SSL_SECURE_RENEGStdEnvVarsalways `false`
SSL_COMPRESS_METHODStdEnvVarsalways `false`
SSL_CIPHER_EXPORTStdEnvVarsalways `false`
SSL_CLIENT_VERIFYStdEnvVarsalways `false`
SSL_SESSION_RESUMEDStdEnvVarseither `Resumed` if a known TLS session id was presented by the client or `Initial` otherwise
SSL_SERVER_CERTExportCertDatathe selected server certificate in PEM format
+

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

+
top
+
+

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

+
+
top
+

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

+ +
+
top
+

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

+ +
+
top
+

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

+ +
+
top
+

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

+ +
+
top
+

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

+

+ +
+
top
+

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>
+
+ +
+
top
+

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

+ +
+
top
+

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
+

+ +

+ +
+
top
+

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

+ +
+
top
+

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

+ +
+
top
+

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

+ +
+
top
+

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

+ +
+
top
+

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

+ +
+
top
+

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

+ +
+
top
+

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 

+
top

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.
+
+ \ No newline at end of file -- cgit v1.2.3