Generate keys, sign data and manage objects on a YubiHSM 2 net
Drive a YubiHSM 2 from a cargo test: generate a key, sign data with it, and manage the
objects on the device. It requires box software 0.59.0 or later.
Handle
use lager::LagerBox;let lager = LagerBox::from_env()?;let hsm = lager.hsm("hsm1");
Methods
Method
Description
name()
The net name this handle addresses
info()
Firmware, serial number, audit-log use and supported algorithms
blink()
Blink the LED, to find the device on the bench
objects()
List the objects that the authentication key can see
generate()
Generate an asymmetric key on the device
public_key()
Read a stored key’s public key, as PEM
sign()
Sign data with a stored key
delete()
Delete an object
reset()
Factory-reset the device
Login
Every method except info() logs in with an authentication key. Give the key and its
password in an HsmAuth:
use lager::HsmAuth;let auth = HsmAuth::new(std::env::var("HSM_PASSWORD").expect("HSM_PASSWORD"));let other = HsmAuth::with_key(2, "another-password");
HsmAuth::new uses authentication key 1, the factory key. The Debug output of an
HsmAuth leaves out the password, so it cannot reach a test log through {:?}.
If the network between your computer and the box is not trusted, reach the box only
through Tailscale or an SSH tunnel. The crate sends the password to the box API over
plain HTTP, the same as all other box API traffic. The box removes the password from
its logs.
The factory login is authentication key 1 with the password password. Replace that
key before you put keys on the HSM that matter.
Types
GenerateKey
pub struct GenerateKey { pub algorithm: String, // "ec-p256", "ec-p384", "ec-p521", "ec-k256", "ed25519" pub object_id: u16, // 0 lets the HSM pick one pub label: String, pub domains: Vec<u8>, // 1-16; empty means domain 1 pub capabilities: Vec<String>, // empty means the defaults for the algorithm}
GenerateKey::new(algorithm) sets every other field to its default.
HsmObject
Each object from objects() carries id, object_type, label, algorithm,
domains, capabilities, size and sequence.
Returns:GeneratedKey, with the key’s id and its public_key_pem.The box refuses RSA generation, because it can take minutes. To make an RSA key, use
the Python API.
Sign data with a stored key, and return the signature bytes. The HSM hashes the data
for the ECDSA and RSA mechanisms, so pass the message itself, not a digest of it.
let signature = hsm.sign(&auth, key.id, b"message to sign", "ecdsa-sha256")?;
List the objects that the authentication key can see. Pass a type or a label to
filter the list. The types are asymmetric-key, authentication-key, opaque,
wrap-key, hmac-key, template and otp-aead-key.
Delete an object. object_type defaults to asymmetric-key.
reset(auth: &HsmAuth) -> Result<()>
reset() deletes every key and object on the device, and you cannot undo it. The
device reboots and keeps only the factory login. Call it only on an HSM that holds no
key you need.