black-bagg 0.3.3

Ultra-secure, zero-trace, pure-Rust CLI vault for spies, journalists, and privacy maximalists.
Documentation

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

Command Purpose Notes
black-bag init [--mem-kib <KiB>] Create a new vault with Argon2id + ML-KEM-1024 wrapping Default memory cost: 262 144 KiB (256 MiB)
black-bag add <record-type> [...] Add login/contact/id/note/bank/wifi/api/wallet/totp/ssh/pgp/recovery records Sensitive fields captured via hidden prompts
black-bag list [--kind KIND] [--tag TAG] [--query Q] Show masked summaries Combine filters for scoped audits
black-bag get <UUID> [--reveal] Inspect records; optionally reveal secrets on a TTY --reveal denied on non-interactive stdout
black-bag totp code <UUID> [--time <UNIX>] Generate TOTP codes Supports historic/time-skew analysis
black-bag rotate [--mem-kib <KiB>] Rewrap master DEK with fresh randomness Optional Argon2 memory override
black-bag doctor [--json] Print health diagnostics JSON output ready for monitoring pipelines
black-bag recovery split/combine Manage Shamir shares for disaster recovery Configurable thresholds and share counts
black-bag backup keygen/sign/verify Manage ML-DSA-87 (or Ed25519) backup signatures Produces .int + .int.sig companions
black-bag selftest Run embedded round-trip checks Useful after upgrades or migrations
black-bag version Display build version, target, and enabled features (mlock, pq, fuzzing) Validate release binaries

Comprehensive CLI Details

Below is a complete list of subcommands, flags, and inputs.

Common

  • Global env: BLACK_BAG_VAULT_PATH overrides default vault location.
  • Hidden prompts: sensitive values are collected interactively (no echo), never via argv.

Init

  • black-bag init [--mem-kib <KiB>]
    • --mem-kib: Argon2 memory (KiB). Default: 262144 (256 MiB). Minimum: 32768.
    • Prompts: master passphrase (twice).

Add (records)

  • Common flags (all add ):
    • --title <string>
    • --tags <t1,t2,...> (comma separated)
    • --notes <string>
  • Login: black-bag add login [--username <s>] [--url <s>]
    • Prompts: Password: (hidden)
  • Contact: black-bag add contact --full-name <s> [--emails <e1,e2,...>] [--phones <p1,p2,...>]
  • Id: black-bag add id [--id-type <s>] [--name-on-doc <s>] [--number <s>] [--issuing-country <s>] [--expiry <s>]
    • Prompts: Sensitive document secret (optional): (hidden, optional)
  • Note: black-bag add note
    • Prompts: Secure note body (Ctrl-D to finish): (multiline)
  • Bank: black-bag add bank [--institution <s>] [--account-name <s>] [--routing-number <s>]
    • Prompts: Account number / secret: (hidden)
  • Wifi: black-bag add wifi [--ssid <s>] [--security <s>] [--location <s>]
    • Prompts: Wi-Fi passphrase: (hidden)
  • Api: black-bag add api [--service <s>] [--environment <s>] [--access-key <s>] [--scopes <s1,s2,...>]
    • Prompts: Secret key: (hidden)
  • Wallet: black-bag add wallet [--asset <s>] [--address <s>] [--network <s>]
    • Prompts: Wallet secret material: (hidden)
  • Totp: black-bag add totp [--issuer <s>] [--account <s>] [--secret <BASE32>] [--digits <6|7|8>] [--step <seconds>] [--skew <steps>] [--algorithm <sha1|sha256|sha512>]
    • If --secret omitted, prompts: Base32 secret: (hidden)
    • Defaults: --digits 6, --step 30, --skew 1, --algorithm sha1
  • Ssh: black-bag add ssh [--label <s>] [--comment <s>]
    • Prompts: Paste private key (Ctrl-D to finish): (multiline, hidden)
  • Pgp: black-bag add pgp [--label <s>] [--fingerprint <s>]
    • Prompts: Paste armored private key (Ctrl-D to finish): (multiline, hidden)
  • Recovery: black-bag add recovery [--description <s>]
    • Prompts: Paste recovery payload (Ctrl-D to finish): (multiline, hidden)

List / Query

  • black-bag list [--kind <login|contact|id|note|bank|wifi|api|wallet|totp|ssh|pgp|recovery>] [--tag <needle>] [--query <needle>]
    • Outputs masked summaries. Combine filters for precise audits.

Get

  • black-bag get <UUID> [--reveal]
    • Shows metadata; with --reveal on a TTY prints sensitive fields.

Rotate

  • black-bag rotate [--mem-kib <KiB>]
    • Rewraps DEK with fresh randomness; optionally adjust Argon2 memory (min 32768).

Doctor

  • black-bag doctor [--json]
    • Human output or JSON with readiness + mlock probe results.

TOTP

  • black-bag totp code <UUID> [--time <UNIX-seconds>]
    • Generates a code for a stored TOTP secret; --time allows historic checks.

Backup (integrity + PQ signatures)

  • Keygen (ML‑DSA‑87):
    • black-bag backup keygen --pub-out <path> --sk-out <path>
    • Writes Base64 public key and public||secret concatenated secret blob.
  • Sign:
    • black-bag backup sign --path <vault.cbor> --key <secret-key> [--pub-out <path>]
    • Creates/updates: <vault>.int (BLAKE3 keyed tag) + <vault>.int.sig (ML‑DSA‑87 or Ed25519).
  • Verify:
    • black-bag backup verify --path <vault.cbor> [--pub-key <pub-key>]
    • With --pub-key, verifies both integrity and signature. Without it, checks only bit‑rot.

Self‑test

  • black-bag selftest
    • Runs an encrypt/decrypt round‑trip sanity check.

Version

  • black-bag version
    • Prints version, target, and compiled features (mlock, pq, etc.).

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).

Instruction Manual (Verbatim)

The following section contains the full instruction manual, verbatim.

Black-Bagg  CLI  Vault  System:  Instruction  
Manual
Table of Contents
1. Introduction
2. Installation
3. Basic Vault Operations
• Initializing a New Vault
• Adding Records (Login, Note, Contact, etc.)
• Listing Records
• Retrieving Records
4. Advanced Features
• Master Key Rotation ( rotate )
• Health Diagnostics ( doctor )
• Shamir Secret Sharing ( recovery )
• Time-Based One-Time Passwords ( totp )
5. Backup and Restore with ML-DSA-87 Signatures
• Generating ML-DSA-87 Keypairs
• Creating and Signing Backups
• Verifying Backups
6. Best Practices, Security Considerations, and Troubleshooting
7. Conclusion
1. Introduction
Black-Bagg is an ultra-secure, zero-trace command-line interface (CLI) vault system 
designed for managing sensitive information. It leverages modern cryptographic primitives 
and secure development practices to protect various types of records, including notes, 
login credentials, and Time-Based One-Time Password (TOTP) secrets. A key feature of 
Black-Bagg is its integration of ML-DSA-87 (Machine Learning-based Digital Signature 
Algorithm) for ensuring the integrity and authenticity of vault backups, providing post-
quantum security. This manual will guide you through the installation, usage, and 
advanced features of Black-Bagg, helping you to effectively secure your digital assets.
2. Installation
To install Black-Bagg, you will first need to set up the Rust programming language 
environment, which includes the cargo  package manager. Black-Bagg is written in Rust and 
distributed as a crate.
2.1. Install Build Dependencies
Black-Bagg, like many Rust applications, may require certain system-level build tools. On 
Debian-based Linux distributions (like Ubuntu), these can be installed using apt :
Bash
sudo apt update
sudo apt install -y build-essential
This command installs essential compilers and libraries required for building software from 
source.
2.2. Install Rust and Cargo
Rust can be installed using rustup , the official Rust installer. Open your terminal and run 
the following command:
Bash
curl --proto =https --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
This script downloads and installs the latest stable version of Rust and its package manager, 
Cargo. The -y  flag automatically confirms the installation options.
After the installation completes, you need to update your shell's PATH environment 
variable to include Cargo's binary directory. You can do this by sourcing the env  file:
Bash
source $HOME/.cargo/env
To verify that Rust and Cargo are installed correctly, you can check their versions:
Bash
cargo --version
rustc --version
2.3. Install Black-Bagg Crate
Once Rust and Cargo are set up, you can install Black-Bagg directly from crates.io using 
Cargo:
Bash
cargo install black-bagg
This command compiles the black-bagg  crate and places the executable in your ~/.cargo/bin  
directory. The executable is named black-bag  (note the single g ).
To confirm the installation and view available commands, run:
Bash
~/.cargo/bin/black-bag --help
It is recommended to add ~/.cargo/bin  to your system's PATH permanently by adding 
source $HOME/.cargo/env  to your shell's configuration file (e.g., ~/.bashrc , ~/.zshrc ) to avoid 
typing the full path every time you use black-bag .
3. Basic Vault Operations
This section covers the fundamental operations for managing your Black-Bagg vault, 
including initialization, adding various types of records, and retrieving stored information.
3.1. Initializing a New Vault
Before you can store any sensitive information, you must initialize a new vault. This process 
creates an encrypted container for your data and sets your master passphrase, which is the 
primary key to unlock and access your vault.
To initialize a new vault, use the init  command:
Bash
black-bag init
The system will then prompt you to enter and confirm your master passphrase. Choose a 
strong, unique passphrase that you can remember. This passphrase is crucial for the 
security of your vault, and its loss means irreversible loss of your data.

Plain Text
Master passphrase: 
Confirm passphrase: 
Initialized vault at /home/your_user/.config/black_bag/vault.cbor
If a vault already exists at the default location ( ~/.config/black_bag/vault.cbor ), the init  
command will return an error. You must remove the existing vault file before initializing a 
new one if you wish to start fresh.
3.2. Adding Records
Black-Bagg supports various types of records, each tailored for specific kinds of sensitive 
information. You can add records using the add  subcommand, followed by the record type 
(e.g., login , note , contact ). Each add  operation will require your master passphrase.
To see all available record types, use:
Bash
black-bag add --help
3.2.1. Adding a Secure Note
Secure notes are versatile for storing any text-based sensitive information. To add a note:
Bash
black-bag add note --title "My Secret Note" --notes "Optional metadata notes"
The system will prompt for your master passphrase, and then for the body of your secure 
note. Type your note content and press Ctrl+D (on Linux/macOS) or Ctrl+Z  then Enter  (on 
Windows) to finish input.
Plain Text
Master passphrase: 
Secure note body (Ctrl-D to finish): 
This is the content of my secret note.
Record added
3.2.2. Adding a Login/Password Record
For storing website or service credentials:

Bash
black-bag add login --title "My Website Login" --username "myuser" --
password "mypassword" --url "https://example.com"
Alternatively, you can omit --username  or --password  to be prompted securely. The system 
will prompt for your master passphrase and any missing details.
3.2.3. Adding Other Record Types
Explore other add  subcommands for specific data types:
• black-bag add contact : Store contact information.
• black-bag add id : Store identity document details.
• black-bag add bank : Store bank account information.
• black-bag add wifi: Store Wi-Fi network credentials.
• black-bag add api : Store API credentials.
• black-bag add wallet : Store cryptocurrency wallet details.
• black-bag add ssh : Store SSH keys.
• black-bag add pgp : Store PGP keys.
• black-bag add recovery : Store recovery kits.
Each of these commands follows a similar interactive pattern, prompting for necessary 
details and your master passphrase.
3.3. Listing Records
To view a masked summary of all records stored in your vault, use the list  command:
Bash
black-bag list
The system will prompt for your master passphrase. The output will display a unique UUID, 
record type, title, and any tags for each entry. Sensitive content (like passwords or note 
bodies) will be hidden by default to prevent accidental exposure.
Plain Text
Master passphrase: 
UUID                                 | type  | title            | tags      
| summary
-------------------------------------|-------|------------------|-----------
|------------------
b819ad9e-33d7-4d34-b931-14212d687e7e | note  | My Secret Note   | tags=[]   
| secure note
7bbe0fcd-2782-470d-b913-1400431cd56d | login | My Website Login | tags=[]   
| username=myuser
3.4. Retrieving Records
To inspect the full details of a specific record, including its sensitive content, use the get  
command with the record's UUID. You will need to provide your master passphrase.
Bash
black-bag get <UUID>
By default, sensitive fields will still be hidden. To reveal the full content, including the note 
body or password, you must use the --reveal  flag. This will again prompt for your master 
passphrase, adding an extra layer of security.
Bash
black-bag get b819ad9e-33d7-4d34-b931-1400431cd56d --reveal
Example output for a revealed note record:
Plain Text
Master passphrase: 
id: b819ad9e-33d7-4d34-b931-14212d687e7e
kind: note
title: My Secret Note
note:
This is the content of my secret note.
This two-step process for viewing sensitive data ensures that your information is protected 
even if someone gains temporary access to your terminal session.
4. Advanced Features
Black-Bagg includes several advanced features designed to enhance security, facilitate 
recovery, and provide utility for managing time-based one-time passwords.
4.1. Master Key Rotation ( rotate )
Regularly rotating your master key is a crucial security practice. The rotate  command 
allows you to re-encrypt your vault's master key with fresh randomness, enhancing its 
resilience against potential long-term cryptanalysis or compromise.
To rotate your master key:
Bash
black-bag rotate
The system will prompt you for your current master passphrase. After successful 
authentication, the rotation process will complete, and your vault's master key will be 
updated.
Plain Text
Master passphrase: 
Rotation complete
It is recommended to perform master key rotation periodically, especially after any 
suspected compromise or if you have been using the same master passphrase for an 
extended period.
4.2. Health Diagnostics ( doctor )
The doctor  command provides a comprehensive health check and diagnostic overview of 
your Black-Bagg vault. This helps you verify the operational status of your vault and its 
security mechanisms.
To run the diagnostics:
Bash
black-bag doctor
You will be prompted for your master passphrase. The output will include information such 
as:
Plain Text
Master passphrase: 
status: ready
records: 3
created: 2025-09-28 12:47:08.067102334 UTC
updated: 2025-09-28 12:52:31.043836811 UTC
argon2: mem=262144 KiB, time=3, lanes=1
mlock: enabled and working
Key information provided by doctor :
• status : Indicates if the vault is accessible and healthy.
• records : The total number of records stored in the vault.
• created / updated: Timestamps for vault creation and last modification.
• argon2 parameters: Details about the Argon2 key derivation function settings, which 
determine the computational cost of deriving your master key and its resistance to 
brute-force attacks.
• mlock  status: Confirms if memory locking is enabled and working. Memory locking 
prevents sensitive data (like your master key) from being written to disk (e.g., swap file), 
protecting against cold boot attacks.
4.3. Shamir Secret Sharing ( recovery )
Black-Bagg implements Shamir's Secret Sharing (SSS) to allow you to split a secret (e.g., 
your master passphrase or any other critical piece of information) into multiple shares. A 
predefined number of these shares (the threshold) are required to reconstruct the original 
secret. This is ideal for disaster recovery or distributing trust.
4.3.1. Splitting a Secret ( recovery split )
To split a secret into shares:
Bash
black-bag recovery split --threshold <THRESHOLD> --shares <TOTAL_SHARES>
Replace <THRESHOLD>  with the minimum number of shares required to reconstruct the 
secret, and <TOTAL_SHARES>  with the total number of shares to generate. For example, to 
create 3 shares where any 2 can reconstruct the secret:
Bash
black-bag recovery split --threshold 2 --shares 3
The system will prompt you for the secret you wish to split, followed by your master 
passphrase. It will then output the generated shares.
Plain Text
Secret to split: 
my_recovery_secret
Master passphrase: 
1-Qfln2/tfY8j6TlB0zGO9ixcx
2-NWQvPUQbdxdGCisJEGnCnYH+
3-GeQXlNone6nZNgIir28cZPO7
Store these shares securely and separately. Remember that if you lose more shares than 
TOTAL_SHARES - THRESHOLD, you will not be able to recover your secret.
4.3.2. Combining Shares ( recovery combine )
To reconstruct a secret from its shares, use the recovery combine  command. You must 
provide at least the THRESHOLD number of shares.
Bash
black-bag recovery combine --threshold <THRESHOLD> --shares "<SHARE1>,
<SHARE2>,..."
For example, to combine two shares from the previous example:
Bash
black-bag recovery combine --threshold 2 --shares "1-
Qfln2/tfY8j6TlB0zGO9ixcx,2-NWQvPUQbdxdGCisJEGnCnYH+"
The system will prompt for your master passphrase and then output the reconstructed 
secret:
Plain Text
Master passphrase: 
my_recovery_secret
4.4. Time-Based One-Time Passwords ( totp)
Black-Bagg can securely store TOTP secrets and generate one-time codes for two-factor 
authentication (2FA).
4.4.1. Adding a TOTP Secret ( add totp)
To add a new TOTP secret to your vault:

Bash
black-bag add totp --title "My Service 2FA" --secret "<BASE32_SECRET>" --
issuer "MyService" --account "myuser@example.com"
Replace <BASE32_SECRET>  with the base32-encoded secret key provided by the service you 
are setting up 2FA for. If you omit --secret , you will be prompted to enter it securely. The 
system will also prompt for your master passphrase.
Note: The secret must be at least 128 bits (20 bytes) long when base32 encoded. A common 
error is providing a secret that is too short.
4.4.2. Generating a TOTP Code ( totp code )
Once a TOTP secret is stored, you can generate a current one-time password using its UUID:
Bash
black-bag totp code <TOTP_RECORD_UUID>
For example, if your TOTP record has the UUID 7bbe0fcd-2782-470d-b913-1400431cd56d :
Bash
black-bag totp code 7bbe0fcd-2782-470d-b913-1400431cd56d
After entering your master passphrase, the system will display the current TOTP code and 
its remaining time-to-live (TTL):
Plain Text
Master passphrase: 
code: 042262
ttl: 23s
This allows you to securely generate 2FA codes directly from your Black-Bagg vault.
5. Backup and Restore with ML-DSA-87 Signatures
Black-Bagg provides robust mechanisms for backing up your vault and ensuring its integrity 
and authenticity using ML-DSA-87 (Machine Learning-based Digital Signature Algorithm) for 
post-quantum security.
5.1. Generating ML-DSA-87 Keypairs
To sign and verify your vault backups, you first need to generate an ML-DSA-87 keypair. This 
consists of a public key (for verification) and a secret key (for signing).
Bash
black-bag backup keygen --pub-out /path/to/ml_dsa_public.key --sk-out 
/path/to/ml_dsa_secret.key
Replace /path/to/ml_dsa_public.key  and /path/to/ml_dsa_secret.key  with your desired file 
paths for the public and secret keys, respectively. The system will prompt for your master 
passphrase to authorize the key generation.
Plain Text
Master passphrase: 
Generated ML-DSA-87 keypair
Store your ml_dsa_secret.key  securely, as it is essential for signing backups. The 
ml_dsa_public.key  can be stored less securely or distributed, as it only allows verification.
5.2. Creating and Signing Backups
Creating a backup involves two steps: copying your vault file and then signing it with your 
ML-DSA-87 secret key.
5.2.1. Copying the Vault File
Your Black-Bagg vault is stored as an encrypted file, typically at 
~/.config/black_bag/vault.cbor . To create a backup, simply copy this file to a safe location:
Bash
cp ~/.config/black_bag/vault.cbor 
/path/to/your_backup_directory/vault_backup.cbor
5.2.2. Signing the Backup
To ensure the integrity and authenticity of your backup, sign it using your ML-DSA-87 secret 
key:
Bash
black-bag backup sign --path 
/path/to/your_backup_directory/vault_backup.cbor --key 
/path/to/ml_dsa_secret.key
This command will prompt for your master passphrase. Upon successful execution, it will 
create a signature sidecar file (e.g., vault_backup.cbor.sig ) alongside your backup file.
Plain Text
Master passphrase: 
Wrote ML-DSA-87 signature sidecar
This signature cryptographically binds the backup file to your secret key, proving its origin 
and ensuring it hasn't been tampered with.
5.3. Verifying Backups
Before restoring a backup, it is crucial to verify its integrity and authenticity using your ML-
DSA-87 public key. This step ensures that the backup is legitimate and has not been 
corrupted or maliciously altered.
Bash
black-bag backup verify --path 
/path/to/your_backup_directory/vault_backup.cbor --pub-key 
/path/to/ml_dsa_public.key
This command will prompt for your master passphrase. If the backup is intact and the 
signature is valid, you will see the following output:
Plain Text
Master passphrase: 
Integrity and signature verified
If the verification fails, it indicates that the backup file has been altered or is not authentic. 
Do not use a backup that fails verification.
5.4. Restoring a Vault from Backup
To restore your vault from a verified backup:
1. Ensure the backup is verified: Always perform the black-bag backup verify  step first.
2. Close Black-Bagg: Ensure no black-bag  processes are running.
3. Replace the vault file: Copy the verified backup file over your existing (or missing) vault 
file:
After replacing the file, your Black-Bagg vault will be restored to the state of the backup. You 
can then use black-bag list  or black-bag doctor  to confirm the restoration.
6. Best Practices, Security Considerations, and 
Troubleshooting
To maximize the security and effectiveness of your Black-Bagg vault, adhere to the 
following best practices and be aware of key security considerations. This section also 
provides guidance for common issues.
6.1. Best Practices
• Strong Master Passphrase: Your master passphrase is the single most critical 
component of your vault's security. It should be long, complex, and unique. Avoid using 
easily guessable phrases, personal information, or dictionary words. Consider using a 
passphrase generator or a method like Diceware to create a memorable yet strong 
passphrase.
• Regular Master Key Rotation: Utilize the black-bag rotate  command periodically (e.g., 
every few months or annually) to re-encrypt your master key with fresh randomness. 
This limits the exposure window of any single key and enhances long-term security.
• Secure Backup Strategy: Implement a robust backup strategy for your vault.cbor  file 
and your ML-DSA-87 secret key. Store backups in multiple, geographically dispersed, 
and encrypted locations (e.g., encrypted USB drives, secure cloud storage). Always sign 
your backups with black-bag backup sign  and verify them with black-bag backup verify  
before relying on them.
• Shamir Secret Sharing for Critical Secrets: For extremely critical secrets (like your 
master passphrase or a recovery key), use black-bag recovery split  to create Shamir 
shares. Distribute these shares to trusted individuals or store them in different secure 
locations. This prevents a single point of failure and provides a resilient recovery 
mechanism.
• Physical Security: The security of your digital vault is only as strong as the physical 
security of the device it resides on. Protect your computer with strong passwords, full-
disk encryption, and keep it physically secure.
• Keep Black-Bagg Updated: Regularly update Black-Bagg and your Rust toolchain to 
benefit from the latest security patches and features. Use cargo update  and rustup 
update .
• Avoid Command History Exposure: While Black-Bagg prompts for passphrases 
interactively to prevent them from appearing in shell history, be mindful of other 
commands that might inadvertently expose sensitive information. Avoid passing 
passphrases directly as command-line arguments unless explicitly designed for secure 
input.
• Understand mlock : Confirm that mlock  is enabled and working using black-bag doctor . 
This feature is vital for preventing sensitive data from being written to disk, but it relies 
on proper system configuration and permissions.
6.2. Security Considerations
• Master Passphrase Compromise: If your master passphrase is compromised, the 
entire vault is at risk. Black-Bagg's use of Argon2 makes brute-forcing difficult, but a 
weak passphrase or one exposed through phishing or malware remains a critical 
vulnerability.
• Malware/Keyloggers: Malicious software on your system can capture your master 
passphrase or vault contents as you interact with Black-Bagg. Ensure your operating 
system is secure, up-to-date, and protected by reputable antivirus/anti-malware 
software.
• Physical Access: An attacker with physical access to your unlocked computer can 
potentially access your vault. mlock  helps mitigate some physical attacks (like cold 
boot), but it's not a panacea. Always lock your computer when unattended.
• Supply Chain Attacks: While Rust's ecosystem is generally secure, a compromised 
black-bagg  crate or Rust toolchain could introduce vulnerabilities. Always download 
tools from official sources and verify their integrity where possible.
• ML-DSA-87 Key Management: The security of your ML-DSA-87 signed backups depends 
on the security of your ml_dsa_secret.key . If this key is compromised, an attacker could 
sign forged backups. Treat this secret key with the same level of security as your master 
passphrase.
6.3. Troubleshooting
• black-bag: command not found: This usually means ~/.cargo/bin  is not in your system's 
PATH. Ensure you have sourced $HOME/.cargo/env  in your current session or added it to 
your shell's configuration file (e.g., ~/.bashrc , ~/.zshrc ).
• Error: vault already exists  during init : You are trying to initialize a vault where one 
already exists. If you intend to create a new vault, first remove the existing one:
• Error: failed to construct TOTP: The length of the shared secret MUST be at least 128 bits : The 
base32 secret provided for add totp  is too short. Ensure your secret is at least 20 bytes 
long when base32 encoded. You can generate a random one with Python:
• Integrity and signature verification failed: When verifying a backup, this error means the 
backup file has been altered or the signature file is invalid/corrupted. Do not trust this 
backup. Investigate the cause of the corruption or tampering. Ensure you are using the 
correct public key for verification.
• Interactive commands hanging or not responding: When running black-bag  
commands that require passphrase input in scripts, you might need to use tools like 
expect  to automate the input. Direct piping with echo  might not work for all 
interactive prompts due to how black-bag  handles secure input.
• mlock: disabled or not working : If black-bag doctor  reports mlock  is not working, it could 
be due to system limitations or permissions. On Linux, you might need to configure 
ulimit -l  to allow memory locking for your user. Consult your operating system's 
documentation for enabling mlock  for non-root users.