yubihsm.rs

Pure Rust reimplementation of [libyubihsm] providing an end-to-end encrypted connection and command interface to [YubiHSM2] devices from [Yubico].

Documentation

About

This is a pure-Rust client library for [YubiHSM2] devices. It implements a subset of the functionality found in the closed-source Yubico SDK and communicates with the [yubihsm-connector] service: an HTTP(S) server which sends the commands to the YubiHSM2 hardware device over USB.

Note that this is NOT an official Yubico project and is in no way supported or endorsed by Yubico (although whoever runs their Twitter account [thinks it's awesome]).

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:

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

Supported Commands

• [Blink]: Blink the YubiHSM2's LEDs (to identify it)
• [Delete Object]: Delete an object of the given ID and type
• [Echo]: Have the card echo an input message
• [Generate Asymmetric Key]: Generate a new asymmetric key within the YubiHSM2
• [Get Object Info]: Get information about an object
• [Get Pubkey]: Get the public key for an asymmetric private key stored on the device
• [List Objects]: List objects visible from the current session
• [Sign Data ECDSA]: Compute an ECDSA signature using an HSM-backed private key
• [Sign Data EdDSA]: Compute an Ed25519 signature using an HSM-backed private key

Adding support for additional commands is easy! See the Contributing section.

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)

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

```rust extern crate yubihsm; use yubihsm::Session;

// Default host, port, auth key ID, and password for yubihsm-connector let mut session = Session::createfrompassword( "http://127.0.0.1:12345", 1, "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 response = yubihsm::sign_ed25519(&session, 100, "Hello, world!").unwrap(); println!("Ed25519 signature: {:?}", response.signature); ```

Contributing

If there are additional [YubiHSM2 commands] you would like to use but aren't presently supported, adding them is very easy, and PRs are welcome!

The YubiHSM2 uses a simple, bincode-like message format, which largely consists of fixed-width integers, bytestrings, and bitfields. This crate implements a [Serde-based message parser] which can automatically parse command/response messages used by the HSM derived from a corresponding Rust struct describing their structure.

Here's a list of steps necessary to implement a new command type:

1. Find the command you wish to implement on the [YubiHSM2 commands] page, and study the structure of the command (i.e. request) and response
2. Add a pub(crate) struct which matches the structure of the command to [commands.rs] and a wrapper function for constructing it and sending it to the YubiHSM.
3. Add an additional struct which matches the response structure to [responses.rs]
4. (Optional) Implement the command in [mockhsm/commands.rs] and write an [integration test]

Here is an [example PR that implements Ed25519 signing] you can study to see what the above steps look like in practice.

Testing

This crate allows you to run the integration test suite in two different ways: live testing against a real YubiHSM2 device, and simulated testing using a MockHSM service which reimplements some YubiHSM2 functionality in software.

cargo test --features=integration: test live against a YubiHSM2 device

This mode assumes you have a YubiHSM2 hardware device, have downloaded the [YubiHSM2 SDK] for your platform, and are running a yubihsm-connector process listening on localhost on the default port of 12345.

The YubiHSM2 device should be in the default factory state. To reset it to this state, either use the [yubihsm-shell reset] command or press on the YubiHSM2 for 10 seconds immediately after inserting it.

You can confirm the tests are running live against the YubiHSM2 by the LED blinking rapidly for 1 second.

NOTE THAT THESE TESTS ARE DESTRUCTIVE: DO NOT RUN THEM AGAINST A YUBIHSM2 WHICH CONTAINS KEYS YOU CARE ABOUT

cargo test --features=mockhsm: simulated tests against a mock HSM

This mode is useful for when you don't have access to physical YubiHSM2 hardware, such as CI environments.

License

yubihsm.rs is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.