Every DocBook source document can be namespaced (DocBook 5) or
non-namespaced (DocBook 4). The set of XSL stylesheets used for
producing an output document can also be namespaced or non-namespaced.
Namespaced source documents should be used with namespaced stylesheets
and non-namespaced source documents should be used with non-namespaced
stylesheets. However, both stylesheet flavors contain processing rules
which allow them to be used interchangeably for any type of source
document.
Unfortunately, these processing rules became broken in version 1.79.1 of
the stylesheets, which means that non-namespaced source documents can no
longer be correctly transformed into man pages using namespaced
stylesheets and vice versa. This problem was fixed upstream [1], but no
released version of the XSL stylesheets contains that fix yet.
Back in 2016, this problem was reported as RT #43831 and allegedly fixed
in commit 1b8ce3b330. However, that fix
only helped for the non-namespaced version of the stylesheets - while
also breaking man page generation for the namespaced flavor.
Since using namespaced DocBook sources is the current best practice
(DocBook 5), make BIND DocBook sources namespaced again. When using
version 1.79.1 or 1.79.2 of the XSL stylesheets, care must be taken to
ensure namespaced stylesheets are used for generating BIND
documentation.
[1] https://github.com/docbook/xslt10-stylesheets/issues/109
632 lines
24 KiB
XML
632 lines
24 KiB
XML
<!DOCTYPE book [
|
|
<!ENTITY mdash "—">]>
|
|
<!--
|
|
- Copyright (C) Internet Systems Consortium, Inc. ("ISC")
|
|
-
|
|
- This Source Code Form is subject to the terms of the Mozilla Public
|
|
- License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
- file, you can obtain one at https://mozilla.org/MPL/2.0/.
|
|
-
|
|
- See the COPYRIGHT file distributed with this work for additional
|
|
- information regarding copyright ownership.
|
|
-->
|
|
|
|
<!-- Converted by db4-upgrade version 1.0 -->
|
|
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pkcs11"><info><title>PKCS#11 (Cryptoki) Support</title></info>
|
|
|
|
<para>
|
|
Public Key Cryptography Standard #11 (PKCS#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>
|
|
<section><info><title>Prerequisites</title></info>
|
|
|
|
<para>
|
|
See the documentation provided by your HSM vendor for
|
|
information about installing, initializing, testing and
|
|
troubleshooting the HSM.
|
|
</para>
|
|
</section>
|
|
<section><info><title>Native PKCS#11</title></info>
|
|
|
|
<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>
|
|
<section><info><title>Building SoftHSMv2</title></info>
|
|
|
|
<para>
|
|
SoftHSMv2, the latest development version of SoftHSM, is available
|
|
from
|
|
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/opendnssec/SoftHSMv2">
|
|
https://github.com/opendnssec/SoftHSMv2
|
|
</link>.
|
|
It is a software library developed by the OpenDNSSEC project
|
|
(<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.opendnssec.org">
|
|
http://www.opendnssec.org
|
|
</link>)
|
|
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>
|
|
</section>
|
|
</section>
|
|
<section><info><title>OpenSSL-based PKCS#11</title></info>
|
|
|
|
<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, 1.0.1 and 1.0.2 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 through 1.0.2.
|
|
</para>
|
|
<note><simpara>
|
|
The OpenSSL patches as of this writing (January 2016)
|
|
support versions 0.9.8zh, 1.0.0t, 1.0.1q and 1.0.2f.
|
|
ISC will provide updated patches as new versions of OpenSSL
|
|
are released. The version number in the following examples
|
|
is expected to change.
|
|
</simpara></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>
|
|
<section><info><title>Patching OpenSSL</title></info>
|
|
|
|
<screen>
|
|
$ <userinput>wget <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="">http://www.openssl.org/source/openssl-0.9.8zc.tar.gz</link></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><simpara>
|
|
The patch file may not be compatible with the
|
|
"patch" utility on all operating systems. You may need to
|
|
install GNU patch.
|
|
</simpara></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>
|
|
</section>
|
|
<section><info><title>Building OpenSSL for the AEP Keyper on Linux</title></info>
|
|
<!-- Example 1 -->
|
|
|
|
<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>
|
|
The Keyper library requires threads, so we
|
|
must specify -pthread.
|
|
</para>
|
|
<screen>
|
|
$ <userinput>cd openssl-0.9.8zc</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>". If "<command>make
|
|
test</command>" fails with "pthread_atfork() not found", you forgot to
|
|
add the -pthread above.
|
|
</para>
|
|
</section>
|
|
<section><info><title>Building OpenSSL for the SCA 6000 on Solaris</title></info>
|
|
<!-- Example 2 -->
|
|
|
|
<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>
|
|
</section>
|
|
<section><info><title>Building OpenSSL for SoftHSM</title></info>
|
|
<!-- Example 3 -->
|
|
|
|
<para>
|
|
SoftHSM (version 1) is a software library developed by the
|
|
OpenDNSSEC project
|
|
(<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.opendnssec.org">
|
|
http://www.opendnssec.org
|
|
</link>)
|
|
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>
|
|
</section>
|
|
<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>
|
|
<section><info><title>Configuring BIND 9 for Linux with the AEP Keyper</title></info>
|
|
<!-- Example 4 -->
|
|
|
|
<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 --enable-threads \
|
|
--with-openssl=/opt/pkcs11/usr \
|
|
--with-pkcs11=/opt/pkcs11/usr/lib/libpkcs11.so</userinput>
|
|
</screen>
|
|
</section>
|
|
<section><info><title>Configuring BIND 9 for Solaris with the SCA 6000</title></info>
|
|
<!-- Example 5 -->
|
|
|
|
<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>
|
|
</section>
|
|
<section><info><title>Configuring BIND 9 for SoftHSM</title></info>
|
|
<!-- Example 6 -->
|
|
|
|
<screen>
|
|
$ <userinput>cd ../bind9</userinput>
|
|
$ <userinput>./configure --enable-threads \
|
|
--with-openssl=/opt/pkcs11/usr \
|
|
--with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so</userinput>
|
|
</screen>
|
|
</section>
|
|
<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>
|
|
</section>
|
|
<section><info><title>PKCS#11 Tools</title></info>
|
|
|
|
<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>
|
|
</section>
|
|
<section><info><title>Using the HSM</title></info>
|
|
|
|
<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>
|
|
</section>
|
|
<section><info><title>Specifying the engine on the command line</title></info>
|
|
|
|
<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>
|
|
</section>
|
|
<section><info><title>Running named with automatic zone re-signing</title></info>
|
|
|
|
<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 <command>named</command> 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
|
|
<command>named</command>.
|
|
</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>
|
|
</section>
|
|
</section>
|