updated for 9.7.0b1 release

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 patched OpenSSL depends on a "PKCS #11 provider".  This is a shared
- - 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
 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
+    system's CPU.  Therefore, we choose the 'sign-only' flavor when
-    that require the secured private key. This is why the PKCS#11
+    building OpenSSL.
-    engine flavor shall be 'sign-only'.
 
     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
+Once you have built OpenSSL, run "apps/openssl engine pkcs11" to confirm
-PKCS #11 support was compiled in correctly.  The output should include the
+that PKCS #11 support was compiled in correctly.  The output should be
-line:
+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
+    The PKCS #11 library for the AEP Keyper is currently only available as
-    we are building on a 64-bit host, we must force a 32-bit build by
+    a 32-bit binary.  If we are building on a 64-bit host, we must force a
-    adding "-m32" to the CC options on the "configure" command line.
+    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
+These tools are built if BIND 9 is configured with the --with-pkcs11
-the benefit of BIND 9, including "pkcs11-keygen" to generate a new key
+option.  (NOTE: If --with-pkcs11 is set to "yes", rather than to the
-pair within the HSM, "pkcs11-list" to list objects currently available
+path of the PKCS #11 provider, then the tools will be built but the
-and "pkcs11-destroy" to remove objects.
+provider will be left undefined.  Use the -m option or the
-
+PKCS11_PROVIDER environment variable to specify the path to the
-<<<To Finish with 20225 and children about --with-pkcs11>>>
+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
+    dnssec-keyfromlabel -l 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)>>
 
 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
+This provides less security than an HSM key, but since HSMs can be
-slower at signing than your system's CPU, it may be more efficient to
+slow or cumbersome to use for security reasons, it may be more
-reserve HSM keys for the less-frequent key-signing operation.  The
+efficient to reserve HSM keys for use in the less frequent
-zone-signing key can be rolled more frequently, if you wish, to
+key-signing operation.  The zone-signing key can be rolled more
-compensate for a reduction in key security.
+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 <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