1 files changed, 287 insertions, 0 deletions
diff --git a/doc/arm/pkcs11.rst b/doc/arm/pkcs11.rst
new file mode 100644
index 0000000..bce9ef6
--- /dev/null
+++ b/doc/arm/pkcs11.rst
@@ -0,0 +1,287 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. 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.
+
+.. _pkcs11:
+
+PKCS#11 (Cryptoki) Support
+--------------------------
+
+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.
+
+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.
+
+PKCS#11 uses 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.
+
+There are two available mechanisms for PKCS#11 support in BIND 9:
+OpenSSL-based PKCS#11 and native PKCS#11. With OpenSSL-based PKCS#11,
+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. Native PKCS#11 enables BIND to bypass OpenSSL completely;
+BIND loads the provider library itself, and uses the PKCS#11 API to
+drive the HSM directly.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+See the documentation provided by the HSM vendor for information about
+installing, initializing, testing, and troubleshooting the HSM.
+
+Native PKCS#11
+~~~~~~~~~~~~~~
+
+Native PKCS#11 mode only works with an HSM capable of carrying out
+*every* 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.)
+
+To build BIND with native PKCS#11, configure it as follows:
+
+::
+
+   $ cd bind9
+   $ ./configure --enable-native-pkcs11 \
+       --with-pkcs11=provider-library-path
+
+
+This causes all BIND tools, including ``named`` and the ``dnssec-*``
+and ``pkcs11-*`` tools, to use the PKCS#11 provider library specified in
+provider-library-path for cryptography. (The provider library path can
+be overridden using the ``-E`` argument in ``named`` and the ``dnssec-*`` tools,
+or the ``-m`` argument in the ``pkcs11-*`` tools.)
+
+Building SoftHSMv2
+^^^^^^^^^^^^^^^^^^
+
+SoftHSMv2, the latest development version of SoftHSM, is available from
+https://github.com/opendnssec/SoftHSMv2. It is a software library
+developed by the OpenDNSSEC project (https://www.opendnssec.org) which
+provides a PKCS#11 interface to a virtual HSM, implemented in the form
+of an SQLite3 database on the local filesystem. It provides less security
+than a true HSM, but it allows users 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.
+
+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
+   $  make
+   $  make install
+   $  /opt/pkcs11/usr/bin/softhsm-util --init-token 0 --slot 0 --label softhsmv2
+
+
+OpenSSL-based PKCS#11
+~~~~~~~~~~~~~~~~~~~~~
+
+OpenSSL-based PKCS#11 uses engine_pkcs11 OpenSSL engine from libp11 project.
+
+For more information, see https://gitlab.isc.org/isc-projects/bind9/-/wikis/BIND-9-PKCS11
+
+PKCS#11 Tools
+~~~~~~~~~~~~~
+
+BIND 9 includes a minimal set of tools to operate the HSM, including
+``pkcs11-keygen`` to generate a new key pair within the HSM,
+``pkcs11-list`` to list objects currently available, ``pkcs11-destroy``
+to remove objects, and ``pkcs11-tokens`` to list available tokens.
+
+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, the tools are
+built but the provider is left undefined. Use the ``-m`` option or the
+``PKCS11_PROVIDER`` environment variable to specify the path to the
+provider.)
+
+Using the HSM
+~~~~~~~~~~~~~
+
+For OpenSSL-based PKCS#11, the runtime environment must first be set up
+so the OpenSSL and PKCS#11 libraries can be loaded:
+
+::
+
+   $ export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}
+
+This causes ``named`` and other binaries to load the OpenSSL library
+from ``/opt/pkcs11/usr/lib``, rather than from the default location. This
+step is not necessary when using native PKCS#11.
+
+Some HSMs require other environment variables to be set. For example,
+when operating an AEP Keyper, the location of
+the "machine" file, which stores information about the Keyper for use by
+the provider library, must be specified. If the machine file is in
+``/opt/Keyper/PKCS11Provider/machine``, use:
+
+::
+
+   $ export KEYPER_LIBRARY_PATH=/opt/Keyper/PKCS11Provider
+
+Such environment variables must be set when running any tool that
+uses the HSM, including ``pkcs11-keygen``, ``pkcs11-list``,
+``pkcs11-destroy``, ``dnssec-keyfromlabel``, ``dnssec-signzone``,
+``dnssec-keygen``, and ``named``.
+
+HSM keys can now be created and used. In this case, we will create
+a 2048-bit key and give it the label "sample-ksk":
+
+::
+
+   $ pkcs11-keygen -b 2048 -l sample-ksk
+
+To confirm that the key exists:
+
+::
+
+   $ pkcs11-list
+   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]
+
+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
+are using the HSM key "sample-ksk" as the key-signing key for
+"example.net":
+
+::
+
+   $ dnssec-keyfromlabel -l sample-ksk -f KSK example.net
+
+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 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.
+
+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:
+
+::
+
+   $ pkcs11-keygen -b 1024 -l sample-zsk
+   $ dnssec-keyfromlabel -l sample-zsk example.net
+
+Alternatively, a conventional on-disk key can be generated
+using ``dnssec-keygen``:
+
+::
+
+   $ dnssec-keygen example.net
+
+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 desired, 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 are done by the HSM.)
+
+Now the zone can be signed. Please note that, if the -S option is not used for
+``dnssec-signzone``, the contents of both
+``K*.key`` files must be added to the zone master file before signing it.
+
+::
+
+   $ dnssec-signzone -S example.net
+   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
+
+Specifying the Engine on the Command Line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When using OpenSSL-based PKCS#11, the "engine" to be used by OpenSSL can
+be specified in ``named`` and all of the BIND ``dnssec-*`` 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 is generally not necessary unless
+a different OpenSSL engine is used.
+
+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:
+
+::
+
+   $ dnssec-signzone -E '' -S example.net
+
+This causes ``dnssec-signzone`` to run as if it were compiled without
+the ``--with-pkcs11`` option.
+
+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.
+
+Running ``named`` With Automatic Zone Re-signing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For ``named`` to dynamically re-sign zones using HSM keys,
+and/or to sign new records inserted via nsupdate, ``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, ``/opt/pkcs11/usr/ssl/openssl.cnf``).
+
+The location of the openssl.cnf file can be overridden by setting the
+``OPENSSL_CONF`` environment variable before running ``named``.
+
+Here is a sample ``openssl.cnf``:
+
+::
+
+       openssl_conf = openssl_def
+       [ openssl_def ]
+       engines = engine_section
+       [ engine_section ]
+       pkcs11 = pkcs11_section
+       [ pkcs11_section ]
+       PIN = <PLACE PIN HERE>
+
+This also allows the ``dnssec-\*`` tools to access the HSM without PIN
+entry. (The ``pkcs11-\*`` tools access the HSM directly, not via OpenSSL, so
+a PIN is still required to use them.)
+
+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``, then the PIN would
+be read from the file ``/etc/hsmpin``.
+
+.. warning::
+
+   Placing the HSM's PIN in a text file in this manner may reduce the
+   security advantage of using an HSM. Use caution
+   when configuring the system in this way.