TLS Certificates Management

TLS certificates and keys are used in several places of dnsdist, dealing with incoming connections over DNS-over-TLS, DNS-over-HTTPS (DoH), DNS-over-HTTP/3 (DoH3) and DNS-over-QUIC (DoQ).

The related functions (addTLSLocal(), addDOHLocal(), addDOH3Local() and addDOQLocal()) accept:

• a path to a X.509 certificate file in PEM format, or a list of paths to such files, or a 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 TLSCertificate objects, as keys are then retrieved from the objects.

For example, to load two certificates, one RSA and one ECDSA one:

addTLSLocal("192.0.2.1:853", { "/path/to/rsa/pem", "/path/to/ecdsa/pem" }, { "/path/to/rsa/key", "/path/to/ecdsa/key" })

Before 2.0.0 the OpenSSL provider did not support selecting the certificate to provide to the client based on the value sent in Server Name Indication extension of the Client Hello message, so providing more than one certificate only made sense to support different algorithms, like RSA and ECDSA. The GnuTLS provider had no such limitation. Since 2.0.0, the OpenSSL provider is capable of selecting the certificate based on the SNI value, so loading several certificates for different hostnames is now possible.

addTLSLocal("192.0.2.1:853", { "/path/to/cert-hostname1", "/path/to/cert-hostname2" }, { "/path/to/key-hostname1", "/path/to/key-hostname2" })

Password-protected PKCS12 files

Note

PKCS12 support requires the use of the openssl TLS provider.

dnsdist can use password-protected PKCS12 certificates and keys. The certificate and key are loaded from a password-protected file using newTLSCertificate() which returns a TLSCertificate object, which can then be passed to addTLSLocal(), addDOHLocal(), addDOH3Local() and addDOQLocal().

myCertObject = newTLSCertificate("path/to/domain.p12", {password="passphrase"}) -- use a password protected PKCS12 file

Reloading certificates

There are two ways to instruct dnsdist to reload the certificate and key files from disk. The easiest one is to use reloadAllCertificates() which reload all DNSCrypt and TLS certificates, along with their associated keys. The second allows a finer-grained, per-bind, approach:

-- 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

-- reload certificates and keys for DoQ binds:
for idx = 0, getDOQFrontendCount() - 1 do
  frontend = getDOQFrontend(idx)
  frontend:reloadCertificates()
end

-- reload certificates and keys for DoH3 binds:
for idx = 0, getDOH3FrontendCount() - 1 do
  frontend = getDOH3Frontend(idx)
  frontend:reloadCertificates()
end

TLS sessions

See TLS Sessions Management.

OCSP stapling

See OCSP Stapling.