dnsdist: Add an OCSP stapling guide

[thirdparty/pdns.git] / pdns / dnsdistdist / docs / reference / config.rst

diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst
index 00b2293f8f58990fabd85dc7c05870a011bccd0d..29f50609d033d1aceadfa47978a2c431c61ae4ff 100644 (file)
--- a/pdns/dnsdistdist/docs/reference/config.rst
+++ b/pdns/dnsdistdist/docs/reference/config.rst
@@ -126,6 +126,8 @@ Listen Sockets
   * ``ciphers``: str - The TLS ciphers to use, in OpenSSL format. Ciphers for TLS 1.3 must be specified via ``ciphersTLS13``.
   * ``ciphersTLS13``: str - The TLS ciphers to use for TLS 1.3, in OpenSSL format.
   * ``serverTokens``: str - The content of the Server: HTTP header returned by dnsdist. The default is "h2o/dnsdist".
+  * ``customResponseHeaders={}``: table - Set custom HTTP header(s) returned by dnsdist.
+  * ``ocspResponses``: list - List of files containing OCSP responses, in the same order than the certificates and keys, that will be used to provide OCSP stapling responses.
 
 .. function:: addTLSLocal(address, certFile(s), keyFile(s) [, options])
 
@@ -136,7 +138,7 @@ Listen Sockets
   .. versionchanged:: 1.3.3
     ``numberOfStoredSessions`` option added.
   .. versionchanged:: 1.4.0
-    ``ciphersTLS13`` option added.
+    ``ciphersTLS13`` and ``ocspResponses`` options added.
 
   Listen on the specified address and TCP port for incoming DNS over TLS connections, presenting the specified X.509 certificate.
 
@@ -160,6 +162,7 @@ Listen Sockets
   * ``ticketsKeysRotationDelay``: int - Set the delay before the TLS tickets key is rotated, in seconds. Default is 43200 (12h).
   * ``sessionTickets``: bool - Whether session resumption via session tickets is enabled. Default is true, meaning tickets are enabled.
   * ``numberOfStoredSessions``: int - The maximum number of sessions kept in memory at the same time. At this time this is only supported by the OpenSSL provider, as stored sessions are not supported with the GnuTLS one. Default is 20480. Setting this value to 0 disables stored session entirely.
+  * ``ocspResponses``: list - List of files containing OCSP responses, in the same order than the certificates and keys, that will be used to provide OCSP stapling responses.
 
 .. function:: setLocal(address[, options])
 
@@ -375,7 +378,7 @@ Servers
       address="IP:PORT",     -- IP and PORT of the backend server (mandatory)
       id=STRING,             -- Use a pre-defined UUID instead of a random one
       qps=NUM,               -- Limit the number of queries per second to NUM, when using the `firstAvailable` policy
-      order=NUM,             -- The order of this server, used by the `leastOustanding` and `firstAvailable` policies
+      order=NUM,             -- The order of this server, used by the `leastOutstanding` and `firstAvailable` policies
       weight=NUM,            -- The weight of this server, used by the `wrandom`, `whashed` and `chashed` policies, default: 1
                              -- Supported values are a minimum of 1, and a maximum of 2147483647.
       pool=STRING|{STRING},  -- The pools this server belongs to (unset or empty string means default pool) as a string or table of strings
@@ -778,6 +781,12 @@ Status, Statistics and More
 
   Print the list of all availables DNS over HTTPS frontends.
 
+.. function:: showDOHResponseCodes()
+
+  .. versionadded:: 1.4.0
+
+  Print the HTTP response codes statistics for all availables DNS over HTTPS frontends.
+
 .. function:: showResponseLatency()
 
   Show a plot of the response time latency distribution
@@ -1072,10 +1081,14 @@ If you are looking for exact name matching, your might want to consider using a
   Represent a set of DNS suffixes for quick matching.
 
   .. method:: SuffixMatchNode:add(name)
+    .. versionchanged:: 1.4.0
+      This method now accepts strings, lists of DNSNames and lists of strings.
 
     Add a suffix to the current set.
 
     :param DNSName name: The suffix to add to the set.
+    :param string name: The suffix to add to the set.
+    :param table name: The suffixes to add to the set. Elements of the table should be of the same type, either DNSName or string.
 
   .. method:: SuffixMatchNode:check(name) -> bool
 
@@ -1103,6 +1116,20 @@ Other functions
 
   Hashes the password to generate a 16-byte key that can be used to pseudonymize IP addresses with IP cipher.
 
+.. function:: generateOCSPResponse(pathToServerCertificate, pathToCACertificate, pathToCAPrivateKey, outputFile, numberOfDaysOfValidity, numberOfMinutesOfValidity)
+
+  .. versionadded:: 1.4.0
+
+  When a local PKI is used to issue the certificate, or for testing purposes, :func:`generateOCSPResponse` can be used to generate an OCSP response file for a certificate, using the certificate and private key of the certification authority that signed that certificate.
+  The resulting file can be directly used with the :func:`addDOHLocal` or the :func:`addTLSLocal` functions.
+
+  :param string pathToServerCertificate: Path to a file containing the certificate used by the server.
+  :param string pathToCACertificate: Path to a file containing the certificate of the certification authority that was used to sign the server certificate.
+  :param string pathToCAPrivateKey: Path to a file containing the private key corresponding to the certification authority certificate.
+  :param string outputFile: Path to a file where the resulting OCSP response will be written to.
+  :param int numberOfDaysOfValidity: Number of days this OCSP response should be valid.
+  :param int numberOfMinutesOfValidity: Number of minutes this OCSP response should be valid, in addition to the number of days.
+
 DOHFrontend
 ~~~~~~~~~~~