An age plugin that protects files with a rypt.dev key. age encrypts the file as usual. The plugin then sends age's 16-byte file key to rypt to be encrypted under one of your rypt keys, and stores the result in the file's header. Decrypting sends that ciphertext back to rypt, which returns the file key only to a caller holding a valid API token for the key's tenant.
It works with the Go age CLI (1.1 or later) and with rage, and should work
with any other client that implements the age plugin protocol.
age finds plugins on your PATH by the name age-plugin-rypt. Install it in
one of these ways.
brew install x6c-co/tap/age-plugin-ryptThis downloads the prebuilt binary, which is signed and notarized on macOS,
and also installs the age CLI.
On a Mac, the formula needs macOS 13 Ventura or later (see Prebuilt binaries).
Use the full name as shown: Homebrew only loads formulae from a third-party tap
once you trust them, and installing by full name trusts this one formula.
If Homebrew says the Command Line Tools are missing or out of date, run
xcode-select --install and try again. On Intel Macs, Homebrew has no prebuilt
age, so Homebrew compiles age from source, which takes a while.
Each release has a
tarball for macOS (Apple silicon and Intel) and Linux (x86_64 and arm64,
statically linked), and a SHA256SUMS file. The tarballs are named
age-plugin-rypt-vX.Y.Z-<os>-<arch>.tar.gz, where <os>-<arch> is
darwin-arm64 (Apple silicon), darwin-amd64 (Intel), linux-amd64 (x86_64)
or linux-arm64. The macOS binaries are signed with a Developer ID and
notarized by Apple.
The macOS binaries need macOS 13 Ventura or later, the oldest macOS that Go 1.27 supports. Version 0.1.0 ran on macOS 11 on Apple silicon and on macOS 10.12 on Intel. A Mac that cannot run Ventura should stay on 0.1.0, whose tarballs are on its release page. Homebrew refuses to install 0.2.0 on such a Mac.
curl -LO https://github.com/x6c-co/age-plugin-rypt/releases/download/v0.2.0/age-plugin-rypt-v0.2.0-darwin-arm64.tar.gz
tar -xzf age-plugin-rypt-v0.2.0-darwin-arm64.tar.gz
sudo mkdir -p /usr/local/bin
sudo install age-plugin-rypt-v0.2.0-darwin-arm64/age-plugin-rypt /usr/local/bin/When a macOS binary was downloaded in a browser, macOS checks its notarization with Apple the first time it runs, which needs an internet connection.
To check that a tarball was built by this repository's release workflow from that release's tag:
gh attestation verify age-plugin-rypt-v0.2.0-darwin-arm64.tar.gz \
--repo x6c-co/age-plugin-rypt \
--signer-workflow x6c-co/age-plugin-rypt/.github/workflows/release.yml \
--source-ref refs/tags/v0.2.0 \
--deny-self-hosted-runnersEach tarball also holds LICENSE-THIRD-PARTY, the licenses of the Go modules
built into the binary and of Go itself, whose runtime and standard library are
part of every Go binary.
go install github.com/x6c-co/age-plugin-rypt@latestThis needs Go 1.27 or later, and builds with the dependency versions in the
module's go.mod. On a Mac, Go 1.27 needs macOS 13 Ventura or later, and so
does the binary it builds. go install puts the binary in
$(go env GOPATH)/bin (~/go/bin by default), or in GOBIN if that is set.
age only finds the plugin if that directory is on your PATH.
Check it is found:
$ age-plugin-rypt --version
age-plugin-rypt 0.2.0The plugin reads its settings from environment variables. It has no configuration file.
| variable | meaning |
|---|---|
RYPT_TOKEN |
Required for encrypting and decrypting. A rypt API key, ry_<prefix>_<secret>, sent as Authorization: Bearer …. Spaces, tabs, newlines, form feeds and carriage returns around it are ignored. |
RYPT_API_URL |
Optional. The API base URL, without /v1. Defaults to https://api.rypt.dev, also when it is set but empty. It must use https, except for the hosts 127.0.0.1 and [::1], which may also use http. Every other host needs https: other loopback addresses such as 127.0.0.2, other ways of writing ::1, and the name localhost, since a name is looked up and could resolve to another machine. A path is kept: with https://example.com/api, requests go to https://example.com/api/v1/keys/…. |
export RYPT_TOKEN=ry_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxIf RYPT_TOKEN is unset or empty, age reports RYPT_TOKEN is not set.
Proxies. The plugin follows Go's standard proxy rules.
- The API uses
https, so the plugin uses the proxy inHTTPS_PROXY, or inhttps_proxyifHTTPS_PROXYis unset or empty.HTTP_PROXYandALL_PROXYare not used. - The value is a URL with the scheme
http,https,socks5orsocks5h, or justhost:port, which means anhttpproxy. - If the value is anything else, or cannot be parsed, the plugin sends no
request. It reports
HTTPS_PROXY is not a valid proxy URL(or the same forhttps_proxy), rather than go around the proxy or use the wrong one. This includes a value such ashttp:/proxy:3128. That value has one of those schemes but no//after it, and Go would read it as a proxy at a host namedhttp. NO_PROXY(orno_proxy, ifNO_PROXYis unset or empty) lists hosts to reach directly, separated by commas.example.commatches that host and its subdomains..example.comand*.example.commatch only its subdomains. An IP address, or a CIDR range such as10.0.0.0/8, matches the addresses it covers.*matches everything. An entry that ends in a port, such asexample.com:8443, matches only that port.- Go's HTTP library always reaches a loopback IP address, such as
127.0.0.1or[::1], directly. It reaches the namelocalhostdirectly only when the name is written in lowercase. Another spelling, such ashttps://LOCALHOST, goes through the proxy. - The plugin does not check the proxy value for a loopback IP address or for
lowercase
localhost. It checks the value for every otherhttpshost, even one thatNO_PROXYlists. - With
https, a proxy only learns the host it connects to.
TLS. Certificates are checked against the operating system's trust store.
On Linux, SSL_CERT_FILE and SSL_CERT_DIR, when set, are used in place of
the system's certificate file and directories. Only when the system has no root
certificates at all does the plugin fall back to Mozilla's root certificates,
which are built into the binary. A proxy that intercepts TLS with its own
certificate authority therefore works once the operating system trusts that
authority. A certificate the system does not trust fails with
rypt: TLS certificate rejected.
You need the id (a UUID) of a rypt key you already have. Create one in the
rypt console or with POST /v1/keys.
new writes an identity file for that key. It does not call the rypt API.
$ age-plugin-rypt new --key 3f2a9c1e-7b4d-4e2a-9f10-6c8d5a2b1e47 > rypt-identity.txt
$ cat rypt-identity.txt
# created: 2026-09-29T20:52:51-05:00
# key: 3f2a9c1e-7b4d-4e2a-9f10-6c8d5a2b1e47
AGE-PLUGIN-RYPT-18U4FC8NMF48Z48CSDJX452C7GU098V2Xrecipient prints the matching recipient. It reads an identity file from a
path, or from standard input when you give no path or -. It prints one line
for each rypt identity in the file, and skips identities of other types. The
file must be UTF-8 and at most 1 MiB. recipient refuses a rypt identity that
age itself would refuse: one in lowercase, or with spaces around it. It does
not check the file's other lines.
$ age-plugin-rypt recipient rypt-identity.txt
age1rypt18u4fc8nmf48z48csdjx452c7gu9hx89g
$ age-plugin-rypt recipient < rypt-identity.txt
age1rypt18u4fc8nmf48z48csdjx452c7gu9hx89gThe identity file contains no secret: both strings just encode the key id. The
secret is RYPT_TOKEN. Anyone with a valid token for the key's tenant and a
copy of the file can decrypt it, whether or not they have the identity file.
# Encrypt to the recipient...
age -e -r age1rypt18u4fc8nmf48z48csdjx452c7gu9hx89g -o secrets.tar.age secrets.tar
# ...or to the identity file, which encrypts to the same key.
age -e -i rypt-identity.txt -o secrets.tar.age secrets.tar
# Decrypt.
age -d -i rypt-identity.txt -o secrets.tar secrets.tar.agerage takes the same flags. The plugin has no default identity, so -j rypt
does not work: always pass -i with an identity file.
rypt recipients can be combined with X25519, SSH and other classic recipients. For example, add an offline X25519 key as a break-glass copy:
age-keygen -o backup.key # keep this file offline
age -e -r age1rypt18u4fc8nmf48z48csdjx452c7gu9hx89g -r "$(age-keygen -y backup.key)" \
-o secrets.tar.age secrets.tar
# If rypt is unavailable:
age -d -i backup.key -o secrets.tar secrets.tar.ageage 1.3 and later refuses to combine post-quantum recipients (age1pq1…,
age1tagpq1…) with classic ones, rypt included. rage needs age-plugin-pq on
PATH to use post-quantum recipients at all, and that plugin then refuses the
same combinations. Both refuse a passphrase with any other recipient.
Identity order. age and rage run the plugin once per identity, and stop at
the first identity that reports an error. If one identity file or list of -i
flags holds a rypt identity and another key, a rypt failure (no token, the API
unreachable, the key deleted) can stop decryption before the other key is
tried. rage and age before 1.3 try identities in the order given, so list the
key you expect to work first. age 1.3 and later try X25519 and post-quantum
keys before plugin identities, but not SSH keys or passphrase-protected
identity files, so list those first on every client. Two rypt identities
behave like any other pair: age and rage stop at the first rypt identity whose
stanza fails, even if a later rypt identity would decrypt the file. List the
rypt identity you expect to work first, or decrypt with that identity alone.
Decrypting with the break-glass key on its own always works.
Each rypt recipient adds one stanza to the age header:
-> rypt 3f2a9c1e-7b4d-4e2a-9f10-6c8d5a2b1e47
<rypt ciphertext of the file key>
The argument is the key id in lowercase hyphenated form. The body is the raw
ciphertext rypt's POST /v1/keys/{id}/encrypt returned. The plugin uses
rypt's direct encrypt/decrypt operations on the file key, not envelope
mode.
Version 0.2.0 uses the same stanza, recipient and identity formats as 0.1.0. Files encrypted with 0.1.0 decrypt with 0.2.0, files encrypted with 0.2.0 decrypt with 0.1.0, and identity files made by either version work with both.
- Encrypting costs one rypt operation per rypt recipient or identity, per file.
- Decrypting tries the file's
ryptstanzas whose key id matches an identity given to that run of the plugin, in header order, and stops at the first that decrypts. Stanzas for other keys are skipped without a request, so a file with no stanza for your keys needs noRYPT_TOKEN. If an attempt fails, the plugin moves on to the next matching stanza. If none decrypts, the plugin reports one error for the file: the different failure messages in header order, joined with;. age, rage and SOPS run the plugin once for each identity, so in practice the stanzas tried are those of one key. A file has more than one stanza for a key only when that key was given more than once when the file was encrypted. (For several rypt identities, see Identity order above.) rypt counts only the operations it completes, so a refused attempt costs nothing. A refusal that comes after rypt finds the key (a400, a409, or the free-tier cap) is recorded in the key's audit log; one that comes before (a401,403,404, or the rate limit) is not. - A
ryptstanza that does not follow the format above makes the header invalid. The plugin then reportsrypt: invalid stanzaand sends no request for that file. It recovers no file key from the file, not even from a well-formedryptstanza in it. This is what the age plugin protocol requires.
If the connection to rypt cannot be made, the connection drops before the
answer is complete, or rypt answers 502, 503 or 504, the plugin sends the
same request again, at most twice more. It waits up to a quarter of a second
before the first retry and up to half a second before the second. It does not
retry a 429, a 500 or any other 4xx answer. Each encrypt or decrypt
request, retries included, must finish within 30 seconds in total. A retried
request can be counted once for each attempt, so up to three times: after a
dropped connection or a 502, 503 or 504, rypt may have completed an
earlier attempt.
The plugin never follows a redirect: a 3xx answer is an error, like any
other answer outside 2xx. A 2xx answer is accepted only if its body is the
answer rypt documents.
- Rotation. rypt ciphertext names the key version it was made under, so
files keep decrypting after a rotation for as long as that version is
retained.
softwarekeys retain 3 versions andhsmkeys 2.freeandwrappedkeys retain only one: rotating one makes every file encrypted under the previous version undecryptable at once (rypt: 400). Before rotating such a key, re-encrypt its files to another recipient, or decrypt them and encrypt them again once the rotation is done. - Deletion. A deleted key refuses every operation (
rypt: 409) for seven days. Within those days it can be restored, in the console or withPOST /v1/keys/{id}/restoreusing the same token, and its files decrypt again. Once the seven days are up it can no longer be restored, even while it still answersrypt: 409. It is then destroyed, or at once with "delete now" in the console: the error becomesrypt: key not found, and files encrypted only to it are lost. Add a second recipient if that is not acceptable. If the second recipient is another rypt key, age and rage still stop at the first rypt identity whose stanza fails, so decrypt with the second key's identity alone, or list it first (see Identity order above). - Billing. On a paid key whose billing has lapsed, encrypting fails with
rypt: 402. Decrypting keeps working. - Free-tier cap. A
freekey that has used its 10,000 operations for the month refuses decrypting as well as encrypting, withrypt: rate limit or op cap reached, until 00:00 UTC on the 1st. For files that must stay readable, use a paid tier or add a second recipient (and mind the identity order above).
age prints these messages after rypt plugin: . rage prints the same
messages, with its own text before them. When several stanzas of a file fail
to decrypt in one run of the plugin, their different messages are joined with
; . With age, rage and SOPS, those are stanzas of one key (see Decrypting
above).
| message | cause |
|---|---|
RYPT_TOKEN is not set |
The variable is unset or empty, or holds only spaces, tabs, newlines, form feeds and carriage returns. |
RYPT_TOKEN is not valid UTF-8, RYPT_TOKEN contains invalid characters |
The value can't be a token. Either it is not valid UTF-8, or, after the ignored characters around it (see Configuration) are removed, it still contains a space, a control character such as a vertical tab, or a character outside ASCII. |
RYPT_API_URL is not a valid URL |
Not an absolute http or https URL with a host, or it has a query or a fragment (any ? or #, even with nothing after it), credentials, a port outside 1–65535, spaces, control characters or non-ASCII characters. |
RYPT_API_URL must use https |
An http URL, valid otherwise, whose host is not 127.0.0.1 or [::1], such as http://localhost. |
HTTPS_PROXY is not a valid proxy URL, or the same for https_proxy |
The proxy variable the plugin would use is not a proxy URL the plugin accepts, or cannot be parsed (see Proxies above). |
rypt: unauthorized |
401 or 403: the token is wrong, malformed or revoked, or is a console token rather than an API key. |
rypt: key not found |
404: the token's tenant has no key with this id. It may be mistyped, belong to another tenant, or have been destroyed. A RYPT_API_URL with the wrong path, such as one ending in /v1, also gives a 404. |
rypt: rate limit or op cap reached |
429: over 100 requests a second for this API key, or a free key at its monthly cap. |
rypt: 400 |
rypt refused the ciphertext: the stanza was made under another key, under a key version rotation has retired, or is corrupt. |
rypt: 402 |
Encrypting with a paid key whose billing has lapsed. |
rypt: 409 |
The key is pending deletion. |
rypt: <status> |
Any other HTTP status outside 2xx, including a redirect. A 502, 503 or 504 is reported only after the retries failed as well. |
rypt: connection failed |
The DNS lookup or the connection failed, the proxy refused or failed the connection, or the connection dropped before the answer was complete, on every attempt. |
rypt: TLS certificate rejected |
The server's certificate is not trusted, or is not for the host in the URL (see TLS above). |
rypt: TLS error |
Another TLS failure, for example an https URL for a server that doesn't speak TLS. |
rypt: request timed out |
No complete answer within 30 seconds, retries included, or the network timed out. |
rypt: request failed |
The request failed for another reason. |
rypt: invalid response |
rypt answered with a 2xx status but not with a valid answer: the body is not the JSON rypt documents, is larger than 8 MiB, or holds an empty or non-base64 value. |
rypt: invalid stanza |
The file has a malformed rypt stanza, so its header is invalid. |
rypt: decrypted file key is not 16 bytes |
rypt returned something that is not an age file key. |
rypt has no default identity: … |
-j rypt was used; pass -i with an identity file. |
key id must be 16 bytes, got N |
The recipient or identity is not a valid rypt key. |
The recipient subcommand prints its own errors, prefixed with
age-plugin-rypt:: no rypt identity found; line N: followed by
identity must be uppercase, identity has surrounding whitespace, which age does not accept, invalid Bech32 encoding or key id must be 16 bytes, got N;
and, naming the file or standard input, larger than 1 MiB, not valid UTF-8
or the system's reason the file could not be read.
- The plugin never prints or logs the token, the file key, the ciphertext, or
a response body. Errors are the fixed messages above, and nothing is written
to standard error when a run succeeds. To keep standard error clean, the
plugin discards everything written to Go's standard logger. Go's HTTP
library writes there every request header sent over HTTP/2, the token among
them, when
GODEBUG=http2debugis set, and any bytes a server sends after its answer. - rypt sees each file key in the clear while it encrypts or decrypts it. That is what direct mode means, and why rypt holds the key.
- The plugin does not wipe file keys from memory. age's Go plugin framework,
which runs the plugin protocol, holds every file key in ordinary memory and
never clears it, and the plugin only passes the keys on. The rypt client
library clears its own copies of the request and response bodies.
recipientclears its copy of the identity file it read. A decrypted value that is not 16 bytes is rejected and cleared. The token is held as a Go string, which cannot be cleared at all. Copies inside the HTTP and TLS libraries' own buffers cannot be wiped from the plugin either. Go cannot guarantee that clearing a buffer removes every copy from memory, so the clearing reduces exposure rather than preventing it. Version 0.1.0 wiped file keys and the token too. Version 0.2.0 cannot, for the reasons above.
go test ./...This runs two sets of tests:
- The unit tests, in the
_test.gofiles next to the code at the root of the repository. - The end-to-end tests in
e2e/. They build the binary and run it against a mock rypt API on 127.0.0.1, through the age plugin protocol and through thenewandrecipientsubcommands. The tests that use an age CLI runage, orragewhenageis not onPATH. They are skipped when neither is found. WhenAGE_PLUGIN_RYPT_REQUIRE_CLIis set, as it is in CI, they fail instead. To use only one of the two programs, setAGE_PLUGIN_RYPT_CLItoageorrage. The tests then fail if that program is not onPATH.
To check that this version and another build can decrypt each other's files,
for example a 0.1.0 binary, set AGE_PLUGIN_RYPT_COMPAT_BINARY to the path of
the other build's age-plugin-rypt binary. The compatibility test runs against
that binary.
GitHub Actions runs .github/workflows/ci.yml on pushes to main, on pull
requests, and weekly. It checks the formatting with gofmt, runs go vet,
and runs the tests with the race detector on Linux and macOS with the age
CLI installed. On macOS it then runs the age CLI tests again with rage,
which is built on the Rust age library rather than the Go one. It also builds
and vets the plugin with the oldest Go that go.mod allows, and runs
govulncheck, which reports security advisories for code the plugin can
reach, in its dependencies and in the standard library.
RELEASING.md covers releases, and
CHANGELOG.md lists the changes in each version.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.