Commit 3806b255 authored by Jan Včelák's avatar Jan Včelák 🚀

docs: simplify section about automatic signing

parent 6681f86e
......@@ -272,15 +272,15 @@ Knot DNS supports automatic DNSSEC signing for static zones. The signing
can operate in two modes:
1. :ref:`Automatic key management <dnssec-automatic-key-management>`.
In this mode, the server also maintains signing keys. New keys are generated
In this mode, the server maintains signing keys. New keys are generated
according to assigned policy and are rolled automatically in a safe manner.
No zone operator intervention is necessary.
2. :ref:`Manual key management <dnssec-manual-key-management>`.
In this mode, the server maintains zone signatures only. The signatures
are kept up-to-date and signing keys are rolled according to timing
parameters assigned to the keys. The keys must be generated by the zone
operator.
parameters assigned to the keys. The keys must be generated and timing
parameters must be assigned by the zone operator.
The DNSSEC signing process maintains some metadata which is stored in the
:abbr:`KASP (Key And Signature Policy)` database. This database is simply
......@@ -291,41 +291,40 @@ a directory in the file-system containing files in the JSON format.
management, the database must be *readable* by the server process. For
automatic key management, it must be *writeable*. If no HSM is used,
the database also contains private key material – don't set the permissions
too loose.
too week.
.. _dnssec-automatic-key-management:
Automatic key management
------------------------
For automatic key management, a signing policy has to be defined in the
first place. This policy specifies how a zone is signed (i.e. signing
algorithm, key size, signature lifetime, key lifetime, etc.). If there are
no special requirements on the policy, the default policy could be used
(see :ref:`policy section<Policy section>` for the defaults)::
For automatic key management, a signing policy has to be configured and
assigned to the zone. The policy specifies how the zone is signed (i.e. signing
algorithm, key size, key lifetime, signature lifetime, etc.). The policy can
be configured in the :ref:`policy section <Policy section>`, or a ``default``
policy with the default parameters can be used.
A minimal zone configuration may look as follows::
zone:
- domain: myzone.test
dnssec-signing: on
dnssec-policy: default
To specify a new policy using *RSA-SHA-256* algorithm for signing keys,
1024-bit long ZSK, and 2048-bit long KSK, run::
With custom signing policy, the policy section will be added::
policy:
- id: test-policy
- id: rsa
algorithm: RSASHA256
ksk-size: 2048
zsk-size: 1024
And assign the policy to the zone::
zone:
- domain: myzone.test
dnssec-signing: on
dnssec-policy: test-policy
dnssec-policy: rsa
Finally, reload the server:
After configuring the server, reload the changes:
.. code-block:: console
......@@ -351,16 +350,15 @@ For automatic DNSSEC signing with manual key management, a signing policy
with manual key management flag has to be set::
policy:
- id: manual-policy
- id: manual
manual: on
zone:
- domain: myzone.test
dnssec-signing: on
dnssec-policy: manual-policy
dnssec-policy: manual
Using :doc:`keymgr <man_keymgr>` utility generate signing keys for the zone.
To generate signing keys, use the :doc:`keymgr <man_keymgr>` utility.
Let's use the Single-Type Signing scheme with two algorithms, which is
a scheme currently not supported by the automatic key management. Run:
......@@ -369,7 +367,7 @@ a scheme currently not supported by the automatic key management. Run:
$ keymgr zone key generate myzone.test algorithm RSASHA256 size 1024
$ keymgr zone key generate myzone.test algorithm ECDSAP256SHA256 size 256
And reload the server.
And reload the server. The zone will be signed.
To perform a manual rollover of a key, the timing parameters of the key need
to be set. Let's roll the RSA key. Generate a new RSA key, but do not activate
......@@ -386,10 +384,11 @@ the new key gets activated:
$ keymgr zone key set myzone.test <old_key_id> retire +1d remove +1d
Reload the server again. The new key gets published. Do not forget to update
the DS record in the parent zone to include the reference to the new RSA key.
This must happen in one day (in this case) including a delay required to
propagate the new DS to caches.
Reload the server again. The new key will be published (i.e. the DNSKEY record
will be added into the zone). Do not forget to update the DS record in the
parent zone to include a reference to the new RSA key. This must happen in one
day (in this case) including a delay required to propagate the new DS to
caches.
Note that as the ``+1d`` time specification is computed from the current time,
the key replacement will not happen at once. First, a new key will be
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment