Struct Client 

pub struct Client {
    connector: Connector,
    session: Arc<Mutex<Option<Session>>>,
    credentials: Option<Credentials>,
}

YubiHSM client: main API in this crate for accessing functions of the HSM hardware device.

Fields

connector: Connector

session: Arc<Mutex<Option<Session>>>

credentials: Option<Credentials>

Implementations

impl Client

pub fn open( connector: Connector, credentials: Credentials, reconnect: bool, ) -> Result<Client, Error<ErrorKind>>

Open a connection via a Connector to a YubiHSM, returning a Client. Connector may use Http, Usb, or MockHsm.

Examples

#[cfg(all(feature = "mockhsm", feature = "passwords"))]
use yubihsm2::{
    Client,
    Connector,
    Credentials,
    authentication::{DEFAULT_AUTHENTICATION_KEY_ID, Key, key::DEFAULT_PASSWORD},
};

let credentials = Credentials {
    authentication_key_id: DEFAULT_AUTHENTICATION_KEY_ID,
    authentication_key: Key::derive_from_password(DEFAULT_PASSWORD),
};
let client = Client::open(Connector::mockhsm(), credentials, false)?;

pub fn create( connector: Connector, credentials: Credentials, ) -> Result<Client, Error<ErrorKind>>

Create a Client, but defer connecting until connect() is called.

pub fn connector(&self) -> &Connector

Borrow this client’s YubiHSM connector (which is Cloneable)

pub fn connect(&self) -> Result<(), Error<ErrorKind>>

Connect to the HSM (idempotently, i.e. returns success if we have an open connection already)

pub fn close_session(&self) -> Result<(), Error<ErrorKind>>

Closes the current [Session] if it is still open.

Errors

Returns an error, if the session lock cannot be acquired or the session cannot be closed.

pub fn session(&self) -> Result<Guard<'_>, Error<ErrorKind>>

Get current [Session] (either opening a new one or returning an already open one).

pub fn ping(&self) -> Result<Duration, Error<ErrorKind>>

Ping the HSM, ensuring we have a live connection and returning the end-to-end latency.

pub fn blink_device(&self, num_seconds: u8) -> Result<(), Error<ErrorKind>>

Blink the HSM’s LEDs (to identify it) for the given number of seconds.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#blink-device-command

pub fn decrypt_oaep<T>( &self, key_id: u16, mgf1_hash_alg: Algorithm, data: T, label_hash: Vec<u8>, ) -> Result<DecryptedData, Error<ErrorKind>>

where T: Into<Vec<u8>>,

Decrypt data encrypted with RSA-OAEP

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#decrypt-oaep-command

pub fn delete_object( &self, object_id: u16, object_type: Type, ) -> Result<(), Error<ErrorKind>>

Delete an object of the given ID and type.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#delete-object-command

pub fn device_info(&self) -> Result<Info, Error<ErrorKind>>

Get information about the HSM device.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#device-info-command

pub fn echo<M>(&self, msg: M) -> Result<Vec<u8>, Error<ErrorKind>>

where M: Into<Vec<u8>>,

Echo a message sent to the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#echo-command

pub fn export_wrapped( &self, wrap_key_id: u16, object_type: Type, object_id: u16, ) -> Result<Message, Error<ErrorKind>>

Export an encrypted object from the HSM using the given key-wrapping key.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#export-wrapped-command

pub fn export_wrapped_with_seed( &self, wrap_key_id: u16, object_type: Type, object_id: u16, ) -> Result<Message, Error<ErrorKind>>

Export an encrypted object from the HSM using the given key-wrapping key including the private key seed.

For YubiHSM devices with firmware version 2.4 or later, this command enables exporting ed25519 keys with the seed for a private key. To ensure backward compatibility with older versions of the HSM, the default is to not export the seed. Importing such a legacy format results in an all-zero seed if such a key is exported in the future.

https://developers.yubico.com/YubiHSM2/Commands/Export_Wrapped.html

pub fn generate_asymmetric_key( &self, key_id: u16, label: Label, domains: Domain, capabilities: Capability, algorithm: Algorithm, ) -> Result<u16, Error<ErrorKind>>

Generate a new asymmetric key within the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#generate-asymmetric-key-command

pub fn generate_hmac_key( &self, key_id: u16, label: Label, domains: Domain, capabilities: Capability, algorithm: Algorithm, ) -> Result<u16, Error<ErrorKind>>

Generate a new HMAC key within the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#generate-hmac-key-command

pub fn generate_symmetric_key( &self, key_id: u16, label: Label, domains: Domain, capabilities: Capability, algorithm: Algorithm, ) -> Result<u16, Error<ErrorKind>>

Generate a new symmetric key within the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#generate-symmetric-key-command

pub fn generate_wrap_key( &self, key_id: u16, label: Label, domains: Domain, capabilities: Capability, delegated_capabilities: Capability, algorithm: Algorithm, ) -> Result<u16, Error<ErrorKind>>

Generate a new wrap key within the HSM.

Delegated capabilities are the set of Capability bits that an object is allowed to have when imported or exported using the wrap key.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#generate-wrap-key-command

pub fn get_log_entries(&self) -> Result<LogEntries, Error<ErrorKind>>

Get audit logs from the HSM device.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-log-entries-command

pub fn get_object_info( &self, object_id: u16, object_type: Type, ) -> Result<Info, Error<ErrorKind>>

Get information about an object.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-object-info-command

pub fn get_opaque(&self, object_id: u16) -> Result<Vec<u8>, Error<ErrorKind>>

Get an opaque object stored in the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-opaque-command

pub fn get_command_audit_option( &self, command: Code, ) -> Result<AuditOption, Error<ErrorKind>>

Get the audit policy setting for a particular command.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-option-command

pub fn get_commands_audit_options( &self, ) -> Result<Vec<AuditCommand>, Error<ErrorKind>>

Get the audit policy settings for all commands.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-option-command

pub fn get_force_audit_option(&self) -> Result<AuditOption, Error<ErrorKind>>

Get the forced auditing global option: when enabled, the device will refuse operations if the log store becomes full.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-option-command

pub fn get_fips_option(&self) -> Result<AuditOption, Error<ErrorKind>>

Get the FIPS operation global option

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-option-command

pub fn get_pseudo_random( &self, bytes: usize, ) -> Result<Vec<u8>, Error<ErrorKind>>

Get some number of bytes of pseudo random data generated on the device.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-pseudo-random-command

pub fn get_public_key(&self, key_id: u16) -> Result<PublicKey, Error<ErrorKind>>

Get the public key for an asymmetric key stored on the device.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-public-key-command

pub fn get_storage_info(&self) -> Result<Info, Error<ErrorKind>>

Get storage info (i.e. currently free storage) from the HSM device.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-storage-info-command

pub fn get_template(&self, object_id: u16) -> Result<Vec<u8>, Error<ErrorKind>>

Get a certificate template (i.e. for SSH CA) stored in the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#get-template-command

pub fn import_wrapped<M>( &self, wrap_key_id: u16, wrap_message: M, ) -> Result<Handle, Error<ErrorKind>>

where M: Into<Message>,

Import an encrypted object from the HSM using the given key-wrapping key.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#import-wrapped-command

pub fn list_objects( &self, filters: &[Filter], ) -> Result<Vec<Entry>, Error<ErrorKind>>

List objects visible from the current session.

Optionally apply a set of provided filters which select objects based on their attributes.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#list-objects-command

pub fn put_asymmetric_key<K>( &self, key_id: u16, label: Label, domains: Domain, capabilities: Capability, algorithm: Algorithm, key_bytes: K, ) -> Result<u16, Error<ErrorKind>>

where K: Into<Vec<u8>>,

Put an existing asymmetric key into the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#put-asymmetric-key-command

pub fn put_authentication_key<K>( &self, key_id: u16, label: Label, domains: Domain, capabilities: Capability, delegated_capabilities: Capability, algorithm: Algorithm, authentication_key: K, ) -> Result<u16, Error<ErrorKind>>

where K: Into<Key>,

Put an existing [authentication::Key] into the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#put-authentication-key-command

pub fn change_authentication_key<K>( &self, key_id: u16, algorithm: Algorithm, authentication_key: K, ) -> Result<u16, Error<ErrorKind>>

where K: Into<Key>,

Change the authentication key used to establish the current session.

Available with firmware version 2.2.0 or later. Atomically replaces the key material while preserving all object metadata (ID, label, domains, capabilities, delegated capabilities).

Only the Authentication Key that was used to open the current session can be changed with this command. The required capability is change-authentication-key.

https://developers.yubico.com/YubiHSM2/Commands/Change_Authentication_Key.html

pub fn put_hmac_key<K>( &self, key_id: u16, label: Label, domains: Domain, capabilities: Capability, algorithm: Algorithm, key_bytes: K, ) -> Result<u16, Error<ErrorKind>>

where K: Into<Vec<u8>>,

Put an existing HMAC key into the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#put-hmac-key-command

pub fn put_opaque<B>( &self, object_id: u16, label: Label, domains: Domain, capabilities: Capability, algorithm: Algorithm, opaque_data: B, ) -> Result<u16, Error<ErrorKind>>

where B: Into<Vec<u8>>,

Put an opaque object (X.509 certificate or other bytestring) into the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#put-opaque-command

pub fn put_otp_aead_key<K>( &self, key_id: u16, label: Label, domains: Domain, capabilities: Capability, algorithm: Algorithm, key_bytes: K, ) -> Result<u16, Error<ErrorKind>>

where K: Into<Vec<u8>>,

Put an existing OTP AEAD key into the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#put-otp-aead-key-command

pub fn put_symmetric_key<K>( &self, key_id: u16, label: Label, domains: Domain, capabilities: Capability, algorithm: Algorithm, key_bytes: K, ) -> Result<u16, Error<ErrorKind>>

where K: Into<Vec<u8>>,

Put an existing symmetric key into the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#put-symmetric-key-command

pub fn put_wrap_key<K>( &self, key_id: u16, label: Label, domains: Domain, capabilities: Capability, delegated_capabilities: Capability, algorithm: Algorithm, key_bytes: K, ) -> Result<u16, Error<ErrorKind>>

where K: Into<Vec<u8>>,

Put an existing wrap key into the HSM.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#put-wrap-key-command

pub fn put_template<T>( &self, object_id: u16, label: Label, domains: Domain, capabilities: Capability, template: T, ) -> Result<u16, Error<ErrorKind>>

where T: Into<Template>,

Put a template object (i.e. for SSH CA) into the HSM.

Use the [Template] type for SSH CA templates.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#put-template-command

pub fn reset_device(&self) -> Result<(), Error<ErrorKind>>

Reset the HSM to a factory default state and reboot, clearing all stored objects and restoring the default auth key.

WARNING: This wipes all keys and other data from the HSM! Make absolutely sure you want to use this!

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#reset-device-command

pub fn reset_device_and_reconnect( &mut self, timeout: Duration, ) -> Result<(), Error<ErrorKind>>

Reset the HSM to a factory default state and reboot, clearing all stored objects and restoring the default auth key. This method further attempts to wait for the HSM to finish resetting and then attempts to reauthenticate with the default credentials.

Upon successfully resetting the device and authenticating using the default administrator credentials in key slot 0x01, a new Client is returned.

WARNING: This wipes all keys and other data from the HSM! Make absolutely sure you want to use this!

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#reset-device-command

pub fn set_command_audit_option( &self, command: Code, audit_option: AuditOption, ) -> Result<(), Error<ErrorKind>>

Configure the audit policy settings for a particular command, e.g. auditing should be On, Off, or Fix (i.e. fixed permanently on).

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#set-option-command

pub fn set_force_audit_option( &self, option: AuditOption, ) -> Result<(), Error<ErrorKind>>

Put the forced auditing global option: when enabled, the device will refuse operations if the log store becomes full.

Options are On, Off, or Fix (i.e. fixed permanently on)

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#set-option-command

pub fn set_fips_option( &self, option: AuditOption, ) -> Result<(), Error<ErrorKind>>

Put the FIPS global option: when enabled, it disables algorithms that are not allowed by FIPS 140.

Options are Off, or On

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#set-option-command

pub fn set_log_index(&self, log_index: u16) -> Result<(), Error<ErrorKind>>

Set the index of the last consumed index of the HSM audit log.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#set-log-index-command

pub fn sign_attestation_certificate( &self, key_id: u16, attestation_key_id: Option<u16>, ) -> Result<Certificate, Error<ErrorKind>>

Obtain an X.509 attestation certificate for a key within the HSM. This can be used to demonstrate that a given key was generated by and stored within a HSM in a non-exportable manner.

The key_id is the subject key for which an attestation certificate is created, and theattestation_key_id will be used to sign the attestation certificate.

If no attestation key is given, the device’s default attestation key will be used, and can be verified against Yubico’s certificate.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#sign-attestation-certificate-command

pub fn sign_ecdsa_prehash_raw<T>( &self, key_id: u16, digest: T, ) -> Result<Vec<u8>, Error<ErrorKind>>

where T: Into<Vec<u8>>,

Compute an ECDSA signature of the given digest (i.e. a precomputed SHA-2 digest)

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#sign-ecdsa-command

Security Warning

This is a low-level ECDSA API, and if used incorrectly could potentially result in forgeable signatures.

We recommend using the [ecdsa::Signer] type instead, which provides a high-level, well-typed, misuse resistant API.

pub fn sign_ed25519<T>( &self, key_id: u16, data: T, ) -> Result<Signature, Error<ErrorKind>>

where T: Into<Vec<u8>>,

Compute an Ed25519 signature with the given key ID.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#sign-eddsa-command

pub fn sign_hmac<M>(&self, key_id: u16, msg: M) -> Result<Tag, Error<ErrorKind>>

where M: Into<Vec<u8>>,

Compute an HMAC tag of the given data with the given key ID.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#sign-hmac-command

pub fn sign_rsa_pkcs1v15_sha256( &self, key_id: u16, data: &[u8], ) -> Result<Signature, Error<ErrorKind>>

Compute an RSASSA-PKCS#1v1.5 signature of the SHA-256 hash of the given data.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#sign-pkcs1-command

pub fn sign_rsa_pss_sha256( &self, key_id: u16, data: &[u8], ) -> Result<Signature, Error<ErrorKind>>

Compute an RSASSA-PSS signature of the SHA-256 hash of the given data with the given key ID.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#sign-pss-command

pub fn unwrap_data<M>( &self, wrap_key_id: u16, wrap_message: M, ) -> Result<Vec<u8>, Error<ErrorKind>>

where M: Into<Message>,

Decrypt data which was encrypted (using AES-CCM) under a wrap key.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#unwrap-data-command

pub fn verify_hmac<M, T>( &self, key_id: u16, msg: M, tag: T, ) -> Result<(), Error<ErrorKind>>

where M: Into<Vec<u8>>, T: Into<Tag>,

Verify an HMAC tag of the given data with the given key ID.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#verify-hmac-command

pub fn wrap_data( &self, wrap_key_id: u16, plaintext: Vec<u8>, ) -> Result<Message, Error<ErrorKind>>

Encrypt data (with AES-CCM) using the given wrap key.

https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-cmd-reference.html#wrap-data-command

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.