DNSCrypt objects and functions
==============================

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

  .. versionchanged:: 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.

  .. versionchanged:: 1.5.0
    Added ``tcpListenQueueSize`` parameter.

  .. versionchanged:: 1.6.0
    Added ``maxInFlight`` and ``maxConcurrentTCPConnections`` parameters.

  Adds a DNSCrypt listen socket on ``address``.

  :param string address: The address and port to listen on
  :param string provider: The provider name for this bind
  :param str certFile(s): The path to a DNSCrypt certificate file, or a list of paths to such files.
  :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.
  :param table options: 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.

.. function:: generateDNSCryptProviderKeys(publicKey, privateKey)

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

  :param string publicKey: path to write the public key to
  :param string privateKey: path to write the private key to

.. function:: 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.

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

.. function:: printDNSCryptProviderFingerprint(keyfile)

  Display the fingerprint of the provided resolver public key

  :param string keyfile: Path to the key file

.. function:: showDNSCryptBinds()

  Display the currently configured DNSCrypt binds

.. function:: getDNSCryptBind(n) -> DNSCryptContext

  Return the :class:`DNSCryptContext` object corresponding to the bind ``n``.

.. function:: getDNSCryptBindCount()

  .. versionadded:: 1.5.0

  Return the number of DNSCrypt binds.

Certificates
------------

.. class:: DNSCryptCert

  Represents a DNSCrypt certificate.

  .. method:: DNSCryptCert:getClientMagic() -> string

    Return this certificate's client magic value.

  .. method:: DNSCryptCert:getEsVersion() -> string

    Return the cryptographic construction to use with this certificate,.

  .. method:: DNSCryptCert:getMagic() -> string

    Return the certificate magic number.

  .. method:: DNSCryptCert:getProtocolMinorVersion() -> string

    Return this certificate's minor version.

  .. method:: DNSCryptCert:getResolverPublicKey() -> string

    Return the public key corresponding to this certificate.

  .. method:: DNSCryptCert:getSerial() -> int

    Return the certificate serial number.

  .. method:: DNSCryptCert:getSignature() -> string

    Return this certificate's signature.

  .. method:: DNSCryptCert:getTSEnd() -> int

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

  .. method:: DNSCryptCert: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

  .. method:: DNSCryptCertificatePair:getCertificate() -> DNSCryptCert

    Return the certificate.

  .. method:: DNSCryptCertificatePair: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.

  .. method:: DNSCryptContext:addNewCertificate(cert, key[, active])

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

    :param DNSCryptCert cert: The certificate to add to the context
    :param DNSCryptPrivateKey key: The private key corresponding to the certificate
    :param bool active: Whether the certificate should be advertised to clients. Default is true

  .. method:: DNSCryptContext:generateAndLoadInMemoryCertificate(keyfile, serial, begin, end [, version]) -> bool

  .. versionchanged:: 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)

  .. method:: DNSCryptContext:getCertificate(index) -> DNSCryptCert

    Return the certificate with index `index`.

    :param int index: The index of the certificate, starting at 0

  .. method:: DNSCryptContext:getCertificatePair(index) -> DNSCryptCertificatePair

    Return the certificate pair with index `index`.

    :param int index: The index of the certificate, starting at 0

  .. method:: DNSCryptContext:getCertificatePair(index) -> table of DNSCryptCertificatePair

    Return a table of certificate pairs.

  .. method:: DNSCryptContext:getProviderName() -> string

    Return the provider name

  .. method:: DNSCryptContext: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.

    :param string certificate: Path to a certificate file
    :param string keyfile: Path to the corresponding key file
    :param bool active: Whether the certificate should be marked as active. Default is true

  .. method:: DNSCryptContext:markActive(serial)

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

    :param int serial: The serial of the number to mark as active

  .. method:: DNSCryptContext: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.

    :param int serial: The serial of the number to mark as inactive

  .. method:: DNSCryptContext:printCertificates()

    Print all the certificates.

  .. method:: DNSCryptContext:reloadCertificates()

    .. versionadded:: 1.6.0

    Reload the current TLS certificate and key pairs.

  .. method:: DNSCryptContext: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.

    :param int serial: The serial of the number to remove
