--- /dev/null
+TLS Certificates Management
+===========================
+
+TLS certificates and keys are used in several places of :program:`dnsdist`, dealing with incoming connections over :doc:`../guides/dns-over-tls`, :doc:`../guides/dns-over-https`, :doc:`../guides/dns-over-http3` and :doc:`../guides/dns-over-quic`.
+
+The related functions (:func:`addTLSLocal`, :func:`addDOHLocal`, :func:`addDOH3Local` and :func:`addDOQLocal`) accept:
+
+- a path to a X.509 certificate file in ``PEM`` format, or a list of paths to such files, or a :class:`TLSCertificate` object
+- a path to the private key file corresponding to the certificate, or a list of paths to such files whose order should match the certificate files ones. This parameter is ignored if the first one contains :class:`TLSCertificate` objects, as keys are then retrieved from the objects.
+
+For example, to load two certificates, one ``RSA`` and one ``ECDSA`` one:
+
+.. code-block:: lua
+
+ addTLSLocal("192.0.2.1:853", { "/path/to/rsa/pem", "/path/to/ecdsa/pem" }, { "/path/to/rsa/key", "/path/to/ecdsa/key" })
+
+Password-protected PKCS12 files
+-------------------------------
+
+.. note::
+
+ ``PKCS12`` support requires the use of the ``openssl`` TLS provider.
+
+:program:`dnsdist` can use password-protected ``PKCS12`` certificates and keys. The certificate and key are loaded from a password-protected file using :func:`newTLSCertificate`
+which returns a :class:`TLSCertificate` object, which can then be passed to :func:`addTLSLocal`, :func:`addDOHLocal`, :func:`addDOH3Local` and :func:`addDOQLocal`.
+
+.. code-block:: lua
+
+ newTLSCertificate("path/to/domain.p12", {password="passphrase"}) -- use a password protected PKCS12 file
+
+Reloading certificates
+----------------------
+
+There are two ways to instruct :program:`dnsdist` to reload the certificate and key files from disk. The easiest one is to use :func:`reloadAllCertificates` which reload all :doc:`../guides/dnscrypt` and TLS certificates, along with their associated keys.
+The second allows a finer-grained, per-bind, approach:
+
+.. code-block:: lua
+
+ -- reload certificates and keys for DoT binds:
+ for idx = 0, getTLSFrontendCount() - 1 do
+ frontend = getTLSFrontend(idx)
+ frontend:reloadCertificates()
+ end
+
+ -- reload certificates and keys for DoH binds:
+ for idx = 0, getDOHFrontendCount() - 1 do
+ frontend = getDOHFrontend(idx)
+ frontend:reloadCertificates()
+ end
+
+TLS sessions
+------------
+
+See :doc:`tls-sessions-management`.
+
+OCSP stapling
+-------------
+
+See :doc:`ocsp-stapling`.
``internalPipeBufferSize`` now defaults to 1048576 on Linux.
.. versionchanged:: 1.8.0
- ``certFile`` now accepts a TLSCertificate object or a list of such objects (see :func:`newTLSCertificate`)
+ ``certFile`` now accepts a :class:`TLSCertificate` object or a list of such objects (see :func:`newTLSCertificate`)
``additionalAddresses``, ``ignoreTLSConfigurationErrors`` and ``keepIncomingHeaders`` options added.
.. versionchanged:: 1.9.0
``enableProxyProtocol``, ``library``, ``proxyProtocolOutsideTLS`` and ``readAhead`` options added.
- Listen on the specified address and TCP port for incoming DNS over HTTPS connections, presenting the specified X.509 certificate.
+ Listen on the specified address and TCP port for incoming DNS over HTTPS connections, presenting the specified X.509 certificate. See :doc:`../advanced/tls-certificates-management` for details about the handling of TLS certificates and keys.
If no certificate (or key) files are specified, listen for incoming DNS over HTTP connections instead.
More information is available in :doc:`../guides/dns-over-https`.
:param str address: The IP Address with an optional port to listen on.
The default port is 443.
- :param str certFile(s): The path to a X.509 certificate file in PEM format, a list of paths to such files, or a TLSCertificate object.
- :param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if ``certFile`` contains TLSCertificate objects.
+ :param str certFile(s): The path to a X.509 certificate file in PEM format, a list of paths to such files, or a :class:`TLSCertificate` object.
+ :param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if ``certFile`` contains :class:`TLSCertificate` objects.
:param str-or-list urls: The path part of a URL, or a list of paths, to accept queries on. Any query with a path matching exactly one of these will be treated as a DoH query (sub-paths can be accepted by setting the ``exactPathMatching`` to false). The default is /dns-query.
:param table options: A table with key: value pairs with listen options.
.. versionadded:: 1.9.0
- Listen on the specified address and UDP port for incoming DNS over HTTP3 connections, presenting the specified X.509 certificate.
+ Listen on the specified address and UDP port for incoming DNS over HTTP3 connections, presenting the specified X.509 certificate. See :doc:`../advanced/tls-certificates-management` for details about the handling of TLS certificates and keys.
More information is available in :doc:`../guides/dns-over-http3`.
:param str address: The IP Address with an optional port to listen on.
The default port is 443.
- :param str certFile(s): The path to a X.509 certificate file in PEM format, a list of paths to such files, or a TLSCertificate object.
- :param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if ``certFile`` contains TLSCertificate objects.
+ :param str certFile(s): The path to a X.509 certificate file in PEM format, a list of paths to such files, or a :class:`TLSCertificate` object.
+ :param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if ``certFile`` contains :class:`TLSCertificate` objects.
:param table options: A table with key: value pairs with listen options.
Options:
.. versionadded:: 1.9.0
Listen on the specified address and UDP port for incoming DNS over QUIC connections, presenting the specified X.509 certificate.
+ See :doc:`../advanced/tls-certificates-management` for details about the handling of TLS certificates and keys.
+ More information is available at :doc:`../guides/dns-over-quic`.
:param str address: The IP Address with an optional port to listen on.
The default port is 853.
- :param str certFile(s): The path to a X.509 certificate file in PEM format, a list of paths to such files, or a TLSCertificate object.
- :param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if ``certFile`` contains TLSCertificate objects.
+ :param str certFile(s): The path to a X.509 certificate file in PEM format, a list of paths to such files, or a :class:`TLSCertificate` object.
+ :param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if ``certFile`` contains :class:`TLSCertificate` objects.
:param table options: A table with key: value pairs with listen options.
Options:
.. versionchanged:: 1.8.0
``tlsAsyncMode`` option added.
.. versionchanged:: 1.8.0
- ``certFile`` now accepts a TLSCertificate object or a list of such objects (see :func:`newTLSCertificate`).
+ ``certFile`` now accepts a :class:`TLSCertificate` object or a list of such objects (see :func:`newTLSCertificate`).
``additionalAddresses``, ``ignoreTLSConfigurationErrors`` and ``ktls`` options added.
.. versionchanged:: 1.9.0
``enableProxyProtocol``, ``readAhead`` and ``proxyProtocolOutsideTLS`` options added.
- Listen on the specified address and TCP port for incoming DNS over TLS connections, presenting the specified X.509 certificate.
+ Listen on the specified address and TCP port for incoming DNS over TLS connections, presenting the specified X.509 certificate. See :doc:`../advanced/tls-certificates-management` for details about the handling of TLS certificates and keys.
+ More information is available at :doc:`../guides/dns-over-tls`.
:param str address: The IP Address with an optional port to listen on.
The default port is 853.
- :param str certFile(s): The path to a X.509 certificate file in PEM format, a list of paths to such files, or a TLSCertificate object.
- :param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if ``certFile`` contains TLSCertificate objects.
+ :param str certFile(s): The path to a X.509 certificate file in PEM format, a list of paths to such files, or a :class:`TLSCertificate` object.
+ :param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if ``certFile`` contains :class:`TLSCertificate` objects.
:param table options: A table with key: value pairs with listen options.
Options:
.. versionadded:: 1.8.0
- Creates a TLSCertificate object suited to be used with functions like :func:`addDOHLocal` and :func:`addTLSLocal` for TLS certificate configuration.
+ Creates a :class:`TLSCertificate` object suited to be used with functions like :func:`addDOHLocal`, :func:`addDOH3Local`, :func:`addDOQLocal` and :func:`addTLSLocal` for TLS certificate configuration.
- PKCS12 files are only supported by the ``openssl`` provider, password-protected or not.
+ ``PKCS12`` files are only supported by the ``openssl`` provider, password-protected or not.
- :param string pathToCert: Path to a file containing the certificate or a PKCS12 file containing both a certificate and a key.
+ :param string pathToCert: Path to a file containing the certificate or a ``PKCS12`` file containing both a certificate and a key.
:param table options: A table with key: value pairs with additional options.
Options:
* ``key="path/to/key"``: string - Path to a file containing the key corresponding to the certificate.
- * ``password="pass"``: string - Password protecting the PKCS12 file if appropriate.
+ * ``password="pass"``: string - Password protecting the ``PKCS12`` file if appropriate.
.. code-block:: lua
newTLSCertificate("path/to/pub.crt", {key="path/to/private.pem"})
- newTLSCertificate("path/to/domain.p12", {password="passphrase"}) -- use a password protected PKCS12 file
+ newTLSCertificate("path/to/domain.p12", {password="passphrase"}) -- use a password protected ``PKCS12`` file
DOHFrontend
~~~~~~~~~~~
Number of remaining nanoseconds elapsed since Unix epoch after subtracting the seconds from the `tv_sec` field.
+TLSCertificate
+~~~~~~~~~~~~~~
+
+.. class:: TLSCertificate
+
+ This object represents a TLS certificate. It can be created with :func:`newTLSCertificate` and used with :func:`addDOHLocal`, :func:`addDOH3Local`, :func:`addDOQLocal` and :func:`addTLSLocal` for TLS certificate configuration. It is mostly useful to deal with password-protected ``PKCS12`` certificates.
+
TLSContext
~~~~~~~~~~
projects / thirdparty / pdns.git / commitdiff
