/contrib/bind9/doc/arm/dnssec.xml

  1<?xml version="1.0" encoding="utf-8"?>
  2<!--
  3 - Copyright (C) 2010, 2012  Internet Systems Consortium, Inc. ("ISC")
  4 -
  5 - Permission to use, copy, modify, and/or distribute this software for any
  6 - purpose with or without fee is hereby granted, provided that the above
  7 - copyright notice and this permission notice appear in all copies.
  8 -
  9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 11 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 15 - PERFORMANCE OF THIS SOFTWARE.
 16-->
 17
 18<!-- $Id$ -->
 19
 20<sect1 id="dnssec.dynamic.zones">
 21  <title>DNSSEC, Dynamic Zones, and Automatic Signing</title>
 22  <para>As of BIND 9.7.0 it is possible to change a dynamic zone
 23  from insecure to signed and back again. A secure zone can use
 24  either NSEC or NSEC3 chains.</para>
 25  <sect2>
 26    <title>Converting from insecure to secure</title>
 27  </sect2>
 28  <para>Changing a zone from insecure to secure can be done in two
 29  ways: using a dynamic DNS update, or the 
 30  <command>auto-dnssec</command> zone option.</para>
 31  <para>For either method, you need to configure 
 32  <command>named</command> so that it can see the 
 33  <filename>K*</filename> files which contain the public and private
 34  parts of the keys that will be used to sign the zone. These files
 35  will have been generated by 
 36  <command>dnssec-keygen</command>. You can do this by placing them
 37  in the key-directory, as specified in 
 38  <filename>named.conf</filename>:</para>
 39  <programlisting>
 40        zone example.net {
 41                type master;
 42                update-policy local;
 43                file "dynamic/example.net/example.net";
 44                key-directory "dynamic/example.net";
 45        };
 46</programlisting>
 47  <para>If one KSK and one ZSK DNSKEY key have been generated, this
 48  configuration will cause all records in the zone to be signed
 49  with the ZSK, and the DNSKEY RRset to be signed with the KSK as
 50  well. An NSEC chain will be generated as part of the initial
 51  signing process.</para>
 52  <sect2>
 53    <title>Dynamic DNS update method</title>
 54  </sect2>
 55  <para>To insert the keys via dynamic update:</para>
 56  <screen>
 57        % nsupdate
 58        &gt; ttl 3600
 59        &gt; update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
 60        &gt; update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
 61        &gt; send
 62</screen>
 63  <para>While the update request will complete almost immediately,
 64  the zone will not be completely signed until 
 65  <command>named</command> has had time to walk the zone and
 66  generate the NSEC and RRSIG records. The NSEC record at the apex
 67  will be added last, to signal that there is a complete NSEC
 68  chain.</para>
 69  <para>If you wish to sign using NSEC3 instead of NSEC, you should
 70  add an NSEC3PARAM record to the initial update request. If you
 71  wish the NSEC3 chain to have the OPTOUT bit set, set it in the
 72  flags field of the NSEC3PARAM record.</para>
 73  <screen>
 74        % nsupdate
 75        &gt; ttl 3600
 76        &gt; update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
 77        &gt; update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
 78        &gt; update add example.net NSEC3PARAM 1 1 100 1234567890
 79        &gt; send
 80</screen>
 81  <para>Again, this update request will complete almost
 82  immediately; however, the record won't show up until 
 83  <command>named</command> has had a chance to build/remove the
 84  relevant chain. A private type record will be created to record
 85  the state of the operation (see below for more details), and will
 86  be removed once the operation completes.</para>
 87  <para>While the initial signing and NSEC/NSEC3 chain generation
 88  is happening, other updates are possible as well.</para>
 89  <sect2>
 90    <title>Fully automatic zone signing</title>
 91  </sect2>
 92  <para>To enable automatic signing, add the 
 93  <command>auto-dnssec</command> option to the zone statement in 
 94  <filename>named.conf</filename>. 
 95  <command>auto-dnssec</command> has two possible arguments: 
 96  <constant>allow</constant> or 
 97  <constant>maintain</constant>.</para>
 98  <para>With 
 99  <command>auto-dnssec allow</command>, 
100  <command>named</command> can search the key directory for keys
101  matching the zone, insert them into the zone, and use them to
102  sign the zone. It will do so only when it receives an 
103  <command>rndc sign &lt;zonename&gt;</command> or 
104  <command>rndc loadkeys &lt;zonename&gt;</command> command.</para>
105  <para>
106  <!-- TODO: this is repeated in the ARM -->
107  <command>auto-dnssec maintain</command> includes the above
108  functionality, but will also automatically adjust the zone's
109  DNSKEY records on schedule according to the keys' timing metadata.
110  (See <xref linkend="man.dnssec-keygen"/> and
111  <xref linkend="man.dnssec-settime"/> for more information.) 
112  If keys are present in the key directory the first time the zone
113  is loaded, it will be signed immediately, without waiting for an 
114  <command>rndc sign</command> or <command>rndc loadkeys</command>
115  command. (Those commands can still be used when there are unscheduled
116  key changes, however.)
117  </para>
118  <para>Using the 
119  <command>auto-dnssec</command> option requires the zone to be
120  configured to allow dynamic updates, by adding an 
121  <command>allow-update</command> or 
122  <command>update-policy</command> statement to the zone
123  configuration. If this has not been done, the configuration will
124  fail.</para>
125  <sect2>
126    <title>Private-type records</title>
127  </sect2>
128  <para>The state of the signing process is signaled by
129  private-type records (with a default type value of 65534). When
130  signing is complete, these records will have a nonzero value for
131  the final octet (for those records which have a nonzero initial
132  octet).</para>
133  <para>The private type record format: If the first octet is
134  non-zero then the record indicates that the zone needs to be
135  signed with the key matching the record, or that all signatures
136  that match the record should be removed.</para>
137  <para>
138    <literallayout>
139<!-- TODO: how to format this? -->
140  algorithm (octet 1)
141  key id in network order (octet 2 and 3)
142  removal flag (octet 4)
143  complete flag (octet 5)
144</literallayout>
145  </para>
146  <para>Only records flagged as "complete" can be removed via
147  dynamic update. Attempts to remove other private type records
148  will be silently ignored.</para>
149  <para>If the first octet is zero (this is a reserved algorithm
150  number that should never appear in a DNSKEY record) then the
151  record indicates changes to the NSEC3 chains are in progress. The
152  rest of the record contains an NSEC3PARAM record. The flag field
153  tells what operation to perform based on the flag bits.</para>
154  <para>
155    <literallayout>
156<!-- TODO: how to format this? -->
157  0x01 OPTOUT
158  0x80 CREATE
159  0x40 REMOVE
160  0x20 NONSEC
161</literallayout>
162  </para>
163  <sect2>
164    <title>DNSKEY rollovers</title>
165  </sect2>
166  <para>As with insecure-to-secure conversions, rolling DNSSEC
167  keys can be done in two ways: using a dynamic DNS update, or the 
168  <command>auto-dnssec</command> zone option.</para>
169  <sect2>
170    <title>Dynamic DNS update method</title>
171  </sect2>
172  <para> To perform key rollovers via dynamic update, you need to add
173  the <filename>K*</filename> files for the new keys so that 
174  <command>named</command> can find them. You can then add the new
175  DNSKEY RRs via dynamic update. 
176  <command>named</command> will then cause the zone to be signed
177  with the new keys. When the signing is complete the private type
178  records will be updated so that the last octet is non
179  zero.</para>
180  <para>If this is for a KSK you need to inform the parent and any
181  trust anchor repositories of the new KSK.</para>
182  <para>You should then wait for the maximum TTL in the zone before
183  removing the old DNSKEY. If it is a KSK that is being updated,
184  you also need to wait for the DS RRset in the parent to be
185  updated and its TTL to expire. This ensures that all clients will
186  be able to verify at least one signature when you remove the old
187  DNSKEY.</para>
188  <para>The old DNSKEY can be removed via UPDATE. Take care to
189  specify the correct key. 
190  <command>named</command> will clean out any signatures generated
191  by the old key after the update completes.</para>
192  <sect2>
193    <title>Automatic key rollovers</title>
194  </sect2>
195  <para>When a new key reaches its activation date (as set by
196  <command>dnssec-keygen</command> or <command>dnssec-settime</command>),
197  if the <command>auto-dnssec</command> zone option is set to 
198  <constant>maintain</constant>, <command>named</command> will
199  automatically carry out the key rollover.  If the key's algorithm
200  has not previously been used to sign the zone, then the zone will
201  be fully signed as quickly as possible.  However, if the new key
202  is replacing an existing key of the same algorithm, then the
203  zone will be re-signed incrementally, with signatures from the
204  old key being replaced with signatures from the new key as their
205  signature validity periods expire.  By default, this rollover
206  completes in 30 days, after which it will be safe to remove the
207  old key from the DNSKEY RRset.</para>
208  <sect2>
209    <title>NSEC3PARAM rollovers via UPDATE</title>
210  </sect2>
211  <para>Add the new NSEC3PARAM record via dynamic update. When the
212  new NSEC3 chain has been generated, the NSEC3PARAM flag field
213  will be zero. At this point you can remove the old NSEC3PARAM
214  record. The old chain will be removed after the update request
215  completes.</para>
216  <sect2>
217    <title>Converting from NSEC to NSEC3</title>
218  </sect2>
219  <para>To do this, you just need to add an NSEC3PARAM record. When
220  the conversion is complete, the NSEC chain will have been removed
221  and the NSEC3PARAM record will have a zero flag field. The NSEC3
222  chain will be generated before the NSEC chain is
223  destroyed.</para>
224  <sect2>
225    <title>Converting from NSEC3 to NSEC</title>
226  </sect2>
227  <para>To do this, use <command>nsupdate</command> to
228  remove all NSEC3PARAM records with a zero flag
229  field. The NSEC chain will be generated before the NSEC3 chain is
230  removed.</para>
231  <sect2>
232    <title>Converting from secure to insecure</title>
233  </sect2>
234  <para>To convert a signed zone to unsigned using dynamic DNS,
235  delete all the DNSKEY records from the zone apex using
236  <command>nsupdate</command>. All signatures, NSEC or NSEC3 chains,
237  and associated NSEC3PARAM records will be removed automatically.
238  This will take place after the update request completes.</para>
239  <para> This requires the 
240  <command>dnssec-secure-to-insecure</command> option to be set to 
241  <userinput>yes</userinput> in 
242  <filename>named.conf</filename>.</para>
243  <para>In addition, if the <command>auto-dnssec maintain</command>
244  zone statement is used, it should be removed or changed to
245  <command>allow</command> instead (or it will re-sign).
246  </para>
247  <sect2>
248    <title>Periodic re-signing</title>
249  </sect2>
250  <para>In any secure zone which supports dynamic updates, named
251  will periodically re-sign RRsets which have not been re-signed as
252  a result of some update action. The signature lifetimes will be
253  adjusted so as to spread the re-sign load over time rather than
254  all at once.</para>
255  <sect2>
256    <title>NSEC3 and OPTOUT</title>
257  </sect2>
258  <para>
259  <command>named</command> only supports creating new NSEC3 chains
260  where all the NSEC3 records in the zone have the same OPTOUT
261  state. 
262  <command>named</command> supports UPDATES to zones where the NSEC3
263  records in the chain have mixed OPTOUT state. 
264  <command>named</command> does not support changing the OPTOUT
265  state of an individual NSEC3 record, the entire chain needs to be
266  changed if the OPTOUT state of an individual NSEC3 needs to be
267  changed.</para>
268</sect1>