Changeset 546bf35 in mod_gnutls

Timestamp:

Jan 13, 2020, 10:52:16 AM (10 months ago)

Author:

Fiona Klute <fiona.klute@…>

Branches:

master, proxy-ticket

Children:

adcd021

Parents:

9bc842e

Message:

Update documentation on OCSP stapling

Location:

doc

Files:

• mod_gnutls_manual.md (modified) (4 diffs)
• style.css (modified) (1 diff)

doc/mod_gnutls_manual.md

@@ -523 +523 @@
 ---------------------------
 
-### GnuTLSOCSPStapling
-
-Enable OCSP stapling for this (virtual) host.
-
-    GnuTLSOCSPStapling [On|Off]
-
-Default: *on* if requirements are met, *off* otherwise\
-Context: server config, virtual host
-
 OCSP stapling, formally known as the TLS Certificate Status Request
 extension, allows the server to provide the client with a cached OCSP
@@ -540 +531 @@
 prevent the client from getting a response.
 
-Using OCSP stapling has a few requirements:
-
-* `GnuTLSCertificateFile` must contain the issuer CA certificate in
-  addition to the server certificate so responses can be verified.
-* The server certificate must either contain an OCSP access URI using
-  HTTP, or `GnuTLSOCSPResponseFile` must be set.
-* Caching OCSP responses requires a cache to store responses. If
-  `mod_socache_shmcb` is loaded `mod_gnutls` can set up the cache
-  automatically without additional configuration, see
-  `GnuTLSOCSPCache`.
-
-Stapling is activated by default if these requirements are met. If
+With TLS 1.2 stapling can be used only for the server certificate,
+with TLS 1.3 mod\_gnutls supports stapling for all certificates in the
+certificate chain except the root CA.
+
+Mod\_gnutls enables OCSP stapling by default if possible. The following
+requirements must be met:
+
+* OCSP responses are verified using the issuer CAs of the certificates
+  being checked, so the CAs must be included in
+  [`GnuTLSCertificateFile`](#gnutlscertificatefile). Providing the
+  whole certificate chain (including the root CA) is recommended.
+
+* Mod\_gnutls needs a cache to store OCSP responses for stapling. If
+  [mod\_socache\_shmcb](http://httpd.apache.org/docs/current/en/mod/mod_socache_shmcb.html)
+  is loaded mod\_gnutls can set up the cache without additional
+  configuration, for other options see
+  [`GnuTLSOCSPCache`](#gnutlsocspcache).
+
+* The certificates must contain OCSP access URIs using HTTP so
+  mod_gnutls can fetch responses, alternatively you may provide
+  responses using [`GnuTLSOCSPResponseFile`](#gnutlsocspresponsefile).
+
+If a server certificate contains the "must-staple" extension (X.509
+TLS Feature extension defined in [RFC
+7633](https://tools.ietf.org/html/rfc7633)) and the configuration does
+not support stapling mod_gnutls will refuse to start.
+
+By default mod\_gnutls regularly refreshes the cached OCSP responses
+in the background, see
+[`GnuTLSOCSPAutoRefresh`](#gnutlsocspautorefresh) for details.
+
+### GnuTLSOCSPStapling
+
+Enable OCSP stapling for this (virtual) host.
+
+    GnuTLSOCSPStapling [On|Off]
+
+Default: *on* if requirements are met, *off* otherwise\
+Context: server config, virtual host
+
+Stapling is activated by default if the requirements [listed
+above](#ocsp-stapling-configuration) are met.
+
+If the server certificate requires stapling ("must-staple") or
 `GnuTLSOCSPStapling` is explicitly set to `on` unmet requirements are
 an error.
@@ -582 +605 @@
 ### GnuTLSOCSPAutoRefresh
 
-Regularly refresh cached OCSP response independent of TLS handshakes?
+Regularly refresh cached OCSP responses independent of TLS handshakes?
 
     GnuTLSOCSPAutoRefresh [On|Off]
@@ -590 +613 @@
 
 By default `mod_gnutls` will regularly refresh the cached OCSP
-response for hosts that have OCSP stapling enabled, regardless of
-whether it is used. This has advantages over updating the OCSP
-response only if a TLS handshake needs it:
+responses, regardless of whether they are used. This has advantages
+over updating OCSP responses only when a TLS handshake needs them:
+
+* Handshakes are not delayed by updating the OCSP response cache
+  first.
 
 * Updating the cached response before it expires can hide short
   unavailability of the OCSP responder, if a repeated request is
   successful before the cache expires (see below).
-
-* Handshakes are not slowed down by fetching responses.
 
 The interval to the next request is determined as follows: After a

doc/style.css

@@ -11 +11 @@
     padding: 12px;
 }
-p code {
+p code, li code {
     background: #f5f5f5;
     border-radius: 4px;