From 3d0386f27ca66379acf50199e1d1298386eeeeb8 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 02:55:53 +0200 Subject: Adding upstream version 3.2.1. Signed-off-by: Daniel Baumann --- modules/cookies/README.rst | 54 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 modules/cookies/README.rst (limited to 'modules/cookies/README.rst') diff --git a/modules/cookies/README.rst b/modules/cookies/README.rst new file mode 100644 index 0000000..5db476c --- /dev/null +++ b/modules/cookies/README.rst @@ -0,0 +1,54 @@ +.. _mod-cookies: + +DNS Cookies +----------- + +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 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. + -- Use a string composed of hexadecimal digits to set the secret. + cookies.config { client_secret = '0123456789ABCDEF', + client_cookie_alg = 'FNV-64' } + + -- Configure the server part of the resolver. + cookies.config { server_secret = 'FEDCBA9876543210', + server_cookie_alg = 'FNV-64' } + + -- Enable client cookie functionality. (Add cookies into outbound + -- queries.) + cookies.config { client_enabled = true } + + -- Enable server cookie functionality. (Handle cookies in inbound + -- requests.) + 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 ``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 +^^^^^^^^^^ + +.. function:: cookies.config(configuration) + + :param table configuration: part of cookie configuration to be changed, may be called without parameter + :return: JSON dictionary containing current configuration + + The function may be called without any parameter. In such case it only returns current configuration. The returned JSON also contains available algorithm choices. + +Dependencies +^^^^^^^^^^^^ + +* `Nettle `_ required for HMAC-SHA256 + -- cgit v1.2.3