Document supported TLS authentication modes

This commit updates the reference manual with short descriptions of
different TLS authentication modes, as mentioned in the RFC 9103,
Section 9.3 (Opportunistic TLS, Strict TLS, Mutual TLS), and mentions
how these authentication modes can be achieved via BIND's
configuration file.

diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst
index 94b3f90834dc29461afa0cf9b7fa2fe6d4bd3c40..4092a33abdc9fa552df460da7b9c778b231d885a 100644 (file)
--- a/doc/arm/reference.rst
+++ b/doc/arm/reference.rst
@@ -4896,6 +4896,56 @@ uses a temporary key and certificate created for the current :iscman:`named`
 session only, and ``none``, which can be used when setting up an HTTP
 listener with no encryption.
 
+BIND supports the following TLS authentication mechanisms described in
+the RFC 9103, Section 9.3: Opportunistic TLS, Strict TLS, and Mutual
+TLS.
+
+Opportunistic TLS provides encryption for data but does not provide
+any authentication for the channel. This mode is the default one and
+it is used whenever ``hostname`` and ``ca-file`` options are not set
+in ``tls`` statements in use. RFC 9103 allows optional fallback to
+clear-text DNS in the cases when TLS is not available. Still, BIND
+intentionally does not support that in order to protect from
+unexpected data leaks due to misconfiguration. Both BIND and its
+complementary tools either successfully establish a secure channel via
+TLS when instructed to do so or fail to establish a connection
+otherwise.
+
+Strict TLS provides server authentication via a pre-configured
+hostname for outgoing connections. This mechanism offers both channel
+confidentiality and channel authentication (of the server). In order
+to achieve Strict TLS, one needs to use ``hostname`` and, optionally,
+``ca-file`` options in the ``tls`` statements used for establishing
+outgoing connections (e.g. the ones used to download zone from
+primaries via TLS). Providing any of the mentioned options will enable
+server authentication. If ``hostname`` is provided but ``ca-file`` is
+missed, then the platform-specific certificate authority certificates
+are used for authentication. The set roughly corresponds to the one
+used by WEB-browsers to authenticate HTTPS hosts. On the other hand,
+if ``ca-file`` is provided but ``hostname`` is missing, then the
+remote side's IP address is used instead.
+
+Mutual TLS is an extension to Strict TLS that provides channel
+confidentiality and mutual channel authentication. It builds up upon
+the clients offering client certificates when establishing connections
+and them doing the server authentication as in the case of Strict
+TLS. The server verifies the provided client certificates and accepts
+the TLS connection in case of successful verification or rejects it
+otherwise. In order to instruct the server to require and verify
+client TLS certificates, one needs to specify the ``ca-file`` option
+in ``tls`` configurations used to configure server listeners. The
+provided file must contain certificate authority certificates used to
+issue client certificates. In most cases, one should build one's own
+TLS certificate authority specifically to issue client certificates
+and include the certificate authority certificate into the file.
+
+For authenticating zone transfers over TLS, Mutual TLS might be
+considered a standalone solution, while Strict TLS paired with
+TSIG-based authentication and, optionally, IP-based access lists,
+might be considered acceptable for most practical purposes. Mutual TLS
+has the advantage of not requiring TSIG and thus, not having security
+issues related to shared cryptographic secrets.
+
 .. _http:
 
 ``http`` Statement Grammar