diff options
Diffstat (limited to '')
-rw-r--r-- | src/knot/modules/cookies/cookies.rst | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/src/knot/modules/cookies/cookies.rst b/src/knot/modules/cookies/cookies.rst new file mode 100644 index 0000000..74bffe5 --- /dev/null +++ b/src/knot/modules/cookies/cookies.rst @@ -0,0 +1,110 @@ +.. _mod-cookies: + +``cookies`` — DNS Cookies +========================= + +DNS Cookies (:rfc:`7873`) is a lightweight security mechanism against +denial-of-service and amplification attacks. The server keeps a secret value +(the Server Secret), which is used to generate a cookie, which is sent to +the client in the OPT RR. The server then verifies the authenticity of the client +by the presence of a correct cookie. Both the server and the client have to +support DNS Cookies, otherwise they are not used. + +.. NOTE:: + This module introduces two statistics counters: + + - ``presence`` – The number of queries containing the COOKIE option. + - ``dropped`` – The number of dropped queries due to the slip limit. + +.. WARNING:: + For effective module operation the :ref:`RRL<mod-rrl>` module must also + be enabled and configured after :ref:`Cookies<mod-cookies>`. See + :ref:`query-modules` how to configure modules. + +Example +------- + +It is recommended to enable DNS Cookies globally, not per zone. The module may be used without any further configuration. + +:: + + template: + - id: default + global-module: mod-cookies # Enable DNS Cookies globally + +Module configuration may be supplied if necessary. + +:: + + mod-cookies: + - id: default + secret-lifetime: 30h # The Server Secret is regenerated every 30 hours + badcookie-slip: 3 # The server replies only to every third query with a wrong cookie + + template: + - id: default + global-module: mod-cookies/default # Enable DNS Cookies globally + +The value of the Server Secret may also be managed manually using the :ref:`mod-cookies_secret` option. In this case +the server does not automatically regenerate the Server Secret. + +:: + + mod-cookies: + - id: default + secret: 0xdeadbeefdeadbeefdeadbeefdeadbeef + +Module reference +---------------- + +:: + + mod-cookies: + - id: STR + secret-lifetime: TIME + badcookie-slip: INT + secret: STR | HEXSTR + +.. _mod-cookies_id: + +id +.. + +A module identifier. + +.. _mod-cookies_secret-lifetime: + +secret-lifetime +............... + +This option configures in seconds how often the Server Secret is regenerated. +The maximum allowed value is 36 days (:rfc:`7873#section-7.1`). + +*Default:* ``26h`` (26 hours) + +.. _mod-cookies_badcookie-slip: + +badcookie-slip +.............. + +This option configures how often the server responds to queries containing +an invalid cookie by sending them the correct cookie. + +- The value **1** means that the server responds to every query. +- The value **2** means that the server responds to every second query with + an invalid cookie, the rest of the queries is dropped. +- The value **N > 2** means that the server responds to every N\ :sup:`th` + query with an invalid cookie, the rest of the queries is dropped. + +*Default:* ``1`` + +.. _mod-cookies_secret: + +secret +...... + +Use this option to set the Server Secret manually. If this option is used, the +Server Secret remains the same until changed manually and the :ref:`mod-cookies_secret-lifetime` option is ignored. +The size of the Server Secret currently MUST BE 16 bytes, or 32 hexadecimal characters. + +*Default:* not set |