pub struct Client { /* private fields */ }
Expand description
YubiHSM client: main API in this crate for accessing functions of the HSM hardware device.
Implementations
sourceimpl Client
impl Client
sourcepub fn open(
connector: Connector,
credentials: Credentials,
reconnect: bool
) -> Result<Self, Error>
pub fn open(
connector: Connector,
credentials: Credentials,
reconnect: bool
) -> Result<Self, Error>
Open a connection via a Connector to a YubiHSM, returning a yubihsm::Client
.
Valid Connector
types are: HttpConnector, UsbConnector, and MockHsm.
sourcepub fn create(
connector: Connector,
credentials: Credentials
) -> Result<Self, Error>
pub fn create(
connector: Connector,
credentials: Credentials
) -> Result<Self, Error>
Create a yubihsm::Client
, but defer connecting until connect()
is called.
sourcepub fn connector(&self) -> &Connector
pub fn connector(&self) -> &Connector
Borrow this client’s YubiHSM connector (which is Clone
able)
sourcepub fn connect(&self) -> Result<(), Error>
pub fn connect(&self) -> Result<(), Error>
Connect to the HSM (idempotently, i.e. returns success if we have an open connection already)
sourcepub fn session(&self) -> Result<Guard<'_>, Error>
pub fn session(&self) -> Result<Guard<'_>, Error>
Get current Session
(either opening a new one or returning an already
open one).
sourcepub fn ping(&self) -> Result<Duration, Error>
pub fn ping(&self) -> Result<Duration, Error>
Ping the HSM, ensuring we have a live connection and returning the end-to-end latency.
sourcepub fn blink_device(&self, num_seconds: u8) -> Result<(), Error>
pub fn blink_device(&self, num_seconds: u8) -> Result<(), Error>
Blink the HSM’s LEDs (to identify it) for the given number of seconds.
https://developers.yubico.com/YubiHSM2/Commands/Blink_Device.html
sourcepub fn decrypt_oaep<T>(
&self,
key_id: Id,
mgf1_hash_alg: Algorithm,
data: T,
label_hash: Vec<u8>
) -> Result<DecryptedData, Error> where
T: Into<Vec<u8>>,
pub fn decrypt_oaep<T>(
&self,
key_id: Id,
mgf1_hash_alg: Algorithm,
data: T,
label_hash: Vec<u8>
) -> Result<DecryptedData, Error> where
T: Into<Vec<u8>>,
Decrypt data encrypted with RSA-OAEP
https://developers.yubico.com/YubiHSM2/Commands/Decrypt_Oaep.html
sourcepub fn delete_object(&self, object_id: Id, object_type: Type) -> Result<(), Error>
pub fn delete_object(&self, object_id: Id, object_type: Type) -> Result<(), Error>
Delete an object of the given ID and type.
https://developers.yubico.com/YubiHSM2/Commands/Delete_Object.html
sourcepub fn derive_ecdh(
&self,
key_id: Id,
public_key: UncompressedPoint
) -> Result<UncompressedPoint, Error>
Available on crate feature untested
only.
pub fn derive_ecdh(
&self,
key_id: Id,
public_key: UncompressedPoint
) -> Result<UncompressedPoint, Error>
untested
only.Elliptic Curve Diffie-Hellman: derive a shared secret via key exchange.
WARNING: This functionality has not been tested and has not yet been confirmed to actually work! USE AT YOUR OWN RISK!
You will need to enable the untested
cargo feature to use it.
https://developers.yubico.com/YubiHSM2/Commands/Derive_Ecdh.html
sourcepub fn device_info(&self) -> Result<Info, Error>
pub fn device_info(&self) -> Result<Info, Error>
Get information about the HSM device.
https://developers.yubico.com/YubiHSM2/Commands/Device_Info.html
sourcepub fn echo<M>(&self, msg: M) -> Result<Vec<u8>, Error> where
M: Into<Vec<u8>>,
pub fn echo<M>(&self, msg: M) -> Result<Vec<u8>, Error> where
M: Into<Vec<u8>>,
Echo a message sent to the HSM.
sourcepub fn export_wrapped(
&self,
wrap_key_id: Id,
object_type: Type,
object_id: Id
) -> Result<Message, Error>
pub fn export_wrapped(
&self,
wrap_key_id: Id,
object_type: Type,
object_id: Id
) -> Result<Message, Error>
Export an encrypted object from the HSM using the given key-wrapping key.
https://developers.yubico.com/YubiHSM2/Commands/Export_Wrapped.html
sourcepub fn generate_asymmetric_key(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm
) -> Result<Id, Error>
pub fn generate_asymmetric_key(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm
) -> Result<Id, Error>
Generate a new asymmetric key within the HSM.
https://developers.yubico.com/YubiHSM2/Commands/Generate_Asymmetric_Key.html
sourcepub fn generate_hmac_key(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm
) -> Result<Id, Error>
pub fn generate_hmac_key(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm
) -> Result<Id, Error>
Generate a new HMAC key within the HSM.
https://developers.yubico.com/YubiHSM2/Commands/Generate_Hmac_Key.html
sourcepub fn generate_wrap_key(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
delegated_capabilities: Capability,
algorithm: Algorithm
) -> Result<Id, Error>
pub fn generate_wrap_key(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
delegated_capabilities: Capability,
algorithm: Algorithm
) -> Result<Id, Error>
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://developers.yubico.com/YubiHSM2/Commands/Generate_Wrap_Key.html
sourcepub fn get_log_entries(&self) -> Result<LogEntries, Error>
pub fn get_log_entries(&self) -> Result<LogEntries, Error>
Get audit logs from the HSM device.
https://developers.yubico.com/YubiHSM2/Commands/Get_Log_Entries.html
sourcepub fn get_object_info(
&self,
object_id: Id,
object_type: Type
) -> Result<Info, Error>
pub fn get_object_info(
&self,
object_id: Id,
object_type: Type
) -> Result<Info, Error>
Get information about an object.
https://developers.yubico.com/YubiHSM2/Commands/Get_Object_Info.html
sourcepub fn get_opaque(&self, object_id: Id) -> Result<Vec<u8>, Error>
pub fn get_opaque(&self, object_id: Id) -> Result<Vec<u8>, Error>
Get an opaque object stored in the HSM.
https://developers.yubico.com/YubiHSM2/Commands/Get_Opaque.html
sourcepub fn get_command_audit_option(
&self,
command: Code
) -> Result<AuditOption, Error>
pub fn get_command_audit_option(
&self,
command: Code
) -> Result<AuditOption, Error>
Get the audit policy setting for a particular command.
https://developers.yubico.com/YubiHSM2/Commands/Get_Option.html
sourcepub fn get_commands_audit_options(&self) -> Result<Vec<AuditCommand>, Error>
pub fn get_commands_audit_options(&self) -> Result<Vec<AuditCommand>, Error>
Get the audit policy settings for all commands.
https://developers.yubico.com/YubiHSM2/Commands/Get_Option.html
sourcepub fn get_force_audit_option(&self) -> Result<AuditOption, Error>
pub fn get_force_audit_option(&self) -> Result<AuditOption, Error>
Get the forced auditing global option: when enabled, the device will refuse operations if the log store becomes full.
https://developers.yubico.com/YubiHSM2/Commands/Get_Option.html
sourcepub fn get_pseudo_random(&self, bytes: usize) -> Result<Vec<u8>, Error>
pub fn get_pseudo_random(&self, bytes: usize) -> Result<Vec<u8>, Error>
Get some number of bytes of pseudo random data generated on the device.
https://developers.yubico.com/YubiHSM2/Commands/Get_Pseudo_Random.html
sourcepub fn get_public_key(&self, key_id: Id) -> Result<PublicKey, Error>
pub fn get_public_key(&self, key_id: Id) -> Result<PublicKey, Error>
Get the public key for an asymmetric key stored on the device.
https://developers.yubico.com/YubiHSM2/Commands/Get_Public_Key.html
sourcepub fn get_storage_info(&self) -> Result<StorageInfo, Error>
pub fn get_storage_info(&self) -> Result<StorageInfo, Error>
Get storage info (i.e. currently free storage) from the HSM device.
https://developers.yubico.com/YubiHSM2/Commands/Get_Storage_Info.html
sourcepub fn get_template(&self, object_id: Id) -> Result<Vec<u8>, Error>
pub fn get_template(&self, object_id: Id) -> Result<Vec<u8>, Error>
Get a certificate template (i.e. for SSH CA) stored in the HSM.
https://developers.yubico.com/YubiHSM2/Commands/Get_Template.html
sourcepub fn import_wrapped<M>(
&self,
wrap_key_id: Id,
wrap_message: M
) -> Result<Handle, Error> where
M: Into<Message>,
pub fn import_wrapped<M>(
&self,
wrap_key_id: Id,
wrap_message: M
) -> Result<Handle, Error> where
M: Into<Message>,
Import an encrypted object from the HSM using the given key-wrapping key.
https://developers.yubico.com/YubiHSM2/Commands/Import_Wrapped.html
sourcepub fn list_objects(&self, filters: &[Filter]) -> Result<Vec<Entry>, Error>
pub fn list_objects(&self, filters: &[Filter]) -> Result<Vec<Entry>, Error>
List objects visible from the current session.
Optionally apply a set of provided filters
which select objects
based on their attributes.
https://developers.yubico.com/YubiHSM2/Commands/List_Objects.html
sourcepub fn put_asymmetric_key<K>(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm,
key_bytes: K
) -> Result<Id, Error> where
K: Into<Vec<u8>>,
pub fn put_asymmetric_key<K>(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm,
key_bytes: K
) -> Result<Id, Error> where
K: Into<Vec<u8>>,
Put an existing asymmetric key into the HSM.
https://developers.yubico.com/YubiHSM2/Commands/Put_Asymmetric.html
sourcepub fn put_authentication_key<K>(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
delegated_capabilities: Capability,
algorithm: Algorithm,
authentication_key: K
) -> Result<Id, Error> where
K: Into<Key>,
pub fn put_authentication_key<K>(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
delegated_capabilities: Capability,
algorithm: Algorithm,
authentication_key: K
) -> Result<Id, Error> where
K: Into<Key>,
Put an existing authentication::Key
into the HSM.
https://developers.yubico.com/YubiHSM2/Commands/Put_Authentication_Key.html
sourcepub fn put_hmac_key<K>(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm,
key_bytes: K
) -> Result<Id, Error> where
K: Into<Vec<u8>>,
pub fn put_hmac_key<K>(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm,
key_bytes: K
) -> Result<Id, Error> where
K: Into<Vec<u8>>,
Put an existing HMAC key into the HSM.
https://developers.yubico.com/YubiHSM2/Commands/Put_Hmac_Key.html
sourcepub fn put_opaque<B>(
&self,
object_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm,
opaque_data: B
) -> Result<Id, Error> where
B: Into<Vec<u8>>,
pub fn put_opaque<B>(
&self,
object_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm,
opaque_data: B
) -> Result<Id, Error> where
B: Into<Vec<u8>>,
Put an opaque object (X.509 certificate or other bytestring) into the HSM.
https://developers.yubico.com/YubiHSM2/Commands/Put_Opaque.html
sourcepub fn put_otp_aead_key<K>(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm,
key_bytes: K
) -> Result<Id, Error> where
K: Into<Vec<u8>>,
pub fn put_otp_aead_key<K>(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
algorithm: Algorithm,
key_bytes: K
) -> Result<Id, Error> where
K: Into<Vec<u8>>,
Put an existing OTP AEAD key into the HSM.
https://developers.yubico.com/YubiHSM2/Commands/Put_Otp_Aead_Key.html
sourcepub fn put_wrap_key<K>(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
delegated_capabilities: Capability,
algorithm: Algorithm,
key_bytes: K
) -> Result<Id, Error> where
K: Into<Vec<u8>>,
pub fn put_wrap_key<K>(
&self,
key_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
delegated_capabilities: Capability,
algorithm: Algorithm,
key_bytes: K
) -> Result<Id, Error> where
K: Into<Vec<u8>>,
Put an existing wrap key into the HSM.
https://developers.yubico.com/YubiHSM2/Commands/Put_Wrap_Key.html
sourcepub fn put_template<T>(
&self,
object_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
template: T
) -> Result<Id, Error> where
T: Into<Template>,
pub fn put_template<T>(
&self,
object_id: Id,
label: Label,
domains: Domain,
capabilities: Capability,
template: T
) -> Result<Id, Error> where
T: Into<Template>,
Put a template object (i.e. for SSH CA) into the HSM.
Use the yubihsm::ssh::Template
type for SSH CA templates.
https://developers.yubico.com/YubiHSM2/Commands/Put_Template.html
sourcepub fn reset_device(&self) -> Result<(), Error>
pub fn reset_device(&self) -> Result<(), Error>
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://developers.yubico.com/YubiHSM2/Commands/Reset_Device.html
sourcepub fn reset_device_and_reconnect(
&mut self,
timeout: Duration
) -> Result<(), Error>
pub fn reset_device_and_reconnect(
&mut self,
timeout: Duration
) -> Result<(), Error>
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 autenticating using the
default administrator credentials in key slot 0x01, a new
yubihsm::Client
is returned.
WARNING: This wipes all keys and other data from the HSM! Make absolutely sure you want to use this!
https://developers.yubico.com/YubiHSM2/Commands/Reset_Device.html
sourcepub fn set_command_audit_option(
&self,
command: Code,
audit_option: AuditOption
) -> Result<(), Error>
pub fn set_command_audit_option(
&self,
command: Code,
audit_option: AuditOption
) -> Result<(), Error>
Configure the audit policy settings for a particular command, e.g. auditing
should be On
, Off
, or Fix
(i.e. fixed permanently on).
https://developers.yubico.com/YubiHSM2/Commands/Set_Option.html
sourcepub fn set_force_audit_option(&self, option: AuditOption) -> Result<(), Error>
pub fn set_force_audit_option(&self, option: AuditOption) -> Result<(), Error>
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://developers.yubico.com/YubiHSM2/Commands/Put_Option.html
sourcepub fn set_log_index(&self, log_index: u16) -> Result<(), Error>
pub fn set_log_index(&self, log_index: u16) -> Result<(), Error>
Set the index of the last consumed index of the HSM audit log.
https://developers.yubico.com/YubiHSM2/Commands/Set_Log_Index.html
sourcepub fn sign_attestation_certificate(
&self,
key_id: Id,
attestation_key_id: Option<Id>
) -> Result<Certificate, Error>
pub fn sign_attestation_certificate(
&self,
key_id: Id,
attestation_key_id: Option<Id>
) -> Result<Certificate, Error>
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://developers.yubico.com/YubiHSM2/Commands/Sign_Attestation_Certificate.html
sourcepub fn sign_ecdsa_prehash_raw<T>(
&self,
key_id: Id,
digest: T
) -> Result<Vec<u8>, Error> where
T: Into<Vec<u8>>,
pub fn sign_ecdsa_prehash_raw<T>(
&self,
key_id: Id,
digest: T
) -> Result<Vec<u8>, Error> where
T: Into<Vec<u8>>,
Compute an ECDSA signature of the given digest (i.e. a precomputed SHA-2 digest)
https://developers.yubico.com/YubiHSM2/Commands/Sign_Ecdsa.html
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.
sourcepub fn sign_ed25519<T>(&self, key_id: Id, data: T) -> Result<Signature, Error> where
T: Into<Vec<u8>>,
pub fn sign_ed25519<T>(&self, key_id: Id, data: T) -> Result<Signature, Error> where
T: Into<Vec<u8>>,
Compute an Ed25519 signature with the given key ID.
https://developers.yubico.com/YubiHSM2/Commands/Sign_Eddsa.html
sourcepub fn sign_hmac<M>(&self, key_id: Id, msg: M) -> Result<Tag, Error> where
M: Into<Vec<u8>>,
pub fn sign_hmac<M>(&self, key_id: Id, msg: M) -> Result<Tag, Error> where
M: Into<Vec<u8>>,
Compute an HMAC tag of the given data with the given key ID.
https://developers.yubico.com/YubiHSM2/Commands/Sign_Hmac.html
sourcepub fn sign_rsa_pkcs1v15_sha256(
&self,
key_id: Id,
data: &[u8]
) -> Result<Signature, Error>
Available on crate feature untested
only.
pub fn sign_rsa_pkcs1v15_sha256(
&self,
key_id: Id,
data: &[u8]
) -> Result<Signature, Error>
untested
only.Compute an RSASSA-PKCS#1v1.5 signature of the SHA-256 hash of the given data.
WARNING: This functionality has not been tested and has not yet been confirmed to actually work! USE AT YOUR OWN RISK!
You will need to enable the untested
cargo feature to use it.
https://developers.yubico.com/YubiHSM2/Commands/Sign_Pkcs1.html
sourcepub fn sign_rsa_pss_sha256(
&self,
key_id: Id,
data: &[u8]
) -> Result<Signature, Error>
Available on crate feature untested
only.
pub fn sign_rsa_pss_sha256(
&self,
key_id: Id,
data: &[u8]
) -> Result<Signature, Error>
untested
only.Compute an RSASSA-PSS signature of the SHA-256 hash of the given data with the given key ID.
WARNING: This functionality has not been tested and has not yet been confirmed to actually work! USE AT YOUR OWN RISK!
You will need to enable the untested
cargo feature to use it.
https://developers.yubico.com/YubiHSM2/Commands/Sign_Pss.html
sourcepub fn sign_ssh_certificate<A>(
&self,
key_id: Id,
template_id: Id,
algorithm: A,
timestamp: u32,
signature: [u8; 32],
request: Vec<u8>
) -> Result<Certificate, Error> where
A: Into<Algorithm>,
Available on crate feature untested
only.
pub fn sign_ssh_certificate<A>(
&self,
key_id: Id,
template_id: Id,
algorithm: A,
timestamp: u32,
signature: [u8; 32],
request: Vec<u8>
) -> Result<Certificate, Error> where
A: Into<Algorithm>,
untested
only.Sign an SSH certificate using the given template.
WARNING: This functionality has not been tested and has not yet been confirmed to actually work! USE AT YOUR OWN RISK!
You will need to enable the untested
cargo feature to use it.
https://developers.yubico.com/YubiHSM2/Commands/Sign_Ssh_Certificate.html
sourcepub fn unwrap_data<M>(
&self,
wrap_key_id: Id,
wrap_message: M
) -> Result<Vec<u8>, Error> where
M: Into<Message>,
pub fn unwrap_data<M>(
&self,
wrap_key_id: Id,
wrap_message: M
) -> Result<Vec<u8>, Error> where
M: Into<Message>,
Decrypt data which was encrypted (using AES-CCM) under a wrap key.
https://developers.yubico.com/YubiHSM2/Commands/Unwrap_Data.html
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Client
impl Send for Client
impl Sync for Client
impl Unpin for Client
impl !UnwindSafe for Client
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more