<?xml version="1.0" encoding="utf-8"?>

<sect1 id="dnssec.dynamic.zones">

<title>DNSSEC, Dynamic Zones, and Automatic Signing</title>

<para>As of BIND 9.7.0 it is possible to change a dynamic zone

from insecure to signed and back again. A secure zone can use

either NSEC or NSEC3 chains.</para>

<sect2>

<title>Converting from insecure to secure</title>

</sect2>

<para>Changing a zone from insecure to secure can be done in two

ways: using a dynamic DNS update, or the

<command>auto-dnssec</command> zone option.</para>

<para>For either method, you need to configure

<command>named</command> so that it can see the

<filename>K*</filename> 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 by

<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 {

type master;

update-policy local;

file "dynamic/example.net/example.net";

key-directory "dynamic/example.net";

};

</programlisting>

<para>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 ZSK, and the DNSKEY RRset to be signed with the KSK as

well. An NSEC chain will be generated as part of the initial

signing process.</para>

<sect2>

<title>Dynamic DNS update method</title>

</sect2>

<para>To insert the keys via dynamic update:</para>

<screen>

% nsupdate

&gt; ttl 3600

&gt; update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=

&gt; update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=

&gt; send

</screen>

<para>While the update request will complete almost immediately,

the zone will not be completely signed until

<command>named</command> has had time to walk the zone 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.</para>

<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>

% nsupdate

&gt; ttl 3600

&gt; update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=

&gt; update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=

&gt; update add example.net NSEC3PARAM 1 1 100 1234567890

&gt; send

</screen>

<para>Again, this update request will complete almost

immediately; however, the record won't show up until

<command>named</command> has had a chance to build/remove the

relevant chain. A private type record will be created to record

the state of the operation (see below for more details), and will

be removed once the operation completes.</para>

<para>While the initial signing and NSEC/NSEC3 chain generation

is happening, other updates are possible as well.</para>

<sect2>

<title>Fully automatic zone signing</title>

</sect2>

<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> command.</para>

<para>

<!-- TODO: this is repeated in the ARM -->

<command>auto-dnssec maintain</command> includes the above

functionality, but will also automatically adjust the zone's

DNSKEY records on schedule according to the keys' timing metadata.

(See <xref linkend="man.dnssec-keygen"/> and

<xref linkend="man.dnssec-settime"/> for more information.)

If keys are present in the key directory the first time the zone

is loaded, it will be signed immediately, without waiting for an

<command>rndc sign</command> command. (This command can still be

used for unscheduled key changes, however.)</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>

<sect2>

<title>Private-type records</title>

</sect2>

<para>The state of the signing process is signaled by

private-type records (with a default type value of 65534). When

signing is complete, these records will have a nonzero value for

the final octet (for those records which have a nonzero initial

octet).</para>

<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>

<literallayout>

algorithm (octet 1)

key id in network order (octet 2 and 3)

removal flag (octet 4)

complete flag (octet 5)

</literallayout>

</para>

<para>Only records flagged as "complete" can be removed via

dynamic update. Attempts to remove other private type records

will be silently ignored.</para>

<para>If the first octet is zero (this is a reserved algorithm

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>

<literallayout>

0x01 OPTOUT

0x80 CREATE

0x40 REMOVE

0x20 NONSEC

</literallayout>

</para>

<sect2>

<title>DNSKEY rollovers via UPDATE</title>

</sect2>

<para>It is possible to perform key rollovers via dynamic update.

You need to add the

<filename>K*</filename> files for the new keys so that

<command>named</command> can find them. You can then add the new

DNSKEY RRs via dynamic update.

<command>named</command> will then cause 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.</para>

<para>If this is for a KSK you need to inform the parent and any

trust anchor repositories of the new KSK.</para>

<para>You should then wait for the maximum TTL in the zone before

removing the old DNSKEY. If it is a KSK that is being updated,

you also need to wait for the DS RRset in the parent to be

updated and its TTL to expire. This ensures that all clients will

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>

<sect2>

<title>NSEC3PARAM rollovers via UPDATE</title>

</sect2>

<para>Add the new NSEC3PARAM record via dynamic update. When the

new NSEC3 chain has been generated, the NSEC3PARAM flag field

will be zero. At this point you can remove the old NSEC3PARAM

record. The old chain will be removed after the update request

completes.</para>

<sect2>

<title>Converting from NSEC to NSEC3</title>

</sect2>

<para>To do this, you just need to add an NSEC3PARAM record. When

the conversion is complete, the NSEC chain will have been removed

and the NSEC3PARAM record will have a zero flag field. The NSEC3

chain will be generated before the NSEC chain is

destroyed.</para>

<sect2>

<title>Converting from NSEC3 to NSEC</title>

</sect2>

<para>To do this, use <command>nsupdate</command> to

remove all NSEC3PARAM records with a zero flag

field. The NSEC chain will be generated before the NSEC3 chain is

removed.</para>

<sect2>

<title>Converting from secure to insecure</title>

</sect2>

<para>To convert a signed zone to unsigned using dynamic DNS,

delete all the DNSKEY records from the zone apex using

<command>nsupdate</command>. All signatures, NSEC or NSEC3 chains,

and associated NSEC3PARAM records will be removed automatically.

This will take place after the update request completes.</para>

<para> This requires the

<command>dnssec-secure-to-insecure</command> option to be set to

<userinput>yes</userinput> in

<filename>named.conf</filename>.</para>

<para>In addition, if the <command>auto-dnssec maintain</command>

zone statement is used, it should be removed or changed to

<command>allow</command> instead (or it will re-sign).

</para>

<sect2>

<title>Periodic re-signing</title>

</sect2>

<para>In any secure zone which supports dynamic updates, named

will periodically re-sign RRsets which have not been re-signed as

a result of some update action. The signature lifetimes will be

adjusted so as to spread the re-sign load over time rather than

all at once.</para>

<sect2>

<title>NSEC3 and OPTOUT</title>

</sect2>

<para>

<command>named</command> only supports creating new NSEC3 chains

where all the NSEC3 records in the zone have the same OPTOUT

state.

<command>named</command> supports UPDATES to zones where the NSEC3

records in the chain have mixed OPTOUT state.

<command>named</command> does not support changing the OPTOUT

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.</para>

</sect1>