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
+ISC to work with with BIND 9, and to provide new features such as
PIN management and key by reference.
-The PKCS#11 engine supports two flavors:
- - the crypto-accelerator which uses the PKCS#11 device for all crypto
- operations it supports. This is the right choice for the SCA 6000.
- - the sign-only which was stripped down and provides only the
- useful features for a secure key store. The Keyper must use this
- flavor.
-
-The modified OpenSSL depends on a "PKCS #11 provider". This is a shared
+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
+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 operation
+ 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 BIND 9.7.0b1 release in the form
of a context diff against OpenSSL 0.9.8k. Before building BIND 9 with
PKCS #11 support, it will be necessary to build OpenSSL with this patch
EXAMPLE 1--BUILDING OPENSSL FOR THE AEP KEYPER ON LINUX:
- The AEP Keyper is a highly-secured key storage device, but it does
+ 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, so it is most efficient to use it only for operations
- that require the secured private key. This is why the PKCS#11
- engine flavor shall be 'sign-only'.
+ 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:
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:
+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
+ (pkcs11) PKCS #11 engine support (sign only)
-<<"apps/openssl engine -t" to see if initialization is correct (available)>>
+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".
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.
+ 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 \
After configuring, run "make", "make test" and "make install".
-PKCS #11 TOOLS
-
-The bin/pkcs11 directory contains a set of tools to operate an HSM for
-the benefit of BIND 9, 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.
+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.
-<<<To Finish with 20225 and children about --with-pkcs11>>>
+These tools are built 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
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".)
-
-<<Something about -E>>
-<<Something about bad formatted .private (simply rerun dnssec-keyfromlabel
-which by side-effect will fix the smart signing dates too)>>
+ 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
arguments:
pkcs11-keygen -b 1024 -l sample-zsk
- dnssec-keyfromlabel -a NSEC3RSASHA1 -l pkcs11:sample-zsk example.net
+ dnssec-keyfromlabel -l 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
+ dnssec-keygen 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.
+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
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
projects / thirdparty / bind9.git / commitdiff
