yb — Secure Blob Storage in Your YubiKey

Rust port in progress. The current implementation is in Python. A full rewrite in Rust is underway (see docs/rust-port-plan.md). The crate name yb on crates.io is reserved for that release. Once the port is complete, cargo install yb will be the recommended installation method and the Python implementation will be retired.

yb is a command-line tool for securely storing, retrieving, and managing small binary blobs directly within a YubiKey using its PIV application. It enables encrypted, name-based storage with hybrid cryptography, leveraging the hardware-backed security of your YubiKey.

GitHub: https://github.com/douzebis/yb

Features

• Store binary blobs under human-friendly names
• Encrypt data using hybrid ECDH + AES-256 encryption with a YubiKey-stored key
• List, fetch, and delete blobs by name
• Inspect low-level object storage for debugging (fsck)
• Designed for use with custom PIV data objects on the YubiKey

Getting Started

Installation (Rust — coming soon)

Once the Rust port is complete, the recommended installation will be:

cargo install yb

Runtime tools must also be on your PATH: yubico-piv-tool, pkcs11-tool (from opensc), openssl, and ykman.

Installation (NixOS)

Choose one of the following:

# Option 1: Enter a dev environment with dependencies installed via nix-shell
nix-shell

# Option 2: Use nix develop (installs into a .venv for editing)
nix-shell shell-editable.nix

# Option 3: Build the yb derivation (does not activate environment)
nix-build

Installation (Traditional Python)

# Create and activate a virtual environment
python3.12 -m venv .venv
source .venv/bin/activate

# Install in editable mode
pip install --editable .

Command Overview

yb format     # Initialize PIV objects and optionally generate key pair
yb store      # Store a named blob in the YubiKey
yb fetch      # Retrieve a blob by name
yb ls         # List stored blobs and metadata
yb rm         # Delete a blob by name
yb fsck       # Inspect and verify object integrity
yb self-test  # Run comprehensive end-to-end tests (destructive)

Use --help with any command for detailed options.

Cryptographic Model

yb uses a hybrid encryption scheme:

• An ephemeral EC P-256 key is generated on each store or fetch call
• A persistent P-256 key in the YubiKey is used for ECDH
• The derived shared secret feeds into HKDF-SHA256, producing an AES-256 key
• Blob data is encrypted using AES-CBC with PKCS7 padding
• Encrypted chunks are stored in custom PIV objects

Example Usage

# Format the store (initialize objects and key)
yb format --generate

# Store a file as a secure blob
yb store --input my-secret.txt my-blob

# Fetch it back
yb fetch --output recovered.txt my-blob
# Please enter User PIN:

# List blobs
yb ls

# Delete a blob
yb rm my-blob

Working with Multiple YubiKeys

If you have multiple YubiKeys, use the --serial option to select which one to use:

# Select YubiKey by serial number (printed on device case)
yb --serial 12345678 ls

# Store a blob on a specific YubiKey
yb --serial 12345678 store --input data.txt my-blob

Finding Your Serial Number:

• Look at your YubiKey case - the serial number is printed on it
• Or let yb tell you when multiple devices are connected

When multiple YubiKeys are connected and you don't specify --serial, yb will show you the available serial numbers:

Error: Multiple YubiKeys are connected:
  - Serial 12345678 (YubiKey 5.7.1)
  - Serial 87654321 (YubiKey 5.4.3)

Use --serial to select one, for example:
  yb --serial 12345678 <command>

Legacy Option: The --reader option is still supported for PC/SC reader names, but --serial is recommended.

Security: Default Credential Detection

For security, yb automatically checks if your YubiKey uses default credentials and refuses to operate if detected:

• Default PIN: 123456
• Default PUK: 12345678
• Default Management Key: 010203040506070801020304050607080102030405060708

If your YubiKey uses any default credentials, yb will display an error like:

Error: YubiKey is using default credentials (INSECURE):
  - PIN (default: 123456, 3 attempts remaining)
  - Management Key (default: 010203...)

This is a security risk. Please change your YubiKey credentials:
  - Change PIN: ykman piv access change-pin
  - Change PUK: ykman piv access change-puk
  - Change Management Key (recommended with PIN-protected mode):
    ykman piv access change-management-key --generate --protect

To proceed anyway (NOT RECOMMENDED), use --allow-defaults flag.

Changing Your Credentials:

# Change PIN
ykman piv access change-pin

# Change PUK
ykman piv access change-puk

# Change Management Key (recommended with PIN-protected mode)
ykman piv access change-management-key --generate --protect

Note: This check requires YubiKey firmware 5.3 or later. On older firmware, yb will display a warning but continue.

For Testing/Development:

• Use --allow-defaults flag to bypass the check (insecure)
• Set YB_SKIP_DEFAULT_CHECK=1 environment variable to skip the check entirely

PIN-Protected Management Key Mode

For enhanced security and convenience, yb supports PIN-protected management key mode. This allows YubiKeys to store the management key on-device, encrypted and protected by your PIN.

Why use PIN-protected mode?

• ✓ More secure than default management key
• ✓ More convenient - no need to provide 48-char hex key
• ✓ You only need to remember your PIN
• ✓ Management key never leaves the YubiKey

One-time setup:

ykman piv access change-management-key --generate --protect

Usage: yb automatically detects PIN-protected mode - no --key flag needed:

yb store myfile           # Prompts for PIN if needed
yb --pin 123456 store     # Non-interactive

See the User Guide for more details.

License

MIT License. See LICENSE for full text.