Crate yubihsm

source ·
Expand description

yubihsm.rs

crate Docs Build Status Dependency Status Apache2/MIT licensed MSRV

Pure Rust client for YubiHSM 2 devices from Yubico.

Documentation

About

This is a pure-Rust client library for YubiHSM 2 devices which implements most the functionality of the libyubihsm C library from Yubico’s YubiHSM SDK. It provides two backends for communicating with YubiHSMs:

  • HTTP: communicate with YubiHSM via the yubihsm-connector process from the Yubico SDK.
  • USB: communicate directly with the YubiHSM over USB using the rusb crate.

The yubihsm::Client type provides access to HSM commands.

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).

NOTE: Looking for a YubiKey library instead of YubiHSM? Check out yubikey-piv.rs instead.

Minimum Supported Rust Version

This crate requires Rust 1.57 or newer.

Supported Commands

NOTE: If there’s a command on this list you’d like to use which isn’t presently supported, please open an issue requesting support.

CommandImpl’dMockHSMDescription
Authenticate SessionAuthenticate to HSM with password or encryption key
Blink DeviceBlink the HSM’s LEDs (to identify it)
Change Authentication KeyReplace the authentication key used to create current session
Close SessionTerminate an encrypted session with the HSM
Create OTP AEADCreate a Yubico OTP AEAD
Create SessionInitiate a new encrypted session with the HSM
Decrypt OAEPDecrypt data encrypted with RSA-OAEP
Decrypt OTPDecrypt a Yubico OTP, obtaining counters and timer info
Decrypt PKCS1Decrypt data encrypted with RSA-PKCS#1v1.5
Delete ObjectDelete an object of the given ID and type
Derive ECDH⚠️Compute Elliptic Curve Diffie-Hellman using HSM-backed key
Device InfoGet information about the HSM
EchoEcho a message sent to the HSM
Export WrappedExport an object from the HSM in encrypted form
Generate Asymmetric KeyRandomly generate new asymmetric key in the HSM
Generate HMAC KeyRandomly generate HMAC key in the HSM
Generate OTP AEAD KeyRandomly generate AES key for Yubico OTP authentication
Generate Wrap KeyRandomly generate AES key for exporting/importing objects
Get Log EntriesObtain the audit log for the HSM
Get Object InfoGet information about an object
Get OpaqueGet an opaque bytestring from the HSM
Get OptionGet HSM auditing settings
Get Pseudo RandomGet random data generated by the HSM’s internal PRNG
Get Public keyGet public key for an HSM-backed asymmetric private key
Get Storage InfoFetch information about currently free storage
Get SSH TemplateFetch SSH certificate template object from the HSM
Import WrappedImport an encrypted key into the HSM
List ObjectsList objects visible from the current session
Put Asymmetric KeyPut an existing asymmetric key into the HSM
Put Authentication KeyPut YubiHSM authentication key into the HSM
Put HMAC KeyPut an HMAC key into the HSM
Put OpaquePut an opaque bytestring into the HSM
Put OTP AEAD KeyPut a Yubico OTP key into the HSM
Put SSH TemplatePut SSH certificate template object into the HSM
Put Wrap KeyPut an AES keywrapping key into the HSM
Randomize OTP AEADRandomly generate a Yubico OTP AEAD
Reset DeviceReset the HSM back to factory default settings
Rewrap OTP AEADRe-wrap a Yubico OTP AEAD from one key to another
Session MessageSend an encrypted message to the HSM
Set Log IndexMark log messages in the HSM as consumed
Set OptionChange HSM auditing settings
Sign Attestation CertificateCreate X.509 certificate for asymmetric key
Sign ECDSACompute an ECDSA signature using HSM-backed key
Sign EdDSACompute an Ed25519 signature using HSM-backed key
Sign HMACPerform an HMAC operation using an HSM-backed key
Sign PKCS1⚠️Compute an RSASSA-PKCS#1v1.5 signature using HSM-backed key
Sign PSS⚠️Compute an RSASSA-PSS signature using HSM-backed key
Sign SSH Certificate⚠️Sign an SSH certificate request
Unwrap DataDecrypt data encrypted using a wrap key
Verify HMACVerify that an HMAC tag for given data is valid
Wrap DataEncrypt data using a wrap key
Status
Supported
⚠️Partial/Untested Support
Unsupported

NOTE: Commands marked ⚠️ have not been properly tested and may contain bugs or not work at all. They are disabled by default: to use them you must enable the untested cargo feature. If you do get them to work, please open an issue (or PR) reporting success so we can promote them to ✅.

Testing

This crate allows you to run the integration test suite in three different ways:

  • Live testing against a real YubiHSM2 device:
    • via HTTP
    • via USB
  • simulated testing using MockHSM which implements some YubiHSM2 functionality

cargo test: test YubiHSM2 live over HTTP via yubihsm-connector

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=usb: test YubiHSM2 live via USB

Adding the usb cargo feature builds in USB connector support in addition to HTTP connector, and also runs the test suite live via USB rather than using the yubihsm-connector process.

ALSO 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.

Getting Started

Most crate functionality can be found in the Client type:

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

Modules

  • Cryptographic algorithms supported by the YubiHSM 2
  • Asymmetric cryptography i.e. digital signatures and public-key encryption.
  • Attestation Certificates: generate an X.509 certificate which attests that a key generated with a YubiHSM is genuine
  • Auditing options (for use with the get_option and put_option command)
  • YubiHSM 2 authentication functionality (i.e. credentials used to authenticate and establish a session with an HSM)
  • Object attributes specifying which operations are allowed to be performed
  • YubiHSM client: core functionality of this crate.
  • YubiHSM commands: types and traits for modeling the commands supported by the HSM device, implemented in relevant modules.
  • Methods of connecting to a YubiHSM 2:
  • HSM device-related functionality
  • Logical partitions within the HSM, allowing several applications to share the device.
  • Elliptic Curve Diffie Hellman Key Exchange.
  • Elliptic Curve Digital Signature Algorithm (ECDSA) support
  • Ed25519 digital signature algorithm support
  • Error types
  • Hash-based Message Authentication Code (HMAC)
  • Objects within the YubiHSM 2 (keys, certificates, or other opaque data)
  • Opaque object support: store arbitrary data in the HSM
  • Yubico One Time Password (OTP) functionality
  • Responses to command sent from the HSM.
  • RSA (Rivest–Shamir–Adleman) asymmetric cryptosystem support (signing/encryption).
  • Authenticated/encrypted sessions with the HSM.
  • setupsetup
    Initial YubiHSM 2 setup functionality using declarative device profiles.
  • Secure Shell Certificate Authority Functionality
  • Certificate templates.
  • “Wrapping” support: YubiHSM 2 key/object encryption for backups and importing existing keys to other derivces.

Structs

  • A Universally Unique Identifier (UUID).