diff --git a/doc/arm/pkcs11.xml b/doc/arm/pkcs11.xml index 9a4c2f4c6c..6ef112bdb9 100644 --- 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 HSM's, + 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.) To build BIND with native PKCS#11, configure as follows: @@ -88,6 +88,38 @@ $ ./configure --enable-native-pkcs11 \ dnssec-* tools, or the in the pkcs11-* tools.) + + SoftHSMv2 is available from + + https://github.com/opendnssec/SoftHSMv2 + ; + it is a software library developed by the OpenDNSSEC project + ( + http://www.opendnssec.org + ) + 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. + + + By default, the SoftHSMv2 configuration file is + prefix/etc/softhsm2.conf, where + prefix 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. + + +$ cd SoftHSMv2 +$ configure --with-crypto-backend=openssl --prefix=/opt/pkcs11/usr --enable-gost +$ make +$ make install +$ /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label softhsmv2 + OpenSSL-based PKCS#11 @@ -138,8 +170,8 @@ $ ./configure --enable-native-pkcs11 \ 1.0.0 and 1.0.1. - 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 @@ $ ./configure --enable-native-pkcs11 \ Patching OpenSSL -$ wget http://www.openssl.org/source/openssl-0.9.8y.tar.gz +$ wget http://www.openssl.org/source/openssl-0.9.8zc.tar.gz Extract the tarball: -$ tar zxf openssl-0.9.8y.tar.gz +$ tar zxf openssl-0.9.8zc.tar.gz Apply the patch from the BIND 9 release: -$ patch -p1 -d openssl-0.9.8y \ - < bind9/bin/pkcs11/openssl-0.9.8y-patch +$ patch -p1 -d openssl-0.9.8zc \ + < bind9/bin/pkcs11/openssl-0.9.8zc-patch Note that the patch file may not be compatible with the @@ -209,7 +241,7 @@ $ cp pkcs11.GCC4.0.2.so.4.05 /opt/pkcs11/usr/lib/libpkcs11.so -$ cd openssl-0.9.8y +$ cd openssl-0.9.8zc $ ./Configure linux-generic32 -m32 -pthread \ --pk11-libname=/opt/pkcs11/usr/lib/libpkcs11.so \ --pk11-flavor=sign-only \ @@ -236,7 +268,7 @@ $ ./Configure linux-generic32 -m32 -pthread \ AMD64 system. -$ cd openssl-0.9.8y +$ cd openssl-0.9.8zc $ ./Configure solaris64-x86_64-cc \ --pk11-libname=/usr/lib/64/libpkcs11.so \ --pk11-flavor=crypto-accelerator \ @@ -255,15 +287,18 @@ $ ./Configure solaris64-x86_64-cc \ Building OpenSSL for SoftHSM - 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 + ( + http://www.opendnssec.org + ) + 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. The SoftHSM cryptographic store must be installed and @@ -272,7 +307,7 @@ $ ./Configure solaris64-x86_64-cc \ file: -$ cd softhsm-1.3.0 +$ cd softhsm-1.3.7 $ configure --prefix=/opt/pkcs11/usr $ make $ make install @@ -287,7 +322,7 @@ $ /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label sofths flavor when building OpenSSL. -$ cd openssl-0.9.8y +$ cd openssl-0.9.8zc $ ./Configure linux-x86_64 -pthread \ --pk11-libname=/opt/pkcs11/usr/lib/libsofthsm.so \ --pk11-flavor=sign-only \ @@ -594,7 +629,7 @@ $ dnssec-signzone -E '' -S example.net 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 - pkcs11:object=local-zsk;pin-source=/etc/hsmpin", + pkcs11:object=local-zsk;pin-source=/etc/hsmpin, then the PIN would be read from the file /etc/hsmpin.