{"getTopRules", true, "[top]", "return the `top` rules"},
{"getTopSelfAnsweredResponseRules", true, "[top]", "return the `top` self-answered response rules"},
{"getTopXFRResponseRules", true, "[top]", "return the `top` XFR response rules"},
- {"getTLSContext", true, "n", "returns the TLS context with index n"},
{"getTLSFrontend", true, "n", "returns the TLS frontend with index n"},
{"getTLSFrontendCount", true, "", "returns the number of DoT listeners"},
{"getVerbose", true, "", "get whether log messages at the verbose level will be logged"},
{"showServerPolicy", true, "", "show name of currently operational server selection policy"},
{"showServers", true, "[{showUUIDs=false}]", "output all servers, optionally with their UUIDs"},
{"showTCPStats", true, "", "show some statistics regarding TCP"},
- {"showTLSContexts", true, "", "list all the available TLS contexts"},
{"showTLSErrorCounters", true, "", "show metrics about TLS handshake failures"},
+ {"showTLSFrontends", true, "", "list all the available TLS contexts"},
{"showVersion", true, "", "show the current version"},
{"showWebserverConfig", true, "", "Show the current webserver configuration"},
{"shutdown", true, "", "shut down `dnsdist`"},
#endif
});
- luaCtx.writeFunction("showTLSContexts", []() {
+ luaCtx.writeFunction("showTLSFrontends", []() {
#ifdef HAVE_DNS_OVER_TLS
setLuaNoSideEffect();
try {
#endif
});
- luaCtx.writeFunction("getTLSContext", [](uint64_t index) {
- std::shared_ptr<TLSCtx> result = nullptr;
-#ifdef HAVE_DNS_OVER_TLS
- setLuaNoSideEffect();
- const auto tlsFrontends = dnsdist::getDoTFrontends();
- try {
- if (index < tlsFrontends.size()) {
- result = tlsFrontends.at(index)->getContext();
- }
- else {
- errlog("Error: trying to get TLS context with index %d but we only have %d context(s)\n", index, tlsFrontends.size());
- g_outputBuffer = "Error: trying to get TLS context with index " + std::to_string(index) + " but we only have " + std::to_string(tlsFrontends.size()) + " context(s)\n";
- }
- }
- catch (const std::exception& e) {
- g_outputBuffer = "Error while trying to get TLS context with index " + std::to_string(index) + ": " + string(e.what()) + "\n";
- errlog("Error while trying to get TLS context with index %d: %s\n", index, string(e.what()));
- }
-#else
- g_outputBuffer="DNS over TLS support is not present!\n";
-#endif
- return result;
- });
-
luaCtx.writeFunction("getTLSFrontend", [](uint64_t index) {
std::shared_ptr<TLSFrontend> result = nullptr;
#ifdef HAVE_DNS_OVER_TLS
return dnsdist::getDoTFrontends().size();
});
- luaCtx.registerFunction<void (std::shared_ptr<TLSCtx>::*)()>("rotateTicketsKey", [](std::shared_ptr<TLSCtx>& ctx) {
- if (ctx != nullptr) {
- ctx->rotateTicketsKey(time(nullptr));
- }
- });
-
- luaCtx.registerFunction<void (std::shared_ptr<TLSCtx>::*)(const std::string&)>("loadTicketsKeys", [](std::shared_ptr<TLSCtx>& ctx, const std::string& file) {
- if (ctx != nullptr) {
- ctx->loadTicketsKeys(file);
- }
- });
-
luaCtx.registerFunction<std::string (std::shared_ptr<TLSFrontend>::*)() const>("getAddressAndPort", [](const std::shared_ptr<TLSFrontend>& frontend) {
if (frontend == nullptr) {
return std::string();
When the automatic rotation mechanism kicks in a new, random key will be added to the list of keys. With the OpenSSL provider, the new key becomes active, so new tickets will be encrypted with this key, and the existing keys become passive and only be used to decrypt existing tickets. With the GnuTLS provider only one key is currently supported so the existing keys are immediately discarded.
This automatic rotation can be disabled by setting ``ticketsKeysRotationDelay`` to 0.
-It is also possible to manually request a STEK rotation using the :func:`getDOHFrontend` (DoH) and :func:`getTLSContext` (DoT) functions to retrieve the bind object, and calling its ``rotateTicketsKey`` method (:meth:`DOHFrontend:rotateTicketsKey`, :meth:`TLSContext:rotateTicketsKey`).
+It is also possible to manually request a STEK rotation using the :func:`getDOHFrontend` (DoH) and :func:`getTLSFrontend` (DoT) functions to retrieve the bind object, and calling its ``rotateTicketsKey`` method (:meth:`DOHFrontend:rotateTicketsKey`, :meth:`TLSFrontend:rotateTicketsKey`).
The default settings should be fine for most deployments, but generating a random key for every dnsdist instance will not allow resuming the session from a different instance in a cluster. It is also not very useful to have a different key for every :func:`addTLSLocal` and :func:`addDOHLocal` directive if you are using the same certificate and key, and it would be much better to use the same STEK to improve the session resumption ratio.
If the file contains several keys, so for example 240 random bytes, dnsdist will load several STEKs, using the last one for encrypting new tickets and all of them to decrypt existing tickets.
In order to rotate the keys at runtime, it is possible to instruct dnsdist to reload the content of the certificates, keys, and STEKs from the same file used at configuration time, for all DoH and DoH binds, by issuing the :func:`reloadAllCertificates` command.
-It can also be done one bind at a time using the :func:`getDOHFrontend` (DoH) and :func:`getTLSContext` (DoT) functions to retrieve the bind object, and calling its ``loadTicketsKeys`` method (:meth:`DOHFrontend:loadTicketsKeys`, :meth:`TLSContext:loadTicketsKeys`).
+It can also be done one bind at a time using the :func:`getDOHFrontend` (DoH) and :func:`getTLSFrontend` (DoT) functions to retrieve the bind object, and calling its ``loadTicketsKeys`` method (:meth:`DOHFrontend:loadTicketsKeys`, :meth:`TLSFrontend:loadTicketsKeys`).
One possible way of handling manual rotation of the key would be to first:
.. function:: getTLSContext(idx)
+ .. versionchanged:: 2.0.0
+ This directive was removed in version 2.0.0, see :func:`getTLSFrontend` instead.
+
Return the TLSContext object for the context of index ``idx``.
.. function:: getTLSFrontend(idx)
.. function:: showTLSContexts()
- Print the list of all available DNS over TLS contexts.
+ .. versionchanged:: 2.0.0
+ This function has been renamed to :func:`showTLSFrontends`.
+
+ Print the list of all available DNS over TLS frontends.
.. function:: showTLSErrorCounters()
Display metrics about TLS handshake failures.
+.. function:: showTLSContexts()
+
+ .. versionadded:: 2.0.0
+
+ .. note::
+ Before 2.0.0 this function was called ``showTLSContexts``.
+
+ Print the list of all available DNS over TLS frontends.
+
.. function:: showVersion()
Print the version of dnsdist
.. class:: TLSContext
+ .. versionchanged:: 2.0.0
+ This class has been removed in version 2.0.0.
+
This object represents an address and port dnsdist is listening on for DNS over TLS queries.
.. method:: TLSContext:loadTicketsKeys(ticketsKeysFile)
Upgrade Guide
=============
+1.9.x to 2.0.0
+--------------
+
+:func:`showTLSContexts` has been renamed to :func:`showTLSFrontends`.
+:func:`getTLSContext` and the associated :class:`TLSContext` have been removed, please use :func:`getTLSFrontend` and the associated :class:`TLSFrontend` instead.
+
1.8.x to 1.9.0
--------------
# rotate the TLS session ticket keys several times, but keep the previously active one around so we can resume
for _ in range(self._numberOfKeys - 1):
- self.sendConsoleCommand("getTLSContext(0):rotateTicketsKey()")
+ self.sendConsoleCommand("getTLSFrontend(0):rotateTicketsKey()")
# the session should be resumed and a new ticket, encrypted with the newly active key, should be stored
self.assertTrue(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot', '/tmp/session.dot'))
# rotate the TLS session ticket keys several times, but keep the previously active one around so we can resume
for _ in range(self._numberOfKeys - 1):
- self.sendConsoleCommand("getTLSContext(0):rotateTicketsKey()")
+ self.sendConsoleCommand("getTLSFrontend(0):rotateTicketsKey()")
self.assertTrue(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot', '/tmp/session.dot'))
# rotate the TLS session ticket keys several times, not keeping any key around this time!
for _ in range(self._numberOfKeys):
- self.sendConsoleCommand("getTLSContext(0):rotateTicketsKey()")
+ self.sendConsoleCommand("getTLSFrontend(0):rotateTicketsKey()")
# we should not be able to resume
self.assertFalse(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot', '/tmp/session.dot'))
self.generateTicketKeysFile(self._numberOfKeys, '/tmp/ticketKeys.1')
self.generateTicketKeysFile(self._numberOfKeys - 1, '/tmp/ticketKeys.2')
# load all ticket keys from the file
- self.sendConsoleCommand("getTLSContext(0):loadTicketsKeys('/tmp/ticketKeys.1')")
+ self.sendConsoleCommand("getTLSFrontend(0):loadTicketsKeys('/tmp/ticketKeys.1')")
# create a new session, resume it
self.assertFalse(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot', None))
self.assertTrue(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot', '/tmp/session.dot', allowNoTicket=True))
# reload the same keys
- self.sendConsoleCommand("getTLSContext(0):loadTicketsKeys('/tmp/ticketKeys.1')")
+ self.sendConsoleCommand("getTLSFrontend(0):loadTicketsKeys('/tmp/ticketKeys.1')")
# should still be able to resume
self.assertTrue(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot', '/tmp/session.dot', allowNoTicket=True))
# rotate the TLS session ticket keys several times, but keep the previously active one around so we can resume
for _ in range(self._numberOfKeys - 1):
- self.sendConsoleCommand("getTLSContext(0):rotateTicketsKey()")
+ self.sendConsoleCommand("getTLSFrontend(0):rotateTicketsKey()")
# should still be able to resume
self.assertTrue(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot', '/tmp/session.dot'))
# reload the same keys
- self.sendConsoleCommand("getTLSContext(0):loadTicketsKeys('/tmp/ticketKeys.1')")
+ self.sendConsoleCommand("getTLSFrontend(0):loadTicketsKeys('/tmp/ticketKeys.1')")
# since the last key was only present in memory, we should not be able to resume
self.assertFalse(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot', '/tmp/session.dot'))
# generate a file with only _numberOfKeys - 1 keys, so the last active one should still be around after loading that one
self.generateTicketKeysFile(self._numberOfKeys - 1, '/tmp/ticketKeys.2')
- self.sendConsoleCommand("getTLSContext(0):loadTicketsKeys('/tmp/ticketKeys.2')")
+ self.sendConsoleCommand("getTLSFrontend(0):loadTicketsKeys('/tmp/ticketKeys.2')")
# we should be able to resume, and the ticket should be re-encrypted with the new key (NOTE THAT we store into a new file!!)
self.assertTrue(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot.2', '/tmp/session.dot'))
self.assertTrue(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot.2', '/tmp/session.dot.2', allowNoTicket=True))
# rotate all keys, we should not be able to resume
for _ in range(self._numberOfKeys):
- self.sendConsoleCommand("getTLSContext(0):rotateTicketsKey()")
+ self.sendConsoleCommand("getTLSFrontend(0):rotateTicketsKey()")
self.assertFalse(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot.3', '/tmp/session.dot.2'))
# reload from file 1, the old session should resume
- self.sendConsoleCommand("getTLSContext(0):loadTicketsKeys('/tmp/ticketKeys.1')")
+ self.sendConsoleCommand("getTLSFrontend(0):loadTicketsKeys('/tmp/ticketKeys.1')")
self.assertTrue(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot', '/tmp/session.dot', allowNoTicket=True))
# reload from file 2, the latest session should resume
- self.sendConsoleCommand("getTLSContext(0):loadTicketsKeys('/tmp/ticketKeys.2')")
+ self.sendConsoleCommand("getTLSFrontend(0):loadTicketsKeys('/tmp/ticketKeys.2')")
self.assertTrue(self.checkSessionResumed('127.0.0.1', self._tlsServerPort, self._serverName, self._caCert, '/tmp/session.dot.2', '/tmp/session.dot.2', allowNoTicket=True))
projects / thirdparty / pdns.git / commitdiff
