diff --git a/doc/modules.rst b/doc/modules.rst index a9c2e194a4423fa73b33a17dba08eeb69d314615..2b92c438826c9e3359d65592ec44a214f646a004 100644 --- a/doc/modules.rst +++ b/doc/modules.rst @@ -21,4 +21,4 @@ Knot DNS Resolver modules .. include:: ../modules/ketcd/README.rst .. include:: ../modules/dns64/README.rst .. include:: ../modules/renumber/README.rst -.. include:: ../modules/cookiectl/README.rst +.. include:: ../modules/cookies/README.rst diff --git a/modules/cookies/README.rst b/modules/cookies/README.rst index 7e3a73029016e68725350ef1a482a567e526683a..2a0d5132f8da2a53c3eea891beaf997da8865341 100644 --- a/modules/cookies/README.rst +++ b/modules/cookies/README.rst @@ -1,37 +1,41 @@ -.. _mod-cookiectl: +.. _mod-cookies: DNS Cookies ----------- -The module is used for configuring the :rfc:`7873` DNS cookies functionality behaviour. +The module performs most of the :rfc:`7873` DNS cookies functionality. Its main purpose is to check the cookies of inbound queries and responses. It is also used to alter the behaviour of the cookie functionality. Example Configuration ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: lua - -- Load the module. - modules = { 'cookiectl' } + -- Load the module before the 'iterate' layer. + modules = { + 'cookies < iterate' + } -- Configure the client part of the resolver. Set 8 bytes of the client -- secret and choose the hashing algorithm to be used. - cookiectl.config( { ['client_secret'] = { 0, 1, 2, 3, 4, 5, 6, 7 }, - ['client_cookie_alg'] = 'FNV-64' } ) + cookies.config( { ['client_secret'] = { 0, 1, 2, 3, 4, 5, 6, 7 }, + ['client_cookie_alg'] = 'FNV-64' } ) -- Configure the server part of the resolver. Sets a string to be used -- as server secret. Also chooses the hashing algorithm to be used. - cookiectl.config( { ['server_secret'] = 'secret key', - ['server_cookie_alg'] = 'FNV-64' } ) + cookies.config( { ['server_secret'] = 'secret key', + ['server_cookie_alg'] = 'FNV-64' } ) -- Enable client cookie functionality. (Add cookies into outbound -- queries.) - cookiectl.config( { ['client_enabled'] = true } ) + cookies.config( { ['client_enabled'] = true } ) -- Enable server cookie functionliaty. (Handle cookies in inbound -- requests.) - cookiectl.config( { ['server_enabled'] = true } ) + cookies.config( { ['server_enabled'] = true } ) -.. tip:: If you want to change several parameters regarding the client or server configuration then do it within a single ``cookiectl.config()`` invocation. +.. tip:: If you want to change several parameters regarding the client or server configuration then do it within a single ``cookies.config()`` invocation. + +.. warning:: The module must be loaded before any other module that has direct influence on query processing and response generation. The module must be able to intercept an incoming query before the processing of the actual query starts. It must also be able to check the cookies of inbound responses and eventually discard them before they are handled by other functional units. Properties ^^^^^^^^^^ @@ -47,6 +51,6 @@ Dependencies ^^^^^^^^^^^^ * `Nettle <https://www.lysator.liu.se/~nisse/nettle/>`_ required for HMAC-SHA256 -* `dns-cookies-wip branch of libknot <https://gitlab.labs.nic.cz/labs/knot/tree/dns-cookies-wip>`_ for DNS cookies handling +* development version of `libknot (master branch) <https://gitlab.labs.nic.cz/labs/knot/tree/master>`_ for DNS cookies handling .. warning:: Libknot is dropping its processing API in latest development versions. However, this should not be a big deal as only some structures have been in usage by the resolver code.