Chapter 4. Advanced DNS Features

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 .jnl 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.

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 .jnw and .jbk; under ordinary circumstances, these will be removed when the dump is complete, and can be safely ignored.

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.

Changes that result from incoming incremental zone transfers are also journalled in a similar way.

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 rndc stop.

If you have to make changes to a dynamic zone manually, the following procedure will work: Disable dynamic updates to the zone using rndc freeze zone. This will update the zone's master file with the changes stored in its .jnl file. Edit the zone file. Run rndc thaw zone to reload the changed zone and re-enable dynamic updates.

rndc sync zone will update the zone file with changes from the journal file without stopping dynamic updates; this may be useful for viewing the current zone state. To remove the .jnl file after updating the zone file, use rndc sync -clean.

Let's say a company named Example, Inc. (example.com) 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.

Example, Inc. 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.

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.

The internal servers will be configured to forward all queries, except queries for site1.internal, site2.internal, site1.example.com, and site2.example.com, to the servers in the DMZ. These internal servers will have complete sets of information for site1.example.com, site2.example.com, site1.internal, and site2.internal.

To protect the site1.internal and site2.internal domains, the internal name servers must be configured to disallow all queries to these domains from any external hosts, including the bastion hosts.

The external servers, which are on the bastion hosts, will be configured to serve the "public" version of the site1 and site2.example.com zones. This could include things such as the host records for public servers (www.example.com and ftp.example.com), and mail exchange (MX) records (a.mx.example.com and b.mx.example.com).

In addition, the public site1 and site2.example.com 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.

Here's an example of a wildcard MX record:

*   IN MX 10 external1.example.com.

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.

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.

In order for all this to work properly, internal clients will need to be configured to query only the internal name servers for DNS queries. This could also be enforced via selective filtering on the network.

If everything has been set properly, Example, Inc.'s internal clients will now be able to:

Hosts on the Internet will be able to:

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 the section called “Sample Configurations”.

Internal DNS server config:

acl internals { 172.16.72.0/24; 192.168.1.0/24; };

acl externals { bastion-ips-go-here; };

options {
    ...
    ...
    forward only;
    // forward to external servers
    forwarders {
        bastion-ips-go-here;
    };
    // 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; }
};

External (bastion host) DNS server config:

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; }
};

In the resolv.conf (or equivalent) on the bastion host(s):

search ...
nameserver 172.16.72.2
nameserver 172.16.72.3
nameserver 172.16.72.4

TSIG keys can be generated using the tsig-keygen command; the output of the command is a key directive suitable for inclusion in named.conf. The key name, algorithm and size can be specified by command line parameters; the defaults are "tsig-key", HMAC-SHA256, and 256 bits, respectively.

Any string which is a valid DNS name can be used as a key name. For example, a key to be shared between servers called host1 and host2 could be called "host1-host2.", and this key could be generated using:

  $ tsig-keygen host1-host2. > host1-host2.key

This key may then be copied to both hosts. The key name and secret must be identical on both hosts. (Note: copying a shared secret from one server to another is beyond the scope of the DNS. A secure transport mechanism should be used: secure FTP, SSL, ssh, telephone, encrypted email, etc.)

tsig-keygen can also be run as ddns-confgen, in which case its output includes additional configuration text for setting up dynamic DNS in named. See ddns-confgen(8) for details.

For a key shared between servers called host1 and host2, the following could be added to each server's named.conf file:

key "host1-host2." {
        algorithm hmac-sha256;
        secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY=";
};

(This is the same key generated above using tsig-keygen.)

Since this text contains a secret, it is recommended that either named.conf not be world-readable, or that the key directive be stored in a file which is not world-readable, and which is included in named.conf via the include directive.

Once a key has been added to named.conf and the server has been restarted or reconfigured, the server can recognize the key. If the server receives a message signed by the key, it will be able to verify the signature. If the signature is valid, the response will be signed using the same key.

TSIG keys that are known to a server can be listed using the command rndc tsig-list.

A server sending a request to another server must be told whether to use a key, and if so, which key to use.

For example, a key may be specified for each server in the masters statement in the definition of a slave zone; in this case, all SOA QUERY messages, NOTIFY messages, and zone transfer requests (AXFR or IXFR) will be signed using the specified key. Keys may also be specified in the also-notify statement of a master or slave zone, causing NOTIFY messages to be signed using the specified key.

Keys can also be specified in a server directive. Adding the following on host1, if the IP address of host2 is 10.1.2.3, would cause all requests from host1 to host2, including normal DNS queries, to be signed using the host1-host2. key:

server 10.1.2.3 {
        keys { host1-host2. ;};
};

Multiple keys may be present in the keys statement, but only the first one is used. As this directive does not contain secrets, it can be used in a world-readable file.

Requests sent by host2 to host1 would not be signed, unless a similar server directive were in host2's configuration file.

Whenever any server sends a TSIG-signed DNS request, it will expect the response to be signed with the same key. If a response is not signed, or if the signature is not valid, the response will be rejected.

TSIG keys may be specified in ACL definitions and ACL directives such as allow-query, allow-transfer and allow-update. The above key would be denoted in an ACL element as key host1-host2.

An example of an allow-update directive using a TSIG key:

allow-update { !{ !localnets; any; }; key host1-host2. ;};

This allows dynamic updates to succeed only if the UPDATE request comes from an address in localnets, and if it is signed using the host1-host2. key.

See the section called “Dynamic Update Policies” for a discussion of the more flexible update-policy statement.

Processing of TSIG-signed messages can result in several errors:

In all of the above cases, the server will return a response code of NOTAUTH (not authenticated).

The dnssec-keygen program is used to generate keys.

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 ZONE, 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.

The following command will generate a 768-bit RSASHA1 key for the child.example zone:

dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example.

Two output files will be produced: Kchild.example.+005+12345.key and Kchild.example.+005+12345.private (where 12345 is an example of a key tag). The key filenames contain the key name (child.example.), algorithm (3 is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in this case). The private key (in the .private file) is used to generate signatures, and the public key (in the .key file) is used for signature verification.

To generate another key with the same properties (but with a different key tag), repeat the above command.

The dnssec-keyfromlabel program is used to get a key pair from a crypto hardware and build the key files. Its usage is similar to dnssec-keygen.

The public keys should be inserted into the zone file by including the .key files using $INCLUDE statements.

The dnssec-signzone program is used to sign a zone.

Any keyset files corresponding to secure subzones should be present. The zone signer will generate NSEC, NSEC3 and RRSIG records for the zone, as well as DS for the child zones if '-g' is specified. If '-g' is not specified, then DS RRsets for the secure child zones need to be added manually.

The following command signs the zone, assuming it is in a file called zone.child.example. By default, all zone keys which have an available private key are used to generate signatures.

dnssec-signzone -o child.example zone.child.example

One output file is produced: zone.child.example.signed. This file should be referenced by named.conf as the input file for the zone.

dnssec-signzone will also produce a keyset and dsset files and optionally a dlvset file. These are used to provide the parent zone administrators with the DNSKEYs (or their corresponding DS records) that are the secure entry point to the zone.

To enable named to respond appropriately to DNS requests from DNSSEC aware clients, dnssec-enable must be set to yes. (This is the default setting.)

To enable named to validate answers from other servers, the dnssec-enable option must be set to yes, and the dnssec-validation options must be set to yes or auto.

If dnssec-validation is set to auto, then a default trust anchor for the DNS root zone will be used. If it is set to yes, however, then at least one trust anchor must be configured with a trusted-keys or managed-keys statement in named.conf, or DNSSEC validation will not occur. The default setting is yes.

trusted-keys 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 trusted-keys (and corresponding zones) are deemed to exist and only the listed keys will be used to validated the DNSKEY RRset that they are from.

managed-keys are trusted keys which are automatically kept up to date via RFC 5011 trust anchor maintenance.

trusted-keys and managed-keys are described in more detail later in this document.

Unlike BIND 8, BIND 9 does not verify signatures on load, so zone keys for authoritative zones do not need to be specified in the configuration file.

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 named is immune to compromises in the DNSSEC components of the security of parent zones.

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;
};

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.

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.

To configure a validating resolver to use RFC 5011 to maintain a trust anchor, configure the trust anchor using a managed-keys statement. Information about this can be found in the section called “managed-keys Statement Definition and Usage”.

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 KSKs which do not sign the zone are "stand-by" keys.

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.

The easiest way to place a stand-by key in a zone is to use the "smart signing" features of dnssec-keygen and dnssec-signzone. If a key with a publication date in the past, but an activation date which is unset or in the future, " dnssec-signzone -S" will include the DNSKEY record in the zone, but will not sign with it:

$ dnssec-keygen -K keys -f KSK -P now -A now+2y example.net
$ dnssec-signzone -S -K keys example.net

To revoke a key, the new command dnssec-revoke has been added. This adds the REVOKED bit to the key flags and re-generates the K*.key and K*.private files.

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.)

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).

See RFC 5011 for more details on key rollover scenarios.

When a key has been revoked, its key ID changes, increasing by 128, and wrapping around at 65535. So, for example, the key "Kexample.com.+005+10000" becomes "Kexample.com.+005+10128".

If two keys have IDs exactly 128 apart, and one is revoked, then the two key IDs will collide, causing several problems. To prevent this, dnssec-keygen 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.

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.

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 IDs.

See the documentation provided by your HSM vendor for information about installing, initializing, testing and troubleshooting the HSM.

Native PKCS#11 mode will only work with an HSM capable of carrying out every cryptographic operation BIND 9 may need. The HSM's provider library must have a complete implementation of the PKCS#11 API, so that all these functions are accessible. As of this writing, only the Thales nShield HSM and SoftHSMv2 can be used in this fashion. For other HSMs, including the AEP Keyper, Sun SCA 6000 and older versions of SoftHSM, use OpenSSL-based PKCS#11. (Note: Eventually, when more HSMs become capable of supporting native PKCS#11, it is expected that OpenSSL-based PKCS#11 will be deprecated.)

To build BIND with native PKCS#11, configure as follows:

$ cd bind9
$ ./configure --enable-native-pkcs11 \
    --with-pkcs11=provider-library-path
    

This will cause all BIND tools, including named and the dnssec-* and pkcs11-* tools, to use the PKCS#11 provider library specified in provider-library-path for cryptography. (The provider library path can be overridden using the -E in named and the dnssec-* tools, or the -m in the pkcs11-* tools.)

$  cd SoftHSMv2 
$  configure --with-crypto-backend=openssl --prefix=/opt/pkcs11/usr --enable-gost 
$  make 
$  make install 
$  /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label softhsmv2 
      

OpenSSL-based PKCS#11 mode uses a modified version of the OpenSSL library; stock OpenSSL does not fully support PKCS#11. ISC provides a patch to OpenSSL to correct this. This patch is based on work originally done by the OpenSolaris project; it has been modified by ISC to provide new features such as PIN management and key-by-reference.

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:

The modified OpenSSL code is included in the BIND 9 release, in the form of a context diff against the latest versions of OpenSSL. OpenSSL 0.9.8, 1.0.0, 1.0.1 and 1.0.2 are 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 through 1.0.2.

Before building BIND 9 with PKCS#11 support, it will be necessary to build OpenSSL with the patch in place, and configure it with the path to your HSM's PKCS#11 provider library.

$ wget http://www.openssl.org/source/openssl-0.9.8zc.tar.gz
  

$ tar zxf openssl-0.9.8zc.tar.gz

$ patch -p1 -d openssl-0.9.8zc \
	      < bind9/bin/pkcs11/openssl-0.9.8zc-patch

$ cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so

$ cd openssl-0.9.8zc
$ ./Configure linux-generic32 -m32 -pthread \
	    --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
	    --pk11-flavor=sign-only \
	    --prefix=/opt/pkcs11/usr

$ cd openssl-0.9.8zc
$ ./Configure solaris64-x86_64-cc \
	    --pk11-libname=/usr/lib/64/libpkcs11.so \
	    --pk11-flavor=crypto-accelerator \
	    --prefix=/opt/pkcs11/usr

$  cd softhsm-1.3.7 
$  configure --prefix=/opt/pkcs11/usr 
$  make 
$  make install 
$  export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf 
$  echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF 
$  /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm 

$ cd openssl-0.9.8zc
$ ./Configure linux-x86_64 -pthread \
	    --pk11-libname=/opt/pkcs11/usr/lib/libsofthsm.so \
	    --pk11-flavor=sign-only \
	    --prefix=/opt/pkcs11/usr

Once you have built OpenSSL, run "apps/openssl engine pkcs11" to confirm that PKCS#11 support was compiled in correctly. The output should be one of the following lines, depending on the flavor selected:

	(pkcs11) PKCS #11 engine support (sign only)

Or:

	(pkcs11) PKCS #11 engine support (crypto accelerator)

Next, run "apps/openssl engine pkcs11 -t". This will attempt to initialize the PKCS#11 engine. If it is able to do so successfully, it will report “[ available ]”.

If the output is correct, run "make install" which will install the modified OpenSSL suite to /opt/pkcs11/usr.

$ cd ../bind9
$ ./configure CC="gcc -m32" --enable-threads \
	   --with-openssl=/opt/pkcs11/usr \
	   --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so

$ cd ../bind9
$ ./configure CC="cc -xarch=amd64" --enable-threads \
	    --with-openssl=/opt/pkcs11/usr \
	    --with-pkcs11=/usr/lib/64/libpkcs11.so

$ cd ../bind9
$ ./configure --enable-threads \
	   --with-openssl=/opt/pkcs11/usr \
	   --with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so

After configuring, run "make", "make test" and "make install".

(Note: If "make test" fails in the "pkcs11" system test, you may have forgotten to set the SOFTHSM_CONF environment variable.)

BIND 9 includes a minimal set of tools to operate the HSM, including pkcs11-keygen to generate a new key pair within the HSM, pkcs11-list to list objects currently available, pkcs11-destroy to remove objects, and pkcs11-tokens to list available tokens.

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.)

For OpenSSL-based PKCS#11, we must first set up the runtime environment so the OpenSSL and PKCS#11 libraries can be loaded:

$ export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}

This causes named and other binaries to load the OpenSSL library from /opt/pkcs11/usr/lib rather than from the default location. This step is not necessary when using native PKCS#11.

Some HSMs require other environment variables to be set. For example, when operating an AEP Keyper, it is necessary to specify the location of the "machine" file, which stores information about the Keyper for use by the provider library. If the machine file is in /opt/Keyper/PKCS11Provider/machine, use:

$ export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider

Such environment variables must be set whenever running any tool that uses the HSM, including pkcs11-keygen, pkcs11-list, pkcs11-destroy, dnssec-keyfromlabel, dnssec-signzone, dnssec-keygen, and named.

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":

$ pkcs11-keygen -b 2048 -l sample-ksk

To confirm that the key exists:

$ pkcs11-list
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]

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":

$ dnssec-keyfromlabel -l sample-ksk -f KSK example.net

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. Signing with the private key takes place inside the HSM.

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:

(Note: When using OpenSSL-based PKCS#11 the label is an arbitrary string which identifies the key. With native PKCS#11, the label is a PKCS#11 URI string which may include other details about the key and the HSM, including its PIN. See dnssec-keyfromlabel(8) for details.)

$ pkcs11-keygen -b 1024 -l sample-zsk
$ dnssec-keyfromlabel -l sample-zsk example.net

Alternatively, you may prefer to generate a conventional on-disk key, using dnssec-keygen:

$ dnssec-keygen example.net

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. (Note: When using native PKCS#11, there is no speed advantage to using on-disk keys, as cryptographic operations will be done by the HSM regardless.)

Now you can sign the zone. (Note: If not using the -S option to dnssec-signzone, it will be necessary to add the contents of both K*.key files to the zone master file before signing it.)

$ dnssec-signzone -S example.net
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

When using OpenSSL-based PKCS#11, the "engine" to be used by OpenSSL can be specified in named and all of the BIND dnssec-* 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.

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:

$ dnssec-signzone -E '' -S example.net

This causes dnssec-signzone to run as if it were compiled without the --with-pkcs11 option.

When built with native PKCS#11 mode, the "engine" option has a different meaning: it specifies the path to the PKCS#11 provider library. This may be useful when testing a new provider library.

If you want named 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. In OpenSSL-based PKCS#11, this is accomplished by placing the PIN into the openssl.cnf file (in the above examples, /opt/pkcs11/usr/ssl/openssl.cnf).

The location of the openssl.cnf file can be overridden by setting the OPENSSL_CONF environment variable before running named.

Sample openssl.cnf:

	openssl_conf = openssl_def
	[ openssl_def ]
	engines = engine_section
	[ engine_section ]
	pkcs11 = pkcs11_section
	[ pkcs11_section ]
	PIN = <PLACE PIN HERE>

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.)

In native PKCS#11 mode, the PIN can be provided in a file specified as an attribute of the key's label. For example, if a key had the label pkcs11:object=local-zsk;pin-source=/etc/hsmpin, then the PIN would be read from the file /etc/hsmpin.

A DLZ database is configured with a dlz statement in named.conf:

    dlz example {
	database "dlopen driver.so args";
	search yes;
    };
    

This specifies a DLZ module to search when answering queries; the module is implemented in driver.so and is loaded at runtime by the dlopen DLZ driver. Multiple dlz statements can be specified; when answering a query, all DLZ modules with search set to yes will be queried to find out if they contain an answer for the query name; the best available answer will be returned to the client.

The search option in the above example can be omitted, because yes is the default value.

If search is set to no, then this DLZ module is not searched for the best match when a query is received. Instead, zones in this DLZ must be separately specified in a zone statement. This allows you to configure a zone normally using standard zone option semantics, but specify a different database back-end for storage of the zone's data. For example, to implement NXDOMAIN redirection using a DLZ module for back-end storage of redirection rules:

    dlz other {
	database "dlopen driver.so args";
	search no;
    };

    zone "." {
	type redirect;
	dlz other;
    };
    

For guidance in implementation of DLZ modules, the directory contrib/dlz/example contains a basic dynamically-linkable DLZ module--i.e., one which can be loaded at runtime by the "dlopen" DLZ driver. The example sets up a single zone, whose name is passed to the module as an argument in the dlz statement:

    dlz other {
	database "dlopen driver.so example.nil";
    };
    

In the above example, the module is configured to create a zone "example.nil", which can answer queries and AXFR requests, and accept DDNS updates. At runtime, prior to any updates, the zone contains an SOA, NS, and a single A record at the apex:

 example.nil.  3600    IN      SOA     example.nil. hostmaster.example.nil. (
					       123 900 600 86400 3600
				       )
 example.nil.  3600    IN      NS      example.nil.
 example.nil.  1800    IN      A       10.53.0.1
    

The sample driver is capable of retrieving information about the querying client, and altering its response on the basis of this information. To demonstrate this feature, the example driver responds to queries for "source-addr.zonename>/TXT" with the source address of the query. Note, however, that this record will *not* be included in AXFR or ANY responses. Normally, this feature would be used to alter responses in some other fashion, e.g., by providing different address records for a particular name depending on the network from which the query arrived.

Documentation of the DLZ module API can be found in contrib/dlz/example/README. This directory also contains the header file dlz_minimal.h, which defines the API and should be included by any dynamically-linkable DLZ module.

A DynDB database is configured with a dyndb statement in named.conf:

    dyndb example "driver.so" {
        parameters
    };
    

The file driver.so is a DynDB module which implements the full DNS database API. Multiple dyndb statements can be specified, to load different drivers or multiple instances of the same driver. Zones provided by a DynDB module are added to the view's zone table, and are treated as normal authoritative zones when BIND is responding to queries. Zone configuration is handled internally by the DynDB module.

The parameters are passed as an opaque string to the DynDB module's initialization routine. Configuration syntax will differ depending on the driver.

For guidance in implementation of DynDB modules, the directory bin/tests/system/dyndb/driver. contains a basic DynDB module. The example sets up two zones, whose names are passed to the module as arguments in the dyndb statement:

    dyndb sample "sample.so" { example.nil. arpa. };
    

In the above example, the module is configured to create a zone "example.nil", which can answer queries and AXFR requests, and accept DDNS updates. At runtime, prior to any updates, the zone contains an SOA, NS, and a single A record at the apex:

 example.nil.  86400    IN      SOA     example.nil. example.nil. (
                                               0 28800 7200 604800 86400
                                       )
 example.nil.  86400    IN      NS      example.nil.
 example.nil.  86400    IN      A       127.0.0.1
    

When the zone is updated dynamically, the DynDB module will determine whether the updated RR is an address (i.e., type A or AAAA) and if so, it will automatically update the corresponding PTR record in a reverse zone. (Updates are not stored permanently; all updates are lost when the server is restarted.)

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,

$ORIGIN example.com.
host            3600    IN      AAAA    2001:db8::1

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 ::ffff:192.168.42.1 as the address.

When looking up an address in nibble format, the address components are simply reversed, just as in IPv4, and ip6.arpa. is appended to the resulting name. For example, the following would provide reverse name lookup for a host with address 2001:db8::1.

$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. )