Skip to content

Crypto toolkit

The cryptography Blackbook uses to protect your secrets is also yours to use directly: encrypt and decrypt data, sign and verify it, hash it (with or without a key), and issue signed tokens that anyone holding the right key can verify.

Every operation takes one key source:

Key source Flag Where the key lives
Managed key -k NAME On the server, in a domain. Its secret material never leaves the server — you send data in and get results back. Protected by the same ACLs, MFA, and audit log as your secrets, and rotatable without breaking anything already produced.
Your profile's key --cmk Your profile's client master key: local, sealed inside your encrypted profile, never sent anywhere.
A key file --key-file PATH A key you hold yourself (unmanaged). Make one with bbk crypto keygen, or bring your own: an Ed25519 PEM or 32 raw / hex / base64 bytes.
A passphrase -p Typed at a prompt (or $BLACKBOOK_CRYPTO_PASSPHRASE), stretched with Argon2id. Encrypt / decrypt only.

Managed keys come in three types: aes256-gcm (encrypt / decrypt), ed25519 (sign / verify / tokens, with a shareable public key), and hmac (keyed hashes / tokens).

# Make managed keys in your domain
bbk key create payroll                       # AES-256-GCM
bbk key create releases -t ed25519           # signing key; prints its public key
bbk key create webhooks -t hmac -M           # -M: every use needs an MFA code

# Encrypt / decrypt. With -k, your data is encrypted locally under a one-time
# data key that the managed key wraps, so the data itself never reaches the server.
bbk crypto encrypt -k payroll salaries.csv -o salaries.csv.bbk
bbk crypto decrypt -k payroll salaries.csv.bbk -o salaries.csv
bbk crypto encrypt -p notes.txt              # passphrase instead; decrypt asks for it

# Sign and verify (exit status 0 = valid, 1 = invalid)
bbk crypto sign -k releases app.tar.gz > app.sig
bbk crypto verify -k releases app.tar.gz -s (Get-Content app.sig)
bbk key show releases                        # prints the public key (base64 + PEM) to share
bbk crypto verify --public-key PUBKEY app.tar.gz -s (Get-Content app.sig)   # offline, no server

# Hash, or HMAC with a key
bbk crypto hash big.iso                      # SHA3-256 (also -a sha3-512 / sha256 / sha512)
bbk crypto hash -k webhooks -m 123456 --text "payload"

# Signed tokens (standard JWTs: EdDSA for Ed25519 keys, HS256 for HMAC keys)
bbk crypto token issue -k releases --sub ci-runner --aud deploy --ttl 15m -c env=prod
bbk crypto token verify -k releases --aud deploy eyJhbGciOiJFZERTQSIs...
bbk key jwks releases                        # JWK Set for any JWT library to verify with

# Rotate: new output uses v2; anything made with v1 still decrypts and verifies
bbk key rotate payroll

Also in the toolkit: crypto keygen (local key files), crypto datakey (a fresh data key for your own envelope encryption), crypto random, crypto derive-key (Argon2id / scrypt / PBKDF2), crypto password-hash / password-verify (Argon2id, standard PHC format), crypto fingerprint, and --aad on encrypt / decrypt to bind ciphertext to a context. Everything works over the API too (/api/v1/keys/...) and as MCP tools for AI agents.

Permissions for managed keys use the normal ACL rules, matched against the key name: create makes a key, read lets you see it and use it, update rotates it, and delete destroys it. Deleting a key makes everything it encrypted unrecoverable, so key rm asks you to type the name back.

For the formats and the security design behind managed keys, see Architecture & cryptography.