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

https://bitbucket.org/freebsd/freebsd-head/ · XML · 268 lines · 247 code · 2 blank · 19 comment · 0 complexity · ba73c92ee16af502d69f1c2d48efbba3 MD5 · raw file

  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. <!-- $Id$ -->
  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> or
  102. <command>rndc loadkeys &lt;zonename&gt;</command> command.</para>
  103. <para>
  104. <!-- TODO: this is repeated in the ARM -->
  105. <command>auto-dnssec maintain</command> includes the above
  106. functionality, but will also automatically adjust the zone's
  107. DNSKEY records on schedule according to the keys' timing metadata.
  108. (See <xref linkend="man.dnssec-keygen"/> and
  109. <xref linkend="man.dnssec-settime"/> for more information.)
  110. If keys are present in the key directory the first time the zone
  111. is loaded, it will be signed immediately, without waiting for an
  112. <command>rndc sign</command> or <command>rndc loadkeys</command>
  113. command. (Those commands can still be used when there are unscheduled
  114. key changes, however.)
  115. </para>
  116. <para>Using the
  117. <command>auto-dnssec</command> option requires the zone to be
  118. configured to allow dynamic updates, by adding an
  119. <command>allow-update</command> or
  120. <command>update-policy</command> statement to the zone
  121. configuration. If this has not been done, the configuration will
  122. fail.</para>
  123. <sect2>
  124. <title>Private-type records</title>
  125. </sect2>
  126. <para>The state of the signing process is signaled by
  127. private-type records (with a default type value of 65534). When
  128. signing is complete, these records will have a nonzero value for
  129. the final octet (for those records which have a nonzero initial
  130. octet).</para>
  131. <para>The private type record format: If the first octet is
  132. non-zero then the record indicates that the zone needs to be
  133. signed with the key matching the record, or that all signatures
  134. that match the record should be removed.</para>
  135. <para>
  136. <literallayout>
  137. <!-- TODO: how to format this? -->
  138. algorithm (octet 1)
  139. key id in network order (octet 2 and 3)
  140. removal flag (octet 4)
  141. complete flag (octet 5)
  142. </literallayout>
  143. </para>
  144. <para>Only records flagged as "complete" can be removed via
  145. dynamic update. Attempts to remove other private type records
  146. will be silently ignored.</para>
  147. <para>If the first octet is zero (this is a reserved algorithm
  148. number that should never appear in a DNSKEY record) then the
  149. record indicates changes to the NSEC3 chains are in progress. The
  150. rest of the record contains an NSEC3PARAM record. The flag field
  151. tells what operation to perform based on the flag bits.</para>
  152. <para>
  153. <literallayout>
  154. <!-- TODO: how to format this? -->
  155. 0x01 OPTOUT
  156. 0x80 CREATE
  157. 0x40 REMOVE
  158. 0x20 NONSEC
  159. </literallayout>
  160. </para>
  161. <sect2>
  162. <title>DNSKEY rollovers</title>
  163. </sect2>
  164. <para>As with insecure-to-secure conversions, rolling DNSSEC
  165. keys can be done in two ways: using a dynamic DNS update, or the
  166. <command>auto-dnssec</command> zone option.</para>
  167. <sect2>
  168. <title>Dynamic DNS update method</title>
  169. </sect2>
  170. <para> To perform key rollovers via dynamic update, you need to add
  171. the <filename>K*</filename> files for the new keys so that
  172. <command>named</command> can find them. You can then add the new
  173. DNSKEY RRs via dynamic update.
  174. <command>named</command> will then cause the zone to be signed
  175. with the new keys. When the signing is complete the private type
  176. records will be updated so that the last octet is non
  177. zero.</para>
  178. <para>If this is for a KSK you need to inform the parent and any
  179. trust anchor repositories of the new KSK.</para>
  180. <para>You should then wait for the maximum TTL in the zone before
  181. removing the old DNSKEY. If it is a KSK that is being updated,
  182. you also need to wait for the DS RRset in the parent to be
  183. updated and its TTL to expire. This ensures that all clients will
  184. be able to verify at least one signature when you remove the old
  185. DNSKEY.</para>
  186. <para>The old DNSKEY can be removed via UPDATE. Take care to
  187. specify the correct key.
  188. <command>named</command> will clean out any signatures generated
  189. by the old key after the update completes.</para>
  190. <sect2>
  191. <title>Automatic key rollovers</title>
  192. </sect2>
  193. <para>When a new key reaches its activation date (as set by
  194. <command>dnssec-keygen</command> or <command>dnssec-settime</command>),
  195. if the <command>auto-dnssec</command> zone option is set to
  196. <constant>maintain</constant>, <command>named</command> will
  197. automatically carry out the key rollover. If the key's algorithm
  198. has not previously been used to sign the zone, then the zone will
  199. be fully signed as quickly as possible. However, if the new key
  200. is replacing an existing key of the same algorithm, then the
  201. zone will be re-signed incrementally, with signatures from the
  202. old key being replaced with signatures from the new key as their
  203. signature validity periods expire. By default, this rollover
  204. completes in 30 days, after which it will be safe to remove the
  205. old key from the DNSKEY RRset.</para>
  206. <sect2>
  207. <title>NSEC3PARAM rollovers via UPDATE</title>
  208. </sect2>
  209. <para>Add the new NSEC3PARAM record via dynamic update. When the
  210. new NSEC3 chain has been generated, the NSEC3PARAM flag field
  211. will be zero. At this point you can remove the old NSEC3PARAM
  212. record. The old chain will be removed after the update request
  213. completes.</para>
  214. <sect2>
  215. <title>Converting from NSEC to NSEC3</title>
  216. </sect2>
  217. <para>To do this, you just need to add an NSEC3PARAM record. When
  218. the conversion is complete, the NSEC chain will have been removed
  219. and the NSEC3PARAM record will have a zero flag field. The NSEC3
  220. chain will be generated before the NSEC chain is
  221. destroyed.</para>
  222. <sect2>
  223. <title>Converting from NSEC3 to NSEC</title>
  224. </sect2>
  225. <para>To do this, use <command>nsupdate</command> to
  226. remove all NSEC3PARAM records with a zero flag
  227. field. The NSEC chain will be generated before the NSEC3 chain is
  228. removed.</para>
  229. <sect2>
  230. <title>Converting from secure to insecure</title>
  231. </sect2>
  232. <para>To convert a signed zone to unsigned using dynamic DNS,
  233. delete all the DNSKEY records from the zone apex using
  234. <command>nsupdate</command>. All signatures, NSEC or NSEC3 chains,
  235. and associated NSEC3PARAM records will be removed automatically.
  236. This will take place after the update request completes.</para>
  237. <para> This requires the
  238. <command>dnssec-secure-to-insecure</command> option to be set to
  239. <userinput>yes</userinput> in
  240. <filename>named.conf</filename>.</para>
  241. <para>In addition, if the <command>auto-dnssec maintain</command>
  242. zone statement is used, it should be removed or changed to
  243. <command>allow</command> instead (or it will re-sign).
  244. </para>
  245. <sect2>
  246. <title>Periodic re-signing</title>
  247. </sect2>
  248. <para>In any secure zone which supports dynamic updates, named
  249. will periodically re-sign RRsets which have not been re-signed as
  250. a result of some update action. The signature lifetimes will be
  251. adjusted so as to spread the re-sign load over time rather than
  252. all at once.</para>
  253. <sect2>
  254. <title>NSEC3 and OPTOUT</title>
  255. </sect2>
  256. <para>
  257. <command>named</command> only supports creating new NSEC3 chains
  258. where all the NSEC3 records in the zone have the same OPTOUT
  259. state.
  260. <command>named</command> supports UPDATES to zones where the NSEC3
  261. records in the chain have mixed OPTOUT state.
  262. <command>named</command> does not support changing the OPTOUT
  263. state of an individual NSEC3 record, the entire chain needs to be
  264. changed if the OPTOUT state of an individual NSEC3 needs to be
  265. changed.</para>
  266. </sect1>