[−][src]Crate yubihsm
yubihsm.rs: pure Rust client for YubiHSM 2 hardware security modules
Prerequisites
This crate builds on Rust 1.31+ and by default uses SIMD features
which require the following RUSTFLAGS:
RUSTFLAGS=-Ctarget-feature=+aes,+ssse3
You can configure your ~/.cargo/config to always pass these flags:
[build]
rustflags = ["-Ctarget-feature=+aes,+ssse3"]
Getting Started
The following documentation describes the most important parts of this crate's API:
- yubihsm::connector: methods of connecting to a YubiHSM (USB or HTTP via yubihsm-connector)
- yubihsm::Client: client providing wrappers for YubiHSM commands.
Example
The following is an example of how to create a yubihsm::Client by connecting via USB, and then performing an Ed25519 signature:
extern crate yubihsm;
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::mockhsm::MockHsm; |
pub use crate::algorithm::*; |
pub use crate::audit::AuditOption; |
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 (encryption/signatures) functionality |
| audit | Auditing options (for use with the |
| 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. |
| error | Error types |
| hmac | Hash-based Message Authentication Code (HMAC) |
| mockhsm | Simulation of the HSM for integration testing. |
| object | Objects within the |
| 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. |
| session | Authenticated/encrypted sessions with the HSM. |
| setup | Initial YubiHSM 2 setup functionality using declarative device profiles. |
| signatory | Signatory adapter: multi-provider digital signature library for Rust |
| template | SSH certificate templates |
| wrap | "Wrapping" support: YubiHSM 2 key/object encryption for backups and importing existing keys to other derivces. |
Structs
| Credentials | Credentials used to establish a session with the HSM |
| HttpConfig | Configuration options for the HTTP (i.e. |
| UsbConfig | Configuration for connecting to the YubiHSM via USB |
| Uuid | A Universally Unique Identifier (UUID). |
Enums
| DeviceErrorKind | Kinds of errors which originate in the HSM |
Constants
| AUTHENTICATION_KEY_SIZE | Auth keys are 2 * AES-128 keys |
Type Definitions
| ClientError | Session errors |
| ConnectionError |
|
| DeviceError | Errors which originate in the HSM |