upstream/bind9
1
0
Fork 0
mirror of https://github.com/isc-projects/bind9.git synced 2026-06-14 23:40:00 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

[v9_10] improve pkcs11.xml documentation

Browse source 
see RT #37801
This commit is contained in:
Evan Hunt 2015-01-10 00:37:38 -08:00
parent 503412e0ab
commit 173d9db665
1 changed files with 59 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

83
doc/arm/pkcs11.xml
View file

@ -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.)
</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>