Struct Context 

pub struct Context {
    pub reader: String,
    pub serial: u32,
    pub firmware: String,
    pub management_key: Option<Zeroizing<String>>,
    pub defaults: DefaultCredentials,
    pub allow_defaults: bool,
    pub pin_fn: Box<dyn Fn() -> Result<Option<String>>>,
    pub piv: Arc<dyn PivBackend>,
    pub debug: bool,
    pub quiet: bool,
    pub protection: ProtectionMode,
    pub flash_handle: Option<Box<dyn FlashHandle>>,
    /* private fields */
}

Fields

reader: String

serial: u32

firmware: String

Firmware version of the selected YubiKey, as reported by the device list (e.g. “5.4.3”). Only the unexpected-error report uses it.

management_key: Option<Zeroizing<String>>

Held in zeroizing memory (spec 0034 G1).

defaults: DefaultCredentials

Which factory-default credentials were still active at startup.

allow_defaults: bool

--allow-defaults: the default-credential policy warns instead of refusing (spec 0024 §3).

pin_fn: Box<dyn Fn() -> Result<Option<String>>>

Called by require_pin() when pin is still None. Returns Some(pin) if it can supply one, None otherwise.

piv: Arc<dyn PivBackend>

debug: bool

quiet: bool

protection: ProtectionMode

How the management key is protected, from ADMIN DATA at startup.

flash_handle: Option<Box<dyn FlashHandle>>

Optional flash handle passed in from the interactive device picker. Kept alive so the LED continues to flash into the next prompt. Consumed by Context::take_flash.

Implementations

impl Context

pub fn new( opts: ContextOptions, pin_fn: Box<dyn Fn() -> Result<Option<String>>>, device_picker: DevicePicker, output: OutputOptions, ) -> Result<Self>

Build a Context from global CLI options, selecting the device.

pin is the PIN resolved from non-interactive sources (env var, stdin, deprecated flag). pin_fn is called by require_pin() the first time a PIN is needed and pin is still None — typically a TTY prompt closure supplied by the application layer.

pub fn with_backend( backend: Arc<dyn PivBackend>, pin: Option<String>, debug: bool, ) -> Result<Self>

Build a Context from an explicit PIV backend.

Use this when you have a VirtualPiv (for tests) or any other custom PivBackend implementation. The backend must expose exactly one device; if it exposes none or more than one, an error is returned.

The card is probed exactly as by Context::new (default credentials, protection mode). allow_defaults starts false.

pub fn require_pin(&self) -> Result<Option<String>>

Return the PIN, invoking pin_fn on first call if not yet resolved.

Resolution order:

1. Already-cached PIN (from a non-interactive source or a prior call).
2. pin_fn() — supplied by the caller of Context::new; typically a TTY prompt closure in the application layer. The result is cached so subsequent calls never invoke pin_fn again.
3. None — the caller must decide whether to error.

pub fn known_pin(&self) -> Option<String>

The PIN known so far (from a non-interactive source, the factory default, or an earlier prompt), without prompting.

pub fn set_pin(&self, pin: &str)

Replace the cached PIN, e.g. after changing it on the card.

pub fn clear_secrets(&self)

Forget the PIN and the resolved management key, overwriting them in memory. Library sessions hold secrets for one call only (spec 0039 G5).

pub fn refresh_defaults(&mut self)

Detect the factory-default credentials again, after changing some of them (spec 0023 §6).

pub fn enforce_default_policy(&self, op: SecretOp) -> Result<Vec<String>>

Apply the default-credential policy for op (spec 0024): refuse with Err, or return the warnings that apply, printed unless --quiet. Call once per command, before its first card write.

pub fn ensure_supported_protection(&self) -> Result<()>

Fail if the card’s management key protection is one yb cannot write with (PIN-derived, or unparseable ADMIN DATA).

pub fn management_key_for_write(&self) -> Result<Zeroizing<String>>

Return the management key to use for write operations, after checking that the card accepts it (spec 0022 §1 step 4).

This is the single place in yb that reads PRINTED for a key. The first candidate the card accepts wins:

1. the explicit key (YB_MANAGEMENT_KEY) — if rejected, fail;
2. PRINTED tag 89, then tag 8A (kept during a key switch), when a PIN is available — whatever the ADMIN DATA flags say;
3. the factory default.

A key found in PRINTED may leave repairs due (see Repairs), carried out by Context::complete_pending_repairs. The result is cached for the rest of the invocation.

pub fn management_key_protected(&self) -> Result<bool>

Whether the management key is already PIN-protected (spec 0023 §3a): PRINTED tag 89 holds the key the card accepts, however that key was obtained. The factory key never counts as protected.

Resolves the management key first. When the key was given explicitly, PRINTED is read with the PIN, and the repairs a protected card needs (legacy flag, leftover tag 8A) are recorded as for a key read from PRINTED.

pub fn management_key_in_printed(&self) -> Result<bool>

Whether PRINTED holds the resolved management key, in tag 89 or 8A, whatever the key’s source (spec 0027 §3a). A failed key switch puts it back there.

pub fn management_key_source(&self) -> Option<KeySource>

Where the resolved management key came from, once resolved.

pub fn pending_repairs(&self) -> Repairs

Repairs due from the management key resolution (none before it).

pub fn complete_pending_repairs(&self)

Carry out the repairs found by Context::management_key_for_write: rewrite ADMIN DATA in the standard layout (spec 0021 §4) and/or clean up PRINTED (spec 0022 §1 step 4).

Call once the command’s own writes have succeeded. A failure is a warning and does not fail the command: the next write retries.

pub fn check_slot_key(&self, slot: u8) -> Result<SlotKeyCheck>

Check that the key in slot matches the public key in the slot’s certificate, by signing a random digest and verifying the signature (spec 0022 §1 step 5). Needs the PIN.

pub fn take_flash(&mut self) -> Option<Box<dyn FlashHandle>>

Take the flash handle passed in from the interactive device picker.

Returns Some(handle) the first time it is called (if the picker provided one), and None on all subsequent calls. The LED stops flashing when the returned handle is dropped.

pub fn get_public_key(&self, slot: u8) -> Result<PublicKey>

Retrieve the YubiKey’s public key from the given PIV slot.