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::Session;

// Default yubihsm-connector URI, auth key ID, and password for yubihsm-connector
let mut session =
    Session::create_from_password(Default::default(), 1, b"password", 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 algorithm::*;

pub use auth_key::*;

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::generate_asymmetric_key;

pub use commands::generate_wrap_key::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::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::sign_ecdsa::*;

pub use commands::sign_eddsa::*;

pub use commands::storage_status::*;

pub use commands::unwrap_data::*;

pub use commands::wrap_data::*;

pub use commands::CommandType;

pub use connector::Connector;

pub use domains::Domain;

pub use object::*;

pub use session::Session;

Modules

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`
connector	Client for the `yubihsm-connector` service
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

HttpConfig	Configuration options for this connector
HttpConnector	HTTP(-ish) connector which supports the minimal parts of the protocol required to communicate with the yubihsm-connector service.
SessionId	Session/Channel IDs

Type Definitions

SessionError

Session errors