DNSCrypt objects and functions

addDNSCryptBind(address, provider, certFile(s), keyFile(s)[, options])

Changed in version 1.4.0: Removed doTCP from the options. A listen socket on TCP is always created. certFile(s) and keyFile(s) now accept a list of files.

Changed in version 1.5.0: Added tcpListenQueueSize parameter.

Changed in version 1.6.0: Added maxInFlight and maxConcurrentTCPConnections parameters.

Adds a DNSCrypt listen socket on address.

Parameters:
  • address (string) – The address and port to listen on
  • provider (string) – The provider name for this bind
  • certFile(s) (str) – The path to a DNSCrypt certificate file, or a list of paths to such files.
  • keyFile(s) (str) – 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.
  • options (table) – A table with key: value pairs with options (see below)

Options:

  • doTCP=true: bool - Also bind on TCP on address, removed in 1.4.0.
  • reusePort=false: bool - Set the SO_REUSEPORT socket option.
  • tcpFastOpenQueueSize=0: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0
  • interface="": str - Sets the network interface to use
  • cpus={}: table - Set the CPU affinity for this listener thread, asking the scheduler to run it on a single CPU id, or a set of CPU ids. This parameter is only available if the OS provides the pthread_setaffinity_np() function.
  • tcpListenQueueSize=SOMAXCONN: int - Set the size of the listen queue. Default is SOMAXCONN.
  • maxInFlight=0: int - Maximum number of in-flight queries. The default is 0, which disables out-of-order processing.
  • maxConcurrentTCPConnections=0: int - Maximum number of concurrent incoming TCP connections. The default is 0 which means unlimited.
generateDNSCryptProviderKeys(publicKey, privateKey)

Generate a new provider keypair and write them to publicKey and privateKey.

Parameters:
  • publicKey (string) – path to write the public key to
  • privateKey (string) – path to write the private key to
generateDNSCryptCertificate(privatekey, certificate, keyfile, serial, validFrom, validUntil[, version])

generate a new resolver private key and related certificate, valid from the validFrom UNIX timestamp until the validUntil one, signed with the provider private key.

Parameters:
  • privatekey (string) – Path to the private key of the provider
  • certificate (string) – Path where to write the certificate file
  • keyfile (string) – Path where to write the private key for the certificate
  • serial (int) – The certificate’s serial number
  • validFrom (int) – Unix timestamp from when the certificate will be valid
  • validUntil (int) – Unix timestamp until when the certificate will be valid
  • version (DNSCryptExchangeVersion) – The exchange version to use. Possible values are DNSCryptExchangeVersion::VERSION1 (default, X25519-XSalsa20Poly1305) and DNSCryptExchangeVersion::VERSION2 (X25519-XChacha20Poly1305)
printDNSCryptProviderFingerprint(keyfile)

Display the fingerprint of the provided resolver public key

Parameters:keyfile (string) – Path to the key file
showDNSCryptBinds()

Display the currently configured DNSCrypt binds

getDNSCryptBind(n) → DNSCryptContext

Return the DNSCryptContext object corresponding to the bind n.

getDNSCryptBindCount()

New in version 1.5.0.

Return the number of DNSCrypt binds.

Certificates

class DNSCryptCert

Represents a DNSCrypt certificate.

:getClientMagic() → string

Return this certificate’s client magic value.

:getEsVersion() → string

Return the cryptographic construction to use with this certificate,.

:getMagic() → string

Return the certificate magic number.

:getProtocolMinorVersion() → string

Return this certificate’s minor version.

:getResolverPublicKey() → string

Return the public key corresponding to this certificate.

:getSerial() → int

Return the certificate serial number.

:getSignature() → string

Return this certificate’s signature.

:getTSEnd() → int

Return the date that the certificate is valid from, as a Unix timestamp.

:getTSStart() → int

Return the date that the certificate is valid until (inclusive), as a Unix timestamp

Certificate Pairs

class DNSCryptCertificatePair

Represents a pair of DNSCrypt certificate and associated key

:getCertificate() → DNSCryptCert

Return the certificate.

:isActive() → bool

Return whether this pair is active and will be advertised to clients.

Context

class DNSCryptContext

Represents a DNSCrypt content. Can be used to rotate certs.

:addNewCertificate(cert, key[, active])

Add a new certificate to the given context. Active certificates are advertised to clients, inactive ones are not.

Parameters:
  • cert (DNSCryptCert) – The certificate to add to the context
  • key (DNSCryptPrivateKey) – The private key corresponding to the certificate
  • active (bool) – Whether the certificate should be advertised to clients. Default is true
:generateAndLoadInMemoryCertificate(keyfile, serial, begin, end[, version]) → bool

Changed in version 2.0.0: A return value indicating whether the certificate was correctly loaded has been added. Before 2.0.0 the method did not return any value.

Generate a new resolver key and the associated certificate in-memory, sign it with the provided provider key, and add it to the context. Returns true if the certificate was correctly loaded, false otherwise.

param string keyfile:
 Path to the provider key file to use
param int serial:
 The serial number of the certificate
param int begin:
 Unix timestamp from when the certificate is valid
param int end:Unix timestamp from until the certificate is valid
param DNSCryptExchangeVersion version:
 The exchange version to use. Possible values are DNSCryptExchangeVersion::VERSION1 (default, X25519-XSalsa20Poly1305) and DNSCryptExchangeVersion::VERSION2 (X25519-XChacha20Poly1305)
:getCertificate(index) → DNSCryptCert

Return the certificate with index index.

Parameters:index (int) – The index of the certificate, starting at 0
:getCertificatePair(index) → DNSCryptCertificatePair

Return the certificate pair with index index.

Parameters:index (int) – The index of the certificate, starting at 0
:getCertificatePair(index) → table of DNSCryptCertificatePair

Return a table of certificate pairs.

:getProviderName() → string

Return the provider name

:loadNewCertificate(certificate, keyfile[, active])

Load a new certificate and the corresponding private key. If active is false, the certificate will not be advertised to clients but can still be used to answer queries tied to it.

Parameters:
  • certificate (string) – Path to a certificate file
  • keyfile (string) – Path to the corresponding key file
  • active (bool) – Whether the certificate should be marked as active. Default is true
:markActive(serial)

Mark the certificate with serial serial as active, meaning it will be advertised to clients.

Parameters:serial (int) – The serial of the number to mark as active
:markInactive(serial)

Mark the certificate with serial serial as inactive, meaning it will not be advertised to clients but can still be used to answer queries tied to this certificate.

Parameters:serial (int) – The serial of the number to mark as inactive
:printCertificates()

Print all the certificates.

:reloadCertificates()

New in version 1.6.0.

Reload the current TLS certificate and key pairs.

:removeInactiveCertificate(serial)

Remove the certificate with serial serial. It will not be possible to answer queries tied to this certificate, so it should have been marked as inactive for a certain time before that. Active certificates should be marked as inactive before they can be removed.

Parameters:serial (int) – The serial of the number to remove