Commit 0b24b2d3 authored by Evan Hunt's avatar Evan Hunt

2848. [doc] Moved README.dnssec, README.libdns, README.pkcs11 and

			README.rfc5011 into the ARM. [RT #20899]
parent c0604017
2848. [doc] Moved README.dnssec, README.libdns, README.pkcs11 and
README.rfc5011 into the ARM. [RT #20899]
2847. [cleanup] Corrected usage message in dnssec-settime. [RT #20921]
2846. [bug] EOF on unix domain sockets was not being handled
DNSSEC and Dynamic Zones
As of BIND 9.7.0 it is possible to change a dynamic zone from
insecure to secure and back again. A secure zone can use either
NSEC or NSEC3 chains.
Converting from insecure to secure
Changing a zone from insecure to secure can be done in two ways:
using a dynamic DNS update, or the "auto-dnssec" zone option.
For either method, you need to configure named so that it can see
the K* 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 dnssec-keygen. You can do this by placing them in
the key-directory, as specified in named.conf:
zone {
type master;
update-policy local;
file "dynamic/";
key-directory "dynamic/";
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.
Dynamic DNS update method
To insert the keys via dynamic update:
% nsupdate
> ttl 3600
> update add DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
> update add DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
> send
While the update request will complete almost immediately, the zone
will not be completely signed until named 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.
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.
% nsupdate
> ttl 3600
> update add DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
> update add DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
> update add NSEC3PARAM 1 1 100 1234567890
> send
Again, this update request will complete almost immediately; however,
the record won't show up until named 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.
While the initial signing and NSEC/NSEC3 chain generation is happening,
other updates are possible as well.
Fully automatic zone signing
To enable automatic signing, add the "auto-dnssec" option to the zone
statement in named.conf. "auto-dnssec" has two possible arguments:
"allow" or "maintain".
With "auto-dnssec allow", named 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 "rndc sign <zonename>"
"auto-dnssec maintain" includes the above functionality, but will also
automatically adjust the zone's DNSKEY records on schedule according to the
keys' timing metadata (see the man pages for dnssec-keygen and
dnssec-settime for more information). If keys are present in the key
directory the first time the zone is loaded, it will be signed
immediately, without waiting for an "rndc sign" command. (This
command can still be used for unscheduled key changes, however.)
Using the "auto-dnssec" option requires the zone to be configured to
allow dynamic updates, by adding an "allow-update" or "update-policy"
statement to the zone configuration. If this has not been done, the
configuration will fail.
Private-type records
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).
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.
algorithm (octet 1)
key id in network order (octet 2 and 3)
removal flag (octet 4)
complete flag (octet 5)
Only records flagged as "complete" can be removed via dynamic update.
Attempts to remove other private type records will be silently ignored.
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.
DNSKEY rollovers via UPDATE
It is possible to perform key rollovers via dynamic update. You need
to add the K* files for the new keys so that named can find them. You
can then add the new DNSKEY RRs via dynamic update. Named 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.
If this is for a KSK you need to inform the parent and any trust
anchor repositories of the new KSK.
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.
The old DNSKEY can be removed via UPDATE. Take care to specify
the correct key. Named will clean out any signatures generated by
the old key after the update completes.
NSEC3PARAM rollovers via UPDATE
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.
Converting from NSEC to NSEC3
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.
Converting from NSEC3 to NSEC
To do this, remove all NSEC3PARAM records with a zero flag field. The
NSEC chain will be generated before the NSEC3 chain is removed.
Converting from secure to insecure
To do this, remove all the DNSKEY records. Any NSEC or NSEC3 chains
will be removed as well, along with associated NSEC3PARAM records.
This will take place after the update request completes. This
requires the "dnssec-secure-to-insecure" option to be set to "yes"
in named.conf.
Periodic re-signing
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.
Named only supports creating new NSEC3 chains where all the NSEC3
records in the zone have the same OPTOUT state. Named supports
UPDATES to zones where the NSEC3 records in the chain have mixed
OPTOUT state. Named 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.
BIND-9 DNS Library Support
This version of BIND9 "exports" its internal libraries so that they
can be used by third-party applications more easily (we call them
"export" libraries in this document). In addition to all major
DNS-related APIs BIND9 is currently using, the export libraries
provide the following features:
- The newly created "DNS client" module. This is a higher level API
that provides an interface to name resolution, single DNS
transaction with a particular server, and dynamic update. Regarding
name resolution, it supports advanced features such as DNSSEC
validation and caching. This module supports both synchronous and
asynchronous mode.
- The new "IRS" (Information Retrieval System) library. It provides
an interface to parse the traditional resolv.conf file and more
advanced, DNS-specific configuration file for the rest of this
package (see the description for the dns.conf file below).
- As part of the IRS library, newly implemented standard address-name
mapping functions, getaddrinfo() and getnameinfo(), are provided.
They use the DNSSEC-aware validating resolver backend, and could use
other advanced features of the BIND9 libraries such as caching. The
getaddrinfo() function resolves both A and AAAA RRs concurrently
(when the address family is unspecified).
- An experimental framework to support other event libraries than
BIND9's internal event task system.
* Prerequisite
GNU make is required to build the export libraries (other part of
BIND9 can still be built with other types of make). In the reminder
of this document, "make" means GNU make. Note that in some platforms
you may need to invoke a different command name than "make"
(e.g. "gmake") to indicate it's GNU make.
* Compilation
1. ./configure --enable-exportlib [other flags]
2. make
This will create (in addition to usual BIND9 programs) and a separate
set of libraries under the lib/export directory. For example,
lib/export/dns/libdns.a is the archive file of the export version of
the BIND9 DNS library.
Sample application programs using the libraries will also be built
under the lib/export/samples directory (see below).
* Installation
1. cd lib/export
2. make install (root privilege is normally required)
(make install at the top directory will do the same)
This will install library object files under the directory specified
by the --with-export-libdir configure option (default:
EPREFIX/lib/bind9), and header files under the directory specified by
the --with-export-includedir configure option (default:
To see how to build your own application after the installation, see
* Known Defects/Restrictions
- Currently, win32 is not supported for the export library. (Normal
BIND9 application can be built as before).
- The "fixed" RRset order is not (currently) supported in the export
library. If you want to use "fixed" RRset order for, e.g. named
while still building the export library even without the fixed
order support, build them separately:
% ./configure --enable-fixed-rrset [other flags, but not --enable-exportlib]
% make (this doesn't have to be make)
% ./configure --enable-exportlib [other flags, but not --enable-fixed-rrset]
% cd lib/export
% make
- The client module and the IRS library currently do not support
DNSSEC validation using DLV (the underlying modules can handle it,
but there is no tunable interface to enable the feature).
- RFC5011 is not supported in the validating stub resolver of the
export library. In fact, it is not clear whether it should: trust
anchors would be a system-wide configuration which would be managed
by an administrator, while the stub resolver will be used by
ordinary applications run by a normal user.
- Not all common /etc/resolv.conf options are supported in the IRS library.
The only available options in this version are "debug" and "ndots".
* The dns.conf File
The IRS library supports an "advanced" configuration file related to
the DNS library for configuration parameters that would be beyond the
capability of the resolv.conf file. Specifically, it is intended to
provide DNSSEC related configuration parameters.
By default the path to this configuration file is /etc/dns.conf.
This module is very experimental and the configuration syntax or
library interfaces may change in future versions. Currently, only the
'trusted-keys' statement is supported, whose syntax is the same as the
same name of statement for named.conf.
* Sample Applications
Some sample application programs using this API are provided for
reference. The following is a brief description of these
- sample: a simple stub resolver utility.
It sends a query of a given name (of a given optional RR type)
to a specified recursive server, and prints the result as a list of
RRs. It can also act as a validating stub resolver if a trust
anchor is given via a set of command line options.
Usage: sample [options] server_address hostname
Options and Arguments:
-t RRtype
specify the RR type of the query. The default is the A RR.
[-a algorithm] [-e] -k keyname -K keystring
specify a command-line DNS key to validate the answer. For
example, to specify the following DNSKEY of 3600 IN DNSKEY 257 3 5 xxx
specify the options as follows:
-e -k -K "xxx"
-e means that this key is a zone's "key signing key" (as known
as "secure Entry point").
when -a is omitted rsasha1 will be used by default.
-s domain:alt_server_address
specify a separate recursive server address for the specific
"domain". Example: -s
an IP(v4/v6) address of the recursive server to which queries
are sent.
the domain name for the query
- sample-async: a simple stub resolver, working asynchronously.
Similar to "sample", but accepts a list of (query) domain names as a
separate file and resolves the names asynchronously.
Usage: sample-async [-s server_address] [-t RR_type] input_file
Options and Arguments:
-s server_address
an IPv4 address of the recursive server to which queries are
sent. (IPv6 addresses are not supported in this implementation)
-t RR_type
specify the RR type of the queries. The default is the A RR.
a list of domain names to be resolved. each line consists of a
single domain name. Example:
- sample-request: a simple DNS transaction client.
It sends a query to a specified server, and prints the response with
minimal processing. It doesn't act as a "stub resolver": it stops
the processing once it gets any response from the server, whether
it's a referral or an alias (CNAME or DNAME) that would require
further queries to get the ultimate answer. In other words, this
utility acts as a very simplified dig.
Usage: sample-request [-t RRtype] server_address hostname
Options and Arguments:
-t RRtype
specify the RR type of the queries. The default is the A RR.
an IP(v4/v6) address of the recursive server to which the query is
the domain name for the query
- sample-gai: getaddrinfo() and getnameinfo() test code.
This is a test program to check getaddrinfo() and getnameinfo()
behavior. It takes a host name as an argument, calls getaddrinfo()
with the given host name, and calls getnameinfo() with the resulting
IP addresses returned by getaddrinfo(). If the dns.conf file exists
and defines a trust anchor, the underlying resolver will act as a
validating resolver, and getaddrinfo()/getnameinfo() will fail with
an EAI_INSECUREDATA error when DNSSEC validation fails.
Usage: sample-gai hostname
- sample-update: a simple dynamic update client program
It accepts a single update command as a command-line argument, sends
an update request message to the authoritative server, and shows the
response from the server. In other words, this is a simplified
Usage: sample-update [options] (add|delete) "update data"
Options and Arguments:
-a auth_server
An IP address of the authoritative server that has authority
for the zone containing the update name. This should normally
be the primary authoritative server that accepts dynamic
updates. It can also be a secondary server that is configured
to forward update requests to the primary server.
-k keyfile
A TSIG key file to secure the update transaction. The keyfile
format is the same as that for the nsupdate utility.
-p prerequisite
A prerequisite for the update (only one prerequisite can be
specified). The prerequisite format is the same as that is
accepted by the nsupdate utility.
-r recursive_server
An IP address of a recursive server that this utility will
use. A recursive server may be necessary to identify the
authoritative server address to which the update request is
-z zonename
The domain name of the zone that contains
Specify the type of update operation. Either "add" or "delete"
must be specified.
"update data"
Specify the data to be updated. A typical example of the data
would look like "name TTL RRtype RDATA".
Note: in practice, either -a or -r must be specified. Others can
be optional; the underlying library routine tries to identify the
appropriate server and the zone name for the update.
Examples: assuming the primary authoritative server of the zone has an IPv6 address 2001:db8::1234,
+ sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add " 30 IN A"
adds an A RR for using the given key.
+ sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete " 30 IN A"
removes all A RRs for using the given key.
+ sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete ""
removes all RRs for using the given key.
- nsprobe: domain/name server checker in terms of RFC4074.
It checks a set of domains to see the name servers of the domains
behave correctly in terms of RFC4074. This is included in the set
of sample programs to show how the export library can be used in a
DNS-related application.
Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file]
run in the "debug" mode. with this option nsprobe will dump
every RRs it receives.
increase verbosity of other normal log messages. This can be
specified multiple times
-c cache_address
specify an IP address of a recursive (caching) name server.
nsprobe uses this server to get the NS RRset of each domain and
the A and/or AAAA RRsets for the name servers. The default
value is
a file name containing a list of domain (zone) names to be
probed. when omitted the standard input will be used. Each
line of the input file specifies a single domain name such as
"". In general this domain name must be the apex
name of some DNS zone (unlike normal "host names" such as
""). nsprobe first identifies the NS RRsets for
the given domain name, and sends A and AAAA queries to these
servers for some "widely used" names under the zone;
specifically, adding "www" and "ftp" to the zone name.
* Library References
As of this writing, there is no formal "manual" of the libraries,
except this document, header files (some of them provide pretty
detailed explanations), and sample application programs.
; $Id: README.libdns,v 1.3 2009/09/15 19:12:03 jinmei Exp $
BIND 9 PKCS #11 (Cryptoki) support
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.
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.
See the HSM vendor documentation for information about installing,
initializing, testing and troubleshooting the HSM.
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.
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 and is specific to the HSM to be
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:
- 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.
- 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.
The modified OpenSSL code is included in the BIND 9.7.0b1 release, in the
form of a context diff against OpenSSL 0.9.8l. 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.
Obtain OpenSSL 0.9.8l:
Extract the tarball:
tar zxf openssl-0.9.8l.tar.gz
Apply the patch from the BIND 9 release:
patch -p1 -d openssl-0.9.8l \
< bind-9.7.0b1/bin/pkcs11/openssl-0.9.8l-patch
(Note that the patch file may not be compatible with the "patch"
utility on all operating systems. You may need to install GNU patch.)
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.
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.
The Keyper-specific PKCS #11 provider library is delivered with the
Keyper software. In this example, we place it /opt/pkcs11/usr/lib:
cp /opt/pkcs11/usr/lib/
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.
Finally, the Keyper library requires threads, so we must specify -pthread.
cd openssl-0.9.8l
./Configure linux-generic32 -m32 -pthread \
--pk11-libname=/opt/pkcs11/usr/lib/ \
--pk11-flavor=sign-only \
After configuring, run "make" and "make test". If "make test" fails
with "pthread_atfork() not found", you forgot to add the -pthread
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'.
In this example, we are building on Solaris x86 on an AMD64 system.
cd openssl-0.9.8l
./Configure solaris64-x86_64-cc \
--pk11-libname=/usr/lib/64/ \
--pk11-flavor=crypto-accelerator \
(For a 32-bit build, use "solaris-x86-cc" and /usr/lib/
After configuring, run "make" and "make test".
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)
(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".
When building BIND 9, the location of the custom-built OpenSSL
library must be specified via configure.
To link with the PKCS #11 provider, threads must be enabled in the
BIND 9 build.
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.
cd ../bind-9.7.0b1
./configure CC="gcc -m32" --enable-threads \
--with-openssl=/opt/pkcs11/usr \
To link with the PKCS #11 provider, threads must be enabled in the
BIND 9 build.