[−][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

Most crate functionality can be found in the Client type:

yubihsm::Client: main API for all YubiHSM functionality! Start here!

In order to connect to the HSM, you'll need to make a yubihsm::Connector.

Example

The following is an example of how to create a yubihsm::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::algorithm::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 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_option` and `put_option` command)
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.
ecdsa	Elliptic Curve Digital Signature Algorithm (ECDSA) support
ed25519	Ed25519 digital signature algorithm support
error	Error types
hmac	Hash-based Message Authentication Code (HMAC)
kex	Key exchange support
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.
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. `yubihsm-connector`) connection
UsbConfig	Configuration for connecting to the YubiHSM via USB
Uuid	A Universally Unique Identifier (UUID).