.. _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]``