yb_core/lib.rs
1// SPDX-FileCopyrightText: 2025 - 2026 Frederic Ruget <fred@atlant.is> <fred@s3ns.io> (GitHub: @douzebis)
2// SPDX-FileCopyrightText: 2025 - 2026 Thales Cloud Sécurisé
3//
4// SPDX-License-Identifier: MIT
5
6//! Core library for `yb` — secure blob storage on a YubiKey.
7//!
8//! # Quick start
9//!
10//! ```no_run
11//! use yb_core::{store::Store, orchestrator, Context, ContextOptions, OutputOptions};
12//!
13//! let ctx = Context::new(ContextOptions { pin: Some("123456".into()), ..Default::default() }, Box::new(|| Ok(None)), Box::new(|_, _| Ok(None)), OutputOptions::default())?;
14//! let store = Store::from_device(&ctx.reader, ctx.piv.as_ref())?;
15//! for blob in orchestrator::list_blobs(&store) {
16//! println!("{} ({} bytes)", blob.name, blob.plain_size);
17//! }
18//! let data = orchestrator::fetch_blob(
19//! &store, ctx.piv.as_ref(), &ctx.reader, "my-secret", ctx.require_pin()?.as_deref(), false,
20//! )?;
21//! # Ok::<(), anyhow::Error>(())
22//! ```
23//!
24//! # Features
25//!
26//! | Feature | Purpose | Default |
27//! |---|---|---|
28//! | `chrono` | `BlobInfo::mtime_local()` convenience method | No |
29//! | `virtual-piv` | `VirtualPiv` in-memory backend for testing | No |
30//! | `integration-tests` | vsmartcard + piv-authenticator tests | No |
31//! | `hardware-tests` | Real YubiKey destructive tests | No |
32//!
33//! # Security note
34//!
35//! Private key material on the YubiKey is never extracted. ECDH key
36//! agreement is performed on-card via the PIV GENERAL AUTHENTICATE command.
37
38pub mod auxiliaries;
39pub mod crypto;
40
41pub mod context;
42pub mod nvm;
43pub mod orchestrator;
44pub mod piv;
45pub mod store;
46
47pub use context::{
48 parse_ec_public_key_from_cert_der, Context, ContextOptions, DevicePicker, OutputOptions,
49};
50pub use nvm::{scan_nvm, NvmUsage};
51pub use orchestrator::{
52 chunks_needed, collect_blob_chain, fetch_blob, list_blobs, remove_blob, store_blob, BlobInfo,
53 Compression, Encryption, StoreOptions,
54};
55pub use piv::hardware::HardwarePiv;
56#[cfg(any(feature = "virtual-piv", feature = "test-utils"))]
57pub use piv::VirtualPiv;
58pub use piv::{DeviceInfo, FlashHandle, PivBackend};
59
60#[cfg(any(test, feature = "test-utils"))]
61pub mod test_utils;