Expand description
§YubiHSM2
A Rust client library for Yubico’s YubiHSM 2 devices.
This project offers USB and HTTP backends for connecting with a YubiHSM2 device.
In addition, for testing purposes, an in-memory “mock HSM” can be used.
§Documentation
- https://docs.rs/yubihsm2/latest/yubihsm2/ for released versions of the crate
§Features
http: Communication with a (local or remote) device over HTTP (default).http-server: Functionality akin to the yubihsm-connector (HTTP only).mockhsm: Communication with an in-memory “mock” HSM. NOTE: Only use this for testing!passwords: Support for device reset and deriving authentication keys from a passphrase (default).secp256k1: For secp256k1 elliptic-curve cryptography (ECC) support.setup: Provisioning profile support (default).untested: For untested functionality of the library.usb: Communication with a local device over USB.
§Contributing
Please refer to the contributing guidelines to learn how to contribute to this project.
§Releases
Releases of yubihsm2 are created by the developers of this project.
OpenPGP certificates with the following OpenPGP fingerprints can be used to verify signed tags:
991F6E3F0765CF6295888586139B09DA5BF0D338(David Runge <dvzrv@archlinux.org>)653909A2F0E37C106F5FAF546C8857E0D8E8F074(Wiktor Kwapisiewicz <wiktor@archlinux.org>)
Some of the above are part of archlinux-keyring and certified by at least three main signing keys of the distribution. All certificate are cross-signed and can be retrieved from OpenPGP keyservers.
§Acknowledgements
This project is a fork of the yubihsm.rs project.
You can use yubihsm2 instead of yubihsm.rs by adding the following to your project’s Cargo.toml:
[dependencies]
yubihsm = { package = "yubihsm2", version = "0.43" }§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.
§Getting Started
Most crate functionality can be found in the Client type.
In order to connect to the HSM, you’ll need to make a Connector.
§Example
The following is an example of how to create a Client by connecting via USB, and then
performing an Ed25519 signature:
use yubihsm::{Client, Credentials, UsbConnector};
// Connect to the first YubiHSM 2 we detect
let connector = UsbConnector::default();
// Default auth key ID and password for YubiHSM 2
// NOTE: DON'T USE THIS IN PRODUCTION!
let credentials = Credentials::default();
// Connect to the HSM and authenticate with the given credentials
let mut hsm_client = Client::open(connector, credentials, true).unwrap();
// Note: You'll need to create this key first. Run the following from yubihsm-shell:
// `generate asymmetric 0 100 ed25519_test_key 1 asymmetric_sign_eddsa ed25519`
let signature = hsm_client.sign_ed25519(100, "Hello, world!").unwrap();
println!("Ed25519 signature: {:?}", signature);Re-exports§
pub use crate::connector::HttpConfig;pub use crate::algorithm::Algorithm;pub use crate::audit::AuditOption;pub use crate::authentication::Credentials;pub use crate::capability::Capability;pub use crate::client::Client;pub use crate::connector::Connector;pub use crate::domain::Domain;pub use crate::error::*;
Modules§
- algorithm
- Cryptographic algorithms supported by the YubiHSM 2
- asymmetric
- Asymmetric cryptography i.e. digital signatures and public-key encryption.
- attestation
- Attestation Certificates: generate an X.509 certificate which attests that a key generated with a YubiHSM is genuine
- audit
- Auditing options (for use with the
get_optionandput_optioncommand) - authentication
- YubiHSM 2 authentication functionality (i.e. credentials used to authenticate and establish a session with an HSM)
- capability
- Object attributes specifying which operations are allowed to be performed
- client
- YubiHSM client: core functionality of this crate.
- command
- YubiHSM commands: types and traits for modeling the commands supported by the HSM device, implemented in relevant modules.
- connector
- Methods of connecting to a YubiHSM 2:
- device
- HSM device-related functionality
- domain
- Logical partitions within the HSM, allowing several applications to share the device.
- ecdh
- Elliptic Curve Diffie Hellman Key Exchange.
- ecdsa
- Elliptic Curve Digital Signature Algorithm (ECDSA) support
- ed25519
- Ed25519 digital signature algorithm support
- error
- Error types
- hmac
- Hash-based Message Authentication Code (HMAC)
- object
- Objects within the
YubiHSM 2(keys, certificates, or other opaque data) - opaque
- Opaque object support: store arbitrary data in the HSM
- otp
- Yubico One Time Password (OTP) functionality
- response
- Responses to command sent from the HSM.
- rsa
- RSA (Rivest–Shamir–Adleman) asymmetric cryptosystem support (signing/encryption).
- session
- Authenticated/encrypted sessions with the HSM.
- setup
- Initial YubiHSM 2 setup functionality using declarative device profiles.
- ssh
- Secure Shell Certificate Authority Functionality
- symmetric
- Symmetric encryption support
- template
- Certificate templates.
- wrap
- “Wrapping” support: YubiHSM 2 key/object encryption for backups and importing existing keys to other derivces.
Structs§
- Uuid
- A Universally Unique Identifier (UUID).