[master] improve pkcs11.xml documentation

see RT #37801

diff --git a/doc/arm/pkcs11.xml b/doc/arm/pkcs11.xml
index 2708bf8f86dd0e74d4b92c55f1b5b65bf2f9d916..6ef112bdb9d308bfcea1eff3aeb5fd94ebed8769 100644 (file)
--- a/doc/arm/pkcs11.xml
+++ b/doc/arm/pkcs11.xml
@@ -64,11 +64,11 @@
       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 SoftHSM can be used in this fashion.  For other HSMs,
+      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: As more HSMs become capable of
-      supporting native PKCS#11, it is expected that OpenSSL-based
-      PKCS#11 will eventually be deprecated.)
+      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,6 +88,38 @@ $ <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>
+$ <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>
   </sect2>
   <sect2>
     <title>OpenSSL-based PKCS#11</title>
@@ -138,8 +170,8 @@ $ <userinput>./configure --enable-native-pkcs11 \
       1.0.0 and 1.0.1.
     </para>
     <note>
-      The latest OpenSSL versions as of this writing (January 2014)
-      are 0.9.8y, 1.0.0l, and 1.0.1f.
+      The latest OpenSSL versions as of this writing (January 2015)
+      are 0.9.8zc, 1.0.0o, and 1.0.1j.
       ISC will provide updated patches as new versions of OpenSSL
       are released. The version number in the following examples
       is expected to change.
@@ -152,16 +184,16 @@ $ <userinput>./configure --enable-native-pkcs11 \
     <sect3>
       <title>Patching OpenSSL</title>
       <screen>
-$ <userinput>wget <ulink>http://www.openssl.org/source/openssl-0.9.8y.tar.gz</ulink></userinput>
+$ <userinput>wget <ulink>http://www.openssl.org/source/openssl-0.9.8zc.tar.gz</ulink></userinput>
   </screen>
       <para>Extract the tarball:</para>
       <screen>
-$ <userinput>tar zxf openssl-0.9.8y.tar.gz</userinput>
+$ <userinput>tar zxf openssl-0.9.8zc.tar.gz</userinput>
 </screen>
       <para>Apply the patch from the BIND 9 release:</para>
       <screen>
-$ <userinput>patch -p1 -d openssl-0.9.8y \
-              &lt; bind9/bin/pkcs11/openssl-0.9.8y-patch</userinput>
+$ <userinput>patch -p1 -d openssl-0.9.8zc \
+              &lt; bind9/bin/pkcs11/openssl-0.9.8zc-patch</userinput>
 </screen>
       <note>
         Note that the patch file may not be compatible with the
@@ -209,7 +241,7 @@ $ <userinput>cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so</userin
         must specify -pthread.
       </para>
       <screen>
-$ <userinput>cd openssl-0.9.8y</userinput>
+$ <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 \
@@ -236,7 +268,7 @@ $ <userinput>./Configure linux-generic32 -m32 -pthread \
         AMD64 system.
       </para>
       <screen>
-$ <userinput>cd openssl-0.9.8y</userinput>
+$ <userinput>cd openssl-0.9.8zc</userinput>
 $ <userinput>./Configure solaris64-x86_64-cc \
             --pk11-libname=/usr/lib/64/libpkcs11.so \
             --pk11-flavor=crypto-accelerator \
@@ -255,15 +287,18 @@ $ <userinput>./Configure solaris64-x86_64-cc \
       <!-- Example 3 -->
       <title>Building OpenSSL for SoftHSM</title>
       <para>
-        SoftHSM is a software library provided by the OpenDNSSEC
-        project (http://www.opendnssec.org) which provides a PKCS#11
-        interface to a virtual HSM, implemented in the form of encrypted
-        data 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
-        provide more secure key storage than traditional key files,
-        and can allow you to experiment with PKCS#11 when an HSM is
-        not available.
+       SoftHSM (version 1) 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.  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.
       </para>
       <para>
         The SoftHSM cryptographic store must be installed and
@@ -272,7 +307,7 @@ $ <userinput>./Configure solaris64-x86_64-cc \
         file:
       </para>
       <screen>
-$ <userinput> cd softhsm-1.3.0 </userinput>
+$ <userinput> cd softhsm-1.3.7 </userinput>
 $ <userinput> configure --prefix=/opt/pkcs11/usr </userinput>
 $ <userinput> make </userinput>
 $ <userinput> make install </userinput>
@@ -287,7 +322,7 @@ $ <userinput> /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label sofths
         flavor when building OpenSSL.
       </para>
       <screen>
-$ <userinput>cd openssl-0.9.8y</userinput>
+$ <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 \
@@ -594,7 +629,7 @@ $ <userinput>dnssec-signzone -E '' -S example.net</userinput>
     <para>
       In native PKCS#11 mode, the PIN can be provided in a file specified
       as an attribute of the key's label.  For example, if a key had the label
-      <userinput>pkcs11:object=local-zsk;pin-source=/etc/hsmpin"</userinput>,
+      <userinput>pkcs11:object=local-zsk;pin-source=/etc/hsmpin</userinput>,
       then the PIN would be read from the file
       <filename>/etc/hsmpin</filename>.
     </para>