Bv9ARM.ch04.html revision 260e8e04b0dc24cb884c789b5d9eb046457f264e
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater - Copyright (C) 2004-2015 Internet Systems Consortium, Inc. ("ISC")
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater - Copyright (C) 2000-2003 Internet Software Consortium.
59dd3b3cd954239d98ef52cd26328856cb6f2975Automatic Updater - Permission to use, copy, modify, and/or distribute this software for any
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater - purpose with or without fee is hereby granted, provided that the above
59dd3b3cd954239d98ef52cd26328856cb6f2975Automatic Updater - copyright notice and this permission notice appear in all copies.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
5c0fc20d6e59216d9a142409e5fdb498153aeaa5Automatic Updater - PERFORMANCE OF THIS SOFTWARE.
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
04eba969cb9a54bbda2896db2067c07b2ac5ba16Automatic Updater<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<link rel="prev" href="Bv9ARM.ch03.html" title="Chapter�3.�Name Server Configuration">
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<link rel="next" href="Bv9ARM.ch05.html" title="Chapter�5.�The BIND 9 Lightweight Resolver">
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<table width="100%" summary="Navigation header">
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<tr><th colspan="3" align="center">Chapter�4.�Advanced DNS Features</th></tr>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<a accesskey="p" href="Bv9ARM.ch03.html">Prev</a>�</td>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<td width="20%" align="right">�<a accesskey="n" href="Bv9ARM.ch05.html">Next</a>
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews<div class="titlepage"><div><div><h1 class="title">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<a name="Bv9ARM.ch04"></a>Chapter�4.�Advanced DNS Features</h1></div></div></div>
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#notify">Notify</a></span></dt>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#dynamic_update">Dynamic Update</a></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<dd><dl><dt><span class="section"><a href="Bv9ARM.ch04.html#journal">The journal file</a></span></dt></dl></dd>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<dt><span class="section"><a href="Bv9ARM.ch04.html#incremental_zone_transfers">Incremental Zone Transfers (IXFR)</a></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#split_dns">Split DNS</a></span></dt>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<dd><dl><dt><span class="section"><a href="Bv9ARM.ch04.html#split_dns_sample">Example split DNS setup</a></span></dt></dl></dd>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#tsig">TSIG</a></span></dt>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.5">Generating a Shared Key</a></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.6">Loading A New Key</a></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.7">Instructing the Server to Use a Key</a></span></dt>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.8">TSIG-Based Access Control</a></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.6.9">Errors</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#tkey">TKEY</a></span></dt>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#sig0">SIG(0)</a></span></dt>
6f046a065e5543f8cd7e2f24991c65d2372f4c8dMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#DNSSEC">DNSSEC</a></span></dt>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec_keys">Generating Keys</a></span></dt>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec_signing">Signing the Zone</a></span></dt>
a8644ebab678a1de66cbfaabb513651a739958afAutomatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec_config">Configuring Servers</a></span></dt>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#dnssec.dynamic.zones">DNSSEC, Dynamic Zones, and Automatic Signing</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.3">Converting from insecure to secure</a></span></dt>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.8">Dynamic DNS update method</a></span></dt>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.16">Fully automatic zone signing</a></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.25">Private-type records</a></span></dt>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.32">DNSKEY rollovers</a></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.34">Dynamic DNS update method</a></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.39">Automatic key rollovers</a></span></dt>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.41">NSEC3PARAM rollovers via UPDATE</a></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.43">Converting from NSEC to NSEC3</a></span></dt>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.45">Converting from NSEC3 to NSEC</a></span></dt>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.47">Converting from secure to insecure</a></span></dt>
96ea71632887c58a9d00f47eb318bf76b35903c3Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.51">Periodic re-signing</a></span></dt>
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.10.53">NSEC3 and OPTOUT</a></span></dt>
2831d2c54acc60414e9ffaf5c702ba475f06754bMark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#rfc5011.support">Dynamic Trust Anchor Management</a></span></dt>
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.11.3">Validating Resolver</a></span></dt>
4cda4fd158d6ded5586bacea8c388445d99611eaAutomatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.11.4">Authoritative Server</a></span></dt>
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#pkcs11">PKCS#11 (Cryptoki) support</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.6">Prerequisites</a></span></dt>
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.7">Native PKCS#11</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.8">OpenSSL-based PKCS#11</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.9">PKCS#11 Tools</a></span></dt>
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.10">Using the HSM</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.11">Specifying the engine on the command line</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.12.12">Running named with automatic zone re-signing</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#dlz-info">DLZ (Dynamically Loadable Zones)</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.13.6">Configuring DLZ</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.13.7">Sample DLZ Driver</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#dyndb-info">DynDB (Dynamic Database)</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.14.5">Configuring DynDB</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.14.6">Sample DynDB Module</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#catz-info">Catalog Zones</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.15.4">Principle of Operation</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.15.5">Configuring Catalog Zones</a></span></dt>
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.15.6">Catalog Zone format</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#ipv6">IPv6 Support in <acronym class="acronym">BIND</acronym> 9</a></span></dt>
ea935c46e8261ea10621e5b038426539fe8a7cc5Mark Andrews<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.16.6">Address Lookups Using AAAA Records</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<dt><span class="section"><a href="Bv9ARM.ch04.html#id-1.5.16.7">Address to Name Lookups Using Nibble Format</a></span></dt>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h2 class="title" style="clear: both">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="notify"></a>Notify</h2></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <acronym class="acronym">DNS</acronym> NOTIFY is a mechanism that allows master
4cda4fd158d6ded5586bacea8c388445d99611eaAutomatic Updater servers to notify their slave servers of changes to a zone's data. In
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews response to a <span class="command"><strong>NOTIFY</strong></span> from a master server, the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater slave will check to see that its version of the zone is the
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews current version and, if not, initiate a zone transfer.
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater For more information about <acronym class="acronym">DNS</acronym>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span class="command"><strong>NOTIFY</strong></span>, see the description of the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span class="command"><strong>notify</strong></span> option in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a> and
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater the description of the zone option <span class="command"><strong>also-notify</strong></span> in
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. The <span class="command"><strong>NOTIFY</strong></span>
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews protocol is specified in RFC 1996.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater As a slave zone can also be a master to other slaves, <span class="command"><strong>named</strong></span>,
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater by default, sends <span class="command"><strong>NOTIFY</strong></span> messages for every zone
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater it loads. Specifying <span class="command"><strong>notify master-only;</strong></span> will
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater cause <span class="command"><strong>named</strong></span> to only send <span class="command"><strong>NOTIFY</strong></span> for master
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington zones that it loads.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h2 class="title" style="clear: both">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="dynamic_update"></a>Dynamic Update</h2></div></div></div>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson Dynamic Update is a method for adding, replacing or deleting
00be0f9f61d4c6bf197d000bfa1a6b7e70ea0866Automatic Updater records in a master server by sending it a special form of DNS
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater messages. The format and meaning of these messages is specified
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Dynamic update is enabled by including an
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>allow-update</strong></span> or an <span class="command"><strong>update-policy</strong></span>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews clause in the <span class="command"><strong>zone</strong></span> statement.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews If the zone's <span class="command"><strong>update-policy</strong></span> is set to
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <strong class="userinput"><code>local</code></strong>, updates to the zone
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson will be permitted for the key <code class="varname">local-ddns</code>,
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews which will be generated by <span class="command"><strong>named</strong></span> at startup.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington See <a class="xref" href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a> for more details.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews Dynamic updates using Kerberos signed requests can be made
56874aef380a64a2c183b7c282c3e7a361d67fa1Automatic Updater using the TKEY/GSS protocol by setting either the
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews <span class="command"><strong>tkey-gssapi-keytab</strong></span> option, or alternatively
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews by setting both the <span class="command"><strong>tkey-gssapi-credential</strong></span>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews and <span class="command"><strong>tkey-domain</strong></span> options. Once enabled,
56874aef380a64a2c183b7c282c3e7a361d67fa1Automatic Updater Kerberos signed requests will be matched against the update
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater policies for the zone, using the Kerberos principal as the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews signer for the request.
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews Updating of secure zones (zones using DNSSEC) follows RFC
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews 3007: RRSIG, NSEC and NSEC3 records affected by updates are
e076d0c88be69de7c190ab924d095e69d2e11f7aAndreas Gustafsson automatically regenerated by the server using an online
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zone key. Update authorization is based on transaction
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater signatures and an explicit server policy.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="titlepage"><div><div><h3 class="title">
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<a name="journal"></a>The journal file</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater All changes made to a zone using dynamic update are stored
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews in the zone's journal file. This file is automatically created
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson by the server when the first dynamic update takes place.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews The name of the journal file is formed by appending the extension
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews <code class="filename">.jnl</code> to the name of the
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews corresponding zone
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews file unless specifically overridden. The journal file is in a
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington binary format and should not be edited manually.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The server will also occasionally write ("dump")
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the complete contents of the updated zone to its zone file.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater This is not done immediately after
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater each dynamic update, because that would be too slow when a large
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zone is updated frequently. Instead, the dump is delayed by
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater up to 15 minutes, allowing additional updates to take place.
bc0a4c01beede169df81a3ee5b614ed9e82339dbAutomatic Updater During the dump process, transient files will be created
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington with the extensions <code class="filename">.jnw</code> and
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="filename">.jbk</code>; under ordinary circumstances, these
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington will be removed when the dump is complete, and can be safely
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington When a server is restarted after a shutdown or crash, it will replay
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington the journal file to incorporate into the zone any updates that
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington place after the last zone dump.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Changes that result from incoming incremental zone transfers are
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington journalled in a similar way.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The zone files of dynamic zones cannot normally be edited by
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington hand because they are not guaranteed to contain the most recent
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington dynamic changes — those are only in the journal file.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The only way to ensure that the zone file of a dynamic zone
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington is up to date is to run <span class="command"><strong>rndc stop</strong></span>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington If you have to make changes to a dynamic zone
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington manually, the following procedure will work:
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Disable dynamic updates to the zone using
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="command"><strong>rndc freeze <em class="replaceable"><code>zone</code></em></strong></span>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington This will update the zone's master file with the changes
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington stored in its <code class="filename">.jnl</code> file.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Edit the zone file. Run
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="command"><strong>rndc thaw <em class="replaceable"><code>zone</code></em></strong></span>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington to reload the changed zone and re-enable dynamic updates.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="command"><strong>rndc sync <em class="replaceable"><code>zone</code></em></strong></span>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington will update the zone file with changes from the journal file
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington without stopping dynamic updates; this may be useful for viewing
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington the current zone state. To remove the <code class="filename">.jnl</code>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington file after updating the zone file, use
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="command"><strong>rndc sync -clean</strong></span>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<div class="titlepage"><div><div><h2 class="title" style="clear: both">
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<a name="incremental_zone_transfers"></a>Incremental Zone Transfers (IXFR)</h2></div></div></div>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The incremental zone transfer (IXFR) protocol is a way for
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington slave servers to transfer only changed data, instead of having to
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington transfer the entire zone. The IXFR protocol is specified in RFC
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington 1995. See <a class="xref" href="Bv9ARM.ch11.html#proposed_standards" title="Proposed Standards">Proposed Standards</a>.
0d3490f93bb980fde704055e74c1b508987a5fe4Mark Andrews When acting as a master, <acronym class="acronym">BIND</acronym> 9
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington supports IXFR for those zones
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington where the necessary change history information is available. These
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington include master zones maintained by dynamic update and slave zones
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington whose data was obtained by IXFR. For manually maintained master
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews zones, and for slave zones obtained by performing a full zone
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews transfer (AXFR), IXFR is supported only if the option
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="command"><strong>ixfr-from-differences</strong></span> is set
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews to <strong class="userinput"><code>yes</code></strong>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater When acting as a slave, <acronym class="acronym">BIND</acronym> 9 will
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington attempt to use IXFR unless
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater it is explicitly disabled. For more information about disabling
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater IXFR, see the description of the <span class="command"><strong>request-ixfr</strong></span> clause
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington of the <span class="command"><strong>server</strong></span> statement.
81c3cb9b921cda22a5a35fa32ca1bf35797b9a36Automatic Updater<div class="titlepage"><div><div><h2 class="title" style="clear: both">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="split_dns"></a>Split DNS</h2></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Setting up different views, or visibility, of the DNS space to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater internal and external resolvers is usually referred to as a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="emphasis"><em>Split DNS</em></span> setup. There are several
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater reasons an organization would want to set up its DNS this way.
c01dec514a81ecf8c17ca3ef8c3ba95e437295ebAutomatic Updater One common reason for setting up a DNS system this way is
2d4f33db52cdd5c8bb7cd86b4c5f74205d686646Automatic Updater to hide "internal" DNS information from "external" clients on the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Internet. There is some debate as to whether or not this is actually
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Internal DNS information leaks out in many ways (via email headers,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater for example) and most savvy "attackers" can find the information
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater they need using other means.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater However, since listing addresses of internal servers that
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington external clients cannot possibly reach can result in
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater connection delays and other annoyances, an organization may
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington choose to use a Split DNS to present a consistent view of itself
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington to the outside world.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Another common reason for setting up a Split DNS system is
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington to allow internal networks that are behind filters or in RFC 1918
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington space (reserved IP space, as documented in RFC 1918) to resolve DNS
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington on the Internet. Split DNS can also be used to allow mail from outside
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington back in to the internal network.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<div class="titlepage"><div><div><h3 class="title">
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<a name="split_dns_sample"></a>Example split DNS setup</h3></div></div></div>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Let's say a company named <span class="emphasis"><em>Example, Inc.</em></span>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington has several corporate sites that have an internal network with
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews Internet Protocol (IP) space and an external demilitarized zone (DMZ),
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews or "outside" section of a network, that is available to the public.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="emphasis"><em>Example, Inc.</em></span> wants its internal clients
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to be able to resolve external hostnames and to exchange mail with
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington people on the outside. The company also wants its internal resolvers
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to have access to certain internal-only zones that are not available
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater at all outside of the internal network.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In order to accomplish this, the company will set up two sets
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington of name servers. One set will be on the inside network (in the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington IP space) and the other set will be on bastion hosts, which are
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews hosts that can talk to both sides of its network, in the DMZ.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The internal servers will be configured to forward all queries,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington except queries for <code class="filename">site1.internal</code>, <code class="filename">site2.internal</code>, <code class="filename">site1.example.com</code>,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington and <code class="filename">site2.example.com</code>, to the servers
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington DMZ. These internal servers will have complete sets of information
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington for <code class="filename">site1.example.com</code>, <code class="filename">site2.example.com</code>, <code class="filename">site1.internal</code>,
b7aab05edae933e169d5f83c653935b17c7f0a8bMark Andrews and <code class="filename">site2.internal</code>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington To protect the <code class="filename">site1.internal</code> and <code class="filename">site2.internal</code> domains,
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews the internal name servers must be configured to disallow all queries
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews to these domains from any external hosts, including the bastion
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The external servers, which are on the bastion hosts, will
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington be configured to serve the "public" version of the <code class="filename">site1</code> and <code class="filename">site2.example.com</code> zones.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington This could include things such as the host records for public servers
bbb069be941f649228760edcc241122933c066d2Automatic Updater (<code class="filename">www.example.com</code> and <code class="filename">ftp.example.com</code>),
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington and mail exchange (MX) records (<code class="filename">a.mx.example.com</code> and <code class="filename">b.mx.example.com</code>).
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington In addition, the public <code class="filename">site1</code> and <code class="filename">site2.example.com</code> zones
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington should have special MX records that contain wildcard (`*') records
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington pointing to the bastion hosts. This is needed because external mail
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington servers do not have any other way of looking up how to deliver mail
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington to those internal hosts. With the wildcard records, the mail will
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington be delivered to the bastion host, which can then forward it on to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater internal hosts.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Here's an example of a wildcard MX record:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<pre class="programlisting">* IN MX 10 external1.example.com.</pre>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Now that they accept mail on behalf of anything in the internal
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater network, the bastion hosts will need to know how to deliver mail
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to internal hosts. In order for this to work properly, the resolvers
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the bastion hosts will need to be configured to point to the internal
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater name servers for DNS resolution.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Queries for internal hostnames will be answered by the internal
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews servers, and queries for external hostnames will be forwarded back
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington out to the DNS servers on the bastion hosts.
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews In order for all this to work properly, internal clients will
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews need to be configured to query <span class="emphasis"><em>only</em></span> the internal
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews name servers for DNS queries. This could also be enforced via
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews filtering on the network.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington If everything has been set properly, <span class="emphasis"><em>Example, Inc.</em></span>'s
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington internal clients will now be able to:
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Look up any hostnames in the <code class="literal">site1</code>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="literal">site2.example.com</code> zones.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Look up any hostnames in the <code class="literal">site1.internal</code> and
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="literal">site2.internal</code> domains.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<li class="listitem">Look up any hostnames on the Internet.</li>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<li class="listitem">Exchange mail with both internal and external people.</li>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Hosts on the Internet will be able to:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Look up any hostnames in the <code class="literal">site1</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="literal">site2.example.com</code> zones.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Exchange mail with anyone in the <code class="literal">site1</code> and
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews <code class="literal">site2.example.com</code> zones.
532d27b39244fadfcf8d8b4593f4c65434c9c664Automatic Updater Here is an example configuration for the setup we just
532d27b39244fadfcf8d8b4593f4c65434c9c664Automatic Updater described above. Note that this is only configuration information;
532d27b39244fadfcf8d8b4593f4c65434c9c664Automatic Updater for information on how to configure your zone files, see <a class="xref" href="Bv9ARM.ch03.html#sample_configuration" title="Sample Configurations">the section called “Sample Configurations”</a>.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington Internal DNS server config:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updateracl internals { 172.16.72.0/24; 192.168.1.0/24; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updateracl externals { <code class="varname">bastion-ips-go-here</code>; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater // forward to external servers
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="varname">bastion-ips-go-here</code>;
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater // sample allow-transfer (no one)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-transfer { none; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater // restrict query access
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-query { internals; externals; };
fd7c65dce9c2b1a3d12ca4df9074cd38019fdb5fAutomatic Updater // restrict recursion
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-recursion { internals; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater// sample master zone
532d27b39244fadfcf8d8b4593f4c65434c9c664Automatic Updater // do normal iterative resolution (do not forward)
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington forwarders { };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-query { internals; externals; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-transfer { internals; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater// sample slave zone
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater masters { 172.16.72.3; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater forwarders { };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-query { internals; externals; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-transfer { internals; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater forwarders { };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-query { internals; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-transfer { internals; }
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater masters { 172.16.72.3; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater forwarders { };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-query { internals };
fd7c65dce9c2b1a3d12ca4df9074cd38019fdb5fAutomatic Updater allow-transfer { internals; }
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews External (bastion host) DNS server config:
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtonacl internals { 172.16.72.0/24; 192.168.1.0/24; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updateracl externals { bastion-ips-go-here; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater // sample allow-transfer (no one)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-transfer { none; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater // default query access
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-query { any; };
2da2220fe7af2c45724b50b0187523b1fab0cf08Rob Austein // restrict cache access
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-query-cache { internals; externals; };
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington // restrict recursion
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-recursion { internals; externals; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater// sample slave zone
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington allow-transfer { internals; externals; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater masters { another_bastion_host_maybe; };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater allow-transfer { internals; externals; }
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In the <code class="filename">resolv.conf</code> (or equivalent) on
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington the bastion host(s):
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtonnameserver 172.16.72.2
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaternameserver 172.16.72.3
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaternameserver 172.16.72.4
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h2 class="title" style="clear: both">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="tsig"></a>TSIG</h2></div></div></div>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington TSIG (Transaction SIGnatures) is a mechanism for authenticating DNS
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington messages, originally specified in RFC 2845. It allows DNS messages
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to be cryptographically signed using a shared secret. TSIG can
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater be used in any DNS transaction, as a way to restrict access to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater certain server functions (e.g., recursive queries) to authorized
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater clients when IP-based access control is insufficient or needs to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater be overridden, or as a way to ensure message authenticity when it
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater is critical to the integrity of the server, such as with dynamic
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater UPDATE messages or zone transfers from a master to a slave server.
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews This is a guide to setting up TSIG in <acronym class="acronym">BIND</acronym>.
f8c47598b87a5eb5ff2ceda6c81d136212d59cefAutomatic Updater It describes the configuration syntax and the process of creating
7a6ad11e0185a73984410f3252f3c49c3a301dbdBrian Wellington <span class="command"><strong>named</strong></span> supports TSIG for server-to-server
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater communication, and some of the tools included with
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <acronym class="acronym">BIND</acronym> support it for sending messages to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>named</strong></span>:
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<a class="xref" href="man.nsupdate.html" title="nsupdate"><span class="refentrytitle"><span class="application">nsupdate</span></span>(1)</a> supports TSIG via the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="option">-k</code>, <code class="option">-l</code> and
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="option">-y</code> command line options, or via
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington the <span class="command"><strong>key</strong></span> command when running
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater interactively.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a class="xref" href="man.dig.html" title="dig"><span class="refentrytitle">dig</span>(1)</a> supports TSIG via the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="option">-k</code> and <code class="option">-y</code> command
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.6.5"></a>Generating a Shared Key</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater TSIG keys can be generated using the <span class="command"><strong>tsig-keygen</strong></span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater command; the output of the command is a <span class="command"><strong>key</strong></span> directive
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater suitable for inclusion in <code class="filename">named.conf</code>. The
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater key name, algorithm and size can be specified by command line parameters;
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the defaults are "tsig-key", HMAC-SHA256, and 256 bits, respectively.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Any string which is a valid DNS name can be used as a key name.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews For example, a key to be shared between servers called
e076d0c88be69de7c190ab924d095e69d2e11f7aAndreas Gustafsson <span class="emphasis"><em>host1</em></span> and <span class="emphasis"><em>host2</em></span> could
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater be called "host1-host2.", and this key could be generated using:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater $ tsig-keygen host1-host2. > host1-host2.key
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater This key may then be copied to both hosts. The key name and secret
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater must be identical on both hosts.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (Note: copying a shared secret from one server to another is beyond
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the scope of the DNS. A secure transport mechanism should be used:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater secure FTP, SSL, ssh, telephone, encrypted email, etc.)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>tsig-keygen</strong></span> can also be run as
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="command"><strong>ddns-confgen</strong></span>, in which case its output includes
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater additional configuration text for setting up dynamic DNS in
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>named</strong></span>. See <a class="xref" href="man.ddns-confgen.html" title="ddns-confgen"><span class="refentrytitle"><span class="application">ddns-confgen</span></span>(8)</a>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.6.6"></a>Loading A New Key</h3></div></div></div>
fd7c65dce9c2b1a3d12ca4df9074cd38019fdb5fAutomatic Updater For a key shared between servers called
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="emphasis"><em>host1</em></span> and <span class="emphasis"><em>host2</em></span>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the following could be added to each server's
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="filename">named.conf</code> file:
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrewskey "host1-host2." {
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews algorithm hmac-sha256;
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY=";
fd7c65dce9c2b1a3d12ca4df9074cd38019fdb5fAutomatic Updater (This is the same key generated above using
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>tsig-keygen</strong></span>.)
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews Since this text contains a secret, it
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater is recommended that either <code class="filename">named.conf</code> not be
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington world-readable, or that the <span class="command"><strong>key</strong></span> directive
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater be stored in a file which is not world-readable, and which is
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater included in <code class="filename">named.conf</code> via the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="command"><strong>include</strong></span> directive.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Once a key has been added to <code class="filename">named.conf</code> and the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater server has been restarted or reconfigured, the server can recognize
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the key. If the server receives a message signed by the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington key, it will be able to verify the signature. If the signature
fd7c65dce9c2b1a3d12ca4df9074cd38019fdb5fAutomatic Updater is valid, the response will be signed using the same key.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater TSIG keys that are known to a server can be listed using the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater command <span class="command"><strong>rndc tsig-list</strong></span>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
53aed64e0f8553762fc0c380ee41cb42f514c7d5Brian Wellington<a name="id-1.5.6.7"></a>Instructing the Server to Use a Key</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater A server sending a request to another server must be told whether
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to use a key, and if so, which key to use.
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews For example, a key may be specified for each server in the
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews <span class="command"><strong>masters</strong></span> statement in the definition of a
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews slave zone; in this case, all SOA QUERY messages, NOTIFY
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews messages, and zone transfer requests (AXFR or IXFR) will be
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews signed using the specified key. Keys may also be specified
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews in the <span class="command"><strong>also-notify</strong></span> statement of a master
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews or slave zone, causing NOTIFY messages to be signed using
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews the specified key.
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews Keys can also be specified in a <span class="command"><strong>server</strong></span>
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews directive. Adding the following on <span class="emphasis"><em>host1</em></span>,
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews if the IP address of <span class="emphasis"><em>host2</em></span> is 10.1.2.3, would
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews cause <span class="emphasis"><em>all</em></span> requests from <span class="emphasis"><em>host1</em></span>
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews to <span class="emphasis"><em>host2</em></span>, including normal DNS queries, to be
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews signed using the <span class="command"><strong>host1-host2.</strong></span> key:
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrewsserver 10.1.2.3 {
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews keys { host1-host2. ;};
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews Multiple keys may be present in the <span class="command"><strong>keys</strong></span>
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews statement, but only the first one is used. As this directive does
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews not contain secrets, it can be used in a world-readable file.
7e1a8f402e3881388db37152f71c698cb1f1c426Mark Andrews Requests sent by <span class="emphasis"><em>host2</em></span> to <span class="emphasis"><em>host1</em></span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater would <span class="emphasis"><em>not</em></span> be signed, unless a similar
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>server</strong></span> directive were in <span class="emphasis"><em>host2</em></span>'s
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater configuration file.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Whenever any server sends a TSIG-signed DNS request, it will expect
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the response to be signed with the same key. If a response is not
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater signed, or if the signature is not valid, the response will be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.6.8"></a>TSIG-Based Access Control</h3></div></div></div>
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater TSIG keys may be specified in ACL definitions and ACL directives
f55369d776907119cd8699a4119d9c80daa7cae4Mark Andrews such as <span class="command"><strong>allow-query</strong></span>, <span class="command"><strong>allow-transfer</strong></span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater and <span class="command"><strong>allow-update</strong></span>.
f55369d776907119cd8699a4119d9c80daa7cae4Mark Andrews The above key would be denoted in an ACL element as
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>key host1-host2.</strong></span>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington An example of an <span class="command"><strong>allow-update</strong></span> directive using
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtonallow-update { !{ !localnets; any; }; key host1-host2. ;};
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater This allows dynamic updates to succeed only if the UPDATE
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater request comes from an address in <span class="command"><strong>localnets</strong></span>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="emphasis"><em>and</em></span> if it is signed using the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>host1-host2.</strong></span> key.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington See <a class="xref" href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a> for a discussion of
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the more flexible <span class="command"><strong>update-policy</strong></span> statement.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<a name="id-1.5.6.9"></a>Errors</h3></div></div></div>
fd7c65dce9c2b1a3d12ca4df9074cd38019fdb5fAutomatic Updater Processing of TSIG-signed messages can result in several errors:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater If a TSIG-aware server receives a message signed by an
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater unknown key, the response will be unsigned, with the TSIG
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater extended error code set to BADKEY.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater If a TSIG-aware server receives a message from a known key
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater but with an invalid signature, the response will be unsigned,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater with the TSIG extended error code set to BADSIG.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater If a TSIG-aware server receives a message with a time
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater outside of the allowed range, the response will be signed, with
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the TSIG extended error code set to BADTIME, and the time values
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater will be adjusted so that the response can be successfully
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In all of the above cases, the server will return a response code
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater of NOTAUTH (not authenticated).
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h2 class="title" style="clear: both">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="tkey"></a>TKEY</h2></div></div></div>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington TKEY (Transaction KEY) is a mechanism for automatically negotiating
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington a shared secret between two hosts, originally specified in RFC 2930.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington There are several TKEY "modes" that specify how a key is to be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater generated or assigned. <acronym class="acronym">BIND</acronym> 9 implements only
fd7c65dce9c2b1a3d12ca4df9074cd38019fdb5fAutomatic Updater one of these modes: Diffie-Hellman key exchange. Both hosts are
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington required to have a KEY record with algorithm DH (though this
fd7c65dce9c2b1a3d12ca4df9074cd38019fdb5fAutomatic Updater record is not required to be present in a zone).
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The TKEY process is initiated by a client or server by sending
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater a query of type TKEY to a TKEY-aware server. The query must include
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater an appropriate KEY record in the additional section, and
8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson must be signed using either TSIG or SIG(0) with a previously
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater established key. The server's response, if successful, will
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater contain a TKEY record in its answer section. After this transaction,
8227257b1c0224a7991e04bb79dc5059d5062dfbAndreas Gustafsson both participants will have enough information to calculate a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater shared secret using Diffie-Hellman key exchange. The shared secret
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater can then be used by to sign subsequent transactions between the
fd7c65dce9c2b1a3d12ca4df9074cd38019fdb5fAutomatic Updater TSIG keys known by the server, including TKEY-negotiated keys, can
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater be listed using <span class="command"><strong>rndc tsig-list</strong></span>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington TKEY-negotiated keys can be deleted from a server using
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>rndc tsig-delete</strong></span>. This can also be done via
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the TKEY protocol itself, by sending an authenticated TKEY query
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington specifying the "key deletion" mode.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h2 class="title" style="clear: both">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="sig0"></a>SIG(0)</h2></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <acronym class="acronym">BIND</acronym> partially supports DNSSEC SIG(0)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater transaction signatures as specified in RFC 2535 and RFC 2931.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater SIG(0) uses public/private keys to authenticate messages. Access control
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater is performed in the same manner as TSIG keys; privileges can be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater granted or denied in ACL directives based on the key name.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews When a SIG(0) signed message is received, it will only be
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington verified if the key is known and trusted by the server. The
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater server will not attempt to recursively fetch or validate the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington SIG(0) signing of multiple-message TCP streams is not supported.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The only tool shipped with <acronym class="acronym">BIND</acronym> 9 that
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater generates SIG(0) signed messages is <span class="command"><strong>nsupdate</strong></span>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h2 class="title" style="clear: both">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="DNSSEC"></a>DNSSEC</h2></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Cryptographic authentication of DNS information is possible
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater through the DNS Security (<span class="emphasis"><em>DNSSEC-bis</em></span>) extensions,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater defined in RFC 4033, RFC 4034, and RFC 4035.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater This section describes the creation and use of DNSSEC signed zones.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In order to set up a DNSSEC secure zone, there are a series
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater of steps which must be followed. <acronym class="acronym">BIND</acronym>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater with several tools
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater that are used in this process, which are explained in more detail
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater below. In all cases, the <code class="option">-h</code> option prints a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater full list of parameters. Note that the DNSSEC tools require the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater keyset files to be in the working directory or the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater directory specified by the <code class="option">-d</code> option, and
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington that the tools shipped with BIND 9.2.x and earlier are not compatible
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater with the current ones.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington There must also be communication with the administrators of
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the parent and/or child zone to transmit keys. A zone's security
81c3cb9b921cda22a5a35fa32ca1bf35797b9a36Automatic Updater status must be indicated by the parent zone for a DNSSEC capable
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater resolver to trust its data. This is done through the presence
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington or absence of a <code class="literal">DS</code> record at the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater For other servers to trust data in this zone, they must
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater either be statically configured with this zone's zone key or the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zone key of another zone above this one in the DNS tree.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
bd40cbcd09057ddfd043291aba82a56c90ec2523Automatic Updater<a name="dnssec_keys"></a>Generating Keys</h3></div></div></div>
a070512005933acaf17f635c6371e555425d9641Automatic Updater The <span class="command"><strong>dnssec-keygen</strong></span> program is used to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater generate keys.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson A secure zone must contain one or more zone keys. The
3341c8b653577f2f0cb8b72702ea6197035334ffMark Andrews zone keys will sign all other records in the zone, as well as
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson the zone keys of any secure delegated zones. Zone keys must
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson have the same name as the zone, a name type of
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <span class="command"><strong>ZONE</strong></span>, and must be usable for
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson authentication.
d912d1139efa8410785f0fc88dfb7dc7fbaae6deMark Andrews It is recommended that zone keys use a cryptographic algorithm
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews designated as "mandatory to implement" by the IETF; currently
9870509cb161e9c8d809ea2db41d371317ba2a35Automatic Updater the only one is RSASHA1.
282e38d96feb488fddbbc0b0409491094786977fMark Andrews The following command will generate a 768-bit RSASHA1 key for
9870509cb161e9c8d809ea2db41d371317ba2a35Automatic Updater the <code class="filename">child.example</code> zone:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <strong class="userinput"><code>dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example.</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Two output files will be produced:
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="filename">Kchild.example.+005+12345.key</code> and
8fca573ba41a1669fff64f234275e956551eb6e5Mark Andrews <code class="filename">Kchild.example.+005+12345.private</code>
0ca8fddd5b5e26d8a05f0936fc4b2666a025b9c0Mark Andrews 12345 is an example of a key tag). The key filenames contain
0ca8fddd5b5e26d8a05f0936fc4b2666a025b9c0Mark Andrews the key name (<code class="filename">child.example.</code>),
8fca573ba41a1669fff64f234275e956551eb6e5Mark Andrews algorithm (3
8fca573ba41a1669fff64f234275e956551eb6e5Mark Andrews is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in
0ca8fddd5b5e26d8a05f0936fc4b2666a025b9c0Mark Andrews The private key (in the <code class="filename">.private</code>
8fca573ba41a1669fff64f234275e956551eb6e5Mark Andrews used to generate signatures, and the public key (in the
c6517a807173827b8f638d31303805ee4c1d8054Automatic Updater <code class="filename">.key</code> file) is used for signature
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews To generate another key with the same properties (but with
10b4a0c3a4eec1b22b990c0a0595fbda51f54e94Automatic Updater a different key tag), repeat the above command.
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews The <span class="command"><strong>dnssec-keyfromlabel</strong></span> program is used
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews to get a key pair from a crypto hardware and build the key
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews files. Its usage is similar to <span class="command"><strong>dnssec-keygen</strong></span>.
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews The public keys should be inserted into the zone file by
bf1263835e8e35421960f65088c043f42aacef13Mark Andrews including the <code class="filename">.key</code> files using
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews <span class="command"><strong>$INCLUDE</strong></span> statements.
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews<div class="titlepage"><div><div><h3 class="title">
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews<a name="dnssec_signing"></a>Signing the Zone</h3></div></div></div>
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews The <span class="command"><strong>dnssec-signzone</strong></span> program is used
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews to sign a zone.
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews Any <code class="filename">keyset</code> files corresponding to
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews secure subzones should be present. The zone signer will
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews generate <code class="literal">NSEC</code>, <code class="literal">NSEC3</code>
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews and <code class="literal">RRSIG</code> records for the zone, as
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews well as <code class="literal">DS</code> for the child zones if
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <code class="literal">'-g'</code> is specified. If <code class="literal">'-g'</code>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews is not specified, then DS RRsets for the secure child
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews zones need to be added manually.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews The following command signs the zone, assuming it is in a
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews file called <code class="filename">zone.child.example</code>. By
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews default, all zone keys which have an available private key are
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews used to generate signatures.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <strong class="userinput"><code>dnssec-signzone -o child.example zone.child.example</code></strong>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews One output file is produced:
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <code class="filename">zone.child.example.signed</code>. This
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews should be referenced by <code class="filename">named.conf</code>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews input file for the zone.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<p><span class="command"><strong>dnssec-signzone</strong></span>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews will also produce a keyset and dsset files and optionally a
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews dlvset file. These are used to provide the parent zone
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews administrators with the <code class="literal">DNSKEYs</code> (or their
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews corresponding <code class="literal">DS</code> records) that are the
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews secure entry point to the zone.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<div class="titlepage"><div><div><h3 class="title">
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<a name="dnssec_config"></a>Configuring Servers</h3></div></div></div>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews To enable <span class="command"><strong>named</strong></span> to respond appropriately
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews to DNS requests from DNSSEC aware clients,
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <span class="command"><strong>dnssec-enable</strong></span> must be set to yes.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews (This is the default setting.)
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews To enable <span class="command"><strong>named</strong></span> to validate answers from
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews other servers, the <span class="command"><strong>dnssec-enable</strong></span> option
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews must be set to <strong class="userinput"><code>yes</code></strong>, and the
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <span class="command"><strong>dnssec-validation</strong></span> options must be set to
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <strong class="userinput"><code>yes</code></strong> or <strong class="userinput"><code>auto</code></strong>.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews If <span class="command"><strong>dnssec-validation</strong></span> is set to
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <strong class="userinput"><code>auto</code></strong>, then a default
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews trust anchor for the DNS root zone will be used.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews If it is set to <strong class="userinput"><code>yes</code></strong>, however,
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews then at least one trust anchor must be configured
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews with a <span class="command"><strong>trusted-keys</strong></span> or
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <span class="command"><strong>managed-keys</strong></span> statement in
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <code class="filename">named.conf</code>, or DNSSEC validation
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews will not occur. The default setting is
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <strong class="userinput"><code>yes</code></strong>.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <span class="command"><strong>trusted-keys</strong></span> are copies of DNSKEY RRs
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews for zones that are used to form the first link in the
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews cryptographic chain of trust. All keys listed in
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <span class="command"><strong>trusted-keys</strong></span> (and corresponding zones)
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews are deemed to exist and only the listed keys will be used
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews to validated the DNSKEY RRset that they are from.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <span class="command"><strong>managed-keys</strong></span> are trusted keys which are
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews automatically kept up to date via RFC 5011 trust anchor
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews maintenance.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <span class="command"><strong>trusted-keys</strong></span> and
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <span class="command"><strong>managed-keys</strong></span> are described in more detail
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews later in this document.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews Unlike <acronym class="acronym">BIND</acronym> 8, <acronym class="acronym">BIND</acronym>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews 9 does not verify signatures on load, so zone keys for
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews authoritative zones do not need to be specified in the
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews configuration file.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews After DNSSEC gets established, a typical DNSSEC configuration
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews will look something like the following. It has one or
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews more public keys for the root. This allows answers from
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews outside the organization to be validated. It will also
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews have several keys for parts of the namespace the organization
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews controls. These are here to ensure that <span class="command"><strong>named</strong></span>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews is immune to compromises in the DNSSEC components of the security
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews of parent zones.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrewsmanaged-keys {
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews /* Root Key */
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews dgxbcDTClU0CRBdiieyLMNzXG3";
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrewstrusted-keys {
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews /* Key for our organization's forward zone */
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews 5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews 4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews /* Key for our reverse zone. */
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews 2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews xOdNax071L18QqZnQQQAVVr+i
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews LhGTnNGp3HoWQLUIzKrJVZ3zg
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews gy3WwNT6kZo6c0tszYqbtvchm
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews siaOdS0yOI6BgPsw+YZdzlYMa
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews IJGf4M4dyoKIhzdZyQ2bYQrjy
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews Q4LB0lC7aOnsMyYKHHYeRvPxj
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews IQXmdqgOJGq+vsevG06zW+1xg
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews 59VvjSPsZJHeDCUyWYrvPZesZ
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews DIRvhDD52SKvbheeTJUm6Ehkz
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews dnssec-enable yes;
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews dnssec-validation yes;
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews None of the keys listed in this example are valid. In particular,
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews the root key is not valid.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews When DNSSEC validation is enabled and properly configured,
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews the resolver will reject any answers from signed, secure zones
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews which fail to validate, and will return SERVFAIL to the client.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews Responses may fail to validate for any of several reasons,
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews including missing, expired, or invalid signatures, a key which
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews does not match the DS RRset in the parent zone, or an insecure
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews response from a zone which, according to its parent, should have
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews been secure.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews When the validator receives a response from an unsigned zone
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews that has a signed parent, it must confirm with the parent
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews that the zone was intentionally left unsigned. It does
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews this by verifying, via signed and validated NSEC/NSEC3 records,
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews that the parent zone contains no DS records for the child.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews If the validator <span class="emphasis"><em>can</em></span> prove that the zone
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews is insecure, then the response is accepted. However, if it
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews cannot, then it must assume an insecure response to be a
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews forgery; it rejects the response and logs an error.
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews The logged error reads "insecurity proof failed" and
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews "got insecure response; parent indicates it should be secure".
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews (Prior to BIND 9.7, the logged error was "not insecure".
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews This referred to the zone, not the response.)
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<div class="titlepage"><div><div><h2 class="title" style="clear: both">
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<a name="dnssec.dynamic.zones"></a>DNSSEC, Dynamic Zones, and Automatic Signing</h2></div></div></div>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<p>As of BIND 9.7.0 it is possible to change a dynamic zone
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater from insecure to signed and back again. A secure zone can use
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater either NSEC or NSEC3 chains.</p>
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews<div class="section"><div class="titlepage"><div><div><h3 class="title">
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews<a name="id-1.5.10.3"></a>Converting from insecure to secure</h3></div></div></div></div>
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews<p>Changing a zone from insecure to secure can be done in two
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews ways: using a dynamic DNS update, or the
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews <span class="command"><strong>auto-dnssec</strong></span> zone option.</p>
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews<p>For either method, you need to configure
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews <span class="command"><strong>named</strong></span> so that it can see the
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews <code class="filename">K*</code> files which contain the public and private
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews parts of the keys that will be used to sign the zone. These files
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews will have been generated by
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews <span class="command"><strong>dnssec-keygen</strong></span>. You can do this by placing them
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews in the key-directory, as specified in
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews type master;
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews update-policy local;
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews<p>If one KSK and one ZSK DNSKEY key have been generated, this
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews configuration will cause all records in the zone to be signed
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews with the ZSK, and the DNSKEY RRset to be signed with the KSK as
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater well. An NSEC chain will be generated as part of the initial
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater signing process.</p>
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater<div class="section"><div class="titlepage"><div><div><h3 class="title">
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater<a name="id-1.5.10.8"></a>Dynamic DNS update method</h3></div></div></div></div>
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater<p>To insert the keys via dynamic update:</p>
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater<p>While the update request will complete almost immediately,
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater the zone will not be completely signed until
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater <span class="command"><strong>named</strong></span> has had time to walk the zone and
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater generate the NSEC and RRSIG records. The NSEC record at the apex
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson will be added last, to signal that there is a complete NSEC
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson<p>If you wish to sign using NSEC3 instead of NSEC, you should
309b912841e8b97bf0b0df0d96c3eaf16990c080Automatic Updater add an NSEC3PARAM record to the initial update request. If you
56874aef380a64a2c183b7c282c3e7a361d67fa1Automatic Updater wish the NSEC3 chain to have the OPTOUT bit set, set it in the
56874aef380a64a2c183b7c282c3e7a361d67fa1Automatic Updater flags field of the NSEC3PARAM record.</p>
754ebd37e782356aedbb2987e3c1a8ab4f29574eMark Andrews > ttl 3600
754ebd37e782356aedbb2987e3c1a8ab4f29574eMark Andrews > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
754ebd37e782356aedbb2987e3c1a8ab4f29574eMark Andrews > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
309b912841e8b97bf0b0df0d96c3eaf16990c080Automatic Updater > update add example.net NSEC3PARAM 1 1 100 1234567890
5c679dbb66df92766f6a7e7bb93c18d61275d1feMark Andrews<p>Again, this update request will complete almost
5c679dbb66df92766f6a7e7bb93c18d61275d1feMark Andrews immediately; however, the record won't show up until
5c679dbb66df92766f6a7e7bb93c18d61275d1feMark Andrews <span class="command"><strong>named</strong></span> has had a chance to build/remove the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater relevant chain. A private type record will be created to record
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the state of the operation (see below for more details), and will
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews be removed once the operation completes.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>While the initial signing and NSEC/NSEC3 chain generation
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews is happening, other updates are possible as well.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="section"><div class="titlepage"><div><div><h3 class="title">
da93950363b307b718d156514b95b9df93a63776Mark Andrews<a name="id-1.5.10.16"></a>Fully automatic zone signing</h3></div></div></div></div>
da93950363b307b718d156514b95b9df93a63776Mark Andrews<p>To enable automatic signing, add the
821d2613356f81e5bb5c107288d6d5cf35c2a1e8Mark Andrews <span class="command"><strong>auto-dnssec</strong></span> option to the zone statement in
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>auto-dnssec</strong></span> has two possible arguments:
f6056ad06781c95198505ae3a361e6dd98df4b91Automatic Updater <code class="constant">maintain</code>.</p>
f6056ad06781c95198505ae3a361e6dd98df4b91Automatic Updater <span class="command"><strong>auto-dnssec allow</strong></span>,
f6056ad06781c95198505ae3a361e6dd98df4b91Automatic Updater <span class="command"><strong>named</strong></span> can search the key directory for keys
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater matching the zone, insert them into the zone, and use them to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater sign the zone. It will do so only when it receives an
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>rndc sign <zonename></strong></span>.</p>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="command"><strong>auto-dnssec maintain</strong></span> includes the above
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater functionality, but will also automatically adjust the zone's
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews DNSKEY records on schedule according to the keys' timing metadata.
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater (See <a class="xref" href="man.dnssec-keygen.html" title="dnssec-keygen"><span class="refentrytitle"><span class="application">dnssec-keygen</span></span>(8)</a> and
79207ee45ade44ff32f6ca93c5b60250bc482089Automatic Updater <a class="xref" href="man.dnssec-settime.html" title="dnssec-settime"><span class="refentrytitle"><span class="application">dnssec-settime</span></span>(8)</a> for more information.)
79207ee45ade44ff32f6ca93c5b60250bc482089Automatic Updater <span class="command"><strong>named</strong></span> will periodically search the key directory
79207ee45ade44ff32f6ca93c5b60250bc482089Automatic Updater for keys matching the zone, and if the keys' metadata indicates
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater that any change should be made the zone, such as adding, removing,
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater or revoking a key, then that action will be carried out. By default,
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater the key directory is checked for changes every 60 minutes; this period
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater can be adjusted with the <code class="option">dnssec-loadkeys-interval</code>, up
79207ee45ade44ff32f6ca93c5b60250bc482089Automatic Updater to a maximum of 24 hours. The <span class="command"><strong>rndc loadkeys</strong></span> forces
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater <span class="command"><strong>named</strong></span> to check for key updates immediately.
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews If keys are present in the key directory the first time the zone
251227789bd26421471076f04f4e9eb7f0efb2f1Mark Andrews is loaded, the zone will be signed immediately, without waiting for an
251227789bd26421471076f04f4e9eb7f0efb2f1Mark Andrews <span class="command"><strong>rndc sign</strong></span> or <span class="command"><strong>rndc loadkeys</strong></span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater command. (Those commands can still be used when there are unscheduled
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater key changes, however.)
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater When new keys are added to a zone, the TTL is set to match that
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater of any existing DNSKEY RRset. If there is no existing DNSKEY RRset,
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater then the TTL will be set to the TTL specified when the key was
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater created (using the <span class="command"><strong>dnssec-keygen -L</strong></span> option), if
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater any, or to the SOA TTL.
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews If you wish the zone to be signed using NSEC3 instead of NSEC,
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews submit an NSEC3PARAM record via dynamic update prior to the
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews scheduled publication and activation of the keys. If you wish the
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews NSEC3 chain to have the OPTOUT bit set, set it in the flags field
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews of the NSEC3PARAM record. The NSEC3PARAM record will not appear in
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews the zone immediately, but it will be stored for later reference. When
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews the zone is signed and the NSEC3 chain is completed, the NSEC3PARAM
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews record will appear in the zone.
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews <span class="command"><strong>auto-dnssec</strong></span> option requires the zone to be
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews configured to allow dynamic updates, by adding an
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews <span class="command"><strong>allow-update</strong></span> or
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews <span class="command"><strong>update-policy</strong></span> statement to the zone
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews configuration. If this has not been done, the configuration will
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<div class="section"><div class="titlepage"><div><div><h3 class="title">
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<a name="id-1.5.10.25"></a>Private-type records</h3></div></div></div></div>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<p>The state of the signing process is signaled by
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater private-type records (with a default type value of 65534). When
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews signing is complete, these records will have a nonzero value for
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews the final octet (for those records which have a nonzero initial
f459d71198c95aee14506310947bbbf495ed2553Automatic Updater<p>The private type record format: If the first octet is
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews non-zero then the record indicates that the zone needs to be
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews signed with the key matching the record, or that all signatures
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews that match the record should be removed.</p>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater��algorithm�(octet�1)<br>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater��key�id�in�network�order�(octet�2�and�3)<br>
45eca3a5d46ed15aee14d81f6cb6c9fb6f365344Mark Andrews��removal�flag�(octet�4)<br>
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews��complete�flag�(octet�5)<br>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<p>Only records flagged as "complete" can be removed via
872a5b83f68b8058945298715b0fa53442aad52fAutomatic Updater dynamic update. Attempts to remove other private type records
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews will be silently ignored.</p>
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater<p>If the first octet is zero (this is a reserved algorithm
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews number that should never appear in a DNSKEY record) then the
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews record indicates changes to the NSEC3 chains are in progress. The
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews rest of the record contains an NSEC3PARAM record. The flag field
90eba8a49d580f9e718983fa39d8e5ee483558c9Automatic Updater tells what operation to perform based on the flag bits.</p>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews��0x01�OPTOUT<br>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington��0x80�CREATE<br>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington��0x40�REMOVE<br>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington��0x20�NONSEC<br>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<div class="section"><div class="titlepage"><div><div><h3 class="title">
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<a name="id-1.5.10.32"></a>DNSKEY rollovers</h3></div></div></div></div>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<p>As with insecure-to-secure conversions, rolling DNSSEC
ed178efa9ab8f813538fce4ff603b81ded9f1799Mark Andrews keys can be done in two ways: using a dynamic DNS update, or the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>auto-dnssec</strong></span> zone option.</p>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="section"><div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.10.34"></a>Dynamic DNS update method</h3></div></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<p> To perform key rollovers via dynamic update, you need to add
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the <code class="filename">K*</code> files for the new keys so that
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>named</strong></span> can find them. You can then add the new
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater DNSKEY RRs via dynamic update.
c28a1243429dfaf8dc5f6c1db0dccdc6ce386baeMark Andrews <span class="command"><strong>named</strong></span> will then cause the zone to be signed
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater with the new keys. When the signing is complete the private type
6c68e68fc550c947100581eb7b5340b81c062c94Andreas Gustafsson records will be updated so that the last octet is non
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>If this is for a KSK you need to inform the parent and any
5f7e0eb1cb917b788906d3e2aa01bfc4885dcae4Mark Andrews trust anchor repositories of the new KSK.</p>
bf1263835e8e35421960f65088c043f42aacef13Mark Andrews<p>You should then wait for the maximum TTL in the zone before
15ae68f3db8261770fc33b8e0f83f5d8c7021e84Mark Andrews removing the old DNSKEY. If it is a KSK that is being updated,
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews you also need to wait for the DS RRset in the parent to be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater updated and its TTL to expire. This ensures that all clients will
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews be able to verify at least one signature when you remove the old
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>The old DNSKEY can be removed via UPDATE. Take care to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater specify the correct key.
7a6ad11e0185a73984410f3252f3c49c3a301dbdBrian Wellington <span class="command"><strong>named</strong></span> will clean out any signatures generated
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews by the old key after the update completes.</p>
8ce463bc15cde5b488f0c58699c5de7a058abcc1Automatic Updater<div class="section"><div class="titlepage"><div><div><h3 class="title">
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson<a name="id-1.5.10.39"></a>Automatic key rollovers</h3></div></div></div></div>
c01dec514a81ecf8c17ca3ef8c3ba95e437295ebAutomatic Updater<p>When a new key reaches its activation date (as set by
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews <span class="command"><strong>dnssec-keygen</strong></span> or <span class="command"><strong>dnssec-settime</strong></span>),
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews if the <span class="command"><strong>auto-dnssec</strong></span> zone option is set to
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews <code class="constant">maintain</code>, <span class="command"><strong>named</strong></span> will
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews automatically carry out the key rollover. If the key's algorithm
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews has not previously been used to sign the zone, then the zone will
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews be fully signed as quickly as possible. However, if the new key
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews is replacing an existing key of the same algorithm, then the
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews zone will be re-signed incrementally, with signatures from the
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews old key being replaced with signatures from the new key as their
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews signature validity periods expire. By default, this rollover
6ceb29d4d4d6f639e50317fa6015806e80aa422aAutomatic Updater completes in 30 days, after which it will be safe to remove the
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews old key from the DNSKEY RRset.</p>
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews<div class="section"><div class="titlepage"><div><div><h3 class="title">
6ceb29d4d4d6f639e50317fa6015806e80aa422aAutomatic Updater<a name="id-1.5.10.41"></a>NSEC3PARAM rollovers via UPDATE</h3></div></div></div></div>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>Add the new NSEC3PARAM record via dynamic update. When the
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews new NSEC3 chain has been generated, the NSEC3PARAM flag field
4cda4fd158d6ded5586bacea8c388445d99611eaAutomatic Updater will be zero. At this point you can remove the old NSEC3PARAM
063c7af445b99e88f5377d9908a63880e4c86afdAutomatic Updater record. The old chain will be removed after the update request
063c7af445b99e88f5377d9908a63880e4c86afdAutomatic Updater completes.</p>
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson<div class="section"><div class="titlepage"><div><div><h3 class="title">
c01dec514a81ecf8c17ca3ef8c3ba95e437295ebAutomatic Updater<a name="id-1.5.10.43"></a>Converting from NSEC to NSEC3</h3></div></div></div></div>
981fd9903a13ba8b13e181a9eee51f228c7204c1Automatic Updater<p>To do this, you just need to add an NSEC3PARAM record. When
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews the conversion is complete, the NSEC chain will have been removed
3098364bcdd7a719fbafa5fc8d2cc9e90e5a5989Automatic Updater and the NSEC3PARAM record will have a zero flag field. The NSEC3
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews chain will be generated before the NSEC chain is
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews destroyed.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="section"><div class="titlepage"><div><div><h3 class="title">
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews<a name="id-1.5.10.45"></a>Converting from NSEC3 to NSEC</h3></div></div></div></div>
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson<p>To do this, use <span class="command"><strong>nsupdate</strong></span> to
063c7af445b99e88f5377d9908a63880e4c86afdAutomatic Updater remove all NSEC3PARAM records with a zero flag
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews field. The NSEC chain will be generated before the NSEC3 chain is
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews removed.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="section"><div class="titlepage"><div><div><h3 class="title">
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews<a name="id-1.5.10.47"></a>Converting from secure to insecure</h3></div></div></div></div>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>To convert a signed zone to unsigned using dynamic DNS,
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews delete all the DNSKEY records from the zone apex using
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>nsupdate</strong></span>. All signatures, NSEC or NSEC3 chains,
1cfd513f9df4f1485c81c245e1292a68f74e581aAutomatic Updater and associated NSEC3PARAM records will be removed automatically.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews This will take place after the update request completes.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p> This requires the
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews <span class="command"><strong>dnssec-secure-to-insecure</strong></span> option to be set to
063c7af445b99e88f5377d9908a63880e4c86afdAutomatic Updater <strong class="userinput"><code>yes</code></strong> in
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>In addition, if the <span class="command"><strong>auto-dnssec maintain</strong></span>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews zone statement is used, it should be removed or changed to
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>allow</strong></span> instead (or it will re-sign).
6ceb29d4d4d6f639e50317fa6015806e80aa422aAutomatic Updater<div class="section"><div class="titlepage"><div><div><h3 class="title">
063c7af445b99e88f5377d9908a63880e4c86afdAutomatic Updater<a name="id-1.5.10.51"></a>Periodic re-signing</h3></div></div></div></div>
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews<p>In any secure zone which supports dynamic updates, <span class="command"><strong>named</strong></span>
289caa2d1585365e94116bdfd8818da313301d7dAutomatic Updater will periodically re-sign RRsets which have not been re-signed as
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews a result of some update action. The signature lifetimes will be
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews adjusted so as to spread the re-sign load over time rather than
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews all at once.</p>
e49d15b398d34b76ceb51e50bcfea9501ade07b6Mark Andrews<div class="section"><div class="titlepage"><div><div><h3 class="title">
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson<a name="id-1.5.10.53"></a>NSEC3 and OPTOUT</h3></div></div></div></div>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>named</strong></span> only supports creating new NSEC3 chains
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews where all the NSEC3 records in the zone have the same OPTOUT
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>named</strong></span> supports UPDATES to zones where the NSEC3
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews records in the chain have mixed OPTOUT state.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>named</strong></span> does not support changing the OPTOUT
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews state of an individual NSEC3 record, the entire chain needs to be
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews changed if the OPTOUT state of an individual NSEC3 needs to be
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews changed.</p>
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews<div class="titlepage"><div><div><h2 class="title" style="clear: both">
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<a name="rfc5011.support"></a>Dynamic Trust Anchor Management</h2></div></div></div>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>BIND 9.7.0 introduces support for RFC 5011, dynamic trust
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews anchor management. Using this feature allows
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson <span class="command"><strong>named</strong></span> to keep track of changes to critical
c01dec514a81ecf8c17ca3ef8c3ba95e437295ebAutomatic Updater DNSSEC keys without any need for the operator to make changes to
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews configuration files.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="titlepage"><div><div><h3 class="title">
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<a name="id-1.5.11.3"></a>Validating Resolver</h3></div></div></div>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>To configure a validating resolver to use RFC 5011 to
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews maintain a trust anchor, configure the trust anchor using a
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>managed-keys</strong></span> statement. Information about
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews this can be found in
3098364bcdd7a719fbafa5fc8d2cc9e90e5a5989Automatic Updater <a class="xref" href="Bv9ARM.ch06.html#managed-keys" title="managed-keys Statement Definition and Usage">the section called “<span class="command"><strong>managed-keys</strong></span> Statement Definition
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="titlepage"><div><div><h3 class="title">
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<a name="id-1.5.11.4"></a>Authoritative Server</h3></div></div></div>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>To set up an authoritative zone for RFC 5011 trust anchor
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews maintenance, generate two (or more) key signing keys (KSKs) for
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews the zone. Sign the zone with one of them; this is the "active"
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews KSK. All KSKs which do not sign the zone are "stand-by"
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>Any validating resolver which is configured to use the
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews active KSK as an RFC 5011-managed trust anchor will take note
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews of the stand-by KSKs in the zone's DNSKEY RRset, and store them
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews for future reference. The resolver will recheck the zone
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews periodically, and after 30 days, if the new key is still there,
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews then the key will be accepted by the resolver as a valid trust
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews anchor for the zone. Any time after this 30-day acceptance
d30cacd81fba215923a09fae58461983142efe8bAutomatic Updater timer has completed, the active KSK can be revoked, and the
d30cacd81fba215923a09fae58461983142efe8bAutomatic Updater zone can be "rolled over" to the newly accepted key.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>The easiest way to place a stand-by key in a zone is to
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews use the "smart signing" features of
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>dnssec-keygen</strong></span> and
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>dnssec-signzone</strong></span>. If a key with a publication
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews date in the past, but an activation date which is unset or in
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews the future, "
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>dnssec-signzone -S</strong></span>" will include the DNSKEY
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews record in the zone, but will not sign with it:</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews$ <strong class="userinput"><code>dnssec-keygen -K keys -f KSK -P now -A now+2y example.net</code></strong>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews$ <strong class="userinput"><code>dnssec-signzone -S -K keys example.net</code></strong>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>To revoke a key, the new command
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>dnssec-revoke</strong></span> has been added. This adds the
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews REVOKED bit to the key flags and re-generates the
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <code class="filename">K*.private</code> files.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>After revoking the active key, the zone must be signed
3098364bcdd7a719fbafa5fc8d2cc9e90e5a5989Automatic Updater with both the revoked KSK and the new active KSK. (Smart
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews signing takes care of this automatically.)</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>Once a key has been revoked and used to sign the DNSKEY
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews RRset in which it appears, that key will never again be
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews accepted as a valid trust anchor by the resolver. However,
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews validation can proceed using the new active key (which had been
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews accepted by the resolver when it was a stand-by key).</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>See RFC 5011 for more details on key rollover
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews scenarios.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>When a key has been revoked, its key ID changes,
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews increasing by 128, and wrapping around at 65535. So, for
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews example, the key "<code class="filename">Kexample.com.+005+10000</code>" becomes
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews "<code class="filename">Kexample.com.+005+10128</code>".</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>If two keys have IDs exactly 128 apart, and one is
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews revoked, then the two key IDs will collide, causing several
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews problems. To prevent this,
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>dnssec-keygen</strong></span> will not generate a new key if
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews another key is present which may collide. This checking will
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews only occur if the new keys are written to the same directory
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews which holds all other keys in use for that zone.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<p>Older versions of BIND 9 did not have this precaution.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews Exercise caution if using key revocation on keys that were
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews generated by previous releases, or if using keys stored in
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews multiple directories or on multiple machines.</p>
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson<p>It is expected that a future release of BIND 9 will
c01dec514a81ecf8c17ca3ef8c3ba95e437295ebAutomatic Updater address this problem in a different way, by storing revoked
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews keys with their original unrevoked key IDs.</p>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="titlepage"><div><div><h2 class="title" style="clear: both">
6ceb29d4d4d6f639e50317fa6015806e80aa422aAutomatic Updater<a name="pkcs11"></a>PKCS#11 (Cryptoki) support</h2></div></div></div>
ea206aebcafe1ed5d470dd99daab9a1cedc81c7cMark Andrews PKCS#11 (Public Key Cryptography Standard #11) defines a
6ceb29d4d4d6f639e50317fa6015806e80aa422aAutomatic Updater platform-independent API for the control of hardware security
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews modules (HSMs) and other cryptographic support devices.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews BIND 9 is known to work with three HSMs: The AEP Keyper, which has
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews been tested with Debian Linux, Solaris x86 and Windows Server 2003;
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews the Thales nShield, tested with Debian Linux; and the Sun SCA 6000
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews cryptographic acceleration board, tested with Solaris x86. In
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews addition, BIND can be used with all current versions of SoftHSM,
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews a software-based HSM simulator library produced by the OpenDNSSEC
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews PKCS#11 makes use of a "provider library": a dynamically loadable
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews library which provides a low-level PKCS#11 interface to drive the HSM
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews hardware. The PKCS#11 provider library comes from the HSM vendor, and
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews it is specific to the HSM to be controlled.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews There are two available mechanisms for PKCS#11 support in BIND 9:
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson OpenSSL-based PKCS#11 and native PKCS#11. When using the first
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater mechanism, BIND uses a modified version of OpenSSL, which loads
94da7d97aecac6e3edb92aafa6b2bc8e80404e11Mark Andrews the provider library and operates the HSM indirectly; any
f55369d776907119cd8699a4119d9c80daa7cae4Mark Andrews cryptographic operations not supported by the HSM can be carried
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson out by OpenSSL instead. The second mechanism enables BIND to bypass
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson OpenSSL completely; BIND loads the provider library itself, and uses
c01dec514a81ecf8c17ca3ef8c3ba95e437295ebAutomatic Updater the PKCS#11 API to drive the HSM directly.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="titlepage"><div><div><h3 class="title">
981fd9903a13ba8b13e181a9eee51f228c7204c1Automatic Updater<a name="id-1.5.12.6"></a>Prerequisites</h3></div></div></div>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews See the documentation provided by your HSM vendor for
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews information about installing, initializing, testing and
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews troubleshooting the HSM.
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews<div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.12.7"></a>Native PKCS#11</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Native PKCS#11 mode will only work with an HSM capable of carrying
94da7d97aecac6e3edb92aafa6b2bc8e80404e11Mark Andrews out <span class="emphasis"><em>every</em></span> cryptographic operation BIND 9 may
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews need. The HSM's provider library must have a complete implementation
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews of the PKCS#11 API, so that all these functions are accessible. As of
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews this writing, only the Thales nShield HSM and SoftHSMv2 can be used
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater in this fashion. For other HSMs, including the AEP Keyper, Sun SCA
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson 6000 and older versions of SoftHSM, use OpenSSL-based PKCS#11.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (Note: Eventually, when more HSMs become capable of supporting
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews native PKCS#11, it is expected that OpenSSL-based PKCS#11 will
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews be deprecated.)
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews To build BIND with native PKCS#11, configure as follows:
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews$ <strong class="userinput"><code>cd bind9</code></strong>
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews$ <strong class="userinput"><code>/configure --enable-native-pkcs11 \
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater --with-pkcs11=<em class="replaceable"><code>provider-library-path</code></em></code></strong>
94da7d97aecac6e3edb92aafa6b2bc8e80404e11Mark Andrews This will cause all BIND tools, including <span class="command"><strong>named</strong></span>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews and the <span class="command"><strong>dnssec-*</strong></span> and <span class="command"><strong>pkcs11-*</strong></span>
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews tools, to use the PKCS#11 provider library specified in
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <em class="replaceable"><code>provider-library-path</code></em> for cryptography.
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson (The provider library path can be overridden using the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="option">-E</code> in <span class="command"><strong>named</strong></span> and the
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <span class="command"><strong>dnssec-*</strong></span> tools, or the <code class="option">-m</code> in
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews the <span class="command"><strong>pkcs11-*</strong></span> tools.)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h4 class="title">
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<a name="id-1.5.12.7.6"></a>Building SoftHSMv2</h4></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater SoftHSMv2, the latest development version of SoftHSM, is available
f345258dabf4e8ad8a1573c56810f52fca50f5d4Mark Andrews <a class="link" href="https://github.com/opendnssec/SoftHSMv2" target="_top">
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews It is a software library developed by the OpenDNSSEC project
f345258dabf4e8ad8a1573c56810f52fca50f5d4Mark Andrews (<a class="link" href="http://www.opendnssec.org" target="_top">
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews which provides a PKCS#11 interface to a virtual HSM, implemented in
f345258dabf4e8ad8a1573c56810f52fca50f5d4Mark Andrews the form of a SQLite3 database on the local filesystem. It provides
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews less security than a true HSM, but it allows you to experiment with
f345258dabf4e8ad8a1573c56810f52fca50f5d4Mark Andrews native PKCS#11 when an HSM is not available. SoftHSMv2 can be
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews configured to use either OpenSSL or the Botan library to perform
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater cryptographic functions, but when using it for native PKCS#11 in
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson BIND, OpenSSL is required.
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews By default, the SoftHSMv2 configuration file is
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <em class="replaceable"><code>prefix</code></em>/etc/softhsm2.conf (where
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson <em class="replaceable"><code>prefix</code></em> is configured at compile time).
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater This location can be overridden by the SOFTHSM2_CONF environment
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews variable. The SoftHSMv2 cryptographic store must be installed and
94da7d97aecac6e3edb92aafa6b2bc8e80404e11Mark Andrews initialized before using it with BIND.
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson$ <strong class="userinput"><code> cd SoftHSMv2 </code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code> configure --with-crypto-backend=openssl --prefix=/opt/pkcs11/usr --enable-gost </code></strong>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews$ <strong class="userinput"><code> make </code></strong>
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews$ <strong class="userinput"><code> make install </code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code> /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label softhsmv2 </code></strong>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="titlepage"><div><div><h3 class="title">
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews<a name="id-1.5.12.8"></a>OpenSSL-based PKCS#11</h3></div></div></div>
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson OpenSSL-based PKCS#11 mode uses a modified version of the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater OpenSSL library; stock OpenSSL does not fully support PKCS#11.
4e6b8a18ff7dd22797970208060cca9f99f54dafAndreas Gustafsson ISC provides a patch to OpenSSL to correct this. This patch is
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews based on work originally done by the OpenSolaris project; it has been
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews modified by ISC to provide new features such as PIN management and
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews key-by-reference.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater There are two "flavors" of PKCS#11 support provided by
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews the patched OpenSSL, one of which must be chosen at
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews configuration time. The correct choice depends on the HSM
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1676408640d8283c9f17eec0b183e1302ea7fd70Mark Andrews Use 'crypto-accelerator' with HSMs that have hardware
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews cryptographic acceleration features, such as the SCA 6000
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews board. This causes OpenSSL to run all supported
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews cryptographic operations in the HSM.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Use 'sign-only' with HSMs that are designed to
94da7d97aecac6e3edb92aafa6b2bc8e80404e11Mark Andrews function primarily as secure key storage devices, but lack
94da7d97aecac6e3edb92aafa6b2bc8e80404e11Mark Andrews hardware acceleration. These devices are highly secure, but
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews are not necessarily any faster at cryptography than the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater system CPU — often, they are slower. It is therefore
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson most efficient to use them only for those cryptographic
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater functions that require access to the secured private key,
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews such as zone signing, and to use the system CPU for all
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews other computationally-intensive operations. The AEP Keyper
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews is an example of such a device.
94da7d97aecac6e3edb92aafa6b2bc8e80404e11Mark Andrews The modified OpenSSL code is included in the BIND 9 release,
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews in the form of a context diff against the latest versions of
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews OpenSSL. OpenSSL 0.9.8, 1.0.0, 1.0.1 and 1.0.2 are supported;
94da7d97aecac6e3edb92aafa6b2bc8e80404e11Mark Andrews there are separate diffs for each version. In the examples to
94da7d97aecac6e3edb92aafa6b2bc8e80404e11Mark Andrews follow, we use OpenSSL 0.9.8, but the same methods work with
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews OpenSSL 1.0.0 through 1.0.2.
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The OpenSSL patches as of this writing (January 2016)
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews support versions 0.9.8zh, 1.0.0t, 1.0.1q and 1.0.2f.
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews ISC will provide updated patches as new versions of OpenSSL
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater are released. The version number in the following examples
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson is expected to change.
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews Before building BIND 9 with PKCS#11 support, it will be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater necessary to build OpenSSL with the patch in place, and configure
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson it with the path to your HSM's PKCS#11 provider library.
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews<div class="titlepage"><div><div><h4 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.12.8.8"></a>Patching OpenSSL</h4></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>wget <a class="link" href="" target="_top">http://www.openssl.org/source/openssl-0.9.8zc.tar.gz</a></code></strong>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews$ <strong class="userinput"><code>tar zxf openssl-0.9.8zc.tar.gz</code></strong>
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews$ <strong class="userinput"><code>patch -p1 -d openssl-0.9.8zc \
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater < bind9/bin/pkcs11/openssl-0.9.8zc-patch</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The patch file may not be compatible with the
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson "patch" utility on all operating systems. You may need to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater install GNU patch.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews When building OpenSSL, place it in a non-standard
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews location so that it does not interfere with OpenSSL libraries
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater elsewhere on the system. In the following examples, we choose
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson to install into "/opt/pkcs11/usr". We will use this location
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater when we configure BIND 9.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Later, when building BIND 9, the location of the custom-built
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson OpenSSL library will need to be specified via configure.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="titlepage"><div><div><h4 class="title">
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews<a name="id-1.5.12.8.9"></a>Building OpenSSL for the AEP Keyper on Linux</h4></div></div></div>
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson The AEP Keyper is a highly secure key storage device,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater but does not provide hardware cryptographic acceleration. It
85c594efe4c8d4a8c7335754d7989d0d7e00661cAutomatic Updater can carry out cryptographic operations, but it is probably
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews slower than your system's CPU. Therefore, we choose the
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews 'sign-only' flavor when building OpenSSL.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The Keyper-specific PKCS#11 provider library is
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson delivered with the Keyper software. In this example, we place
94da7d97aecac6e3edb92aafa6b2bc8e80404e11Mark Andrews$ <strong class="userinput"><code>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</code></strong>
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews This library is only available for Linux as a 32-bit
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater binary. If we are compiling on a 64-bit Linux system, it is
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson necessary to force a 32-bit build, by specifying -m32 in the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater build options.
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews Finally, the Keyper library requires threads, so we
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater must specify -pthread.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews$ <strong class="userinput"><code>cd openssl-0.9.8zc</code></strong>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews$ <strong class="userinput"><code>/Configure linux-generic32 -m32 -pthread \
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater --pk11-flavor=sign-only \
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater After configuring, run "<span class="command"><strong>make</strong></span>"
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews and "<span class="command"><strong>make test</strong></span>". If "<span class="command"><strong>make
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater test</strong></span>" fails with "pthread_atfork() not found", you forgot to
063c7af445b99e88f5377d9908a63880e4c86afdAutomatic Updater add the -pthread above.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews<div class="titlepage"><div><div><h4 class="title">
dd9ad704c3800e3ab07ede8595871eac79984871Mark Andrews<a name="id-1.5.12.8.10"></a>Building OpenSSL for the SCA 6000 on Solaris</h4></div></div></div>
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater The SCA-6000 PKCS#11 provider is installed as a system
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews library, libpkcs11. It is a true crypto accelerator, up to 4
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews times faster than any CPU, so the flavor shall be
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews 'crypto-accelerator'.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews In this example, we are building on Solaris x86 on an
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews AMD64 system.
65f40aa6826be815fe71f0f71e51e1ee0e80d56bAutomatic Updater$ <strong class="userinput"><code>cd openssl-0.9.8zc</code></strong>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews$ <strong class="userinput"><code>/Configure solaris64-x86_64-cc \
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews --pk11-flavor=crypto-accelerator \
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (For a 32-bit build, use "solaris-x86-cc" and /usr/lib/libpkcs11.so.)
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews After configuring, run
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>make</strong></span> and
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>make test</strong></span>.
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updater<div class="titlepage"><div><div><h4 class="title">
10640b2e3efc7bc8034108136d7487f7407fbf37Andreas Gustafsson<a name="id-1.5.12.8.11"></a>Building OpenSSL for SoftHSM</h4></div></div></div>
10640b2e3efc7bc8034108136d7487f7407fbf37Andreas Gustafsson SoftHSM (version 1) is a software library developed by the
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews OpenDNSSEC project
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (<a class="link" href="http://www.opendnssec.org" target="_top">
bf46736ab182c4663beb5a08cb2ebf7c364e0aa9Automatic Updater which provides a
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater PKCS#11 interface to a virtual HSM, implemented in the form of
bf46736ab182c4663beb5a08cb2ebf7c364e0aa9Automatic Updater a SQLite3 database on the local filesystem. SoftHSM uses
70232e6b444994979d8bab60bc9a8656ffd861e9Mark Andrews the Botan library to perform cryptographic functions. Though
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater less secure than a true HSM, it can allow you to experiment
bf46736ab182c4663beb5a08cb2ebf7c364e0aa9Automatic Updater with PKCS#11 when an HSM is not available.
3e79333aa37d3b88959372431a02af8a3eb7cfd9Automatic Updater The SoftHSM cryptographic store must be installed and
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater initialized before using it with OpenSSL, and the SOFTHSM_CONF
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater environment variable must always point to the SoftHSM configuration
a8644ebab678a1de66cbfaabb513651a739958afAutomatic Updater$ <strong class="userinput"><code> cd softhsm-1.3.7 </code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code> configure --prefix=/opt/pkcs11/usr </code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code> make </code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code> make install </code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </code></strong>
4cda4fd158d6ded5586bacea8c388445d99611eaAutomatic Updater$ <strong class="userinput"><code> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater SoftHSM can perform all cryptographic operations, but
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater since it only uses your system CPU, there is no advantage to using
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater it for anything but signing. Therefore, we choose the 'sign-only'
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater flavor when building OpenSSL.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>cd openssl-0.9.8zc</code></strong>
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews$ <strong class="userinput"><code>/Configure linux-x86_64 -pthread \
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater --pk11-libname=/opt/pkcs11/usr/lib/libsofthsm.so \
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews --pk11-flavor=sign-only \
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater After configuring, run "<span class="command"><strong>make</strong></span>"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater and "<span class="command"><strong>make test</strong></span>".
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Once you have built OpenSSL, run
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater "<span class="command"><strong>apps/openssl engine pkcs11</strong></span>" to confirm
3e79333aa37d3b88959372431a02af8a3eb7cfd9Automatic Updater that PKCS#11 support was compiled in correctly. The output
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater should be one of the following lines, depending on the flavor
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (pkcs11) PKCS #11 engine support (sign only)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (pkcs11) PKCS #11 engine support (crypto accelerator)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater "<span class="command"><strong>apps/openssl engine pkcs11 -t</strong></span>". This will
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater attempt to initialize the PKCS#11 engine. If it is able to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater do so successfully, it will report
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="quote">“<span class="quote"><code class="literal">[ available ]</code></span>”</span>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater If the output is correct, run
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater "<span class="command"><strong>make install</strong></span>" which will install the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater modified OpenSSL suite to <code class="filename">/opt/pkcs11/usr</code>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h4 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.12.8.18"></a>Configuring BIND 9 for Linux with the AEP Keyper</h4></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater To link with the PKCS#11 provider, threads must be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater enabled in the BIND 9 build.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The PKCS#11 library for the AEP Keyper is currently
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater only available as a 32-bit binary. If we are building on a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater 64-bit host, we must force a 32-bit build by adding "-m32" to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the CC options on the "configure" command line.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>cd /bind9</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>/configure CC="gcc -m32" --enable-threads \
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h4 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.12.8.19"></a>Configuring BIND 9 for Solaris with the SCA 6000</h4></div></div></div>
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater To link with the PKCS#11 provider, threads must be
40696c4c389a780082fb77840c173b201ce696d6Automatic Updater enabled in the BIND 9 build.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>cd /bind9</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>/configure CC="cc -xarch=amd64" --enable-threads \
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater --with-pkcs11=/usr/lib/64/libpkcs11.so</code></strong>
5147281cb8e25c599d759dfa65fdb6f9125efefbMark Andrews<p>(For a 32-bit build, omit CC="cc -xarch=amd64".)</p>
04eba969cb9a54bbda2896db2067c07b2ac5ba16Automatic Updater If configure complains about OpenSSL not working, you
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater may have a 32/64-bit architecture mismatch. Or, you may have
40696c4c389a780082fb77840c173b201ce696d6Automatic Updater incorrectly specified the path to OpenSSL (it should be the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater same as the --prefix argument to the OpenSSL
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h4 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.12.8.20"></a>Configuring BIND 9 for SoftHSM</h4></div></div></div>
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater$ <strong class="userinput"><code>cd /bind9</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>/configure --enable-threads \
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater --with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so</code></strong>
bbb069be941f649228760edcc241122933c066d2Automatic Updater After configuring, run
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater "<span class="command"><strong>make</strong></span>",
bbb069be941f649228760edcc241122933c066d2Automatic Updater "<span class="command"><strong>make test</strong></span>" and
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater "<span class="command"><strong>make install</strong></span>".
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (Note: If "make test" fails in the "pkcs11" system test, you may
5147281cb8e25c599d759dfa65fdb6f9125efefbMark Andrews have forgotten to set the SOFTHSM_CONF environment variable.)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.12.9"></a>PKCS#11 Tools</h3></div></div></div>
9a0529a96f1c97e5056f0c31d604279ca8fdbdc7Automatic Updater BIND 9 includes a minimal set of tools to operate the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater HSM, including
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>pkcs11-keygen</strong></span> to generate a new key pair
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater within the HSM,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>pkcs11-list</strong></span> to list objects currently
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>pkcs11-destroy</strong></span> to remove objects, and
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>pkcs11-tokens</strong></span> to list available tokens.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In UNIX/Linux builds, these tools are built only if BIND
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater 9 is configured with the --with-pkcs11 option. (Note: If
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater --with-pkcs11 is set to "yes", rather than to the path of the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater PKCS#11 provider, then the tools will be built but the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater provider will be left undefined. Use the -m option or the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater PKCS11_PROVIDER environment variable to specify the path to the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.12.10"></a>Using the HSM</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater For OpenSSL-based PKCS#11, we must first set up the runtime
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater environment so the OpenSSL and PKCS#11 libraries can be loaded:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater This causes <span class="command"><strong>named</strong></span> and other binaries to load
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the OpenSSL library from <code class="filename">/opt/pkcs11/usr/lib</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater rather than from the default location. This step is not necessary
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater when using native PKCS#11.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Some HSMs require other environment variables to be set.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater For example, when operating an AEP Keyper, it is necessary to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater specify the location of the "machine" file, which stores
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater information about the Keyper for use by the provider
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater library. If the machine file is in
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="filename">/opt/Keyper/PKCS11Provider/machine</code>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Such environment variables must be set whenever running
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater any tool that uses the HSM, including
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>pkcs11-keygen</strong></span>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>pkcs11-list</strong></span>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>pkcs11-destroy</strong></span>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>dnssec-keyfromlabel</strong></span>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>dnssec-signzone</strong></span>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>dnssec-keygen</strong></span>, and
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>named</strong></span>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater We can now create and use keys in the HSM. In this case,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater we will create a 2048 bit key and give it the label
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>pkcs11-keygen -b 2048 -l sample-ksk</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>pkcs11-list</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaterobject[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0]
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaterobject[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0]
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Before using this key to sign a zone, we must create a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater pair of BIND 9 key files. The "dnssec-keyfromlabel" utility
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater does this. In this case, we will be using the HSM key
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater "sample-ksk" as the key-signing key for "example.net":
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater$ <strong class="userinput"><code>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The resulting K*.key and K*.private files can now be used
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to sign the zone. Unlike normal K* files, which contain both
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater public and private key data, these files will contain only the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater public key data, plus an identifier for the private key which
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater remains stored within the HSM. Signing with the private key takes
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater place inside the HSM.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater If you wish to generate a second key in the HSM for use
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater as a zone-signing key, follow the same procedure above, using a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater different keylabel, a smaller key size, and omitting "-f KSK"
4cda4fd158d6ded5586bacea8c388445d99611eaAutomatic Updater from the dnssec-keyfromlabel arguments:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (Note: When using OpenSSL-based PKCS#11 the label is an arbitrary
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater string which identifies the key. With native PKCS#11, the label is
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater a PKCS#11 URI string which may include other details about the key
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater and the HSM, including its PIN. See
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <a class="xref" href="man.dnssec-keyfromlabel.html" title="dnssec-keyfromlabel"><span class="refentrytitle"><span class="application">dnssec-keyfromlabel</span></span>(8)</a> for details.)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>pkcs11-keygen -b 1024 -l sample-zsk</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>dnssec-keyfromlabel -l sample-zsk example.net</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Alternatively, you may prefer to generate a conventional
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater on-disk key, using dnssec-keygen:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater$ <strong class="userinput"><code>dnssec-keygen example.net</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater This provides less security than an HSM key, but since
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater HSMs can be slow or cumbersome to use for security reasons, it
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater may be more efficient to reserve HSM keys for use in the less
555d01f4c02295e896a26c649d0ffc8808a0bbdcAutomatic Updater frequent key-signing operation. The zone-signing key can be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater rolled more frequently, if you wish, to compensate for a
593e8b883a3612fb55eeefd707933cb702531844Automatic Updater reduction in key security. (Note: When using native PKCS#11,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater there is no speed advantage to using on-disk keys, as cryptographic
fc3576328379e813ccf6b3a6e66d9bb701a79c83Automatic Updater operations will be done by the HSM regardless.)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Now you can sign the zone. (Note: If not using the -S
0d3490f93bb980fde704055e74c1b508987a5fe4Mark Andrews option to <span class="command"><strong>dnssec-signzone</strong></span>, it will be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater necessary to add the contents of both <code class="filename">K*.key</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater files to the zone master file before signing it.)
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater$ <strong class="userinput"><code>dnssec-signzone -S example.net</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterVerifying the zone using the following algorithms:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterZone signing complete:
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic UpdaterAlgorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by
3e79333aa37d3b88959372431a02af8a3eb7cfd9Automatic Updater<div class="titlepage"><div><div><h3 class="title">
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updater<a name="id-1.5.12.11"></a>Specifying the engine on the command line</h3></div></div></div>
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson When using OpenSSL-based PKCS#11, the "engine" to be used by
992616aaf75643a0c9f84826f0a1ed5a27e84328Mark Andrews OpenSSL can be specified in <span class="command"><strong>named</strong></span> and all of
59dd3b3cd954239d98ef52cd26328856cb6f2975Automatic Updater the BIND <span class="command"><strong>dnssec-*</strong></span> tools by using the "-E
9351aa7eb4e282ba2050bd247ec7dc3139c199d9Automatic Updater <engine>" command line option. If BIND 9 is built with
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson the --with-pkcs11 option, this option defaults to "pkcs11".
9351aa7eb4e282ba2050bd247ec7dc3139c199d9Automatic Updater Specifying the engine will generally not be necessary unless
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater for some reason you wish to use a different OpenSSL
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater If you wish to disable use of the "pkcs11" engine —
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews for troubleshooting purposes, or because the HSM is unavailable
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater — set the engine to the empty string. For example:
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater$ <strong class="userinput"><code>dnssec-signzone -E '' -S example.net</code></strong>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>dnssec-signzone</strong></span> to run as if it were compiled
70232e6b444994979d8bab60bc9a8656ffd861e9Mark Andrews without the --with-pkcs11 option.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater When built with native PKCS#11 mode, the "engine" option has a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater different meaning: it specifies the path to the PKCS#11 provider
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater library. This may be useful when testing a new provider library.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.12.12"></a>Running named with automatic zone re-signing</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater If you want <span class="command"><strong>named</strong></span> to dynamically re-sign zones
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater using HSM keys, and/or to to sign new records inserted via nsupdate,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater then <span class="command"><strong>named</strong></span> must have access to the HSM PIN. In OpenSSL-based PKCS#11,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater this is accomplished by placing the PIN into the openssl.cnf file
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater (in the above examples,
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater <code class="filename">/opt/pkcs11/usr/ssl/openssl.cnf</code>).
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater The location of the openssl.cnf file can be overridden by
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater setting the OPENSSL_CONF environment variable before running
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater <span class="command"><strong>named</strong></span>.
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews openssl_conf = openssl_def
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater [ openssl_def ]
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater engines = engine_section
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater [ engine_section ]
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater pkcs11 = pkcs11_section
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater [ pkcs11_section ]
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater PIN = <em class="replaceable"><code><PLACE PIN HERE></code></em>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater This will also allow the dnssec-* tools to access the HSM
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater without PIN entry. (The pkcs11-* tools access the HSM directly,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater not via OpenSSL, so a PIN will still be required to use
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In native PKCS#11 mode, the PIN can be provided in a file specified
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater as an attribute of the key's label. For example, if a key had the label
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <strong class="userinput"><code>pkcs11:object=local-zsk;pin-source=/etc/hsmpin</code></strong>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater then the PIN would be read from the file
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="filename">/etc/hsmpin</code>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Placing the HSM's PIN in a text file in this manner may reduce the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater security advantage of using an HSM. Be sure this is what you want to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater do before configuring the system in this way.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h2 class="title" style="clear: both">
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater<a name="dlz-info"></a>DLZ (Dynamically Loadable Zones)</h2></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater DLZ (Dynamically Loadable Zones) is an extension to BIND 9 that allows
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zone data to be retrieved directly from an external database. There is
f6056ad06781c95198505ae3a361e6dd98df4b91Automatic Updater no required format or schema. DLZ drivers exist for several different
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater database backends including PostgreSQL, MySQL, and LDAP and can be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater written for any other.
40696c4c389a780082fb77840c173b201ce696d6Automatic Updater Historically, DLZ drivers had to be statically linked with the <span class="command"><strong>named</strong></span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater binary and were turned on via a configure option at compile time (for
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater example, <strong class="userinput"><code>"configure --with-dlz-ldap"</code></strong>).
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater Currently, the drivers provided in the BIND 9 tarball in
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="filename">contrib/dlz/drivers</code> are still linked this
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In BIND 9.8 and higher, it is possible to link some DLZ modules
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater dynamically at runtime, via the DLZ "dlopen" driver, which acts as a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater generic wrapper around a shared object implementing the DLZ API. The
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater "dlopen" driver is linked into <span class="command"><strong>named</strong></span> by default, so configure options
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater are no longer necessary when using these dynamically linkable drivers,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater but are still needed for the older drivers in
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="filename">contrib/dlz/drivers</code>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater When the DLZ module provides data to <span class="command"><strong>named</strong></span>, it does so in text format.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The response is converted to DNS wire format by <span class="command"><strong>named</strong></span>. This
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater conversion, and the lack of any internal caching, places significant
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater limits on the query performance of DLZ modules. Consequently, DLZ is
6a78eb0a8677dca8817233799a715de27f9c2cbbMark Andrews not recommended for use on high-volume servers. However, it can be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater used in a hidden master configuration, with slaves retrieving zone
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater updates via AXFR. (Note, however, that DLZ has no built-in support for
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater DNS notify; slaves are not automatically informed of changes to the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zones in the database.)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.13.6"></a>Configuring DLZ</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater A DLZ database is configured with a <span class="command"><strong>dlz</strong></span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater statement in <code class="filename">named.conf</code>:
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater database "dlopen driver.so <code class="option">args</code>";
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater This specifies a DLZ module to search when answering queries; the
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater module is implemented in <code class="filename">driver.so</code> and is
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater loaded at runtime by the dlopen DLZ driver. Multiple
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>dlz</strong></span> statements can be specified; when
f6056ad06781c95198505ae3a361e6dd98df4b91Automatic Updater answering a query, all DLZ modules with <code class="option">search</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater set to <code class="literal">yes</code> will be queried to find out if
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington they contain an answer for the query name; the best available
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater answer will be returned to the client.
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater The <code class="option">search</code> option in the above example can be
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater omitted, because <code class="literal">yes</code> is the default value.
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater If <code class="option">search</code> is set to <code class="literal">no</code>, then
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater this DLZ module is <span class="emphasis"><em>not</em></span> searched for the best
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington match when a query is received. Instead, zones in this DLZ must be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater separately specified in a zone statement. This allows you to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater configure a zone normally using standard zone option semantics,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington but specify a different database back-end for storage of the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zone's data. For example, to implement NXDOMAIN redirection using
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington a DLZ module for back-end storage of redirection rules:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater database "dlopen driver.so <code class="option">args</code>";
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater type redirect;
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater<div class="titlepage"><div><div><h3 class="title">
788778633d6d67dee01b68a5827f8e655f2c276bMark Andrews<a name="id-1.5.13.7"></a>Sample DLZ Driver</h3></div></div></div>
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews For guidance in implementation of DLZ modules, the directory
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="filename">contrib/dlz/example</code> contains a basic
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater dynamically-linkable DLZ module--i.e., one which can be
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews loaded at runtime by the "dlopen" DLZ driver.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The example sets up a single zone, whose name is passed
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews to the module as an argument in the <span class="command"><strong>dlz</strong></span>
2775a809a54d11e1dd4e1b44aca0bcd5de16f8b2Automatic Updater In the above example, the module is configured to create a zone
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater "example.nil", which can answer queries and AXFR requests, and
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater accept DDNS updates. At runtime, prior to any updates, the zone
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater contains an SOA, NS, and a single A record at the apex:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater example.nil. 3600 IN SOA example.nil. hostmaster.example.nil. (
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater 123 900 600 86400 3600
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater example.nil. 1800 IN A 10.53.0.1
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater The sample driver is capable of retrieving information about the
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater querying client, and altering its response on the basis of this
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater information. To demonstrate this feature, the example driver
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater responds to queries for "source-addr.<code class="option">zonename</code>>/TXT"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater with the source address of the query. Note, however, that this
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater record will *not* be included in AXFR or ANY responses. Normally,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater this feature would be used to alter responses in some other fashion,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater e.g., by providing different address records for a particular name
83a97deac2c474a2e8fd60326135236fe267069cAutomatic Updater depending on the network from which the query arrived.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Documentation of the DLZ module API can be found in
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="filename">contrib/dlz/example/README</code>. This directory also
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews contains the header file <code class="filename">dlz_minimal.h</code>, which
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater defines the API and should be included by any dynamically-linkable
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h2 class="title" style="clear: both">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="dyndb-info"></a>DynDB (Dynamic Database)</h2></div></div></div>
c01dec514a81ecf8c17ca3ef8c3ba95e437295ebAutomatic Updater DynDB is an extension to BIND 9 which, like DLZ
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater (see <a class="xref" href="Bv9ARM.ch04.html#dlz-info" title="DLZ (Dynamically Loadable Zones)">the section called “DLZ (Dynamically Loadable Zones)”</a>), allows zone data to be
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews retrieved from an external database. Unlike DLZ, a DynDB module
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater provides a full-featured BIND zone database interface. Where
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews DLZ translates DNS queries into real-time database lookups,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater resulting in relatively poor query performance, and is unable
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to handle DNSSEC-signed data due to its limited API, a DynDB
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater module can pre-load an in-memory database from the external
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater data source, providing the same performance and functionality
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater as zones served natively by BIND.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater A DynDB module supporting LDAP has been created by Red Hat
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater and is available from
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <a class="link" href="https://fedorahosted.org/bind-dyndb-ldap/" target="_top">https://fedorahosted.org/bind-dyndb-ldap/</a>.
c01dec514a81ecf8c17ca3ef8c3ba95e437295ebAutomatic Updater A sample DynDB module for testing and developer guidance
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater is included with the BIND source code, in the directory
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="filename">bin/tests/system/dyndb/driver</code>.
420ebb7c689947a99ff547b7f76bc18bc2ad17b4Automatic Updater<div class="titlepage"><div><div><h3 class="title">
532d27b39244fadfcf8d8b4593f4c65434c9c664Automatic Updater<a name="id-1.5.14.5"></a>Configuring DynDB</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater A DynDB database is configured with a <span class="command"><strong>dyndb</strong></span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater statement in <code class="filename">named.conf</code>:
97669cab1f7e6f953dbf39ef1b2c4206ecb50d9eAutomatic Updater dyndb example "driver.so" {
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <em class="replaceable"><code>parameters</code></em>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The file <code class="filename">driver.so</code> is a DynDB module which
c6517a807173827b8f638d31303805ee4c1d8054Automatic Updater implements the full DNS database API. Multiple
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>dyndb</strong></span> statements can be specified, to load
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater different drivers or multiple instances of the same driver.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Zones provided by a DynDB module are added to the view's zone
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater table, and are treated as normal authoritative zones when BIND
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater is responding to queries. Zone configuration is handled internally
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater by the DynDB module.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The <em class="replaceable"><code>parameters</code></em> are passed as an opaque
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater string to the DynDB module's initialization routine. Configuration
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater syntax will differ depending on the driver.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
6f046a065e5543f8cd7e2f24991c65d2372f4c8dMark Andrews<a name="id-1.5.14.6"></a>Sample DynDB Module</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater For guidance in implementation of DynDB modules, the directory
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="filename">bin/tests/system/dyndb/driver</code>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater contains a basic DynDB module.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The example sets up two zones, whose names are passed
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater to the module as arguments in the <span class="command"><strong>dyndb</strong></span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater dyndb sample "sample.so" { example.nil. arpa. };
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In the above example, the module is configured to create a zone
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater "example.nil", which can answer queries and AXFR requests, and
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater accept DDNS updates. At runtime, prior to any updates, the zone
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater contains an SOA, NS, and a single A record at the apex:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater example.nil. 86400 IN SOA example.nil. example.nil. (
21386ce160ea276bcc61a14103933fe74ec77193Automatic Updater 0 28800 7200 604800 86400
00be0f9f61d4c6bf197d000bfa1a6b7e70ea0866Automatic Updater example.nil. 86400 IN A 127.0.0.1
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater When the zone is updated dynamically, the DynDB module will determine
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updater whether the updated RR is an address (i.e., type A or AAAA) and if
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updater so, it will automatically update the corresponding PTR record in a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater reverse zone. (Updates are not stored permanently; all updates are
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater lost when the server is restarted.)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h2 class="title" style="clear: both">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="catz-info"></a>Catalog Zones</h2></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater A "catalog zone" is a special DNS zone that contains a list of
00be0f9f61d4c6bf197d000bfa1a6b7e70ea0866Automatic Updater other zones to be served, along with their configuration parameters.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Zones listed in a catalog zone are called "member zones".
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater When a catalog zone is loaded or transferred to a slave server
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater which supports this functionality, the slave server will create
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater the member zones automatically. When the catalog zone is updated
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater is updated (for example, to add or delete member zones, or change
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater their configuration aprameters) those changes are immediately put
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater into effect. Because the catalog zone is a normal DNS zone, these
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater configuration changes can be propagated using the standard AXFR/IXFR
40696c4c389a780082fb77840c173b201ce696d6Automatic Updater zone transfer mechanism.
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater Catalog zones' format and behavior are specified as an internet draft
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater for interoperability among DNS implementations. As of this release, the
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater latest revision of the DNS catalog zones draft can be found here:
30cd5217f750e75c24b4fe4b5ecf92e832ba64c3Automatic Updater https://datatracker.ietf.org/doc/draft-muks-dnsop-dns-catalog-zones/
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.15.4"></a>Principle of Operation</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Normally, if a zone is to be served by a slave server, the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="filename">named.conf</code> file on the server must list the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zone, or the zone must be added using <span class="command"><strong>rndc addzone</strong></span>.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington In environments with a large number of slave servers and/or where
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the zones being served are changing frequently, the overhead involved
1d92d8a2456b23842a649b6104c60a9d6ea25333Brian Wellington in maintaining consistent zone configuration on all the slave
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater servers can be significant.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater A catalog zone is a way to ease this administrative burden. It is a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater DNS zone that lists member zones that should be served by slave servers.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater When a slave server receives an update to the catalog zone, it adds,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater removes, or reconfigures member zones based on the data received.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater To use a catalog zone, it must first be set up as a normal zone on
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the master and the on slave servers that will be configured to use
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater it. It must also be added to a <code class="option">catalog-zones</code> list
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater in the <code class="option">options</code> or <code class="option">view</code> statement
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater in <code class="filename">named.conf</code>. (This is comparable to the way
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater a policy zone is configured as a normal zone and also listed in
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater a <code class="option">response-policy</code> statement.)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater To use the catalog zone feature to serve a new member zone:
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson Set up the the member zone to be served on the master as normal.
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews This could be done by editing <code class="filename">named.conf</code>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater or by running <span class="command"><strong>rndc addzone</strong></span>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Add an entry to the catalog zone for the new member zone.
70232e6b444994979d8bab60bc9a8656ffd861e9Mark Andrews This could be done by editing the catalog zone's master file
11ba7973f989b3657cbb27447bdcdd976c71ac56Brian Wellington and running <span class="command"><strong>rndc reload</strong></span>, or by updating
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the zone using <span class="command"><strong>nsupdate</strong></span>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The change to the catalog zone will be propagated from the master to all
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater slaves using the normal AXFR/IXFR mechanism. When the slave receives the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater update to the catalog zone, it will detect the entry for the new member
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zone, create an instance of of that zone on the slave server, and point
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater that instance to the <code class="option">masters</code> specified in the catalog
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zone data. The newly created member zone is a normal slave zone, so
5ae0e2c8b72fa44237edeb37d1945b1c3535ca39Automatic Updater BIND will immediately initiate a transfer of zone contents from the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater master. Once complete, the slave will start serving the member zone.
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews Removing a member zone from a slave server requires nothing more than
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews deleting the member zone's entry in the catalog zone. The change to the
e4757e3dafe50ae59f693eec828f68c42c197a70Andreas Gustafsson catalog cone is propagated to the slave server using the normal AXFR/IXFR
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews transfer mechanism. The slave server, on processing the update, will
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater notice that the member zone has been removed. It will stop serving the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington zone and remove it froms its list of configured zones. (Removing the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater member zone from the master server has to be done in the normal way,
70232e6b444994979d8bab60bc9a8656ffd861e9Mark Andrews by editing the configuration file or running
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="command"><strong>rndc delzone</strong></span>.)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<div class="titlepage"><div><div><h3 class="title">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="id-1.5.15.5"></a>Configuring Catalog Zones</h3></div></div></div>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Catalog zones are configured with a <span class="command"><strong>catalog-zones</strong></span>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater statement in the <code class="literal">options</code> or <code class="literal">view</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater section of <code class="filename">named.conf</code>. For example,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtoncatalog-zones {
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zone "catalog.example" default-masters { 10.53.0.1; } in-memory true min-update-interval 10;
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater This statement specifies that the zone
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="literal">catalog.example</code> is a catalog zone. This zone must be
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater properly configured in the same view. In most configurations, it would
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater be a slave zone.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The <code class="option">default-masters</code> option defines the default masters
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater for member zones listed in a catalog zone. This can be overriden by
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater options within a catalog zone. If no such options are included, then
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater member zones will transfer their contents from the servers listed in
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The <code class="option">in-memory</code> option, if set to <code class="literal">yes</code>,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater causes member zones to be stored only in memory. This is functionally
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater equivalent to configuring a slave zone without a <code class="option">file</code>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater option. The default is <code class="literal">no</code>; member zones' content
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater will be stored locally in a file whose name is automatically generated
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater from the view name, catalog zone name, and member zone name.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington The <code class="option">min-update-interval</code> option sets the minimum
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater interval between processing of updates to catalog zones, in seconds.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews If an update to a catalog zone (for example, via IXFR) happens less
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews than <code class="option">min-update-interval</code> seconds after the most
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews recent update, then the changes will not be carried out until this
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews interval has elapsed. The default is <code class="literal">5</code> seconds.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews Catalog zones are defined on a per-view basis. Configuring a non-empty
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews <code class="option">catalog-zones</code> statement in a view will automatically
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews turn on <code class="option">allow-new-zones</code> for that view. (Note: this
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews means <span class="command"><strong>rndc addzone</strong></span> and <span class="command"><strong>rndc delzone</strong></span>
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews will also work in any view that supports catalog zones.)
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<div class="titlepage"><div><div><h3 class="title">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<a name="id-1.5.15.6"></a>Catalog Zone format</h3></div></div></div>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews A catalog zone is a regular DNS zone; therefore, it has to have a
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews single <code class="literal">SOA</code> and at least one <code class="literal">NS</code>
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews A record stating the version of the catalog zone format is
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews also required. If the version number listed is not supported by
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews the server, then a catalog zone may not be used by that server.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewscatalog.example. IN SOA . . 2016022901 900 600 86400 1
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrewscatalog.example. IN NS nsexample.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews Note that this record must have the domain name
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews version.<em class="replaceable"><code>catalog-zone-name</code></em>. This illustrates
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews how the meaning of data stored in a catalog zone is indicated by the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews the domain name label immediately before the catalog zone domain.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews Catalog zones can contain a set of global options that are applied to
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews all member zones, overriding the settings for the catalog zone
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews in the configuration file. Currently only the "masters" option
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews is supported:
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrewsmasters.catalog.example IN AAAA 2001:db8::1
4b2cb1422c7c600fbc13b1cb06a8b4693bc11af8Mark Andrews (Note that if more than one server is defined, the order in which
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews they are used is undefined. The above example could correspond to
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater a zone configured with
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="option">masters { 192.0.2.1; 2001:db8::1; };</code>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <code class="option">masters { 2001:db8::1; 192.0.2.1; };</code>.
34729dbcb3526974cf98ee03ec20a107d9458417Andreas Gustafsson There is currently no way to force a particular ordering.)
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater A member zone is added by including a <code class="literal">PTR</code>
34729dbcb3526974cf98ee03ec20a107d9458417Andreas Gustafsson resource record in the <code class="literal">zones</code> sub-domain of the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater catalog zone. The record label is a <code class="literal">SHA-1</code> hash
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater of the member zone name in wire format. The target of the PTR
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater record is the member zone name. For example, to add the member
34729dbcb3526974cf98ee03ec20a107d9458417Andreas Gustafsson zone <code class="literal">domain.example</code>:
34729dbcb3526974cf98ee03ec20a107d9458417Andreas Gustafsson5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example IN PTR domain.example.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater The hash is necessary to identify options for a specific member
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater zone. The member zone-specific options are defined the same way as
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater global options, but in the member zone subdomain:
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafssonmasters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example IN A 192.0.2.2
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updatermasters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example IN AAAA 2001:db8::2
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updater As would be expected, options defined for a specific zone override
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updater the global options defined in the catalog zone. These in turn override
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the global options defined in the <code class="literal">catalog-zones</code>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington statement in the configuration file.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington (Note that none of the global records an option will be inherited if
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater any records are defined for that option for the specific zone. For
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington example, if the zone had a <code class="literal">masters</code> record of type
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater A but not AAAA, then it would <span class="emphasis"><em>not</em></span> inherit the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater type AAAA record from the global option.)
992616aaf75643a0c9f84826f0a1ed5a27e84328Mark Andrews<div class="titlepage"><div><div><h2 class="title" style="clear: both">
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<a name="ipv6"></a>IPv6 Support in <acronym class="acronym">BIND</acronym> 9</h2></div></div></div>
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews <acronym class="acronym">BIND</acronym> 9 fully supports all currently
ac4e70ff8955669341f435bc0a734a17c01af124Mark Andrews defined forms of IPv6 name to address and address to name
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater lookups. It will also use IPv6 addresses to make queries when
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater running on an IPv6 capable system.
922e6a3c2ac4ef900dd9dc99f0cc137f18372583Andreas Gustafsson For forward lookups, <acronym class="acronym">BIND</acronym> 9 supports
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington only AAAA records. RFC 3363 deprecated the use of A6 records,
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updater and client-side support for A6 records was accordingly removed
aa1d397c4736cd86540555193d71e55fa3b37b2aMark Andrews from <acronym class="acronym">BIND</acronym> 9.
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updater However, authoritative <acronym class="acronym">BIND</acronym> 9 name servers still
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updater load zone files containing A6 records correctly, answer queries
2f60dbd3787caa91e8ab1d7ae39ea312ad5ba31fAutomatic Updater for A6 records, and accept zone transfer for a zone containing A6
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater For IPv6 reverse lookups, <acronym class="acronym">BIND</acronym> 9 supports
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the traditional "nibble" format used in the
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="emphasis"><em>ip6.arpa</em></span> domain, as well as the older, deprecated
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <span class="emphasis"><em>ip6.int</em></span> domain.
79207ee45ade44ff32f6ca93c5b60250bc482089Automatic Updater Older versions of <acronym class="acronym">BIND</acronym> 9
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater supported the "binary label" (also known as "bitstring") format,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater but support of binary labels has been completely removed per
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater Many applications in <acronym class="acronym">BIND</acronym> 9 do not understand
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater the binary label format at all any more, and will return an
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater error if given.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In particular, an authoritative <acronym class="acronym">BIND</acronym> 9
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater name server will not load a zone file containing binary labels.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater For an overview of the format and structure of IPv6 addresses,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater see <a class="xref" href="Bv9ARM.ch11.html#ipv6addresses" title="IPv6 addresses (AAAA)">the section called “IPv6 addresses (AAAA)”</a>.
9870509cb161e9c8d809ea2db41d371317ba2a35Automatic Updater<div class="titlepage"><div><div><h3 class="title">
992616aaf75643a0c9f84826f0a1ed5a27e84328Mark Andrews<a name="id-1.5.16.6"></a>Address Lookups Using AAAA Records</h3></div></div></div>
f9a89df8bd3cf6ae1a292dd6b122b4cf7d760314Automatic Updater The IPv6 AAAA record is a parallel to the IPv4 A record,
63d98873e29dee9608c27f40613cb69d130a56e7Mark Andrews and, unlike the deprecated A6 record, specifies the entire
6b12e2e17cc58d3abb9b232a748eac86bba0b437Automatic Updater IPv6 address in a single record. For example,
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaterhost 3600 IN AAAA 2001:db8::1
40d9598efa56a495aabe77174cdf2429f9b01764Mark Andrews Use of IPv4-in-IPv6 mapped addresses is not recommended.