black-bag

black-bag is a zero-trace, no-compromise command-line vault for high-risk operators. It ships as a single Rust binary with the strongest defaults we can provide: Argon2id hardening, ML-KEM-1024 cascaded wrapping (Kyber), XChaCha20-Poly1305 payload encryption, zeroization of every secret buffer, and page-locked memory on Unix. There is no optional telemetry, no cloud, no GUI—just a laser-focused CLI that keeps secrets safe even under hostile conditions.

Install

Install the CLI from crates.io (recommended):

cargo install black-bagg

Upgrade to the latest release:

cargo install black-bagg --force

Note: The installed binary is named black-bag.

Alternatively, build from source (see “Building and testing” below).

Post-Quantum Signatures: ML-DSA-87 (at a glance)

ML-DSA-87 is the NIST-standardized module-lattice digital signature scheme (derived from CRYSTALS-Dilithium, highest-security parameter set). In black-bag it provides authenticity for offline vault backups.

• What it is: A post-quantum digital signature (Dilithium Level-5). Public key ≈ 2.6 KiB; signatures ≈ 4.6 KiB.
• What it protects: Ensures a .cbor backup and its keyed integrity tag (.int) came from an authorized signer (no silent tampering).
• How we use it:
  • We compute a BLAKE3 keyed integrity tag .int over the vault bytes, keyed by the embedded ML‑KEM public key (binds tag to the specific vault state).
  • We sign that tag with ML‑DSA‑87, producing .int.sig.
  • Verification requires both .int and .int.sig with the corresponding ML‑DSA public key.
• Commands (preferred PQ flow):
  • Generate keys (one‑time):
    • black-bag backup keygen --pub-out backup.mldsa87.pub --sk-out backup.mldsa87.sk
  • Sign a backup:
    • black-bag backup sign --path /path/to/vault.cbor --key backup.mldsa87.sk --pub-out backup.mldsa87.pub
  • Verify before restore/use:
    • black-bag backup verify --path /path/to/vault.cbor --pub-key backup.mldsa87.pub
• Best practices:
  • Keep backup.mldsa87.sk offline/air‑gapped. Distribute only backup.mldsa87.pub.
  • Always verify both integrity and signature; .int alone only detects bit‑rot.
  • Treat .cbor, .int, and .int.sig as a set; transport them together.

Security Profile (summary)

• KDF: Argon2id (tunable; default 256 MiB, 3 passes, 1 lane)
• Key Encapsulation: ML‑KEM‑1024 (Kyber Level‑5)
• Payload AEAD: XChaCha20‑Poly1305 with domain‑separated AAD
• PQ Signatures: ML‑DSA‑87 (Dilithium Level‑5) for backup authenticity
• Memory Hygiene: zeroization everywhere + mlock on Unix (passphrase/DEK/secret buffers)
• Recovery: Shamir Secret Sharing via vetted sharks (GF(2^8))
• Zero‑trace UX: no secrets in argv/stdout/logs/tmp; atomic writes with strict perms

Highlights

• Zero-trace posture – secrets never touch stdout, logs, temp files, or the clipboard. All input happens via hidden TTY prompts and is stored only after AEAD encryption.
• Modern crypto pipeline – Argon2id → ML-KEM-1024 (Kyber) → random 32-byte DEKs sealed with XChaCha20-Poly1305. Writes are atomic/fdatasync’d with strict permissions and zeroized in memory on drop.
• Rich record catalogue – logins, contacts, identity docs, secure notes, payment cards, SSH keys, PGP keys, TOTP seeds, recovery kits, bank accounts, Wi-Fi profiles, API credentials, and crypto wallets. Every record supports tagging and full-text queries.
• Cross-platform parity – builds cleanly on macOS, Linux, and Windows. mlock is enabled automatically on supported Unix platforms and degrades gracefully elsewhere.
• Security by default – all protective features are enabled in every binary; there are no configuration flags that weaken the threat posture.

Quick Start

# initialize a vault (recommended memory cost: 256 MiB)
black-bag init --mem-kib 262144

# add and list API credentials (secrets collected via hidden prompts)
black-bag add api --service intel-api --environment production --access-key AKIA-123 --scopes read,write
black-bag list --kind api

# inspect a record by UUID (safe default: masked; use --reveal on a TTY)
black-bag get <UUID>
black-bag get <UUID> --reveal

Quick start

# prerequisites: Rust toolchain 1.81+ (via rustup) and a standard build environment
cargo build --release
install -m 0755 target/release/black-bag ~/.local/bin/black-bag

black-bag --help

Recommended hygiene:

• Run from an encrypted disk.
• Disable shell history or use HISTCONTROL=ignorespace with leading spaces.
• Set RUST_BACKTRACE=0 in operational shells.

Creating your vault

black-bag init --mem-kib 262144

You’ll be prompted for the master passphrase twice. The vault stores under the platform data directory (e.g., ~/.config/black_bag/vault.cbor).

Adding records

# login
black-bag add login --title "Ops Portal" --username phoenix --url https://ops.example --tags mission

# contact
black-bag add contact --full-name "Analyst Zero" --emails a0@example --phones "mobile:+1-555-0101,desk:+1-555-0110" --tags handler

# identity document
black-bag add id --id-type passport --name-on-doc "Alex Smith" --number X1234567 --issuing-country US --expiry 2032-08-01

# secure note
black-bag add note --title "Fallback Protocol" --tags red-team

# bank account
black-bag add bank --institution "First Federal" --account-name "Ops budget" --routing-number 021000021 --tags finance

# Wi-Fi profile
black-bag add wifi --ssid "safehouse-net" --security WPA2 --location Berlin --tags infrastructure

# API credential
black-bag add api --service intel-api --environment production --access-key AKIA-123 --scopes read,write --tags automation

# crypto wallet
black-bag add wallet --label btc-cold --asset BTC --address bc1q... --network mainnet --tags treasury

# totp secret
black-bag add totp --title "GitHub MFA" --issuer GitHub --account you@example --secret JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP

# totp codes
black-bag totp code <UUID> --time 59

Sensitive fields (passwords, passphrases, API secrets, private keys) are collected via hidden prompts after the command issues—nothing sensitive ever appears in argv or shell history.

Listing, filtering, and querying

black-bag list                      # masked summaries
black-bag list --kind bank_account  # filter by record family
black-bag list --tag mission        # filter by tag
black-bag list --query opsnet       # full-text search across metadata

Inspect a specific record:

black-bag get <UUID>
black-bag get <UUID> --reveal      # requires an interactive TTY

Rotation, health, and recovery

• black-bag rotate – rewraps the master DEK with fresh randomness.
• black-bag doctor – prints health info (Argon2 params, feature flags, item counts).
• black-bag recovery split / combine – manage Shamir shares for catastrophic recovery.
• black-bag version – display binary version, target, and compiled features (mlock, pq, fuzzing, etc.).
• black-bag backup keygen/sign/verify – manage ML-DSA-87 (or legacy Ed25519) authenticity for offline backups.

CLI Command Reference

Backup workflow (PQ-safe)

# one-time: generate ML-DSA-87 keys for signing sidecars
black-bag backup keygen --pub-out backup.mldsa87.pub --sk-out backup.mldsa87.sk

# copy the ciphertext and immediately mint/update integrity + signature sidecars
cp ~/.config/black_bag/vault.cbor /offline/vault-$(date +%Y%m%d).cbor
black-bag backup sign \
  --path /offline/vault-$(date +%Y%m%d).cbor \
  --key  backup.mldsa87.sk \
  --pub-out /offline/backup.mldsa87.pub

# later, verify both bit-rot and authenticity before restore
black-bag backup verify \
  --path /offline/vault-$(date +%Y%m%d).cbor \
  --pub-key /offline/backup.mldsa87.pub

The signing command produces two companions next to the ciphertext: vault-*.cbor.int (BLAKE3 tag keyed with the ML-KEM public key) and vault-*.cbor.int.sig (ML-DSA-87 or Ed25519 signature). Ship all three files together and treat any verification failure as tampering until proven otherwise.

Rotation, health, and recovery

• black-bag rotate – rewraps the master DEK with fresh randomness.
• black-bag doctor – prints health info (Argon2 params, feature flags, item counts).
• black-bag recovery split / combine – manage Shamir shares for catastrophic recovery.
• black-bag selftest – quick sanity check of encryption/decryption paths.
• black-bag version – confirm binary target/profile and compiled features (mlock, pq, etc.).

Threat model (summary)

See docs/THREAT_MODEL.md for assumptions, adversary capabilities, and residual risks. Treat the vault ciphertext as sensitive and keep backups offline.

Building and testing

cargo fmt
cargo clippy --all-targets --all-features
cargo test

Build from source (alternative install)

Prereqs: Rust toolchain 1.81+ (via rustup) and a standard build environment.

git clone <your-repo-url> black-bag
cd black-bag
cargo build --release
install -m 0755 target/release/black-bag ~/.local/bin/black-bag
black-bag --help

CI should run the same three commands on every commit. Tests cover cryptographic round-trips, helper utilities, and zero-trace guarantees.

Memory Locking (mlock)

On Unix platforms, when built with the default mlock feature, black-bag locks sensitive memory (passphrases, DEKs, and secret buffers) using mlock(2) for the lifetime of those values and unlocks it on drop. This reduces the risk of secrets being paged to disk.

• Status check: black-bag doctor reports whether mlock is enabled and functional on the host.
• macOS: mlock generally works for unprivileged processes within system limits. If you run into failures, check per-process limits with ulimit -l and consider adjusting them in your launch environment.
• Linux: mlock requires sufficient RLIMIT_MEMLOCK or CAP_IPC_LOCK.
  • Temporary session limit (KB): ulimit -l 65536 (example: 64 MiB)
  • Or grant the binary capability (use with care): sudo setcap cap_ipc_lock=+ep $(command -v black-bag)

Notes:

• Locking is best‑effort; when the OS refuses the lock, black-bag continues to function but warns in doctor output. You should raise limits until doctor reports mlock: enabled and working.
• On non‑Unix targets, the mlock feature is ignored and no attempts are made to pin memory.

Doctor JSON fields

black-bag doctor --json | jq

Emits:

• ready (bool): overall health flag
• recordCount (number): number of records
• argonMemKib, argonTimeCost, argonLanes: Argon2id params
• createdAt, updatedAt: RFC3339 timestamps
• mlock.enabled (bool): build/OS support
• mlock.ok (bool): lock/unlock probe succeeded
• mlock.error (string|null): OS error if locking failed

Shamir Secret Sharing

The recovery split / combine commands now use the vetted sharks crate (GF(2^8)) under the hood, keeping the same CLI and share format (id-base64). See docs/SHAMIR.md for details and security notes.

Configuration

• BLACK_BAG_VAULT_PATH: override the default vault path. Useful for testing, multiple vaults, or automation.
• Recommended shell hygiene: HISTCONTROL=ignorespace and avoid pasting secrets into terminals; keep RUST_BACKTRACE=0 in operational shells.

Troubleshooting

• “mlock: enabled but failed (…)” → Raise OS limits (macOS: check ulimit -l; Linux: ulimit -l 65536 or grant CAP_IPC_LOCK).
• “Verify failed” on a backup → Stop; do not restore. Recompute .int and re‑verify with the correct .int.sig and public key.
• “record … not found” → Use black-bag list --query <needle> to locate likely matches, then rerun get.

License

Dual‑licensed under Apache‑2.0 and MIT (your choice). See LICENSE-APACHE and LICENSE-MIT.

Mission-ready checklist

• Argon2id + ML-KEM-1024 + XChaCha20-Poly1305 enabled by default
• No GUI, clipboard, or plaintext log exposure
• Cross-platform parity (Windows/macOS/Linux)
• Comprehensive record catalogue with search & tagging
• Lint/tests clean with zero warnings
• Operator docs and threat model committed

For production roll-out, schedule an independent cryptography/code audit and set up fuzzing pipelines (see docs/FURTHER_HARDENING.md).