From 988f4496320604225900061e696c7201db8e9d03 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 17 Sep 2024 11:06:04 +0000 Subject: removed experimental mod_tls. source, documenation and test cases git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1920744 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/allmodules.xml | 1 - docs/manual/mod/mod_tls.xml | 640 ----------------------------------------- 2 files changed, 641 deletions(-) delete mode 100644 docs/manual/mod/mod_tls.xml (limited to 'docs') diff --git a/docs/manual/mod/allmodules.xml b/docs/manual/mod/allmodules.xml index 0a9d8b752b..cb8b6fcad1 100644 --- a/docs/manual/mod/allmodules.xml +++ b/docs/manual/mod/allmodules.xml @@ -129,7 +129,6 @@ mod_suexec.xml mod_syslog.xml mod_systemd.xml - mod_tls.xml mod_unique_id.xml mod_unixd.xml mod_userdir.xml diff --git a/docs/manual/mod/mod_tls.xml b/docs/manual/mod/mod_tls.xml deleted file mode 100644 index 8e88923482..0000000000 --- a/docs/manual/mod/mod_tls.xml +++ /dev/null @@ -1,640 +0,0 @@ - - - - - - - - - - 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 VirtualHosts. - 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+ - TLSProtocol v1.2+ - - 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 - determines if the order of ciphers supported by the client is honored - TLSHonorClientOrder on|off - TLSHonorClientOrder on - - server config - virtual host - - -

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

-

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

- -

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

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

- - - - - TLSProxyCiphersPrefer - defines ciphers that are preferred for a proxy connection. - TLSProxyCiphersPrefer 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. -

- - - - - TLSProxyCiphersSuppress - defines ciphers that are not to be used for a proxy connection. - TLSProxyCiphersSuppress 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 - TLSStrictSNI on - - server config - - -

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

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

- - - - -- cgit v1.2.3