Hardware Security Modules (HSMs)

Note

Cascade does not require a Hardware Security Module (HSM) to operate. While it is common practice to secure cryptographic key material using an HSM, not all operators use an HSM. Cascade is able to use OpenSSL and/or ring software cryptography to generate signing keys and to cryptographically sign DNS RRset data, storing the generated keys in on-disk files.

An Introduction to HSMs

A Hardware Security Module is typically a tamper proof hardware vault capable of generating and securely storing cryptographic keys and performing signing operations using those keys on data provided via an interface and returning the signed result via the same interface.

HSM Interfaces

In most cases, you interact with an HSM via an interface that is compliant with the Oasis PKCS#11 (Public-Key Cryptography Standard) specification. Some HSMs also or alternatively support a newer Oasis specification called KMIP (Key Management Interoperability Protocol).

KMIP is a data (de)serialization protocol that operates on top of the widely used TCP and TLS combination of protocols. As such, it requires no additional software or special configuration to use and poses no direct security or stability threat to the client process.

This is quite different to PKCS#11, which requires the HSM vendor to provide a library of code that offers a C language style interface to be used by the client at runtime by loading the library (a.k.a. module) into its own process with no knowledge of or control over what that code is going to do.

Cascade and HSMs

Cascade supports both PKCS#11 and KMIP compatible HSMs. KMIP is supported natively, while PKCS#11 is supported through our cascade-hsm-bridge.

Cascade is an application written in Rust. Crossing the divide between the Rust host application and a loaded C library means giving up the stability and memory safety guarantees offered by Rust. As such, Cascade was designed to not load PKCS#11 modules directly but instead to hand that risk off to a helper tool: cascade-hsm-bridge.

To interact with a HSM over its PKCS#11 interface, Cascade sends KMIP requests to cascade-hsm-bridge, which executes them against a loaded PKCS#11 vendor library.

Supported HSMs

In principle any HSM supporting PKCS#11 v2.40 or KMIP 1.2 should be supported. To work with an HSM using its PKCS#11 interface, Cascade requires our cascade-hsm-bridge.

Several HSMs have been tested with Cascade. Our testing was limited to normal usage only, not attempting to deliberately cause problems, and not attempting to stress or performance test the interface. The tested HSMs are:

Supported HSMs

HSM	Type	Interface	Integration guide
Fortanix DSM	Cloud	KMIP
Thales Cloud HSM	Cloud	PKCS#11	view
Nitrokey NetHSM [1]	Docker image	PKCS#11	view
YubiHSM 2	USB key	PKCS#11
SoftHSM v2.6.1	Software	PKCS#11	view
SmartCard-HSM	Smart Card	PKCS#11	view

[1]

Works with v1.7.2 of their PKCS#11 module. v2.0.0 and above are NOT currently supported due to a known bug in cascade-hsm-bridge.

Note

Cascade requires TLS 1.3 for connections to the KMIP server, even though KMIP 1.2 requires servers to offer support for old versions of the TLS protocol with known security vulnerabilities. For this reason, PyKMIP is NOT supported by Cascade as it only supports older vulnerable TLS versions.

Setting up cascade-hsm-bridge

If you installed Cascade via a DEB or RPM package you should also already have the cascade-hsm-bridge software installed, unless you explicitly opted not to install it. You can also build the software from source.

See also

We provide man pages for both the cascade-hsm-bridge daemon and configuration file.

When installed via a package the daemon will not be run automatically. This is because you will need to:

• Edit the cascade-hsm-bridge configuration file to set the location of your PKCS#11 module.

• Depending on your PKCS#11 module, you may need to set vendor specific environment variables for the cascade-hsm-bridge process. You may also need to ensure that vendor specific configuration files and possibly other software is installed and correctly configured.

• Ensure that the cascade-hsm-bridge user has access to the resources needed by the PKCS#11 module to be loaded.

• Use the (vendor specific) PKCS#11 module setup process to create a token label and PIN that Cascade should use to authenticate with the HSM.

• Optionally, generate a proper TLS certificate for use by cascade-hsm-bridge and set the cascade-hsm-bridge:cert_path and cascade-hsm-bridge:key_path in /etc/cascade-hsm-bridge/config.toml to point the certificate file and accompanying private key. If you omit these settings, cascade-hsm-bridge will generate a long-lived self-signed TLS certificate each time it starts.

Note

There is currently no way to test that the cascade-hsm-bridge configuration is correct other than trying to use it with Cascade.

When ready, start cascade-hsm-bridge either via systemd (if installed from a package) or directly:

cascade-hsm-bridge --config /etc/cascade-hsm-bridge/config.toml -d --user <USER> --group <GROUP>

Tip

Use the cascade-hsm-bridge:--user and cascade-hsm-bridge:--group arguments to make cascade-hsm-bridge run as the same user that has access to any necessary resources required by PKCS#11 module vendor.

Using cascade-hsm-bridge with Cascade

To use cascade-hsm-bridge with Cascade we must tell it that there is a HSM running that it can connect to. In the instructions below the PKCS#11 token label and PIN are the values you configured above.

cascade hsm add --insecure --username <PKCS#11 token label> --password <PKCS#11 PIN> cascade-hsm-bridge 127.0.0.1

Note

The --insecure option must be used if using a self-signed TLS certificate, which is the default. 127.0.0.1 should be changed if your cascade-hsm-bridge instance is running on a different address.

Cascade will verify that it can connect and that the target server appears to be a KMIP compatible HSM.

Note

Cascade does not yet verify that the target KMIP server supports the operations needed by Cascade. For cascade-hsm-bridge this isn’t a problem as it is designed to work with Cascade.

Next, we need to add the HSM to a policy so that when zones are added the keys for the zones will be generated using the HSM.

To do this, edit /etc/cascade/policies/<your_policy>.toml and set:

[key-manager.generation]
hsm-server-id = "cascade-hsm-bridge"

Now when you use cascade zone add --policy <your_policy> the HSM will be used for key generation and signing.