1 files changed, 158 insertions, 0 deletions
diff --git a/src/knot/modules/onlinesign/onlinesign.rst b/src/knot/modules/onlinesign/onlinesign.rst
new file mode 100644
index 0000000..c1859e2
--- /dev/null
+++ b/src/knot/modules/onlinesign/onlinesign.rst
@@ -0,0 +1,158 @@
+.. _mod-onlinesign:
+
+``onlinesign`` — Online DNSSEC signing
+======================================
+
+The module provides online DNSSEC signing. Instead of pre-computing the zone
+signatures when the zone is loaded into the server or instead of loading an
+externally signed zone, the signatures are computed on-the-fly during
+answering.
+
+The main purpose of the module is to enable authenticated responses with
+zones which use other dynamic module (e.g., automatic reverse record
+synthesis) because these zones cannot be pre-signed. However, it can be also
+used as a simple signing solution for zones with low traffic and also as
+a protection against zone content enumeration (zone walking).
+
+In order to minimize the number of computed signatures per query, the module
+produces a bit different responses from the responses that would be sent if
+the zone was pre-signed. Still, the responses should be perfectly valid for
+a DNSSEC validating resolver.
+
+.. rubric:: Differences from statically signed zones:
+
+* The NSEC records are constructed as Minimally Covering NSEC Records
+  (:rfc:`7129#appendix-A`). Therefore the generated domain names cover
+  the complete domain name space in the zone's authority.
+
+* NXDOMAIN responses are promoted to NODATA responses. The module proves
+  that the query type does not exist rather than that the domain name does not
+  exist.
+
+* Domain names matching a wildcard are expanded. The module pretends and proves
+  that the domain name exists rather than proving a presence of the wildcard.
+
+.. rubric:: Records synthesized by the module:
+
+* DNSKEY record is synthesized in the zone apex and includes public key
+  material for the active signing key.
+
+* NSEC records are synthesized as needed.
+
+* RRSIG records are synthesized for authoritative content of the zone.
+
+* CDNSKEY and CDS records are generated as usual to publish valid Secure Entry Point.
+
+.. rubric:: Limitations:
+
+* Due to limited interaction between the server and the module,
+  after any change to KASP DB (including `knotc zone-ksk-submitted` command)
+  or when a scheduled DNSSEC event shall be processed (e.g. transition to next
+  DNSKEY rollover state) the server must be reloaded or queried to the zone
+  (with the DO bit set) to apply the change or to trigger the event. For optimal
+  operation, the recommended query frequency is at least ones per second for
+  each zone configured.
+
+* The NSEC records may differ for one domain name if queried for different
+  types. This is an implementation shortcoming as the dynamic modules
+  cooperate loosely. Possible synthesis of a type by other module cannot
+  be predicted. This dissimilarity should not affect response validation,
+  even with validators performing aggressive negative caching (:rfc:`8198`).
+
+* The module isn't compatible with the Offline KSK mode yet.
+
+.. rubric:: Recommendations:
+
+* Configure the module with an explicit signing policy which has the
+  :ref:`policy_rrsig-lifetime` value in the order of hours.
+
+* Note that :ref:`policy_single-type-signing` should be set explicitly to
+  avoid fallback to backward-compatible default.
+
+Example
+-------
+
+* Enable the module in the zone configuration with the default signing policy::
+
+   zone:
+     - domain: example.com
+       module: mod-onlinesign
+
+  Or with an explicit signing policy::
+
+   policy:
+     - id: rsa
+       algorithm: RSASHA256
+       ksk-size: 2048
+       rrsig-lifetime: 25h
+       rrsig-refresh: 20h
+
+   mod-onlinesign:
+     - id: explicit
+       policy: rsa
+
+   zone:
+     - domain: example.com
+       module: mod-onlinesign/explicit
+
+  Or use manual policy in an analogous manner, see
+  :ref:`Manual key management<dnssec-manual-key-management>`.
+
+* Make sure the zone is not signed and also that the automatic signing is
+  disabled. All is set, you are good to go. Reload (or start) the server:
+
+  .. code-block:: console
+
+   $ knotc reload
+
+The following example stacks the online signing with reverse record synthesis
+module::
+
+ mod-synthrecord:
+   - id: lan-forward
+     type: forward
+     prefix: ip-
+     ttl: 1200
+     network: 192.168.100.0/24
+
+ zone:
+   - domain: corp.example.net
+     module: [mod-synthrecord/lan-forward, mod-onlinesign]
+
+Module reference
+----------------
+
+::
+
+ mod-onlinesign:
+   - id: STR
+     policy: policy_id
+     nsec-bitmap: STR ...
+
+.. _mod-onlinesign_id:
+
+id
+..
+
+A module identifier.
+
+.. _mod-onlinesign_policy:
+
+policy
+......
+
+A :ref:`reference<policy_id>` to DNSSEC signing policy. A special *default*
+value can be used for the default policy setting.
+
+*Default:* an imaginary policy with all default values
+
+.. _mod-onlinesign_nsec-bitmap:
+
+nsec-bitmap
+...........
+
+A list of Resource Record types included in an NSEC bitmap generated by the module.
+This option should reflect zone contents or synthesized responses by modules,
+such as :ref:`synthrecord<mod-synthrecord>` and :ref:`GeoIP<mod-geoip>`.
+
+*Default:* ``[A, AAAA]``