+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
+++ /dev/null
-
- 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 example.net {
- type master;
- update-policy local;
- file "dynamic/example.net/example.net";
- key-directory "dynamic/example.net";
- };
-
-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 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
-
-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 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
-
-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>"
-command.
-
-"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.
-
- 0x01 OPTOUT
- 0x80 CREATE
- 0x40 REMOVE
- 0x20 NONSEC
-
- 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.
-
- NSEC3 and OPTOUT
-
-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.
+++ /dev/null
-
- 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:
-PREFIX/include/bind9).
-
-To see how to build your own application after the installation, see
-lib/export/samples/Makefile-postinstall.in
-
-* 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
-applications.
-
-- 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 example.com:
- example.com. 3600 IN DNSKEY 257 3 5 xxx
- specify the options as follows:
- -e -k example.com -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 example.com:2001:db8::1234
- server_address
- an IP(v4/v6) address of the recursive server to which queries
- are sent.
- hostname
- 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.
- input_file
- a list of domain names to be resolved. each line consists of a
- single domain name. Example:
- www.example.com
- mx.examle.net
- ns.xxx.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.
- server_address
- an IP(v4/v6) address of the recursive server to which the query is
- sent.
- hostname
- 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
- nsupdate.
-
- 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
- sent.
- -z zonename
- The domain name of the zone that contains
- (add|delete)
- 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
- dynamic.example.com zone has an IPv6 address 2001:db8::1234,
- + sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add "foo.dynamic.example.com 30 IN A 192.168.2.1"
- adds an A RR for foo.dynamic.example.com using the given key.
- + sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com 30 IN A"
- removes all A RRs for foo.dynamic.example.com using the given key.
- + sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"
- removes all RRs for foo.dynamic.example.com 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]
- Options
- -d
- run in the "debug" mode. with this option nsprobe will dump
- every RRs it receives.
- -v
- 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 127.0.0.1.
- input_file
- 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
- "example.com". In general this domain name must be the apex
- name of some DNS zone (unlike normal "host names" such as
- "www.example.com"). 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 $
+++ /dev/null
-
- BIND 9 PKCS #11 (Cryptoki) support
-
-INTRODUCTION
-
-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.
-
-PREREQUISITES
-
-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
-controlled.
-
-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:
-
- wget http://www.openssl.org/source/openssl-0.9.8l.tar.gz
-
-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.
-
- EXAMPLE 1--BUILDING OPENSSL FOR THE AEP KEYPER ON LINUX:
-
- 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 pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so
-
- 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/libpkcs11.so \
- --pk11-flavor=sign-only \
- --prefix=/opt/pkcs11/usr
-
- After configuring, run "make" and "make test". If "make test" fails
- with "pthread_atfork() not found", you forgot to add the -pthread
- above.
-
- EXAMPLE 2--BUILDING OPENSSL FOR THE SCA 6000 ON SOLARIS:
-
- 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/libpkcs11.so \
- --pk11-flavor=crypto-accelerator \
- --prefix=/opt/pkcs11/usr
-
- (For a 32-bit build, use "solaris-x86-cc" and /usr/lib/libpkcs11.so.)
-
- 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)
-
-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".
-
-BUILDING BIND 9
-
-When building BIND 9, the location of the custom-built OpenSSL
-library must be specified via configure.
-
- EXAMPLE 3--CONFIGURING BIND 9 FOR LINUX
-
- 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 \
- --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so
-
- EXAMPLE 4--CONFIGURING BIND 9 FOR SOLARIS
-
- To link with the PKCS #11 provider, threads must be enabled in the
- BIND 9 build.
-
- cd ../bind-9.7.0b1
- ./configure CC="cc -xarch=amd64" --enable-threads \
- --with-openssl=/opt/pkcs11/usr \
- --with-pkcs11=/usr/lib/64/libpkcs11.so
-
- (For a 32-bit build, omit CC="cc -xarch=amd64".)
-
-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).
-
-After configuring, run "make", "make test" and "make install".
-
-PKCS #11 TOOLS
-
-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, and "pkcs11-destroy" to remove
-objects.
-
-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.)
-
-USING THE HSM
-
-First, we must 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}
-
-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
-/opt/Keyper/PKCS11Provider/machine, use:
-
- export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider
-
-These 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 (which will use
-the HSM for random number generation), 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.
-The HSM handles signing with the private key.
-
-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:
-
- 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.
-
-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
-
-SPECIFYING THE ENGINE ON THE COMMAND LINE
-
-The OpenSSL engine can be specified in named and all of the 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.
-
-RUNNING NAMED WITH AUTOMATIC ZONE RE-SIGNING
-
-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. This can be 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.)
-
-PLEASE NOTE: 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 BIND 9 in this way.
+++ /dev/null
-
- BIND 9 RFC 5011 support
-
-BIND 9.7.0 introduces support for RFC 5011, dynamic trust anchor
-management. Using this feature allows named to keep track of changes to
-critical DNSSEC keys without any need for the operator to make changes to
-configuration files.
-
-VALIDATING RESOLVER
--------------------
-
-To configure a validating resolver to use RFC5011 to maintain a trust
-anchor, configure the trust anchor using a "managed-keys" statement.
-Information about this can be found in the ARM, in the section titled
-"managed-keys Statement Definition".
-
-AUTHORITATIVE SERVER
---------------------
-
-To set up an authoritative zone for RFC5011 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.
-
-Any validating resolver which is configured to use the active KSK as an
-RFC5011-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 ID's exactly 128 apart, and one is revoked, then the
-two key ID's 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 ID's.
- PERFORMANCE OF THIS SOFTWARE.
-->
-<!-- File: $Id: Bv9ARM-book.xml,v 1.454 2010/01/23 00:33:21 marka Exp $ -->
+<!-- File: $Id: Bv9ARM-book.xml,v 1.455 2010/02/03 01:31:48 each Exp $ -->
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<title>BIND 9 Administrator Reference Manual</title>
</sect2>
</sect1>
+
+ <xi:include href="dnssec.xml"/>
+
+ <xi:include href="managed-keys.xml"/>
+
+ <xi:include href="pkcs11.xml"/>
+
<sect1>
<title>IPv6 Support in <acronym>BIND</acronym> 9</title>
</sect2>
- <sect2>
+ <sect2 id="trusted-keys">
<title><command>trusted-keys</command> Statement Grammar</title>
<programlisting><command>trusted-keys</command> {
</programlisting>
</sect2>
- <sect2>
+ <sect2 id="managed-keys">
<title><command>managed-keys</command> Statement Definition
and Usage</title>
<para>
</bibliography>
</sect2>
</sect1>
+
+ <xi:include href="libdns.xml"/>
+
</appendix>
+
<reference id="Bv9ARM.ch10">
<title>Manual pages</title>
<xi:include href="../../bin/dig/dig.docbook"/>
--- /dev/null
+<?xml version="1.0" encoding="utf-8"?>
+<sect1 id="dnssec.dynamic.zones">
+ <title>DNSSEC, Dynamic Zones, and Automatic Signing</title>
+ <para>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.</para>
+ <sect2>
+ <title>Converting from insecure to secure</title>
+ </sect2>
+ <para>Changing a zone from insecure to secure can be done in two
+ ways: using a dynamic DNS update, or the
+ <command>auto-dnssec</command> zone option.</para>
+ <para>For either method, you need to configure
+ <command>named</command> so that it can see the
+ <filename>K*</filename> 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
+ <command>dnssec-keygen</command>. You can do this by placing them
+ in the key-directory, as specified in
+ <filename>named.conf</filename>:</para>
+ <programlisting>
+ zone example.net {
+ type master;
+ update-policy local;
+ file "dynamic/example.net/example.net";
+ key-directory "dynamic/example.net";
+ };
+</programlisting>
+ <para>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.</para>
+ <sect2>
+ <title>Dynamic DNS update method</title>
+ </sect2>
+ <para>To insert the keys via dynamic update:</para>
+ <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
+</screen>
+ <para>While the update request will complete almost immediately,
+ the zone will not be completely signed until
+ <command>named</command> 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.</para>
+ <para>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.</para>
+ <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
+</screen>
+ <para>Again, this update request will complete almost
+ immediately; however, the record won't show up until
+ <command>named</command> 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.</para>
+ <para>While the initial signing and NSEC/NSEC3 chain generation
+ is happening, other updates are possible as well.</para>
+ <sect2>
+ <title>Fully automatic zone signing</title>
+ </sect2>
+ <para>To enable automatic signing, add the
+ <command>auto-dnssec</command> option to the zone statement in
+ <filename>named.conf</filename>.
+ <command>auto-dnssec</command> has two possible arguments:
+ <constant>allow</constant> or
+ <constant>maintain</constant>.</para>
+ <para>With
+ <command>auto-dnssec allow</command>,
+ <command>named</command> 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
+ <command>rndc sign <zonename></command> command.</para>
+ <para>
+ <!-- TODO: this is repeated in the ARM -->
+ <command>auto-dnssec maintain</command> includes the above
+ functionality, but will also automatically adjust the zone's
+ DNSKEY records on schedule according to the keys' timing metadata.
+ (See <xref linkend="man.dnssec-keygen"/> and
+ <xref linkend="man.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
+ <command>rndc sign</command> command. (This command can still be
+ used for unscheduled key changes, however.)</para>
+ <para>Using the
+ <command>auto-dnssec</command> option requires the zone to be
+ configured to allow dynamic updates, by adding an
+ <command>allow-update</command> or
+ <command>update-policy</command> statement to the zone
+ configuration. If this has not been done, the configuration will
+ fail.</para>
+ <sect2>
+ <title>Private-type records</title>
+ </sect2>
+ <para>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).</para>
+ <para>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.</para>
+ <para>
+ <literallayout>
+<!-- TODO: how to format this? -->
+ algorithm (octet 1)
+ key id in network order (octet 2 and 3)
+ removal flag (octet 4)
+ complete flag (octet 5)
+</literallayout>
+ </para>
+ <para>Only records flagged as "complete" can be removed via
+ dynamic update. Attempts to remove other private type records
+ will be silently ignored.</para>
+ <para>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.</para>
+ <para>
+ <literallayout>
+<!-- TODO: how to format this? -->
+ 0x01 OPTOUT
+ 0x80 CREATE
+ 0x40 REMOVE
+ 0x20 NONSEC
+</literallayout>
+ </para>
+ <sect2>
+ <title>DNSKEY rollovers via UPDATE</title>
+ </sect2>
+ <para>It is possible to perform key rollovers via dynamic update.
+ You need to add the
+ <filename>K*</filename> files for the new keys so that
+ <command>named</command> can find them. You can then add the new
+ DNSKEY RRs via dynamic update.
+ <command>named</command> 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.</para>
+ <para>If this is for a KSK you need to inform the parent and any
+ trust anchor repositories of the new KSK.</para>
+ <para>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.</para>
+ <para>The old DNSKEY can be removed via UPDATE. Take care to
+ specify the correct key.
+ <command>named</command> will clean out any signatures generated
+ by the old key after the update completes.</para>
+ <sect2>
+ <title>NSEC3PARAM rollovers via UPDATE</title>
+ </sect2>
+ <para>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.</para>
+ <sect2>
+ <title>Converting from NSEC to NSEC3</title>
+ </sect2>
+ <para>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.</para>
+ <sect2>
+ <title>Converting from NSEC3 to NSEC</title>
+ </sect2>
+ <para>To do this, use <command>nsupdate</command> to
+ remove all NSEC3PARAM records with a zero flag
+ field. The NSEC chain will be generated before the NSEC3 chain is
+ removed.</para>
+ <sect2>
+ <title>Converting from secure to insecure</title>
+ </sect2>
+ <para>To convert a signed zone to unsigned using dynamic DNS,
+ delete all the DNSKEY records from the zone apex using
+ <command>nsupdate</command>. All signatures, NSEC or NSEC3 chains,
+ and associated NSEC3PARAM records will be removed automatically.
+ This will take place after the update request completes.</para>
+ <para> This requires the
+ <command>dnssec-secure-to-insecure</command> option to be set to
+ <userinput>yes</userinput> in
+ <filename>named.conf</filename>.</para>
+ <para>In addition, if the <command>auto-dnssec maintain</command>
+ zone statement is used, it should be removed or changed to
+ <command>allow</command> instead (or it will re-sign).
+ </para>
+ <sect2>
+ <title>Periodic re-signing</title>
+ </sect2>
+ <para>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.</para>
+ <sect2>
+ <title>NSEC3 and OPTOUT</title>
+ </sect2>
+ <para>
+ <command>named</command> only supports creating new NSEC3 chains
+ where all the NSEC3 records in the zone have the same OPTOUT
+ state.
+ <command>named</command> supports UPDATES to zones where the NSEC3
+ records in the chain have mixed OPTOUT state.
+ <command>named</command> 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.</para>
+</sect1>
--- /dev/null
+<?xml version="1.0" encoding="utf-8"?>
+<sect1 id="bind9.library">
+ <title>BIND 9 DNS Library Support</title>
+ <para>This version of BIND 9 "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 BIND 9 is currently using, the export
+ libraries provide the following features:</para>
+ <itemizedlist>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ <listitem>
+ <para>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).</para>
+ </listitem>
+ <listitem>
+ <para>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 BIND 9 libraries such as caching. The
+ getaddrinfo() function resolves both A and AAAA RRs
+ concurrently (when the address family is unspecified).</para>
+ </listitem>
+ <listitem>
+ <para>An experimental framework to support other event
+ libraries than BIND 9's internal event task system.</para>
+ </listitem>
+ </itemizedlist>
+ <sect2>
+ <title>Prerequisite</title>
+ <para>GNU make is required to build the export libraries (other
+ part of BIND 9 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.</para>
+ </sect2>
+ <sect2>
+ <title>Compilation</title>
+ <screen>
+$ <userinput>./configure --enable-exportlib <replaceable>[other flags]</replaceable></userinput>
+$ <userinput>make</userinput>
+</screen>
+ <para>
+ This will create (in addition to usual BIND 9 programs) and a
+ separate set of libraries under the lib/export directory. For
+ example, <filename>lib/export/dns/libdns.a</filename> is the archive file of the
+ export version of the BIND 9 DNS library. Sample application
+ programs using the libraries will also be built under the
+ lib/export/samples directory (see below).</para>
+ </sect2>
+ <sect2>
+ <title>Installation</title>
+ <screen>
+$ <userinput>cd lib/export</userinput>
+$ <userinput>make install</userinput>
+</screen>
+ <para>
+ 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: PREFIX/include/bind9).
+ Root privilege is normally required.
+ "<command>make install</command>" at the top directory will do the
+ same.
+ </para>
+ <para>
+ To see how to build your own
+ application after the installation, see
+ <filename>lib/export/samples/Makefile-postinstall.in</filename>.</para>
+ </sect2>
+ <sect2>
+ <title>Known Defects/Restrictions</title>
+ <itemizedlist>
+ <listitem>
+<!-- TODO: what about AIX? -->
+ <para>Currently, win32 is not supported for the export
+ library. (Normal BIND 9 application can be built as
+ before).</para>
+ </listitem>
+ <listitem>
+ <para>The "fixed" RRset order is not (currently) supported in
+ the export library. If you want to use "fixed" RRset order
+ for, e.g. <command>named</command> while still building the
+ export library even without the fixed order support, build
+ them separately:
+ <screen>
+$ <userinput>./configure --enable-fixed-rrset <replaceable>[other flags, but not --enable-exportlib]</replaceable></userinput>
+$ <userinput>make</userinput>
+$ <userinput>./configure --enable-exportlib <replaceable>[other flags, but not --enable-fixed-rrset]</replaceable></userinput>
+$ <userinput>cd lib/export</userinput>
+$ <userinput>make</userinput>
+</screen>
+ </para>
+ </listitem>
+ <listitem>
+ <para>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).</para>
+ </listitem>
+ <listitem>
+ <para>RFC 5011 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.</para>
+ </listitem>
+ <listitem>
+ <para>Not all common <filename>/etc/resolv.conf</filename>
+ options are supported
+ in the IRS library. The only available options in this
+ version are "debug" and "ndots".</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ <sect2>
+ <title>The dns.conf File</title>
+ <para>The IRS library supports an "advanced" configuration file
+ related to the DNS library for configuration parameters that
+ would be beyond the capability of the
+ <filename>resolv.conf</filename> file.
+ Specifically, it is intended to provide DNSSEC related
+ configuration parameters. By default the path to this
+ configuration file is <filename>/etc/dns.conf</filename>.
+ This module is very
+ experimental and the configuration syntax or library interfaces
+ may change in future versions. Currently, only the
+ <command>trusted-keys</command>
+ statement is supported, whose syntax is the same as the same name
+ of statement for <filename>named.conf</filename>. (See
+ <xref linkend="trusted-keys" /> for details.)</para>
+ </sect2>
+ <sect2>
+ <title>Sample Applications</title>
+ <para>Some sample application programs using this API are
+ provided for reference. The following is a brief description of
+ these applications.
+ </para>
+ <sect3>
+ <title>sample: a simple stub resolver utility</title>
+ <para>
+ 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.</para>
+ <para>
+ Usage: sample [options] server_address hostname
+ </para>
+ <para>
+ Options and Arguments:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ -t RRtype
+ </term>
+ <listitem><para>
+ specify the RR type of the query. The default is the A RR.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ [-a algorithm] [-e] -k keyname -K keystring
+ </term>
+ <listitem><para>
+ specify a command-line DNS key to validate the answer. For
+ example, to specify the following DNSKEY of example.com:
+<literallayout>
+ example.com. 3600 IN DNSKEY 257 3 5 xxx
+</literallayout>
+ specify the options as follows:
+<screen>
+<userinput>
+ -e -k example.com -K "xxx"
+</userinput>
+</screen>
+ -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.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ -s domain:alt_server_address
+ </term>
+ <listitem><para>
+ specify a separate recursive server address for the specific
+ "domain". Example: -s example.com:2001:db8::1234
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>server_address</term>
+ <listitem><para>
+ an IP(v4/v6) address of the recursive server to which queries
+ are sent.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hostname</term>
+ <listitem><para>
+ the domain name for the query
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ <sect3>
+ <title>sample-async: a simple stub resolver, working asynchronously</title>
+ <para>
+ Similar to "sample", but accepts a list
+ of (query) domain names as a separate file and resolves the names
+ asynchronously.</para>
+ <para>
+ Usage: sample-async [-s server_address] [-t RR_type] input_file</para>
+ <para>
+ Options and Arguments:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ -s server_address
+ </term>
+ <listitem>
+ an IPv4 address of the recursive server to which queries are sent.
+ (IPv6 addresses are not supported in this implementation)
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ -t RR_type
+ </term>
+ <listitem>
+ specify the RR type of the queries. The default is the A
+ RR.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ input_file
+ </term>
+ <listitem>
+ a list of domain names to be resolved. each line
+ consists of a single domain name. Example:
+ <literallayout>
+ www.example.com
+ mx.examle.net
+ ns.xxx.example
+</literallayout>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ <sect3>
+ <title>sample-request: a simple DNS transaction client</title>
+ <para>
+ 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 <command>dig</command>.
+ </para>
+ <para>
+ Usage: sample-request [-t RRtype] server_address hostname
+ </para>
+ <para>
+ Options and Arguments:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ -t RRtype
+ </term>
+ <listitem>
+ <para>
+ specify the RR type of
+ the queries. The default is the A RR.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ server_address
+ </term>
+ <listitem>
+ <para>
+ an IP(v4/v6)
+ address of the recursive server to which the query is sent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ hostname
+ </term>
+ <listitem>
+ <para>
+ the domain name for the query
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ <sect3>
+ <title>sample-gai: getaddrinfo() and getnameinfo() test code</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ Usage: sample-gai hostname
+ </para>
+ </sect3>
+ <sect3>
+ <title>sample-update: a simple dynamic update client program</title>
+ <para>
+ 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 <command>nsupdate</command>.
+ </para>
+ <para>
+ Usage: sample-update [options] (add|delete) "update data"
+ </para>
+ <para>
+ Options and Arguments:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ -a auth_server
+ </term>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ -k keyfile
+ </term>
+ <listitem><para>
+ A TSIG key file to secure the update transaction. The keyfile
+ format is the same as that for the nsupdate utility.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ -p prerequisite
+ </term>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ -r recursive_server
+ </term>
+ <listitem><para>
+ 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
+ sent.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ -z zonename
+ </term>
+ <listitem><para>
+ The domain name of the zone that contains
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ (add|delete)
+ </term>
+ <listitem><para>
+ Specify the type of update operation. Either "add" or "delete"
+ must be specified.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ "update data"
+ </term>
+ <listitem><para>
+ Specify the data to be updated. A typical example of the data
+ would look like "name TTL RRtype RDATA".
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <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.</note>
+
+ <para>
+ Examples: assuming the primary authoritative server of the
+ dynamic.example.com zone has an IPv6 address 2001:db8::1234,
+ </para>
+ <screen>
+$ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key add "foo.dynamic.example.com 30 IN A 192.168.2.1"</userinput></screen>
+ <para>
+ adds an A RR for foo.dynamic.example.com using the given key.
+ </para>
+ <screen>
+$ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com 30 IN A"</userinput></screen>
+ <para>
+ removes all A RRs for foo.dynamic.example.com using the given key.
+ </para>
+ <screen>
+$ <userinput>sample-update -a sample-update -k Kxxx.+nnn+mmmm.key delete "foo.dynamic.example.com"</userinput></screen>
+ <para>
+ removes all RRs for foo.dynamic.example.com using the given key.
+ </para>
+ </sect3>
+ <sect3>
+ <title>nsprobe: domain/name server checker in terms of RFC 4074</title>
+ <para>
+ It checks a set
+ of domains to see the name servers of the domains behave
+ correctly in terms of RFC 4074. This is included in the set of
+ sample programs to show how the export library can be used in a
+ DNS-related application.
+ </para>
+ <para>
+ Usage: nsprobe [-d] [-v [-v...]] [-c cache_address] [input_file]
+ </para>
+ <para>
+ Options
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ -d
+ </term>
+ <listitem><para>
+ run in the "debug" mode. with this option nsprobe will dump
+ every RRs it receives.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ -v
+ </term>
+ <listitem><para>
+ increase verbosity of other normal log messages. This can be
+ specified multiple times
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ -c cache_address
+ </term>
+ <listitem><para>
+ 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 127.0.0.1.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ input_file
+ </term>
+ <listitem><para>
+ 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
+ "example.com". In general this domain name must be the apex
+ name of some DNS zone (unlike normal "host names" such as
+ "www.example.com"). 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.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>Library References</title>
+ <para>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.</para>
+ </sect2>
+</sect1>
+<!-- $Id: libdns.xml,v 1.2 2010/02/03 01:31:49 each Exp $ -->
--- /dev/null
+<?xml version="1.0" encoding="utf-8"?>
+<sect1 id="rfc5011.support">
+ <title>Dynamic Trust Anchor Management</title>
+ <para>BIND 9.7.0 introduces support for RFC 5011, dynamic trust
+ anchor management. Using this feature allows
+ <command>named</command> to keep track of changes to critical
+ DNSSEC keys without any need for the operator to make changes to
+ configuration files.</para>
+ <sect2>
+ <title>Validating Resolver</title>
+ <!-- TODO: command tag is overloaded for configuration and executables -->
+ <para>To configure a validating resolver to use RFC 5011 to
+ maintain a trust anchor, configure the trust anchor using a
+ <command>managed-keys</command> statement. Information about
+ this can be found in
+ <xref linkend="managed-keys" />.</para>
+ <!-- TODO: managed-keys examples
+also in DNSSEC section above here in ARM -->
+ </sect2>
+ <sect2>
+ <title>Authoritative Server</title>
+ <para>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.</para>
+ <para>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.</para>
+ <para>The easiest way to place a stand-by key in a zone is to
+ use the "smart signing" features of
+ <command>dnssec-keygen</command> and
+ <command>dnssec-signzone</command>. If a key with a publication
+ date in the past, but an activation date which is unset or in
+ the future, "
+ <command>dnssec-signzone -S</command>" will include the DNSKEY
+ record in the zone, but will not sign with it:</para>
+ <screen>
+$ <userinput>dnssec-keygen -K keys -f KSK -P now -A now+2y example.net</userinput>
+$ <userinput>dnssec-signzone -S -K keys example.net</userinput>
+</screen>
+ <para>To revoke a key, the new command
+ <command>dnssec-revoke</command> has been added. This adds the
+ REVOKED bit to the key flags and re-generates the
+ <filename>K*.key</filename> and
+ <filename>K*.private</filename> files.</para>
+ <para>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.)</para>
+ <para>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).</para>
+ <para>See RFC 5011 for more details on key rollover
+ scenarios.</para>
+ <para>When a key has been revoked, its key ID changes,
+ increasing by 128, and wrapping around at 65535. So, for
+ example, the key "<filename>Kexample.com.+005+10000</filename>" becomes
+ "<filename>Kexample.com.+005+10128</filename>".</para>
+ <para>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,
+ <command>dnssec-keygen</command> 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.</para>
+ <para>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.</para>
+ <para>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.</para>
+ </sect2>
+</sect1>
--- /dev/null
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+ [<!ENTITY mdash "—">]>
+<sect1 id="pkcs11">
+ <title>PKCS #11 (Cryptoki) support</title>
+ <para>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.</para>
+ <para>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.</para>
+ <sect2>
+ <title>Prerequisites</title>
+ <para>See the HSM vendor documentation for information about
+ installing, initializing, testing and troubleshooting the
+ HSM.</para>
+ <para>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.</para>
+ <para>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 controlled.</para>
+ <para>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:</para>
+ <itemizedlist>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </itemizedlist>
+ <para>The modified OpenSSL code is included in the BIND 9.7.0
+ release, in the form of a context diff against the latest OpenSSL.
+ </para>
+ <note>
+ The latest OpenSSL version at the time of the BIND release
+ is 0.9.8l.
+ ISC will provide an updated patch as new versions of OpenSSL
+ are released. The version number in the following examples
+ is expected to change.</note>
+ <para>
+ 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.</para>
+ <para>Obtain OpenSSL 0.9.8l:</para>
+ <screen>
+$ <userinput>wget <ulink>http://www.openssl.org/source/openssl-0.9.8l.tar.gz</ulink></userinput>
+</screen>
+ <para>Extract the tarball:</para>
+ <screen>
+$ <userinput>tar zxf openssl-0.9.8l.tar.gz</userinput>
+</screen>
+ <para>Apply the patch from the BIND 9 release:</para>
+ <screen>
+$ <userinput>patch -p1 -d openssl-0.9.8l \
+ < bind-9.7.0/bin/pkcs11/openssl-0.9.8l-patch</userinput>
+</screen>
+ <note>(Note that the patch file may not be compatible with the
+ "patch" utility on all operating systems. You may need to
+ install GNU patch.)</note>
+ <para>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.</para>
+ <sect3>
+ <!-- Example 1 -->
+ <title>Building OpenSSL for the AEP Keyper on Linux</title>
+ <para>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.</para>
+ <para>The Keyper-specific PKCS #11 provider library is
+ delivered with the Keyper software. In this example, we place
+ it /opt/pkcs11/usr/lib:</para>
+ <screen>
+$ <userinput>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</userinput>
+</screen>
+ <para>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.</para>
+ <para>Finally, the Keyper library requires threads, so we
+ must specify -pthread.</para>
+ <screen>
+$ <userinput>cd openssl-0.9.8l</userinput>
+$ <userinput>./Configure linux-generic32 -m32 -pthread \
+ --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
+ --pk11-flavor=sign-only \
+ --prefix=/opt/pkcs11/usr</userinput>
+</screen>
+ <para>After configuring, run "<command>make</command>"
+ and "<command>make test</command>". If "<command>make
+ test</command>" fails with "pthread_atfork() not found", you forgot to
+ add the -pthread above.</para>
+ </sect3>
+ <sect3>
+ <!-- Example 2 -->
+ <title>Building OpenSSL for the SCA 6000 on Solaris</title>
+ <para>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'.</para>
+ <para>In this example, we are building on Solaris x86 on an
+ AMD64 system.</para>
+ <screen>
+$ <userinput>cd openssl-0.9.8l</userinput>
+$ <userinput>./Configure solaris64-x86_64-cc \
+ --pk11-libname=/usr/lib/64/libpkcs11.so \
+ --pk11-flavor=crypto-accelerator \
+ --prefix=/opt/pkcs11/usr</userinput>
+</screen>
+ <para>(For a 32-bit build, use "solaris-x86-cc" and
+ /usr/lib/libpkcs11.so.)</para>
+ <para>After configuring, run
+ <command>make</command> and
+ <command>make test</command>.</para>
+ <para>Once you have built OpenSSL, run
+ "<command>apps/openssl engine pkcs11</command>" to confirm
+ that PKCS #11 support was compiled in correctly. The output
+ should be one of the following lines, depending on the flavor
+ selected:</para>
+ <screen>
+ (pkcs11) PKCS #11 engine support (sign only)
+</screen>
+ <para>Or:</para>
+ <screen>
+ (pkcs11) PKCS #11 engine support (crypto accelerator)
+</screen>
+ <para>Next, run
+ "<command>apps/openssl engine pkcs11 -t</command>". This will
+ attempt to initialize the PKCS #11 engine. If it is able to
+ do so successfully, it will report
+ <quote><literal>[ available ]</literal></quote>.</para>
+ <para>If the output is correct, run
+ "<command>make install</command>" which will install the
+ modified OpenSSL suite to
+ <filename>/opt/pkcs11/usr</filename>.</para>
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>Building BIND 9 with PKCS#11</title>
+ <para>When building BIND 9, the location of the custom-built
+ OpenSSL library must be specified via configure.</para>
+ <sect3>
+ <!-- Example 3 -->
+ <title>Configuring BIND 9 for Linux</title>
+ <para>To link with the PKCS #11 provider, threads must be
+ enabled in the BIND 9 build.</para>
+ <para>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.</para>
+ <screen>
+$ <userinput>cd ../bind-9.7.0</userinput>
+$ <userinput>./configure CC="gcc -m32" --enable-threads \
+ --with-openssl=/opt/pkcs11/usr \
+ --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput>
+</screen>
+ </sect3>
+ <sect3>
+ <!-- Example 4 -->
+ <title>Configuring BIND 9 for Solaris</title>
+ <para>To link with the PKCS #11 provider, threads must be
+ enabled in the BIND 9 build.</para>
+ <screen>
+$ <userinput>cd ../bind-9.7.0</userinput>
+$ <userinput>./configure CC="cc -xarch=amd64" --enable-threads \
+ --with-openssl=/opt/pkcs11/usr \
+ --with-pkcs11=/usr/lib/64/libpkcs11.so</userinput>
+</screen>
+ <para>(For a 32-bit build, omit CC="cc -xarch=amd64".)</para>
+ <para>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).</para>
+ </sect3>
+ <para>After configuring, run
+ "<command>make</command>",
+ "<command>make test</command>" and
+ "<command>make install</command>".</para>
+ </sect2>
+ <sect2>
+ <title>PKCS #11 Tools</title>
+ <para>BIND 9 includes a minimal set of tools to operate the
+ HSM, including
+ <command>pkcs11-keygen</command> to generate a new key pair
+ within the HSM,
+ <command>pkcs11-list</command> to list objects currently
+ available, and
+ <command>pkcs11-destroy</command> to remove objects.</para>
+ <para>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.)</para>
+ </sect2>
+ <sect2>
+ <title>Using the HSM</title>
+ <para>First, we must set up the runtime environment so the
+ OpenSSL and PKCS #11 libraries can be loaded:</para>
+ <screen>
+$ <userinput>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</userinput>
+</screen>
+ <para>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
+ <filename>/opt/Keyper/PKCS11Provider/machine</filename>,
+ use:</para>
+ <screen>
+$ <userinput>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</userinput>
+</screen>
+ <!-- TODO: why not defined at compile time? -->
+ <para>These environment variables must be set whenever running
+ any tool that uses the HSM, including
+ <command>pkcs11-keygen</command>,
+ <command>pkcs11-list</command>,
+ <command>pkcs11-destroy</command>,
+ <command>dnssec-keyfromlabel</command>,
+ <command>dnssec-signzone</command>,
+ <command>dnssec-keygen</command>(which will use the HSM for
+ random number generation), and
+ <command>named</command>.</para>
+ <para>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":</para>
+ <screen>
+$ <userinput>pkcs11-keygen -b 2048 -l sample-ksk</userinput>
+</screen>
+ <para>To confirm that the key exists:</para>
+ <screen>
+$ <userinput>pkcs11-list</userinput>
+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]
+</screen>
+ <para>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":</para>
+ <screen>
+$ <userinput>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</userinput>
+</screen>
+ <para>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.</para>
+ <para>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:</para>
+ <screen>
+$ <userinput>pkcs11-keygen -b 1024 -l sample-zsk</userinput>
+$ <userinput>dnssec-keyfromlabel -l sample-zsk example.net</userinput>
+</screen>
+ <para>Alternatively, you may prefer to generate a conventional
+ on-disk key, using dnssec-keygen:</para>
+ <screen>
+$ <userinput>dnssec-keygen example.net</userinput>
+</screen>
+ <para>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.</para>
+ <para>Now you can sign the zone. (Note: If not using the -S
+ option to
+ <command>dnssec-signzone</command>, it will be necessary to add
+ the contents of both
+ <filename>K*.key</filename> files to the zone master file before
+ signing it.)</para>
+ <screen>
+$ <userinput>dnssec-signzone -S example.net</userinput>
+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
+</screen>
+ </sect2>
+ <sect2>
+ <title>Specifying the engine on the command line</title>
+ <para>The OpenSSL engine can be specified in
+ <command>named</command> and all of the BIND
+ <command>dnssec-*</command> 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.</para>
+ <para>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:</para>
+ <screen>
+$ <userinput>dnssec-signzone -E '' -S example.net</userinput>
+</screen>
+ <para>This causes
+ <command>dnssec-signzone</command> to run as if it were compiled
+ without the --with-pkcs11 option.</para>
+ </sect2>
+ <sect2>
+ <title>Running named with automatic zone re-signing</title>
+ <para>If you want
+ <command>named</command> 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,
+ <filename>/opt/pkcs11/usr/ssl/openssl.cnf</filename>).</para>
+ <para>The location of the openssl.cnf file can be overridden by
+ setting the OPENSSL_CONF environment variable before running
+ named.</para>
+ <para>Sample openssl.cnf:</para>
+ <programlisting>
+ openssl_conf = openssl_def
+ [ openssl_def ]
+ engines = engine_section
+ [ engine_section ]
+ pkcs11 = pkcs11_section
+ [ pkcs11_section ]
+ PIN = <replaceable><PLACE PIN HERE></replaceable>
+</programlisting>
+ <para>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.)</para>
+<!--
+If the PIN is not known, I believe the first time named needs the
+PIN to open a key, it'll ask you to type in the PIN, which will be
+a problem because it probably won't be running on a terminal
+-->
+ <warning>
+ <para>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.</para>
+ </warning>
+ </sect2>
+ <!-- TODO: what is alternative then for named dynamic re-signing? -->
+ <!-- TODO: what happens if PIN is not known? named will log about it? -->
+</sect1>
projects / thirdparty / bind9.git / commitdiff
