From: Christophe Jaillet Date: Sat, 25 Dec 2021 09:12:00 +0000 (+0000) Subject: Improve mod_tls documentation layout X-Git-Tag: 2.4.53-rc1-candidate~113 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7134f393e888ba0a22a1f04a028eb41bb4b82839;p=thirdparty%2Fapache%2Fhttpd.git Improve mod_tls documentation layout Merge 1896372, 1896373, 1896374, 1896377, 1896378 from trunk [skip ci] git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1896379 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_tls.xml b/docs/manual/mod/mod_tls.xml index a627ae7a28a..8e889234828 100644 --- a/docs/manual/mod/mod_tls.xml +++ b/docs/manual/mod/mod_tls.xml @@ -47,7 +47,7 @@ directive have been kept mostly similar to mod_ssl ones.

-
+
TLS in a VirtualHost context Listen 443 @@ -71,7 +71,7 @@ TLSEngine 443

-
Feature Comparison with mod_ssl +
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, @@ -89,7 +89,7 @@ TLSEngine 443 SNI Virtual Hostsyesyes Client Certificatesyesno Machine Certificates for Backendyesyes -OCSP Staplingyesyes**)via mod_md +OCSP Staplingyesyes**)via mod_md Backend OCSP checkyesno**)stapling will be verified TLS version to allowmin-maxmin TLS ciphersexclusive listpreferred/suppressed @@ -107,7 +107,7 @@ TLSEngine 443

-
TLS Protocols +
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. @@ -124,7 +124,7 @@ TLSProtocol TLSv1.3+

-
TLS Ciphers +
TLS Ciphers

The list of TLS ciphers supported in the rustls library, can be found here. All TLS v1.3 @@ -184,14 +184,15 @@ TLSCipherSuppress ECDHE-ECDSA-AES256-SHA384

-
Virtual Hosts +
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) + virtual host (ServerName or + ServerAlias) or the connection will fail.

@@ -223,7 +224,7 @@ TLSEngine 443

-
ACME Certificates +
ACME Certificates

ACME certificates via mod_md are supported, just as for mod_ssl. A minimal configuration: @@ -240,7 +241,7 @@ MDomain example.net

-
OCSP Stapling +
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 @@ -249,15 +250,15 @@ MDomain example.net

-
TLS Variables +
TLS Variables

- Via the directive TLSOptions, several 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. + are only a subset of the many variables that mod_ssl exposes.

@@ -279,7 +280,7 @@ MDomain example.net

-
Client Certificates +
Client Certificates

While rustls supports client certificates in principle, parts of the infrastructure to make use of these in a server are not @@ -300,15 +301,17 @@ MDomain example.net TLSEngine defines on which address+port the module shall handle incoming connections. - TLSEngine [address:]port + 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. + 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 @@ -326,7 +329,7 @@ MDomain example.net TLSCertificate adds a certificate and key (PEM encoded) to a server/virtual host. - TLSCertificate cert_file [key_file] + TLSCertificate cert_file [key_file] server config virtual host @@ -345,7 +348,8 @@ MDomain example.net TLSProtocol specifies the minimum version of the TLS protocol to use. - TLSProtocol version+ + TLSProtocol version+ + TLSProtocol v1.2+ server config virtual host @@ -360,7 +364,7 @@ MDomain example.net TLSCiphersPrefer defines ciphers that are preferred. - TLSCiphersPrefer cipher(-list) + TLSCiphersPrefer cipher(-list) server config virtual host @@ -388,7 +392,7 @@ TLSCiphersPrefer ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305 TLSCiphersSuppress defines ciphers that are not to be used. - TLSCiphersSuppress cipher(-list) + TLSCiphersSuppress cipher(-list) server config virtual host @@ -414,16 +418,17 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305 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. This is `on` by default. + TLSHonorClientOrder determines if the order of ciphers + supported by the client is honored.

@@ -432,7 +437,7 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305 TLSOptions enables SSL variables for requests. - TLSOptions [+|-]option + TLSOptions [+|-]option server config virtual host @@ -441,7 +446,8 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305

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

    @@ -458,7 +464,7 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305 Therefore most variables are not set by default.

    - You can configure `TLSOptions` per location or generally on a + 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. @@ -489,10 +495,12 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305

    - `TLSProxyEngine on|off` is analog to `SSLProxyEngine` in mod_ssl. + 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`. + This can be used in a server/virtual host or Proxy section to + enable the module for outgoing connections using mod_proxy.

    @@ -500,7 +508,7 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305 TLSProxyCA sets the root certificates to validate the backend server with. - TLSProxyCA file.pem + TLSProxyCA file.pem server config virtual host @@ -508,7 +516,7 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305

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

    @@ -516,7 +524,8 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305 TLSProxyProtocol specifies the minimum version of the TLS protocol to use in proxy connections. - TLSProxyProtocol version+ + TLSProxyProtocol version+ + TLSProxyProtocol v1.2+ server config virtual host @@ -530,9 +539,9 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305 - TLSProxyCipherPrefer + TLSProxyCiphersPrefer defines ciphers that are preferred for a proxy connection. - TLSProxyCipherPrefer cipher(-list) + TLSProxyCiphersPrefer cipher(-list) server config virtual host @@ -549,9 +558,9 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305 - TLSProxyCipherSuppress + TLSProxyCiphersSuppress defines ciphers that are not to be used for a proxy connection. - TLSProxyCipherSuppress cipher(-list) + TLSProxyCiphersSuppress cipher(-list) server config virtual host @@ -570,7 +579,7 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305 TLSProxyMachineCertificate adds a certificate and key file (PEM encoded) to a proxy setup. - TLSProxyMachineCertificate cert_file [key_file] + TLSProxyMachineCertificate cert_file [key_file] server config virtual host @@ -595,12 +604,13 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305 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. This is `on` by default. + Client connections using SNI will be unsuccessful if no match is found.

    @@ -608,7 +618,7 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305 TLSSessionCache specifies the cache for TLS session resumption. - TLSSessionCache cache-spec + TLSSessionCache cache-spec server config @@ -616,7 +626,8 @@ TLSCiphersSuppress ECDHE-ECDSA-CHACHA20-POLY1305

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

VariableTLSOptionDescription