The PKCS#11 support in BIND 9 comes in two flavors:
The native PKCS#11 that interfaces directly with the HSM provided library via
PKCS#11 API. This allows BIND 9 to interact directly with the PKCS#11
provider for the public key cryptography (DNSSEC).
The OpenSSL-based PKCS#11 interfaces with the PKCS#11 provider indirectly via
pkcs11 engine provided by the OpenSC project.
This page describes the second method as it is more universal and doesn't
require BIND 9 to be recompiled.
engine_pkcs11 tries to fit the PKCS#11 API within the engine API of OpenSSL.
That is, it provides a gateway between PKCS#11 modules and the OpenSSL engine
API. One has to register the engine with OpenSSL and one has to provide the
path to the PKCS#11 module which should be gatewayed to. This can be done by
editing the OpenSSL configuration file, by engine specific controls, or by using
the p11-kit proxy module.
In this document, we'll describe how to compile, install and configure
engine_pkcs11 to be used with BIND 9. For simplicity, we use SoftHSM2 as a
We'll assume that the installation path for BIND 9 is /opt/bind9.
SoftHSM2 can be either installed as a package or
installed from the source. The installation from the source is beyond the scope
of this document. On DEB-based Linux distributions, the package is called
softhsm2, on RPM-based Linux distributions, the package is called just
The engines_pkcs11 module has be merged into
libp11 library. To use engines_pkcs11 with
BIND 9, you either need libp11 (>= 0.4.11 to be released before end of January 2020) which contains necessary fixes and
hasn't been released yet, or use the version from the master branch of the
upstream repository. In this document, we'll show you how to use the most
current version of the engines_pkcs11. We assume that you have a working build
environment for BIND 9 and git installed.
Clone current version of libp11 sources:
git clone https://github.com/OpenSC/libp11.git
Bootstrap and compile:
cd libp11./bootstrap./configure --with-enginesdir=/opt/bind9/engines
After the compilation successfully finished, install the engines_pkcs11:
You should customize the pin, so-pin and label values, but please make
sure you use correct values when copying the examples below.
Configuring OpenSSL to use engine_pkcs11
The canonical documentation for configuring engine_pkcs11 is in the
but here's copy of working configuration with SoftHSM2 for your convenience:
We are going to use our own custom copy of OpenSSL configuration, again it's
driven by an environment variable, this time called OPENSSL_CONF. We are
going to copy the global OpenSSL configuration (often found in
etc/ssl/openssl.conf) and customize it to use engines_pkcs11.
Remember that each key should have unique label and we are going to use that
label to reference the private key.
Convert the RSA keys stored in the HSM into a format that BIND 9 understands.
The dnssec-keyfromlabel tool from BIND 9 can link the raw keys stored in
the HSM with the K<zone>+<alg>+<id> files. You'll need to provide the
OpenSSL engine name (pkcs11), the algorithm (RSASHA256) and the PKCS#11
label that specify the token (we initialized it as bind9), the name of the
PKCS#11 object (called label when generating the keys using pkcs11-tool)
and the HSM PIN.
dnssec-keyfromlabel -E pkcs11 -a RSASHA256 -l "token=bind9;object=example.net-ksk;pin-value=0000" -f KSK example.net
dnssec-keyfromlabel -E pkcs11 -a RSASHA256 -l "token=bind9;object=example.net-zsk;pin-value=0000" example.net
NOTE: you can use PIN stored on disk, by specifying pin-source=<path_to>/<file>, f.e.:
Fetching example.net/RSASHA256/31729 (KSK) from key repository.Fetching example.net/RSASHA256/42231 (ZSK) from key repository.Verifying the zone using the following algorithms: RSASHA256.Zone fully signed:Algorithm: RSASHA256: KSKs: 1 active, 0 stand-by, 0 revoked ZSKs: 1 active, 0 stand-by, 0 revokedexample.db.signed