diff --git a/README.pkcs11 b/README.pkcs11 index 5b6fac4fd9..9a096f45ee 100644 --- a/README.pkcs11 +++ b/README.pkcs11 @@ -20,22 +20,32 @@ 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 +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 @@ -65,12 +75,11 @@ 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 + 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: @@ -111,13 +120,19 @@ We will use this location when we configure BIND 9. 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". @@ -131,9 +146,10 @@ library must be specified via configure. To link with the PKCS #11 provider, threads must be enabled in the BIND 9 build. - The PKCS #11 library 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 \ @@ -159,14 +175,17 @@ 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. -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. - -<<>> +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 @@ -203,16 +222,7 @@ 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".) - -<> -<> + 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 @@ -226,18 +236,19 @@ smaller key size, and omitting "-f KSK" from the dnssec-keyfromlabel 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 @@ -250,6 +261,23 @@ K*.key files to the zone master file before signing it.) 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 " 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