How filosottile/age works
Purpose and Entry Points
age is a Go implementation of the age file-encryption format and a reusable library. Primary binaries are age for streaming encryption/decryption, age-keygen for key generation/conversion, and age-inspect for unauthenticated format metadata inspection. Entrypoints: cmd/age/age.go, cmd/age-keygen/keygen.go, and cmd/age-inspect/inspect.go.
Public Cryptographic API
The root package exposes recipient/identity abstractions and streaming encryption/decryption, separating callers from individual key mechanisms. Core API, parsing, and shared primitives are in age.go, parse.go, and primitives.go. Encryption wraps plaintext for one or more recipients; decryption tries supplied identities against encrypted header stanzas before exposing payload plaintext.
File Format and Streaming Boundary
The on-disk/wire format is implemented below the public API: header serialization/parsing and payload framing are in internal/format/format.go; authenticated chunked payload processing is in internal/stream/stream.go. This is the compatibility and security boundary for the age specification: callers provide io.Reader/io.Writer, allowing CLI pipelines without loading files into memory.
Native Recipient and Identity Types
Built-in key systems implement the public recipient/identity contracts: default X25519 keys in x25519.go, passphrase-based scrypt encryption in scrypt.go, and hybrid post-quantum ML-KEM/X25519 support in pq.go. Encoded key parsing relies on internal Bech32 support at internal/bech32/bech32.go. Multi-recipient encryption generates recipient-specific wrapped file keys while retaining one encrypted payload.
SSH and Tagged-Key Extensions
SSH public/private key interoperability is provided by agessh/agessh.go and agessh/encrypted_keys.go, including SSH key-file handling rather than agent integration. The tag package supplies tagged recipient/identity behavior in tag/tag.go; its companion test plugin demonstrates integration under tag/internal/age-plugin-tagtest/plugin-tagtest.go.
CLI Orchestration and User Interaction
The age CLI parses flags and key sources, resolves recipients/identities from arguments and files, invokes the root API, and owns filesystem/stdin/stdout behavior. Main orchestration and key-source handling reside in cmd/age/age.go, cmd/age/parse.go, and cmd/age/encrypted_keys.go. Terminal prompts and passphrase UX are separated into cmd/age/tui.go and shared terminal support in internal/term/term.go.
Plugin Protocol and Deployment Model
The plugin subsystem permits external recipient and identity implementations as subprocesses discoverable through PATH; client protocol logic is in plugin/client.go, plugin/plugin.go, and plugin/encode.go. Built-in plugin executables/examples include cmd/age-plugin-batchpass/plugin-batchpass.go and extra/age-plugin-pq/plugin-pq.go. The project targets supported Go runtimes (go.mod) and standard OS command-line environments; it has no server, database, or required network service. CI is GitHub Actions-based in .github/workflows/build.yml and .github/workflows/interop.yml.
Main entry points: age.go Public crypto API · age/age.go age CLI · client.go Plugin protocol client · x25519.go Native key types
Components 20
Core library
Public API, format, streaming, and built-in key systems.
- Public crypto API · Recipient and identity contracts plus streaming encryption and decryption.
age.go - Key parsing & primitives
parse.go - Age file format · Header stanza serialization/parsing and payload framing.
internal/format/format.go - Authenticated stream · Chunked authenticated payload encryption and decryption.
internal/stream/stream.go - Native key types · X25519, scrypt passphrase, and ML-KEM/X25519 recipients and identities.
x25519.go - Bech32 encoding
internal/bech32/bech32.go
Command-line tools
Streaming tools and terminal interaction.
- age CLI · Resolves key sources and streams files, stdin, and stdout through the public API.
cmd/age/age.go - CLI key sources
cmd/age/parse.go - Encrypted key files
cmd/age/encrypted_keys.go - Terminal prompts · Passphrase and interactive terminal UX.
cmd/age/tui.go - Terminal support
internal/term/term.go - age-keygen · Generates and converts keys.
cmd/age-keygen/keygen.go - age-inspect · Reads unauthenticated format metadata.
cmd/age-inspect/inspect.go
Extensions
SSH, tagged keys, and external plugin support.
- SSH key extension · SSH public/private-key interoperability and encrypted SSH key-file handling.
agessh/agessh.go - Tagged keys · Tagged recipient and identity behavior.
tag/tag.go - Plugin protocol client · Discovers and communicates with recipient and identity subprocesses on PATH.
plugin/client.go - Batchpass plugin
cmd/age-plugin-batchpass/plugin-batchpass.go - PQ plugin example
extra/age-plugin-pq/plugin-pq.go
Build and compatibility
- Supported Go runtime
go.mod - CI build & interop
.github/workflows/build.yml
Connections 19
- age CLI → CLI key sources: resolves keys
- age CLI → Encrypted key files: loads key files
- age CLI → Terminal prompts: prompts
- Terminal prompts → Terminal support: uses
- age CLI → Public crypto API: encrypts/decrypts
- age-keygen → Native key types: creates keys
- age-inspect → Age file format: inspects headers
- Public crypto API → Key parsing & primitives: parses inputs
- Public crypto API → Age file format: reads/writes headers
- Public crypto API → Authenticated stream: processes payload
- Public crypto API → Native key types: uses recipients/identities
- Native key types → Bech32 encoding: encodes keys
- SSH key extension → Public crypto API: implements contracts
- Tagged keys → Public crypto API: implements contracts
- Plugin protocol client → Public crypto API: implements contracts
- Plugin protocol client → Batchpass plugin: launches via PATH
- Plugin protocol client → PQ plugin example: launches via PATH
- Supported Go runtime → Public crypto API: builds
- CI build & interop → Supported Go runtime: validates