2
0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-30 14:07:59 +00:00

Change indentation in doc/arm/dnssec.xml

This commit does not change anything significant, it just makes
the file more readable in preparation for upcoming changes related
to the `dnssec-policy` configuration option.
This commit is contained in:
Matthijs Mekking
2019-09-02 10:13:24 +02:00
parent 799e95b132
commit c67379fb92

View File

@@ -15,30 +15,36 @@
<section><info><title>Converting from insecure to secure</title></info> <section><info><title>Converting from insecure to secure</title></info>
</section> </section>
<para>Changing a zone from insecure to secure can be done in two <para>
ways: using a dynamic DNS update, or the Changing a zone from insecure to secure can be done in two
<command>auto-dnssec</command> zone option.</para> ways: using a dynamic DNS update, or the
<para>For either method, you need to configure <command>auto-dnssec</command> zone option.
<command>named</command> so that it can see the </para>
<filename>K*</filename> files which contain the public and private <para>
parts of the keys that will be used to sign the zone. These files For either method, you need to configure
will have been generated by <command>named</command> so that it can see the
<command>dnssec-keygen</command>. You can do this by placing them <filename>K*</filename> files which contain the public and private
in the key-directory, as specified in parts of the keys that will be used to sign the zone. These files
<filename>named.conf</filename>:</para> will have been generated by
<programlisting> <command>dnssec-keygen</command>. You can do this by placing them
in the key-directory, as specified in
<filename>named.conf</filename>:</para>
<programlisting>
zone example.net { zone example.net {
type master; type master;
update-policy local; update-policy local;
file "dynamic/example.net/example.net"; file "dynamic/example.net/example.net";
key-directory "dynamic/example.net"; key-directory "dynamic/example.net";
}; };
</programlisting> </programlisting>
<para>If one KSK and one ZSK DNSKEY key have been generated, this <para>
configuration will cause all records in the zone to be signed If one KSK and one ZSK DNSKEY key have been generated, this
with the ZSK, and the DNSKEY RRset to be signed with the KSK as configuration will cause all records in the zone to be signed
well. An NSEC chain will be generated as part of the initial with the ZSK, and the DNSKEY RRset to be signed with the KSK as
signing process.</para> well. An NSEC chain will be generated as part of the initial
signing process.
</para>
<section><info><title>Dynamic DNS update method</title></info> <section><info><title>Dynamic DNS update method</title></info>
</section> </section>
@@ -50,16 +56,20 @@
&gt; update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= &gt; update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
&gt; send &gt; send
</screen> </screen>
<para>While the update request will complete almost immediately, <para>
the zone will not be completely signed until While the update request will complete almost immediately,
<command>named</command> has had time to walk the zone and the zone will not be completely signed until
generate the NSEC and RRSIG records. The NSEC record at the apex <command>named</command> has had time to walk the zone and
will be added last, to signal that there is a complete NSEC generate the NSEC and RRSIG records. The NSEC record at the apex
chain.</para> will be added last, to signal that there is a complete NSEC
<para>If you wish to sign using NSEC3 instead of NSEC, you should chain.
add an NSEC3PARAM record to the initial update request. If you </para>
wish the NSEC3 chain to have the OPTOUT bit set, set it in the <para>
flags field of the NSEC3PARAM record.</para> If you wish to sign using NSEC3 instead of NSEC, you should
add an NSEC3PARAM record to the initial update request. If you
wish the NSEC3 chain to have the OPTOUT bit set, set it in the
flags field of the NSEC3PARAM record.
</para>
<screen> <screen>
% nsupdate % nsupdate
&gt; ttl 3600 &gt; ttl 3600
@@ -68,90 +78,105 @@
&gt; update add example.net NSEC3PARAM 1 1 100 1234567890 &gt; update add example.net NSEC3PARAM 1 1 100 1234567890
&gt; send &gt; send
</screen> </screen>
<para>Again, this update request will complete almost <para>
immediately; however, the record won't show up until Again, this update request will complete almost
<command>named</command> has had a chance to build/remove the immediately; however, the record won't show up until
relevant chain. A private type record will be created to record <command>named</command> has had a chance to build/remove the
the state of the operation (see below for more details), and will relevant chain. A private type record will be created to record
be removed once the operation completes.</para> the state of the operation (see below for more details), and will
<para>While the initial signing and NSEC/NSEC3 chain generation be removed once the operation completes.
is happening, other updates are possible as well.</para> </para>
<para>
While the initial signing and NSEC/NSEC3 chain generation
is happening, other updates are possible as well.
</para>
<section><info><title>Fully automatic zone signing</title></info> <section><info><title>Fully automatic zone signing</title></info>
</section> </section>
<para>To enable automatic signing, add the
<command>auto-dnssec</command> option to the zone statement in
<filename>named.conf</filename>.
<command>auto-dnssec</command> has two possible arguments:
<constant>allow</constant> or
<constant>maintain</constant>.</para>
<para>With
<command>auto-dnssec allow</command>,
<command>named</command> can search the key directory for 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
<command>rndc sign &lt;zonename&gt;</command>.</para>
<para> <para>
<!-- TODO: this is repeated in the ARM --> To enable automatic signing, add the
<command>auto-dnssec maintain</command> includes the above <command>auto-dnssec</command> option to the zone statement in
functionality, but will also automatically adjust the zone's <filename>named.conf</filename>.
DNSKEY records on schedule according to the keys' timing metadata. <command>auto-dnssec</command> has two possible arguments:
(See <xref linkend="man.dnssec-keygen"/> and <constant>allow</constant> or
<xref linkend="man.dnssec-settime"/> for more information.) <constant>maintain</constant>.
</para> </para>
<para> <para>
<command>named</command> will periodically search the key directory With <command>auto-dnssec allow</command>,
for keys matching the zone, and if the keys' metadata indicates <command>named</command> can search the key directory for keys
that any change should be made the zone, such as adding, removing, matching the zone, insert them into the zone, and use them to
or revoking a key, then that action will be carried out. By default, sign the zone. It will do so only when it receives an
the key directory is checked for changes every 60 minutes; this period <command>rndc sign &lt;zonename&gt;</command>.
can be adjusted with the <option>dnssec-loadkeys-interval</option>, up
to a maximum of 24 hours. The <command>rndc loadkeys</command> forces
<command>named</command> to check for key updates immediately.
</para> </para>
<para> <para>
If keys are present in the key directory the first time the zone <!-- TODO: this is repeated in the ARM -->
is loaded, the zone will be signed immediately, without waiting for an <command>auto-dnssec maintain</command> includes the above
<command>rndc sign</command> or <command>rndc loadkeys</command> functionality, but will also automatically adjust the zone's
command. (Those commands can still be used when there are unscheduled DNSKEY records on schedule according to the keys' timing metadata.
key changes, however.) (See <xref linkend="man.dnssec-keygen"/> and
<xref linkend="man.dnssec-settime"/> for more information.)
</para> </para>
<para> <para>
When new keys are added to a zone, the TTL is set to match that <command>named</command> will periodically search the key directory
of any existing DNSKEY RRset. If there is no existing DNSKEY RRset, for keys matching the zone, and if the keys' metadata indicates
then the TTL will be set to the TTL specified when the key was that any change should be made the zone, such as adding, removing,
created (using the <command>dnssec-keygen -L</command> option), if or revoking a key, then that action will be carried out. By default,
any, or to the SOA TTL. the key directory is checked for changes every 60 minutes; this period
can be adjusted with the <option>dnssec-loadkeys-interval</option>, up
to a maximum of 24 hours. The <command>rndc loadkeys</command> forces
<command>named</command> to check for key updates immediately.
</para> </para>
<para> <para>
If you wish the zone to be signed using NSEC3 instead of NSEC, If keys are present in the key directory the first time the zone
submit an NSEC3PARAM record via dynamic update prior to the is loaded, the zone will be signed immediately, without waiting for an
scheduled publication and activation of the keys. If you wish the <command>rndc sign</command> or <command>rndc loadkeys</command>
NSEC3 chain to have the OPTOUT bit set, set it in the flags field command. (Those commands can still be used when there are unscheduled
of the NSEC3PARAM record. The NSEC3PARAM record will not appear in key changes, however.)
the zone immediately, but it will be stored for later reference. When
the zone is signed and the NSEC3 chain is completed, the NSEC3PARAM
record will appear in the zone.
</para> </para>
<para>Using the <para>
<command>auto-dnssec</command> option requires the zone to be When new keys are added to a zone, the TTL is set to match that
configured to allow dynamic updates, by adding an of any existing DNSKEY RRset. If there is no existing DNSKEY RRset,
<command>allow-update</command> or then the TTL will be set to the TTL specified when the key was
<command>update-policy</command> statement to the zone created (using the <command>dnssec-keygen -L</command> option), if
configuration. If this has not been done, the configuration will any, or to the SOA TTL.
fail.</para> </para>
<para>
If you wish the zone to be signed using NSEC3 instead of NSEC,
submit an NSEC3PARAM record via dynamic update prior to the
scheduled publication and activation of the keys. If you wish the
NSEC3 chain to have the OPTOUT bit set, set it in the flags field
of the NSEC3PARAM record. The NSEC3PARAM record will not appear in
the zone immediately, but it will be stored for later reference. When
the zone is signed and the NSEC3 chain is completed, the NSEC3PARAM
record will appear in the zone.
</para>
<para>
Using the
<command>auto-dnssec</command> option requires the zone to be
configured to allow dynamic updates, by adding an
<command>allow-update</command> or
<command>update-policy</command> statement to the zone
configuration. If this has not been done, the configuration will
fail.
</para>
<section><info><title>Private-type records</title></info> <section><info><title>Private-type records</title></info>
</section> </section>
<para>The state of the signing process is signaled by <para>
private-type records (with a default type value of 65534). When The state of the signing process is signaled by
signing is complete, these records will have a nonzero value for private-type records (with a default type value of 65534). When
the final octet (for those records which have a nonzero initial signing is complete, these records will have a nonzero value for
octet).</para> the final octet (for those records which have a nonzero initial
<para>The private type record format: If the first octet is octet).
non-zero then the record indicates that the zone needs to be </para>
signed with the key matching the record, or that all signatures <para>
that match the record should be removed.</para> The private type record format: If the first octet is
non-zero then the record indicates that the zone needs to be
signed with the key matching the record, or that all signatures
that match the record should be removed.
</para>
<para> <para>
<literallayout> <literallayout>
<!-- TODO: how to format this? --> <!-- TODO: how to format this? -->
@@ -161,14 +186,18 @@
complete flag (octet 5) complete flag (octet 5)
</literallayout> </literallayout>
</para> </para>
<para>Only records flagged as "complete" can be removed via <para>
dynamic update. Attempts to remove other private type records Only records flagged as "complete" can be removed via
will be silently ignored.</para> dynamic update. Attempts to remove other private type records
<para>If the first octet is zero (this is a reserved algorithm will be silently ignored.
number that should never appear in a DNSKEY record) then the </para>
record indicates changes to the NSEC3 chains are in progress. The <para>
rest of the record contains an NSEC3PARAM record. The flag field If the first octet is zero (this is a reserved algorithm
tells what operation to perform based on the flag bits.</para> number that should never appear in a DNSKEY record) then the
record indicates changes to the NSEC3 chains are in progress. The
rest of the record contains an NSEC3PARAM record. The flag field
tells what operation to perform based on the flag bits.
</para>
<para> <para>
<literallayout> <literallayout>
<!-- TODO: how to format this? --> <!-- TODO: how to format this? -->
@@ -181,106 +210,136 @@
<section><info><title>DNSKEY rollovers</title></info> <section><info><title>DNSKEY rollovers</title></info>
</section> </section>
<para>As with insecure-to-secure conversions, rolling DNSSEC <para>
keys can be done in two ways: using a dynamic DNS update, or the As with insecure-to-secure conversions, rolling DNSSEC
<command>auto-dnssec</command> zone option.</para> keys can be done in two ways: using a dynamic DNS update, or the
<command>auto-dnssec</command> zone option.
</para>
<section><info><title>Dynamic DNS update method</title></info> <section><info><title>Dynamic DNS update method</title></info>
</section> </section>
<para> To perform key rollovers via dynamic update, you need to add <para>
the <filename>K*</filename> files for the new keys so that To perform key rollovers via dynamic update, you need to add
<command>named</command> can find them. You can then add the new the <filename>K*</filename> files for the new keys so that
DNSKEY RRs via dynamic update. <command>named</command> can find them. You can then add the new
<command>named</command> will then cause the zone to be signed DNSKEY RRs via dynamic update.
with the new keys. When the signing is complete the private type <command>named</command> will then cause the zone to be signed
records will be updated so that the last octet is non with the new keys. When the signing is complete the private type
zero.</para> records will be updated so that the last octet is non
<para>If this is for a KSK you need to inform the parent and any zero.
trust anchor repositories of the new KSK.</para> </para>
<para>You should then wait for the maximum TTL in the zone before <para>
removing the old DNSKEY. If it is a KSK that is being updated, If this is for a KSK you need to inform the parent and any
you also need to wait for the DS RRset in the parent to be trust anchor repositories of the new KSK.
updated and its TTL to expire. This ensures that all clients will </para>
be able to verify at least one signature when you remove the old <para>
DNSKEY.</para> You should then wait for the maximum TTL in the zone before
<para>The old DNSKEY can be removed via UPDATE. Take care to removing the old DNSKEY. If it is a KSK that is being updated,
specify the correct key. you also need to wait for the DS RRset in the parent to be
<command>named</command> will clean out any signatures generated updated and its TTL to expire. This ensures that all clients will
by the old key after the update completes.</para> be able to verify at least one signature when you remove the old
DNSKEY.
</para>
<para>
The old DNSKEY can be removed via UPDATE. Take care to
specify the correct key.
<command>named</command> will clean out any signatures generated
by the old key after the update completes.
</para>
<section><info><title>Automatic key rollovers</title></info> <section><info><title>Automatic key rollovers</title></info>
</section> </section>
<para>When a new key reaches its activation date (as set by <para>
<command>dnssec-keygen</command> or <command>dnssec-settime</command>), When a new key reaches its activation date (as set by
if the <command>auto-dnssec</command> zone option is set to <command>dnssec-keygen</command> or <command>dnssec-settime</command>),
<constant>maintain</constant>, <command>named</command> will if the <command>auto-dnssec</command> zone option is set to
automatically carry out the key rollover. If the key's algorithm <constant>maintain</constant>, <command>named</command> will
has not previously been used to sign the zone, then the zone will automatically carry out the key rollover. If the key's algorithm
be fully signed as quickly as possible. However, if the new key has not previously been used to sign the zone, then the zone will
is replacing an existing key of the same algorithm, then the be fully signed as quickly as possible. However, if the new key
zone will be re-signed incrementally, with signatures from the is replacing an existing key of the same algorithm, then the
old key being replaced with signatures from the new key as their zone will be re-signed incrementally, with signatures from the
signature validity periods expire. By default, this rollover old key being replaced with signatures from the new key as their
completes in 30 days, after which it will be safe to remove the signature validity periods expire. By default, this rollover
old key from the DNSKEY RRset.</para> completes in 30 days, after which it will be safe to remove the
old key from the DNSKEY RRset.
</para>
<section><info><title>NSEC3PARAM rollovers via UPDATE</title></info> <section><info><title>NSEC3PARAM rollovers via UPDATE</title></info>
</section> </section>
<para>Add the new NSEC3PARAM record via dynamic update. When the <para>
new NSEC3 chain has been generated, the NSEC3PARAM flag field Add the new NSEC3PARAM record via dynamic update. When the
will be zero. At this point you can remove the old NSEC3PARAM new NSEC3 chain has been generated, the NSEC3PARAM flag field
record. The old chain will be removed after the update request will be zero. At this point you can remove the old NSEC3PARAM
completes.</para> record. The old chain will be removed after the update request
completes.
</para>
<section><info><title>Converting from NSEC to NSEC3</title></info> <section><info><title>Converting from NSEC to NSEC3</title></info>
</section> </section>
<para>To do this, you just need to add an NSEC3PARAM record. When <para>
the conversion is complete, the NSEC chain will have been removed To do this, you just need to add an NSEC3PARAM record. When
and the NSEC3PARAM record will have a zero flag field. The NSEC3 the conversion is complete, the NSEC chain will have been removed
chain will be generated before the NSEC chain is and the NSEC3PARAM record will have a zero flag field. The NSEC3
destroyed.</para> chain will be generated before the NSEC chain is
destroyed.
</para>
<section><info><title>Converting from NSEC3 to NSEC</title></info> <section><info><title>Converting from NSEC3 to NSEC</title></info>
</section> </section>
<para>To do this, use <command>nsupdate</command> to <para>
remove all NSEC3PARAM records with a zero flag To do this, use <command>nsupdate</command> to
field. The NSEC chain will be generated before the NSEC3 chain is remove all NSEC3PARAM records with a zero flag
removed.</para> field. The NSEC chain will be generated before the NSEC3 chain is
removed.
</para>
<section><info><title>Converting from secure to insecure</title></info> <section><info><title>Converting from secure to insecure</title></info>
</section> </section>
<para>To convert a signed zone to unsigned using dynamic DNS, <para>
delete all the DNSKEY records from the zone apex using To convert a signed zone to unsigned using dynamic DNS,
<command>nsupdate</command>. All signatures, NSEC or NSEC3 chains, delete all the DNSKEY records from the zone apex using
and associated NSEC3PARAM records will be removed automatically. <command>nsupdate</command>. All signatures, NSEC or NSEC3 chains,
This will take place after the update request completes.</para> and associated NSEC3PARAM records will be removed automatically.
<para> This requires the This will take place after the update request completes.</para>
<command>dnssec-secure-to-insecure</command> option to be set to <para> This requires the
<userinput>yes</userinput> in <command>dnssec-secure-to-insecure</command> option to be set to
<filename>named.conf</filename>.</para> <userinput>yes</userinput> in
<para>In addition, if the <command>auto-dnssec maintain</command> <filename>named.conf</filename>.</para>
zone statement is used, it should be removed or changed to <para>In addition, if the <command>auto-dnssec maintain</command>
<command>allow</command> instead (or it will re-sign). zone statement is used, it should be removed or changed to
<command>allow</command> instead (or it will re-sign).
</para> </para>
<section><info><title>Periodic re-signing</title></info> <section><info><title>Periodic re-signing</title></info>
</section> </section>
<para>In any secure zone which supports dynamic updates, <command>named</command> <para>
will periodically re-sign RRsets which have not been re-signed as In any secure zone which supports dynamic updates, <command>named</command>
a result of some update action. The signature lifetimes will be will periodically re-sign RRsets which have not been re-signed as
adjusted so as to spread the re-sign load over time rather than a result of some update action. The signature lifetimes will be
all at once.</para> adjusted so as to spread the re-sign load over time rather than
all at once.
</para>
<section><info><title>NSEC3 and OPTOUT</title></info> <section><info><title>NSEC3 and OPTOUT</title></info>
</section> </section>
<para> <para>
<command>named</command> only supports creating new NSEC3 chains <command>named</command> only supports creating new NSEC3 chains
where all the NSEC3 records in the zone have the same OPTOUT where all the NSEC3 records in the zone have the same OPTOUT
state. state.
<command>named</command> supports UPDATES to zones where the NSEC3 <command>named</command> supports UPDATES to zones where the NSEC3
records in the chain have mixed OPTOUT state. records in the chain have mixed OPTOUT state.
<command>named</command> does not support changing the OPTOUT <command>named</command> does not support changing the OPTOUT
state of an individual NSEC3 record, the entire chain needs to be state of an individual NSEC3 record, the entire chain needs to be
changed if the OPTOUT state of an individual NSEC3 needs to be changed if the OPTOUT state of an individual NSEC3 needs to be
changed.</para> changed.
</para>
</section> </section>