Skip to main content

Crate yubihsm2

Crate yubihsm2 

Source
Expand description

§YubiHSM2

A Rust client library for Yubico’s YubiHSM 2 devices.

This project offers USB and HTTP backends for connecting with a YubiHSM2 device.

In addition, for testing purposes, an in-memory “mock HSM” can be used.

§Documentation

§Features

  • http: Communication with a (local or remote) device over HTTP (default).
  • http-server: Functionality akin to the yubihsm-connector (HTTP only).
  • mockhsm: Communication with an in-memory “mock” HSM. NOTE: Only use this for testing!
  • passwords: Support for device reset and deriving authentication keys from a passphrase (default).
  • secp256k1: For secp256k1 elliptic-curve cryptography (ECC) support.
  • setup: Provisioning profile support (default).
  • untested: For untested functionality of the library.
  • usb: Communication with a local device over USB.

§Contributing

Please refer to the contributing guidelines to learn how to contribute to this project.

§Releases

Releases of yubihsm2 are created by the developers of this project.

OpenPGP certificates with the following OpenPGP fingerprints can be used to verify signed tags:

Some of the above are part of archlinux-keyring and certified by at least three main signing keys of the distribution. All certificate are cross-signed and can be retrieved from OpenPGP keyservers.

§Acknowledgements

This project is a fork of the yubihsm.rs project.

You can use yubihsm2 instead of yubihsm.rs by adding the following to your project’s Cargo.toml:

[dependencies]
yubihsm = { package = "yubihsm2", version = "0.43" }

§License

This project may be used under the terms of the Apache-2.0 or MIT license.

Changes to this project - unless stated otherwise - automatically fall under the terms of both of the aforementioned licenses.

§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 Connector.

§Example

The following is an example of how to create a 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§

pub use crate::connector::HttpConfig;
pub use crate::algorithm::Algorithm;
pub use crate::audit::AuditOption;
pub use crate::authentication::Credentials;
pub use crate::capability::Capability;
pub use crate::client::Client;
pub use crate::connector::Connector;
pub use crate::domain::Domain;
pub use crate::error::*;

Modules§

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

Structs§

Uuid
A Universally Unique Identifier (UUID).