
		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
acceration board, tested under Solaris x86, and the AEP Keyper
network-attached key storage device, tested with a Debian Linux system.
(The Keyper has also been tested with Windows Server 2003 and found to
work, but with some stability problems that have not yet been resolved.)

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

The modified OpenSSL code is included in BIND 9.7.0a3 release in the form
of a context diff against OpenSSL 0.9.8i.  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.8i:

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

Extract the tarball:

    tar zxf openssl-0.9.8i.tar.gz

Apply the patch from the BIND 9 release:

    patch -p1 -d openssl-0.9.8i \
            < bind-9.7.0a3/contrib/pkcs11-keygen/openssl-0.9.8i-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-secured key storage device, but it does
    not provide hardware cryptographic acceleration.  It can carry out
    cryptographic operations, but it is probably slower than your
    system's CPU, so it is most efficient to use it only for operations
    that require the secured private key.

    The patched OpenSSL source tree includes two versions of the PKCS #11
    engine; one uses the HSM for all cryptographic operations, and the
    other only uses it for signing.  The signing-only engine is recommended
    for the Keyper.  To build OpenSSL with the signing-only engine:

        cp openssl-0.9.8i/crypto/engine/hw_pk11-kp.c \
           openssl-0.9.8i/crypto/engine/hw_pk11.c
        cp openssl-0.9.8i/crypto/engine/hw_pk11_pub-kp.c \
           openssl-0.9.8i/crypto/engine/hw_pk11_pub.c

    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.8i
        ./Configure linux-generic32 -m32 -pthread \
            --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
            --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.

    In this example, we are building on Solaris x86 on an AMD64 system.

        cd openssl-0.9.8i
        ./Configure solaris64-x86_64-cc \
            --pk11-libname=/usr/lib/64/libpkcs11.so \
            --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" to confirm that
PKCS #11 support was compiled in correctly.  The output should include the
line:

        (pkcs11) PKCS #11 engine support

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 is 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.0a3
        ./configure CC="gcc -m32" --enable-threads \
            --with-openssl=/opt/pkcs11/usr

    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.0a3
        ./configure CC="cc -xarch=amd64" --enable-threads \
            --with-openssl=/opt/pkcs11/usr

    (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

The contrib/pkcs11-keygen directory contains a set of experimental
tools to operate an HSM for the benefit of BIND 9, including "genkey" to
generate a new key pair within the HSM, and "listobjs" to list keys
currently available.

These tools are not yet complete, not documented, and not supported
by ISC.  As of BIND 9.7.0a3, they still lack such basic amenities as
a Makefile.  Other commercial or open-source PKCS #11 tools may be
available which are better-suited to the job.  However, in the
absence of those tools, the ones provided in contrib/pkcs11-keygen
can get you started.

    EXAMPLE 5--BUILDING TOOLS ON LINUX:

    gcc -m32 -DHAVE_GETPASS -I. -L /opt/pkcs11/usr/lib \
        genkey.c -o genkey -lpkcs11
    gcc -m32 -DHAVE_GETPASS -I. -L /opt/pkcs11/usr/lib \
        listobjs.c -o listobjs -lpkcs11
    gcc -m32 -DHAVE_GETPASS -I. -L /opt/pkcs11/usr/lib \
        destroyobj.c -o destroyobj -lpkcs11
    cd ../..

    EXAMPLE 6--BUILDING TOOLS ON SOLARIS WITH SCA 6000:

    cc -I. genkey.c -o genkey -lpkcs11
    cc -I. listobjs.c -o listobjs -lpkcs11
    cc -I. destroyobj.c -o destroyobj -lpkcs11
    cd ../..

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
which uses the HSM, including genkey, listobjs, destroyobj,
dnssec-keyfromlabel, dnssec-signzone, 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":

    contrib/pkcs11-keygen/genkey -b 2048 -l sample-ksk

To confirm that the key exists:

    contrib/pkcs11-keygen/listobjs
    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 -a NSEC3RSASHA1 -l pkcs11:sample-ksk -f KSK example.net

(Note:  It is necessary to specify "pkcs11:" before the key's label;
otherwise the PCKS #11 engine will look for the key on disk rather than
in the HSM.  If you forget to do this, dnssec-keyfromlabel will return
"not found".)

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:

    contrib/pkcs11-keygen/genkey -b 1024 -l sample-zsk
    dnssec-keyfromlabel -a NSEC3RSASHA1 -l pkcs11:sample-zsk example.net

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

    dnssec-keygen -a NSEC3RSASHA1 -b 1024 example.net

This provides less security than an HSM key, but since HSMs are often
slower at signing than your system's CPU, it may be more efficient to
reserve HSM keys for 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

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>

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.
