DNSCrypt objects and functions

addDNSCryptBind(address, provider, certificate, keyfile[, options])

Changed in version 1.3.0: cpus option added.

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
  • certificate (string) – Path to the certificate file
  • keyfile (string) – Path to the key file of the certificate
  • options (table) – A table with key: value pairs with options (see below)

Options:

  • doTCP=true: bool - Also bind on TCP on address.
  • reusePort=false: bool - Set the SO_REUSEPORT socket option.
  • tcpFastOpenSize=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.
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])

Changed in version 1.3.0: version optional parameter added.

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.

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 the certificate is valid from, as a Unix timestamp.

:getTSStart() → int

Return the date 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])

New in version 1.3.0.

Add a new certificate to the 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])

Changed in version 1.3.0: version optional parameter added.

Generate a new resolver key and the associated certificate in-memory, sign it with the provided provider key, and add it to the context

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

Deprecated since version 1.3.0: Removed as it relied on one certificate. See DNSCryptContext:getCertificate().

Return the current certificate.

:getOldCertificate() → DNSCryptCert

Deprecated since version 1.3.0: Removed as it relied on one certificate.

Return the previous certificate.

:hasOldCertificate() → bool

Deprecated since version 1.3.0: Removed as it relied on one certificate.

Whether or not the context has a previous certificate, from a certificate rotation.

:getCertificate(index) → DNSCryptCert

New in version 1.3.0.

Return the certificate with index index.

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

New in version 1.3.0.

Return the certificate pair with index index.

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

New in version 1.3.0.

Return a table of certificate pairs.

:getProviderName() → string

Return the provider name

:loadNewCertificate(certificate, keyfile[, active])

Changed in version 1.3.0: active optional parameter added.

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 a the corresponding key file
  • active (bool) – Whether the certificate should be marked as active. Default is true
:markActive(serial)

New in version 1.3.0.

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)

New in version 1.3.0.

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

New in version 1.3.0.

Print all the certificates.

:removeInactiveCertificate(serial)

New in version 1.3.0.

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