VaultKit Quickstart

VaultKit seals and opens small JSON vaults using Argon2id + AES-GCM. It supports AAD binding modes for tamper-evidence:

• --aad none → portable vaults (can be moved anywhere).
• --aad path → path-bound vaults (break if relocated).
• --aad custom --aad-hex <HEX> → vaults bound to custom secret bytes.

Create & View a Portable Vault

echo '{ "msg":"portable" }' > p.json
./vaultkit new  --input p.json --output p.vlt --password pw --aad none
./vaultkit view --file p.vlt --password pw --aad none
Move it and it still works:

mkdir -p moved && mv p.vlt moved/
./vaultkit view --file moved/p.vlt --password pw --aad none

Create & View a Path-Bound Vault
echo '{ "msg":"bound" }' > b.json
./vaultkit new  --input b.json --output a/bound.vlt --password pw --aad path
./vaultkit view --file a/bound.vlt --password pw --aad path


Moving it causes decryption failure:

mv a/bound.vlt x/
./vaultkit view --file x/bound.vlt --password pw --aad path   # crypto failure (expected)

Custom AAD (Hex Key)
AA=deadbeefcafebabe
./vaultkit new  --input b.json --output c.vlt --password pw --aad custom --aad-hex "$AA"
./vaultkit view --file c.vlt --password pw --aad custom --aad-hex "$AA"


Using the wrong hex fails decryption.

Lifecycle Ops

Set expiry:

./vaultkit set-expiry --file moved/p.vlt \
  --expires-at "2025-12-31T23:59:59Z" --password pw --aad none


Set burn-on-view:

./vaultkit set-burn-flag --file a/bound.vlt \
  --password pw --aad path --value true


Rotate password:

export VIOS_OLD_PASSWORD=pw VIOS_NEW_PASSWORD=pw2
./vaultkit rotate-key --file moved/p.vlt --aad none
./vaultkit view --file moved/p.vlt --password pw2 --aad none


Burn (delete):

./vaultkit burn --file moved/p.vlt

When to Use Which AAD Mode

Portable (none) → shareable, backup-friendly, can move freely.

Path (path) → tamper-evident, breaks if copied/moved (binds to filesystem path).

Custom (custom) → bind to an external secret (hex key); useful for device-tied or org-wide vaults.