[](https://deepwiki.com/douzebis/yb)
[](https://crates.io/crates/yb)
# yb — Secure Blob Storage in Your YubiKey
**yb** is a command-line tool for securely storing, retrieving, and managing
binary blobs directly within a [YubiKey](https://www.yubico.com/products/)
using its PIV application. Blobs are stored under human-friendly names,
optionally encrypted with hardware-backed hybrid cryptography.
> **Installing with `cargo install`?** It builds yb from source. On Linux,
> install `pkg-config` and the PC/SC library (pcsclite) first; on NixOS,
> build in a `nix-shell` that provides them. See
> [Installation](#installation). On macOS, nothing extra is needed.
**GitHub**: https://github.com/douzebis/yb
---
## Features
- **Store** binary blobs under human-friendly names (files or stdin)
- **Encrypt** data using hybrid ECDH + HKDF-SHA256 + AES-256-GCM, with the
private key never leaving the YubiKey
- **Sign** every stored blob, its name and metadata included, with a P-256
ECDSA signature for tamper detection
- **Integrity checking** in `fetch`, `list` and `fsck`, no PIN required —
`fetch` refuses a CORRUPTED blob; `list` and `fsck` flag it
- **List**, **fetch**, and **remove** blobs by exact name or glob pattern
- **Multiple YubiKeys** supported via `--serial`
- **Management key kept on the YubiKey**, unlocked by the PIN: writes need
only the PIN
- **Shell completions** for bash, zsh, and fish (dynamic blob-name completion)
- No runtime dependencies beyond PC/SC — a single binary
---
## Installation
### NixOS / Nix
yb is packaged in nixpkgs (which may lag behind crates.io):
```nix
# configuration.nix
environment.systemPackages = [ pkgs.yb ];
services.pcscd.enable = true;
```
Or try it without installing: `nix-shell -p yb`.
Build and install from the repo:
```shell
nix-build
result/bin/yb --help
```
Or enter a development shell with `yb` on `PATH` and shell completions
activated automatically:
```shell
nix-shell
```
### cargo install (Debian, Arch, Fedora, NixOS, macOS, …)
`cargo install` builds yb from source. On Linux, it needs `pkg-config` and
the PC/SC development library; install them first:
```shell
# Debian / Ubuntu
sudo apt install pkgconf libpcsclite-dev
# Arch
sudo pacman -S pkgconf pcsclite
# Fedora
sudo dnf install pkgconf pcsc-lite-devel
# macOS — PC/SC is built into the OS; no extra library needed
```
Then:
```shell
cargo install --locked yb
```
On NixOS, libraries are not installed globally: build in a shell that
provides them, in one step:
```shell
nix-shell -p cargo rustc pkg-config pcsclite --run 'cargo install --locked yb'
```
`--locked` is recommended: it uses the dependency versions yb was tested
with at release time. Plain `cargo install yb` (as shown on crates.io)
works too; it picks the newest compatible versions, which may need a more
recent Rust toolchain than yours.
Runtime requirement: a PC/SC daemon must be running (`pcscd` on Linux; on
NixOS, `services.pcscd.enable = true;`). No other external tools are
needed.
**Troubleshooting:**
- *The build fails with `Could not find a PCSC library` … `The pkg-config
command could not be found`.* `pkg-config` or the PC/SC library is
missing: install them as above (on NixOS, use the `nix-shell` line).
- *`yb --version` answers `No such option: --version`, or `yb ls` reports
`Store has bad object size`.* An older yb (the 0.1.x Python version)
comes first on your `PATH`. Check with `type -a yb`: `cargo install`
puts yb in `~/.cargo/bin`. Remove the old one, or put `~/.cargo/bin`
first on your `PATH`.
> **Man pages:** `cargo install` does not install man pages. To generate
> them locally, run:
>
> ```shell
> cargo install --locked --bin yb-gen-man yb
> yb-gen-man /usr/local/share/man/man1
> ```
>
> Or, if you have the source tree available:
>
> ```shell
> cargo run --manifest-path rust/Cargo.toml --bin yb-gen-man -- /usr/local/share/man/man1
> ```
### Build from source
```shell
git clone https://github.com/douzebis/yb
cd yb/rust
cargo build --release
# Binary is at target/release/yb
```
---
## Shell Completions
yb supports dynamic shell completions — blob names and serial numbers are
completed live against the connected YubiKey.
### bash
```shell
source <(YB_COMPLETE=bash yb | sed 's/yb//2;s/yb//2')
```
Add to `~/.bashrc` for persistence.
### zsh
```shell
YB_COMPLETE=zsh yb > ~/.zfunc/_yb
# Ensure ~/.zfunc is in your fpath, then:
autoload -Uz compinit && compinit
```
### fish
```shell
YB_COMPLETE=fish yb > ~/.config/fish/completions/yb.fish
```
When installed via `nix-build`, completion scripts are installed automatically
into the system completion directories. When using `nix-shell`, bash
completions are activated for the current session automatically.
---
## Quick Start
```shell
# One-time setup, guided: changes a factory PIN/PUK, generates a P-256 key,
# and keeps the management key on the YubiKey, unlocked by the PIN
yb format
# Stash a secret
# Retrieve it
yb fetch -p api-token
# See what's there — signatures verified automatically, no PIN needed
yb ls -l
# Something feels off? Check the store
yb fsck --nvm
```
For full option details: `yb <command> --help` or `man yb`.
---
## PIN Handling
yb resolves the PIN in this order:
1. `--pin-stdin` — reads one line from stdin (for scripting and pipelines)
2. `YB_PIN` environment variable
3. Interactive TTY prompt — deferred until a PIN is actually needed
Commands that never need a PIN (`list`, `fsck` without `--check-key`) never
prompt.
Both perform signature verification using only the public key from the
store's X.509 certificate.
> **Security note:** `YB_PIN` and `--pin-stdin` are convenient for
> scripting but carry OS-level exposure risks. `YB_PIN` is visible to
> child processes and, on some systems, to other users via `/proc`.
> `--pin-stdin` is the safer non-interactive option — pipe the PIN on
> stdin rather than setting an environment variable when possible.
> The default interactive TTY prompt (`rpassword`) has no such exposure.
---
## Cryptographic Model
yb uses a **hybrid encryption scheme**:
1. A fresh ephemeral P-256 key pair is generated for each `store` operation.
2. ECDH between the ephemeral key and the YubiKey's resident P-256 key
produces a shared secret — the YubiKey performs this operation on-card
via GENERAL AUTHENTICATE; the private key never leaves the device.
3. The shared secret is fed into **HKDF-SHA256** to derive an AES-256 key.
4. The blob is encrypted with **AES-256-GCM** (authenticated encryption).
5. The ephemeral public key, nonce, and ciphertext are stored in the YubiKey
PIV objects.
Decryption (`fetch`) reverses steps 2–4, again using the YubiKey for ECDH.
Legacy blobs produced by the Python predecessor (AES-256-CBC, without
authentication) are still readable; `yb fetch` warns about them, and
`yb ls` and `yb fsck` mark them LEGACY. Storing them again encrypts them
with AES-256-GCM.
### Signatures and what they protect against
Every blob is signed with the same YubiKey key (P-256 ECDSA, which needs
the PIN). The signature covers the blob's name, its metadata (key slot,
compression, sizes, modification time) and its stored bytes. `yb fetch`
checks it, using only the public certificate, before writing or
decrypting anything, and refuses a blob whose signature does not match;
`yb ls` and `yb fsck` mark such a blob CORRUPTED.
This protects blobs against anyone who can write PIV objects but cannot
use the PIN: corruption, a leaked or default management key, a tool
writing objects directly. It does not protect against someone who has the
PIN, who can sign anything. In particular, **yb offers no rollback
protection**: a whole store restored to an older, genuinely signed state
cannot be told apart from the current one by the YubiKey alone.
Blobs written before yb 0.3 carry no signature: they are still fetched,
with a warning, and marked UNSIGNED. Storing such a blob again signs it.
---
## Storage Model
yb stores blobs in custom PIV data objects (retired key certificate slots
`0x5F_0000`–`0x5F_0013`). Large blobs are split across multiple objects
using a linked-chunk format. Default store configuration:
| Object count | 32 | Tunable at format time (`--object-count`) |
| Max object size | 3,063 bytes | Each PIV object is written at the size its content requires |
| Gross capacity | up to ~61 KB | Shared with other PIV data; YubiKey 5 NVM pool is 51,200 bytes |
| ECDH key slot | `0x82` | Tunable at format time (`--key-slot`) |
---
## Multiple YubiKeys
```shell
# List connected readers
yb list-readers
# Use a specific YubiKey by serial number
yb --serial 12345678 list
yb --serial 12345678 store secret.txt
```
When multiple YubiKeys are connected and `--serial` is omitted, yb prints
the available serials and exits.
---
## Security: Default Credential Detection
yb checks for factory-default credentials (PIN `123456`, PUK `12345678`,
management key `010203...`). It refuses to store secrets behind a factory
PIN or PUK, and warns elsewhere; `yb fsck` reports them. On a new
YubiKey, the guided `yb format` changes them. To change them without
touching the store:
```shell
ykman piv access change-pin
ykman piv access change-puk
```
For the management key, the convenient approach is to **keep it on the
YubiKey**: it is replaced with a random value stored on the YubiKey itself,
which only your PIN unlocks. You then never need to keep or type the
management key: yb reads it when a write needs it (no `YB_MANAGEMENT_KEY`).
This is a convenience, not extra security. ykman calls this "PIN-protected"
mode. As with ykman, the key is read into the computer's memory for the
write that needs it: PIV authenticates the management key on the host side,
so it cannot stay on the YubiKey. yb holds it in memory that is
overwritten when the write is done.
The guided `yb format` always sets it up. From a script, at format time
(`--protect` keeps a key that is already stored on the YubiKey):
```shell
yb format --generate --protect
```
Or, on a YubiKey already formatted, without touching the store (this also
replaces a key that is already kept on the YubiKey):
```shell
yb rotate-management-key
```
To bypass the default-credential check (testing only): `--allow-defaults` or
`YB_SKIP_DEFAULT_CHECK=1`.
Requires YubiKey firmware 5.3 or later for credential detection.
---
## C Library (libyubiblob)
`rust/yubiblob` builds **libyubiblob**, a C interface to yb's blob store,
for programs that want a small, safe store on a YubiKey without running
the `yb` command: list, fetch, store and remove blobs, with typed status
codes, the PIN passed in memory, and the same guarantees as `yb`
(interrupted writes lose nothing, tampering is detected). It assumes a
YubiKey set up with `yb format`.
```shell
cd rust
cargo cinstall -p yubiblob --release --prefix /usr/local # needs cargo-c
pkg-config --cflags --libs yubiblob
```
The interface, its rules (memory, strings, errors, threads) and its
versioning: [spec 0039](docs/specs/0039-c-api.md). Before 1.0, each
minor version may change the interface.
---
## Format Specification
The yblob binary format is fully documented in
[`docs/YBLOB_FORMAT.md`](docs/YBLOB_FORMAT.md). It is designed to be
implementation-independent: any tool that can read and write YubiKey PIV data
objects can interoperate with a yblob store without using `yb` itself.
---
## File Format Recognition
The yblob binary format is registered in the
[`file` magic database](https://github.com/file/file) (merged June 2025,
[bug #666](https://bugs.astron.com/view.php?id=666)). On any system with an
up-to-date `file` installation, raw PIV object dumps are identified
automatically:
```shell
$ file yubikey_object_dump.bin
yubikey_object_dump.bin: yblob object store image data
```
The magic number is `0xF2ED5F0B` (little-endian u32 at offset 0), present in
every PIV object written by yb.
---
## License
MIT License. See `LICENSE` for full text.