mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-29 21:47:59 +00:00
Code Issues Releases Wiki Activity

Merge branch '1881-text-edits-in-dnssec-rst' into 'master'

Browse Source 
Resolve "Text edits in dnssec.rst"

Closes #1881

See merge request isc-projects/bind9!3589
This commit is contained in:
Ondřej Surý 2020-05-29 13:15:24 +00:00
commit 1c7f63b300
1 changed files with 94 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
doc/arm/dnssec.rst
View File

@ -23,16 +23,16 @@
DNSSEC, Dynamic Zones, and Automatic Signing DNSSEC, Dynamic Zones, and Automatic Signing
-------------------------------------------- --------------------------------------------
Converting from insecure to secure Converting From Insecure to Secure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Changing a zone from insecure to secure can be done in two ways: using a Changing a zone from insecure to secure can be done in two ways: using a
dynamic DNS update, or the ``auto-dnssec`` zone option. dynamic DNS update, or via the ``auto-dnssec`` zone option.
For either method, you need to configure ``named`` so that it can see For either method, ``named`` must be configured so that it can see
the ``K*`` files which contain the public and private parts of the keys the ``K*`` files which contain the public and private parts of the keys
that will be used to sign the zone. These files will have been generated that are used to sign the zone. These files are generated
by ``dnssec-keygen``. You can do this by placing them in the by ``dnssec-keygen``, and they should be placed in the
key-directory, as specified in ``named.conf``: key-directory, as specified in ``named.conf``:
:: ::
@ -45,11 +45,11 @@ key-directory, as specified in ``named.conf``:
}; };
If one KSK and one ZSK DNSKEY key have been generated, this If one KSK and one ZSK DNSKEY key have been generated, this
configuration will cause all records in the zone to be signed with the configuration causes all records in the zone to be signed with the
ZSK, and the DNSKEY RRset to be signed with the KSK as well. An NSEC ZSK, and the DNSKEY RRset to be signed with the KSK. An NSEC
chain will be generated as part of the initial signing process. chain is generated as part of the initial signing process.
Dynamic DNS update method Dynamic DNS Update Method
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
To insert the keys via dynamic update: To insert the keys via dynamic update:
@ -62,14 +62,14 @@ To insert the keys via dynamic update:
> update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
> send > send
While the update request will complete almost immediately, the zone will While the update request completes almost immediately, the zone is
not be completely signed until ``named`` has had time to walk the zone not completely signed until ``named`` has had time to walk the zone
and generate the NSEC and RRSIG records. The NSEC record at the apex and generate the NSEC and RRSIG records. The NSEC record at the apex
will be added last, to signal that there is a complete NSEC chain. is added last, to signal that there is a complete NSEC chain.
If you wish to sign using NSEC3 instead of NSEC, you should add an To sign using NSEC3 instead of NSEC, add an
NSEC3PARAM record to the initial update request. If you wish the NSEC3 NSEC3PARAM record to the initial update request. The OPTOUT bit in the NSEC3
chain to have the OPTOUT bit set, set it in the flags field of the chain can be set in the flags field of the
NSEC3PARAM record. NSEC3PARAM record.
:: ::
@ -81,16 +81,16 @@ NSEC3PARAM record.
> update add example.net NSEC3PARAM 1 1 100 1234567890 > update add example.net NSEC3PARAM 1 1 100 1234567890
> send > send
Again, this update request will complete almost immediately; however, Again, this update request completes almost immediately; however,
the record won't show up until ``named`` has had a chance to the record does not show up until ``named`` has had a chance to
build/remove the relevant chain. A private type record will be created build/remove the relevant chain. A private type record is created
to record the state of the operation (see below for more details), and to record the state of the operation (see below for more details), and
will be removed once the operation completes. is removed once the operation completes.
While the initial signing and NSEC/NSEC3 chain generation is happening, While the initial signing and NSEC/NSEC3 chain generation is happening,
other updates are possible as well. other updates are possible as well.
Fully automatic zone signing Fully Automatic Zone Signing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable automatic signing, add the ``auto-dnssec`` option to the zone To enable automatic signing, add the ``auto-dnssec`` option to the zone
@ -99,55 +99,54 @@ statement in ``named.conf``. ``auto-dnssec`` has two possible arguments:
With ``auto-dnssec allow``, ``named`` can search the key directory for With ``auto-dnssec allow``, ``named`` can search the key directory for
keys matching the zone, insert them into the zone, and use them to sign keys matching the zone, insert them into the zone, and use them to sign
the zone. It will do so only when it receives an the zone. It does so only when it receives an
``rndc sign <zonename>``. ``rndc sign <zonename>``.
``auto-dnssec maintain`` includes the above functionality, but will also ``auto-dnssec maintain`` includes the above functionality, but also
automatically adjust the zone's DNSKEY records on schedule according to automatically adjusts the zone's DNSKEY records on a schedule according to
the keys' timing metadata. (See :ref:`man_dnssec-keygen` and the keys' timing metadata. (See :ref:`man_dnssec-keygen` and
:ref:`man_dnssec-settime` for more information.) :ref:`man_dnssec-settime` for more information.)
``named`` will periodically search the key directory for keys matching ``named`` periodically searches the key directory for keys matching
the zone, and if the keys' metadata indicates that any change should be the zone; if the keys' metadata indicates that any change should be
made the zone, such as adding, removing, or revoking a key, then that made to the zone, such as adding, removing, or revoking a key, then that
action will be carried out. By default, the key directory is checked for action is carried out. By default, the key directory is checked for
changes every 60 minutes; this period can be adjusted with the changes every 60 minutes; this period can be adjusted with the
``dnssec-loadkeys-interval``, up to a maximum of 24 hours. The ``dnssec-loadkeys-interval``, up to a maximum of 24 hours. The
``rndc loadkeys`` forces ``named`` to check for key updates immediately. ``rndc loadkeys`` command forces ``named`` to check for key updates immediately.
If keys are present in the key directory the first time the zone is If keys are present in the key directory the first time the zone is
loaded, the zone will be signed immediately, without waiting for an loaded, the zone is signed immediately, without waiting for an
``rndc sign`` or ``rndc loadkeys`` command. (Those commands can still be ``rndc sign`` or ``rndc loadkeys`` command. Those commands can still be
used when there are unscheduled key changes, however.) used when there are unscheduled key changes.
When new keys are added to a zone, the TTL is set to match that of any When new keys are added to a zone, the TTL is set to match that of any
existing DNSKEY RRset. If there is no existing DNSKEY RRset, then the existing DNSKEY RRset. If there is no existing DNSKEY RRset, the
TTL will be set to the TTL specified when the key was created (using the TTL is set to the TTL specified when the key was created (using the
``dnssec-keygen -L`` option), if any, or to the SOA TTL. ``dnssec-keygen -L`` option), if any, or to the SOA TTL.
If you wish the zone to be signed using NSEC3 instead of NSEC, submit an To sign the zone using NSEC3 instead of NSEC, submit an
NSEC3PARAM record via dynamic update prior to the scheduled publication NSEC3PARAM record via dynamic update prior to the scheduled publication
and activation of the keys. If you wish the NSEC3 chain to have the and activation of the keys. The OPTOUT bit for the NSEC3 chain can be set
OPTOUT bit set, set it in the flags field of the NSEC3PARAM record. The in the flags field of the NSEC3PARAM record. The
NSEC3PARAM record will not appear in the zone immediately, but it will NSEC3PARAM record does not appear in the zone immediately, but it is
be stored for later reference. When the zone is signed and the NSEC3 stored for later reference. When the zone is signed and the NSEC3
chain is completed, the NSEC3PARAM record will appear in the zone. chain is completed, the NSEC3PARAM record appears in the zone.
Using the ``auto-dnssec`` option requires the zone to be configured to Using the ``auto-dnssec`` option requires the zone to be configured to
allow dynamic updates, by adding an ``allow-update`` or allow dynamic updates, by adding an ``allow-update`` or
``update-policy`` statement to the zone configuration. If this has not ``update-policy`` statement to the zone configuration. If this has not
been done, the configuration will fail. been done, the configuration fails.
Private-type records Private-type Records
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
The state of the signing process is signaled by private-type records The state of the signing process is signaled by private-type records
(with a default type value of 65534). When signing is complete, these (with a default type value of 65534). When signing is complete, those
records will have a nonzero value for the final octet (for those records records with a nonzero initial octet have a nonzero value for the final octet.
which have a nonzero initial octet).
The private type record format: If the first octet is non-zero then the If the first octet of a private-type record is non-zero, the
record indicates that the zone needs to be signed with the key matching record indicates either that the zone needs to be signed with the key matching
the record, or that all signatures that match the record should be the record, or that all signatures that match the record should be
removed. removed.
@ -160,12 +159,12 @@ removed.
complete flag (octet 5) complete flag (octet 5)
Only records flagged as "complete" can be removed via dynamic update. Only records flagged as "complete" can be removed via dynamic update.
Attempts to remove other private type records will be silently ignored. Attempts to remove other private type records are silently ignored.
If the first octet is zero (this is a reserved algorithm number that If the first octet is zero (this is a reserved algorithm number that
should never appear in a DNSKEY record) then the record indicates should never appear in a DNSKEY record), the record indicates
changes to the NSEC3 chains are in progress. The rest of the record changes to the NSEC3 chains are in progress. The rest of the record
contains an NSEC3PARAM record. The flag field tells what operation to contains an NSEC3PARAM record, while the flag field tells what operation to
perform based on the flag bits. perform based on the flag bits.
0x01 OPTOUT 0x01 OPTOUT
@ -176,92 +175,92 @@ perform based on the flag bits.
0x20 NONSEC 0x20 NONSEC
DNSKEY rollovers DNSKEY Rollovers
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
As with insecure-to-secure conversions, rolling DNSSEC keys can be done As with insecure-to-secure conversions, DNSSEC keyrolls can be done
in two ways: using a dynamic DNS update, or the ``auto-dnssec`` zone in two ways: using a dynamic DNS update, or via the ``auto-dnssec`` zone
option. option.
Dynamic DNS update method Dynamic DNS Update Method
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
To perform key rollovers via dynamic update, you need to add the ``K*`` To perform key rollovers via dynamic update, the ``K*``
files for the new keys so that ``named`` can find them. You can then add files for the new keys must be added so that ``named`` can find them.
the new DNSKEY RRs via dynamic update. ``named`` will then cause the The new DNSKEY RRs can then be added via dynamic update. ``named`` then causes the
zone to be signed with the new keys. When the signing is complete the zone to be signed with the new keys; when the signing is complete, the
private type records will be updated so that the last octet is non zero. private-type records are updated so that the last octet is non-zero.
If this is for a KSK you need to inform the parent and any trust anchor If this is for a KSK, the parent and any trust anchor
repositories of the new KSK. repositories of the new KSK must be informed.
You should then wait for the maximum TTL in the zone before removing the The maximum TTL in the zone must expire before removing the
old DNSKEY. If it is a KSK that is being updated, you also need to wait old DNSKEY. If it is a KSK that is being updated,
for the DS RRset in the parent to be updated and its TTL to expire. This the DS RRset in the parent must also be updated and its TTL allowed to expire. This
ensures that all clients will be able to verify at least one signature ensures that all clients are able to verify at least one signature
when you remove the old DNSKEY. when the old DNSKEY is removed.
The old DNSKEY can be removed via UPDATE. Take care to specify the The old DNSKEY can be removed via UPDATE, taking care to specify the
correct key. ``named`` will clean out any signatures generated by the correct key. ``named`` cleans out any signatures generated by the
old key after the update completes. old key after the update completes.
Automatic key rollovers Automatic Key Rollovers
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
When a new key reaches its activation date (as set by ``dnssec-keygen`` When a new key reaches its activation date (as set by ``dnssec-keygen``
or ``dnssec-settime``), if the ``auto-dnssec`` zone option is set to or ``dnssec-settime``), if the ``auto-dnssec`` zone option is set to
``maintain``, ``named`` will automatically carry out the key rollover. ``maintain``, ``named`` automatically carries out the key rollover.
If the key's algorithm has not previously been used to sign the zone, If the key's algorithm has not previously been used to sign the zone,
then the zone will be fully signed as quickly as possible. However, if then the zone is fully signed as quickly as possible. However, if
the new key is replacing an existing key of the same algorithm, then the the new key replaces an existing key of the same algorithm, the
zone will be re-signed incrementally, with signatures from the old key zone is re-signed incrementally, with signatures from the old key
being replaced with signatures from the new key as their signature replaced with signatures from the new key as their signature
validity periods expire. By default, this rollover completes in 30 days, validity periods expire. By default, this rollover completes in 30 days,
after which it will be safe to remove the old key from the DNSKEY RRset. after which it is safe to remove the old key from the DNSKEY RRset.
NSEC3PARAM rollovers via UPDATE NSEC3PARAM Rollovers via UPDATE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Add the new NSEC3PARAM record via dynamic update. When the new NSEC3 The new NSEC3PARAM record can be added via dynamic update. When the new NSEC3
chain has been generated, the NSEC3PARAM flag field will be zero. At chain has been generated, the NSEC3PARAM flag field is set to zero. At
this point you can remove the old NSEC3PARAM record. The old chain will that point, the old NSEC3PARAM record can be removed. The old chain is
be removed after the update request completes. removed after the update request completes.
Converting from NSEC to NSEC3 Converting From NSEC to NSEC3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To do this, you just need to add an NSEC3PARAM record. When the To do this, an NSEC3PARAM record must be added. When the
conversion is complete, the NSEC chain will have been removed and the conversion is complete, the NSEC chain is removed and the
NSEC3PARAM record will have a zero flag field. The NSEC3 chain will be NSEC3PARAM record has a zero flag field. The NSEC3 chain is
generated before the NSEC chain is destroyed. generated before the NSEC chain is destroyed.
Converting from NSEC3 to NSEC Converting From NSEC3 to NSEC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To do this, use ``nsupdate`` to remove all NSEC3PARAM records with a To do this, use ``nsupdate`` to remove all NSEC3PARAM records with a
zero flag field. The NSEC chain will be generated before the NSEC3 chain zero flag field. The NSEC chain is generated before the NSEC3 chain
is removed. is removed.
Converting from secure to insecure Converting From Secure to Insecure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To convert a signed zone to unsigned using dynamic DNS, delete all the To convert a signed zone to unsigned using dynamic DNS, delete all the
DNSKEY records from the zone apex using ``nsupdate``. All signatures, DNSKEY records from the zone apex using ``nsupdate``. All signatures,
NSEC or NSEC3 chains, and associated NSEC3PARAM records will be removed NSEC or NSEC3 chains, and associated NSEC3PARAM records are removed
automatically. This will take place after the update request completes. automatically. This takes place after the update request completes.
This requires the ``dnssec-secure-to-insecure`` option to be set to This requires the ``dnssec-secure-to-insecure`` option to be set to
``yes`` in ``named.conf``. ``yes`` in ``named.conf``.
In addition, if the ``auto-dnssec maintain`` zone statement is used, it In addition, if the ``auto-dnssec maintain`` zone statement is used, it
should be removed or changed to ``allow`` instead (or it will re-sign). should be removed or changed to ``allow`` instead; otherwise it will re-sign.
Periodic re-signing Periodic Re-signing
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
In any secure zone which supports dynamic updates, ``named`` will In any secure zone which supports dynamic updates, ``named``
periodically re-sign RRsets which have not been re-signed as a result of periodically re-signs RRsets which have not been re-signed as a result of
some update action. The signature lifetimes will be adjusted so as to some update action. The signature lifetimes are adjusted to
spread the re-sign load over time rather than all at once. spread the re-sign load over time rather than all at once.
NSEC3 and OPTOUT NSEC3 and OPTOUT
@ -271,5 +270,5 @@ NSEC3 and OPTOUT
records in the zone have the same OPTOUT state. ``named`` supports records in the zone have the same OPTOUT state. ``named`` supports
UPDATES to zones where the NSEC3 records in the chain have mixed OPTOUT UPDATES to zones where the NSEC3 records in the chain have mixed OPTOUT
state. ``named`` does not support changing the OPTOUT state of an state. ``named`` does not support changing the OPTOUT state of an
individual NSEC3 record, the entire chain needs to be changed if the individual NSEC3 record; if the
OPTOUT state of an individual NSEC3 needs to be changed. OPTOUT state of an individual NSEC3 needs to be changed, the entire chain must be changed.