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:

Adapters: methods of connecting to a YubiHSM (USB or HTTP via yubihsm-connector)
Session: end-to-end encrypted connection with the YubiHSM. You'll need an active one to do anything.
commands: commands supported by the YubiHSM (i.e. main functionality)

Example

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 adapter::Adapter;

pub use algorithm::*;

pub use auth_key::AuthKey;

pub use auth_key::AUTH_KEY_SIZE;

pub use capability::Capability;

pub use command::attest_asymmetric::*;

pub use command::blink::*;

pub use command::delete_object::*;

pub use command::device_info::*;

pub use command::echo::*;

pub use command::export_wrapped::*;

pub use command::generate_asymmetric_key::*;

pub use command::generate_hmac_key::*;

pub use command::generate_wrap_key::*;

pub use command::get_logs::*;

pub use command::get_object_info::*;

pub use command::get_opaque::*;

pub use command::get_option::*;

pub use command::get_pseudo_random::*;

pub use command::get_pubkey::*;

pub use command::hmac::*;

pub use command::import_wrapped::*;

pub use command::list_objects::*;

pub use command::put_asymmetric_key::*;

pub use command::put_auth_key::*;

pub use command::put_hmac_key::*;

pub use command::put_opaque::*;

pub use command::put_option::*;

pub use command::put_otp_aead_key::*;

pub use command::put_wrap_key::*;

pub use command::reset::*;

pub use command::set_log_index::*;

pub use command::sign_ecdsa::*;

pub use command::sign_eddsa::*;

pub use command::storage_status::*;

pub use command::unwrap_data::*;

pub use command::verify_hmac::*;

pub use command::wrap_data::*;

pub use command::CommandType;

pub use command::sign_rsa_pkcs1v15::*;

pub use command::sign_rsa_pss::*;

pub use credentials::Credentials;

pub use domain::Domain;

pub use error::*;

pub use mockhsm::MockSession;

pub use object::*;

pub use response::ResponseCode;

pub use session::HttpSession;

pub use session::UsbSession;

pub use session::Session;

pub use wrap::WrapMessage;

pub use wrap::WrapNonce;

Modules

adapter	Adapters for connecting to the HSM. There are two main adapters supported:
algorithm	Cryptographic algorithms supported by the HSM
auth_key	Authentication keys used to establish encrypted sessions with the HSM `YubiHSM2` authentication keys (2 * AES-128 symmetric PSK) from which session keys are derived
capability	Object attributes specifying which operations are allowed to be performed
command	Commands supported by the HSM
credentials	Credentials used to authenticate to the HSM (key ID + `AuthKey`)
domain	Logical partitions within the HSM, allowing several applications to share the device
error	Error types
mockhsm	Software simulation of the HSM for integration testing
object	Objects stored in the HSM
response	Responses to command sent from the HSM
session	Encrypted sessions with the HSM
wrap	Object wrapping support, i.e. encrypt objects from one HSM to another

Structs

HttpAdapter	Adapter for `yubihsm-connector` which communicates using HTTP.
HttpConfig	Configuration options for the HTTP (i.e. `yubihsm-connector`) adapter
MockAdapter	A mocked connection to the MockHsm
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).

Enums

AuditOption

Auditing policy options

Type Definitions

SessionError

Session errors