Crate signstar_yubihsm2

Expand description

§Signstar YubiHSM2

Integration for YubiHSM2 devices as Signstar backend.

This library contains a small, safe subset of primitives used by Signstar. For example: YubiHSM2 allows exporting raw secret keys while in Signstar we would always export them under wrap (encrypted). Additionally, this library provides strong types for expressing object capabilities and identity.

To ease deployment and provisioning of a YubiHSM2 backend a command-line interface to execute deployment scenarios is included.

§Documentation

https://signstar.archlinux.page/rustdoc/signstar_yubihsm2/ for development version of the crate
https://docs.rs/signstar_yubihsm2/latest/signstar_yubihsm2/ for released versions of the crate

§Examples

§CLI

Reset the device to factory settings (erasing all key material) and get the HSM info:

echo $PWD
signstar-yubihsm scenario run "tests/scenarios/reset.json" | jq --compact-output

Adding new authentication key:

signstar-yubihsm scenario run "tests/scenarios/add-auth.json" | jq --compact-output

Generating key:

signstar-yubihsm scenario run "tests/scenarios/gen-key.json" | jq --compact-output

Signing using ed25519 keys:

signstar-yubihsm scenario run "tests/scenarios/raw-sign.json" | jq --compact-output

Exporting key under wrap:

signstar-yubihsm scenario run "tests/scenarios/wrapping/export-wrapped.json" | jq --compact-output

Import previously wrapped key and using it for signing:

signstar-yubihsm scenario run "tests/scenarios/wrapping/import-wrapped.json" | jq --compact-output

Enable forced auditing of signing and retrieving log:

signstar-yubihsm scenario run "tests/scenarios/audit.json" | jq --compact-output

§Features

_yubihsm2-mockhsm: Test environment and integration using a virtual YubiHSM2. NOTE: Unless you are developing this crate, you will very likely not want to use this feature. WARNING: This feature requires building in debug mode (see signstar#288)!
cli: Enables command line interface for executing scenario files
serde: Serialization and deserialization of objects using serde.

§Contributing

Please refer to the contributing guidelines to learn how to contribute to this project.

§License

This project may be used under the terms of the Apache-2.0 or MIT license.

Changes to this project - unless stated otherwise - automatically fall under the terms of both of the aforementioned licenses.

Modules§

automation: Provides utilities for YubiHSM automation.
backup: Utilities for parsing and creating YubiHSM2 wrap files.
connection 🔒
error 🔒: Error handling.
object: Types for describing objects stored on a YubiHSM2.
signer 🔒: Signing data with YubiHSM.
user 🔒: User handling for YubiHSM2 devices.
yubihsm: Re-exports of the upstream yubihsm library.

Structs§

Credentials: Credentials for a YubiHSM2 device.
YubiHsm2SigningKey: A signing key stored in the YubiHSM.

Enums§

Connection: A connection to a YubiHSM2.
Error: The error that may occur when using a YubiHSM2 device.