<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+ [<!ENTITY mdash "—">]>
<!--
- Copyright (C) 2010, 2012-2014 Internet Systems Consortium, Inc. ("ISC")
-
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
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:
<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>
</para>
<itemizedlist>
<listitem>
- 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>
- 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 — 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 — 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>
<para>Apply the patch from the BIND 9 release:</para>
<screen>
$ <userinput>patch -p1 -d openssl-0.9.8zc \
- < bind9/bin/pkcs11/openssl-0.9.8zc-patch</userinput>
+ < 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>
</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>
$ <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>
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
<!-- 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>
<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>
</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><PLACE PIN HERE></replaceable>
+ openssl_conf = openssl_def
+ [ openssl_def ]
+ engines = engine_section
+ [ engine_section ]
+ pkcs11 = pkcs11_section
+ [ pkcs11_section ]
+ PIN = <replaceable><PLACE PIN HERE></replaceable>
</programlisting>
<para>
This will also allow the dnssec-* tools to access the HSM
</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>
projects / thirdparty / bind9.git / commitdiff
