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