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" })

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.