From 0cb680442ecaa6118cc610b5ecc6e824330bf61a Mon Sep 17 00:00:00 2001 From: Yann Ylavic Date: Fri, 18 Oct 2024 13:10:45 +0000 Subject: More mod_tls docs removal. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1921402 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_tls.html | 5 - docs/manual/mod/mod_tls.html.en.utf8 | 663 ----------------------------------- docs/manual/mod/mod_tls.xml.meta | 12 - 3 files changed, 680 deletions(-) delete mode 100644 docs/manual/mod/mod_tls.html delete mode 100644 docs/manual/mod/mod_tls.html.en.utf8 delete mode 100644 docs/manual/mod/mod_tls.xml.meta (limited to 'docs') diff --git a/docs/manual/mod/mod_tls.html b/docs/manual/mod/mod_tls.html deleted file mode 100644 index 02a1ee1ac2..0000000000 --- a/docs/manual/mod/mod_tls.html +++ /dev/null @@ -1,5 +0,0 @@ -# GENERATED FROM XML -- DO NOT EDIT - -URI: mod_tls.html.en.utf8 -Content-Language: en -Content-type: text/html; charset=UTF-8 diff --git a/docs/manual/mod/mod_tls.html.en.utf8 b/docs/manual/mod/mod_tls.html.en.utf8 deleted file mode 100644 index 197f3bd50d..0000000000 --- a/docs/manual/mod/mod_tls.html.en.utf8 +++ /dev/null @@ -1,663 +0,0 @@ - - - - - -mod_tls - Apache HTTP Server Version 2.5 - - - - - - - -
-

Modules | Directives | FAQ | Glossary | Sitemap

-

Apache HTTP Server Version 2.5

-
-
<-
-
-Apache > HTTP Server > Documentation > Version 2.5 > 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. -

-
- -
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 diff --git a/docs/manual/mod/mod_tls.xml.meta b/docs/manual/mod/mod_tls.xml.meta deleted file mode 100644 index 321d1ad732..0000000000 --- a/docs/manual/mod/mod_tls.xml.meta +++ /dev/null @@ -1,12 +0,0 @@ - - - - - mod_tls - /mod/ - .. - - - en - - -- cgit v1.2.3