Integrating with SoftHSMv2

Note

The instructions on this page are for an Ubuntu 24.04 host and assume that Cascade has already been installed using our DEB package.

SoftHSM is an implementation of a cryptographic store accessible through a PKCS#11 interface. You can use it to explore PKCS#11 without having a Hardware Security Module. It was originally developed as a part of the OpenDNSSEC project, but is now a standalone project. SoftHSM uses Botan or OpenSSL for its cryptographic operations.

—https://www.softhsm.org/

Install SoftHSMv2

# apt install -y softhsm2
# softhsm2-util --init-token --label Cascade --pin 1234 --so-pin 1234 --free

Configure cascade-hsm-bridge

cascade-hsm-bridge needs to know where to find the SoftHSMv2 PKCS#11 module. As PKCS#11 modules are loaded into a host application, any access to resources needed by the PKCS#11 module must be granted to the host application. For SoftHSM that involves granting the user that cascade-hsm-bridge runs as read-write access to the /var/lib/softhsm directory. Let’s set this all up and start the daemon:

# sed -i -e 's|^lib_path = .\+|lib_path = "/usr/lib/softhsm/libsofthsm2.so"|' /etc/cascade-hsm-bridge/config.toml
# chown -R cascade-hsm-bridge: /var/lib/softhsm
# systemctl start cascade-hsm-bridge

Create a Cascade Policy that uses SoftHSM

Create a Cascade policy called softhsm and set it to use a HSM called cascade-hsm-bridge.

# cascade template policy | tee /etc/cascade/policies/softhsm.toml
# sed -i -e 's|^#hsm-server-id = .\+|hsm-server-id = "cascade-hsm-bridge"|' /etc/cascade/policies/softhsm.toml

Start the Cascade daemon:

# systemctl start cascaded
# cascade policy reload

Configure a HSM in Cascade called cascade-hsm-bridge that will connect to the locally running cascade-hsm-bridge daemon:

# cascade hsm add --insecure --username Cascade --password 1234 cascade-hsm-bridge 127.0.0.1
Added KMIP server 'cascade-hsm-bridge 0.1.0-alpha using PKCS#11 token with label Cascade in slot SoftHSM slot ID 0x1948bafd via library libsofthsm2.so'.

Sign a Test Zone with SoftHSM

Create a test zone to load and sign and ensure the Cascade daemon has access to it:

# mkdir /etc/cascade/zones
# cat > /etc/cascade/zones/example.com << EOF
example.com.    3600    IN      SOA     ns.example.com. username.example.com. 1 86400 7200 2419200 300
example.com.            IN      NS      ns
ns                      IN      A       192.0.2.1
EOF
# chown -R cascade: /etc/cascade/zones

Add our test zone to Cascade and associate the policy that we created with the zone:

# cascade zone add --source /etc/cascade/zones/example.com --policy softhsm example.com
Added zone example.com

Check that the zone has been signed, and print out additional information which includes the identifiers of the signing keys that were used:

# cascade zone status example.com --detailed
Status report for zone 'example.com' using policy 'softhsm'
✔ Waited for a new version of the example.com zone
✔ Loaded version 1
  Loaded at 2025-10-01T21:44:13+00:00 (1m 46s ago)
  Loaded 196 B from the filesystem in 0 seconds
✔ Auto approving signing of version 1, no checks enabled in policy.
✔ Approval received to sign version 1, signing requested
✔ Signed version 1 as version 2025100101
  Signed at 2025-10-01T21:44:13+00:00 (1m 45s ago)
  Signed 3 records in 0s
✔ Auto approving publication of version 2025100101, no checks enabled in policy.
✔ Published version 2025100101
  Published zone available on 127.0.0.1:4543
DNSSEC keys:
  KSK tagged 16598:
    Reference: kmip://cascade-hsm-bridge/keys/C9623EAF300AF8E4A3DF6D5F6AD6674B49CCD322_pub?algorithm=13&flags=257
    Actively used for signing
  ZSK tagged 50714:
    Reference: kmip://cascade-hsm-bridge/keys/3C95A4EC3A1E26BC67EC0336926ADBB212ADB3D8_pub?algorithm=13&flags=256
    Actively used for signing
...

Inspect the SoftHSM Key Store

Install the pkcs11-tool program from the opensc package and use it to query SoftHSMv2 directly:

# apt install -y opensc
# pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --token-label Cascade --so-pin 1234 -O
Public Key Object; EC  EC_POINT 256 bits
  EC_POINT:   04410489c96a67a451f26b75d0cbf903211d7d892e36c577a707e144a97309f20f47144a4bb1c5b437ac04fc1a2f44251253f69bd6d9d575cbe69b612e1d6fc2bf903d
  EC_PARAMS:  06082a8648ce3d030107 (OID 1.2.840.10045.3.1.7)
  label:      example.com-50714-zsk-pub
  ID:         3c95a4ec3a1e26bc67ec0336926adbb212adb3d8
  Usage:      verify, verifyRecover
  Access:     local
Public Key Object; EC  EC_POINT 256 bits
  EC_POINT:   0441041517afa18dcf0eb9aec58de3bd54585e152e634ee332c4d73c587e4fb2ebded9432be24cd4ea34f34290ffbd5f27a1ef1cfaa82662e8ebaf236c23896f19dfb2
  EC_PARAMS:  06082a8648ce3d030107 (OID 1.2.840.10045.3.1.7)
  label:      example.com-16598-ksk-pub
  ID:         c9623eaf300af8e4a3df6d5f6ad6674b49ccd322
  Usage:      verify, verifyRecover
  Access:     local

Notice that the key IDs stored in SoftHSMv2 match those reported by Cascade.

End.