Struct yubikey_piv::yubikey::YubiKey

pub struct YubiKey { /* fields omitted */ }

YubiKey Device: this is the primary API for opening a session and performing various operations.

Almost all functionality in this library will require an open session with a YubiKey which is represented by this type.

Methods

impl YubiKey

pub fn open() -> Result<Self, Error>

Open a connection to a YubiKey.

Returns an error if there is more than one YubiKey detected.

If you need to operate in environments with more than one YubiKey attached to the same system, use [yubikey_piv::Readers] to select from the available PC/SC readers connected.

pub fn reconnect(&mut self) -> Result<(), Error>

Reconnect to a YubiKey

pub fn version(&mut self) -> Version

Get the YubiKey's PIV application version.

This always uses the cached version queried when the key is initialized.

pub fn serial(&mut self) -> Serial

Get YubiKey device serial number.

This always uses the cached version queried when the key is initialized.

pub fn device_model(&self) -> u32

Get YubiKey device model

pub fn authenticate(&mut self, mgm_key: MgmKey) -> Result<(), Error>

Authenticate to the card using the provided management key (MGM).

pub fn deauthenticate(&mut self) -> Result<(), Error>

Deauthenticate

pub fn sign_data(
    &mut self,
    raw_in: &[u8],
    algorithm: AlgorithmId,
    key: SlotId
) -> Result<Zeroizing<Vec<u8>>, Error>

Sign data using a PIV key

pub fn decrypt_data(
    &mut self,
    input: &[u8],
    algorithm: AlgorithmId,
    key: SlotId
) -> Result<Zeroizing<Vec<u8>>, Error>

Decrypt data using a PIV key

pub fn verify_pin(&mut self, pin: &[u8]) -> Result<(), Error>

Verify device PIN.

pub fn get_pin_retries(&mut self) -> Result<u8, Error>

Get the number of PIN retries

pub fn set_pin_retries(
    &mut self,
    pin_tries: u8,
    puk_tries: u8
) -> Result<(), Error>

Set the number of PIN retries

pub fn change_pin(
    &mut self,
    current_pin: &[u8],
    new_pin: &[u8]
) -> Result<(), Error>

Change the Personal Identification Number (PIN).

The default PIN code is 123456

pub fn set_pin_last_changed(yubikey: &mut YubiKey) -> Result<(), Error>

Set PIN last changed

pub fn change_puk(
    &mut self,
    current_puk: &[u8],
    new_puk: &[u8]
) -> Result<(), Error>

Change the PIN Unblocking Key (PUK). PUKs are codes for resetting lost/forgotten PINs, or devices that have become blocked because of too many failed attempts.

The PUK is part of the PIV standard that the YubiKey follows.

The default PUK code is 12345678.

pub fn block_puk(yubikey: &mut YubiKey) -> Result<(), Error>

Block PUK: permanently prevent the PIN from becoming unblocked

pub fn unblock_pin(&mut self, puk: &[u8], new_pin: &[u8]) -> Result<(), Error>

Unblock a Personal Identification Number (PIN) using a previously configured PIN Unblocking Key (PUK).

pub fn fetch_object(
    &mut self,
    object_id: ObjectId
) -> Result<Zeroizing<Vec<u8>>, Error>

Fetch an object from the YubiKey

pub fn save_object(
    &mut self,
    object_id: ObjectId,
    indata: &mut [u8]
) -> Result<(), Error>

Save an object

pub fn import_private_key(
    &mut self,
    key: SlotId,
    algorithm: AlgorithmId,
    p: Option<&[u8]>,
    q: Option<&[u8]>,
    dp: Option<&[u8]>,
    dq: Option<&[u8]>,
    qinv: Option<&[u8]>,
    ec_data: Option<&[u8]>,
    pin_policy: u8,
    touch_policy: u8
) -> Result<(), Error>

Import a private encryption or signing key into the YubiKey

pub fn attest(&mut self, key: SlotId) -> Result<Zeroizing<Vec<u8>>, Error>

Generate an attestation certificate for a stored key. https://developers.yubico.com/PIV/Introduction/PIV_attestation.html

pub fn get_auth_challenge(&mut self) -> Result<[u8; 8], Error>

Get an auth challenge

pub fn verify_auth_response(&mut self, response: [u8; 8]) -> Result<(), Error>

Verify an auth response

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

Reset YubiKey.

WARNING: this is a destructive operation which will destroy all keys!

The reset function is only available when both pins are blocked.

Trait Implementations

impl<'a, '_> TryFrom<&'a Reader<'_>> for YubiKey

type Error = Error

The type returned in the event of a conversion error.

fn try_from(reader: &'a Reader) -> Result<Self, Error>

Performs the conversion.