bind9/doc/arm/dnssec.xml

<!--
 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
 -
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, you can obtain one at https://mozilla.org/MPL/2.0/.
 -
 - See the COPYRIGHT file distributed with this work for additional
 - information regarding copyright ownership.
-->

<!-- Converted by db4-upgrade version 1.0 -->
<section xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="dnssec.dynamic.zones"><info><title>DNSSEC, Dynamic Zones, and Automatic Signing</title></info>

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

  </section>
  <para>A zone ca be changed from insecure to secure in two
  ways: using a dynamic DNS update, or via the
  <command>auto-dnssec</command> zone option.</para>
  <para>For either method,
  <command>named</command> must be configured so that it can see the
  <filename>K*</filename> files which contain the public and private
  parts of the keys that are used to sign the zone. These files
  are generated by
  <command>dnssec-keygen</command>, and they should be placed
  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 causes all records in the zone to be signed
  with the ZSK, and the DNSKEY RRset to be signed with the KSK.
  An NSEC chain is generated as part of the initial
  signing process.</para>
  <section><info><title>Dynamic DNS Update Method</title></info>

  </section>
  <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 completes almost immediately,
  the zone is not 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
  is added last, to signal that there is a complete NSEC
  chain.</para>
  <para>To sign using NSEC3 instead of NSEC,
  add an NSEC3PARAM record to the initial update request.
  The OPTOUT bit in the NSEC3 chain can be set 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 completes almost
  immediately; however, the record does not show up until
  <command>named</command> has had a chance to build/remove the
  relevant chain. A private type record is created to record
  the state of the operation (see below for more details), and is
  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>
  <section><info><title>Fully Automatic Zone Signing</title></info>

  </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 does so only when it receives an
  <command>rndc sign &lt;zonename&gt;</command>.</para>
  <para>
  <!-- TODO: this is repeated in the ARM -->
  <command>auto-dnssec maintain</command> includes the above
  functionality, but also automatically adjusts the zone's
  DNSKEY records on a schedule according to the keys' timing metadata.
  (See <xref linkend="man.dnssec-keygen"/> and
  <xref linkend="man.dnssec-settime"/> for more information.)
  </para>
  <para>
  <command>named</command> periodically searches the key directory
  for keys matching the zone; if the keys' metadata indicates
  that any change should be made to the zone - such as adding, removing,
  or revoking a key - then that action is carried out.  By default,
  the key directory is checked for changes every 60 minutes; this period
  can be adjusted with <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>
  If keys are present in the key directory the first time the zone
  is loaded, the zone is signed immediately, without waiting for an
  <command>rndc sign</command> or <command>rndc loadkeys</command>
  command. Those commands can still be used when there are unscheduled
  key changes.
  </para>
  <para>
  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,
  the TTL is set to the TTL specified when the key was
  created (using the <command>dnssec-keygen -L</command> option), if
  any, or to the SOA TTL.
  </para>
  <para>
  To sign the zone using NSEC3 instead of NSEC,
  submit an NSEC3PARAM record via dynamic update prior to the
  scheduled publication and activation of the keys.
  The OPTOUT bit for the NSEC3 chain can be set in the flags field
  of the NSEC3PARAM record.  The NSEC3PARAM record does not appear in
  the zone immediately, but it is stored for later reference.  When
  the zone is signed and the NSEC3 chain is completed, the NSEC3PARAM
  record appears 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
  fails.</para>
  <section><info><title>Private Type Records</title></info>

  </section>
  <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 with a non-zero initial octet
  have a non-zero value for the final octet.</para>
  <para>If the first octet of a private type record is
  non-zero, the 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 removed. Here are the meanings
  of the different values of the first octet:</para>
  <para>
    <literallayout>
<!-- TODO: how to format this? -->
  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
  are silently ignored.</para>
  <para>If the first octet is zero (this is a reserved algorithm
  number that should never appear in a DNSKEY record), the
  record indicates that changes to the NSEC3 chains are in progress. The
  rest of the record contains an NSEC3PARAM record, while the flag field
  tells what operation to perform based on the flag bits:</para>
  <para>
    <literallayout>
<!-- TODO: how to format this? -->
  0x01 OPTOUT
  0x80 CREATE
  0x40 REMOVE
  0x20 NONSEC
</literallayout>
  </para>
  <section><info><title>DNSKEY Rollovers</title></info>

  </section>
  <para>As with insecure-to-secure conversions, DNSSEC keyrolls
  can be done in two ways: using a dynamic DNS update, or via the
  <command>auto-dnssec</command> zone option.</para>
  <section><info><title>Dynamic DNS Update Method</title></info>

  </section>
  <para> To perform key rollovers via dynamic update,
  the <filename>K*</filename> files for the new keys must be added so that
  <command>named</command> can find them. The new
  DNSKEY RRs can then be added via dynamic update.
  <command>named</command> then causes the zone to be signed
  with the new keys; when the signing is complete, the private type
  records are updated so that the last octet is non-zero.</para>
  <para>If this is for a KSK, the parent and any
  trust anchor repositories of the new KSK must be informed.</para>
  <para>The maximum TTL in the zone must expire before
  removing the old DNSKEY. If it is a KSK that is being updated,
  the DS RRset in the parent must also be
  updated its TTL allowed to expire. This ensures that all clients
  are able to verify at least one signature when the old DNSKEY is removed.</para>
  <para>The old DNSKEY can be removed via UPDATE, taking care to
  specify the correct key.
  <command>named</command> cleans out any signatures generated
  by the old key after the update completes.</para>
  <section><info><title>Automatic Key Rollovers</title></info>

  </section>
  <para>When a new key reaches its activation date (as set by
  <command>dnssec-keygen</command> or <command>dnssec-settime</command>),
  and if the <command>auto-dnssec</command> zone option is set to
  <constant>maintain</constant>, <command>named</command>
  automatically carries out the key rollover.  If the key's algorithm
  has not previously been used to sign the zone, then the zone is
  fully signed as quickly as possible.  However, if the new key
  replaces an existing key of the same algorithm, the
  zone is re-signed incrementally, with signatures from the
  old key replaced with signatures from the new key as their
  signature validity periods expire.  By default, this rollover
  completes in 30 days, after which it is safe to remove the
  old key from the DNSKEY RRset.</para>
  <section><info><title>NSEC3PARAM Rollovers via UPDATE</title></info>

  </section>
  <para>The new NSEC3PARAM record can be added via dynamic update. When the
  new NSEC3 chain has been generated, the NSEC3PARAM flag field
  is set to zero. At that point, the old NSEC3PARAM
  record can be removed. The old chain is removed after the update request
  completes.</para>
  <section><info><title>Converting From NSEC to NSEC3</title></info>

  </section>
  <para>To do this, an NSEC3PARAM record must be added. When
  the conversion is complete, the NSEC chain is removed
  and the NSEC3PARAM record has a zero flag field. The NSEC3
  chain is generated before the NSEC chain is
  destroyed.</para>
  <section><info><title>Converting From NSEC3 to NSEC</title></info>

  </section>
  <para>To do this, use <command>nsupdate</command> to
  remove all NSEC3PARAM records with a zero flag
  field. The NSEC chain is generated before the NSEC3 chain is
  removed.</para>
  <section><info><title>Converting From Secure to Insecure</title></info>

  </section>
  <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 are removed automatically.
  This takes 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; otherwise, it will re-sign).
  </para>
  <section><info><title>Periodic Re-signing</title></info>

  </section>
  <para>In any secure zone which supports dynamic updates, <command>named</command>
  periodically re-signs RRsets which have not been re-signed as
  a result of some update action. The signature lifetimes are
  adjusted to spread the re-sign load over time rather than
  all at once.</para>
  <section><info><title>NSEC3 and OPTOUT</title></info>

  </section>
  <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; if the OPTOUT state of an individual NSEC3 needs to be
  changed, the entire chain must be
  changed.</para>
</section>