From: Stefan Eissing Date: Fri, 10 Dec 2021 12:20:49 +0000 (+0000) Subject: *) mod_tls: adding module documentation to our manuals. X-Git-Tag: 2.5.0-alpha2-ci-test-only~655 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=02800f09f784639380f404630e882506ee98b696;p=thirdparty%2Fapache%2Fhttpd.git *) mod_tls: adding module documentation to our manuals. [skip ci] git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1895755 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_tls.xml b/docs/manual/mod/mod_tls.xml new file mode 100644 index 00000000000..a627ae7a28a --- /dev/null +++ b/docs/manual/mod/mod_tls.xml @@ -0,0 +1,629 @@ + + + + + + + + + + mod_tls + TLS v1.2 and v1.3 implemented in memory-safe Rust via + the rustls library + + Experimental + mod_tls.c + tls_module + Available in version 2.4.52 and later + +

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

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

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

+

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

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

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

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

+
+ + + TLSEngine + defines on which address+port the module shall handle incoming connections. + TLSEngine [address:]port + + server config + + +

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

+ + + + + TLSCertificate + adds a certificate and key (PEM encoded) to a server/virtual host. + TLSCertificate cert_file [key_file] + + server config + virtual host + + +

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

+ + + + + TLSProtocol + specifies the minimum version of the TLS protocol to use. + TLSProtocol version+ + + server config + virtual host + + +

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

+ + + + + TLSCiphersPrefer + defines ciphers that are preferred. + TLSCiphersPrefer cipher(-list) + + server config + virtual host + + +

+ 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 + defines ciphers that are not to be used. + TLSCiphersSuppress cipher(-list) + + server config + virtual host + + +

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

+ + + + + TLSHonorClientOrder + + TLSHonorClientOrder on|off + + server config + virtual host + + +

+ TLSHonorClientOrder determines if the order of ciphers + supported by the client is honored. This is `on` by default. +

+

+ + + + + TLSOptions + enables SSL variables for requests. + TLSOptions [+|-]option + + server config + virtual host + directory + .htaccess + + +

+ 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> + + + + + + + TLSProxyEngine + enables TLS for backend connections. + TLSProxyEngine on|off + + server config + virtual host + proxy section + + +

+ `TLSProxyEngine on|off` 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`. +

+ + + + + TLSProxyCA + sets the root certificates to validate the backend server with. + TLSProxyCA file.pem + + server config + virtual host + proxy section + + +

+ `TLSProxyEngine on|off` is analog to `SSLProxyCACertificatePath` in mod_ssl. +

+ + + + + TLSProxyProtocol + specifies the minimum version of the TLS protocol to use in proxy connections. + TLSProxyProtocol version+ + + server config + virtual host + proxy section + + +

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

+ + + + + TLSProxyCipherPrefer + defines ciphers that are preferred for a proxy connection. + TLSProxyCipherPrefer cipher(-list) + + server config + virtual host + proxy section + + +

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

+ + + + + TLSProxyCipherSuppress + defines ciphers that are not to be used for a proxy connection. + TLSProxyCipherSuppress cipher(-list) + + server config + virtual host + proxy section + + +

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

+ + + + + TLSProxyMachineCertificate + adds a certificate and key file (PEM encoded) to a proxy setup. + TLSProxyMachineCertificate cert_file [key_file] + + server config + virtual host + proxy section + + +

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

+ + + + + TLSStrictSNI + enforces exact matches of client server indicators (SNI) against host names. + TLSStrictSNI on|off + + server config + + +

+ Client connections using SNI will be unsuccessful if no match is found. This is `on` by default. +

+ + + + + TLSSessionCache + specifies the cache for TLS session resumption. + TLSSessionCache cache-spec + + server config + + +

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

+ + + +