Skip to main content

Installation

This guide shows how to integrate BIND with a Securosys Primus HSM or CloudHSM, to delegate DNSSEC key generation and signing to the HSM.

info
  1. This guide assumes that you are familiar with BIND administration. Please read the BIND documentation to learn more about BIND. In particular, please see the DNSSEC chapter and the DNSSEC guide.
  2. This guide shows the steps for automated signing. In automated signing, BIND creates the keys on the HSM and takes care of rollovers. Manual signing is an advanced topic and is not recommended.
  3. This guide is written for Debian-based systems using the distribution-provided packages. Commands and file paths differ on other distributions and for manual installations.

Prerequisites​

  • A Securosys Primus HSM or CloudHSM
  • A server with: BIND 9.20 or later, OpenSSL 3 or later
    • Older BIND releases don't support PKCS#11 URIs in the dnssec-policy config field, and thus don't support automated key management via PKCS#11.

This guide was tested on Debian 13 with BIND 9.20.29, OpenSSL 3.5.7, pkcs11-provider 1.0, Primus PKCS#11 Provider 2.9.3-bind.

warning

Primus PKCS#11 Provider 2.9.3-bind is not yet publicly released. Please contact us if you are interested in testing BIND with Primus HSM.

Supported Algorithms​

The following algorithms were tested to work with BIND 9.20.29 and Primus HSM: RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384.

Ed25519 and Ed448 require BIND 9.21.23 or later.

Step 1: Install BIND​

Follow the BIND documentation to install BIND.

Many Linux distributions package BIND. For example, to install BIND on Debian:

sudo apt install bind9

Step 2: Install the Primus PKCS#11 Provider​

Install the Primus PKCS#11 Provider on the same machine as BIND.

Next, add the bind user (which the BIND install from the Debian package created) to the primus group (which the PKCS#11 Provider install created). This ensures that BIND can access the PKCS#11 Provider. For example, on Debian-based systems:

sudo usermod -aG primus bind

On other Linux distributions, or if you installed BIND differently, the bind user may have a different name.

If it fails, follow the PKCS#11 Provider troubleshooting steps.

Step 3: Configure OpenSSL pkcs11-provider​

Configure OpenSSL to integrate with the Primus PKCS#11 Provider through the OpenSSL pkcs11-provider. This requires OpenSSL 3 or later.

Create BIND-specific OpenSSL Config​

To avoid polluting the system-wide OpenSSL installation, it is recommended to create a BIND-specific OpenSSL config.

Start by copying the default config to the BIND directory:

sudo cp /etc/ssl/openssl.cnf /etc/bind/openssl.cnf

Proceed to edit the /etc/bind/openssl.cnf as described in the OpenSSL 3 guide. Point it to libprimusP11.so and configure it with your token label. Do not include this file in the global /etc/ssl/openssl.cnf.

Verify that the configuration can access the PKCS#11 provider:

OPENSSL_CONF=/etc/bind/openssl.cnf openssl list -providers

The output should list the PKCS#11 provider:

Providers:
base
name: OpenSSL Base Provider
version: 3.5.7
status: active
default
name: OpenSSL Default Provider
version: 3.5.7
status: active
pkcs11
name: PKCS#11 Provider
version: 3.5.0

If it fails, follow the OpenSSL troubleshooting steps.

Check that BIND runs with this config file:

# Basic check
sudo -u bind OPENSSL_CONF=/etc/bind/openssl.cnf named -v

# Proper server run
sudo -u bind OPENSSL_CONF=/etc/bind/openssl.cnf named -g -u bind

Configure BIND service with custom OpenSSL config​

Finally, set the OPENSSL_CONF environment variable for BIND to point to your custom config file.

The details of this depend on how you are running BIND. For example, in Debian's systemd-based install of BIND, you can inspect the service definition to find the environment file location:

systemctl show bind9.service | grep Environment

In a Debian package based install, this returns:

EnvironmentFiles=/etc/default/named

Therefore, edit the file:

sudo nano /etc/default/named

And add this line:

OPENSSL_CONF=/etc/bind/openssl.cnf

Afterwards, restart the service to have it pick up the new environment variable:

sudo systemctl restart bind9.service

Step 4: Configure BIND​

In this step, you will configure named to use Primus HSM through OpenSSL pkcs11-provider.

Create a zone file​

Create a zone file for a test zone. For example, you can use this example and save the contents to /var/lib/bind/example.com.

sudo nano /var/lib/bind/example.com

Configure named.conf​

Add the zone to the named.conf and configure it with a dnssec-policy and a key-store.

Edit the configuration file:

sudo nano /etc/bind/named.conf.local

Add the following content:

zone "example.com" {
type primary;
file "/var/lib/bind/example.com";
dnssec-policy "custom";
};

dnssec-policy "custom" {
keys {
ksk key-store "primus-hsm" lifetime 365d algorithm ecdsap384sha384;
zsk key-store "primus-hsm" lifetime 60d algorithm ecdsap384sha384;
};
};

key-store "primus-hsm" {
directory "/var/cache/bind";
pkcs11-uri "pkcs11:token=PARTITION_NAME?pin-source=file:/etc/bind/p11password.txt";
};

Replace the PARTITION_NAME with the value for your HSM Partition.
The directory is needed because named uses it to store files that contain references to HSM objects.

Create a file for the PKCS#11 Password. Edit it to contain your PKCS#11 Password on a single line, and nothing else (no trailing newline).

sudo install -m 640 -o root -g bind /dev/null /etc/bind/p11password.txt
sudo nano /etc/bind/p11password.txt
warning

Make sure that the file permissions are set so that only the root user can read/write it, the bind group can read it, and others are denied access.

Finally, reload the named configuration:

rndc reload

BIND should pick up your dnssec-policy, triggering it to automatically generate keys on the HSM and use them to sign the configured zones.

Step 5: Check that it worked​

You can use the rndc utility to inspect the status of your zones:

$ rndc dnssec -status example.com
dnssec-policy: custom
current time: Wed Nov 11 10:57:33 2026

key: 56763 (ECDSAP256SHA256), ZSK
published: yes - since Tue Nov 10 16:51:34 2026
zone signing: yes - since Tue Nov 10 16:51:34 2026

Next rollover scheduled on Sat Jan 9 14:46:34 2027
- goal: omnipresent
- dnskey: omnipresent
- zone rrsig: rumoured

key: 60650 (ECDSAP256SHA256), KSK
published: yes - since Tue Nov 10 16:51:34 2026
key signing: yes - since Tue Nov 10 16:51:34 2026

Next rollover scheduled on Wed Nov 10 14:46:34 2027
- goal: omnipresent
- dnskey: omnipresent
- ds: hidden
- key rrsig: omnipresent

You can inspect the /var/cache/bind/ directory for the key files that BIND has created:

$ ls /var/cache/bind/
Kexample.com.+013+48194.key Kexample.com.+013+48194.private Kexample.com.+013+48194.state Kexample.com.+013+50586.key Kexample.com.+013+50586.private Kexample.com.+013+50586.state managed-keys.bind managed-keys.bind.jnl

Inspect a private key file:

$ sudo cat /var/cache/bind/Kexample.com.+013+48194.private
Private-key-format: v1.3
Algorithm: 13 (ECDSAP256SHA256)
Label: cGtjczExOnRva2VuPVBBUlRJVElPTl9OQU1FP3Bpbi1zb3VyY2U9ZmlsZTovZXRjL2JpbmQvcDExcGFzc3dvcmQudHh0O29iamVjdD1leGFtcGxlLmNvbS4tY3VzdG9tLi16c2stMjAyNjExMTAxNDU0MTA5MTc=
Created: 20261110145410
Publish: 20261110145410
Activate: 20261110145410
Inactive: 20270109145410
Delete: 20270119155910

If you base64-decode the label, you can see that it contains a PKCS#11 URI reference:

pkcs11:token=PARTITION_NAME?pin-source=file:/etc/bind/p11password.txt;object=example.com.-custom.-zsk-20261110145410917

This gives you the key label on the HSM (here: example.com.-custom.-zsk-20261110145410917).

Step 6: Update parent zone​

Work with the parent zone to get your DNSSEC keys included there as DS or DNSKEY records.

Get startedwith CloudHSM.
Other questions?Ask Sales.
Feedback
Need help?