Crate yubihsm[−][src]

yubihsm.rs: pure Rust client for YubiHSM2 hardware security modules

Prerequisites

This crate builds on Rust 1.27+ and by default uses SIMD features which require the following RUSTFLAGS:

RUSTFLAGS=-Ctarget-feature=+aes

You can configure your ~/.cargo/config to always pass these flags:

[build]
rustflags = ["-Ctarget-feature=+aes"]

Getting Started

The following documentation describes the most important parts of this crate's API:

Session: end-to-end encrypted connection with the YubiHSM. You'll need an active one to do anything.
commands: commands supported by the YubiHSM2 (i.e. main functionality)

The following is an example of how to create a Session by connecting to a yubihsm-connector process, and then performing an Ed25519 signature:

extern crate yubihsm;
use yubihsm::HttpSession;

// Default yubihsm-connector URI, auth key ID, and password for yubihsm-connector
// NOTE: DON'T USE THIS IN PRODUCTION!
let mut session =
    HttpSession::create(Default::default(), Default::default(), 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 = yubihsm::sign_ed25519(&mut session, 100, "Hello, world!").unwrap();
println!("Ed25519 signature: {:?}", signature);

Re-exports

pub use adapters::Adapter;

pub use algorithm::*;

pub use auth_key::AuthKey;

pub use auth_key::AUTH_KEY_SIZE;

pub use capabilities::Capability;

pub use commands::attest_asymmetric::*;

pub use commands::blink::*;

pub use commands::delete_object::*;

pub use commands::device_info::*;

pub use commands::echo::*;

pub use commands::export_wrapped::*;

pub use commands::generate_asymmetric_key::*;

pub use commands::generate_hmac_key::*;

pub use commands::generate_wrap_key::*;

pub use commands::get_logs::*;

pub use commands::get_object_info::*;

pub use commands::get_opaque::*;

pub use commands::get_pubkey::*;

pub use commands::hmac::*;

pub use commands::import_wrapped::*;

pub use commands::list_objects::*;

pub use commands::put_asymmetric_key::*;

pub use commands::put_auth_key::*;

pub use commands::put_hmac_key::*;

pub use commands::put_opaque::*;

pub use commands::put_otp_aead_key::*;

pub use commands::put_wrap_key::*;

pub use commands::reset::*;

pub use commands::set_log_index::*;

pub use commands::sign_ecdsa::*;

pub use commands::sign_eddsa::*;

pub use commands::storage_status::*;

pub use commands::unwrap_data::*;

pub use commands::verify_hmac::*;

pub use commands::wrap_data::*;

pub use commands::CommandType;

pub use commands::sign_rsa_pkcs1v15::*;

pub use commands::sign_rsa_pss::*;

pub use credentials::Credentials;

pub use domains::Domain;

pub use object::*;

pub use session::UsbSession;

pub use session::HttpSession;

pub use session::Session;

Modules

adapters	Adapters for connecting to the `YubiHSM2`
algorithm	Cryptographic algorithms supported by the `YubiHSM2`
auth_key	Authentication keys used to establish encrypted sessions with the `YubiHSM2` `YubiHSM2` authentication keys (2 * AES-128 symmetric PSK) from which session keys are derived
capabilities	Object attributes specifying which operations are allowed to be performed
commands	Commands supported by the `YubiHSM2`
credentials	Credentials used to authenticate to the `YubiHSM2` (key ID + `AuthKey`)
domains	Logical partitions within the `YubiHSM2`, allowing several applications to share the device
error	Error types
mockhsm	Software simulation of the `YubiHSM2` for integration testing
object	Objects stored in the `YubiHSM2`
session	`YubiHSM2` sessions: primary API for performing HSM operations

Structs

HttpAdapter	HTTP(-ish) adapter which supports the minimal parts of the protocol required to communicate with the yubihsm-connector service.
HttpConfig	Configuration options for the HTTP (i.e. `yubihsm-connector`) adapter
SerialNumber	YubiHSM serial numbers
SessionId	Session/Channel IDs
UsbAdapter	`libusb`-based adapter which communicates directly with the YubiHSM2
UsbDevices	A collection of detected YubiHSM 2 devices, represented as `HsmDevice`
UsbTimeout	Timeouts when performing USB operations
Uuid	A Universally Unique Identifier (UUID).

Type Definitions

SessionError

Session errors