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