1*00b67f09SDavid van Moolenbroek<!-- 2*00b67f09SDavid van Moolenbroek - Copyright (C) 2004-2015 Internet Systems Consortium, Inc. ("ISC") 3*00b67f09SDavid van Moolenbroek - Copyright (C) 2000-2003 Internet Software Consortium. 4*00b67f09SDavid van Moolenbroek - 5*00b67f09SDavid van Moolenbroek - Permission to use, copy, modify, and/or distribute this software for any 6*00b67f09SDavid van Moolenbroek - purpose with or without fee is hereby granted, provided that the above 7*00b67f09SDavid van Moolenbroek - copyright notice and this permission notice appear in all copies. 8*00b67f09SDavid van Moolenbroek - 9*00b67f09SDavid van Moolenbroek - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10*00b67f09SDavid van Moolenbroek - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11*00b67f09SDavid van Moolenbroek - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12*00b67f09SDavid van Moolenbroek - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13*00b67f09SDavid van Moolenbroek - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14*00b67f09SDavid van Moolenbroek - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15*00b67f09SDavid van Moolenbroek - PERFORMANCE OF THIS SOFTWARE. 16*00b67f09SDavid van Moolenbroek--> 17*00b67f09SDavid van Moolenbroek<!-- $Id: Bv9ARM.ch04.html,v 1.5 2015/09/03 07:33:34 christos Exp $ --> 18*00b67f09SDavid van Moolenbroek<html> 19*00b67f09SDavid van Moolenbroek<head> 20*00b67f09SDavid van Moolenbroek<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 21*00b67f09SDavid van Moolenbroek<title>Chapter�4.�Advanced DNS Features</title> 22*00b67f09SDavid van Moolenbroek<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> 23*00b67f09SDavid van Moolenbroek<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> 24*00b67f09SDavid van Moolenbroek<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> 25*00b67f09SDavid van Moolenbroek<link rel="prev" href="Bv9ARM.ch03.html" title="Chapter�3.�Name Server Configuration"> 26*00b67f09SDavid van Moolenbroek<link rel="next" href="Bv9ARM.ch05.html" title="Chapter�5.�The BIND 9 Lightweight Resolver"> 27*00b67f09SDavid van Moolenbroek</head> 28*00b67f09SDavid van Moolenbroek<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 29*00b67f09SDavid van Moolenbroek<div class="navheader"> 30*00b67f09SDavid van Moolenbroek<table width="100%" summary="Navigation header"> 31*00b67f09SDavid van Moolenbroek<tr><th colspan="3" align="center">Chapter�4.�Advanced DNS Features</th></tr> 32*00b67f09SDavid van Moolenbroek<tr> 33*00b67f09SDavid van Moolenbroek<td width="20%" align="left"> 34*00b67f09SDavid van Moolenbroek<a accesskey="p" href="Bv9ARM.ch03.html">Prev</a>�</td> 35*00b67f09SDavid van Moolenbroek<th width="60%" align="center">�</th> 36*00b67f09SDavid van Moolenbroek<td width="20%" align="right">�<a accesskey="n" href="Bv9ARM.ch05.html">Next</a> 37*00b67f09SDavid van Moolenbroek</td> 38*00b67f09SDavid van Moolenbroek</tr> 39*00b67f09SDavid van Moolenbroek</table> 40*00b67f09SDavid van Moolenbroek<hr> 41*00b67f09SDavid van Moolenbroek</div> 42*00b67f09SDavid van Moolenbroek<div class="chapter" lang="en"> 43*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title"> 44*00b67f09SDavid van Moolenbroek<a name="Bv9ARM.ch04"></a>Chapter�4.�Advanced DNS Features</h2></div></div></div> 45*00b67f09SDavid van Moolenbroek<div class="toc"> 46*00b67f09SDavid van Moolenbroek<p><b>Table of Contents</b></p> 47*00b67f09SDavid van Moolenbroek<dl> 48*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#notify">Notify</a></span></dt> 49*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#dynamic_update">Dynamic Update</a></span></dt> 50*00b67f09SDavid van Moolenbroek<dd><dl><dt><span class="sect2"><a href="Bv9ARM.ch04.html#journal">The journal file</a></span></dt></dl></dd> 51*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#incremental_zone_transfers">Incremental Zone Transfers (IXFR)</a></span></dt> 52*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#id2569920">Split DNS</a></span></dt> 53*00b67f09SDavid van Moolenbroek<dd><dl><dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2569938">Example split DNS setup</a></span></dt></dl></dd> 54*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#tsig">TSIG</a></span></dt> 55*00b67f09SDavid van Moolenbroek<dd><dl> 56*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2570439">Generate Shared Keys for Each Pair of Hosts</a></span></dt> 57*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2570581">Copying the Shared Secret to Both Machines</a></span></dt> 58*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2570592">Informing the Servers of the Key's Existence</a></span></dt> 59*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2570628">Instructing the Server to Use the Key</a></span></dt> 60*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2570685">TSIG Key Based Access Control</a></span></dt> 61*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2570734">Errors</a></span></dt> 62*00b67f09SDavid van Moolenbroek</dl></dd> 63*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#id2570748">TKEY</a></span></dt> 64*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#id2570797">SIG(0)</a></span></dt> 65*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#DNSSEC">DNSSEC</a></span></dt> 66*00b67f09SDavid van Moolenbroek<dd><dl> 67*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2570934">Generating Keys</a></span></dt> 68*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2571218">Signing the Zone</a></span></dt> 69*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2571299">Configuring Servers</a></span></dt> 70*00b67f09SDavid van Moolenbroek</dl></dd> 71*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#dnssec.dynamic.zones">DNSSEC, Dynamic Zones, and Automatic Signing</a></span></dt> 72*00b67f09SDavid van Moolenbroek<dd><dl> 73*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2611126">Converting from insecure to secure</a></span></dt> 74*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563650">Dynamic DNS update method</a></span></dt> 75*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563686">Fully automatic zone signing</a></span></dt> 76*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563933">Private-type records</a></span></dt> 77*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2582676">DNSKEY rollovers</a></span></dt> 78*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2582689">Dynamic DNS update method</a></span></dt> 79*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2582722">Automatic key rollovers</a></span></dt> 80*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2582748">NSEC3PARAM rollovers via UPDATE</a></span></dt> 81*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2582758">Converting from NSEC to NSEC3</a></span></dt> 82*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2582768">Converting from NSEC3 to NSEC</a></span></dt> 83*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2582780">Converting from secure to insecure</a></span></dt> 84*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2582818">Periodic re-signing</a></span></dt> 85*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2582827">NSEC3 and OPTOUT</a></span></dt> 86*00b67f09SDavid van Moolenbroek</dl></dd> 87*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#rfc5011.support">Dynamic Trust Anchor Management</a></span></dt> 88*00b67f09SDavid van Moolenbroek<dd><dl> 89*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2610708">Validating Resolver</a></span></dt> 90*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2610730">Authoritative Server</a></span></dt> 91*00b67f09SDavid van Moolenbroek</dl></dd> 92*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#pkcs11">PKCS#11 (Cryptoki) support</a></span></dt> 93*00b67f09SDavid van Moolenbroek<dd><dl> 94*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2666121">Prerequisites</a></span></dt> 95*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2666131">Native PKCS#11</a></span></dt> 96*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2611390">OpenSSL-based PKCS#11</a></span></dt> 97*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2638570">PKCS#11 Tools</a></span></dt> 98*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2638606">Using the HSM</a></span></dt> 99*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2638892">Specifying the engine on the command line</a></span></dt> 100*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2639009">Running named with automatic zone re-signing</a></span></dt> 101*00b67f09SDavid van Moolenbroek</dl></dd> 102*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#dlz-info">DLZ (Dynamically Loadable Zones)</a></span></dt> 103*00b67f09SDavid van Moolenbroek<dd><dl> 104*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2639074">Configuring DLZ</a></span></dt> 105*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2611909">Sample DLZ Driver</a></span></dt> 106*00b67f09SDavid van Moolenbroek</dl></dd> 107*00b67f09SDavid van Moolenbroek<dt><span class="sect1"><a href="Bv9ARM.ch04.html#id2571523">IPv6 Support in <acronym class="acronym">BIND</acronym> 9</a></span></dt> 108*00b67f09SDavid van Moolenbroek<dd><dl> 109*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2571789">Address Lookups Using AAAA Records</a></span></dt> 110*00b67f09SDavid van Moolenbroek<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2571811">Address to Name Lookups Using Nibble Format</a></span></dt> 111*00b67f09SDavid van Moolenbroek</dl></dd> 112*00b67f09SDavid van Moolenbroek</dl> 113*00b67f09SDavid van Moolenbroek</div> 114*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 115*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 116*00b67f09SDavid van Moolenbroek<a name="notify"></a>Notify</h2></div></div></div> 117*00b67f09SDavid van Moolenbroek<p> 118*00b67f09SDavid van Moolenbroek <acronym class="acronym">DNS</acronym> NOTIFY is a mechanism that allows master 119*00b67f09SDavid van Moolenbroek servers to notify their slave servers of changes to a zone's data. In 120*00b67f09SDavid van Moolenbroek response to a <span><strong class="command">NOTIFY</strong></span> from a master server, the 121*00b67f09SDavid van Moolenbroek slave will check to see that its version of the zone is the 122*00b67f09SDavid van Moolenbroek current version and, if not, initiate a zone transfer. 123*00b67f09SDavid van Moolenbroek </p> 124*00b67f09SDavid van Moolenbroek<p> 125*00b67f09SDavid van Moolenbroek For more information about <acronym class="acronym">DNS</acronym> 126*00b67f09SDavid van Moolenbroek <span><strong class="command">NOTIFY</strong></span>, see the description of the 127*00b67f09SDavid van Moolenbroek <span><strong class="command">notify</strong></span> option in <a href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a> and 128*00b67f09SDavid van Moolenbroek the description of the zone option <span><strong class="command">also-notify</strong></span> in 129*00b67f09SDavid van Moolenbroek <a href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. The <span><strong class="command">NOTIFY</strong></span> 130*00b67f09SDavid van Moolenbroek protocol is specified in RFC 1996. 131*00b67f09SDavid van Moolenbroek </p> 132*00b67f09SDavid van Moolenbroek<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 133*00b67f09SDavid van Moolenbroek<h3 class="title">Note</h3> 134*00b67f09SDavid van Moolenbroek As a slave zone can also be a master to other slaves, <span><strong class="command">named</strong></span>, 135*00b67f09SDavid van Moolenbroek by default, sends <span><strong class="command">NOTIFY</strong></span> messages for every zone 136*00b67f09SDavid van Moolenbroek it loads. Specifying <span><strong class="command">notify master-only;</strong></span> will 137*00b67f09SDavid van Moolenbroek cause <span><strong class="command">named</strong></span> to only send <span><strong class="command">NOTIFY</strong></span> for master 138*00b67f09SDavid van Moolenbroek zones that it loads. 139*00b67f09SDavid van Moolenbroek </div> 140*00b67f09SDavid van Moolenbroek</div> 141*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 142*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 143*00b67f09SDavid van Moolenbroek<a name="dynamic_update"></a>Dynamic Update</h2></div></div></div> 144*00b67f09SDavid van Moolenbroek<p> 145*00b67f09SDavid van Moolenbroek Dynamic Update is a method for adding, replacing or deleting 146*00b67f09SDavid van Moolenbroek records in a master server by sending it a special form of DNS 147*00b67f09SDavid van Moolenbroek messages. The format and meaning of these messages is specified 148*00b67f09SDavid van Moolenbroek in RFC 2136. 149*00b67f09SDavid van Moolenbroek </p> 150*00b67f09SDavid van Moolenbroek<p> 151*00b67f09SDavid van Moolenbroek Dynamic update is enabled by including an 152*00b67f09SDavid van Moolenbroek <span><strong class="command">allow-update</strong></span> or an <span><strong class="command">update-policy</strong></span> 153*00b67f09SDavid van Moolenbroek clause in the <span><strong class="command">zone</strong></span> statement. 154*00b67f09SDavid van Moolenbroek </p> 155*00b67f09SDavid van Moolenbroek<p> 156*00b67f09SDavid van Moolenbroek If the zone's <span><strong class="command">update-policy</strong></span> is set to 157*00b67f09SDavid van Moolenbroek <strong class="userinput"><code>local</code></strong>, updates to the zone 158*00b67f09SDavid van Moolenbroek will be permitted for the key <code class="varname">local-ddns</code>, 159*00b67f09SDavid van Moolenbroek which will be generated by <span><strong class="command">named</strong></span> at startup. 160*00b67f09SDavid van Moolenbroek See <a href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a> for more details. 161*00b67f09SDavid van Moolenbroek </p> 162*00b67f09SDavid van Moolenbroek<p> 163*00b67f09SDavid van Moolenbroek Dynamic updates using Kerberos signed requests can be made 164*00b67f09SDavid van Moolenbroek using the TKEY/GSS protocol by setting either the 165*00b67f09SDavid van Moolenbroek <span><strong class="command">tkey-gssapi-keytab</strong></span> option, or alternatively 166*00b67f09SDavid van Moolenbroek by setting both the <span><strong class="command">tkey-gssapi-credential</strong></span> 167*00b67f09SDavid van Moolenbroek and <span><strong class="command">tkey-domain</strong></span> options. Once enabled, 168*00b67f09SDavid van Moolenbroek Kerberos signed requests will be matched against the update 169*00b67f09SDavid van Moolenbroek policies for the zone, using the Kerberos principal as the 170*00b67f09SDavid van Moolenbroek signer for the request. 171*00b67f09SDavid van Moolenbroek </p> 172*00b67f09SDavid van Moolenbroek<p> 173*00b67f09SDavid van Moolenbroek Updating of secure zones (zones using DNSSEC) follows RFC 174*00b67f09SDavid van Moolenbroek 3007: RRSIG, NSEC and NSEC3 records affected by updates are 175*00b67f09SDavid van Moolenbroek automatically regenerated by the server using an online 176*00b67f09SDavid van Moolenbroek zone key. Update authorization is based on transaction 177*00b67f09SDavid van Moolenbroek signatures and an explicit server policy. 178*00b67f09SDavid van Moolenbroek </p> 179*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 180*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 181*00b67f09SDavid van Moolenbroek<a name="journal"></a>The journal file</h3></div></div></div> 182*00b67f09SDavid van Moolenbroek<p> 183*00b67f09SDavid van Moolenbroek All changes made to a zone using dynamic update are stored 184*00b67f09SDavid van Moolenbroek in the zone's journal file. This file is automatically created 185*00b67f09SDavid van Moolenbroek by the server when the first dynamic update takes place. 186*00b67f09SDavid van Moolenbroek The name of the journal file is formed by appending the extension 187*00b67f09SDavid van Moolenbroek <code class="filename">.jnl</code> to the name of the 188*00b67f09SDavid van Moolenbroek corresponding zone 189*00b67f09SDavid van Moolenbroek file unless specifically overridden. The journal file is in a 190*00b67f09SDavid van Moolenbroek binary format and should not be edited manually. 191*00b67f09SDavid van Moolenbroek </p> 192*00b67f09SDavid van Moolenbroek<p> 193*00b67f09SDavid van Moolenbroek The server will also occasionally write ("dump") 194*00b67f09SDavid van Moolenbroek the complete contents of the updated zone to its zone file. 195*00b67f09SDavid van Moolenbroek This is not done immediately after 196*00b67f09SDavid van Moolenbroek each dynamic update, because that would be too slow when a large 197*00b67f09SDavid van Moolenbroek zone is updated frequently. Instead, the dump is delayed by 198*00b67f09SDavid van Moolenbroek up to 15 minutes, allowing additional updates to take place. 199*00b67f09SDavid van Moolenbroek During the dump process, transient files will be created 200*00b67f09SDavid van Moolenbroek with the extensions <code class="filename">.jnw</code> and 201*00b67f09SDavid van Moolenbroek <code class="filename">.jbk</code>; under ordinary circumstances, these 202*00b67f09SDavid van Moolenbroek will be removed when the dump is complete, and can be safely 203*00b67f09SDavid van Moolenbroek ignored. 204*00b67f09SDavid van Moolenbroek </p> 205*00b67f09SDavid van Moolenbroek<p> 206*00b67f09SDavid van Moolenbroek When a server is restarted after a shutdown or crash, it will replay 207*00b67f09SDavid van Moolenbroek the journal file to incorporate into the zone any updates that 208*00b67f09SDavid van Moolenbroek took 209*00b67f09SDavid van Moolenbroek place after the last zone dump. 210*00b67f09SDavid van Moolenbroek </p> 211*00b67f09SDavid van Moolenbroek<p> 212*00b67f09SDavid van Moolenbroek Changes that result from incoming incremental zone transfers are 213*00b67f09SDavid van Moolenbroek also 214*00b67f09SDavid van Moolenbroek journalled in a similar way. 215*00b67f09SDavid van Moolenbroek </p> 216*00b67f09SDavid van Moolenbroek<p> 217*00b67f09SDavid van Moolenbroek The zone files of dynamic zones cannot normally be edited by 218*00b67f09SDavid van Moolenbroek hand because they are not guaranteed to contain the most recent 219*00b67f09SDavid van Moolenbroek dynamic changes — those are only in the journal file. 220*00b67f09SDavid van Moolenbroek The only way to ensure that the zone file of a dynamic zone 221*00b67f09SDavid van Moolenbroek is up to date is to run <span><strong class="command">rndc stop</strong></span>. 222*00b67f09SDavid van Moolenbroek </p> 223*00b67f09SDavid van Moolenbroek<p> 224*00b67f09SDavid van Moolenbroek If you have to make changes to a dynamic zone 225*00b67f09SDavid van Moolenbroek manually, the following procedure will work: 226*00b67f09SDavid van Moolenbroek Disable dynamic updates to the zone using 227*00b67f09SDavid van Moolenbroek <span><strong class="command">rndc freeze <em class="replaceable"><code>zone</code></em></strong></span>. 228*00b67f09SDavid van Moolenbroek This will update the zone's master file with the changes 229*00b67f09SDavid van Moolenbroek stored in its <code class="filename">.jnl</code> file. 230*00b67f09SDavid van Moolenbroek Edit the zone file. Run 231*00b67f09SDavid van Moolenbroek <span><strong class="command">rndc thaw <em class="replaceable"><code>zone</code></em></strong></span> 232*00b67f09SDavid van Moolenbroek to reload the changed zone and re-enable dynamic updates. 233*00b67f09SDavid van Moolenbroek </p> 234*00b67f09SDavid van Moolenbroek<p> 235*00b67f09SDavid van Moolenbroek <span><strong class="command">rndc sync <em class="replaceable"><code>zone</code></em></strong></span> 236*00b67f09SDavid van Moolenbroek will update the zone file with changes from the journal file 237*00b67f09SDavid van Moolenbroek without stopping dynamic updates; this may be useful for viewing 238*00b67f09SDavid van Moolenbroek the current zone state. To remove the <code class="filename">.jnl</code> 239*00b67f09SDavid van Moolenbroek file after updating the zone file, use 240*00b67f09SDavid van Moolenbroek <span><strong class="command">rndc sync -clean</strong></span>. 241*00b67f09SDavid van Moolenbroek </p> 242*00b67f09SDavid van Moolenbroek</div> 243*00b67f09SDavid van Moolenbroek</div> 244*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 245*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 246*00b67f09SDavid van Moolenbroek<a name="incremental_zone_transfers"></a>Incremental Zone Transfers (IXFR)</h2></div></div></div> 247*00b67f09SDavid van Moolenbroek<p> 248*00b67f09SDavid van Moolenbroek The incremental zone transfer (IXFR) protocol is a way for 249*00b67f09SDavid van Moolenbroek slave servers to transfer only changed data, instead of having to 250*00b67f09SDavid van Moolenbroek transfer the entire zone. The IXFR protocol is specified in RFC 251*00b67f09SDavid van Moolenbroek 1995. See <a href="Bv9ARM.ch11.html#proposed_standards">Proposed Standards</a>. 252*00b67f09SDavid van Moolenbroek </p> 253*00b67f09SDavid van Moolenbroek<p> 254*00b67f09SDavid van Moolenbroek When acting as a master, <acronym class="acronym">BIND</acronym> 9 255*00b67f09SDavid van Moolenbroek supports IXFR for those zones 256*00b67f09SDavid van Moolenbroek where the necessary change history information is available. These 257*00b67f09SDavid van Moolenbroek include master zones maintained by dynamic update and slave zones 258*00b67f09SDavid van Moolenbroek whose data was obtained by IXFR. For manually maintained master 259*00b67f09SDavid van Moolenbroek zones, and for slave zones obtained by performing a full zone 260*00b67f09SDavid van Moolenbroek transfer (AXFR), IXFR is supported only if the option 261*00b67f09SDavid van Moolenbroek <span><strong class="command">ixfr-from-differences</strong></span> is set 262*00b67f09SDavid van Moolenbroek to <strong class="userinput"><code>yes</code></strong>. 263*00b67f09SDavid van Moolenbroek </p> 264*00b67f09SDavid van Moolenbroek<p> 265*00b67f09SDavid van Moolenbroek When acting as a slave, <acronym class="acronym">BIND</acronym> 9 will 266*00b67f09SDavid van Moolenbroek attempt to use IXFR unless 267*00b67f09SDavid van Moolenbroek it is explicitly disabled. For more information about disabling 268*00b67f09SDavid van Moolenbroek IXFR, see the description of the <span><strong class="command">request-ixfr</strong></span> clause 269*00b67f09SDavid van Moolenbroek of the <span><strong class="command">server</strong></span> statement. 270*00b67f09SDavid van Moolenbroek </p> 271*00b67f09SDavid van Moolenbroek</div> 272*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 273*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 274*00b67f09SDavid van Moolenbroek<a name="id2569920"></a>Split DNS</h2></div></div></div> 275*00b67f09SDavid van Moolenbroek<p> 276*00b67f09SDavid van Moolenbroek Setting up different views, or visibility, of the DNS space to 277*00b67f09SDavid van Moolenbroek internal and external resolvers is usually referred to as a 278*00b67f09SDavid van Moolenbroek <span class="emphasis"><em>Split DNS</em></span> setup. There are several 279*00b67f09SDavid van Moolenbroek reasons an organization would want to set up its DNS this way. 280*00b67f09SDavid van Moolenbroek </p> 281*00b67f09SDavid van Moolenbroek<p> 282*00b67f09SDavid van Moolenbroek One common reason for setting up a DNS system this way is 283*00b67f09SDavid van Moolenbroek to hide "internal" DNS information from "external" clients on the 284*00b67f09SDavid van Moolenbroek Internet. There is some debate as to whether or not this is actually 285*00b67f09SDavid van Moolenbroek useful. 286*00b67f09SDavid van Moolenbroek Internal DNS information leaks out in many ways (via email headers, 287*00b67f09SDavid van Moolenbroek for example) and most savvy "attackers" can find the information 288*00b67f09SDavid van Moolenbroek they need using other means. 289*00b67f09SDavid van Moolenbroek However, since listing addresses of internal servers that 290*00b67f09SDavid van Moolenbroek external clients cannot possibly reach can result in 291*00b67f09SDavid van Moolenbroek connection delays and other annoyances, an organization may 292*00b67f09SDavid van Moolenbroek choose to use a Split DNS to present a consistent view of itself 293*00b67f09SDavid van Moolenbroek to the outside world. 294*00b67f09SDavid van Moolenbroek </p> 295*00b67f09SDavid van Moolenbroek<p> 296*00b67f09SDavid van Moolenbroek Another common reason for setting up a Split DNS system is 297*00b67f09SDavid van Moolenbroek to allow internal networks that are behind filters or in RFC 1918 298*00b67f09SDavid van Moolenbroek space (reserved IP space, as documented in RFC 1918) to resolve DNS 299*00b67f09SDavid van Moolenbroek on the Internet. Split DNS can also be used to allow mail from outside 300*00b67f09SDavid van Moolenbroek back in to the internal network. 301*00b67f09SDavid van Moolenbroek </p> 302*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 303*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 304*00b67f09SDavid van Moolenbroek<a name="id2569938"></a>Example split DNS setup</h3></div></div></div> 305*00b67f09SDavid van Moolenbroek<p> 306*00b67f09SDavid van Moolenbroek Let's say a company named <span class="emphasis"><em>Example, Inc.</em></span> 307*00b67f09SDavid van Moolenbroek (<code class="literal">example.com</code>) 308*00b67f09SDavid van Moolenbroek has several corporate sites that have an internal network with 309*00b67f09SDavid van Moolenbroek reserved 310*00b67f09SDavid van Moolenbroek Internet Protocol (IP) space and an external demilitarized zone (DMZ), 311*00b67f09SDavid van Moolenbroek or "outside" section of a network, that is available to the public. 312*00b67f09SDavid van Moolenbroek </p> 313*00b67f09SDavid van Moolenbroek<p> 314*00b67f09SDavid van Moolenbroek <span class="emphasis"><em>Example, Inc.</em></span> wants its internal clients 315*00b67f09SDavid van Moolenbroek to be able to resolve external hostnames and to exchange mail with 316*00b67f09SDavid van Moolenbroek people on the outside. The company also wants its internal resolvers 317*00b67f09SDavid van Moolenbroek to have access to certain internal-only zones that are not available 318*00b67f09SDavid van Moolenbroek at all outside of the internal network. 319*00b67f09SDavid van Moolenbroek </p> 320*00b67f09SDavid van Moolenbroek<p> 321*00b67f09SDavid van Moolenbroek In order to accomplish this, the company will set up two sets 322*00b67f09SDavid van Moolenbroek of name servers. One set will be on the inside network (in the 323*00b67f09SDavid van Moolenbroek reserved 324*00b67f09SDavid van Moolenbroek IP space) and the other set will be on bastion hosts, which are 325*00b67f09SDavid van Moolenbroek "proxy" 326*00b67f09SDavid van Moolenbroek hosts that can talk to both sides of its network, in the DMZ. 327*00b67f09SDavid van Moolenbroek </p> 328*00b67f09SDavid van Moolenbroek<p> 329*00b67f09SDavid van Moolenbroek The internal servers will be configured to forward all queries, 330*00b67f09SDavid van Moolenbroek except queries for <code class="filename">site1.internal</code>, <code class="filename">site2.internal</code>, <code class="filename">site1.example.com</code>, 331*00b67f09SDavid van Moolenbroek and <code class="filename">site2.example.com</code>, to the servers 332*00b67f09SDavid van Moolenbroek in the 333*00b67f09SDavid van Moolenbroek DMZ. These internal servers will have complete sets of information 334*00b67f09SDavid van Moolenbroek for <code class="filename">site1.example.com</code>, <code class="filename">site2.example.com</code>, <code class="filename">site1.internal</code>, 335*00b67f09SDavid van Moolenbroek and <code class="filename">site2.internal</code>. 336*00b67f09SDavid van Moolenbroek </p> 337*00b67f09SDavid van Moolenbroek<p> 338*00b67f09SDavid van Moolenbroek To protect the <code class="filename">site1.internal</code> and <code class="filename">site2.internal</code> domains, 339*00b67f09SDavid van Moolenbroek the internal name servers must be configured to disallow all queries 340*00b67f09SDavid van Moolenbroek to these domains from any external hosts, including the bastion 341*00b67f09SDavid van Moolenbroek hosts. 342*00b67f09SDavid van Moolenbroek </p> 343*00b67f09SDavid van Moolenbroek<p> 344*00b67f09SDavid van Moolenbroek The external servers, which are on the bastion hosts, will 345*00b67f09SDavid van Moolenbroek be configured to serve the "public" version of the <code class="filename">site1</code> and <code class="filename">site2.example.com</code> zones. 346*00b67f09SDavid van Moolenbroek This could include things such as the host records for public servers 347*00b67f09SDavid van Moolenbroek (<code class="filename">www.example.com</code> and <code class="filename">ftp.example.com</code>), 348*00b67f09SDavid van Moolenbroek and mail exchange (MX) records (<code class="filename">a.mx.example.com</code> and <code class="filename">b.mx.example.com</code>). 349*00b67f09SDavid van Moolenbroek </p> 350*00b67f09SDavid van Moolenbroek<p> 351*00b67f09SDavid van Moolenbroek In addition, the public <code class="filename">site1</code> and <code class="filename">site2.example.com</code> zones 352*00b67f09SDavid van Moolenbroek should have special MX records that contain wildcard (`*') records 353*00b67f09SDavid van Moolenbroek pointing to the bastion hosts. This is needed because external mail 354*00b67f09SDavid van Moolenbroek servers do not have any other way of looking up how to deliver mail 355*00b67f09SDavid van Moolenbroek to those internal hosts. With the wildcard records, the mail will 356*00b67f09SDavid van Moolenbroek be delivered to the bastion host, which can then forward it on to 357*00b67f09SDavid van Moolenbroek internal hosts. 358*00b67f09SDavid van Moolenbroek </p> 359*00b67f09SDavid van Moolenbroek<p> 360*00b67f09SDavid van Moolenbroek Here's an example of a wildcard MX record: 361*00b67f09SDavid van Moolenbroek </p> 362*00b67f09SDavid van Moolenbroek<pre class="programlisting">* IN MX 10 external1.example.com.</pre> 363*00b67f09SDavid van Moolenbroek<p> 364*00b67f09SDavid van Moolenbroek Now that they accept mail on behalf of anything in the internal 365*00b67f09SDavid van Moolenbroek network, the bastion hosts will need to know how to deliver mail 366*00b67f09SDavid van Moolenbroek to internal hosts. In order for this to work properly, the resolvers 367*00b67f09SDavid van Moolenbroek on 368*00b67f09SDavid van Moolenbroek the bastion hosts will need to be configured to point to the internal 369*00b67f09SDavid van Moolenbroek name servers for DNS resolution. 370*00b67f09SDavid van Moolenbroek </p> 371*00b67f09SDavid van Moolenbroek<p> 372*00b67f09SDavid van Moolenbroek Queries for internal hostnames will be answered by the internal 373*00b67f09SDavid van Moolenbroek servers, and queries for external hostnames will be forwarded back 374*00b67f09SDavid van Moolenbroek out to the DNS servers on the bastion hosts. 375*00b67f09SDavid van Moolenbroek </p> 376*00b67f09SDavid van Moolenbroek<p> 377*00b67f09SDavid van Moolenbroek In order for all this to work properly, internal clients will 378*00b67f09SDavid van Moolenbroek need to be configured to query <span class="emphasis"><em>only</em></span> the internal 379*00b67f09SDavid van Moolenbroek name servers for DNS queries. This could also be enforced via 380*00b67f09SDavid van Moolenbroek selective 381*00b67f09SDavid van Moolenbroek filtering on the network. 382*00b67f09SDavid van Moolenbroek </p> 383*00b67f09SDavid van Moolenbroek<p> 384*00b67f09SDavid van Moolenbroek If everything has been set properly, <span class="emphasis"><em>Example, Inc.</em></span>'s 385*00b67f09SDavid van Moolenbroek internal clients will now be able to: 386*00b67f09SDavid van Moolenbroek </p> 387*00b67f09SDavid van Moolenbroek<div class="itemizedlist"><ul type="disc"> 388*00b67f09SDavid van Moolenbroek<li> 389*00b67f09SDavid van Moolenbroek Look up any hostnames in the <code class="literal">site1</code> 390*00b67f09SDavid van Moolenbroek and 391*00b67f09SDavid van Moolenbroek <code class="literal">site2.example.com</code> zones. 392*00b67f09SDavid van Moolenbroek </li> 393*00b67f09SDavid van Moolenbroek<li> 394*00b67f09SDavid van Moolenbroek Look up any hostnames in the <code class="literal">site1.internal</code> and 395*00b67f09SDavid van Moolenbroek <code class="literal">site2.internal</code> domains. 396*00b67f09SDavid van Moolenbroek </li> 397*00b67f09SDavid van Moolenbroek<li>Look up any hostnames on the Internet.</li> 398*00b67f09SDavid van Moolenbroek<li>Exchange mail with both internal and external people.</li> 399*00b67f09SDavid van Moolenbroek</ul></div> 400*00b67f09SDavid van Moolenbroek<p> 401*00b67f09SDavid van Moolenbroek Hosts on the Internet will be able to: 402*00b67f09SDavid van Moolenbroek </p> 403*00b67f09SDavid van Moolenbroek<div class="itemizedlist"><ul type="disc"> 404*00b67f09SDavid van Moolenbroek<li> 405*00b67f09SDavid van Moolenbroek Look up any hostnames in the <code class="literal">site1</code> 406*00b67f09SDavid van Moolenbroek and 407*00b67f09SDavid van Moolenbroek <code class="literal">site2.example.com</code> zones. 408*00b67f09SDavid van Moolenbroek </li> 409*00b67f09SDavid van Moolenbroek<li> 410*00b67f09SDavid van Moolenbroek Exchange mail with anyone in the <code class="literal">site1</code> and 411*00b67f09SDavid van Moolenbroek <code class="literal">site2.example.com</code> zones. 412*00b67f09SDavid van Moolenbroek </li> 413*00b67f09SDavid van Moolenbroek</ul></div> 414*00b67f09SDavid van Moolenbroek<p> 415*00b67f09SDavid van Moolenbroek Here is an example configuration for the setup we just 416*00b67f09SDavid van Moolenbroek described above. Note that this is only configuration information; 417*00b67f09SDavid van Moolenbroek for information on how to configure your zone files, see <a href="Bv9ARM.ch03.html#sample_configuration" title="Sample Configurations">the section called “Sample Configurations”</a>. 418*00b67f09SDavid van Moolenbroek </p> 419*00b67f09SDavid van Moolenbroek<p> 420*00b67f09SDavid van Moolenbroek Internal DNS server config: 421*00b67f09SDavid van Moolenbroek </p> 422*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 423*00b67f09SDavid van Moolenbroek 424*00b67f09SDavid van Moolenbroekacl internals { 172.16.72.0/24; 192.168.1.0/24; }; 425*00b67f09SDavid van Moolenbroek 426*00b67f09SDavid van Moolenbroekacl externals { <code class="varname">bastion-ips-go-here</code>; }; 427*00b67f09SDavid van Moolenbroek 428*00b67f09SDavid van Moolenbroekoptions { 429*00b67f09SDavid van Moolenbroek ... 430*00b67f09SDavid van Moolenbroek ... 431*00b67f09SDavid van Moolenbroek forward only; 432*00b67f09SDavid van Moolenbroek // forward to external servers 433*00b67f09SDavid van Moolenbroek forwarders { 434*00b67f09SDavid van Moolenbroek <code class="varname">bastion-ips-go-here</code>; 435*00b67f09SDavid van Moolenbroek }; 436*00b67f09SDavid van Moolenbroek // sample allow-transfer (no one) 437*00b67f09SDavid van Moolenbroek allow-transfer { none; }; 438*00b67f09SDavid van Moolenbroek // restrict query access 439*00b67f09SDavid van Moolenbroek allow-query { internals; externals; }; 440*00b67f09SDavid van Moolenbroek // restrict recursion 441*00b67f09SDavid van Moolenbroek allow-recursion { internals; }; 442*00b67f09SDavid van Moolenbroek ... 443*00b67f09SDavid van Moolenbroek ... 444*00b67f09SDavid van Moolenbroek}; 445*00b67f09SDavid van Moolenbroek 446*00b67f09SDavid van Moolenbroek// sample master zone 447*00b67f09SDavid van Moolenbroekzone "site1.example.com" { 448*00b67f09SDavid van Moolenbroek type master; 449*00b67f09SDavid van Moolenbroek file "m/site1.example.com"; 450*00b67f09SDavid van Moolenbroek // do normal iterative resolution (do not forward) 451*00b67f09SDavid van Moolenbroek forwarders { }; 452*00b67f09SDavid van Moolenbroek allow-query { internals; externals; }; 453*00b67f09SDavid van Moolenbroek allow-transfer { internals; }; 454*00b67f09SDavid van Moolenbroek}; 455*00b67f09SDavid van Moolenbroek 456*00b67f09SDavid van Moolenbroek// sample slave zone 457*00b67f09SDavid van Moolenbroekzone "site2.example.com" { 458*00b67f09SDavid van Moolenbroek type slave; 459*00b67f09SDavid van Moolenbroek file "s/site2.example.com"; 460*00b67f09SDavid van Moolenbroek masters { 172.16.72.3; }; 461*00b67f09SDavid van Moolenbroek forwarders { }; 462*00b67f09SDavid van Moolenbroek allow-query { internals; externals; }; 463*00b67f09SDavid van Moolenbroek allow-transfer { internals; }; 464*00b67f09SDavid van Moolenbroek}; 465*00b67f09SDavid van Moolenbroek 466*00b67f09SDavid van Moolenbroekzone "site1.internal" { 467*00b67f09SDavid van Moolenbroek type master; 468*00b67f09SDavid van Moolenbroek file "m/site1.internal"; 469*00b67f09SDavid van Moolenbroek forwarders { }; 470*00b67f09SDavid van Moolenbroek allow-query { internals; }; 471*00b67f09SDavid van Moolenbroek allow-transfer { internals; } 472*00b67f09SDavid van Moolenbroek}; 473*00b67f09SDavid van Moolenbroek 474*00b67f09SDavid van Moolenbroekzone "site2.internal" { 475*00b67f09SDavid van Moolenbroek type slave; 476*00b67f09SDavid van Moolenbroek file "s/site2.internal"; 477*00b67f09SDavid van Moolenbroek masters { 172.16.72.3; }; 478*00b67f09SDavid van Moolenbroek forwarders { }; 479*00b67f09SDavid van Moolenbroek allow-query { internals }; 480*00b67f09SDavid van Moolenbroek allow-transfer { internals; } 481*00b67f09SDavid van Moolenbroek}; 482*00b67f09SDavid van Moolenbroek</pre> 483*00b67f09SDavid van Moolenbroek<p> 484*00b67f09SDavid van Moolenbroek External (bastion host) DNS server config: 485*00b67f09SDavid van Moolenbroek </p> 486*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 487*00b67f09SDavid van Moolenbroekacl internals { 172.16.72.0/24; 192.168.1.0/24; }; 488*00b67f09SDavid van Moolenbroek 489*00b67f09SDavid van Moolenbroekacl externals { bastion-ips-go-here; }; 490*00b67f09SDavid van Moolenbroek 491*00b67f09SDavid van Moolenbroekoptions { 492*00b67f09SDavid van Moolenbroek ... 493*00b67f09SDavid van Moolenbroek ... 494*00b67f09SDavid van Moolenbroek // sample allow-transfer (no one) 495*00b67f09SDavid van Moolenbroek allow-transfer { none; }; 496*00b67f09SDavid van Moolenbroek // default query access 497*00b67f09SDavid van Moolenbroek allow-query { any; }; 498*00b67f09SDavid van Moolenbroek // restrict cache access 499*00b67f09SDavid van Moolenbroek allow-query-cache { internals; externals; }; 500*00b67f09SDavid van Moolenbroek // restrict recursion 501*00b67f09SDavid van Moolenbroek allow-recursion { internals; externals; }; 502*00b67f09SDavid van Moolenbroek ... 503*00b67f09SDavid van Moolenbroek ... 504*00b67f09SDavid van Moolenbroek}; 505*00b67f09SDavid van Moolenbroek 506*00b67f09SDavid van Moolenbroek// sample slave zone 507*00b67f09SDavid van Moolenbroekzone "site1.example.com" { 508*00b67f09SDavid van Moolenbroek type master; 509*00b67f09SDavid van Moolenbroek file "m/site1.foo.com"; 510*00b67f09SDavid van Moolenbroek allow-transfer { internals; externals; }; 511*00b67f09SDavid van Moolenbroek}; 512*00b67f09SDavid van Moolenbroek 513*00b67f09SDavid van Moolenbroekzone "site2.example.com" { 514*00b67f09SDavid van Moolenbroek type slave; 515*00b67f09SDavid van Moolenbroek file "s/site2.foo.com"; 516*00b67f09SDavid van Moolenbroek masters { another_bastion_host_maybe; }; 517*00b67f09SDavid van Moolenbroek allow-transfer { internals; externals; } 518*00b67f09SDavid van Moolenbroek}; 519*00b67f09SDavid van Moolenbroek</pre> 520*00b67f09SDavid van Moolenbroek<p> 521*00b67f09SDavid van Moolenbroek In the <code class="filename">resolv.conf</code> (or equivalent) on 522*00b67f09SDavid van Moolenbroek the bastion host(s): 523*00b67f09SDavid van Moolenbroek </p> 524*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 525*00b67f09SDavid van Moolenbroeksearch ... 526*00b67f09SDavid van Moolenbroeknameserver 172.16.72.2 527*00b67f09SDavid van Moolenbroeknameserver 172.16.72.3 528*00b67f09SDavid van Moolenbroeknameserver 172.16.72.4 529*00b67f09SDavid van Moolenbroek</pre> 530*00b67f09SDavid van Moolenbroek</div> 531*00b67f09SDavid van Moolenbroek</div> 532*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 533*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 534*00b67f09SDavid van Moolenbroek<a name="tsig"></a>TSIG</h2></div></div></div> 535*00b67f09SDavid van Moolenbroek<p> 536*00b67f09SDavid van Moolenbroek This is a short guide to setting up Transaction SIGnatures 537*00b67f09SDavid van Moolenbroek (TSIG) based transaction security in <acronym class="acronym">BIND</acronym>. It describes changes 538*00b67f09SDavid van Moolenbroek to the configuration file as well as what changes are required for 539*00b67f09SDavid van Moolenbroek different features, including the process of creating transaction 540*00b67f09SDavid van Moolenbroek keys and using transaction signatures with <acronym class="acronym">BIND</acronym>. 541*00b67f09SDavid van Moolenbroek </p> 542*00b67f09SDavid van Moolenbroek<p> 543*00b67f09SDavid van Moolenbroek <acronym class="acronym">BIND</acronym> primarily supports TSIG for server 544*00b67f09SDavid van Moolenbroek to server communication. 545*00b67f09SDavid van Moolenbroek This includes zone transfer, notify, and recursive query messages. 546*00b67f09SDavid van Moolenbroek Resolvers based on newer versions of <acronym class="acronym">BIND</acronym> 8 have limited support 547*00b67f09SDavid van Moolenbroek for TSIG. 548*00b67f09SDavid van Moolenbroek </p> 549*00b67f09SDavid van Moolenbroek<p> 550*00b67f09SDavid van Moolenbroek TSIG can also be useful for dynamic update. A primary 551*00b67f09SDavid van Moolenbroek server for a dynamic zone should control access to the dynamic 552*00b67f09SDavid van Moolenbroek update service, but IP-based access control is insufficient. 553*00b67f09SDavid van Moolenbroek The cryptographic access control provided by TSIG 554*00b67f09SDavid van Moolenbroek is far superior. The <span><strong class="command">nsupdate</strong></span> 555*00b67f09SDavid van Moolenbroek program supports TSIG via the <code class="option">-k</code> and 556*00b67f09SDavid van Moolenbroek <code class="option">-y</code> command line options or inline by use 557*00b67f09SDavid van Moolenbroek of the <span><strong class="command">key</strong></span>. 558*00b67f09SDavid van Moolenbroek </p> 559*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 560*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 561*00b67f09SDavid van Moolenbroek<a name="id2570439"></a>Generate Shared Keys for Each Pair of Hosts</h3></div></div></div> 562*00b67f09SDavid van Moolenbroek<p> 563*00b67f09SDavid van Moolenbroek A shared secret is generated to be shared between <span class="emphasis"><em>host1</em></span> and <span class="emphasis"><em>host2</em></span>. 564*00b67f09SDavid van Moolenbroek An arbitrary key name is chosen: "host1-host2.". The key name must 565*00b67f09SDavid van Moolenbroek be the same on both hosts. 566*00b67f09SDavid van Moolenbroek </p> 567*00b67f09SDavid van Moolenbroek<div class="sect3" lang="en"> 568*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h4 class="title"> 569*00b67f09SDavid van Moolenbroek<a name="id2570524"></a>Automatic Generation</h4></div></div></div> 570*00b67f09SDavid van Moolenbroek<p> 571*00b67f09SDavid van Moolenbroek The following command will generate a 128-bit (16 byte) HMAC-SHA256 572*00b67f09SDavid van Moolenbroek key as described above. Longer keys are better, but shorter keys 573*00b67f09SDavid van Moolenbroek are easier to read. Note that the maximum key length is the digest 574*00b67f09SDavid van Moolenbroek length, here 256 bits. 575*00b67f09SDavid van Moolenbroek </p> 576*00b67f09SDavid van Moolenbroek<p> 577*00b67f09SDavid van Moolenbroek <strong class="userinput"><code>dnssec-keygen -a hmac-sha256 -b 128 -n HOST host1-host2.</code></strong> 578*00b67f09SDavid van Moolenbroek </p> 579*00b67f09SDavid van Moolenbroek<p> 580*00b67f09SDavid van Moolenbroek The key is in the file <code class="filename">Khost1-host2.+163+00000.private</code>. 581*00b67f09SDavid van Moolenbroek Nothing directly uses this file, but the base-64 encoded string 582*00b67f09SDavid van Moolenbroek following "<code class="literal">Key:</code>" 583*00b67f09SDavid van Moolenbroek can be extracted from the file and used as a shared secret: 584*00b67f09SDavid van Moolenbroek </p> 585*00b67f09SDavid van Moolenbroek<pre class="programlisting">Key: La/E5CjG9O+os1jq0a2jdA==</pre> 586*00b67f09SDavid van Moolenbroek<p> 587*00b67f09SDavid van Moolenbroek The string "<code class="literal">La/E5CjG9O+os1jq0a2jdA==</code>" can 588*00b67f09SDavid van Moolenbroek be used as the shared secret. 589*00b67f09SDavid van Moolenbroek </p> 590*00b67f09SDavid van Moolenbroek</div> 591*00b67f09SDavid van Moolenbroek<div class="sect3" lang="en"> 592*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h4 class="title"> 593*00b67f09SDavid van Moolenbroek<a name="id2570563"></a>Manual Generation</h4></div></div></div> 594*00b67f09SDavid van Moolenbroek<p> 595*00b67f09SDavid van Moolenbroek The shared secret is simply a random sequence of bits, encoded 596*00b67f09SDavid van Moolenbroek in base-64. Most ASCII strings are valid base-64 strings (assuming 597*00b67f09SDavid van Moolenbroek the length is a multiple of 4 and only valid characters are used), 598*00b67f09SDavid van Moolenbroek so the shared secret can be manually generated. 599*00b67f09SDavid van Moolenbroek </p> 600*00b67f09SDavid van Moolenbroek<p> 601*00b67f09SDavid van Moolenbroek Also, a known string can be run through <span><strong class="command">mmencode</strong></span> or 602*00b67f09SDavid van Moolenbroek a similar program to generate base-64 encoded data. 603*00b67f09SDavid van Moolenbroek </p> 604*00b67f09SDavid van Moolenbroek</div> 605*00b67f09SDavid van Moolenbroek</div> 606*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 607*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 608*00b67f09SDavid van Moolenbroek<a name="id2570581"></a>Copying the Shared Secret to Both Machines</h3></div></div></div> 609*00b67f09SDavid van Moolenbroek<p> 610*00b67f09SDavid van Moolenbroek This is beyond the scope of DNS. A secure transport mechanism 611*00b67f09SDavid van Moolenbroek should be used. This could be secure FTP, ssh, telephone, etc. 612*00b67f09SDavid van Moolenbroek </p> 613*00b67f09SDavid van Moolenbroek</div> 614*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 615*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 616*00b67f09SDavid van Moolenbroek<a name="id2570592"></a>Informing the Servers of the Key's Existence</h3></div></div></div> 617*00b67f09SDavid van Moolenbroek<p> 618*00b67f09SDavid van Moolenbroek Imagine <span class="emphasis"><em>host1</em></span> and <span class="emphasis"><em>host 2</em></span> 619*00b67f09SDavid van Moolenbroek are 620*00b67f09SDavid van Moolenbroek both servers. The following is added to each server's <code class="filename">named.conf</code> file: 621*00b67f09SDavid van Moolenbroek </p> 622*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 623*00b67f09SDavid van Moolenbroekkey host1-host2. { 624*00b67f09SDavid van Moolenbroek algorithm hmac-sha256; 625*00b67f09SDavid van Moolenbroek secret "La/E5CjG9O+os1jq0a2jdA=="; 626*00b67f09SDavid van Moolenbroek}; 627*00b67f09SDavid van Moolenbroek</pre> 628*00b67f09SDavid van Moolenbroek<p> 629*00b67f09SDavid van Moolenbroek The secret is the one generated above. Since this is a secret, it 630*00b67f09SDavid van Moolenbroek is recommended that either <code class="filename">named.conf</code> be 631*00b67f09SDavid van Moolenbroek non-world readable, or the key directive be added to a non-world 632*00b67f09SDavid van Moolenbroek readable file that is included by <code class="filename">named.conf</code>. 633*00b67f09SDavid van Moolenbroek </p> 634*00b67f09SDavid van Moolenbroek<p> 635*00b67f09SDavid van Moolenbroek At this point, the key is recognized. This means that if the 636*00b67f09SDavid van Moolenbroek server receives a message signed by this key, it can verify the 637*00b67f09SDavid van Moolenbroek signature. If the signature is successfully verified, the 638*00b67f09SDavid van Moolenbroek response is signed by the same key. 639*00b67f09SDavid van Moolenbroek </p> 640*00b67f09SDavid van Moolenbroek</div> 641*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 642*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 643*00b67f09SDavid van Moolenbroek<a name="id2570628"></a>Instructing the Server to Use the Key</h3></div></div></div> 644*00b67f09SDavid van Moolenbroek<p> 645*00b67f09SDavid van Moolenbroek Since keys are shared between two hosts only, the server must 646*00b67f09SDavid van Moolenbroek be told when keys are to be used. The following is added to the <code class="filename">named.conf</code> file 647*00b67f09SDavid van Moolenbroek for <span class="emphasis"><em>host1</em></span>, if the IP address of <span class="emphasis"><em>host2</em></span> is 648*00b67f09SDavid van Moolenbroek 10.1.2.3: 649*00b67f09SDavid van Moolenbroek </p> 650*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 651*00b67f09SDavid van Moolenbroekserver 10.1.2.3 { 652*00b67f09SDavid van Moolenbroek keys { host1-host2. ;}; 653*00b67f09SDavid van Moolenbroek}; 654*00b67f09SDavid van Moolenbroek</pre> 655*00b67f09SDavid van Moolenbroek<p> 656*00b67f09SDavid van Moolenbroek Multiple keys may be present, but only the first is used. 657*00b67f09SDavid van Moolenbroek This directive does not contain any secrets, so it may be in a 658*00b67f09SDavid van Moolenbroek world-readable 659*00b67f09SDavid van Moolenbroek file. 660*00b67f09SDavid van Moolenbroek </p> 661*00b67f09SDavid van Moolenbroek<p> 662*00b67f09SDavid van Moolenbroek If <span class="emphasis"><em>host1</em></span> sends a message that is a request 663*00b67f09SDavid van Moolenbroek to that address, the message will be signed with the specified key. <span class="emphasis"><em>host1</em></span> will 664*00b67f09SDavid van Moolenbroek expect any responses to signed messages to be signed with the same 665*00b67f09SDavid van Moolenbroek key. 666*00b67f09SDavid van Moolenbroek </p> 667*00b67f09SDavid van Moolenbroek<p> 668*00b67f09SDavid van Moolenbroek A similar statement must be present in <span class="emphasis"><em>host2</em></span>'s 669*00b67f09SDavid van Moolenbroek configuration file (with <span class="emphasis"><em>host1</em></span>'s address) for <span class="emphasis"><em>host2</em></span> to 670*00b67f09SDavid van Moolenbroek sign request messages to <span class="emphasis"><em>host1</em></span>. 671*00b67f09SDavid van Moolenbroek </p> 672*00b67f09SDavid van Moolenbroek</div> 673*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 674*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 675*00b67f09SDavid van Moolenbroek<a name="id2570685"></a>TSIG Key Based Access Control</h3></div></div></div> 676*00b67f09SDavid van Moolenbroek<p> 677*00b67f09SDavid van Moolenbroek <acronym class="acronym">BIND</acronym> allows IP addresses and ranges 678*00b67f09SDavid van Moolenbroek to be specified in ACL 679*00b67f09SDavid van Moolenbroek definitions and 680*00b67f09SDavid van Moolenbroek <span><strong class="command">allow-{ query | transfer | update }</strong></span> 681*00b67f09SDavid van Moolenbroek directives. 682*00b67f09SDavid van Moolenbroek This has been extended to allow TSIG keys also. The above key would 683*00b67f09SDavid van Moolenbroek be denoted <span><strong class="command">key host1-host2.</strong></span> 684*00b67f09SDavid van Moolenbroek </p> 685*00b67f09SDavid van Moolenbroek<p> 686*00b67f09SDavid van Moolenbroek An example of an <span><strong class="command">allow-update</strong></span> directive would be: 687*00b67f09SDavid van Moolenbroek </p> 688*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 689*00b67f09SDavid van Moolenbroekallow-update { key host1-host2. ;}; 690*00b67f09SDavid van Moolenbroek</pre> 691*00b67f09SDavid van Moolenbroek<p> 692*00b67f09SDavid van Moolenbroek This allows dynamic updates to succeed only if the request 693*00b67f09SDavid van Moolenbroek was signed by a key named "<span><strong class="command">host1-host2.</strong></span>". 694*00b67f09SDavid van Moolenbroek </p> 695*00b67f09SDavid van Moolenbroek<p> 696*00b67f09SDavid van Moolenbroek See <a href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a> for a discussion of 697*00b67f09SDavid van Moolenbroek the more flexible <span><strong class="command">update-policy</strong></span> statement. 698*00b67f09SDavid van Moolenbroek </p> 699*00b67f09SDavid van Moolenbroek</div> 700*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 701*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 702*00b67f09SDavid van Moolenbroek<a name="id2570734"></a>Errors</h3></div></div></div> 703*00b67f09SDavid van Moolenbroek<p> 704*00b67f09SDavid van Moolenbroek The processing of TSIG signed messages can result in 705*00b67f09SDavid van Moolenbroek several errors. If a signed message is sent to a non-TSIG aware 706*00b67f09SDavid van Moolenbroek server, a FORMERR (format error) will be returned, since the server will not 707*00b67f09SDavid van Moolenbroek understand the record. This is a result of misconfiguration, 708*00b67f09SDavid van Moolenbroek since the server must be explicitly configured to send a TSIG 709*00b67f09SDavid van Moolenbroek signed message to a specific server. 710*00b67f09SDavid van Moolenbroek </p> 711*00b67f09SDavid van Moolenbroek<p> 712*00b67f09SDavid van Moolenbroek If a TSIG aware server receives a message signed by an 713*00b67f09SDavid van Moolenbroek unknown key, the response will be unsigned with the TSIG 714*00b67f09SDavid van Moolenbroek extended error code set to BADKEY. If a TSIG aware server 715*00b67f09SDavid van Moolenbroek receives a message with a signature that does not validate, the 716*00b67f09SDavid van Moolenbroek response will be unsigned with the TSIG extended error code set 717*00b67f09SDavid van Moolenbroek to BADSIG. If a TSIG aware server receives a message with a time 718*00b67f09SDavid van Moolenbroek outside of the allowed range, the response will be signed with 719*00b67f09SDavid van Moolenbroek the TSIG extended error code set to BADTIME, and the time values 720*00b67f09SDavid van Moolenbroek will be adjusted so that the response can be successfully 721*00b67f09SDavid van Moolenbroek verified. In any of these cases, the message's rcode (response code) is set to 722*00b67f09SDavid van Moolenbroek NOTAUTH (not authenticated). 723*00b67f09SDavid van Moolenbroek </p> 724*00b67f09SDavid van Moolenbroek</div> 725*00b67f09SDavid van Moolenbroek</div> 726*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 727*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 728*00b67f09SDavid van Moolenbroek<a name="id2570748"></a>TKEY</h2></div></div></div> 729*00b67f09SDavid van Moolenbroek<p><span><strong class="command">TKEY</strong></span> 730*00b67f09SDavid van Moolenbroek is a mechanism for automatically generating a shared secret 731*00b67f09SDavid van Moolenbroek between two hosts. There are several "modes" of 732*00b67f09SDavid van Moolenbroek <span><strong class="command">TKEY</strong></span> that specify how the key is generated 733*00b67f09SDavid van Moolenbroek or assigned. <acronym class="acronym">BIND</acronym> 9 implements only one of 734*00b67f09SDavid van Moolenbroek these modes, the Diffie-Hellman key exchange. Both hosts are 735*00b67f09SDavid van Moolenbroek required to have a Diffie-Hellman KEY record (although this 736*00b67f09SDavid van Moolenbroek record is not required to be present in a zone). The 737*00b67f09SDavid van Moolenbroek <span><strong class="command">TKEY</strong></span> process must use signed messages, 738*00b67f09SDavid van Moolenbroek signed either by TSIG or SIG(0). The result of 739*00b67f09SDavid van Moolenbroek <span><strong class="command">TKEY</strong></span> is a shared secret that can be used to 740*00b67f09SDavid van Moolenbroek sign messages with TSIG. <span><strong class="command">TKEY</strong></span> can also be 741*00b67f09SDavid van Moolenbroek used to delete shared secrets that it had previously 742*00b67f09SDavid van Moolenbroek generated. 743*00b67f09SDavid van Moolenbroek </p> 744*00b67f09SDavid van Moolenbroek<p> 745*00b67f09SDavid van Moolenbroek The <span><strong class="command">TKEY</strong></span> process is initiated by a 746*00b67f09SDavid van Moolenbroek client 747*00b67f09SDavid van Moolenbroek or server by sending a signed <span><strong class="command">TKEY</strong></span> 748*00b67f09SDavid van Moolenbroek query 749*00b67f09SDavid van Moolenbroek (including any appropriate KEYs) to a TKEY-aware server. The 750*00b67f09SDavid van Moolenbroek server response, if it indicates success, will contain a 751*00b67f09SDavid van Moolenbroek <span><strong class="command">TKEY</strong></span> record and any appropriate keys. 752*00b67f09SDavid van Moolenbroek After 753*00b67f09SDavid van Moolenbroek this exchange, both participants have enough information to 754*00b67f09SDavid van Moolenbroek determine the shared secret; the exact process depends on the 755*00b67f09SDavid van Moolenbroek <span><strong class="command">TKEY</strong></span> mode. When using the 756*00b67f09SDavid van Moolenbroek Diffie-Hellman 757*00b67f09SDavid van Moolenbroek <span><strong class="command">TKEY</strong></span> mode, Diffie-Hellman keys are 758*00b67f09SDavid van Moolenbroek exchanged, 759*00b67f09SDavid van Moolenbroek and the shared secret is derived by both participants. 760*00b67f09SDavid van Moolenbroek </p> 761*00b67f09SDavid van Moolenbroek</div> 762*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 763*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 764*00b67f09SDavid van Moolenbroek<a name="id2570797"></a>SIG(0)</h2></div></div></div> 765*00b67f09SDavid van Moolenbroek<p> 766*00b67f09SDavid van Moolenbroek <acronym class="acronym">BIND</acronym> 9 partially supports DNSSEC SIG(0) 767*00b67f09SDavid van Moolenbroek transaction signatures as specified in RFC 2535 and RFC 2931. 768*00b67f09SDavid van Moolenbroek SIG(0) 769*00b67f09SDavid van Moolenbroek uses public/private keys to authenticate messages. Access control 770*00b67f09SDavid van Moolenbroek is performed in the same manner as TSIG keys; privileges can be 771*00b67f09SDavid van Moolenbroek granted or denied based on the key name. 772*00b67f09SDavid van Moolenbroek </p> 773*00b67f09SDavid van Moolenbroek<p> 774*00b67f09SDavid van Moolenbroek When a SIG(0) signed message is received, it will only be 775*00b67f09SDavid van Moolenbroek verified if the key is known and trusted by the server; the server 776*00b67f09SDavid van Moolenbroek will not attempt to locate and/or validate the key. 777*00b67f09SDavid van Moolenbroek </p> 778*00b67f09SDavid van Moolenbroek<p> 779*00b67f09SDavid van Moolenbroek SIG(0) signing of multiple-message TCP streams is not 780*00b67f09SDavid van Moolenbroek supported. 781*00b67f09SDavid van Moolenbroek </p> 782*00b67f09SDavid van Moolenbroek<p> 783*00b67f09SDavid van Moolenbroek The only tool shipped with <acronym class="acronym">BIND</acronym> 9 that 784*00b67f09SDavid van Moolenbroek generates SIG(0) signed messages is <span><strong class="command">nsupdate</strong></span>. 785*00b67f09SDavid van Moolenbroek </p> 786*00b67f09SDavid van Moolenbroek</div> 787*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 788*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 789*00b67f09SDavid van Moolenbroek<a name="DNSSEC"></a>DNSSEC</h2></div></div></div> 790*00b67f09SDavid van Moolenbroek<p> 791*00b67f09SDavid van Moolenbroek Cryptographic authentication of DNS information is possible 792*00b67f09SDavid van Moolenbroek through the DNS Security (<span class="emphasis"><em>DNSSEC-bis</em></span>) extensions, 793*00b67f09SDavid van Moolenbroek defined in RFC 4033, RFC 4034, and RFC 4035. 794*00b67f09SDavid van Moolenbroek This section describes the creation and use of DNSSEC signed zones. 795*00b67f09SDavid van Moolenbroek </p> 796*00b67f09SDavid van Moolenbroek<p> 797*00b67f09SDavid van Moolenbroek In order to set up a DNSSEC secure zone, there are a series 798*00b67f09SDavid van Moolenbroek of steps which must be followed. <acronym class="acronym">BIND</acronym> 799*00b67f09SDavid van Moolenbroek 9 ships 800*00b67f09SDavid van Moolenbroek with several tools 801*00b67f09SDavid van Moolenbroek that are used in this process, which are explained in more detail 802*00b67f09SDavid van Moolenbroek below. In all cases, the <code class="option">-h</code> option prints a 803*00b67f09SDavid van Moolenbroek full list of parameters. Note that the DNSSEC tools require the 804*00b67f09SDavid van Moolenbroek keyset files to be in the working directory or the 805*00b67f09SDavid van Moolenbroek directory specified by the <code class="option">-d</code> option, and 806*00b67f09SDavid van Moolenbroek that the tools shipped with BIND 9.2.x and earlier are not compatible 807*00b67f09SDavid van Moolenbroek with the current ones. 808*00b67f09SDavid van Moolenbroek </p> 809*00b67f09SDavid van Moolenbroek<p> 810*00b67f09SDavid van Moolenbroek There must also be communication with the administrators of 811*00b67f09SDavid van Moolenbroek the parent and/or child zone to transmit keys. A zone's security 812*00b67f09SDavid van Moolenbroek status must be indicated by the parent zone for a DNSSEC capable 813*00b67f09SDavid van Moolenbroek resolver to trust its data. This is done through the presence 814*00b67f09SDavid van Moolenbroek or absence of a <code class="literal">DS</code> record at the 815*00b67f09SDavid van Moolenbroek delegation 816*00b67f09SDavid van Moolenbroek point. 817*00b67f09SDavid van Moolenbroek </p> 818*00b67f09SDavid van Moolenbroek<p> 819*00b67f09SDavid van Moolenbroek For other servers to trust data in this zone, they must 820*00b67f09SDavid van Moolenbroek either be statically configured with this zone's zone key or the 821*00b67f09SDavid van Moolenbroek zone key of another zone above this one in the DNS tree. 822*00b67f09SDavid van Moolenbroek </p> 823*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 824*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 825*00b67f09SDavid van Moolenbroek<a name="id2570934"></a>Generating Keys</h3></div></div></div> 826*00b67f09SDavid van Moolenbroek<p> 827*00b67f09SDavid van Moolenbroek The <span><strong class="command">dnssec-keygen</strong></span> program is used to 828*00b67f09SDavid van Moolenbroek generate keys. 829*00b67f09SDavid van Moolenbroek </p> 830*00b67f09SDavid van Moolenbroek<p> 831*00b67f09SDavid van Moolenbroek A secure zone must contain one or more zone keys. The 832*00b67f09SDavid van Moolenbroek zone keys will sign all other records in the zone, as well as 833*00b67f09SDavid van Moolenbroek the zone keys of any secure delegated zones. Zone keys must 834*00b67f09SDavid van Moolenbroek have the same name as the zone, a name type of 835*00b67f09SDavid van Moolenbroek <span><strong class="command">ZONE</strong></span>, and must be usable for 836*00b67f09SDavid van Moolenbroek authentication. 837*00b67f09SDavid van Moolenbroek It is recommended that zone keys use a cryptographic algorithm 838*00b67f09SDavid van Moolenbroek designated as "mandatory to implement" by the IETF; currently 839*00b67f09SDavid van Moolenbroek the only one is RSASHA1. 840*00b67f09SDavid van Moolenbroek </p> 841*00b67f09SDavid van Moolenbroek<p> 842*00b67f09SDavid van Moolenbroek The following command will generate a 768-bit RSASHA1 key for 843*00b67f09SDavid van Moolenbroek the <code class="filename">child.example</code> zone: 844*00b67f09SDavid van Moolenbroek </p> 845*00b67f09SDavid van Moolenbroek<p> 846*00b67f09SDavid van Moolenbroek <strong class="userinput"><code>dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example.</code></strong> 847*00b67f09SDavid van Moolenbroek </p> 848*00b67f09SDavid van Moolenbroek<p> 849*00b67f09SDavid van Moolenbroek Two output files will be produced: 850*00b67f09SDavid van Moolenbroek <code class="filename">Kchild.example.+005+12345.key</code> and 851*00b67f09SDavid van Moolenbroek <code class="filename">Kchild.example.+005+12345.private</code> 852*00b67f09SDavid van Moolenbroek (where 853*00b67f09SDavid van Moolenbroek 12345 is an example of a key tag). The key filenames contain 854*00b67f09SDavid van Moolenbroek the key name (<code class="filename">child.example.</code>), 855*00b67f09SDavid van Moolenbroek algorithm (3 856*00b67f09SDavid van Moolenbroek is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in 857*00b67f09SDavid van Moolenbroek this case). 858*00b67f09SDavid van Moolenbroek The private key (in the <code class="filename">.private</code> 859*00b67f09SDavid van Moolenbroek file) is 860*00b67f09SDavid van Moolenbroek used to generate signatures, and the public key (in the 861*00b67f09SDavid van Moolenbroek <code class="filename">.key</code> file) is used for signature 862*00b67f09SDavid van Moolenbroek verification. 863*00b67f09SDavid van Moolenbroek </p> 864*00b67f09SDavid van Moolenbroek<p> 865*00b67f09SDavid van Moolenbroek To generate another key with the same properties (but with 866*00b67f09SDavid van Moolenbroek a different key tag), repeat the above command. 867*00b67f09SDavid van Moolenbroek </p> 868*00b67f09SDavid van Moolenbroek<p> 869*00b67f09SDavid van Moolenbroek The <span><strong class="command">dnssec-keyfromlabel</strong></span> program is used 870*00b67f09SDavid van Moolenbroek to get a key pair from a crypto hardware and build the key 871*00b67f09SDavid van Moolenbroek files. Its usage is similar to <span><strong class="command">dnssec-keygen</strong></span>. 872*00b67f09SDavid van Moolenbroek </p> 873*00b67f09SDavid van Moolenbroek<p> 874*00b67f09SDavid van Moolenbroek The public keys should be inserted into the zone file by 875*00b67f09SDavid van Moolenbroek including the <code class="filename">.key</code> files using 876*00b67f09SDavid van Moolenbroek <span><strong class="command">$INCLUDE</strong></span> statements. 877*00b67f09SDavid van Moolenbroek </p> 878*00b67f09SDavid van Moolenbroek</div> 879*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 880*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 881*00b67f09SDavid van Moolenbroek<a name="id2571218"></a>Signing the Zone</h3></div></div></div> 882*00b67f09SDavid van Moolenbroek<p> 883*00b67f09SDavid van Moolenbroek The <span><strong class="command">dnssec-signzone</strong></span> program is used 884*00b67f09SDavid van Moolenbroek to sign a zone. 885*00b67f09SDavid van Moolenbroek </p> 886*00b67f09SDavid van Moolenbroek<p> 887*00b67f09SDavid van Moolenbroek Any <code class="filename">keyset</code> files corresponding to 888*00b67f09SDavid van Moolenbroek secure subzones should be present. The zone signer will 889*00b67f09SDavid van Moolenbroek generate <code class="literal">NSEC</code>, <code class="literal">NSEC3</code> 890*00b67f09SDavid van Moolenbroek and <code class="literal">RRSIG</code> records for the zone, as 891*00b67f09SDavid van Moolenbroek well as <code class="literal">DS</code> for the child zones if 892*00b67f09SDavid van Moolenbroek <code class="literal">'-g'</code> is specified. If <code class="literal">'-g'</code> 893*00b67f09SDavid van Moolenbroek is not specified, then DS RRsets for the secure child 894*00b67f09SDavid van Moolenbroek zones need to be added manually. 895*00b67f09SDavid van Moolenbroek </p> 896*00b67f09SDavid van Moolenbroek<p> 897*00b67f09SDavid van Moolenbroek The following command signs the zone, assuming it is in a 898*00b67f09SDavid van Moolenbroek file called <code class="filename">zone.child.example</code>. By 899*00b67f09SDavid van Moolenbroek default, all zone keys which have an available private key are 900*00b67f09SDavid van Moolenbroek used to generate signatures. 901*00b67f09SDavid van Moolenbroek </p> 902*00b67f09SDavid van Moolenbroek<p> 903*00b67f09SDavid van Moolenbroek <strong class="userinput"><code>dnssec-signzone -o child.example zone.child.example</code></strong> 904*00b67f09SDavid van Moolenbroek </p> 905*00b67f09SDavid van Moolenbroek<p> 906*00b67f09SDavid van Moolenbroek One output file is produced: 907*00b67f09SDavid van Moolenbroek <code class="filename">zone.child.example.signed</code>. This 908*00b67f09SDavid van Moolenbroek file 909*00b67f09SDavid van Moolenbroek should be referenced by <code class="filename">named.conf</code> 910*00b67f09SDavid van Moolenbroek as the 911*00b67f09SDavid van Moolenbroek input file for the zone. 912*00b67f09SDavid van Moolenbroek </p> 913*00b67f09SDavid van Moolenbroek<p><span><strong class="command">dnssec-signzone</strong></span> 914*00b67f09SDavid van Moolenbroek will also produce a keyset and dsset files and optionally a 915*00b67f09SDavid van Moolenbroek dlvset file. These are used to provide the parent zone 916*00b67f09SDavid van Moolenbroek administrators with the <code class="literal">DNSKEYs</code> (or their 917*00b67f09SDavid van Moolenbroek corresponding <code class="literal">DS</code> records) that are the 918*00b67f09SDavid van Moolenbroek secure entry point to the zone. 919*00b67f09SDavid van Moolenbroek </p> 920*00b67f09SDavid van Moolenbroek</div> 921*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 922*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 923*00b67f09SDavid van Moolenbroek<a name="id2571299"></a>Configuring Servers</h3></div></div></div> 924*00b67f09SDavid van Moolenbroek<p> 925*00b67f09SDavid van Moolenbroek To enable <span><strong class="command">named</strong></span> to respond appropriately 926*00b67f09SDavid van Moolenbroek to DNS requests from DNSSEC aware clients, 927*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-enable</strong></span> must be set to yes. 928*00b67f09SDavid van Moolenbroek (This is the default setting.) 929*00b67f09SDavid van Moolenbroek </p> 930*00b67f09SDavid van Moolenbroek<p> 931*00b67f09SDavid van Moolenbroek To enable <span><strong class="command">named</strong></span> to validate answers from 932*00b67f09SDavid van Moolenbroek other servers, the <span><strong class="command">dnssec-enable</strong></span> option 933*00b67f09SDavid van Moolenbroek must be set to <strong class="userinput"><code>yes</code></strong>, and the 934*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-validation</strong></span> options must be set to 935*00b67f09SDavid van Moolenbroek <strong class="userinput"><code>yes</code></strong> or <strong class="userinput"><code>auto</code></strong>. 936*00b67f09SDavid van Moolenbroek </p> 937*00b67f09SDavid van Moolenbroek<p> 938*00b67f09SDavid van Moolenbroek If <span><strong class="command">dnssec-validation</strong></span> is set to 939*00b67f09SDavid van Moolenbroek <strong class="userinput"><code>auto</code></strong>, then a default 940*00b67f09SDavid van Moolenbroek trust anchor for the DNS root zone will be used. 941*00b67f09SDavid van Moolenbroek If it is set to <strong class="userinput"><code>yes</code></strong>, however, 942*00b67f09SDavid van Moolenbroek then at least one trust anchor must be configured 943*00b67f09SDavid van Moolenbroek with a <span><strong class="command">trusted-keys</strong></span> or 944*00b67f09SDavid van Moolenbroek <span><strong class="command">managed-keys</strong></span> statement in 945*00b67f09SDavid van Moolenbroek <code class="filename">named.conf</code>, or DNSSEC validation 946*00b67f09SDavid van Moolenbroek will not occur. The default setting is 947*00b67f09SDavid van Moolenbroek <strong class="userinput"><code>yes</code></strong>. 948*00b67f09SDavid van Moolenbroek </p> 949*00b67f09SDavid van Moolenbroek<p> 950*00b67f09SDavid van Moolenbroek <span><strong class="command">trusted-keys</strong></span> are copies of DNSKEY RRs 951*00b67f09SDavid van Moolenbroek for zones that are used to form the first link in the 952*00b67f09SDavid van Moolenbroek cryptographic chain of trust. All keys listed in 953*00b67f09SDavid van Moolenbroek <span><strong class="command">trusted-keys</strong></span> (and corresponding zones) 954*00b67f09SDavid van Moolenbroek are deemed to exist and only the listed keys will be used 955*00b67f09SDavid van Moolenbroek to validated the DNSKEY RRset that they are from. 956*00b67f09SDavid van Moolenbroek </p> 957*00b67f09SDavid van Moolenbroek<p> 958*00b67f09SDavid van Moolenbroek <span><strong class="command">managed-keys</strong></span> are trusted keys which are 959*00b67f09SDavid van Moolenbroek automatically kept up to date via RFC 5011 trust anchor 960*00b67f09SDavid van Moolenbroek maintenance. 961*00b67f09SDavid van Moolenbroek </p> 962*00b67f09SDavid van Moolenbroek<p> 963*00b67f09SDavid van Moolenbroek <span><strong class="command">trusted-keys</strong></span> and 964*00b67f09SDavid van Moolenbroek <span><strong class="command">managed-keys</strong></span> are described in more detail 965*00b67f09SDavid van Moolenbroek later in this document. 966*00b67f09SDavid van Moolenbroek </p> 967*00b67f09SDavid van Moolenbroek<p> 968*00b67f09SDavid van Moolenbroek Unlike <acronym class="acronym">BIND</acronym> 8, <acronym class="acronym">BIND</acronym> 969*00b67f09SDavid van Moolenbroek 9 does not verify signatures on load, so zone keys for 970*00b67f09SDavid van Moolenbroek authoritative zones do not need to be specified in the 971*00b67f09SDavid van Moolenbroek configuration file. 972*00b67f09SDavid van Moolenbroek </p> 973*00b67f09SDavid van Moolenbroek<p> 974*00b67f09SDavid van Moolenbroek After DNSSEC gets established, a typical DNSSEC configuration 975*00b67f09SDavid van Moolenbroek will look something like the following. It has one or 976*00b67f09SDavid van Moolenbroek more public keys for the root. This allows answers from 977*00b67f09SDavid van Moolenbroek outside the organization to be validated. It will also 978*00b67f09SDavid van Moolenbroek have several keys for parts of the namespace the organization 979*00b67f09SDavid van Moolenbroek controls. These are here to ensure that <span><strong class="command">named</strong></span> 980*00b67f09SDavid van Moolenbroek is immune to compromises in the DNSSEC components of the security 981*00b67f09SDavid van Moolenbroek of parent zones. 982*00b67f09SDavid van Moolenbroek </p> 983*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 984*00b67f09SDavid van Moolenbroekmanaged-keys { 985*00b67f09SDavid van Moolenbroek /* Root Key */ 986*00b67f09SDavid van Moolenbroek "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS 987*00b67f09SDavid van Moolenbroek JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh 988*00b67f09SDavid van Moolenbroek aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy 989*00b67f09SDavid van Moolenbroek 4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg 990*00b67f09SDavid van Moolenbroek hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp 991*00b67f09SDavid van Moolenbroek 5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke 992*00b67f09SDavid van Moolenbroek g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq 993*00b67f09SDavid van Moolenbroek 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ 994*00b67f09SDavid van Moolenbroek 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ 995*00b67f09SDavid van Moolenbroek dgxbcDTClU0CRBdiieyLMNzXG3"; 996*00b67f09SDavid van Moolenbroek}; 997*00b67f09SDavid van Moolenbroek 998*00b67f09SDavid van Moolenbroektrusted-keys { 999*00b67f09SDavid van Moolenbroek /* Key for our organization's forward zone */ 1000*00b67f09SDavid van Moolenbroek example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6 1001*00b67f09SDavid van Moolenbroek 5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z 1002*00b67f09SDavid van Moolenbroek GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb 1003*00b67f09SDavid van Moolenbroek 4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL 1004*00b67f09SDavid van Moolenbroek kBOUKUf/mC7HvfwYH/Be22GnClrinKJp1O 1005*00b67f09SDavid van Moolenbroek g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S 1006*00b67f09SDavid van Moolenbroek TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq 1007*00b67f09SDavid van Moolenbroek FxmAVZP20igTixin/1LcrgX/KMEGd/biuv 1008*00b67f09SDavid van Moolenbroek F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm 1009*00b67f09SDavid van Moolenbroek /oyWR8BW/hWdzOvnSCThlHf3xiYleDbt/o 1010*00b67f09SDavid van Moolenbroek 1OTQ09A0="; 1011*00b67f09SDavid van Moolenbroek 1012*00b67f09SDavid van Moolenbroek /* Key for our reverse zone. */ 1013*00b67f09SDavid van Moolenbroek 2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc 1014*00b67f09SDavid van Moolenbroek xOdNax071L18QqZnQQQAVVr+i 1015*00b67f09SDavid van Moolenbroek LhGTnNGp3HoWQLUIzKrJVZ3zg 1016*00b67f09SDavid van Moolenbroek gy3WwNT6kZo6c0tszYqbtvchm 1017*00b67f09SDavid van Moolenbroek gQC8CzKojM/W16i6MG/eafGU3 1018*00b67f09SDavid van Moolenbroek siaOdS0yOI6BgPsw+YZdzlYMa 1019*00b67f09SDavid van Moolenbroek IJGf4M4dyoKIhzdZyQ2bYQrjy 1020*00b67f09SDavid van Moolenbroek Q4LB0lC7aOnsMyYKHHYeRvPxj 1021*00b67f09SDavid van Moolenbroek IQXmdqgOJGq+vsevG06zW+1xg 1022*00b67f09SDavid van Moolenbroek YJh9rCIfnm1GX/KMgxLPG2vXT 1023*00b67f09SDavid van Moolenbroek D/RnLX+D3T3UL7HJYHJhAZD5L 1024*00b67f09SDavid van Moolenbroek 59VvjSPsZJHeDCUyWYrvPZesZ 1025*00b67f09SDavid van Moolenbroek DIRvhDD52SKvbheeTJUm6Ehkz 1026*00b67f09SDavid van Moolenbroek ytNN2SN96QRk8j/iI8ib"; 1027*00b67f09SDavid van Moolenbroek}; 1028*00b67f09SDavid van Moolenbroek 1029*00b67f09SDavid van Moolenbroekoptions { 1030*00b67f09SDavid van Moolenbroek ... 1031*00b67f09SDavid van Moolenbroek dnssec-enable yes; 1032*00b67f09SDavid van Moolenbroek dnssec-validation yes; 1033*00b67f09SDavid van Moolenbroek}; 1034*00b67f09SDavid van Moolenbroek</pre> 1035*00b67f09SDavid van Moolenbroek<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 1036*00b67f09SDavid van Moolenbroek<h3 class="title">Note</h3> 1037*00b67f09SDavid van Moolenbroek None of the keys listed in this example are valid. In particular, 1038*00b67f09SDavid van Moolenbroek the root key is not valid. 1039*00b67f09SDavid van Moolenbroek </div> 1040*00b67f09SDavid van Moolenbroek<p> 1041*00b67f09SDavid van Moolenbroek When DNSSEC validation is enabled and properly configured, 1042*00b67f09SDavid van Moolenbroek the resolver will reject any answers from signed, secure zones 1043*00b67f09SDavid van Moolenbroek which fail to validate, and will return SERVFAIL to the client. 1044*00b67f09SDavid van Moolenbroek </p> 1045*00b67f09SDavid van Moolenbroek<p> 1046*00b67f09SDavid van Moolenbroek Responses may fail to validate for any of several reasons, 1047*00b67f09SDavid van Moolenbroek including missing, expired, or invalid signatures, a key which 1048*00b67f09SDavid van Moolenbroek does not match the DS RRset in the parent zone, or an insecure 1049*00b67f09SDavid van Moolenbroek response from a zone which, according to its parent, should have 1050*00b67f09SDavid van Moolenbroek been secure. 1051*00b67f09SDavid van Moolenbroek </p> 1052*00b67f09SDavid van Moolenbroek<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 1053*00b67f09SDavid van Moolenbroek<h3 class="title">Note</h3> 1054*00b67f09SDavid van Moolenbroek<p> 1055*00b67f09SDavid van Moolenbroek When the validator receives a response from an unsigned zone 1056*00b67f09SDavid van Moolenbroek that has a signed parent, it must confirm with the parent 1057*00b67f09SDavid van Moolenbroek that the zone was intentionally left unsigned. It does 1058*00b67f09SDavid van Moolenbroek this by verifying, via signed and validated NSEC/NSEC3 records, 1059*00b67f09SDavid van Moolenbroek that the parent zone contains no DS records for the child. 1060*00b67f09SDavid van Moolenbroek </p> 1061*00b67f09SDavid van Moolenbroek<p> 1062*00b67f09SDavid van Moolenbroek If the validator <span class="emphasis"><em>can</em></span> prove that the zone 1063*00b67f09SDavid van Moolenbroek is insecure, then the response is accepted. However, if it 1064*00b67f09SDavid van Moolenbroek cannot, then it must assume an insecure response to be a 1065*00b67f09SDavid van Moolenbroek forgery; it rejects the response and logs an error. 1066*00b67f09SDavid van Moolenbroek </p> 1067*00b67f09SDavid van Moolenbroek<p> 1068*00b67f09SDavid van Moolenbroek The logged error reads "insecurity proof failed" and 1069*00b67f09SDavid van Moolenbroek "got insecure response; parent indicates it should be secure". 1070*00b67f09SDavid van Moolenbroek (Prior to BIND 9.7, the logged error was "not insecure". 1071*00b67f09SDavid van Moolenbroek This referred to the zone, not the response.) 1072*00b67f09SDavid van Moolenbroek </p> 1073*00b67f09SDavid van Moolenbroek</div> 1074*00b67f09SDavid van Moolenbroek</div> 1075*00b67f09SDavid van Moolenbroek</div> 1076*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 1077*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1078*00b67f09SDavid van Moolenbroek<a name="dnssec.dynamic.zones"></a>DNSSEC, Dynamic Zones, and Automatic Signing</h2></div></div></div> 1079*00b67f09SDavid van Moolenbroek<p>As of BIND 9.7.0 it is possible to change a dynamic zone 1080*00b67f09SDavid van Moolenbroek from insecure to signed and back again. A secure zone can use 1081*00b67f09SDavid van Moolenbroek either NSEC or NSEC3 chains.</p> 1082*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1083*00b67f09SDavid van Moolenbroek<a name="id2611126"></a>Converting from insecure to secure</h3></div></div></div></div> 1084*00b67f09SDavid van Moolenbroek<p>Changing a zone from insecure to secure can be done in two 1085*00b67f09SDavid van Moolenbroek ways: using a dynamic DNS update, or the 1086*00b67f09SDavid van Moolenbroek <span><strong class="command">auto-dnssec</strong></span> zone option.</p> 1087*00b67f09SDavid van Moolenbroek<p>For either method, you need to configure 1088*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> so that it can see the 1089*00b67f09SDavid van Moolenbroek <code class="filename">K*</code> files which contain the public and private 1090*00b67f09SDavid van Moolenbroek parts of the keys that will be used to sign the zone. These files 1091*00b67f09SDavid van Moolenbroek will have been generated by 1092*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-keygen</strong></span>. You can do this by placing them 1093*00b67f09SDavid van Moolenbroek in the key-directory, as specified in 1094*00b67f09SDavid van Moolenbroek <code class="filename">named.conf</code>:</p> 1095*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 1096*00b67f09SDavid van Moolenbroek zone example.net { 1097*00b67f09SDavid van Moolenbroek type master; 1098*00b67f09SDavid van Moolenbroek update-policy local; 1099*00b67f09SDavid van Moolenbroek file "dynamic/example.net/example.net"; 1100*00b67f09SDavid van Moolenbroek key-directory "dynamic/example.net"; 1101*00b67f09SDavid van Moolenbroek }; 1102*00b67f09SDavid van Moolenbroek</pre> 1103*00b67f09SDavid van Moolenbroek<p>If one KSK and one ZSK DNSKEY key have been generated, this 1104*00b67f09SDavid van Moolenbroek configuration will cause all records in the zone to be signed 1105*00b67f09SDavid van Moolenbroek with the ZSK, and the DNSKEY RRset to be signed with the KSK as 1106*00b67f09SDavid van Moolenbroek well. An NSEC chain will be generated as part of the initial 1107*00b67f09SDavid van Moolenbroek signing process.</p> 1108*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1109*00b67f09SDavid van Moolenbroek<a name="id2563650"></a>Dynamic DNS update method</h3></div></div></div></div> 1110*00b67f09SDavid van Moolenbroek<p>To insert the keys via dynamic update:</p> 1111*00b67f09SDavid van Moolenbroek<pre class="screen"> 1112*00b67f09SDavid van Moolenbroek % nsupdate 1113*00b67f09SDavid van Moolenbroek > ttl 3600 1114*00b67f09SDavid van Moolenbroek > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= 1115*00b67f09SDavid van Moolenbroek > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= 1116*00b67f09SDavid van Moolenbroek > send 1117*00b67f09SDavid van Moolenbroek</pre> 1118*00b67f09SDavid van Moolenbroek<p>While the update request will complete almost immediately, 1119*00b67f09SDavid van Moolenbroek the zone will not be completely signed until 1120*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> has had time to walk the zone and 1121*00b67f09SDavid van Moolenbroek generate the NSEC and RRSIG records. The NSEC record at the apex 1122*00b67f09SDavid van Moolenbroek will be added last, to signal that there is a complete NSEC 1123*00b67f09SDavid van Moolenbroek chain.</p> 1124*00b67f09SDavid van Moolenbroek<p>If you wish to sign using NSEC3 instead of NSEC, you should 1125*00b67f09SDavid van Moolenbroek add an NSEC3PARAM record to the initial update request. If you 1126*00b67f09SDavid van Moolenbroek wish the NSEC3 chain to have the OPTOUT bit set, set it in the 1127*00b67f09SDavid van Moolenbroek flags field of the NSEC3PARAM record.</p> 1128*00b67f09SDavid van Moolenbroek<pre class="screen"> 1129*00b67f09SDavid van Moolenbroek % nsupdate 1130*00b67f09SDavid van Moolenbroek > ttl 3600 1131*00b67f09SDavid van Moolenbroek > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= 1132*00b67f09SDavid van Moolenbroek > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= 1133*00b67f09SDavid van Moolenbroek > update add example.net NSEC3PARAM 1 1 100 1234567890 1134*00b67f09SDavid van Moolenbroek > send 1135*00b67f09SDavid van Moolenbroek</pre> 1136*00b67f09SDavid van Moolenbroek<p>Again, this update request will complete almost 1137*00b67f09SDavid van Moolenbroek immediately; however, the record won't show up until 1138*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> has had a chance to build/remove the 1139*00b67f09SDavid van Moolenbroek relevant chain. A private type record will be created to record 1140*00b67f09SDavid van Moolenbroek the state of the operation (see below for more details), and will 1141*00b67f09SDavid van Moolenbroek be removed once the operation completes.</p> 1142*00b67f09SDavid van Moolenbroek<p>While the initial signing and NSEC/NSEC3 chain generation 1143*00b67f09SDavid van Moolenbroek is happening, other updates are possible as well.</p> 1144*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1145*00b67f09SDavid van Moolenbroek<a name="id2563686"></a>Fully automatic zone signing</h3></div></div></div></div> 1146*00b67f09SDavid van Moolenbroek<p>To enable automatic signing, add the 1147*00b67f09SDavid van Moolenbroek <span><strong class="command">auto-dnssec</strong></span> option to the zone statement in 1148*00b67f09SDavid van Moolenbroek <code class="filename">named.conf</code>. 1149*00b67f09SDavid van Moolenbroek <span><strong class="command">auto-dnssec</strong></span> has two possible arguments: 1150*00b67f09SDavid van Moolenbroek <code class="constant">allow</code> or 1151*00b67f09SDavid van Moolenbroek <code class="constant">maintain</code>.</p> 1152*00b67f09SDavid van Moolenbroek<p>With 1153*00b67f09SDavid van Moolenbroek <span><strong class="command">auto-dnssec allow</strong></span>, 1154*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> can search the key directory for keys 1155*00b67f09SDavid van Moolenbroek matching the zone, insert them into the zone, and use them to 1156*00b67f09SDavid van Moolenbroek sign the zone. It will do so only when it receives an 1157*00b67f09SDavid van Moolenbroek <span><strong class="command">rndc sign <zonename></strong></span>.</p> 1158*00b67f09SDavid van Moolenbroek<p> 1159*00b67f09SDavid van Moolenbroek 1160*00b67f09SDavid van Moolenbroek <span><strong class="command">auto-dnssec maintain</strong></span> includes the above 1161*00b67f09SDavid van Moolenbroek functionality, but will also automatically adjust the zone's 1162*00b67f09SDavid van Moolenbroek DNSKEY records on schedule according to the keys' timing metadata. 1163*00b67f09SDavid van Moolenbroek (See <a href="man.dnssec-keygen.html" title="dnssec-keygen"><span class="refentrytitle"><span class="application">dnssec-keygen</span></span>(8)</a> and 1164*00b67f09SDavid van Moolenbroek <a href="man.dnssec-settime.html" title="dnssec-settime"><span class="refentrytitle"><span class="application">dnssec-settime</span></span>(8)</a> for more information.) 1165*00b67f09SDavid van Moolenbroek </p> 1166*00b67f09SDavid van Moolenbroek<p> 1167*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> will periodically search the key directory 1168*00b67f09SDavid van Moolenbroek for keys matching the zone, and if the keys' metadata indicates 1169*00b67f09SDavid van Moolenbroek that any change should be made the zone, such as adding, removing, 1170*00b67f09SDavid van Moolenbroek or revoking a key, then that action will be carried out. By default, 1171*00b67f09SDavid van Moolenbroek the key directory is checked for changes every 60 minutes; this period 1172*00b67f09SDavid van Moolenbroek can be adjusted with the <code class="option">dnssec-loadkeys-interval</code>, up 1173*00b67f09SDavid van Moolenbroek to a maximum of 24 hours. The <span><strong class="command">rndc loadkeys</strong></span> forces 1174*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> to check for key updates immediately. 1175*00b67f09SDavid van Moolenbroek </p> 1176*00b67f09SDavid van Moolenbroek<p> 1177*00b67f09SDavid van Moolenbroek If keys are present in the key directory the first time the zone 1178*00b67f09SDavid van Moolenbroek is loaded, the zone will be signed immediately, without waiting for an 1179*00b67f09SDavid van Moolenbroek <span><strong class="command">rndc sign</strong></span> or <span><strong class="command">rndc loadkeys</strong></span> 1180*00b67f09SDavid van Moolenbroek command. (Those commands can still be used when there are unscheduled 1181*00b67f09SDavid van Moolenbroek key changes, however.) 1182*00b67f09SDavid van Moolenbroek </p> 1183*00b67f09SDavid van Moolenbroek<p> 1184*00b67f09SDavid van Moolenbroek When new keys are added to a zone, the TTL is set to match that 1185*00b67f09SDavid van Moolenbroek of any existing DNSKEY RRset. If there is no existing DNSKEY RRset, 1186*00b67f09SDavid van Moolenbroek then the TTL will be set to the TTL specified when the key was 1187*00b67f09SDavid van Moolenbroek created (using the <span><strong class="command">dnssec-keygen -L</strong></span> option), if 1188*00b67f09SDavid van Moolenbroek any, or to the SOA TTL. 1189*00b67f09SDavid van Moolenbroek </p> 1190*00b67f09SDavid van Moolenbroek<p> 1191*00b67f09SDavid van Moolenbroek If you wish the zone to be signed using NSEC3 instead of NSEC, 1192*00b67f09SDavid van Moolenbroek submit an NSEC3PARAM record via dynamic update prior to the 1193*00b67f09SDavid van Moolenbroek scheduled publication and activation of the keys. If you wish the 1194*00b67f09SDavid van Moolenbroek NSEC3 chain to have the OPTOUT bit set, set it in the flags field 1195*00b67f09SDavid van Moolenbroek of the NSEC3PARAM record. The NSEC3PARAM record will not appear in 1196*00b67f09SDavid van Moolenbroek the zone immediately, but it will be stored for later reference. When 1197*00b67f09SDavid van Moolenbroek the zone is signed and the NSEC3 chain is completed, the NSEC3PARAM 1198*00b67f09SDavid van Moolenbroek record will appear in the zone. 1199*00b67f09SDavid van Moolenbroek </p> 1200*00b67f09SDavid van Moolenbroek<p>Using the 1201*00b67f09SDavid van Moolenbroek <span><strong class="command">auto-dnssec</strong></span> option requires the zone to be 1202*00b67f09SDavid van Moolenbroek configured to allow dynamic updates, by adding an 1203*00b67f09SDavid van Moolenbroek <span><strong class="command">allow-update</strong></span> or 1204*00b67f09SDavid van Moolenbroek <span><strong class="command">update-policy</strong></span> statement to the zone 1205*00b67f09SDavid van Moolenbroek configuration. If this has not been done, the configuration will 1206*00b67f09SDavid van Moolenbroek fail.</p> 1207*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1208*00b67f09SDavid van Moolenbroek<a name="id2563933"></a>Private-type records</h3></div></div></div></div> 1209*00b67f09SDavid van Moolenbroek<p>The state of the signing process is signaled by 1210*00b67f09SDavid van Moolenbroek private-type records (with a default type value of 65534). When 1211*00b67f09SDavid van Moolenbroek signing is complete, these records will have a nonzero value for 1212*00b67f09SDavid van Moolenbroek the final octet (for those records which have a nonzero initial 1213*00b67f09SDavid van Moolenbroek octet).</p> 1214*00b67f09SDavid van Moolenbroek<p>The private type record format: If the first octet is 1215*00b67f09SDavid van Moolenbroek non-zero then the record indicates that the zone needs to be 1216*00b67f09SDavid van Moolenbroek signed with the key matching the record, or that all signatures 1217*00b67f09SDavid van Moolenbroek that match the record should be removed.</p> 1218*00b67f09SDavid van Moolenbroek<p> 1219*00b67f09SDavid van Moolenbroek </p> 1220*00b67f09SDavid van Moolenbroek<div class="literallayout"><p><br> 1221*00b67f09SDavid van Moolenbroek<br> 1222*00b67f09SDavid van Moolenbroek��algorithm�(octet�1)<br> 1223*00b67f09SDavid van Moolenbroek��key�id�in�network�order�(octet�2�and�3)<br> 1224*00b67f09SDavid van Moolenbroek��removal�flag�(octet�4)<br> 1225*00b67f09SDavid van Moolenbroek��complete�flag�(octet�5)<br> 1226*00b67f09SDavid van Moolenbroek</p></div> 1227*00b67f09SDavid van Moolenbroek<p> 1228*00b67f09SDavid van Moolenbroek </p> 1229*00b67f09SDavid van Moolenbroek<p>Only records flagged as "complete" can be removed via 1230*00b67f09SDavid van Moolenbroek dynamic update. Attempts to remove other private type records 1231*00b67f09SDavid van Moolenbroek will be silently ignored.</p> 1232*00b67f09SDavid van Moolenbroek<p>If the first octet is zero (this is a reserved algorithm 1233*00b67f09SDavid van Moolenbroek number that should never appear in a DNSKEY record) then the 1234*00b67f09SDavid van Moolenbroek record indicates changes to the NSEC3 chains are in progress. The 1235*00b67f09SDavid van Moolenbroek rest of the record contains an NSEC3PARAM record. The flag field 1236*00b67f09SDavid van Moolenbroek tells what operation to perform based on the flag bits.</p> 1237*00b67f09SDavid van Moolenbroek<p> 1238*00b67f09SDavid van Moolenbroek </p> 1239*00b67f09SDavid van Moolenbroek<div class="literallayout"><p><br> 1240*00b67f09SDavid van Moolenbroek<br> 1241*00b67f09SDavid van Moolenbroek��0x01�OPTOUT<br> 1242*00b67f09SDavid van Moolenbroek��0x80�CREATE<br> 1243*00b67f09SDavid van Moolenbroek��0x40�REMOVE<br> 1244*00b67f09SDavid van Moolenbroek��0x20�NONSEC<br> 1245*00b67f09SDavid van Moolenbroek</p></div> 1246*00b67f09SDavid van Moolenbroek<p> 1247*00b67f09SDavid van Moolenbroek </p> 1248*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1249*00b67f09SDavid van Moolenbroek<a name="id2582676"></a>DNSKEY rollovers</h3></div></div></div></div> 1250*00b67f09SDavid van Moolenbroek<p>As with insecure-to-secure conversions, rolling DNSSEC 1251*00b67f09SDavid van Moolenbroek keys can be done in two ways: using a dynamic DNS update, or the 1252*00b67f09SDavid van Moolenbroek <span><strong class="command">auto-dnssec</strong></span> zone option.</p> 1253*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1254*00b67f09SDavid van Moolenbroek<a name="id2582689"></a>Dynamic DNS update method</h3></div></div></div></div> 1255*00b67f09SDavid van Moolenbroek<p> To perform key rollovers via dynamic update, you need to add 1256*00b67f09SDavid van Moolenbroek the <code class="filename">K*</code> files for the new keys so that 1257*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> can find them. You can then add the new 1258*00b67f09SDavid van Moolenbroek DNSKEY RRs via dynamic update. 1259*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> will then cause the zone to be signed 1260*00b67f09SDavid van Moolenbroek with the new keys. When the signing is complete the private type 1261*00b67f09SDavid van Moolenbroek records will be updated so that the last octet is non 1262*00b67f09SDavid van Moolenbroek zero.</p> 1263*00b67f09SDavid van Moolenbroek<p>If this is for a KSK you need to inform the parent and any 1264*00b67f09SDavid van Moolenbroek trust anchor repositories of the new KSK.</p> 1265*00b67f09SDavid van Moolenbroek<p>You should then wait for the maximum TTL in the zone before 1266*00b67f09SDavid van Moolenbroek removing the old DNSKEY. If it is a KSK that is being updated, 1267*00b67f09SDavid van Moolenbroek you also need to wait for the DS RRset in the parent to be 1268*00b67f09SDavid van Moolenbroek updated and its TTL to expire. This ensures that all clients will 1269*00b67f09SDavid van Moolenbroek be able to verify at least one signature when you remove the old 1270*00b67f09SDavid van Moolenbroek DNSKEY.</p> 1271*00b67f09SDavid van Moolenbroek<p>The old DNSKEY can be removed via UPDATE. Take care to 1272*00b67f09SDavid van Moolenbroek specify the correct key. 1273*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> will clean out any signatures generated 1274*00b67f09SDavid van Moolenbroek by the old key after the update completes.</p> 1275*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1276*00b67f09SDavid van Moolenbroek<a name="id2582722"></a>Automatic key rollovers</h3></div></div></div></div> 1277*00b67f09SDavid van Moolenbroek<p>When a new key reaches its activation date (as set by 1278*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-keygen</strong></span> or <span><strong class="command">dnssec-settime</strong></span>), 1279*00b67f09SDavid van Moolenbroek if the <span><strong class="command">auto-dnssec</strong></span> zone option is set to 1280*00b67f09SDavid van Moolenbroek <code class="constant">maintain</code>, <span><strong class="command">named</strong></span> will 1281*00b67f09SDavid van Moolenbroek automatically carry out the key rollover. If the key's algorithm 1282*00b67f09SDavid van Moolenbroek has not previously been used to sign the zone, then the zone will 1283*00b67f09SDavid van Moolenbroek be fully signed as quickly as possible. However, if the new key 1284*00b67f09SDavid van Moolenbroek is replacing an existing key of the same algorithm, then the 1285*00b67f09SDavid van Moolenbroek zone will be re-signed incrementally, with signatures from the 1286*00b67f09SDavid van Moolenbroek old key being replaced with signatures from the new key as their 1287*00b67f09SDavid van Moolenbroek signature validity periods expire. By default, this rollover 1288*00b67f09SDavid van Moolenbroek completes in 30 days, after which it will be safe to remove the 1289*00b67f09SDavid van Moolenbroek old key from the DNSKEY RRset.</p> 1290*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1291*00b67f09SDavid van Moolenbroek<a name="id2582748"></a>NSEC3PARAM rollovers via UPDATE</h3></div></div></div></div> 1292*00b67f09SDavid van Moolenbroek<p>Add the new NSEC3PARAM record via dynamic update. When the 1293*00b67f09SDavid van Moolenbroek new NSEC3 chain has been generated, the NSEC3PARAM flag field 1294*00b67f09SDavid van Moolenbroek will be zero. At this point you can remove the old NSEC3PARAM 1295*00b67f09SDavid van Moolenbroek record. The old chain will be removed after the update request 1296*00b67f09SDavid van Moolenbroek completes.</p> 1297*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1298*00b67f09SDavid van Moolenbroek<a name="id2582758"></a>Converting from NSEC to NSEC3</h3></div></div></div></div> 1299*00b67f09SDavid van Moolenbroek<p>To do this, you just need to add an NSEC3PARAM record. When 1300*00b67f09SDavid van Moolenbroek the conversion is complete, the NSEC chain will have been removed 1301*00b67f09SDavid van Moolenbroek and the NSEC3PARAM record will have a zero flag field. The NSEC3 1302*00b67f09SDavid van Moolenbroek chain will be generated before the NSEC chain is 1303*00b67f09SDavid van Moolenbroek destroyed.</p> 1304*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1305*00b67f09SDavid van Moolenbroek<a name="id2582768"></a>Converting from NSEC3 to NSEC</h3></div></div></div></div> 1306*00b67f09SDavid van Moolenbroek<p>To do this, use <span><strong class="command">nsupdate</strong></span> to 1307*00b67f09SDavid van Moolenbroek remove all NSEC3PARAM records with a zero flag 1308*00b67f09SDavid van Moolenbroek field. The NSEC chain will be generated before the NSEC3 chain is 1309*00b67f09SDavid van Moolenbroek removed.</p> 1310*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1311*00b67f09SDavid van Moolenbroek<a name="id2582780"></a>Converting from secure to insecure</h3></div></div></div></div> 1312*00b67f09SDavid van Moolenbroek<p>To convert a signed zone to unsigned using dynamic DNS, 1313*00b67f09SDavid van Moolenbroek delete all the DNSKEY records from the zone apex using 1314*00b67f09SDavid van Moolenbroek <span><strong class="command">nsupdate</strong></span>. All signatures, NSEC or NSEC3 chains, 1315*00b67f09SDavid van Moolenbroek and associated NSEC3PARAM records will be removed automatically. 1316*00b67f09SDavid van Moolenbroek This will take place after the update request completes.</p> 1317*00b67f09SDavid van Moolenbroek<p> This requires the 1318*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-secure-to-insecure</strong></span> option to be set to 1319*00b67f09SDavid van Moolenbroek <strong class="userinput"><code>yes</code></strong> in 1320*00b67f09SDavid van Moolenbroek <code class="filename">named.conf</code>.</p> 1321*00b67f09SDavid van Moolenbroek<p>In addition, if the <span><strong class="command">auto-dnssec maintain</strong></span> 1322*00b67f09SDavid van Moolenbroek zone statement is used, it should be removed or changed to 1323*00b67f09SDavid van Moolenbroek <span><strong class="command">allow</strong></span> instead (or it will re-sign). 1324*00b67f09SDavid van Moolenbroek </p> 1325*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1326*00b67f09SDavid van Moolenbroek<a name="id2582818"></a>Periodic re-signing</h3></div></div></div></div> 1327*00b67f09SDavid van Moolenbroek<p>In any secure zone which supports dynamic updates, named 1328*00b67f09SDavid van Moolenbroek will periodically re-sign RRsets which have not been re-signed as 1329*00b67f09SDavid van Moolenbroek a result of some update action. The signature lifetimes will be 1330*00b67f09SDavid van Moolenbroek adjusted so as to spread the re-sign load over time rather than 1331*00b67f09SDavid van Moolenbroek all at once.</p> 1332*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> 1333*00b67f09SDavid van Moolenbroek<a name="id2582827"></a>NSEC3 and OPTOUT</h3></div></div></div></div> 1334*00b67f09SDavid van Moolenbroek<p> 1335*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> only supports creating new NSEC3 chains 1336*00b67f09SDavid van Moolenbroek where all the NSEC3 records in the zone have the same OPTOUT 1337*00b67f09SDavid van Moolenbroek state. 1338*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> supports UPDATES to zones where the NSEC3 1339*00b67f09SDavid van Moolenbroek records in the chain have mixed OPTOUT state. 1340*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> does not support changing the OPTOUT 1341*00b67f09SDavid van Moolenbroek state of an individual NSEC3 record, the entire chain needs to be 1342*00b67f09SDavid van Moolenbroek changed if the OPTOUT state of an individual NSEC3 needs to be 1343*00b67f09SDavid van Moolenbroek changed.</p> 1344*00b67f09SDavid van Moolenbroek</div> 1345*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 1346*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1347*00b67f09SDavid van Moolenbroek<a name="rfc5011.support"></a>Dynamic Trust Anchor Management</h2></div></div></div> 1348*00b67f09SDavid van Moolenbroek<p>BIND 9.7.0 introduces support for RFC 5011, dynamic trust 1349*00b67f09SDavid van Moolenbroek anchor management. Using this feature allows 1350*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span> to keep track of changes to critical 1351*00b67f09SDavid van Moolenbroek DNSSEC keys without any need for the operator to make changes to 1352*00b67f09SDavid van Moolenbroek configuration files.</p> 1353*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 1354*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 1355*00b67f09SDavid van Moolenbroek<a name="id2610708"></a>Validating Resolver</h3></div></div></div> 1356*00b67f09SDavid van Moolenbroek<p>To configure a validating resolver to use RFC 5011 to 1357*00b67f09SDavid van Moolenbroek maintain a trust anchor, configure the trust anchor using a 1358*00b67f09SDavid van Moolenbroek <span><strong class="command">managed-keys</strong></span> statement. Information about 1359*00b67f09SDavid van Moolenbroek this can be found in 1360*00b67f09SDavid van Moolenbroek <a href="Bv9ARM.ch06.html#managed-keys" title="managed-keys Statement Definition 1361*00b67f09SDavid van Moolenbroek and Usage">the section called “<span><strong class="command">managed-keys</strong></span> Statement Definition 1362*00b67f09SDavid van Moolenbroek and Usage”</a>.</p> 1363*00b67f09SDavid van Moolenbroek</div> 1364*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 1365*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 1366*00b67f09SDavid van Moolenbroek<a name="id2610730"></a>Authoritative Server</h3></div></div></div> 1367*00b67f09SDavid van Moolenbroek<p>To set up an authoritative zone for RFC 5011 trust anchor 1368*00b67f09SDavid van Moolenbroek maintenance, generate two (or more) key signing keys (KSKs) for 1369*00b67f09SDavid van Moolenbroek the zone. Sign the zone with one of them; this is the "active" 1370*00b67f09SDavid van Moolenbroek KSK. All KSK's which do not sign the zone are "stand-by" 1371*00b67f09SDavid van Moolenbroek keys.</p> 1372*00b67f09SDavid van Moolenbroek<p>Any validating resolver which is configured to use the 1373*00b67f09SDavid van Moolenbroek active KSK as an RFC 5011-managed trust anchor will take note 1374*00b67f09SDavid van Moolenbroek of the stand-by KSKs in the zone's DNSKEY RRset, and store them 1375*00b67f09SDavid van Moolenbroek for future reference. The resolver will recheck the zone 1376*00b67f09SDavid van Moolenbroek periodically, and after 30 days, if the new key is still there, 1377*00b67f09SDavid van Moolenbroek then the key will be accepted by the resolver as a valid trust 1378*00b67f09SDavid van Moolenbroek anchor for the zone. Any time after this 30-day acceptance 1379*00b67f09SDavid van Moolenbroek timer has completed, the active KSK can be revoked, and the 1380*00b67f09SDavid van Moolenbroek zone can be "rolled over" to the newly accepted key.</p> 1381*00b67f09SDavid van Moolenbroek<p>The easiest way to place a stand-by key in a zone is to 1382*00b67f09SDavid van Moolenbroek use the "smart signing" features of 1383*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-keygen</strong></span> and 1384*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-signzone</strong></span>. If a key with a publication 1385*00b67f09SDavid van Moolenbroek date in the past, but an activation date which is unset or in 1386*00b67f09SDavid van Moolenbroek the future, " 1387*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-signzone -S</strong></span>" will include the DNSKEY 1388*00b67f09SDavid van Moolenbroek record in the zone, but will not sign with it:</p> 1389*00b67f09SDavid van Moolenbroek<pre class="screen"> 1390*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>dnssec-keygen -K keys -f KSK -P now -A now+2y example.net</code></strong> 1391*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>dnssec-signzone -S -K keys example.net</code></strong> 1392*00b67f09SDavid van Moolenbroek</pre> 1393*00b67f09SDavid van Moolenbroek<p>To revoke a key, the new command 1394*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-revoke</strong></span> has been added. This adds the 1395*00b67f09SDavid van Moolenbroek REVOKED bit to the key flags and re-generates the 1396*00b67f09SDavid van Moolenbroek <code class="filename">K*.key</code> and 1397*00b67f09SDavid van Moolenbroek <code class="filename">K*.private</code> files.</p> 1398*00b67f09SDavid van Moolenbroek<p>After revoking the active key, the zone must be signed 1399*00b67f09SDavid van Moolenbroek with both the revoked KSK and the new active KSK. (Smart 1400*00b67f09SDavid van Moolenbroek signing takes care of this automatically.)</p> 1401*00b67f09SDavid van Moolenbroek<p>Once a key has been revoked and used to sign the DNSKEY 1402*00b67f09SDavid van Moolenbroek RRset in which it appears, that key will never again be 1403*00b67f09SDavid van Moolenbroek accepted as a valid trust anchor by the resolver. However, 1404*00b67f09SDavid van Moolenbroek validation can proceed using the new active key (which had been 1405*00b67f09SDavid van Moolenbroek accepted by the resolver when it was a stand-by key).</p> 1406*00b67f09SDavid van Moolenbroek<p>See RFC 5011 for more details on key rollover 1407*00b67f09SDavid van Moolenbroek scenarios.</p> 1408*00b67f09SDavid van Moolenbroek<p>When a key has been revoked, its key ID changes, 1409*00b67f09SDavid van Moolenbroek increasing by 128, and wrapping around at 65535. So, for 1410*00b67f09SDavid van Moolenbroek example, the key "<code class="filename">Kexample.com.+005+10000</code>" becomes 1411*00b67f09SDavid van Moolenbroek "<code class="filename">Kexample.com.+005+10128</code>".</p> 1412*00b67f09SDavid van Moolenbroek<p>If two keys have ID's exactly 128 apart, and one is 1413*00b67f09SDavid van Moolenbroek revoked, then the two key ID's will collide, causing several 1414*00b67f09SDavid van Moolenbroek problems. To prevent this, 1415*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-keygen</strong></span> will not generate a new key if 1416*00b67f09SDavid van Moolenbroek another key is present which may collide. This checking will 1417*00b67f09SDavid van Moolenbroek only occur if the new keys are written to the same directory 1418*00b67f09SDavid van Moolenbroek which holds all other keys in use for that zone.</p> 1419*00b67f09SDavid van Moolenbroek<p>Older versions of BIND 9 did not have this precaution. 1420*00b67f09SDavid van Moolenbroek Exercise caution if using key revocation on keys that were 1421*00b67f09SDavid van Moolenbroek generated by previous releases, or if using keys stored in 1422*00b67f09SDavid van Moolenbroek multiple directories or on multiple machines.</p> 1423*00b67f09SDavid van Moolenbroek<p>It is expected that a future release of BIND 9 will 1424*00b67f09SDavid van Moolenbroek address this problem in a different way, by storing revoked 1425*00b67f09SDavid van Moolenbroek keys with their original unrevoked key ID's.</p> 1426*00b67f09SDavid van Moolenbroek</div> 1427*00b67f09SDavid van Moolenbroek</div> 1428*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 1429*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1430*00b67f09SDavid van Moolenbroek<a name="pkcs11"></a>PKCS#11 (Cryptoki) support</h2></div></div></div> 1431*00b67f09SDavid van Moolenbroek<p> 1432*00b67f09SDavid van Moolenbroek PKCS#11 (Public Key Cryptography Standard #11) defines a 1433*00b67f09SDavid van Moolenbroek platform-independent API for the control of hardware security 1434*00b67f09SDavid van Moolenbroek modules (HSMs) and other cryptographic support devices. 1435*00b67f09SDavid van Moolenbroek </p> 1436*00b67f09SDavid van Moolenbroek<p> 1437*00b67f09SDavid van Moolenbroek BIND 9 is known to work with three HSMs: The AEP Keyper, which has 1438*00b67f09SDavid van Moolenbroek been tested with Debian Linux, Solaris x86 and Windows Server 2003; 1439*00b67f09SDavid van Moolenbroek the Thales nShield, tested with Debian Linux; and the Sun SCA 6000 1440*00b67f09SDavid van Moolenbroek cryptographic acceleration board, tested with Solaris x86. In 1441*00b67f09SDavid van Moolenbroek addition, BIND can be used with all current versions of SoftHSM, 1442*00b67f09SDavid van Moolenbroek a software-based HSM simulator library produced by the OpenDNSSEC 1443*00b67f09SDavid van Moolenbroek project. 1444*00b67f09SDavid van Moolenbroek </p> 1445*00b67f09SDavid van Moolenbroek<p> 1446*00b67f09SDavid van Moolenbroek PKCS#11 makes use of a "provider library": a dynamically loadable 1447*00b67f09SDavid van Moolenbroek library which provides a low-level PKCS#11 interface to drive the HSM 1448*00b67f09SDavid van Moolenbroek hardware. The PKCS#11 provider library comes from the HSM vendor, and 1449*00b67f09SDavid van Moolenbroek it is specific to the HSM to be controlled. 1450*00b67f09SDavid van Moolenbroek </p> 1451*00b67f09SDavid van Moolenbroek<p> 1452*00b67f09SDavid van Moolenbroek There are two available mechanisms for PKCS#11 support in BIND 9: 1453*00b67f09SDavid van Moolenbroek OpenSSL-based PKCS#11 and native PKCS#11. When using the first 1454*00b67f09SDavid van Moolenbroek mechanism, BIND uses a modified version of OpenSSL, which loads 1455*00b67f09SDavid van Moolenbroek the provider library and operates the HSM indirectly; any 1456*00b67f09SDavid van Moolenbroek cryptographic operations not supported by the HSM can be carried 1457*00b67f09SDavid van Moolenbroek out by OpenSSL instead. The second mechanism enables BIND to bypass 1458*00b67f09SDavid van Moolenbroek OpenSSL completely; BIND loads the provider library itself, and uses 1459*00b67f09SDavid van Moolenbroek the PKCS#11 API to drive the HSM directly. 1460*00b67f09SDavid van Moolenbroek </p> 1461*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 1462*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 1463*00b67f09SDavid van Moolenbroek<a name="id2666121"></a>Prerequisites</h3></div></div></div> 1464*00b67f09SDavid van Moolenbroek<p> 1465*00b67f09SDavid van Moolenbroek See the documentation provided by your HSM vendor for 1466*00b67f09SDavid van Moolenbroek information about installing, initializing, testing and 1467*00b67f09SDavid van Moolenbroek troubleshooting the HSM. 1468*00b67f09SDavid van Moolenbroek </p> 1469*00b67f09SDavid van Moolenbroek</div> 1470*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 1471*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 1472*00b67f09SDavid van Moolenbroek<a name="id2666131"></a>Native PKCS#11</h3></div></div></div> 1473*00b67f09SDavid van Moolenbroek<p> 1474*00b67f09SDavid van Moolenbroek Native PKCS#11 mode will only work with an HSM capable of carrying 1475*00b67f09SDavid van Moolenbroek out <span class="emphasis"><em>every</em></span> cryptographic operation BIND 9 may 1476*00b67f09SDavid van Moolenbroek need. The HSM's provider library must have a complete implementation 1477*00b67f09SDavid van Moolenbroek of the PKCS#11 API, so that all these functions are accessible. As of 1478*00b67f09SDavid van Moolenbroek this writing, only the Thales nShield HSM and SoftHSMv2 can be used 1479*00b67f09SDavid van Moolenbroek in this fashion. For other HSMs, including the AEP Keyper, Sun SCA 1480*00b67f09SDavid van Moolenbroek 6000 and older versions of SoftHSM, use OpenSSL-based PKCS#11. 1481*00b67f09SDavid van Moolenbroek (Note: Eventually, when more HSMs become capable of supporting 1482*00b67f09SDavid van Moolenbroek native PKCS#11, it is expected that OpenSSL-based PKCS#11 will 1483*00b67f09SDavid van Moolenbroek be deprecated.) 1484*00b67f09SDavid van Moolenbroek </p> 1485*00b67f09SDavid van Moolenbroek<p> 1486*00b67f09SDavid van Moolenbroek To build BIND with native PKCS#11, configure as follows: 1487*00b67f09SDavid van Moolenbroek </p> 1488*00b67f09SDavid van Moolenbroek<pre class="screen"> 1489*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>cd bind9</code></strong> 1490*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>./configure --enable-native-pkcs11 \ 1491*00b67f09SDavid van Moolenbroek --with-pkcs11=<em class="replaceable"><code>provider-library-path</code></em></code></strong> 1492*00b67f09SDavid van Moolenbroek </pre> 1493*00b67f09SDavid van Moolenbroek<p> 1494*00b67f09SDavid van Moolenbroek This will cause all BIND tools, including <span><strong class="command">named</strong></span> 1495*00b67f09SDavid van Moolenbroek and the <span><strong class="command">dnssec-*</strong></span> and <span><strong class="command">pkcs11-*</strong></span> 1496*00b67f09SDavid van Moolenbroek tools, to use the PKCS#11 provider library specified in 1497*00b67f09SDavid van Moolenbroek <em class="replaceable"><code>provider-library-path</code></em> for cryptography. 1498*00b67f09SDavid van Moolenbroek (The provider library path can be overridden using the 1499*00b67f09SDavid van Moolenbroek <code class="option">-E</code> in <span><strong class="command">named</strong></span> and the 1500*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-*</strong></span> tools, or the <code class="option">-m</code> in 1501*00b67f09SDavid van Moolenbroek the <span><strong class="command">pkcs11-*</strong></span> tools.) 1502*00b67f09SDavid van Moolenbroek </p> 1503*00b67f09SDavid van Moolenbroek<div class="sect3" lang="en"> 1504*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h4 class="title"> 1505*00b67f09SDavid van Moolenbroek<a name="id2610983"></a>Building SoftHSMv2</h4></div></div></div> 1506*00b67f09SDavid van Moolenbroek<p> 1507*00b67f09SDavid van Moolenbroek SoftHSMv2, the latest development version of SoftHSM, is available 1508*00b67f09SDavid van Moolenbroek from 1509*00b67f09SDavid van Moolenbroek <a href="https://github.com/opendnssec/SoftHSMv2" target="_top"> 1510*00b67f09SDavid van Moolenbroek https://github.com/opendnssec/SoftHSMv2 1511*00b67f09SDavid van Moolenbroek </a>. 1512*00b67f09SDavid van Moolenbroek It is a software library developed by the OpenDNSSEC project 1513*00b67f09SDavid van Moolenbroek (<a href="http://www.opendnssec.org" target="_top"> 1514*00b67f09SDavid van Moolenbroek http://www.opendnssec.org 1515*00b67f09SDavid van Moolenbroek </a>) 1516*00b67f09SDavid van Moolenbroek which provides a PKCS#11 interface to a virtual HSM, implemented in 1517*00b67f09SDavid van Moolenbroek the form of a SQLite3 database on the local filesystem. It provides 1518*00b67f09SDavid van Moolenbroek less security than a true HSM, but it allows you to experiment with 1519*00b67f09SDavid van Moolenbroek native PKCS#11 when an HSM is not available. SoftHSMv2 can be 1520*00b67f09SDavid van Moolenbroek configured to use either OpenSSL or the Botan library to perform 1521*00b67f09SDavid van Moolenbroek cryptographic functions, but when using it for native PKCS#11 in 1522*00b67f09SDavid van Moolenbroek BIND, OpenSSL is required. 1523*00b67f09SDavid van Moolenbroek </p> 1524*00b67f09SDavid van Moolenbroek<p> 1525*00b67f09SDavid van Moolenbroek By default, the SoftHSMv2 configuration file is 1526*00b67f09SDavid van Moolenbroek <em class="replaceable"><code>prefix</code></em>/etc/softhsm2.conf (where 1527*00b67f09SDavid van Moolenbroek <em class="replaceable"><code>prefix</code></em> is configured at compile time). 1528*00b67f09SDavid van Moolenbroek This location can be overridden by the SOFTHSM2_CONF environment 1529*00b67f09SDavid van Moolenbroek variable. The SoftHSMv2 cryptographic store must be installed and 1530*00b67f09SDavid van Moolenbroek initialized before using it with BIND. 1531*00b67f09SDavid van Moolenbroek </p> 1532*00b67f09SDavid van Moolenbroek<pre class="screen"> 1533*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> cd SoftHSMv2 </code></strong> 1534*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> configure --with-crypto-backend=openssl --prefix=/opt/pkcs11/usr --enable-gost </code></strong> 1535*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> make </code></strong> 1536*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> make install </code></strong> 1537*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label softhsmv2 </code></strong> 1538*00b67f09SDavid van Moolenbroek </pre> 1539*00b67f09SDavid van Moolenbroek</div> 1540*00b67f09SDavid van Moolenbroek</div> 1541*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 1542*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 1543*00b67f09SDavid van Moolenbroek<a name="id2611390"></a>OpenSSL-based PKCS#11</h3></div></div></div> 1544*00b67f09SDavid van Moolenbroek<p> 1545*00b67f09SDavid van Moolenbroek OpenSSL-based PKCS#11 mode uses a modified version of the 1546*00b67f09SDavid van Moolenbroek OpenSSL library; stock OpenSSL does not fully support PKCS#11. 1547*00b67f09SDavid van Moolenbroek ISC provides a patch to OpenSSL to correct this. This patch is 1548*00b67f09SDavid van Moolenbroek based on work originally done by the OpenSolaris project; it has been 1549*00b67f09SDavid van Moolenbroek modified by ISC to provide new features such as PIN management and 1550*00b67f09SDavid van Moolenbroek key-by-reference. 1551*00b67f09SDavid van Moolenbroek </p> 1552*00b67f09SDavid van Moolenbroek<p> 1553*00b67f09SDavid van Moolenbroek There are two "flavors" of PKCS#11 support provided by 1554*00b67f09SDavid van Moolenbroek the patched OpenSSL, one of which must be chosen at 1555*00b67f09SDavid van Moolenbroek configuration time. The correct choice depends on the HSM 1556*00b67f09SDavid van Moolenbroek hardware: 1557*00b67f09SDavid van Moolenbroek </p> 1558*00b67f09SDavid van Moolenbroek<div class="itemizedlist"><ul type="disc"> 1559*00b67f09SDavid van Moolenbroek<li><p> 1560*00b67f09SDavid van Moolenbroek Use 'crypto-accelerator' with HSMs that have hardware 1561*00b67f09SDavid van Moolenbroek cryptographic acceleration features, such as the SCA 6000 1562*00b67f09SDavid van Moolenbroek board. This causes OpenSSL to run all supported 1563*00b67f09SDavid van Moolenbroek cryptographic operations in the HSM. 1564*00b67f09SDavid van Moolenbroek </p></li> 1565*00b67f09SDavid van Moolenbroek<li><p> 1566*00b67f09SDavid van Moolenbroek Use 'sign-only' with HSMs that are designed to 1567*00b67f09SDavid van Moolenbroek function primarily as secure key storage devices, but lack 1568*00b67f09SDavid van Moolenbroek hardware acceleration. These devices are highly secure, but 1569*00b67f09SDavid van Moolenbroek are not necessarily any faster at cryptography than the 1570*00b67f09SDavid van Moolenbroek system CPU — often, they are slower. It is therefore 1571*00b67f09SDavid van Moolenbroek most efficient to use them only for those cryptographic 1572*00b67f09SDavid van Moolenbroek functions that require access to the secured private key, 1573*00b67f09SDavid van Moolenbroek such as zone signing, and to use the system CPU for all 1574*00b67f09SDavid van Moolenbroek other computationally-intensive operations. The AEP Keyper 1575*00b67f09SDavid van Moolenbroek is an example of such a device. 1576*00b67f09SDavid van Moolenbroek </p></li> 1577*00b67f09SDavid van Moolenbroek</ul></div> 1578*00b67f09SDavid van Moolenbroek<p> 1579*00b67f09SDavid van Moolenbroek The modified OpenSSL code is included in the BIND 9 release, 1580*00b67f09SDavid van Moolenbroek in the form of a context diff against the latest versions of 1581*00b67f09SDavid van Moolenbroek OpenSSL. OpenSSL 0.9.8, 1.0.0, and 1.0.1 are supported; there are 1582*00b67f09SDavid van Moolenbroek separate diffs for each version. In the examples to follow, 1583*00b67f09SDavid van Moolenbroek we use OpenSSL 0.9.8, but the same methods work with OpenSSL 1584*00b67f09SDavid van Moolenbroek 1.0.0 and 1.0.1. 1585*00b67f09SDavid van Moolenbroek </p> 1586*00b67f09SDavid van Moolenbroek<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 1587*00b67f09SDavid van Moolenbroek<h3 class="title">Note</h3> 1588*00b67f09SDavid van Moolenbroek The latest OpenSSL versions as of this writing (January 2015) 1589*00b67f09SDavid van Moolenbroek are 0.9.8zc, 1.0.0o, and 1.0.1j. 1590*00b67f09SDavid van Moolenbroek ISC will provide updated patches as new versions of OpenSSL 1591*00b67f09SDavid van Moolenbroek are released. The version number in the following examples 1592*00b67f09SDavid van Moolenbroek is expected to change. 1593*00b67f09SDavid van Moolenbroek </div> 1594*00b67f09SDavid van Moolenbroek<p> 1595*00b67f09SDavid van Moolenbroek Before building BIND 9 with PKCS#11 support, it will be 1596*00b67f09SDavid van Moolenbroek necessary to build OpenSSL with the patch in place, and configure 1597*00b67f09SDavid van Moolenbroek it with the path to your HSM's PKCS#11 provider library. 1598*00b67f09SDavid van Moolenbroek </p> 1599*00b67f09SDavid van Moolenbroek<div class="sect3" lang="en"> 1600*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h4 class="title"> 1601*00b67f09SDavid van Moolenbroek<a name="id2611564"></a>Patching OpenSSL</h4></div></div></div> 1602*00b67f09SDavid van Moolenbroek<pre class="screen"> 1603*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>wget <a href="" target="_top">http://www.openssl.org/source/openssl-0.9.8zc.tar.gz</a></code></strong> 1604*00b67f09SDavid van Moolenbroek </pre> 1605*00b67f09SDavid van Moolenbroek<p>Extract the tarball:</p> 1606*00b67f09SDavid van Moolenbroek<pre class="screen"> 1607*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>tar zxf openssl-0.9.8zc.tar.gz</code></strong> 1608*00b67f09SDavid van Moolenbroek</pre> 1609*00b67f09SDavid van Moolenbroek<p>Apply the patch from the BIND 9 release:</p> 1610*00b67f09SDavid van Moolenbroek<pre class="screen"> 1611*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>patch -p1 -d openssl-0.9.8zc \ 1612*00b67f09SDavid van Moolenbroek < bind9/bin/pkcs11/openssl-0.9.8zc-patch</code></strong> 1613*00b67f09SDavid van Moolenbroek</pre> 1614*00b67f09SDavid van Moolenbroek<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 1615*00b67f09SDavid van Moolenbroek<h3 class="title">Note</h3> 1616*00b67f09SDavid van Moolenbroek Note that the patch file may not be compatible with the 1617*00b67f09SDavid van Moolenbroek "patch" utility on all operating systems. You may need to 1618*00b67f09SDavid van Moolenbroek install GNU patch. 1619*00b67f09SDavid van Moolenbroek </div> 1620*00b67f09SDavid van Moolenbroek<p> 1621*00b67f09SDavid van Moolenbroek When building OpenSSL, place it in a non-standard 1622*00b67f09SDavid van Moolenbroek location so that it does not interfere with OpenSSL libraries 1623*00b67f09SDavid van Moolenbroek elsewhere on the system. In the following examples, we choose 1624*00b67f09SDavid van Moolenbroek to install into "/opt/pkcs11/usr". We will use this location 1625*00b67f09SDavid van Moolenbroek when we configure BIND 9. 1626*00b67f09SDavid van Moolenbroek </p> 1627*00b67f09SDavid van Moolenbroek<p> 1628*00b67f09SDavid van Moolenbroek Later, when building BIND 9, the location of the custom-built 1629*00b67f09SDavid van Moolenbroek OpenSSL library will need to be specified via configure. 1630*00b67f09SDavid van Moolenbroek </p> 1631*00b67f09SDavid van Moolenbroek</div> 1632*00b67f09SDavid van Moolenbroek<div class="sect3" lang="en"> 1633*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h4 class="title"> 1634*00b67f09SDavid van Moolenbroek<a name="id2611760"></a>Building OpenSSL for the AEP Keyper on Linux</h4></div></div></div> 1635*00b67f09SDavid van Moolenbroek<p> 1636*00b67f09SDavid van Moolenbroek The AEP Keyper is a highly secure key storage device, 1637*00b67f09SDavid van Moolenbroek but does not provide hardware cryptographic acceleration. It 1638*00b67f09SDavid van Moolenbroek can carry out cryptographic operations, but it is probably 1639*00b67f09SDavid van Moolenbroek slower than your system's CPU. Therefore, we choose the 1640*00b67f09SDavid van Moolenbroek 'sign-only' flavor when building OpenSSL. 1641*00b67f09SDavid van Moolenbroek </p> 1642*00b67f09SDavid van Moolenbroek<p> 1643*00b67f09SDavid van Moolenbroek The Keyper-specific PKCS#11 provider library is 1644*00b67f09SDavid van Moolenbroek delivered with the Keyper software. In this example, we place 1645*00b67f09SDavid van Moolenbroek it /opt/pkcs11/usr/lib: 1646*00b67f09SDavid van Moolenbroek </p> 1647*00b67f09SDavid van Moolenbroek<pre class="screen"> 1648*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</code></strong> 1649*00b67f09SDavid van Moolenbroek</pre> 1650*00b67f09SDavid van Moolenbroek<p> 1651*00b67f09SDavid van Moolenbroek This library is only available for Linux as a 32-bit 1652*00b67f09SDavid van Moolenbroek binary. If we are compiling on a 64-bit Linux system, it is 1653*00b67f09SDavid van Moolenbroek necessary to force a 32-bit build, by specifying -m32 in the 1654*00b67f09SDavid van Moolenbroek build options. 1655*00b67f09SDavid van Moolenbroek </p> 1656*00b67f09SDavid van Moolenbroek<p> 1657*00b67f09SDavid van Moolenbroek Finally, the Keyper library requires threads, so we 1658*00b67f09SDavid van Moolenbroek must specify -pthread. 1659*00b67f09SDavid van Moolenbroek </p> 1660*00b67f09SDavid van Moolenbroek<pre class="screen"> 1661*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>cd openssl-0.9.8zc</code></strong> 1662*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>./Configure linux-generic32 -m32 -pthread \ 1663*00b67f09SDavid van Moolenbroek --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \ 1664*00b67f09SDavid van Moolenbroek --pk11-flavor=sign-only \ 1665*00b67f09SDavid van Moolenbroek --prefix=/opt/pkcs11/usr</code></strong> 1666*00b67f09SDavid van Moolenbroek</pre> 1667*00b67f09SDavid van Moolenbroek<p> 1668*00b67f09SDavid van Moolenbroek After configuring, run "<span><strong class="command">make</strong></span>" 1669*00b67f09SDavid van Moolenbroek and "<span><strong class="command">make test</strong></span>". If "<span><strong class="command">make 1670*00b67f09SDavid van Moolenbroek test</strong></span>" fails with "pthread_atfork() not found", you forgot to 1671*00b67f09SDavid van Moolenbroek add the -pthread above. 1672*00b67f09SDavid van Moolenbroek </p> 1673*00b67f09SDavid van Moolenbroek</div> 1674*00b67f09SDavid van Moolenbroek<div class="sect3" lang="en"> 1675*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h4 class="title"> 1676*00b67f09SDavid van Moolenbroek<a name="id2611829"></a>Building OpenSSL for the SCA 6000 on Solaris</h4></div></div></div> 1677*00b67f09SDavid van Moolenbroek<p> 1678*00b67f09SDavid van Moolenbroek The SCA-6000 PKCS#11 provider is installed as a system 1679*00b67f09SDavid van Moolenbroek library, libpkcs11. It is a true crypto accelerator, up to 4 1680*00b67f09SDavid van Moolenbroek times faster than any CPU, so the flavor shall be 1681*00b67f09SDavid van Moolenbroek 'crypto-accelerator'. 1682*00b67f09SDavid van Moolenbroek </p> 1683*00b67f09SDavid van Moolenbroek<p> 1684*00b67f09SDavid van Moolenbroek In this example, we are building on Solaris x86 on an 1685*00b67f09SDavid van Moolenbroek AMD64 system. 1686*00b67f09SDavid van Moolenbroek </p> 1687*00b67f09SDavid van Moolenbroek<pre class="screen"> 1688*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>cd openssl-0.9.8zc</code></strong> 1689*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>./Configure solaris64-x86_64-cc \ 1690*00b67f09SDavid van Moolenbroek --pk11-libname=/usr/lib/64/libpkcs11.so \ 1691*00b67f09SDavid van Moolenbroek --pk11-flavor=crypto-accelerator \ 1692*00b67f09SDavid van Moolenbroek --prefix=/opt/pkcs11/usr</code></strong> 1693*00b67f09SDavid van Moolenbroek</pre> 1694*00b67f09SDavid van Moolenbroek<p> 1695*00b67f09SDavid van Moolenbroek (For a 32-bit build, use "solaris-x86-cc" and /usr/lib/libpkcs11.so.) 1696*00b67f09SDavid van Moolenbroek </p> 1697*00b67f09SDavid van Moolenbroek<p> 1698*00b67f09SDavid van Moolenbroek After configuring, run 1699*00b67f09SDavid van Moolenbroek <span><strong class="command">make</strong></span> and 1700*00b67f09SDavid van Moolenbroek <span><strong class="command">make test</strong></span>. 1701*00b67f09SDavid van Moolenbroek </p> 1702*00b67f09SDavid van Moolenbroek</div> 1703*00b67f09SDavid van Moolenbroek<div class="sect3" lang="en"> 1704*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h4 class="title"> 1705*00b67f09SDavid van Moolenbroek<a name="id2611878"></a>Building OpenSSL for SoftHSM</h4></div></div></div> 1706*00b67f09SDavid van Moolenbroek<p> 1707*00b67f09SDavid van Moolenbroek SoftHSM (version 1) is a software library developed by the 1708*00b67f09SDavid van Moolenbroek OpenDNSSEC project 1709*00b67f09SDavid van Moolenbroek (<a href="http://www.opendnssec.org" target="_top"> 1710*00b67f09SDavid van Moolenbroek http://www.opendnssec.org 1711*00b67f09SDavid van Moolenbroek </a>) 1712*00b67f09SDavid van Moolenbroek which provides a 1713*00b67f09SDavid van Moolenbroek PKCS#11 interface to a virtual HSM, implemented in the form of 1714*00b67f09SDavid van Moolenbroek a SQLite3 database on the local filesystem. SoftHSM uses 1715*00b67f09SDavid van Moolenbroek the Botan library to perform cryptographic functions. Though 1716*00b67f09SDavid van Moolenbroek less secure than a true HSM, it can allow you to experiment 1717*00b67f09SDavid van Moolenbroek with PKCS#11 when an HSM is not available. 1718*00b67f09SDavid van Moolenbroek </p> 1719*00b67f09SDavid van Moolenbroek<p> 1720*00b67f09SDavid van Moolenbroek The SoftHSM cryptographic store must be installed and 1721*00b67f09SDavid van Moolenbroek initialized before using it with OpenSSL, and the SOFTHSM_CONF 1722*00b67f09SDavid van Moolenbroek environment variable must always point to the SoftHSM configuration 1723*00b67f09SDavid van Moolenbroek file: 1724*00b67f09SDavid van Moolenbroek </p> 1725*00b67f09SDavid van Moolenbroek<pre class="screen"> 1726*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> cd softhsm-1.3.7 </code></strong> 1727*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> configure --prefix=/opt/pkcs11/usr </code></strong> 1728*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> make </code></strong> 1729*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> make install </code></strong> 1730*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </code></strong> 1731*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </code></strong> 1732*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </code></strong> 1733*00b67f09SDavid van Moolenbroek</pre> 1734*00b67f09SDavid van Moolenbroek<p> 1735*00b67f09SDavid van Moolenbroek SoftHSM can perform all cryptographic operations, but 1736*00b67f09SDavid van Moolenbroek since it only uses your system CPU, there is no advantage to using 1737*00b67f09SDavid van Moolenbroek it for anything but signing. Therefore, we choose the 'sign-only' 1738*00b67f09SDavid van Moolenbroek flavor when building OpenSSL. 1739*00b67f09SDavid van Moolenbroek </p> 1740*00b67f09SDavid van Moolenbroek<pre class="screen"> 1741*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>cd openssl-0.9.8zc</code></strong> 1742*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>./Configure linux-x86_64 -pthread \ 1743*00b67f09SDavid van Moolenbroek --pk11-libname=/opt/pkcs11/usr/lib/libsofthsm.so \ 1744*00b67f09SDavid van Moolenbroek --pk11-flavor=sign-only \ 1745*00b67f09SDavid van Moolenbroek --prefix=/opt/pkcs11/usr</code></strong> 1746*00b67f09SDavid van Moolenbroek</pre> 1747*00b67f09SDavid van Moolenbroek<p> 1748*00b67f09SDavid van Moolenbroek After configuring, run "<span><strong class="command">make</strong></span>" 1749*00b67f09SDavid van Moolenbroek and "<span><strong class="command">make test</strong></span>". 1750*00b67f09SDavid van Moolenbroek </p> 1751*00b67f09SDavid van Moolenbroek</div> 1752*00b67f09SDavid van Moolenbroek<p> 1753*00b67f09SDavid van Moolenbroek Once you have built OpenSSL, run 1754*00b67f09SDavid van Moolenbroek "<span><strong class="command">apps/openssl engine pkcs11</strong></span>" to confirm 1755*00b67f09SDavid van Moolenbroek that PKCS#11 support was compiled in correctly. The output 1756*00b67f09SDavid van Moolenbroek should be one of the following lines, depending on the flavor 1757*00b67f09SDavid van Moolenbroek selected: 1758*00b67f09SDavid van Moolenbroek </p> 1759*00b67f09SDavid van Moolenbroek<pre class="screen"> 1760*00b67f09SDavid van Moolenbroek (pkcs11) PKCS #11 engine support (sign only) 1761*00b67f09SDavid van Moolenbroek</pre> 1762*00b67f09SDavid van Moolenbroek<p>Or:</p> 1763*00b67f09SDavid van Moolenbroek<pre class="screen"> 1764*00b67f09SDavid van Moolenbroek (pkcs11) PKCS #11 engine support (crypto accelerator) 1765*00b67f09SDavid van Moolenbroek</pre> 1766*00b67f09SDavid van Moolenbroek<p> 1767*00b67f09SDavid van Moolenbroek Next, run 1768*00b67f09SDavid van Moolenbroek "<span><strong class="command">apps/openssl engine pkcs11 -t</strong></span>". This will 1769*00b67f09SDavid van Moolenbroek attempt to initialize the PKCS#11 engine. If it is able to 1770*00b67f09SDavid van Moolenbroek do so successfully, it will report 1771*00b67f09SDavid van Moolenbroek “<span class="quote"><code class="literal">[ available ]</code></span>”. 1772*00b67f09SDavid van Moolenbroek </p> 1773*00b67f09SDavid van Moolenbroek<p> 1774*00b67f09SDavid van Moolenbroek If the output is correct, run 1775*00b67f09SDavid van Moolenbroek "<span><strong class="command">make install</strong></span>" which will install the 1776*00b67f09SDavid van Moolenbroek modified OpenSSL suite to <code class="filename">/opt/pkcs11/usr</code>. 1777*00b67f09SDavid van Moolenbroek </p> 1778*00b67f09SDavid van Moolenbroek<div class="sect3" lang="en"> 1779*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h4 class="title"> 1780*00b67f09SDavid van Moolenbroek<a name="id2638385"></a>Configuring BIND 9 for Linux with the AEP Keyper</h4></div></div></div> 1781*00b67f09SDavid van Moolenbroek<p> 1782*00b67f09SDavid van Moolenbroek To link with the PKCS#11 provider, threads must be 1783*00b67f09SDavid van Moolenbroek enabled in the BIND 9 build. 1784*00b67f09SDavid van Moolenbroek </p> 1785*00b67f09SDavid van Moolenbroek<p> 1786*00b67f09SDavid van Moolenbroek The PKCS#11 library for the AEP Keyper is currently 1787*00b67f09SDavid van Moolenbroek only available as a 32-bit binary. If we are building on a 1788*00b67f09SDavid van Moolenbroek 64-bit host, we must force a 32-bit build by adding "-m32" to 1789*00b67f09SDavid van Moolenbroek the CC options on the "configure" command line. 1790*00b67f09SDavid van Moolenbroek </p> 1791*00b67f09SDavid van Moolenbroek<pre class="screen"> 1792*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>cd ../bind9</code></strong> 1793*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>./configure CC="gcc -m32" --enable-threads \ 1794*00b67f09SDavid van Moolenbroek --with-openssl=/opt/pkcs11/usr \ 1795*00b67f09SDavid van Moolenbroek --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</code></strong> 1796*00b67f09SDavid van Moolenbroek</pre> 1797*00b67f09SDavid van Moolenbroek</div> 1798*00b67f09SDavid van Moolenbroek<div class="sect3" lang="en"> 1799*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h4 class="title"> 1800*00b67f09SDavid van Moolenbroek<a name="id2638417"></a>Configuring BIND 9 for Solaris with the SCA 6000</h4></div></div></div> 1801*00b67f09SDavid van Moolenbroek<p> 1802*00b67f09SDavid van Moolenbroek To link with the PKCS#11 provider, threads must be 1803*00b67f09SDavid van Moolenbroek enabled in the BIND 9 build. 1804*00b67f09SDavid van Moolenbroek </p> 1805*00b67f09SDavid van Moolenbroek<pre class="screen"> 1806*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>cd ../bind9</code></strong> 1807*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>./configure CC="cc -xarch=amd64" --enable-threads \ 1808*00b67f09SDavid van Moolenbroek --with-openssl=/opt/pkcs11/usr \ 1809*00b67f09SDavid van Moolenbroek --with-pkcs11=/usr/lib/64/libpkcs11.so</code></strong> 1810*00b67f09SDavid van Moolenbroek</pre> 1811*00b67f09SDavid van Moolenbroek<p>(For a 32-bit build, omit CC="cc -xarch=amd64".)</p> 1812*00b67f09SDavid van Moolenbroek<p> 1813*00b67f09SDavid van Moolenbroek If configure complains about OpenSSL not working, you 1814*00b67f09SDavid van Moolenbroek may have a 32/64-bit architecture mismatch. Or, you may have 1815*00b67f09SDavid van Moolenbroek incorrectly specified the path to OpenSSL (it should be the 1816*00b67f09SDavid van Moolenbroek same as the --prefix argument to the OpenSSL 1817*00b67f09SDavid van Moolenbroek Configure). 1818*00b67f09SDavid van Moolenbroek </p> 1819*00b67f09SDavid van Moolenbroek</div> 1820*00b67f09SDavid van Moolenbroek<div class="sect3" lang="en"> 1821*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h4 class="title"> 1822*00b67f09SDavid van Moolenbroek<a name="id2638521"></a>Configuring BIND 9 for SoftHSM</h4></div></div></div> 1823*00b67f09SDavid van Moolenbroek<pre class="screen"> 1824*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>cd ../bind9</code></strong> 1825*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>./configure --enable-threads \ 1826*00b67f09SDavid van Moolenbroek --with-openssl=/opt/pkcs11/usr \ 1827*00b67f09SDavid van Moolenbroek --with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so</code></strong> 1828*00b67f09SDavid van Moolenbroek</pre> 1829*00b67f09SDavid van Moolenbroek</div> 1830*00b67f09SDavid van Moolenbroek<p> 1831*00b67f09SDavid van Moolenbroek After configuring, run 1832*00b67f09SDavid van Moolenbroek "<span><strong class="command">make</strong></span>", 1833*00b67f09SDavid van Moolenbroek "<span><strong class="command">make test</strong></span>" and 1834*00b67f09SDavid van Moolenbroek "<span><strong class="command">make install</strong></span>". 1835*00b67f09SDavid van Moolenbroek </p> 1836*00b67f09SDavid van Moolenbroek<p> 1837*00b67f09SDavid van Moolenbroek (Note: If "make test" fails in the "pkcs11" system test, you may 1838*00b67f09SDavid van Moolenbroek have forgotten to set the SOFTHSM_CONF environment variable.) 1839*00b67f09SDavid van Moolenbroek </p> 1840*00b67f09SDavid van Moolenbroek</div> 1841*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 1842*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 1843*00b67f09SDavid van Moolenbroek<a name="id2638570"></a>PKCS#11 Tools</h3></div></div></div> 1844*00b67f09SDavid van Moolenbroek<p> 1845*00b67f09SDavid van Moolenbroek BIND 9 includes a minimal set of tools to operate the 1846*00b67f09SDavid van Moolenbroek HSM, including 1847*00b67f09SDavid van Moolenbroek <span><strong class="command">pkcs11-keygen</strong></span> to generate a new key pair 1848*00b67f09SDavid van Moolenbroek within the HSM, 1849*00b67f09SDavid van Moolenbroek <span><strong class="command">pkcs11-list</strong></span> to list objects currently 1850*00b67f09SDavid van Moolenbroek available, 1851*00b67f09SDavid van Moolenbroek <span><strong class="command">pkcs11-destroy</strong></span> to remove objects, and 1852*00b67f09SDavid van Moolenbroek <span><strong class="command">pkcs11-tokens</strong></span> to list available tokens. 1853*00b67f09SDavid van Moolenbroek </p> 1854*00b67f09SDavid van Moolenbroek<p> 1855*00b67f09SDavid van Moolenbroek In UNIX/Linux builds, these tools are built only if BIND 1856*00b67f09SDavid van Moolenbroek 9 is configured with the --with-pkcs11 option. (Note: If 1857*00b67f09SDavid van Moolenbroek --with-pkcs11 is set to "yes", rather than to the path of the 1858*00b67f09SDavid van Moolenbroek PKCS#11 provider, then the tools will be built but the 1859*00b67f09SDavid van Moolenbroek provider will be left undefined. Use the -m option or the 1860*00b67f09SDavid van Moolenbroek PKCS11_PROVIDER environment variable to specify the path to the 1861*00b67f09SDavid van Moolenbroek provider.) 1862*00b67f09SDavid van Moolenbroek </p> 1863*00b67f09SDavid van Moolenbroek</div> 1864*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 1865*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 1866*00b67f09SDavid van Moolenbroek<a name="id2638606"></a>Using the HSM</h3></div></div></div> 1867*00b67f09SDavid van Moolenbroek<p> 1868*00b67f09SDavid van Moolenbroek For OpenSSL-based PKCS#11, we must first set up the runtime 1869*00b67f09SDavid van Moolenbroek environment so the OpenSSL and PKCS#11 libraries can be loaded: 1870*00b67f09SDavid van Moolenbroek </p> 1871*00b67f09SDavid van Moolenbroek<pre class="screen"> 1872*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</code></strong> 1873*00b67f09SDavid van Moolenbroek</pre> 1874*00b67f09SDavid van Moolenbroek<p> 1875*00b67f09SDavid van Moolenbroek This causes <span><strong class="command">named</strong></span> and other binaries to load 1876*00b67f09SDavid van Moolenbroek the OpenSSL library from <code class="filename">/opt/pkcs11/usr/lib</code> 1877*00b67f09SDavid van Moolenbroek rather than from the default location. This step is not necessary 1878*00b67f09SDavid van Moolenbroek when using native PKCS#11. 1879*00b67f09SDavid van Moolenbroek </p> 1880*00b67f09SDavid van Moolenbroek<p> 1881*00b67f09SDavid van Moolenbroek Some HSMs require other environment variables to be set. 1882*00b67f09SDavid van Moolenbroek For example, when operating an AEP Keyper, it is necessary to 1883*00b67f09SDavid van Moolenbroek specify the location of the "machine" file, which stores 1884*00b67f09SDavid van Moolenbroek information about the Keyper for use by the provider 1885*00b67f09SDavid van Moolenbroek library. If the machine file is in 1886*00b67f09SDavid van Moolenbroek <code class="filename">/opt/Keyper/PKCS11Provider/machine</code>, 1887*00b67f09SDavid van Moolenbroek use: 1888*00b67f09SDavid van Moolenbroek </p> 1889*00b67f09SDavid van Moolenbroek<pre class="screen"> 1890*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</code></strong> 1891*00b67f09SDavid van Moolenbroek</pre> 1892*00b67f09SDavid van Moolenbroek<p> 1893*00b67f09SDavid van Moolenbroek Such environment variables must be set whenever running 1894*00b67f09SDavid van Moolenbroek any tool that uses the HSM, including 1895*00b67f09SDavid van Moolenbroek <span><strong class="command">pkcs11-keygen</strong></span>, 1896*00b67f09SDavid van Moolenbroek <span><strong class="command">pkcs11-list</strong></span>, 1897*00b67f09SDavid van Moolenbroek <span><strong class="command">pkcs11-destroy</strong></span>, 1898*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-keyfromlabel</strong></span>, 1899*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-signzone</strong></span>, 1900*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-keygen</strong></span>, and 1901*00b67f09SDavid van Moolenbroek <span><strong class="command">named</strong></span>. 1902*00b67f09SDavid van Moolenbroek </p> 1903*00b67f09SDavid van Moolenbroek<p> 1904*00b67f09SDavid van Moolenbroek We can now create and use keys in the HSM. In this case, 1905*00b67f09SDavid van Moolenbroek we will create a 2048 bit key and give it the label 1906*00b67f09SDavid van Moolenbroek "sample-ksk": 1907*00b67f09SDavid van Moolenbroek </p> 1908*00b67f09SDavid van Moolenbroek<pre class="screen"> 1909*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>pkcs11-keygen -b 2048 -l sample-ksk</code></strong> 1910*00b67f09SDavid van Moolenbroek</pre> 1911*00b67f09SDavid van Moolenbroek<p>To confirm that the key exists:</p> 1912*00b67f09SDavid van Moolenbroek<pre class="screen"> 1913*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>pkcs11-list</code></strong> 1914*00b67f09SDavid van MoolenbroekEnter PIN: 1915*00b67f09SDavid van Moolenbroekobject[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0] 1916*00b67f09SDavid van Moolenbroekobject[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0] 1917*00b67f09SDavid van Moolenbroek</pre> 1918*00b67f09SDavid van Moolenbroek<p> 1919*00b67f09SDavid van Moolenbroek Before using this key to sign a zone, we must create a 1920*00b67f09SDavid van Moolenbroek pair of BIND 9 key files. The "dnssec-keyfromlabel" utility 1921*00b67f09SDavid van Moolenbroek does this. In this case, we will be using the HSM key 1922*00b67f09SDavid van Moolenbroek "sample-ksk" as the key-signing key for "example.net": 1923*00b67f09SDavid van Moolenbroek </p> 1924*00b67f09SDavid van Moolenbroek<pre class="screen"> 1925*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</code></strong> 1926*00b67f09SDavid van Moolenbroek</pre> 1927*00b67f09SDavid van Moolenbroek<p> 1928*00b67f09SDavid van Moolenbroek The resulting K*.key and K*.private files can now be used 1929*00b67f09SDavid van Moolenbroek to sign the zone. Unlike normal K* files, which contain both 1930*00b67f09SDavid van Moolenbroek public and private key data, these files will contain only the 1931*00b67f09SDavid van Moolenbroek public key data, plus an identifier for the private key which 1932*00b67f09SDavid van Moolenbroek remains stored within the HSM. Signing with the private key takes 1933*00b67f09SDavid van Moolenbroek place inside the HSM. 1934*00b67f09SDavid van Moolenbroek </p> 1935*00b67f09SDavid van Moolenbroek<p> 1936*00b67f09SDavid van Moolenbroek If you wish to generate a second key in the HSM for use 1937*00b67f09SDavid van Moolenbroek as a zone-signing key, follow the same procedure above, using a 1938*00b67f09SDavid van Moolenbroek different keylabel, a smaller key size, and omitting "-f KSK" 1939*00b67f09SDavid van Moolenbroek from the dnssec-keyfromlabel arguments: 1940*00b67f09SDavid van Moolenbroek </p> 1941*00b67f09SDavid van Moolenbroek<p> 1942*00b67f09SDavid van Moolenbroek (Note: When using OpenSSL-based PKCS#11 the label is an arbitrary 1943*00b67f09SDavid van Moolenbroek string which identifies the key. With native PKCS#11, the label is 1944*00b67f09SDavid van Moolenbroek a PKCS#11 URI string which may include other details about the key 1945*00b67f09SDavid van Moolenbroek and the HSM, including its PIN. See 1946*00b67f09SDavid van Moolenbroek <a href="man.dnssec-keyfromlabel.html" title="dnssec-keyfromlabel"><span class="refentrytitle"><span class="application">dnssec-keyfromlabel</span></span>(8)</a> for details.) 1947*00b67f09SDavid van Moolenbroek </p> 1948*00b67f09SDavid van Moolenbroek<pre class="screen"> 1949*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>pkcs11-keygen -b 1024 -l sample-zsk</code></strong> 1950*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>dnssec-keyfromlabel -l sample-zsk example.net</code></strong> 1951*00b67f09SDavid van Moolenbroek</pre> 1952*00b67f09SDavid van Moolenbroek<p> 1953*00b67f09SDavid van Moolenbroek Alternatively, you may prefer to generate a conventional 1954*00b67f09SDavid van Moolenbroek on-disk key, using dnssec-keygen: 1955*00b67f09SDavid van Moolenbroek </p> 1956*00b67f09SDavid van Moolenbroek<pre class="screen"> 1957*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>dnssec-keygen example.net</code></strong> 1958*00b67f09SDavid van Moolenbroek</pre> 1959*00b67f09SDavid van Moolenbroek<p> 1960*00b67f09SDavid van Moolenbroek This provides less security than an HSM key, but since 1961*00b67f09SDavid van Moolenbroek HSMs can be slow or cumbersome to use for security reasons, it 1962*00b67f09SDavid van Moolenbroek may be more efficient to reserve HSM keys for use in the less 1963*00b67f09SDavid van Moolenbroek frequent key-signing operation. The zone-signing key can be 1964*00b67f09SDavid van Moolenbroek rolled more frequently, if you wish, to compensate for a 1965*00b67f09SDavid van Moolenbroek reduction in key security. (Note: When using native PKCS#11, 1966*00b67f09SDavid van Moolenbroek there is no speed advantage to using on-disk keys, as cryptographic 1967*00b67f09SDavid van Moolenbroek operations will be done by the HSM regardless.) 1968*00b67f09SDavid van Moolenbroek </p> 1969*00b67f09SDavid van Moolenbroek<p> 1970*00b67f09SDavid van Moolenbroek Now you can sign the zone. (Note: If not using the -S 1971*00b67f09SDavid van Moolenbroek option to <span><strong class="command">dnssec-signzone</strong></span>, it will be 1972*00b67f09SDavid van Moolenbroek necessary to add the contents of both <code class="filename">K*.key</code> 1973*00b67f09SDavid van Moolenbroek files to the zone master file before signing it.) 1974*00b67f09SDavid van Moolenbroek </p> 1975*00b67f09SDavid van Moolenbroek<pre class="screen"> 1976*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>dnssec-signzone -S example.net</code></strong> 1977*00b67f09SDavid van MoolenbroekEnter PIN: 1978*00b67f09SDavid van MoolenbroekVerifying the zone using the following algorithms: 1979*00b67f09SDavid van MoolenbroekNSEC3RSASHA1. 1980*00b67f09SDavid van MoolenbroekZone signing complete: 1981*00b67f09SDavid van MoolenbroekAlgorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by 1982*00b67f09SDavid van Moolenbroekexample.net.signed 1983*00b67f09SDavid van Moolenbroek</pre> 1984*00b67f09SDavid van Moolenbroek</div> 1985*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 1986*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 1987*00b67f09SDavid van Moolenbroek<a name="id2638892"></a>Specifying the engine on the command line</h3></div></div></div> 1988*00b67f09SDavid van Moolenbroek<p> 1989*00b67f09SDavid van Moolenbroek When using OpenSSL-based PKCS#11, the "engine" to be used by 1990*00b67f09SDavid van Moolenbroek OpenSSL can be specified in <span><strong class="command">named</strong></span> and all of 1991*00b67f09SDavid van Moolenbroek the BIND <span><strong class="command">dnssec-*</strong></span> tools by using the "-E 1992*00b67f09SDavid van Moolenbroek <engine>" command line option. If BIND 9 is built with 1993*00b67f09SDavid van Moolenbroek the --with-pkcs11 option, this option defaults to "pkcs11". 1994*00b67f09SDavid van Moolenbroek Specifying the engine will generally not be necessary unless 1995*00b67f09SDavid van Moolenbroek for some reason you wish to use a different OpenSSL 1996*00b67f09SDavid van Moolenbroek engine. 1997*00b67f09SDavid van Moolenbroek </p> 1998*00b67f09SDavid van Moolenbroek<p> 1999*00b67f09SDavid van Moolenbroek If you wish to disable use of the "pkcs11" engine — 2000*00b67f09SDavid van Moolenbroek for troubleshooting purposes, or because the HSM is unavailable 2001*00b67f09SDavid van Moolenbroek — set the engine to the empty string. For example: 2002*00b67f09SDavid van Moolenbroek </p> 2003*00b67f09SDavid van Moolenbroek<pre class="screen"> 2004*00b67f09SDavid van Moolenbroek$ <strong class="userinput"><code>dnssec-signzone -E '' -S example.net</code></strong> 2005*00b67f09SDavid van Moolenbroek</pre> 2006*00b67f09SDavid van Moolenbroek<p> 2007*00b67f09SDavid van Moolenbroek This causes 2008*00b67f09SDavid van Moolenbroek <span><strong class="command">dnssec-signzone</strong></span> to run as if it were compiled 2009*00b67f09SDavid van Moolenbroek without the --with-pkcs11 option. 2010*00b67f09SDavid van Moolenbroek </p> 2011*00b67f09SDavid van Moolenbroek<p> 2012*00b67f09SDavid van Moolenbroek When built with native PKCS#11 mode, the "engine" option has a 2013*00b67f09SDavid van Moolenbroek different meaning: it specifies the path to the PKCS#11 provider 2014*00b67f09SDavid van Moolenbroek library. This may be useful when testing a new provider library. 2015*00b67f09SDavid van Moolenbroek </p> 2016*00b67f09SDavid van Moolenbroek</div> 2017*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 2018*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 2019*00b67f09SDavid van Moolenbroek<a name="id2639009"></a>Running named with automatic zone re-signing</h3></div></div></div> 2020*00b67f09SDavid van Moolenbroek<p> 2021*00b67f09SDavid van Moolenbroek If you want <span><strong class="command">named</strong></span> to dynamically re-sign zones 2022*00b67f09SDavid van Moolenbroek using HSM keys, and/or to to sign new records inserted via nsupdate, 2023*00b67f09SDavid van Moolenbroek then named must have access to the HSM PIN. In OpenSSL-based PKCS#11, 2024*00b67f09SDavid van Moolenbroek this is accomplished by placing the PIN into the openssl.cnf file 2025*00b67f09SDavid van Moolenbroek (in the above examples, 2026*00b67f09SDavid van Moolenbroek <code class="filename">/opt/pkcs11/usr/ssl/openssl.cnf</code>). 2027*00b67f09SDavid van Moolenbroek </p> 2028*00b67f09SDavid van Moolenbroek<p> 2029*00b67f09SDavid van Moolenbroek The location of the openssl.cnf file can be overridden by 2030*00b67f09SDavid van Moolenbroek setting the OPENSSL_CONF environment variable before running 2031*00b67f09SDavid van Moolenbroek named. 2032*00b67f09SDavid van Moolenbroek </p> 2033*00b67f09SDavid van Moolenbroek<p>Sample openssl.cnf:</p> 2034*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 2035*00b67f09SDavid van Moolenbroek openssl_conf = openssl_def 2036*00b67f09SDavid van Moolenbroek [ openssl_def ] 2037*00b67f09SDavid van Moolenbroek engines = engine_section 2038*00b67f09SDavid van Moolenbroek [ engine_section ] 2039*00b67f09SDavid van Moolenbroek pkcs11 = pkcs11_section 2040*00b67f09SDavid van Moolenbroek [ pkcs11_section ] 2041*00b67f09SDavid van Moolenbroek PIN = <em class="replaceable"><code><PLACE PIN HERE></code></em> 2042*00b67f09SDavid van Moolenbroek</pre> 2043*00b67f09SDavid van Moolenbroek<p> 2044*00b67f09SDavid van Moolenbroek This will also allow the dnssec-* tools to access the HSM 2045*00b67f09SDavid van Moolenbroek without PIN entry. (The pkcs11-* tools access the HSM directly, 2046*00b67f09SDavid van Moolenbroek not via OpenSSL, so a PIN will still be required to use 2047*00b67f09SDavid van Moolenbroek them.) 2048*00b67f09SDavid van Moolenbroek </p> 2049*00b67f09SDavid van Moolenbroek<p> 2050*00b67f09SDavid van Moolenbroek In native PKCS#11 mode, the PIN can be provided in a file specified 2051*00b67f09SDavid van Moolenbroek as an attribute of the key's label. For example, if a key had the label 2052*00b67f09SDavid van Moolenbroek <strong class="userinput"><code>pkcs11:object=local-zsk;pin-source=/etc/hsmpin</code></strong>, 2053*00b67f09SDavid van Moolenbroek then the PIN would be read from the file 2054*00b67f09SDavid van Moolenbroek <code class="filename">/etc/hsmpin</code>. 2055*00b67f09SDavid van Moolenbroek </p> 2056*00b67f09SDavid van Moolenbroek<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> 2057*00b67f09SDavid van Moolenbroek<h3 class="title">Warning</h3> 2058*00b67f09SDavid van Moolenbroek<p> 2059*00b67f09SDavid van Moolenbroek Placing the HSM's PIN in a text file in this manner may reduce the 2060*00b67f09SDavid van Moolenbroek security advantage of using an HSM. Be sure this is what you want to 2061*00b67f09SDavid van Moolenbroek do before configuring the system in this way. 2062*00b67f09SDavid van Moolenbroek </p> 2063*00b67f09SDavid van Moolenbroek</div> 2064*00b67f09SDavid van Moolenbroek</div> 2065*00b67f09SDavid van Moolenbroek</div> 2066*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 2067*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 2068*00b67f09SDavid van Moolenbroek<a name="dlz-info"></a>DLZ (Dynamically Loadable Zones)</h2></div></div></div> 2069*00b67f09SDavid van Moolenbroek<p> 2070*00b67f09SDavid van Moolenbroek DLZ (Dynamically Loadable Zones) is an extension to BIND 9 that allows 2071*00b67f09SDavid van Moolenbroek zone data to be retrieved directly from an external database. There is 2072*00b67f09SDavid van Moolenbroek no required format or schema. DLZ drivers exist for several different 2073*00b67f09SDavid van Moolenbroek database backends including PostgreSQL, MySQL, and LDAP and can be 2074*00b67f09SDavid van Moolenbroek written for any other. 2075*00b67f09SDavid van Moolenbroek </p> 2076*00b67f09SDavid van Moolenbroek<p> 2077*00b67f09SDavid van Moolenbroek Historically, DLZ drivers had to be statically linked with the named 2078*00b67f09SDavid van Moolenbroek binary and were turned on via a configure option at compile time (for 2079*00b67f09SDavid van Moolenbroek example, <strong class="userinput"><code>"configure --with-dlz-ldap"</code></strong>). 2080*00b67f09SDavid van Moolenbroek Currently, the drivers provided in the BIND 9 tarball in 2081*00b67f09SDavid van Moolenbroek <code class="filename">contrib/dlz/drivers</code> are still linked this 2082*00b67f09SDavid van Moolenbroek way. 2083*00b67f09SDavid van Moolenbroek </p> 2084*00b67f09SDavid van Moolenbroek<p> 2085*00b67f09SDavid van Moolenbroek In BIND 9.8 and higher, it is possible to link some DLZ modules 2086*00b67f09SDavid van Moolenbroek dynamically at runtime, via the DLZ "dlopen" driver, which acts as a 2087*00b67f09SDavid van Moolenbroek generic wrapper around a shared object implementing the DLZ API. The 2088*00b67f09SDavid van Moolenbroek "dlopen" driver is linked into named by default, so configure options 2089*00b67f09SDavid van Moolenbroek are no longer necessary when using these dynamically linkable drivers, 2090*00b67f09SDavid van Moolenbroek but are still needed for the older drivers in 2091*00b67f09SDavid van Moolenbroek <code class="filename">contrib/dlz/drivers</code>. 2092*00b67f09SDavid van Moolenbroek </p> 2093*00b67f09SDavid van Moolenbroek<p> 2094*00b67f09SDavid van Moolenbroek When the DLZ module provides data to named, it does so in text format. 2095*00b67f09SDavid van Moolenbroek The response is converted to DNS wire format by named. This 2096*00b67f09SDavid van Moolenbroek conversion, and the lack of any internal caching, places significant 2097*00b67f09SDavid van Moolenbroek limits on the query performance of DLZ modules. Consequently, DLZ is 2098*00b67f09SDavid van Moolenbroek not recommended for use on high-volume servers. However, it can be 2099*00b67f09SDavid van Moolenbroek used in a hidden master configuration, with slaves retrieving zone 2100*00b67f09SDavid van Moolenbroek updates via AXFR. (Note, however, that DLZ has no built-in support for 2101*00b67f09SDavid van Moolenbroek DNS notify; slaves are not automatically informed of changes to the 2102*00b67f09SDavid van Moolenbroek zones in the database.) 2103*00b67f09SDavid van Moolenbroek </p> 2104*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 2105*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 2106*00b67f09SDavid van Moolenbroek<a name="id2639074"></a>Configuring DLZ</h3></div></div></div> 2107*00b67f09SDavid van Moolenbroek<p> 2108*00b67f09SDavid van Moolenbroek A DLZ database is configured with a <span><strong class="command">dlz</strong></span> 2109*00b67f09SDavid van Moolenbroek statement in <code class="filename">named.conf</code>: 2110*00b67f09SDavid van Moolenbroek </p> 2111*00b67f09SDavid van Moolenbroek<pre class="screen"> 2112*00b67f09SDavid van Moolenbroek dlz example { 2113*00b67f09SDavid van Moolenbroek database "dlopen driver.so <code class="option">args</code>"; 2114*00b67f09SDavid van Moolenbroek search yes; 2115*00b67f09SDavid van Moolenbroek }; 2116*00b67f09SDavid van Moolenbroek </pre> 2117*00b67f09SDavid van Moolenbroek<p> 2118*00b67f09SDavid van Moolenbroek This specifies a DLZ module to search when answering queries; the 2119*00b67f09SDavid van Moolenbroek module is implemented in <code class="filename">driver.so</code> and is 2120*00b67f09SDavid van Moolenbroek loaded at runtime by the dlopen DLZ driver. Multiple 2121*00b67f09SDavid van Moolenbroek <span><strong class="command">dlz</strong></span> statements can be specified; when 2122*00b67f09SDavid van Moolenbroek answering a query, all DLZ modules with <code class="option">search</code> 2123*00b67f09SDavid van Moolenbroek set to <code class="literal">yes</code> will be queried to find out if 2124*00b67f09SDavid van Moolenbroek they contain an answer for the query name; the best available 2125*00b67f09SDavid van Moolenbroek answer will be returned to the client. 2126*00b67f09SDavid van Moolenbroek </p> 2127*00b67f09SDavid van Moolenbroek<p> 2128*00b67f09SDavid van Moolenbroek The <code class="option">search</code> option in the above example can be 2129*00b67f09SDavid van Moolenbroek omitted, because <code class="literal">yes</code> is the default value. 2130*00b67f09SDavid van Moolenbroek </p> 2131*00b67f09SDavid van Moolenbroek<p> 2132*00b67f09SDavid van Moolenbroek If <code class="option">search</code> is set to <code class="literal">no</code>, then 2133*00b67f09SDavid van Moolenbroek this DLZ module is <span class="emphasis"><em>not</em></span> searched for the best 2134*00b67f09SDavid van Moolenbroek match when a query is received. Instead, zones in this DLZ must be 2135*00b67f09SDavid van Moolenbroek separately specified in a zone statement. This allows you to 2136*00b67f09SDavid van Moolenbroek configure a zone normally using standard zone option semantics, 2137*00b67f09SDavid van Moolenbroek but specify a different database back-end for storage of the 2138*00b67f09SDavid van Moolenbroek zone's data. For example, to implement NXDOMAIN redirection using 2139*00b67f09SDavid van Moolenbroek a DLZ module for back-end storage of redirection rules: 2140*00b67f09SDavid van Moolenbroek </p> 2141*00b67f09SDavid van Moolenbroek<pre class="screen"> 2142*00b67f09SDavid van Moolenbroek dlz other { 2143*00b67f09SDavid van Moolenbroek database "dlopen driver.so <code class="option">args</code>"; 2144*00b67f09SDavid van Moolenbroek search no; 2145*00b67f09SDavid van Moolenbroek }; 2146*00b67f09SDavid van Moolenbroek 2147*00b67f09SDavid van Moolenbroek zone "." { 2148*00b67f09SDavid van Moolenbroek type redirect; 2149*00b67f09SDavid van Moolenbroek dlz other; 2150*00b67f09SDavid van Moolenbroek }; 2151*00b67f09SDavid van Moolenbroek </pre> 2152*00b67f09SDavid van Moolenbroek</div> 2153*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 2154*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 2155*00b67f09SDavid van Moolenbroek<a name="id2611909"></a>Sample DLZ Driver</h3></div></div></div> 2156*00b67f09SDavid van Moolenbroek<p> 2157*00b67f09SDavid van Moolenbroek For guidance in implementation of DLZ modules, the directory 2158*00b67f09SDavid van Moolenbroek <code class="filename">contrib/dlz/example</code> contains a basic 2159*00b67f09SDavid van Moolenbroek dynamically-linkable DLZ module--i.e., one which can be 2160*00b67f09SDavid van Moolenbroek loaded at runtime by the "dlopen" DLZ driver. 2161*00b67f09SDavid van Moolenbroek The example sets up a single zone, whose name is passed 2162*00b67f09SDavid van Moolenbroek to the module as an argument in the <span><strong class="command">dlz</strong></span> 2163*00b67f09SDavid van Moolenbroek statement: 2164*00b67f09SDavid van Moolenbroek </p> 2165*00b67f09SDavid van Moolenbroek<pre class="screen"> 2166*00b67f09SDavid van Moolenbroek dlz other { 2167*00b67f09SDavid van Moolenbroek database "dlopen driver.so example.nil"; 2168*00b67f09SDavid van Moolenbroek }; 2169*00b67f09SDavid van Moolenbroek </pre> 2170*00b67f09SDavid van Moolenbroek<p> 2171*00b67f09SDavid van Moolenbroek In the above example, the module is configured to create a zone 2172*00b67f09SDavid van Moolenbroek "example.nil", which can answer queries and AXFR requests, and 2173*00b67f09SDavid van Moolenbroek accept DDNS updates. At runtime, prior to any updates, the zone 2174*00b67f09SDavid van Moolenbroek contains an SOA, NS, and a single A record at the apex: 2175*00b67f09SDavid van Moolenbroek </p> 2176*00b67f09SDavid van Moolenbroek<pre class="screen"> 2177*00b67f09SDavid van Moolenbroek example.nil. 3600 IN SOA example.nil. hostmaster.example.nil. ( 2178*00b67f09SDavid van Moolenbroek 123 900 600 86400 3600 2179*00b67f09SDavid van Moolenbroek ) 2180*00b67f09SDavid van Moolenbroek example.nil. 3600 IN NS example.nil. 2181*00b67f09SDavid van Moolenbroek example.nil. 1800 IN A 10.53.0.1 2182*00b67f09SDavid van Moolenbroek </pre> 2183*00b67f09SDavid van Moolenbroek<p> 2184*00b67f09SDavid van Moolenbroek The sample driver is capable of retrieving information about the 2185*00b67f09SDavid van Moolenbroek querying client, and altering its response on the basis of this 2186*00b67f09SDavid van Moolenbroek information. To demonstrate this feature, the example driver 2187*00b67f09SDavid van Moolenbroek responds to queries for "source-addr.<code class="option">zonename</code>>/TXT" 2188*00b67f09SDavid van Moolenbroek with the source address of the query. Note, however, that this 2189*00b67f09SDavid van Moolenbroek record will *not* be included in AXFR or ANY responses. Normally, 2190*00b67f09SDavid van Moolenbroek this feature would be used to alter responses in some other fashion, 2191*00b67f09SDavid van Moolenbroek e.g., by providing different address records for a particular name 2192*00b67f09SDavid van Moolenbroek depending on the network from which the query arrived. 2193*00b67f09SDavid van Moolenbroek </p> 2194*00b67f09SDavid van Moolenbroek<p> 2195*00b67f09SDavid van Moolenbroek Documentation of the DLZ module API can be found in 2196*00b67f09SDavid van Moolenbroek <code class="filename">contrib/dlz/example/README</code>. This directory also 2197*00b67f09SDavid van Moolenbroek contains the header file <code class="filename">dlz_minimal.h</code>, which 2198*00b67f09SDavid van Moolenbroek defines the API and should be included by any dynamically-linkable 2199*00b67f09SDavid van Moolenbroek DLZ module. 2200*00b67f09SDavid van Moolenbroek </p> 2201*00b67f09SDavid van Moolenbroek</div> 2202*00b67f09SDavid van Moolenbroek</div> 2203*00b67f09SDavid van Moolenbroek<div class="sect1" lang="en"> 2204*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 2205*00b67f09SDavid van Moolenbroek<a name="id2571523"></a>IPv6 Support in <acronym class="acronym">BIND</acronym> 9</h2></div></div></div> 2206*00b67f09SDavid van Moolenbroek<p> 2207*00b67f09SDavid van Moolenbroek <acronym class="acronym">BIND</acronym> 9 fully supports all currently 2208*00b67f09SDavid van Moolenbroek defined forms of IPv6 name to address and address to name 2209*00b67f09SDavid van Moolenbroek lookups. It will also use IPv6 addresses to make queries when 2210*00b67f09SDavid van Moolenbroek running on an IPv6 capable system. 2211*00b67f09SDavid van Moolenbroek </p> 2212*00b67f09SDavid van Moolenbroek<p> 2213*00b67f09SDavid van Moolenbroek For forward lookups, <acronym class="acronym">BIND</acronym> 9 supports 2214*00b67f09SDavid van Moolenbroek only AAAA records. RFC 3363 deprecated the use of A6 records, 2215*00b67f09SDavid van Moolenbroek and client-side support for A6 records was accordingly removed 2216*00b67f09SDavid van Moolenbroek from <acronym class="acronym">BIND</acronym> 9. 2217*00b67f09SDavid van Moolenbroek However, authoritative <acronym class="acronym">BIND</acronym> 9 name servers still 2218*00b67f09SDavid van Moolenbroek load zone files containing A6 records correctly, answer queries 2219*00b67f09SDavid van Moolenbroek for A6 records, and accept zone transfer for a zone containing A6 2220*00b67f09SDavid van Moolenbroek records. 2221*00b67f09SDavid van Moolenbroek </p> 2222*00b67f09SDavid van Moolenbroek<p> 2223*00b67f09SDavid van Moolenbroek For IPv6 reverse lookups, <acronym class="acronym">BIND</acronym> 9 supports 2224*00b67f09SDavid van Moolenbroek the traditional "nibble" format used in the 2225*00b67f09SDavid van Moolenbroek <span class="emphasis"><em>ip6.arpa</em></span> domain, as well as the older, deprecated 2226*00b67f09SDavid van Moolenbroek <span class="emphasis"><em>ip6.int</em></span> domain. 2227*00b67f09SDavid van Moolenbroek Older versions of <acronym class="acronym">BIND</acronym> 9 2228*00b67f09SDavid van Moolenbroek supported the "binary label" (also known as "bitstring") format, 2229*00b67f09SDavid van Moolenbroek but support of binary labels has been completely removed per 2230*00b67f09SDavid van Moolenbroek RFC 3363. 2231*00b67f09SDavid van Moolenbroek Many applications in <acronym class="acronym">BIND</acronym> 9 do not understand 2232*00b67f09SDavid van Moolenbroek the binary label format at all any more, and will return an 2233*00b67f09SDavid van Moolenbroek error if given. 2234*00b67f09SDavid van Moolenbroek In particular, an authoritative <acronym class="acronym">BIND</acronym> 9 2235*00b67f09SDavid van Moolenbroek name server will not load a zone file containing binary labels. 2236*00b67f09SDavid van Moolenbroek </p> 2237*00b67f09SDavid van Moolenbroek<p> 2238*00b67f09SDavid van Moolenbroek For an overview of the format and structure of IPv6 addresses, 2239*00b67f09SDavid van Moolenbroek see <a href="Bv9ARM.ch11.html#ipv6addresses" title="IPv6 addresses (AAAA)">the section called “IPv6 addresses (AAAA)”</a>. 2240*00b67f09SDavid van Moolenbroek </p> 2241*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 2242*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 2243*00b67f09SDavid van Moolenbroek<a name="id2571789"></a>Address Lookups Using AAAA Records</h3></div></div></div> 2244*00b67f09SDavid van Moolenbroek<p> 2245*00b67f09SDavid van Moolenbroek The IPv6 AAAA record is a parallel to the IPv4 A record, 2246*00b67f09SDavid van Moolenbroek and, unlike the deprecated A6 record, specifies the entire 2247*00b67f09SDavid van Moolenbroek IPv6 address in a single record. For example, 2248*00b67f09SDavid van Moolenbroek </p> 2249*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 2250*00b67f09SDavid van Moolenbroek$ORIGIN example.com. 2251*00b67f09SDavid van Moolenbroekhost 3600 IN AAAA 2001:db8::1 2252*00b67f09SDavid van Moolenbroek</pre> 2253*00b67f09SDavid van Moolenbroek<p> 2254*00b67f09SDavid van Moolenbroek Use of IPv4-in-IPv6 mapped addresses is not recommended. 2255*00b67f09SDavid van Moolenbroek If a host has an IPv4 address, use an A record, not 2256*00b67f09SDavid van Moolenbroek a AAAA, with <code class="literal">::ffff:192.168.42.1</code> as 2257*00b67f09SDavid van Moolenbroek the address. 2258*00b67f09SDavid van Moolenbroek </p> 2259*00b67f09SDavid van Moolenbroek</div> 2260*00b67f09SDavid van Moolenbroek<div class="sect2" lang="en"> 2261*00b67f09SDavid van Moolenbroek<div class="titlepage"><div><div><h3 class="title"> 2262*00b67f09SDavid van Moolenbroek<a name="id2571811"></a>Address to Name Lookups Using Nibble Format</h3></div></div></div> 2263*00b67f09SDavid van Moolenbroek<p> 2264*00b67f09SDavid van Moolenbroek When looking up an address in nibble format, the address 2265*00b67f09SDavid van Moolenbroek components are simply reversed, just as in IPv4, and 2266*00b67f09SDavid van Moolenbroek <code class="literal">ip6.arpa.</code> is appended to the 2267*00b67f09SDavid van Moolenbroek resulting name. 2268*00b67f09SDavid van Moolenbroek For example, the following would provide reverse name lookup for 2269*00b67f09SDavid van Moolenbroek a host with address 2270*00b67f09SDavid van Moolenbroek <code class="literal">2001:db8::1</code>. 2271*00b67f09SDavid van Moolenbroek </p> 2272*00b67f09SDavid van Moolenbroek<pre class="programlisting"> 2273*00b67f09SDavid van Moolenbroek$ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. 2274*00b67f09SDavid van Moolenbroek1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0 14400 IN PTR ( 2275*00b67f09SDavid van Moolenbroek host.example.com. ) 2276*00b67f09SDavid van Moolenbroek</pre> 2277*00b67f09SDavid van Moolenbroek</div> 2278*00b67f09SDavid van Moolenbroek</div> 2279*00b67f09SDavid van Moolenbroek</div> 2280*00b67f09SDavid van Moolenbroek<div class="navfooter"> 2281*00b67f09SDavid van Moolenbroek<hr> 2282*00b67f09SDavid van Moolenbroek<table width="100%" summary="Navigation footer"> 2283*00b67f09SDavid van Moolenbroek<tr> 2284*00b67f09SDavid van Moolenbroek<td width="40%" align="left"> 2285*00b67f09SDavid van Moolenbroek<a accesskey="p" href="Bv9ARM.ch03.html">Prev</a>�</td> 2286*00b67f09SDavid van Moolenbroek<td width="20%" align="center">�</td> 2287*00b67f09SDavid van Moolenbroek<td width="40%" align="right">�<a accesskey="n" href="Bv9ARM.ch05.html">Next</a> 2288*00b67f09SDavid van Moolenbroek</td> 2289*00b67f09SDavid van Moolenbroek</tr> 2290*00b67f09SDavid van Moolenbroek<tr> 2291*00b67f09SDavid van Moolenbroek<td width="40%" align="left" valign="top">Chapter�3.�Name Server Configuration�</td> 2292*00b67f09SDavid van Moolenbroek<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> 2293*00b67f09SDavid van Moolenbroek<td width="40%" align="right" valign="top">�Chapter�5.�The <acronym class="acronym">BIND</acronym> 9 Lightweight Resolver</td> 2294*00b67f09SDavid van Moolenbroek</tr> 2295*00b67f09SDavid van Moolenbroek</table> 2296*00b67f09SDavid van Moolenbroek</div> 2297*00b67f09SDavid van Moolenbroek<p style="text-align: center;">BIND 9.10.2-P4</p> 2298*00b67f09SDavid van Moolenbroek</body> 2299*00b67f09SDavid van Moolenbroek</html> 2300