agevault is a directory encryption tool using age file
encryption.
It locks/unlocks a vault (directory) with a passphrase-protected identity file.
Like age, it features no config options, allowing for a straightforward secure flow.
This project has been tested, but has not undergone a formal security audit, and none is planned.
The codebase is intentionally kept simple and readable, so you're encouraged to review it yourself before relying on it for anything sensitive.
Use at your own risk (see LICENSE).
Always install the latest release to make sure you have the latest security improvements and fixes.
If the update has the same major version (e.g. v1.x.x), then it's guaranteed to be backwards
compatible.
Get them from the latest release.
nix run github:ndavd/agevault
go install github.com/ndavd/agevault@latest
docker build -t agevault .
docker run --rm -it -u ${UID}:${GID} -v .:/tmp agevault
For the full documentation, read the agevault(1) man page.
lock/unlock directory with passphrase-protected identity file
usage: agevault [directory-name] lock|unlock|keygen [-pq]
Assuming we want to secure the directory my-vault/:
-
Generate identity file
$ agevault my-vault keygen create identity passphrase: confirm identity passphrase: .ab2a0883204b8bb5a463fe79ecde7674.my-vault.key.age CREATED ab2a0883204b8bb5a463fe79ecde7674 ADDED to my-vault/.agevault-recipients
-
Lock vault
$ agevault my-vault lock my-vault LOCKED with: ab2a0883204b8bb5a463fe79ecde7674
-
Unlock vault
$ agevault my-vault unlock enter passphrase for identity file ".ab2a0883204b8bb5a463fe79ecde7674.my-vault.key.age": my-vault UNLOCKED
-
That's it. Do your changes, lock it again, etc.
The vault is encrypted to every recipient listed in <vault>/.agevault-recipients. keygen adds
its recipient automatically, and the file is locked together with the rest of the vault. For
my-vault, it looks like this:
# agevault recipients for my-vault
# lines starting with # are ignored
# fingerprint: ab2a0883204b8bb5a463fe79ecde7674
age14p8nysmdqmlhgczshculs35kt2y8rrsx9jd9mc0rglg90rr504xsh3qzty
To share a vault, the other person runs agevault <vault> keygen (add -pq for post-quantum
vaults) and sends you the recipient and fingerprint from their <vault>/.agevault-recipients. Paste
the recipient into yours and lock, then send them <vault>.age. They need to remove the empty
<vault>/ created by their keygen before unlocking.
Every recipient's fingerprint is printed on lock. Check that each one is yours or matches a fingerprint someone sent you.
keygen -pq generates a post-quantum identity (ML-KEM-768 + X25519) instead of an X25519 one. Its
recipient starts with age1pq1 and is much longer.
age can't encrypt to post-quantum and X25519 recipients at the same time, so every recipient of a
vault must be the same kind. keygen refuses to add a recipient that doesn't match the existing
ones, so everyone sharing a post-quantum vault must use keygen -pq.
Previously, the recipient was stored in the identity filename. Vaults created with older versions
are migrated automatically: the first lock creates .agevault-recipients from the existing
identity file. Once it's migrated, the identity file can be renamed, as long as it keeps the
.<vault>.key.age ending.
agevault relies entirely on age for the cryptography involved, inheriting its security. It
provides the minimal infrastructure required for age to work as a directory encryption tool.
agevault uses a passphrase-encrypted identity for a few key reasons:
- Extra security factor: Having the encrypted identity file or the passphrase by itself is useless.
- Easier to lock: If only symmetric encryption was used, the user would need the passphrase to lock as well; this way, the vault can be locked without entering the passphrase.
- Multiple keys (recipients): Each passphrase corresponds to its own key, so multiple people can own the vault: any one of them can lock it, and any one of them can unlock it with their own passphrase.
- Post-quantum keys
- Multi-user vault support