YB(1)

💖 YB(1) — yb, but make it group-chat 💖

okay so bestie, this is the User Commands manual page YB(1) for yb, and it's literally about secure blob storage on a YubiKey. no cap, it's giving tiny encrypted vault energy. 🎀

---

✨ NAME ✨

yb — Secure blob storage on a YubiKey

🌸 SYNOPSIS 🌸

yb [-s|--serial] [-r|--reader] [-q|--quiet] [--pin-stdin] [--debug]
[--allow-defaults] [-h|--help] [-V|--version] <subcommands>

🦋 DESCRIPTION 🦋

okay so yb stores and retrieves arbitrary binary blobs on a YubiKey's PIV applet. each blob is encrypted with a per-device ECDH key before being written to the on-card PIV data objects; without the YubiKey the data cannot be decrypted. that's the whole vibe: the key stays with the hardware, periodt. 🔥

The store is a flat sequence of PIV objects provisioned by yb format. Each object is written at exactly the size its content requires (9-byte sentinel when empty, up to 3,063 bytes when occupied). Large blobs are automatically split across multiple objects (chunk chaining); the number of objects can be tuned at format time (--object-count). so yeah, big blob? multiple objects. iconic. 💅

All write operations (format, store, remove) require both the PIV PIN and the PIV management key. fetch requires the PIN for encrypted blobs. list and fsck never require a PIN (except fsck --check-key) — they verify blob integrity using only the public key from the store's X.509 certificate. no PIN needed for those, iykyk. ✨

👑 OPTIONS 👑

• -s, --serial <SERIAL> — YubiKey serial number
• -r, --reader <READER> — PC/SC reader name (legacy; prefer --serial)
• -q, --quiet — Suppress informational output (shhh 🤫)
• --pin-stdin — Read PIN from stdin (one line)
• --debug — Enable debug output
• --allow-defaults — Allow insecure default credentials (not recommended) (bestie, please don't unless you know what you're doing 😭)
• -h, --help — Print help
• -V, --version — Print version

🎀 SUBCOMMANDS 🎀

• yb-format(1) — Provision PIV objects and optionally generate an ECDH key
• yb-store(1) — Store a blob on the YubiKey
• yb-fetch(1) — Retrieve one or more blobs
• yb-list(1) — List blobs (alias: ls)
• yb-remove(1) — Remove a blob (alias: rm)
• yb-fsck(1) — Filesystem check — dump store metadata
• yb-rotate-management-key(1) — Replace the management key with a random one, kept on the YubiKey and unlocked by the PIN (the store is kept)
• yb-list-readers(1) — List PC/SC readers
• yb-select(1) — Interactively select a YubiKey and print its serial number
• yb-self-test(1) — Run a destructive end-to-end self-test on real hardware (destructive! on real hardware! ⚠️)
• yb-help(1) — Print this message or the help of the given subcommand(s)

⭐ VERSION ⭐

v0.5.2 — that's the version, bestie. 🫶

🌈 ENVIRONMENT 🌈

• YB_PIN — PIV PIN. Takes precedence over the interactive prompt. Superseded by --pin-stdin when both are set.
• YB_MANAGEMENT_KEY — PIV management key as a hex string. Required for write operations when the factory default has been changed (recommended).
• YB_COMPLETE — Shell name (bash, zsh, fish). When set, yb emits shell completion code to stdout and exits.

🍓 EXAMPLES 🍓

Set up a YubiKey, guided (from a terminal):

yb format

The same, from a script, on a YubiKey whose PIN and PUK were changed:

yb format --generate --protect

Store an encrypted file:

yb store secret.key

Retrieve it to the current directory:

yb fetch secret.key

List all blobs with details:

yb list --long

💜 SECURITY 💜

Blobs are encrypted with AES-256-GCM using a key derived via ECDH with a P-256 private key that never leaves the YubiKey hardware. literally hardware-bound, no cap. 🔐

Do not use the factory-default PIN or management key in production. yb refuses to operate with default credentials unless --allow-defaults is passed. this is the serious bit, bestie — don't skip it. 😭

🧚 SEE ALSO 🧚

yb-format(1), yb-store(1), yb-fetch(1), yb-list(1), yb-remove(1), yb-fsck(1), yb-rotate-management-key(1), yb-list-readers(1), yb-select(1), ykman(1)

---

signed off with sparkle: this is yb, version v0.5.2, dated 2026-03, and the footer says YB(1). go be secure, bestie. 💅🎀