diff options
Diffstat (limited to 'contrib/bind9/doc/arm/Bv9ARM.ch04.html')
| -rw-r--r-- | contrib/bind9/doc/arm/Bv9ARM.ch04.html | 1921 |
1 files changed, 1921 insertions, 0 deletions
diff --git a/contrib/bind9/doc/arm/Bv9ARM.ch04.html b/contrib/bind9/doc/arm/Bv9ARM.ch04.html new file mode 100644 index 0000000..e22a0cb --- /dev/null +++ b/contrib/bind9/doc/arm/Bv9ARM.ch04.html @@ -0,0 +1,1921 @@ +<!-- + - Copyright (C) 2004-2013 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2000-2003 Internet Software Consortium. + - + - Permission to use, copy, modify, and/or distribute this software for any + - purpose with or without fee is hereby granted, provided that the above + - copyright notice and this permission notice appear in all copies. + - + - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH + - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, + - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE + - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + - PERFORMANCE OF THIS SOFTWARE. +--> +<!-- $Id$ --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 4. Advanced DNS Features</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> +<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch03.html" title="Chapter 3. Name Server Configuration"> +<link rel="next" href="Bv9ARM.ch05.html" title="Chapter 5. The BIND 9 Lightweight Resolver"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Chapter 4. Advanced DNS Features</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch03.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch05.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="chapter" lang="en"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="Bv9ARM.ch04"></a>Chapter 4. Advanced DNS Features</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#notify">Notify</a></span></dt> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#dynamic_update">Dynamic Update</a></span></dt> +<dd><dl><dt><span class="sect2"><a href="Bv9ARM.ch04.html#journal">The journal file</a></span></dt></dl></dd> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#incremental_zone_transfers">Incremental Zone Transfers (IXFR)</a></span></dt> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#id2571175">Split DNS</a></span></dt> +<dd><dl><dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2571193">Example split DNS setup</a></span></dt></dl></dd> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#tsig">TSIG</a></span></dt> +<dd><dl> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2571763">Generate Shared Keys for Each Pair of Hosts</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2571836">Copying the Shared Secret to Both Machines</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2571847">Informing the Servers of the Key's Existence</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2571883">Instructing the Server to Use the Key</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2571941">TSIG Key Based Access Control</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2564003">Errors</a></span></dt> +</dl></dd> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#id2564017">TKEY</a></span></dt> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#id2572326">SIG(0)</a></span></dt> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#DNSSEC">DNSSEC</a></span></dt> +<dd><dl> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2572394">Generating Keys</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2572541">Signing the Zone</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2572622">Configuring Servers</a></span></dt> +</dl></dd> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#dnssec.dynamic.zones">DNSSEC, Dynamic Zones, and Automatic Signing</a></span></dt> +<dd><dl> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563413">Converting from insecure to secure</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563450">Dynamic DNS update method</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563555">Fully automatic zone signing</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563726">Private-type records</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563832">DNSKEY rollovers</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563845">Dynamic DNS update method</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563878">Automatic key rollovers</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563905">NSEC3PARAM rollovers via UPDATE</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563914">Converting from NSEC to NSEC3</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563924">Converting from NSEC3 to NSEC</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2563937">Converting from secure to insecure</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2572029">Periodic re-signing</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2572039">NSEC3 and OPTOUT</a></span></dt> +</dl></dd> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#rfc5011.support">Dynamic Trust Anchor Management</a></span></dt> +<dd><dl> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2572072">Validating Resolver</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2609027">Authoritative Server</a></span></dt> +</dl></dd> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#pkcs11">PKCS #11 (Cryptoki) support</a></span></dt> +<dd><dl> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2611929">Prerequisites</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2610179">Building BIND 9 with PKCS#11</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2612283">PKCS #11 Tools</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2612382">Using the HSM</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2636884">Specifying the engine on the command line</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2636930">Running named with automatic zone re-signing</a></span></dt> +</dl></dd> +<dt><span class="sect1"><a href="Bv9ARM.ch04.html#id2572842">IPv6 Support in <acronym class="acronym">BIND</acronym> 9</a></span></dt> +<dd><dl> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2573109">Address Lookups Using AAAA Records</a></span></dt> +<dt><span class="sect2"><a href="Bv9ARM.ch04.html#id2573130">Address to Name Lookups Using Nibble Format</a></span></dt> +</dl></dd> +</dl> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="notify"></a>Notify</h2></div></div></div> +<p> + <acronym class="acronym">DNS</acronym> NOTIFY is a mechanism that allows master + servers to notify their slave servers of changes to a zone's data. In + response to a <span><strong class="command">NOTIFY</strong></span> from a master server, the + slave will check to see that its version of the zone is the + current version and, if not, initiate a zone transfer. + </p> +<p> + For more information about <acronym class="acronym">DNS</acronym> + <span><strong class="command">NOTIFY</strong></span>, see the description of the + <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 + the description of the zone option <span><strong class="command">also-notify</strong></span> in + <a href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. The <span><strong class="command">NOTIFY</strong></span> + protocol is specified in RFC 1996. + </p> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + As a slave zone can also be a master to other slaves, <span><strong class="command">named</strong></span>, + by default, sends <span><strong class="command">NOTIFY</strong></span> messages for every zone + it loads. Specifying <span><strong class="command">notify master-only;</strong></span> will + cause <span><strong class="command">named</strong></span> to only send <span><strong class="command">NOTIFY</strong></span> for master + zones that it loads. + </div> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="dynamic_update"></a>Dynamic Update</h2></div></div></div> +<p> + Dynamic Update is a method for adding, replacing or deleting + records in a master server by sending it a special form of DNS + messages. The format and meaning of these messages is specified + in RFC 2136. + </p> +<p> + Dynamic update is enabled by including an + <span><strong class="command">allow-update</strong></span> or an <span><strong class="command">update-policy</strong></span> + clause in the <span><strong class="command">zone</strong></span> statement. + </p> +<p> + If the zone's <span><strong class="command">update-policy</strong></span> is set to + <strong class="userinput"><code>local</code></strong>, updates to the zone + will be permitted for the key <code class="varname">local-ddns</code>, + which will be generated by <span><strong class="command">named</strong></span> at startup. + See <a href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a> for more details. + </p> +<p> + Dynamic updates using Kerberos signed requests can be made + using the TKEY/GSS protocol by setting either the + <span><strong class="command">tkey-gssapi-keytab</strong></span> option, or alternatively + by setting both the <span><strong class="command">tkey-gssapi-credential</strong></span> + and <span><strong class="command">tkey-domain</strong></span> options. Once enabled, + Kerberos signed requests will be matched against the update + policies for the zone, using the Kerberos principal as the + signer for the request. + </p> +<p> + Updating of secure zones (zones using DNSSEC) follows RFC + 3007: RRSIG, NSEC and NSEC3 records affected by updates are + automatically regenerated by the server using an online + zone key. Update authorization is based on transaction + signatures and an explicit server policy. + </p> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="journal"></a>The journal file</h3></div></div></div> +<p> + All changes made to a zone using dynamic update are stored + in the zone's journal file. This file is automatically created + by the server when the first dynamic update takes place. + The name of the journal file is formed by appending the extension + <code class="filename">.jnl</code> to the name of the + corresponding zone + file unless specifically overridden. The journal file is in a + binary format and should not be edited manually. + </p> +<p> + The server will also occasionally write ("dump") + the complete contents of the updated zone to its zone file. + This is not done immediately after + each dynamic update, because that would be too slow when a large + zone is updated frequently. Instead, the dump is delayed by + up to 15 minutes, allowing additional updates to take place. + During the dump process, transient files will be created + with the extensions <code class="filename">.jnw</code> and + <code class="filename">.jbk</code>; under ordinary circumstances, these + will be removed when the dump is complete, and can be safely + ignored. + </p> +<p> + When a server is restarted after a shutdown or crash, it will replay + the journal file to incorporate into the zone any updates that + took + place after the last zone dump. + </p> +<p> + Changes that result from incoming incremental zone transfers are + also + journalled in a similar way. + </p> +<p> + The zone files of dynamic zones cannot normally be edited by + hand because they are not guaranteed to contain the most recent + dynamic changes — those are only in the journal file. + The only way to ensure that the zone file of a dynamic zone + is up to date is to run <span><strong class="command">rndc stop</strong></span>. + </p> +<p> + If you have to make changes to a dynamic zone + manually, the following procedure will work: Disable dynamic updates + to the zone using + <span><strong class="command">rndc freeze <em class="replaceable"><code>zone</code></em></strong></span>. + This will also remove the zone's <code class="filename">.jnl</code> file + and update the master file. Edit the zone file. Run + <span><strong class="command">rndc thaw <em class="replaceable"><code>zone</code></em></strong></span> + to reload the changed zone and re-enable dynamic updates. + </p> +</div> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="incremental_zone_transfers"></a>Incremental Zone Transfers (IXFR)</h2></div></div></div> +<p> + The incremental zone transfer (IXFR) protocol is a way for + slave servers to transfer only changed data, instead of having to + transfer the entire zone. The IXFR protocol is specified in RFC + 1995. See <a href="Bv9ARM.ch09.html#proposed_standards">Proposed Standards</a>. + </p> +<p> + When acting as a master, <acronym class="acronym">BIND</acronym> 9 + supports IXFR for those zones + where the necessary change history information is available. These + include master zones maintained by dynamic update and slave zones + whose data was obtained by IXFR. For manually maintained master + zones, and for slave zones obtained by performing a full zone + transfer (AXFR), IXFR is supported only if the option + <span><strong class="command">ixfr-from-differences</strong></span> is set + to <strong class="userinput"><code>yes</code></strong>. + </p> +<p> + When acting as a slave, <acronym class="acronym">BIND</acronym> 9 will + attempt to use IXFR unless + it is explicitly disabled. For more information about disabling + IXFR, see the description of the <span><strong class="command">request-ixfr</strong></span> clause + of the <span><strong class="command">server</strong></span> statement. + </p> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="id2571175"></a>Split DNS</h2></div></div></div> +<p> + Setting up different views, or visibility, of the DNS space to + internal and external resolvers is usually referred to as a + <span class="emphasis"><em>Split DNS</em></span> setup. There are several + reasons an organization would want to set up its DNS this way. + </p> +<p> + One common reason for setting up a DNS system this way is + to hide "internal" DNS information from "external" clients on the + Internet. There is some debate as to whether or not this is actually + useful. + Internal DNS information leaks out in many ways (via email headers, + for example) and most savvy "attackers" can find the information + they need using other means. + However, since listing addresses of internal servers that + external clients cannot possibly reach can result in + connection delays and other annoyances, an organization may + choose to use a Split DNS to present a consistent view of itself + to the outside world. + </p> +<p> + Another common reason for setting up a Split DNS system is + to allow internal networks that are behind filters or in RFC 1918 + space (reserved IP space, as documented in RFC 1918) to resolve DNS + on the Internet. Split DNS can also be used to allow mail from outside + back in to the internal network. + </p> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2571193"></a>Example split DNS setup</h3></div></div></div> +<p> + Let's say a company named <span class="emphasis"><em>Example, Inc.</em></span> + (<code class="literal">example.com</code>) + has several corporate sites that have an internal network with + reserved + Internet Protocol (IP) space and an external demilitarized zone (DMZ), + or "outside" section of a network, that is available to the public. + </p> +<p> + <span class="emphasis"><em>Example, Inc.</em></span> wants its internal clients + to be able to resolve external hostnames and to exchange mail with + people on the outside. The company also wants its internal resolvers + to have access to certain internal-only zones that are not available + at all outside of the internal network. + </p> +<p> + In order to accomplish this, the company will set up two sets + of name servers. One set will be on the inside network (in the + reserved + IP space) and the other set will be on bastion hosts, which are + "proxy" + hosts that can talk to both sides of its network, in the DMZ. + </p> +<p> + The internal servers will be configured to forward all queries, + except queries for <code class="filename">site1.internal</code>, <code class="filename">site2.internal</code>, <code class="filename">site1.example.com</code>, + and <code class="filename">site2.example.com</code>, to the servers + in the + DMZ. These internal servers will have complete sets of information + for <code class="filename">site1.example.com</code>, <code class="filename">site2.example.com</code>, <code class="filename">site1.internal</code>, + and <code class="filename">site2.internal</code>. + </p> +<p> + To protect the <code class="filename">site1.internal</code> and <code class="filename">site2.internal</code> domains, + the internal name servers must be configured to disallow all queries + to these domains from any external hosts, including the bastion + hosts. + </p> +<p> + The external servers, which are on the bastion hosts, will + be configured to serve the "public" version of the <code class="filename">site1</code> and <code class="filename">site2.example.com</code> zones. + This could include things such as the host records for public servers + (<code class="filename">www.example.com</code> and <code class="filename">ftp.example.com</code>), + and mail exchange (MX) records (<code class="filename">a.mx.example.com</code> and <code class="filename">b.mx.example.com</code>). + </p> +<p> + In addition, the public <code class="filename">site1</code> and <code class="filename">site2.example.com</code> zones + should have special MX records that contain wildcard (`*') records + pointing to the bastion hosts. This is needed because external mail + servers do not have any other way of looking up how to deliver mail + to those internal hosts. With the wildcard records, the mail will + be delivered to the bastion host, which can then forward it on to + internal hosts. + </p> +<p> + Here's an example of a wildcard MX record: + </p> +<pre class="programlisting">* IN MX 10 external1.example.com.</pre> +<p> + Now that they accept mail on behalf of anything in the internal + network, the bastion hosts will need to know how to deliver mail + to internal hosts. In order for this to work properly, the resolvers + on + the bastion hosts will need to be configured to point to the internal + name servers for DNS resolution. + </p> +<p> + Queries for internal hostnames will be answered by the internal + servers, and queries for external hostnames will be forwarded back + out to the DNS servers on the bastion hosts. + </p> +<p> + In order for all this to work properly, internal clients will + need to be configured to query <span class="emphasis"><em>only</em></span> the internal + name servers for DNS queries. This could also be enforced via + selective + filtering on the network. + </p> +<p> + If everything has been set properly, <span class="emphasis"><em>Example, Inc.</em></span>'s + internal clients will now be able to: + </p> +<div class="itemizedlist"><ul type="disc"> +<li> + Look up any hostnames in the <code class="literal">site1</code> + and + <code class="literal">site2.example.com</code> zones. + </li> +<li> + Look up any hostnames in the <code class="literal">site1.internal</code> and + <code class="literal">site2.internal</code> domains. + </li> +<li>Look up any hostnames on the Internet.</li> +<li>Exchange mail with both internal and external people.</li> +</ul></div> +<p> + Hosts on the Internet will be able to: + </p> +<div class="itemizedlist"><ul type="disc"> +<li> + Look up any hostnames in the <code class="literal">site1</code> + and + <code class="literal">site2.example.com</code> zones. + </li> +<li> + Exchange mail with anyone in the <code class="literal">site1</code> and + <code class="literal">site2.example.com</code> zones. + </li> +</ul></div> +<p> + Here is an example configuration for the setup we just + described above. Note that this is only configuration information; + 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>. + </p> +<p> + Internal DNS server config: + </p> +<pre class="programlisting"> + +acl internals { 172.16.72.0/24; 192.168.1.0/24; }; + +acl externals { <code class="varname">bastion-ips-go-here</code>; }; + +options { + ... + ... + forward only; + // forward to external servers + forwarders { + <code class="varname">bastion-ips-go-here</code>; + }; + // sample allow-transfer (no one) + allow-transfer { none; }; + // restrict query access + allow-query { internals; externals; }; + // restrict recursion + allow-recursion { internals; }; + ... + ... +}; + +// sample master zone +zone "site1.example.com" { + type master; + file "m/site1.example.com"; + // do normal iterative resolution (do not forward) + forwarders { }; + allow-query { internals; externals; }; + allow-transfer { internals; }; +}; + +// sample slave zone +zone "site2.example.com" { + type slave; + file "s/site2.example.com"; + masters { 172.16.72.3; }; + forwarders { }; + allow-query { internals; externals; }; + allow-transfer { internals; }; +}; + +zone "site1.internal" { + type master; + file "m/site1.internal"; + forwarders { }; + allow-query { internals; }; + allow-transfer { internals; } +}; + +zone "site2.internal" { + type slave; + file "s/site2.internal"; + masters { 172.16.72.3; }; + forwarders { }; + allow-query { internals }; + allow-transfer { internals; } +}; +</pre> +<p> + External (bastion host) DNS server config: + </p> +<pre class="programlisting"> +acl internals { 172.16.72.0/24; 192.168.1.0/24; }; + +acl externals { bastion-ips-go-here; }; + +options { + ... + ... + // sample allow-transfer (no one) + allow-transfer { none; }; + // default query access + allow-query { any; }; + // restrict cache access + allow-query-cache { internals; externals; }; + // restrict recursion + allow-recursion { internals; externals; }; + ... + ... +}; + +// sample slave zone +zone "site1.example.com" { + type master; + file "m/site1.foo.com"; + allow-transfer { internals; externals; }; +}; + +zone "site2.example.com" { + type slave; + file "s/site2.foo.com"; + masters { another_bastion_host_maybe; }; + allow-transfer { internals; externals; } +}; +</pre> +<p> + In the <code class="filename">resolv.conf</code> (or equivalent) on + the bastion host(s): + </p> +<pre class="programlisting"> +search ... +nameserver 172.16.72.2 +nameserver 172.16.72.3 +nameserver 172.16.72.4 +</pre> +</div> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="tsig"></a>TSIG</h2></div></div></div> +<p> + This is a short guide to setting up Transaction SIGnatures + (TSIG) based transaction security in <acronym class="acronym">BIND</acronym>. It describes changes + to the configuration file as well as what changes are required for + different features, including the process of creating transaction + keys and using transaction signatures with <acronym class="acronym">BIND</acronym>. + </p> +<p> + <acronym class="acronym">BIND</acronym> primarily supports TSIG for server + to server communication. + This includes zone transfer, notify, and recursive query messages. + Resolvers based on newer versions of <acronym class="acronym">BIND</acronym> 8 have limited support + for TSIG. + </p> +<p> + TSIG can also be useful for dynamic update. A primary + server for a dynamic zone should control access to the dynamic + update service, but IP-based access control is insufficient. + The cryptographic access control provided by TSIG + is far superior. The <span><strong class="command">nsupdate</strong></span> + program supports TSIG via the <code class="option">-k</code> and + <code class="option">-y</code> command line options or inline by use + of the <span><strong class="command">key</strong></span>. + </p> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2571763"></a>Generate Shared Keys for Each Pair of Hosts</h3></div></div></div> +<p> + A shared secret is generated to be shared between <span class="emphasis"><em>host1</em></span> and <span class="emphasis"><em>host2</em></span>. + An arbitrary key name is chosen: "host1-host2.". The key name must + be the same on both hosts. + </p> +<div class="sect3" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2571780"></a>Automatic Generation</h4></div></div></div> +<p> + The following command will generate a 128-bit (16 byte) HMAC-SHA256 + key as described above. Longer keys are better, but shorter keys + are easier to read. Note that the maximum key length is the digest + length, here 256 bits. + </p> +<p> + <strong class="userinput"><code>dnssec-keygen -a hmac-sha256 -b 128 -n HOST host1-host2.</code></strong> + </p> +<p> + The key is in the file <code class="filename">Khost1-host2.+163+00000.private</code>. + Nothing directly uses this file, but the base-64 encoded string + following "<code class="literal">Key:</code>" + can be extracted from the file and used as a shared secret: + </p> +<pre class="programlisting">Key: La/E5CjG9O+os1jq0a2jdA==</pre> +<p> + The string "<code class="literal">La/E5CjG9O+os1jq0a2jdA==</code>" can + be used as the shared secret. + </p> +</div> +<div class="sect3" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2571818"></a>Manual Generation</h4></div></div></div> +<p> + The shared secret is simply a random sequence of bits, encoded + in base-64. Most ASCII strings are valid base-64 strings (assuming + the length is a multiple of 4 and only valid characters are used), + so the shared secret can be manually generated. + </p> +<p> + Also, a known string can be run through <span><strong class="command">mmencode</strong></span> or + a similar program to generate base-64 encoded data. + </p> +</div> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2571836"></a>Copying the Shared Secret to Both Machines</h3></div></div></div> +<p> + This is beyond the scope of DNS. A secure transport mechanism + should be used. This could be secure FTP, ssh, telephone, etc. + </p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2571847"></a>Informing the Servers of the Key's Existence</h3></div></div></div> +<p> + Imagine <span class="emphasis"><em>host1</em></span> and <span class="emphasis"><em>host 2</em></span> + are + both servers. The following is added to each server's <code class="filename">named.conf</code> file: + </p> +<pre class="programlisting"> +key host1-host2. { + algorithm hmac-sha256; + secret "La/E5CjG9O+os1jq0a2jdA=="; +}; +</pre> +<p> + The secret is the one generated above. Since this is a secret, it + is recommended that either <code class="filename">named.conf</code> be + non-world readable, or the key directive be added to a non-world + readable file that is included by <code class="filename">named.conf</code>. + </p> +<p> + At this point, the key is recognized. This means that if the + server receives a message signed by this key, it can verify the + signature. If the signature is successfully verified, the + response is signed by the same key. + </p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2571883"></a>Instructing the Server to Use the Key</h3></div></div></div> +<p> + Since keys are shared between two hosts only, the server must + be told when keys are to be used. The following is added to the <code class="filename">named.conf</code> file + for <span class="emphasis"><em>host1</em></span>, if the IP address of <span class="emphasis"><em>host2</em></span> is + 10.1.2.3: + </p> +<pre class="programlisting"> +server 10.1.2.3 { + keys { host1-host2. ;}; +}; +</pre> +<p> + Multiple keys may be present, but only the first is used. + This directive does not contain any secrets, so it may be in a + world-readable + file. + </p> +<p> + If <span class="emphasis"><em>host1</em></span> sends a message that is a request + to that address, the message will be signed with the specified key. <span class="emphasis"><em>host1</em></span> will + expect any responses to signed messages to be signed with the same + key. + </p> +<p> + A similar statement must be present in <span class="emphasis"><em>host2</em></span>'s + configuration file (with <span class="emphasis"><em>host1</em></span>'s address) for <span class="emphasis"><em>host2</em></span> to + sign request messages to <span class="emphasis"><em>host1</em></span>. + </p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2571941"></a>TSIG Key Based Access Control</h3></div></div></div> +<p> + <acronym class="acronym">BIND</acronym> allows IP addresses and ranges + to be specified in ACL + definitions and + <span><strong class="command">allow-{ query | transfer | update }</strong></span> + directives. + This has been extended to allow TSIG keys also. The above key would + be denoted <span><strong class="command">key host1-host2.</strong></span> + </p> +<p> + An example of an <span><strong class="command">allow-update</strong></span> directive would be: + </p> +<pre class="programlisting"> +allow-update { key host1-host2. ;}; +</pre> +<p> + This allows dynamic updates to succeed only if the request + was signed by a key named "<span><strong class="command">host1-host2.</strong></span>". + </p> +<p> + See <a href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a> for a discussion of + the more flexible <span><strong class="command">update-policy</strong></span> statement. + </p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2564003"></a>Errors</h3></div></div></div> +<p> + The processing of TSIG signed messages can result in + several errors. If a signed message is sent to a non-TSIG aware + server, a FORMERR (format error) will be returned, since the server will not + understand the record. This is a result of misconfiguration, + since the server must be explicitly configured to send a TSIG + signed message to a specific server. + </p> +<p> + If a TSIG aware server receives a message signed by an + unknown key, the response will be unsigned with the TSIG + extended error code set to BADKEY. If a TSIG aware server + receives a message with a signature that does not validate, the + response will be unsigned with the TSIG extended error code set + to BADSIG. If a TSIG aware server receives a message with a time + outside of the allowed range, the response will be signed with + the TSIG extended error code set to BADTIME, and the time values + will be adjusted so that the response can be successfully + verified. In any of these cases, the message's rcode (response code) is set to + NOTAUTH (not authenticated). + </p> +</div> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="id2564017"></a>TKEY</h2></div></div></div> +<p><span><strong class="command">TKEY</strong></span> + is a mechanism for automatically generating a shared secret + between two hosts. There are several "modes" of + <span><strong class="command">TKEY</strong></span> that specify how the key is generated + or assigned. <acronym class="acronym">BIND</acronym> 9 implements only one of + these modes, the Diffie-Hellman key exchange. Both hosts are + required to have a Diffie-Hellman KEY record (although this + record is not required to be present in a zone). The + <span><strong class="command">TKEY</strong></span> process must use signed messages, + signed either by TSIG or SIG(0). The result of + <span><strong class="command">TKEY</strong></span> is a shared secret that can be used to + sign messages with TSIG. <span><strong class="command">TKEY</strong></span> can also be + used to delete shared secrets that it had previously + generated. + </p> +<p> + The <span><strong class="command">TKEY</strong></span> process is initiated by a + client + or server by sending a signed <span><strong class="command">TKEY</strong></span> + query + (including any appropriate KEYs) to a TKEY-aware server. The + server response, if it indicates success, will contain a + <span><strong class="command">TKEY</strong></span> record and any appropriate keys. + After + this exchange, both participants have enough information to + determine the shared secret; the exact process depends on the + <span><strong class="command">TKEY</strong></span> mode. When using the + Diffie-Hellman + <span><strong class="command">TKEY</strong></span> mode, Diffie-Hellman keys are + exchanged, + and the shared secret is derived by both participants. + </p> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="id2572326"></a>SIG(0)</h2></div></div></div> +<p> + <acronym class="acronym">BIND</acronym> 9 partially supports DNSSEC SIG(0) + transaction signatures as specified in RFC 2535 and RFC 2931. + SIG(0) + uses public/private keys to authenticate messages. Access control + is performed in the same manner as TSIG keys; privileges can be + granted or denied based on the key name. + </p> +<p> + When a SIG(0) signed message is received, it will only be + verified if the key is known and trusted by the server; the server + will not attempt to locate and/or validate the key. + </p> +<p> + SIG(0) signing of multiple-message TCP streams is not + supported. + </p> +<p> + The only tool shipped with <acronym class="acronym">BIND</acronym> 9 that + generates SIG(0) signed messages is <span><strong class="command">nsupdate</strong></span>. + </p> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="DNSSEC"></a>DNSSEC</h2></div></div></div> +<p> + Cryptographic authentication of DNS information is possible + through the DNS Security (<span class="emphasis"><em>DNSSEC-bis</em></span>) extensions, + defined in RFC 4033, RFC 4034, and RFC 4035. + This section describes the creation and use of DNSSEC signed zones. + </p> +<p> + In order to set up a DNSSEC secure zone, there are a series + of steps which must be followed. <acronym class="acronym">BIND</acronym> + 9 ships + with several tools + that are used in this process, which are explained in more detail + below. In all cases, the <code class="option">-h</code> option prints a + full list of parameters. Note that the DNSSEC tools require the + keyset files to be in the working directory or the + directory specified by the <code class="option">-d</code> option, and + that the tools shipped with BIND 9.2.x and earlier are not compatible + with the current ones. + </p> +<p> + There must also be communication with the administrators of + the parent and/or child zone to transmit keys. A zone's security + status must be indicated by the parent zone for a DNSSEC capable + resolver to trust its data. This is done through the presence + or absence of a <code class="literal">DS</code> record at the + delegation + point. + </p> +<p> + For other servers to trust data in this zone, they must + either be statically configured with this zone's zone key or the + zone key of another zone above this one in the DNS tree. + </p> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2572394"></a>Generating Keys</h3></div></div></div> +<p> + The <span><strong class="command">dnssec-keygen</strong></span> program is used to + generate keys. + </p> +<p> + A secure zone must contain one or more zone keys. The + zone keys will sign all other records in the zone, as well as + the zone keys of any secure delegated zones. Zone keys must + have the same name as the zone, a name type of + <span><strong class="command">ZONE</strong></span>, and must be usable for + authentication. + It is recommended that zone keys use a cryptographic algorithm + designated as "mandatory to implement" by the IETF; currently + the only one is RSASHA1. + </p> +<p> + The following command will generate a 768-bit RSASHA1 key for + the <code class="filename">child.example</code> zone: + </p> +<p> + <strong class="userinput"><code>dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example.</code></strong> + </p> +<p> + Two output files will be produced: + <code class="filename">Kchild.example.+005+12345.key</code> and + <code class="filename">Kchild.example.+005+12345.private</code> + (where + 12345 is an example of a key tag). The key filenames contain + the key name (<code class="filename">child.example.</code>), + algorithm (3 + is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in + this case). + The private key (in the <code class="filename">.private</code> + file) is + used to generate signatures, and the public key (in the + <code class="filename">.key</code> file) is used for signature + verification. + </p> +<p> + To generate another key with the same properties (but with + a different key tag), repeat the above command. + </p> +<p> + The <span><strong class="command">dnssec-keyfromlabel</strong></span> program is used + to get a key pair from a crypto hardware and build the key + files. Its usage is similar to <span><strong class="command">dnssec-keygen</strong></span>. + </p> +<p> + The public keys should be inserted into the zone file by + including the <code class="filename">.key</code> files using + <span><strong class="command">$INCLUDE</strong></span> statements. + </p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2572541"></a>Signing the Zone</h3></div></div></div> +<p> + The <span><strong class="command">dnssec-signzone</strong></span> program is used + to sign a zone. + </p> +<p> + Any <code class="filename">keyset</code> files corresponding to + secure subzones should be present. The zone signer will + generate <code class="literal">NSEC</code>, <code class="literal">NSEC3</code> + and <code class="literal">RRSIG</code> records for the zone, as + well as <code class="literal">DS</code> for the child zones if + <code class="literal">'-g'</code> is specified. If <code class="literal">'-g'</code> + is not specified, then DS RRsets for the secure child + zones need to be added manually. + </p> +<p> + The following command signs the zone, assuming it is in a + file called <code class="filename">zone.child.example</code>. By + default, all zone keys which have an available private key are + used to generate signatures. + </p> +<p> + <strong class="userinput"><code>dnssec-signzone -o child.example zone.child.example</code></strong> + </p> +<p> + One output file is produced: + <code class="filename">zone.child.example.signed</code>. This + file + should be referenced by <code class="filename">named.conf</code> + as the + input file for the zone. + </p> +<p><span><strong class="command">dnssec-signzone</strong></span> + will also produce a keyset and dsset files and optionally a + dlvset file. These are used to provide the parent zone + administrators with the <code class="literal">DNSKEYs</code> (or their + corresponding <code class="literal">DS</code> records) that are the + secure entry point to the zone. + </p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2572622"></a>Configuring Servers</h3></div></div></div> +<p> + To enable <span><strong class="command">named</strong></span> to respond appropriately + to DNS requests from DNSSEC aware clients, + <span><strong class="command">dnssec-enable</strong></span> must be set to yes. + (This is the default setting.) + </p> +<p> + To enable <span><strong class="command">named</strong></span> to validate answers from + other servers, the <span><strong class="command">dnssec-enable</strong></span> option + must be set to <strong class="userinput"><code>yes</code></strong>, and the + <span><strong class="command">dnssec-validation</strong></span> options must be set to + <strong class="userinput"><code>yes</code></strong> or <strong class="userinput"><code>auto</code></strong>. + </p> +<p> + If <span><strong class="command">dnssec-validation</strong></span> is set to + <strong class="userinput"><code>auto</code></strong>, then a default + trust anchor for the DNS root zone will be used. + If it is set to <strong class="userinput"><code>yes</code></strong>, however, + then at least one trust anchor must be configured + with a <span><strong class="command">trusted-keys</strong></span> or + <span><strong class="command">managed-keys</strong></span> statement in + <code class="filename">named.conf</code>, or DNSSEC validation + will not occur. The default setting is + <strong class="userinput"><code>yes</code></strong>. + </p> +<p> + <span><strong class="command">trusted-keys</strong></span> are copies of DNSKEY RRs + for zones that are used to form the first link in the + cryptographic chain of trust. All keys listed in + <span><strong class="command">trusted-keys</strong></span> (and corresponding zones) + are deemed to exist and only the listed keys will be used + to validated the DNSKEY RRset that they are from. + </p> +<p> + <span><strong class="command">managed-keys</strong></span> are trusted keys which are + automatically kept up to date via RFC 5011 trust anchor + maintenance. + </p> +<p> + <span><strong class="command">trusted-keys</strong></span> and + <span><strong class="command">managed-keys</strong></span> are described in more detail + later in this document. + </p> +<p> + Unlike <acronym class="acronym">BIND</acronym> 8, <acronym class="acronym">BIND</acronym> + 9 does not verify signatures on load, so zone keys for + authoritative zones do not need to be specified in the + configuration file. + </p> +<p> + After DNSSEC gets established, a typical DNSSEC configuration + will look something like the following. It has one or + more public keys for the root. This allows answers from + outside the organization to be validated. It will also + have several keys for parts of the namespace the organization + controls. These are here to ensure that <span><strong class="command">named</strong></span> + is immune to compromises in the DNSSEC components of the security + of parent zones. + </p> +<pre class="programlisting"> +managed-keys { + /* Root Key */ + "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS + JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh + aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy + 4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg + hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp + 5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke + g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq + 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ + 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ + dgxbcDTClU0CRBdiieyLMNzXG3"; +}; + +trusted-keys { + /* Key for our organization's forward zone */ + example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6 + 5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z + GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb + 4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL + kBOUKUf/mC7HvfwYH/Be22GnClrinKJp1O + g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S + TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq + FxmAVZP20igTixin/1LcrgX/KMEGd/biuv + F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm + /oyWR8BW/hWdzOvnSCThlHf3xiYleDbt/o + 1OTQ09A0="; + + /* Key for our reverse zone. */ + 2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc + xOdNax071L18QqZnQQQAVVr+i + LhGTnNGp3HoWQLUIzKrJVZ3zg + gy3WwNT6kZo6c0tszYqbtvchm + gQC8CzKojM/W16i6MG/eafGU3 + siaOdS0yOI6BgPsw+YZdzlYMa + IJGf4M4dyoKIhzdZyQ2bYQrjy + Q4LB0lC7aOnsMyYKHHYeRvPxj + IQXmdqgOJGq+vsevG06zW+1xg + YJh9rCIfnm1GX/KMgxLPG2vXT + D/RnLX+D3T3UL7HJYHJhAZD5L + 59VvjSPsZJHeDCUyWYrvPZesZ + DIRvhDD52SKvbheeTJUm6Ehkz + ytNN2SN96QRk8j/iI8ib"; +}; + +options { + ... + dnssec-enable yes; + dnssec-validation yes; +}; +</pre> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + None of the keys listed in this example are valid. In particular, + the root key is not valid. + </div> +<p> + When DNSSEC validation is enabled and properly configured, + the resolver will reject any answers from signed, secure zones + which fail to validate, and will return SERVFAIL to the client. + </p> +<p> + Responses may fail to validate for any of several reasons, + including missing, expired, or invalid signatures, a key which + does not match the DS RRset in the parent zone, or an insecure + response from a zone which, according to its parent, should have + been secure. + </p> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p> + When the validator receives a response from an unsigned zone + that has a signed parent, it must confirm with the parent + that the zone was intentionally left unsigned. It does + this by verifying, via signed and validated NSEC/NSEC3 records, + that the parent zone contains no DS records for the child. + </p> +<p> + If the validator <span class="emphasis"><em>can</em></span> prove that the zone + is insecure, then the response is accepted. However, if it + cannot, then it must assume an insecure response to be a + forgery; it rejects the response and logs an error. + </p> +<p> + The logged error reads "insecurity proof failed" and + "got insecure response; parent indicates it should be secure". + (Prior to BIND 9.7, the logged error was "not insecure". + This referred to the zone, not the response.) + </p> +</div> +</div> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="dnssec.dynamic.zones"></a>DNSSEC, Dynamic Zones, and Automatic Signing</h2></div></div></div> +<p>As of BIND 9.7.0 it is possible to change a dynamic zone + from insecure to signed and back again. A secure zone can use + either NSEC or NSEC3 chains.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563413"></a>Converting from insecure to secure</h3></div></div></div></div> +<p>Changing a zone from insecure to secure can be done in two + ways: using a dynamic DNS update, or the + <span><strong class="command">auto-dnssec</strong></span> zone option.</p> +<p>For either method, you need to configure + <span><strong class="command">named</strong></span> so that it can see the + <code class="filename">K*</code> files which contain the public and private + parts of the keys that will be used to sign the zone. These files + will have been generated by + <span><strong class="command">dnssec-keygen</strong></span>. You can do this by placing them + in the key-directory, as specified in + <code class="filename">named.conf</code>:</p> +<pre class="programlisting"> + zone example.net { + type master; + update-policy local; + file "dynamic/example.net/example.net"; + key-directory "dynamic/example.net"; + }; +</pre> +<p>If one KSK and one ZSK DNSKEY key have been generated, this + configuration will cause all records in the zone to be signed + with the ZSK, and the DNSKEY RRset to be signed with the KSK as + well. An NSEC chain will be generated as part of the initial + signing process.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563450"></a>Dynamic DNS update method</h3></div></div></div></div> +<p>To insert the keys via dynamic update:</p> +<pre class="screen"> + % nsupdate + > ttl 3600 + > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= + > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= + > send +</pre> +<p>While the update request will complete almost immediately, + the zone will not be completely signed until + <span><strong class="command">named</strong></span> has had time to walk the zone and + generate the NSEC and RRSIG records. The NSEC record at the apex + will be added last, to signal that there is a complete NSEC + chain.</p> +<p>If you wish to sign using NSEC3 instead of NSEC, you should + add an NSEC3PARAM record to the initial update request. If you + wish the NSEC3 chain to have the OPTOUT bit set, set it in the + flags field of the NSEC3PARAM record.</p> +<pre class="screen"> + % nsupdate + > ttl 3600 + > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= + > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= + > update add example.net NSEC3PARAM 1 1 100 1234567890 + > send +</pre> +<p>Again, this update request will complete almost + immediately; however, the record won't show up until + <span><strong class="command">named</strong></span> has had a chance to build/remove the + relevant chain. A private type record will be created to record + the state of the operation (see below for more details), and will + be removed once the operation completes.</p> +<p>While the initial signing and NSEC/NSEC3 chain generation + is happening, other updates are possible as well.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563555"></a>Fully automatic zone signing</h3></div></div></div></div> +<p>To enable automatic signing, add the + <span><strong class="command">auto-dnssec</strong></span> option to the zone statement in + <code class="filename">named.conf</code>. + <span><strong class="command">auto-dnssec</strong></span> has two possible arguments: + <code class="constant">allow</code> or + <code class="constant">maintain</code>.</p> +<p>With + <span><strong class="command">auto-dnssec allow</strong></span>, + <span><strong class="command">named</strong></span> can search the key directory for keys + matching the zone, insert them into the zone, and use them to + sign the zone. It will do so only when it receives an + <span><strong class="command">rndc sign <zonename></strong></span>.</p> +<p> + + <span><strong class="command">auto-dnssec maintain</strong></span> includes the above + functionality, but will also automatically adjust the zone's + DNSKEY records on schedule according to the keys' timing metadata. + (See <a href="man.dnssec-keygen.html" title="dnssec-keygen"><span class="refentrytitle"><span class="application">dnssec-keygen</span></span>(8)</a> and + <a href="man.dnssec-settime.html" title="dnssec-settime"><span class="refentrytitle"><span class="application">dnssec-settime</span></span>(8)</a> for more information.) + </p> +<p> + <span><strong class="command">named</strong></span> will periodically search the key directory + for keys matching the zone, and if the keys' metadata indicates + that any change should be made the zone, such as adding, removing, + or revoking a key, then that action will be carried out. By default, + the key directory is checked for changes every 60 minutes; this period + can be adjusted with the <code class="option">dnssec-loadkeys-interval</code>, up + to a maximum of 24 hours. The <span><strong class="command">rndc loadkeys</strong></span> forces + <span><strong class="command">named</strong></span> to check for key updates immediately. + </p> +<p> + If keys are present in the key directory the first time the zone + is loaded, the zone will be signed immediately, without waiting for an + <span><strong class="command">rndc sign</strong></span> or <span><strong class="command">rndc loadkeys</strong></span> + command. (Those commands can still be used when there are unscheduled + key changes, however.) + </p> +<p> + If you wish the zone to be signed using NSEC3 instead of NSEC, + submit an NSEC3PARAM record via dynamic update prior to the + scheduled publication and activation of the keys. If you wish the + NSEC3 chain to have the OPTOUT bit set, set it in the flags field + of the NSEC3PARAM record. The NSEC3PARAM record will not appear in + the zone immediately, but it will be stored for later reference. When + the zone is signed and the NSEC3 chain is completed, the NSEC3PARAM + record will appear in the zone. + </p> +<p>Using the + <span><strong class="command">auto-dnssec</strong></span> option requires the zone to be + configured to allow dynamic updates, by adding an + <span><strong class="command">allow-update</strong></span> or + <span><strong class="command">update-policy</strong></span> statement to the zone + configuration. If this has not been done, the configuration will + fail.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563726"></a>Private-type records</h3></div></div></div></div> +<p>The state of the signing process is signaled by + private-type records (with a default type value of 65534). When + signing is complete, these records will have a nonzero value for + the final octet (for those records which have a nonzero initial + octet).</p> +<p>The private type record format: If the first octet is + non-zero then the record indicates that the zone needs to be + signed with the key matching the record, or that all signatures + that match the record should be removed.</p> +<p> + </p> +<div class="literallayout"><p><br> +<br> + algorithm (octet 1)<br> + key id in network order (octet 2 and 3)<br> + removal flag (octet 4)<br> + complete flag (octet 5)<br> +</p></div> +<p> + </p> +<p>Only records flagged as "complete" can be removed via + dynamic update. Attempts to remove other private type records + will be silently ignored.</p> +<p>If the first octet is zero (this is a reserved algorithm + number that should never appear in a DNSKEY record) then the + record indicates changes to the NSEC3 chains are in progress. The + rest of the record contains an NSEC3PARAM record. The flag field + tells what operation to perform based on the flag bits.</p> +<p> + </p> +<div class="literallayout"><p><br> +<br> + 0x01 OPTOUT<br> + 0x80 CREATE<br> + 0x40 REMOVE<br> + 0x20 NONSEC<br> +</p></div> +<p> + </p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563832"></a>DNSKEY rollovers</h3></div></div></div></div> +<p>As with insecure-to-secure conversions, rolling DNSSEC + keys can be done in two ways: using a dynamic DNS update, or the + <span><strong class="command">auto-dnssec</strong></span> zone option.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563845"></a>Dynamic DNS update method</h3></div></div></div></div> +<p> To perform key rollovers via dynamic update, you need to add + the <code class="filename">K*</code> files for the new keys so that + <span><strong class="command">named</strong></span> can find them. You can then add the new + DNSKEY RRs via dynamic update. + <span><strong class="command">named</strong></span> will then cause the zone to be signed + with the new keys. When the signing is complete the private type + records will be updated so that the last octet is non + zero.</p> +<p>If this is for a KSK you need to inform the parent and any + trust anchor repositories of the new KSK.</p> +<p>You should then wait for the maximum TTL in the zone before + removing the old DNSKEY. If it is a KSK that is being updated, + you also need to wait for the DS RRset in the parent to be + updated and its TTL to expire. This ensures that all clients will + be able to verify at least one signature when you remove the old + DNSKEY.</p> +<p>The old DNSKEY can be removed via UPDATE. Take care to + specify the correct key. + <span><strong class="command">named</strong></span> will clean out any signatures generated + by the old key after the update completes.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563878"></a>Automatic key rollovers</h3></div></div></div></div> +<p>When a new key reaches its activation date (as set by + <span><strong class="command">dnssec-keygen</strong></span> or <span><strong class="command">dnssec-settime</strong></span>), + if the <span><strong class="command">auto-dnssec</strong></span> zone option is set to + <code class="constant">maintain</code>, <span><strong class="command">named</strong></span> will + automatically carry out the key rollover. If the key's algorithm + has not previously been used to sign the zone, then the zone will + be fully signed as quickly as possible. However, if the new key + is replacing an existing key of the same algorithm, then the + zone will be re-signed incrementally, with signatures from the + old key being replaced with signatures from the new key as their + signature validity periods expire. By default, this rollover + completes in 30 days, after which it will be safe to remove the + old key from the DNSKEY RRset.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563905"></a>NSEC3PARAM rollovers via UPDATE</h3></div></div></div></div> +<p>Add the new NSEC3PARAM record via dynamic update. When the + new NSEC3 chain has been generated, the NSEC3PARAM flag field + will be zero. At this point you can remove the old NSEC3PARAM + record. The old chain will be removed after the update request + completes.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563914"></a>Converting from NSEC to NSEC3</h3></div></div></div></div> +<p>To do this, you just need to add an NSEC3PARAM record. When + the conversion is complete, the NSEC chain will have been removed + and the NSEC3PARAM record will have a zero flag field. The NSEC3 + chain will be generated before the NSEC chain is + destroyed.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563924"></a>Converting from NSEC3 to NSEC</h3></div></div></div></div> +<p>To do this, use <span><strong class="command">nsupdate</strong></span> to + remove all NSEC3PARAM records with a zero flag + field. The NSEC chain will be generated before the NSEC3 chain is + removed.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2563937"></a>Converting from secure to insecure</h3></div></div></div></div> +<p>To convert a signed zone to unsigned using dynamic DNS, + delete all the DNSKEY records from the zone apex using + <span><strong class="command">nsupdate</strong></span>. All signatures, NSEC or NSEC3 chains, + and associated NSEC3PARAM records will be removed automatically. + This will take place after the update request completes.</p> +<p> This requires the + <span><strong class="command">dnssec-secure-to-insecure</strong></span> option to be set to + <strong class="userinput"><code>yes</code></strong> in + <code class="filename">named.conf</code>.</p> +<p>In addition, if the <span><strong class="command">auto-dnssec maintain</strong></span> + zone statement is used, it should be removed or changed to + <span><strong class="command">allow</strong></span> instead (or it will re-sign). + </p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2572029"></a>Periodic re-signing</h3></div></div></div></div> +<p>In any secure zone which supports dynamic updates, named + will periodically re-sign RRsets which have not been re-signed as + a result of some update action. The signature lifetimes will be + adjusted so as to spread the re-sign load over time rather than + all at once.</p> +<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"> +<a name="id2572039"></a>NSEC3 and OPTOUT</h3></div></div></div></div> +<p> + <span><strong class="command">named</strong></span> only supports creating new NSEC3 chains + where all the NSEC3 records in the zone have the same OPTOUT + state. + <span><strong class="command">named</strong></span> supports UPDATES to zones where the NSEC3 + records in the chain have mixed OPTOUT state. + <span><strong class="command">named</strong></span> does not support changing the OPTOUT + state of an individual NSEC3 record, the entire chain needs to be + changed if the OPTOUT state of an individual NSEC3 needs to be + changed.</p> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="rfc5011.support"></a>Dynamic Trust Anchor Management</h2></div></div></div> +<p>BIND 9.7.0 introduces support for RFC 5011, dynamic trust + anchor management. Using this feature allows + <span><strong class="command">named</strong></span> to keep track of changes to critical + DNSSEC keys without any need for the operator to make changes to + configuration files.</p> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2572072"></a>Validating Resolver</h3></div></div></div> +<p>To configure a validating resolver to use RFC 5011 to + maintain a trust anchor, configure the trust anchor using a + <span><strong class="command">managed-keys</strong></span> statement. Information about + this can be found in + <a href="Bv9ARM.ch06.html#managed-keys" title="managed-keys Statement Definition + and Usage">the section called “<span><strong class="command">managed-keys</strong></span> Statement Definition + and Usage”</a>.</p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2609027"></a>Authoritative Server</h3></div></div></div> +<p>To set up an authoritative zone for RFC 5011 trust anchor + maintenance, generate two (or more) key signing keys (KSKs) for + the zone. Sign the zone with one of them; this is the "active" + KSK. All KSK's which do not sign the zone are "stand-by" + keys.</p> +<p>Any validating resolver which is configured to use the + active KSK as an RFC 5011-managed trust anchor will take note + of the stand-by KSKs in the zone's DNSKEY RRset, and store them + for future reference. The resolver will recheck the zone + periodically, and after 30 days, if the new key is still there, + then the key will be accepted by the resolver as a valid trust + anchor for the zone. Any time after this 30-day acceptance + timer has completed, the active KSK can be revoked, and the + zone can be "rolled over" to the newly accepted key.</p> +<p>The easiest way to place a stand-by key in a zone is to + use the "smart signing" features of + <span><strong class="command">dnssec-keygen</strong></span> and + <span><strong class="command">dnssec-signzone</strong></span>. If a key with a publication + date in the past, but an activation date which is unset or in + the future, " + <span><strong class="command">dnssec-signzone -S</strong></span>" will include the DNSKEY + record in the zone, but will not sign with it:</p> +<pre class="screen"> +$ <strong class="userinput"><code>dnssec-keygen -K keys -f KSK -P now -A now+2y example.net</code></strong> +$ <strong class="userinput"><code>dnssec-signzone -S -K keys example.net</code></strong> +</pre> +<p>To revoke a key, the new command + <span><strong class="command">dnssec-revoke</strong></span> has been added. This adds the + REVOKED bit to the key flags and re-generates the + <code class="filename">K*.key</code> and + <code class="filename">K*.private</code> files.</p> +<p>After revoking the active key, the zone must be signed + with both the revoked KSK and the new active KSK. (Smart + signing takes care of this automatically.)</p> +<p>Once a key has been revoked and used to sign the DNSKEY + RRset in which it appears, that key will never again be + accepted as a valid trust anchor by the resolver. However, + validation can proceed using the new active key (which had been + accepted by the resolver when it was a stand-by key).</p> +<p>See RFC 5011 for more details on key rollover + scenarios.</p> +<p>When a key has been revoked, its key ID changes, + increasing by 128, and wrapping around at 65535. So, for + example, the key "<code class="filename">Kexample.com.+005+10000</code>" becomes + "<code class="filename">Kexample.com.+005+10128</code>".</p> +<p>If two keys have ID's exactly 128 apart, and one is + revoked, then the two key ID's will collide, causing several + problems. To prevent this, + <span><strong class="command">dnssec-keygen</strong></span> will not generate a new key if + another key is present which may collide. This checking will + only occur if the new keys are written to the same directory + which holds all other keys in use for that zone.</p> +<p>Older versions of BIND 9 did not have this precaution. + Exercise caution if using key revocation on keys that were + generated by previous releases, or if using keys stored in + multiple directories or on multiple machines.</p> +<p>It is expected that a future release of BIND 9 will + address this problem in a different way, by storing revoked + keys with their original unrevoked key ID's.</p> +</div> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="pkcs11"></a>PKCS #11 (Cryptoki) support</h2></div></div></div> +<p>PKCS #11 (Public Key Cryptography Standard #11) defines a + platform- independent API for the control of hardware security + modules (HSMs) and other cryptographic support devices.</p> +<p>BIND 9 is known to work with two HSMs: The Sun SCA 6000 + cryptographic acceleration board, tested under Solaris x86, and + the AEP Keyper network-attached key storage device, tested with + Debian Linux, Solaris x86 and Windows Server 2003.</p> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2611929"></a>Prerequisites</h3></div></div></div> +<p>See the HSM vendor documentation for information about + installing, initializing, testing and troubleshooting the + HSM.</p> +<p>BIND 9 uses OpenSSL for cryptography, but stock OpenSSL + does not yet fully support PKCS #11. However, a PKCS #11 engine + for OpenSSL is available from the OpenSolaris project. It has + been modified by ISC to work with with BIND 9, and to provide + new features such as PIN management and key by + reference.</p> +<p>The patched OpenSSL depends on a "PKCS #11 provider". + This is a shared library object, providing a low-level PKCS #11 + interface to the HSM hardware. It is dynamically loaded by + OpenSSL at runtime. The PKCS #11 provider comes from the HSM + vendor, and is specific to the HSM to be controlled.</p> +<p>There are two "flavors" of PKCS #11 support provided by + the patched OpenSSL, one of which must be chosen at + configuration time. The correct choice depends on the HSM + hardware:</p> +<div class="itemizedlist"><ul type="disc"> +<li><p>Use 'crypto-accelerator' with HSMs that have hardware + cryptographic acceleration features, such as the SCA 6000 + board. This causes OpenSSL to run all supported + cryptographic operations in the HSM.</p></li> +<li><p>Use 'sign-only' with HSMs that are designed to + function primarily as secure key storage devices, but lack + hardware acceleration. These devices are highly secure, but + are not necessarily any faster at cryptography than the + system CPU — often, they are slower. It is therefore + most efficient to use them only for those cryptographic + functions that require access to the secured private key, + such as zone signing, and to use the system CPU for all + other computationally-intensive operations. The AEP Keyper + is an example of such a device.</p></li> +</ul></div> +<p>The modified OpenSSL code is included in the BIND 9 release, + in the form of a context diff against the latest verions of + OpenSSL. OpenSSL 0.9.8 and 1.0.0 are both supported; there are + separate diffs for each version. In the examples to follow, + we use OpenSSL 0.9.8, but the same methods work with OpenSSL 1.0.0. + </p> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + The latest OpenSSL versions at the time of the BIND release + are 0.9.8s and 1.0.0f. + ISC will provide an updated patch as new versions of OpenSSL + are released. The version number in the following examples + is expected to change.</div> +<p> + Before building BIND 9 with PKCS #11 support, it will be + necessary to build OpenSSL with this patch in place and inform + it of the path to the HSM-specific PKCS #11 provider + library.</p> +<p>Obtain OpenSSL 0.9.8s:</p> +<pre class="screen"> +$ <strong class="userinput"><code>wget <a href="" target="_top">http://www.openssl.org/source/openssl-0.9.8s.tar.gz</a></code></strong> +</pre> +<p>Extract the tarball:</p> +<pre class="screen"> +$ <strong class="userinput"><code>tar zxf openssl-0.9.8s.tar.gz</code></strong> +</pre> +<p>Apply the patch from the BIND 9 release:</p> +<pre class="screen"> +$ <strong class="userinput"><code>patch -p1 -d openssl-0.9.8s \ + < bind9/bin/pkcs11/openssl-0.9.8s-patch</code></strong> +</pre> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3>(Note that the patch file may not be compatible with the + "patch" utility on all operating systems. You may need to + install GNU patch.)</div> +<p>When building OpenSSL, place it in a non-standard + location so that it does not interfere with OpenSSL libraries + elsewhere on the system. In the following examples, we choose + to install into "/opt/pkcs11/usr". We will use this location + when we configure BIND 9.</p> +<div class="sect3" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2609772"></a>Building OpenSSL for the AEP Keyper on Linux</h4></div></div></div> +<p>The AEP Keyper is a highly secure key storage device, + but does not provide hardware cryptographic acceleration. It + can carry out cryptographic operations, but it is probably + slower than your system's CPU. Therefore, we choose the + 'sign-only' flavor when building OpenSSL.</p> +<p>The Keyper-specific PKCS #11 provider library is + delivered with the Keyper software. In this example, we place + it /opt/pkcs11/usr/lib:</p> +<pre class="screen"> +$ <strong class="userinput"><code>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</code></strong> +</pre> +<p>This library is only available for Linux as a 32-bit + binary. If we are compiling on a 64-bit Linux system, it is + necessary to force a 32-bit build, by specifying -m32 in the + build options.</p> +<p>Finally, the Keyper library requires threads, so we + must specify -pthread.</p> +<pre class="screen"> +$ <strong class="userinput"><code>cd openssl-0.9.8s</code></strong> +$ <strong class="userinput"><code>./Configure linux-generic32 -m32 -pthread \ + --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \ + --pk11-flavor=sign-only \ + --prefix=/opt/pkcs11/usr</code></strong> +</pre> +<p>After configuring, run "<span><strong class="command">make</strong></span>" + and "<span><strong class="command">make test</strong></span>". If "<span><strong class="command">make + test</strong></span>" fails with "pthread_atfork() not found", you forgot to + add the -pthread above.</p> +</div> +<div class="sect3" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2609910"></a>Building OpenSSL for the SCA 6000 on Solaris</h4></div></div></div> +<p>The SCA-6000 PKCS #11 provider is installed as a system + library, libpkcs11. It is a true crypto accelerator, up to 4 + times faster than any CPU, so the flavor shall be + 'crypto-accelerator'.</p> +<p>In this example, we are building on Solaris x86 on an + AMD64 system.</p> +<pre class="screen"> +$ <strong class="userinput"><code>cd openssl-0.9.8s</code></strong> +$ <strong class="userinput"><code>./Configure solaris64-x86_64-cc \ + --pk11-libname=/usr/lib/64/libpkcs11.so \ + --pk11-flavor=crypto-accelerator \ + --prefix=/opt/pkcs11/usr</code></strong> +</pre> +<p>(For a 32-bit build, use "solaris-x86-cc" and + /usr/lib/libpkcs11.so.)</p> +<p>After configuring, run + <span><strong class="command">make</strong></span> and + <span><strong class="command">make test</strong></span>.</p> +</div> +<div class="sect3" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2609959"></a>Building OpenSSL for SoftHSM</h4></div></div></div> +<p>SoftHSM is a software library provided by the OpenDNSSEC + project (http://www.opendnssec.org) which provides a PKCS#11 + interface to a virtual HSM, implemented in the form of encrypted + data on the local filesystem. It uses the Botan library for + encryption and SQLite3 for data storage. Though less secure + than a true HSM, it can provide more secure key storage than + traditional key files, and can allow you to experiment with + PKCS#11 when an HSM is not available.</p> +<p>The SoftHSM cryptographic store must be installed and + initialized before using it with OpenSSL, and the SOFTHSM_CONF + environment variable must always point to the SoftHSM configuration + file:</p> +<pre class="screen"> +$ <strong class="userinput"><code> cd softhsm-1.3.0 </code></strong> +$ <strong class="userinput"><code> configure --prefix=/opt/pkcs11/usr </code></strong> +$ <strong class="userinput"><code> make </code></strong> +$ <strong class="userinput"><code> make install </code></strong> +$ <strong class="userinput"><code> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </code></strong> +$ <strong class="userinput"><code> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </code></strong> +$ <strong class="userinput"><code> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </code></strong> +</pre> +<p>SoftHSM can perform all cryptographic operations, but + since it only uses your system CPU, there is no need to use it + for anything but signing. Therefore, we choose the 'sign-only' + flavor when building OpenSSL.</p> +<pre class="screen"> +$ <strong class="userinput"><code>cd openssl-0.9.8s</code></strong> +$ <strong class="userinput"><code>./Configure linux-x86_64 -pthread \ + --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \ + --pk11-flavor=sign-only \ + --prefix=/opt/pkcs11/usr</code></strong> +</pre> +<p>After configuring, run "<span><strong class="command">make</strong></span>" + and "<span><strong class="command">make test</strong></span>".</p> +</div> +<p>Once you have built OpenSSL, run + "<span><strong class="command">apps/openssl engine pkcs11</strong></span>" to confirm + that PKCS #11 support was compiled in correctly. The output + should be one of the following lines, depending on the flavor + selected:</p> +<pre class="screen"> + (pkcs11) PKCS #11 engine support (sign only) +</pre> +<p>Or:</p> +<pre class="screen"> + (pkcs11) PKCS #11 engine support (crypto accelerator) +</pre> +<p>Next, run + "<span><strong class="command">apps/openssl engine pkcs11 -t</strong></span>". This will + attempt to initialize the PKCS #11 engine. If it is able to + do so successfully, it will report + “<span class="quote"><code class="literal">[ available ]</code></span>”.</p> +<p>If the output is correct, run + "<span><strong class="command">make install</strong></span>" which will install the + modified OpenSSL suite to + <code class="filename">/opt/pkcs11/usr</code>.</p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2610179"></a>Building BIND 9 with PKCS#11</h3></div></div></div> +<p>When building BIND 9, the location of the custom-built + OpenSSL library must be specified via configure.</p> +<div class="sect3" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2610187"></a>Configuring BIND 9 for Linux with the AEP Keyper</h4></div></div></div> +<p>To link with the PKCS #11 provider, threads must be + enabled in the BIND 9 build.</p> +<p>The PKCS #11 library for the AEP Keyper is currently + only available as a 32-bit binary. If we are building on a + 64-bit host, we must force a 32-bit build by adding "-m32" to + the CC options on the "configure" command line.</p> +<pre class="screen"> +$ <strong class="userinput"><code>cd ../bind9</code></strong> +$ <strong class="userinput"><code>./configure CC="gcc -m32" --enable-threads \ + --with-openssl=/opt/pkcs11/usr \ + --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</code></strong> +</pre> +</div> +<div class="sect3" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2610219"></a>Configuring BIND 9 for Solaris with the SCA 6000</h4></div></div></div> +<p>To link with the PKCS #11 provider, threads must be + enabled in the BIND 9 build.</p> +<pre class="screen"> +$ <strong class="userinput"><code>cd ../bind9</code></strong> +$ <strong class="userinput"><code>./configure CC="cc -xarch=amd64" --enable-threads \ + --with-openssl=/opt/pkcs11/usr \ + --with-pkcs11=/usr/lib/64/libpkcs11.so</code></strong> +</pre> +<p>(For a 32-bit build, omit CC="cc -xarch=amd64".)</p> +<p>If configure complains about OpenSSL not working, you + may have a 32/64-bit architecture mismatch. Or, you may have + incorrectly specified the path to OpenSSL (it should be the + same as the --prefix argument to the OpenSSL + Configure).</p> +</div> +<div class="sect3" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id2612235"></a>Configuring BIND 9 for SoftHSM</h4></div></div></div> +<pre class="screen"> +$ <strong class="userinput"><code>cd ../bind9</code></strong> +$ <strong class="userinput"><code>./configure --enable-threads \ + --with-openssl=/opt/pkcs11/usr \ + --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</code></strong> +</pre> +</div> +<p>After configuring, run + "<span><strong class="command">make</strong></span>", + "<span><strong class="command">make test</strong></span>" and + "<span><strong class="command">make install</strong></span>".</p> +<p>(Note: If "make test" fails in the "pkcs11" system test, you may + have forgotten to set the SOFTHSM_CONF environment variable.)</p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2612283"></a>PKCS #11 Tools</h3></div></div></div> +<p>BIND 9 includes a minimal set of tools to operate the + HSM, including + <span><strong class="command">pkcs11-keygen</strong></span> to generate a new key pair + within the HSM, + <span><strong class="command">pkcs11-list</strong></span> to list objects currently + available, and + <span><strong class="command">pkcs11-destroy</strong></span> to remove objects.</p> +<p>In UNIX/Linux builds, these tools are built only if BIND + 9 is configured with the --with-pkcs11 option. (NOTE: If + --with-pkcs11 is set to "yes", rather than to the path of the + PKCS #11 provider, then the tools will be built but the + provider will be left undefined. Use the -m option or the + PKCS11_PROVIDER environment variable to specify the path to the + provider.)</p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2612382"></a>Using the HSM</h3></div></div></div> +<p>First, we must set up the runtime environment so the + OpenSSL and PKCS #11 libraries can be loaded:</p> +<pre class="screen"> +$ <strong class="userinput"><code>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</code></strong> +</pre> +<p>When operating an AEP Keyper, it is also necessary to + specify the location of the "machine" file, which stores + information about the Keyper for use by PKCS #11 provider + library. If the machine file is in + <code class="filename">/opt/Keyper/PKCS11Provider/machine</code>, + use:</p> +<pre class="screen"> +$ <strong class="userinput"><code>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</code></strong> +</pre> +<p>These environment variables must be set whenever running + any tool that uses the HSM, including + <span><strong class="command">pkcs11-keygen</strong></span>, + <span><strong class="command">pkcs11-list</strong></span>, + <span><strong class="command">pkcs11-destroy</strong></span>, + <span><strong class="command">dnssec-keyfromlabel</strong></span>, + <span><strong class="command">dnssec-signzone</strong></span>, + <span><strong class="command">dnssec-keygen</strong></span>(which will use the HSM for + random number generation), and + <span><strong class="command">named</strong></span>.</p> +<p>We can now create and use keys in the HSM. In this case, + we will create a 2048 bit key and give it the label + "sample-ksk":</p> +<pre class="screen"> +$ <strong class="userinput"><code>pkcs11-keygen -b 2048 -l sample-ksk</code></strong> +</pre> +<p>To confirm that the key exists:</p> +<pre class="screen"> +$ <strong class="userinput"><code>pkcs11-list</code></strong> +Enter PIN: +object[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0] +object[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0] +</pre> +<p>Before using this key to sign a zone, we must create a + pair of BIND 9 key files. The "dnssec-keyfromlabel" utility + does this. In this case, we will be using the HSM key + "sample-ksk" as the key-signing key for "example.net":</p> +<pre class="screen"> +$ <strong class="userinput"><code>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</code></strong> +</pre> +<p>The resulting K*.key and K*.private files can now be used + to sign the zone. Unlike normal K* files, which contain both + public and private key data, these files will contain only the + public key data, plus an identifier for the private key which + remains stored within the HSM. The HSM handles signing with the + private key.</p> +<p>If you wish to generate a second key in the HSM for use + as a zone-signing key, follow the same procedure above, using a + different keylabel, a smaller key size, and omitting "-f KSK" + from the dnssec-keyfromlabel arguments:</p> +<pre class="screen"> +$ <strong class="userinput"><code>pkcs11-keygen -b 1024 -l sample-zsk</code></strong> +$ <strong class="userinput"><code>dnssec-keyfromlabel -l sample-zsk example.net</code></strong> +</pre> +<p>Alternatively, you may prefer to generate a conventional + on-disk key, using dnssec-keygen:</p> +<pre class="screen"> +$ <strong class="userinput"><code>dnssec-keygen example.net</code></strong> +</pre> +<p>This provides less security than an HSM key, but since + HSMs can be slow or cumbersome to use for security reasons, it + may be more efficient to reserve HSM keys for use in the less + frequent key-signing operation. The zone-signing key can be + rolled more frequently, if you wish, to compensate for a + reduction in key security.</p> +<p>Now you can sign the zone. (Note: If not using the -S + option to + <span><strong class="command">dnssec-signzone</strong></span>, it will be necessary to add + the contents of both + <code class="filename">K*.key</code> files to the zone master file before + signing it.)</p> +<pre class="screen"> +$ <strong class="userinput"><code>dnssec-signzone -S example.net</code></strong> +Enter PIN: +Verifying the zone using the following algorithms: +NSEC3RSASHA1. +Zone signing complete: +Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by +example.net.signed +</pre> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2636884"></a>Specifying the engine on the command line</h3></div></div></div> +<p>The OpenSSL engine can be specified in + <span><strong class="command">named</strong></span> and all of the BIND + <span><strong class="command">dnssec-*</strong></span> tools by using the "-E + <engine>" command line option. If BIND 9 is built with + the --with-pkcs11 option, this option defaults to "pkcs11". + Specifying the engine will generally not be necessary unless + for some reason you wish to use a different OpenSSL + engine.</p> +<p>If you wish to disable use of the "pkcs11" engine — + for troubleshooting purposes, or because the HSM is unavailable + — set the engine to the empty string. For example:</p> +<pre class="screen"> +$ <strong class="userinput"><code>dnssec-signzone -E '' -S example.net</code></strong> +</pre> +<p>This causes + <span><strong class="command">dnssec-signzone</strong></span> to run as if it were compiled + without the --with-pkcs11 option.</p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2636930"></a>Running named with automatic zone re-signing</h3></div></div></div> +<p>If you want + <span><strong class="command">named</strong></span> to dynamically re-sign zones using HSM + keys, and/or to to sign new records inserted via nsupdate, then + named must have access to the HSM PIN. This can be accomplished + by placing the PIN into the openssl.cnf file (in the above + examples, + <code class="filename">/opt/pkcs11/usr/ssl/openssl.cnf</code>).</p> +<p>The location of the openssl.cnf file can be overridden by + setting the OPENSSL_CONF environment variable before running + named.</p> +<p>Sample openssl.cnf:</p> +<pre class="programlisting"> + openssl_conf = openssl_def + [ openssl_def ] + engines = engine_section + [ engine_section ] + pkcs11 = pkcs11_section + [ pkcs11_section ] + PIN = <em class="replaceable"><code><PLACE PIN HERE></code></em> +</pre> +<p>This will also allow the dnssec-* tools to access the HSM + without PIN entry. (The pkcs11-* tools access the HSM directly, + not via OpenSSL, so a PIN will still be required to use + them.)</p> +<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Warning</h3> +<p>Placing the HSM's PIN in a text file in + this manner may reduce the security advantage of using an + HSM. Be sure this is what you want to do before configuring + OpenSSL in this way.</p> +</div> +</div> +</div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="id2572842"></a>IPv6 Support in <acronym class="acronym">BIND</acronym> 9</h2></div></div></div> +<p> + <acronym class="acronym">BIND</acronym> 9 fully supports all currently + defined forms of IPv6 name to address and address to name + lookups. It will also use IPv6 addresses to make queries when + running on an IPv6 capable system. + </p> +<p> + For forward lookups, <acronym class="acronym">BIND</acronym> 9 supports + only AAAA records. RFC 3363 deprecated the use of A6 records, + and client-side support for A6 records was accordingly removed + from <acronym class="acronym">BIND</acronym> 9. + However, authoritative <acronym class="acronym">BIND</acronym> 9 name servers still + load zone files containing A6 records correctly, answer queries + for A6 records, and accept zone transfer for a zone containing A6 + records. + </p> +<p> + For IPv6 reverse lookups, <acronym class="acronym">BIND</acronym> 9 supports + the traditional "nibble" format used in the + <span class="emphasis"><em>ip6.arpa</em></span> domain, as well as the older, deprecated + <span class="emphasis"><em>ip6.int</em></span> domain. + Older versions of <acronym class="acronym">BIND</acronym> 9 + supported the "binary label" (also known as "bitstring") format, + but support of binary labels has been completely removed per + RFC 3363. + Many applications in <acronym class="acronym">BIND</acronym> 9 do not understand + the binary label format at all any more, and will return an + error if given. + In particular, an authoritative <acronym class="acronym">BIND</acronym> 9 + name server will not load a zone file containing binary labels. + </p> +<p> + For an overview of the format and structure of IPv6 addresses, + see <a href="Bv9ARM.ch09.html#ipv6addresses" title="IPv6 addresses (AAAA)">the section called “IPv6 addresses (AAAA)”</a>. + </p> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2573109"></a>Address Lookups Using AAAA Records</h3></div></div></div> +<p> + The IPv6 AAAA record is a parallel to the IPv4 A record, + and, unlike the deprecated A6 record, specifies the entire + IPv6 address in a single record. For example, + </p> +<pre class="programlisting"> +$ORIGIN example.com. +host 3600 IN AAAA 2001:db8::1 +</pre> +<p> + Use of IPv4-in-IPv6 mapped addresses is not recommended. + If a host has an IPv4 address, use an A record, not + a AAAA, with <code class="literal">::ffff:192.168.42.1</code> as + the address. + </p> +</div> +<div class="sect2" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id2573130"></a>Address to Name Lookups Using Nibble Format</h3></div></div></div> +<p> + When looking up an address in nibble format, the address + components are simply reversed, just as in IPv4, and + <code class="literal">ip6.arpa.</code> is appended to the + resulting name. + For example, the following would provide reverse name lookup for + a host with address + <code class="literal">2001:db8::1</code>. + </p> +<pre class="programlisting"> +$ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. +1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0 14400 IN PTR ( + host.example.com. ) +</pre> +</div> +</div> +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch03.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch05.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Chapter 3. Name Server Configuration </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Chapter 5. The <acronym class="acronym">BIND</acronym> 9 Lightweight Resolver</td> +</tr> +</table> +</div> +</body> +</html> |
