00b67f09dd
Also known as ISC bind. This import adds utilities such as host(1), dig(1), and nslookup(1), as well as many other tools and libraries. Change-Id: I035ca46e64f1965d57019e773f4ff0ef035e4aa3
649 lines
25 KiB
XML
649 lines
25 KiB
XML
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
|
[<!ENTITY mdash "—">]>
|
|
<!--
|
|
- Copyright (C) 2010, 2012-2015 Internet Systems Consortium, Inc. ("ISC")
|
|
-
|
|
- Permission to use, copy, modify, and/or distribute this software for any
|
|
- purpose with or without fee is hereby granted, provided that the above
|
|
- copyright notice and this permission notice appear in all copies.
|
|
-
|
|
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
|
|
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
|
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
|
|
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
- PERFORMANCE OF THIS SOFTWARE.
|
|
-->
|
|
|
|
<sect1 id="pkcs11">
|
|
<title>PKCS#11 (Cryptoki) support</title>
|
|
<para>
|
|
PKCS#11 (Public Key Cryptography Standard #11) defines a
|
|
platform-independent API for the control of hardware security
|
|
modules (HSMs) and other cryptographic support devices.
|
|
</para>
|
|
<para>
|
|
BIND 9 is known to work with three HSMs: The AEP Keyper, which has
|
|
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 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
|
|
library which provides a low-level PKCS#11 interface to drive the HSM
|
|
hardware. The PKCS#11 provider library comes from the HSM vendor, and
|
|
it is specific to the HSM to be controlled.
|
|
</para>
|
|
<para>
|
|
There are two available mechanisms for PKCS#11 support in BIND 9:
|
|
OpenSSL-based PKCS#11 and native PKCS#11. When using the first
|
|
mechanism, BIND uses a modified version of OpenSSL, which loads
|
|
the provider library and operates the HSM indirectly; any
|
|
cryptographic operations not supported by the HSM can be carried
|
|
out by OpenSSL instead. The second mechanism enables BIND to bypass
|
|
OpenSSL completely; BIND loads the provider library itself, and uses
|
|
the PKCS#11 API to drive the HSM directly.
|
|
</para>
|
|
<sect2>
|
|
<title>Prerequisites</title>
|
|
<para>
|
|
See the documentation provided by your HSM vendor for
|
|
information about installing, initializing, testing and
|
|
troubleshooting the HSM.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Native PKCS#11</title>
|
|
<para>
|
|
Native PKCS#11 mode will only work with an HSM capable of carrying
|
|
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 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:
|
|
</para>
|
|
<screen>
|
|
$ <userinput>cd bind9</userinput>
|
|
$ <userinput>./configure --enable-native-pkcs11 \
|
|
--with-pkcs11=<replaceable>provider-library-path</replaceable></userinput>
|
|
</screen>
|
|
<para>
|
|
This will cause all BIND tools, including <command>named</command>
|
|
and the <command>dnssec-*</command> and <command>pkcs11-*</command>
|
|
tools, to use the PKCS#11 provider library specified in
|
|
<replaceable>provider-library-path</replaceable> for cryptography.
|
|
(The provider library path can be overridden using the
|
|
<option>-E</option> in <command>named</command> and the
|
|
<command>dnssec-*</command> tools, or the <option>-m</option> in
|
|
the <command>pkcs11-*</command> tools.)
|
|
</para>
|
|
<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>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2>
|
|
<title>OpenSSL-based PKCS#11</title>
|
|
<para>
|
|
OpenSSL-based PKCS#11 mode uses a modified version of the
|
|
OpenSSL library; stock OpenSSL does not fully support PKCS#11.
|
|
ISC provides a patch to OpenSSL to correct this. This patch is
|
|
based on work originally done by the OpenSolaris project; it has been
|
|
modified by ISC to provide new features such as PIN management and
|
|
key-by-reference.
|
|
</para>
|
|
<para>
|
|
There are two "flavors" of PKCS#11 support provided by
|
|
the patched OpenSSL, one of which must be chosen at
|
|
configuration time. The correct choice depends on the HSM
|
|
hardware:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<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>
|
|
<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>
|
|
The modified OpenSSL code is included in the BIND 9 release,
|
|
in the form of a context diff against the latest versions of
|
|
OpenSSL. OpenSSL 0.9.8, 1.0.0, and 1.0.1 are supported; there are
|
|
separate diffs for each version. In the examples to follow,
|
|
we use OpenSSL 0.9.8, but the same methods work with OpenSSL
|
|
1.0.0 and 1.0.1.
|
|
</para>
|
|
<note>
|
|
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.
|
|
</note>
|
|
<para>
|
|
Before building BIND 9 with PKCS#11 support, it will be
|
|
necessary to build OpenSSL with the patch in place, and configure
|
|
it with the path to your HSM's PKCS#11 provider library.
|
|
</para>
|
|
<sect3>
|
|
<title>Patching OpenSSL</title>
|
|
<screen>
|
|
$ <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.8zc.tar.gz</userinput>
|
|
</screen>
|
|
<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>
|
|
</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>
|
|
<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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</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:
|
|
</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.
|
|
</para>
|
|
<para>
|
|
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>
|
|
</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.
|
|
</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'.
|
|
</para>
|
|
<para>
|
|
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>
|
|
</screen>
|
|
<para>
|
|
(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>.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<!-- Example 3 -->
|
|
<title>Building OpenSSL for SoftHSM</title>
|
|
<para>
|
|
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 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:
|
|
</para>
|
|
<screen>
|
|
$ <userinput> cd softhsm-1.3.7 </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 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>
|
|
</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>
|
|
<screen>
|
|
(pkcs11) PKCS #11 engine support (crypto accelerator)
|
|
</screen>
|
|
<para>
|
|
Next, run
|
|
"<command>apps/openssl engine pkcs11 -t</command>". This will
|
|
attempt to initialize the PKCS#11 engine. If it is able to
|
|
do so successfully, it will report
|
|
<quote><literal>[ available ]</literal></quote>.
|
|
</para>
|
|
<para>
|
|
If the output is correct, run
|
|
"<command>make install</command>" which will install the
|
|
modified OpenSSL suite to <filename>/opt/pkcs11/usr</filename>.
|
|
</para>
|
|
<sect3>
|
|
<!-- 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.
|
|
</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.
|
|
</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>
|
|
</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.
|
|
</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>
|
|
</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).
|
|
</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/libsofthsm.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>
|
|
<para>
|
|
BIND 9 includes a minimal set of tools to operate the
|
|
HSM, including
|
|
<command>pkcs11-keygen</command> to generate a new key pair
|
|
within the HSM,
|
|
<command>pkcs11-list</command> to list objects currently
|
|
available,
|
|
<command>pkcs11-destroy</command> to remove objects, and
|
|
<command>pkcs11-tokens</command> to list available tokens.
|
|
</para>
|
|
<para>
|
|
In UNIX/Linux builds, these tools are built only if BIND
|
|
9 is configured with the --with-pkcs11 option. (Note: If
|
|
--with-pkcs11 is set to "yes", rather than to the path of the
|
|
PKCS#11 provider, then the tools will be built but the
|
|
provider will be left undefined. Use the -m option or the
|
|
PKCS11_PROVIDER environment variable to specify the path to the
|
|
provider.)
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Using the HSM</title>
|
|
<para>
|
|
For OpenSSL-based PKCS#11, we must first set up the runtime
|
|
environment so the OpenSSL and PKCS#11 libraries can be loaded:
|
|
</para>
|
|
<screen>
|
|
$ <userinput>export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}</userinput>
|
|
</screen>
|
|
<para>
|
|
This causes <command>named</command> and other binaries to load
|
|
the OpenSSL library from <filename>/opt/pkcs11/usr/lib</filename>
|
|
rather than from the default location. This step is not necessary
|
|
when using native PKCS#11.
|
|
</para>
|
|
<para>
|
|
Some HSMs require other environment variables to be set.
|
|
For example, when operating an AEP Keyper, it is necessary to
|
|
specify the location of the "machine" file, which stores
|
|
information about the Keyper for use by the provider
|
|
library. If the machine file is in
|
|
<filename>/opt/Keyper/PKCS11Provider/machine</filename>,
|
|
use:
|
|
</para>
|
|
<screen>
|
|
$ <userinput>export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider</userinput>
|
|
</screen>
|
|
<para>
|
|
Such environment variables must be set whenever running
|
|
any tool that uses the HSM, including
|
|
<command>pkcs11-keygen</command>,
|
|
<command>pkcs11-list</command>,
|
|
<command>pkcs11-destroy</command>,
|
|
<command>dnssec-keyfromlabel</command>,
|
|
<command>dnssec-signzone</command>,
|
|
<command>dnssec-keygen</command>, and
|
|
<command>named</command>.
|
|
</para>
|
|
<para>
|
|
We can now create and use keys in the HSM. In this case,
|
|
we will create a 2048 bit key and give it the label
|
|
"sample-ksk":
|
|
</para>
|
|
<screen>
|
|
$ <userinput>pkcs11-keygen -b 2048 -l sample-ksk</userinput>
|
|
</screen>
|
|
<para>To confirm that the key exists:</para>
|
|
<screen>
|
|
$ <userinput>pkcs11-list</userinput>
|
|
Enter PIN:
|
|
object[0]: handle 2147483658 class 3 label[8] 'sample-ksk' id[0]
|
|
object[1]: handle 2147483657 class 2 label[8] 'sample-ksk' id[0]
|
|
</screen>
|
|
<para>
|
|
Before using this key to sign a zone, we must create a
|
|
pair of BIND 9 key files. The "dnssec-keyfromlabel" utility
|
|
does this. In this case, we will be using the HSM key
|
|
"sample-ksk" as the key-signing key for "example.net":
|
|
</para>
|
|
<screen>
|
|
$ <userinput>dnssec-keyfromlabel -l sample-ksk -f KSK example.net</userinput>
|
|
</screen>
|
|
<para>
|
|
The resulting K*.key and K*.private files can now be used
|
|
to sign the zone. Unlike normal K* files, which contain both
|
|
public and private key data, these files will contain only the
|
|
public key data, plus an identifier for the private key which
|
|
remains stored within the HSM. Signing with the private key takes
|
|
place inside the HSM.
|
|
</para>
|
|
<para>
|
|
If you wish to generate a second key in the HSM for use
|
|
as a zone-signing key, follow the same procedure above, using a
|
|
different keylabel, a smaller key size, and omitting "-f KSK"
|
|
from the dnssec-keyfromlabel arguments:
|
|
</para>
|
|
<para>
|
|
(Note: When using OpenSSL-based PKCS#11 the label is an arbitrary
|
|
string which identifies the key. With native PKCS#11, the label is
|
|
a PKCS#11 URI string which may include other details about the key
|
|
and the HSM, including its PIN. See
|
|
<xref linkend="man.dnssec-keyfromlabel"/> for details.)
|
|
</para>
|
|
<screen>
|
|
$ <userinput>pkcs11-keygen -b 1024 -l sample-zsk</userinput>
|
|
$ <userinput>dnssec-keyfromlabel -l sample-zsk example.net</userinput>
|
|
</screen>
|
|
<para>
|
|
Alternatively, you may prefer to generate a conventional
|
|
on-disk key, using dnssec-keygen:
|
|
</para>
|
|
<screen>
|
|
$ <userinput>dnssec-keygen example.net</userinput>
|
|
</screen>
|
|
<para>
|
|
This provides less security than an HSM key, but since
|
|
HSMs can be slow or cumbersome to use for security reasons, it
|
|
may be more efficient to reserve HSM keys for use in the less
|
|
frequent key-signing operation. The zone-signing key can be
|
|
rolled more frequently, if you wish, to compensate for a
|
|
reduction in key security. (Note: When using native PKCS#11,
|
|
there is no speed advantage to using on-disk keys, as cryptographic
|
|
operations will be done by the HSM regardless.)
|
|
</para>
|
|
<para>
|
|
Now you can sign the zone. (Note: If not using the -S
|
|
option to <command>dnssec-signzone</command>, it will be
|
|
necessary to add the contents of both <filename>K*.key</filename>
|
|
files to the zone master file before signing it.)
|
|
</para>
|
|
<screen>
|
|
$ <userinput>dnssec-signzone -S example.net</userinput>
|
|
Enter PIN:
|
|
Verifying the zone using the following algorithms:
|
|
NSEC3RSASHA1.
|
|
Zone signing complete:
|
|
Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by
|
|
example.net.signed
|
|
</screen>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Specifying the engine on the command line</title>
|
|
<para>
|
|
When using OpenSSL-based PKCS#11, the "engine" to be used by
|
|
OpenSSL can be specified in <command>named</command> and all of
|
|
the BIND <command>dnssec-*</command> tools by using the "-E
|
|
<engine>" command line option. If BIND 9 is built with
|
|
the --with-pkcs11 option, this option defaults to "pkcs11".
|
|
Specifying the engine will generally not be necessary unless
|
|
for some reason you wish to use a different OpenSSL
|
|
engine.
|
|
</para>
|
|
<para>
|
|
If you wish to disable use of the "pkcs11" engine —
|
|
for troubleshooting purposes, or because the HSM is unavailable
|
|
— set the engine to the empty string. For example:
|
|
</para>
|
|
<screen>
|
|
$ <userinput>dnssec-signzone -E '' -S example.net</userinput>
|
|
</screen>
|
|
<para>
|
|
This causes
|
|
<command>dnssec-signzone</command> to run as if it were compiled
|
|
without the --with-pkcs11 option.
|
|
</para>
|
|
<para>
|
|
When built with native PKCS#11 mode, the "engine" option has a
|
|
different meaning: it specifies the path to the PKCS#11 provider
|
|
library. This may be useful when testing a new provider library.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Running named with automatic zone re-signing</title>
|
|
<para>
|
|
If you want <command>named</command> to dynamically re-sign zones
|
|
using HSM keys, and/or to to sign new records inserted via nsupdate,
|
|
then named must have access to the HSM PIN. In OpenSSL-based PKCS#11,
|
|
this is accomplished by placing the PIN into the openssl.cnf file
|
|
(in the above examples,
|
|
<filename>/opt/pkcs11/usr/ssl/openssl.cnf</filename>).
|
|
</para>
|
|
<para>
|
|
The location of the openssl.cnf file can be overridden by
|
|
setting the OPENSSL_CONF environment variable before running
|
|
named.
|
|
</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>
|
|
</programlisting>
|
|
<para>
|
|
This will also allow the dnssec-* tools to access the HSM
|
|
without PIN entry. (The pkcs11-* tools access the HSM directly,
|
|
not via OpenSSL, so a PIN will still be required to use
|
|
them.)
|
|
</para>
|
|
<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>,
|
|
then the PIN would be read from the file
|
|
<filename>/etc/hsmpin</filename>.
|
|
</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.
|
|
</para>
|
|
</warning>
|
|
</sect2>
|
|
</sect1>
|