add section explaining how to build with SoftHSM

doc/arm/pkcs11.xml

@@ -17,7 +17,7 @@
  - PERFORMANCE OF THIS SOFTWARE.
 -->
 
-<!-- $Id: pkcs11.xml,v 1.6 2012/01/16 19:09:01 each Exp $ -->
+<!-- $Id: pkcs11.xml,v 1.7 2012/01/16 22:50:12 each Exp $ -->
 
 <sect1 id="pkcs11">
   <title>PKCS #11 (Cryptoki) support</title>
@@ -159,36 +159,74 @@ $ <userinput>./Configure solaris64-x86_64-cc \
       <para>After configuring, run 
       <command>make</command> and 
       <command>make test</command>.</para>
-      <para>Once you have built OpenSSL, run
+    </sect3>
-      "<command>apps/openssl engine pkcs11</command>" to confirm
+    <sect3>
-      that PKCS #11 support was compiled in correctly. The output
+      <!-- Example 3 -->
-      should be one of the following lines, depending on the flavor
+      <title>Building OpenSSL for SoftHSM</title>
-      selected:</para>
+      <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.  It uses 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.</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:</para>
       <screen>
+$ <userinput> cd softhsm-1.3.0 </userinput>
+$ <userinput> configure --prefix=/opt/pkcs11/usr </userinput>
+$ <userinput> make </userinput>
+$ <userinput> make install </userinput>
+$ <userinput> export SOFTHSM_CONF=/opt/pkcs11/softhsm.conf </userinput>
+$ <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 need to use it
+      for anything but signing.  Therefore, we choose the 'sign-only'
+      flavor when building OpenSSL.</para>
+      <screen>
+$ <userinput>cd openssl-0.9.8s</userinput>
+$ <userinput>./Configure linux-x86_64 -pthread \
+            --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>".</para>
+    </sect3>
+    <para>Once you have built OpenSSL, run
+    "<command>apps/openssl engine pkcs11</command>" to confirm
+    that PKCS #11 support was compiled in correctly. The output
+    should be one of the following lines, depending on the flavor
+    selected:</para>
+    <screen>
         (pkcs11) PKCS #11 engine support (sign only)
 </screen>
-      <para>Or:</para>
+    <para>Or:</para>
-      <screen>
+    <screen>
         (pkcs11) PKCS #11 engine support (crypto accelerator)
 </screen>
-      <para>Next, run
+    <para>Next, run
-      "<command>apps/openssl engine pkcs11 -t</command>". This will
+    "<command>apps/openssl engine pkcs11 -t</command>". This will
-      attempt to initialize the PKCS #11 engine. If it is able to
+    attempt to initialize the PKCS #11 engine. If it is able to
-      do so successfully, it will report
+    do so successfully, it will report
-      <quote><literal>[ available ]</literal></quote>.</para>
+    <quote><literal>[ available ]</literal></quote>.</para>
-      <para>If the output is correct, run
+    <para>If the output is correct, run
-      "<command>make install</command>" which will install the
+    "<command>make install</command>" which will install the
-      modified OpenSSL suite to 
+    modified OpenSSL suite to 
-      <filename>/opt/pkcs11/usr</filename>.</para>
+    <filename>/opt/pkcs11/usr</filename>.</para>
-    </sect3>
   </sect2>
   <sect2>
     <title>Building BIND 9 with PKCS#11</title>
     <para>When building BIND 9, the location of the custom-built
     OpenSSL library must be specified via configure.</para>
     <sect3>
-      <!-- Example 3 -->
+      <!-- Example 4 -->
-      <title>Configuring BIND 9 for Linux</title>
+      <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.</para>
       <para>The PKCS #11 library for the AEP Keyper is currently
@@ -203,8 +241,8 @@ $ <userinput>./configure CC="gcc -m32" --enable-threads \
 </screen>
     </sect3>
     <sect3>
-      <!-- Example 4 -->
+      <!-- Example 5 -->
-      <title>Configuring BIND 9 for Solaris</title>
+      <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.</para>
       <screen>
@@ -220,10 +258,22 @@ $ <userinput>./configure CC="cc -xarch=amd64" --enable-threads \
       same as the --prefix argument to the OpenSSL
       Configure).</para>
     </sect3>
+    <sect3>
+      <!-- Example 6 -->
+      <title>Configuring BIND 9 for SoftHSM</title>
+      <screen>
+$ <userinput>cd ../bind9</userinput>
+$ <userinput>./configure --enable-threads \
+           --with-openssl=/opt/pkcs11/usr \
+           --with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput>
+</screen>
+    </sect3>
     <para>After configuring, run
     "<command>make</command>",
     "<command>make test</command>" and
     "<command>make install</command>".</para>
+    <para>(Note: If "make test" fails in the "pkcs11" system test, you may
+    have forgotten to set the SOFTHSM_CONF environment variable.)</para>
   </sect2>
   <sect2>
     <title>PKCS #11 Tools</title>