From: Remi Gacogne Date: Sun, 29 Oct 2017 22:14:27 +0000 (+0100) Subject: dnsdist: Document the new DNSCrypt calls, restore compatibility X-Git-Tag: dnsdist-1.3.0~37^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=55710b0f252932fe10a75e0fa9309a1b2174adc2;p=thirdparty%2Fpdns.git dnsdist: Document the new DNSCrypt calls, restore compatibility --- diff --git a/pdns/dnsdist-lua-bindings.cc b/pdns/dnsdist-lua-bindings.cc index 292bc48c2e..7889973462 100644 --- a/pdns/dnsdist-lua-bindings.cc +++ b/pdns/dnsdist-lua-bindings.cc @@ -288,7 +288,6 @@ void setupLuaBindings(bool client) #ifdef HAVE_DNSCRYPT /* DNSCryptContext bindings */ g_lua.registerFunction("getProviderName", [](const DNSCryptContext& ctx) { return ctx.getProviderName().toStringNoDot(); }); - g_lua.registerFunction("addNewCertificate", &DNSCryptContext::addNewCertificate); g_lua.registerFunction("markActive", &DNSCryptContext::markActive); g_lua.registerFunction("markInactive", &DNSCryptContext::markInactive); g_lua.registerFunction("removeInactiveCertificate", &DNSCryptContext::removeInactiveCertificate); @@ -327,14 +326,62 @@ void setupLuaBindings(bool client) } std::shared_ptr result = nullptr; - auto certs = ctx->getCertificates(); - if (idx < certs.size()) { - result = certs.at(idx); + auto pairs = ctx->getCertificates(); + if (idx < pairs.size()) { + result = pairs.at(idx); } return result; }); + g_lua.registerFunction::*)()>("getCurrentCertificate", [](std::shared_ptr ctx) { + + if (ctx == nullptr) { + throw std::runtime_error("DNSCryptContext::getCurrentCertificate() called on a nil value"); + } + + auto pairs = ctx->getCertificates(); + for (const auto& pair : pairs) { + if (pair->active) { + return pair->cert; + } + } + + throw std::runtime_error("This context has no active certificate"); + }); + + g_lua.registerFunction::*)()>("getOldCertificate", [](std::shared_ptr ctx) { + + if (ctx == nullptr) { + throw std::runtime_error("DNSCryptContext::getOldCertificate() called on a nil value"); + } + + auto pairs = ctx->getCertificates(); + for (const auto& pair : pairs) { + if (!pair->active) { + return pair->cert; + } + } + + throw std::runtime_error("This context has no inactive certificate"); + }); + + g_lua.registerFunction::*)()>("hasOldCertificate", [](std::shared_ptr ctx) { + + if (ctx == nullptr) { + throw std::runtime_error("DNSCryptContext::hasOldCertificate() called on a nil value"); + } + + auto pairs = ctx->getCertificates(); + for (const auto& pair : pairs) { + if (!pair->active) { + return true; + } + } + + return false; + }); + g_lua.registerFunction::*)()>("printCertificates", [](const std::shared_ptr ctx) { ostringstream ret; diff --git a/pdns/dnsdistdist/docs/reference/dnscrypt.rst b/pdns/dnsdistdist/docs/reference/dnscrypt.rst index f023e96a84..a119ae7a36 100644 --- a/pdns/dnsdistdist/docs/reference/dnscrypt.rst +++ b/pdns/dnsdistdist/docs/reference/dnscrypt.rst @@ -27,16 +27,18 @@ DNSCrypt objects and functions :param string privateKey: path to write the private key to .. function:: generateDNSCryptCertificate(privatekey, certificate, keyfile, serial, validFrom, validUntil, version) + .. versionchanged:: 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. - :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). + :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) @@ -95,6 +97,22 @@ Certificates 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 ------- @@ -102,22 +120,57 @@ Context Represents a DNSCrypt content. Can be used to rotate certs. - .. method:: DNSCryptContext:generateAndLoadInMemoryCertificate(keyfile, serial, begin, end) + .. method:: DNSCryptContext:addNewCertificate(cert, key[, active]) + + .. versionadded:: 1.3.0 + + Add a new certificate to the the given context. Active certificates are advertised to + clients, inactive ones are not. - Generate a new resolver key and the associated certificate in-memory, sign it with the provided provider key, and use the new certificate + :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 - :param string keyfile: Path to the key file to use + .. method:: DNSCryptContext:generateAndLoadInMemoryCertificate(keyfile, serial, begin, end [, version]) + + .. versionchanged:: 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 + + :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:getCertificatePair(index) -> DNSCryptCertificatePair + + .. versionadded:: 1.3.0 + + 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 + + .. versionadded:: 1.3.0 + + Return a table of certificate pairs. .. method:: DNSCryptContext:getCurrentCertificate() -> DNSCryptCert - Return the current certificate. + .. deprecated:: 1.3.0 + + Return the current certificate. Deprecated as of 1.3.0 since more than one active certificate + is now supported. For compatibility, it will return the first active certificate. .. method:: DNSCryptContext:getOldCertificate() -> DNSCryptCert - Return the previous certificate. + .. deprecated:: 1.3.0 + + Return the previous certificate. Deprecated as of 1.3.0 since more than one inactive certificate + is now supported. For compatibility, it will return the first inactive certificate. .. method:: DNSCryptContext:getProviderName() -> string @@ -125,11 +178,55 @@ Context .. method:: DNSCryptContext:hasOldCertificate() -> bool - Whether or not the context has a previous certificate, from a certificate rotation. + .. deprecated:: 1.3.0 + + Whether or not the context has a previous certificate, from a certificate rotation. Since + 1.3.0 several certificates active and inactive certificates can be used at the same time, + so this function is deprecated. In order to keep compatibility this function will simply + return `true` if at least one inactive certificate is configured. - .. method:: DNSCryptContext:loadNewCertificate(certificate, keyfile) + .. method:: DNSCryptContext:loadNewCertificate(certificate, keyfile[, active]) - Load a new certificate and the corresponding private key, and use it + .. versionchanged:: 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. :param string certificate: Path to a certificate file :param string keyfile: Path to a the corresponding key file + :param bool active: Whether the certificate should be marked as active. Default is true + + .. method:: DNSCryptContext:markActive(serial) + + .. versionadded:: 1.3.0 + + 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) + + .. versionadded:: 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. + + :param int serial: The serial of the number to mark as inactive + + .. method:: DNSCryptContext:printCertificates() + + .. versionadded:: 1.3.0 + + Print all the certificates. + + .. method:: DNSCryptContext:removeInactiveCertificate(serial) + + .. versionadded:: 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. + + :param int serial: The serial of the number to remove