Installation

This guide shows how to integrate the Knot DNS server with a Securosys Primus HSM or CloudHSM.

Prerequisites

• A Securosys Primus HSM or CloudHSM.
• A server to deploy Knot DNS on.

Step 1: Install Knot DNS

Follow the Knot DNS documentation to install Knot DNS.

Step 2: Install the Primus PKCS#11 Provider

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

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

sudo usermod -aG primus knot

To test basic connectivity:

$ sudo -u knot /usr/local/primus/bin/ppin --test

Load config file: '/etc/primus/primus.cfg'

hsm0: Connect to 'ch01-api.cloudshsm.com' on port 2310 with priority , firmware: RE-3.2.9
    slot0 (id=0), user='MY-PARTITION': OK

Number of tested HSMs: 1 (number of partitions: 1)
Number of failures: 0

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

Step 3: Add a Keystore to Knot DNS

Edit the Knot DNS config file to add a keystore section. This tells Knot DNS where to find the PKCS#11 Provider.

Open the file for editing:

sudo nano /etc/knot/knot.conf

Add the following section. Replace ${PARTITION_NAME} and ${PKCS11_PASSWORD} with your specific values.

keystore:
  - id: primus
    backend: pkcs11
    config: "pkcs11:token=${PARTITION_NAME};pin-value=${PKCS11_PASSWORD} /usr/local/primus/lib/libprimusP11.so"

Save your edits to the config file.

Step 4: Testing

Knot DNS provides a dedicated subcommand for testing HSM connectivity.

$ sudo -u knot keymgr primus keystore-test

Keystore id 'primus', type PKCS #11

Algorithm             Generate    Import    Remove       Use
RSASHA256 1024b            yes       yes       yes       yes
RSASHA256 2048b            yes       yes       yes       yes
RSASHA256 4096b            yes       yes       yes       yes
RSASHA512 1024b            yes       yes       yes       yes
RSASHA512 2048b            yes       yes       yes       yes
RSASHA512 4096b            yes       yes       yes       yes
ECDSAP256SHA256 256b       yes       yes       yes       yes
ECDSAP384SHA384 384b       yes       yes       yes       yes
ED25519 256b               yes       yes       yes       yes
ED448 456b                 yes       yes       yes       yes

info

When key import is disabled in the Security Configuration of the HSM, the import column shows "no" for all rows.

In earlier versions of the Primus HSM firmware, the RSA import shows "no" when Key Invalidation is enabled (which is the default in CloudHSM). This is fixed in firmware version 3.2.11 and 3.3.2.

Step 5: Add DNSSEC to a Zone

Create a DNS zone for a domain, for example for securosys.example.com.

To enable DNSSEC for this zone, you have to:

• Define a DNSSEC policy. You can fine-tune this, for example, to choose the algorithm (RSA, EC, Ed), key sizes, and key lifetimes.
• Enable dnssec-signing for your zone.

keystore:
  - id: primus
    backend: pkcs11
    config: "pkcs11:token=${PARTITION_NAME};pin-value=${PKCS11_PASSWORD} /usr/local/primus/lib/libprimusP11.so"

policy:
  - id: custom_policy
    keystore: primus
    manual: off

zone:
  - domain: securosys.example.com
    dnssec-signing: on
    dnssec-policy: custom_policy

This example uses automatic key management. If you prefer manual key management, set manual: on. In manual mode you need to create the respective keys yourself, for example with the keymgr tool provided by Knot DNS.

Then reload Knot DNS and check the logs for errors:

sudo -u knot knotc reload

journalctl -u knot

To list the keys for a zone:

$ sudo -u knot keymgr securosys.example.com list

dbd0ee65eaa8d80331a936910d37bbdae13cfdec 57015 KSK ECDSAP256SHA256 created=1766056629 publish=1766056629 ready=1766056629
a97dac3d2d9383d05778e743ee8dd25847ff1a71 26814 ZSK ECDSAP256SHA256 created=1766057205 publish=1766057205 active=1766057217

The first values (dbd0ee... and a97dac...) are the key labels. Use these when you want to list keys on the HSM, for example with pkcs11-tool. The second values (57015, 26814) are the key tags, as defined by DNSSEC.

Generally, see keymgr --help for the various key management commands that Knot DNS offers to manage DNSSEC.

Next Steps

Follow the Knot DNS documentation for more information about operating Knot DNS.