From: Evan Hunt <each@isc.org>
Date: Sat, 10 Jan 2015 19:40:01 +0000 (-0800)
Subject: [master] revise pkcs11 doc
X-Git-Tag: v9.11.0a1~1124
X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=6124e803cf8cb30dbd412b8c64667206c50e1976;p=thirdparty%2Fbind9.git

[master] revise pkcs11 doc
---

diff --git a/doc/arm/pkcs11.xml b/doc/arm/pkcs11.xml
index 6ef112bdb9d..f38b68333b9 100644
--- a/doc/arm/pkcs11.xml
+++ b/doc/arm/pkcs11.xml
@@ -1,6 +1,6 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-               [<!ENTITY mdash "&#8212;">]>
+	       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+	       [<!ENTITY mdash "&#8212;">]>
 <!--
  - Copyright (C) 2010, 2012-2014  Internet Systems Consortium, Inc. ("ISC")
  -
@@ -29,8 +29,9 @@
     been tested with Debian Linux, Solaris x86 and Windows Server 2003;
     the Thales nShield, tested with Debian Linux; and the Sun SCA 6000
     cryptographic acceleration board, tested with Solaris x86.  In
-    addition, BIND can be used with SoftHSM, a software-based HSM
-    simulator produced by the OpenDNSSEC project.
+    addition, BIND can be used with all current versions of SoftHSM,
+    a software-based HSM simulator library produced by the OpenDNSSEC
+    project.
   </para>
   <para>
     PKCS#11 makes use of a "provider library": a dynamically loadable
@@ -63,12 +64,12 @@
       out <emphasis>every</emphasis> cryptographic operation BIND 9 may
       need. The HSM's provider library must have a complete implementation
       of the PKCS#11 API, so that all these functions are accessible. As of
-      this writing, only the Thales nShield HSM and the latest development
-      version of SoftHSMv2 can be used in this fashion.  For other HSMs,
-      including the AEP Keyper, Sun SCA 6000 and older versions of SoftHSM,
-      use OpenSSL-based PKCS#11. (Note: Eventually, when more HSMs become
-      capable of supporting native PKCS#11, it is expected that OpenSSL-based
-      PKCS#11 will be deprecated.)
+      this writing, only the Thales nShield HSM and SoftHSMv2 can be used
+      in this fashion.  For other HSMs, including the AEP Keyper, Sun SCA
+      6000 and older versions of SoftHSM, use OpenSSL-based PKCS#11.
+      (Note: Eventually, when more HSMs become capable of supporting
+      native PKCS#11, it is expected that OpenSSL-based PKCS#11 will
+      be deprecated.)
     </para>
     <para>
       To build BIND with native PKCS#11, configure as follows:
@@ -88,38 +89,42 @@ $ <userinput>./configure --enable-native-pkcs11 \
       <command>dnssec-*</command> tools, or the <option>-m</option> in
       the <command>pkcs11-*</command> tools.)
     </para>
-    <para>
-      SoftHSMv2 is available from
-      <ulink url="https://github.com/opendnssec/SoftHSMv2">
-	https://github.com/opendnssec/SoftHSMv2
-      </ulink>;
-      it is a software library developed by the OpenDNSSEC project
-      (<ulink url="http://www.opendnssec.org">
-	http://www.opendnssec.org
-      </ulink>)
-      which provides a PKCS#11 interface to a virtual HSM, implemented in
-      the form of a SQLite3 database on the local filesystem.  It provides
-      less security than a true HSM, but it allows you to experiment with
-      native PKCS#11 when an HSM is not available.  SoftHSMv2 can be built
-      to use either OpenSSL or the Botan library for encryption, but as
-      of this writing (January 2015), when using it for native PKCS#11
-      in BIND, OpenSSL is required.
-    </para>
-    <para>
-      By default, the SoftHSMv2 configuration file is
-      <replaceable>prefix</replaceable>/etc/softhsm2.conf, where
-      <replaceable>prefix</replaceable> is configured at compile time.
-      This location can be overridden by the SOFTHSM2_CONF environment
-      variable.  The SoftHSMv2 cryptographic store must be installed and
-      initialized before using it with BIND.
-    </para>
-    <screen>
+    <sect3>
+      <title>Building SoftHSMv2</title>
+      <para>
+	SoftHSMv2, the latest development version of SoftHSM, is available
+	from
+	<ulink url="https://github.com/opendnssec/SoftHSMv2">
+	  https://github.com/opendnssec/SoftHSMv2
+	</ulink>.
+	It is a software library developed by the OpenDNSSEC project
+	(<ulink url="http://www.opendnssec.org">
+	  http://www.opendnssec.org
+	</ulink>)
+	which provides a PKCS#11 interface to a virtual HSM, implemented in
+	the form of a SQLite3 database on the local filesystem.  It provides
+	less security than a true HSM, but it allows you to experiment with
+	native PKCS#11 when an HSM is not available.  SoftHSMv2 can be
+	configured to use either OpenSSL or the Botan library to perform
+	cryptographic functions, but when using it for native PKCS#11 in
+	BIND, OpenSSL is required.
+      </para>
+      <para>
+	By default, the SoftHSMv2 configuration file is
+	<replaceable>prefix</replaceable>/etc/softhsm2.conf (where
+	<replaceable>prefix</replaceable> is configured at compile time).
+	This location can be overridden by the SOFTHSM2_CONF environment
+	variable.  The SoftHSMv2 cryptographic store must be installed and
+	initialized before using it with BIND.
+      </para>
+      <screen>
 $ <userinput> cd SoftHSMv2 </userinput>
 $ <userinput> configure --with-crypto-backend=openssl --prefix=/opt/pkcs11/usr --enable-gost </userinput>
 $ <userinput> make </userinput>
 $ <userinput> make install </userinput>
 $ <userinput> /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label softhsmv2 </userinput>
-    </screen>
+      </screen>
+    </sect3>
   </sect2>
   <sect2>
     <title>OpenSSL-based PKCS#11</title>
@@ -139,26 +144,26 @@ $ <userinput> /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label s
     </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>
+	<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 &mdash; 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>
+	<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 &mdash; 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>
@@ -193,94 +198,94 @@ $ <userinput>tar zxf openssl-0.9.8zc.tar.gz</userinput>
       <para>Apply the patch from the BIND 9 release:</para>
       <screen>
 $ <userinput>patch -p1 -d openssl-0.9.8zc \
-              &lt; bind9/bin/pkcs11/openssl-0.9.8zc-patch</userinput>
+	      &lt; bind9/bin/pkcs11/openssl-0.9.8zc-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 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.
+	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>
       <para>
-        Later, when building BIND 9, the location of the custom-built
-        OpenSSL library will need to be specified via configure.
+	Later, when building BIND 9, the location of the custom-built
+	OpenSSL library will need to be specified via configure.
       </para>
     </sect3>
     <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.
+	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:
+	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.
+	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.
+	Finally, the Keyper library requires threads, so we
+	must specify -pthread.
       </para>
       <screen>
 $ <userinput>cd openssl-0.9.8zc</userinput>
 $ <userinput>./Configure linux-generic32 -m32 -pthread \
-            --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \
-            --pk11-flavor=sign-only \
-            --prefix=/opt/pkcs11/usr</userinput>
+	    --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.
+	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'.
+	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.
+	In this example, we are building on Solaris x86 on an
+	AMD64 system.
       </para>
       <screen>
 $ <userinput>cd openssl-0.9.8zc</userinput>
 $ <userinput>./Configure solaris64-x86_64-cc \
-            --pk11-libname=/usr/lib/64/libpkcs11.so \
-            --pk11-flavor=crypto-accelerator \
-            --prefix=/opt/pkcs11/usr</userinput>
+	    --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.)
+	(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>.
+	After configuring, run 
+	<command>make</command> and 
+	<command>make test</command>.
       </para>
     </sect3>
     <sect3>
@@ -294,17 +299,16 @@ $ <userinput>./Configure solaris64-x86_64-cc \
 	</ulink>)
 	which provides a
 	PKCS#11 interface to a virtual HSM, implemented in the form of
-	a SQLite3 database on the local filesystem.  SoftHSM can be
-	configured to use either OpenSSL or the Botan library for
-	encryption, and SQLite3 for data storage.  Though less secure
-	than a true HSM, it can allow you to experiment with PKCS#11
-	when an HSM is not available.
+	a SQLite3 database on the local filesystem.  SoftHSM uses
+	the Botan library to perform cryptographic functions.  Though
+	less secure than a true HSM, it can allow you to experiment
+	with PKCS#11 when an HSM is not available.
       </para>
       <para>
-        The SoftHSM cryptographic store must be installed and
-        initialized before using it with OpenSSL, and the SOFTHSM_CONF
-        environment variable must always point to the SoftHSM configuration
-        file:
+	The SoftHSM cryptographic store must be installed and
+	initialized before using it with OpenSSL, and the SOFTHSM_CONF
+	environment variable must always point to the SoftHSM configuration
+	file:
       </para>
       <screen>
 $ <userinput> cd softhsm-1.3.7 </userinput>
@@ -316,21 +320,21 @@ $ <userinput> echo "0:/opt/pkcs11/softhsm.db" > $SOFTHSM_CONF </userinput>
 $ <userinput> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm </userinput>
 </screen>
       <para>
-        SoftHSM can perform all cryptographic operations, but
-        since it only uses your system CPU, there is no advantage to using
-        it for anything but signing.  Therefore, we choose the 'sign-only'
-        flavor when building OpenSSL.
+	SoftHSM can perform all cryptographic operations, but
+	since it only uses your system CPU, there is no advantage to using
+	it for anything but signing.  Therefore, we choose the 'sign-only'
+	flavor when building OpenSSL.
       </para>
       <screen>
 $ <userinput>cd openssl-0.9.8zc</userinput>
 $ <userinput>./Configure linux-x86_64 -pthread \
-            --pk11-libname=/opt/pkcs11/usr/lib/libsofthsm.so \
-            --pk11-flavor=sign-only \
-            --prefix=/opt/pkcs11/usr</userinput>
+	    --pk11-libname=/opt/pkcs11/usr/lib/libsofthsm.so \
+	    --pk11-flavor=sign-only \
+	    --prefix=/opt/pkcs11/usr</userinput>
 </screen>
       <para>
-        After configuring, run "<command>make</command>"
-        and "<command>make test</command>".
+	After configuring, run "<command>make</command>"
+	and "<command>make test</command>".
       </para>
     </sect3>
     <para>
@@ -341,11 +345,11 @@ $ <userinput>./Configure linux-x86_64 -pthread \
       selected:
     </para>
     <screen>
-        (pkcs11) PKCS #11 engine support (sign only)
+	(pkcs11) PKCS #11 engine support (sign only)
 </screen>
     <para>Or:</para>
     <screen>
-        (pkcs11) PKCS #11 engine support (crypto accelerator)
+	(pkcs11) PKCS #11 engine support (crypto accelerator)
 </screen>
     <para>
       Next, run
@@ -363,42 +367,42 @@ $ <userinput>./Configure linux-x86_64 -pthread \
       <!-- Example 4 -->
       <title>Configuring BIND 9 for Linux with the AEP Keyper</title>
       <para>
-        To link with the PKCS#11 provider, threads must be
-        enabled in the BIND 9 build.
+	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.
+	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 ../bind9</userinput>
 $ <userinput>./configure CC="gcc -m32" --enable-threads \
-           --with-openssl=/opt/pkcs11/usr \
-           --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput>
+	   --with-openssl=/opt/pkcs11/usr \
+	   --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput>
 </screen>
     </sect3>
     <sect3>
       <!-- Example 5 -->
       <title>Configuring BIND 9 for Solaris with the SCA 6000</title>
       <para>
-        To link with the PKCS#11 provider, threads must be
-        enabled in the BIND 9 build.
+	To link with the PKCS#11 provider, threads must be
+	enabled in the BIND 9 build.
       </para>
       <screen>
 $ <userinput>cd ../bind9</userinput>
 $ <userinput>./configure CC="cc -xarch=amd64" --enable-threads \
-            --with-openssl=/opt/pkcs11/usr \
-            --with-pkcs11=/usr/lib/64/libpkcs11.so</userinput>
+	    --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).
+	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>
     <sect3>
@@ -407,8 +411,8 @@ $ <userinput>./configure CC="cc -xarch=amd64" --enable-threads \
       <screen>
 $ <userinput>cd ../bind9</userinput>
 $ <userinput>./configure --enable-threads \
-           --with-openssl=/opt/pkcs11/usr \
-           --with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so</userinput>
+	   --with-openssl=/opt/pkcs11/usr \
+	   --with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so</userinput>
 </screen>
     </sect3>
     <para>
@@ -612,13 +616,13 @@ $ <userinput>dnssec-signzone -E '' -S example.net</userinput>
     </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>&lt;PLACE PIN HERE&gt;</replaceable>
+	openssl_conf = openssl_def
+	[ openssl_def ]
+	engines = engine_section
+	[ engine_section ]
+	pkcs11 = pkcs11_section
+	[ pkcs11_section ]
+	PIN = <replaceable>&lt;PLACE PIN HERE&gt;</replaceable>
 </programlisting>
     <para>
       This will also allow the dnssec-* tools to access the HSM
@@ -635,9 +639,9 @@ $ <userinput>dnssec-signzone -E '' -S example.net</userinput>
     </para>
     <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 the system in this way.
+	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 the system in this way.
       </para>
     </warning>
   </sect2>