age: Simple, Modern, and Secure File Encryption

To use age, first generate a key pair, then encrypt a file using a recipient public key, and finally decrypt it using your identity file.

1. Generate a key: age-keygen -o key.txt
2. Encrypt: tar cvz ~/data | age -r <PUBLIC_KEY> > data.tar.gz.age
3. Decrypt: age --decrypt -i key.txt data.tar.gz.age > data.tar.gz

# Generate key
$ age-keygen -o key.txt

# Encrypt a tarball to a recipient
$ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age

# Decrypt the file
$ age --decrypt -i key.txt data.tar.gz.age > data.tar.gz

To protect against future quantum computer attacks, you can generate hybrid post-quantum keys using the -pq flag with age-keygen. Post-quantum identities start with AGE-SECRET-KEY-PQ-1... and recipients with age1pq1....

Note: Support for post-quantum keys requires age v1.3.0 or later. For older versions, use the age-plugin-pq binary.

$ age-keygen -pq -o key.txt
$ age-keygen -y key.txt > recipient.txt
$ age -R recipient.txt example.jpg > example.jpg.age
$ age -d -i key.txt example.jpg.age > example.jpg

The age tool can be extended via plugins. A plugin is only loaded if a corresponding recipient or identity is specified in the command.

• Plugin Recipient: Starts with age1<pluginname>1.
• Plugin Identity: Starts with AGE-PLUGIN-<PLUGINNAME>-1.

When a plugin is invoked, age searches for age-plugin-<name> in the system PATH and executes it. The plugin handles the header encryption/decryption and may request user input.

Common Plugin Patterns:

• Hardware Keys: Plugins like age-plugin-yubikey allow using hardware-backed identities.
• Symmetric Encryption: Some plugins might only provide an identity (for encryption) or require the -j flag (for decryption).

To integrate an external identity provider or key management system with age, you can use the plugin package to implement age.Recipient or age.Identity.

• Use Recipient when you want to encrypt data for a specific recipient (e.g., a public key stored in a plugin).
• Use Identity when you want to decrypt data using a plugin-managed identity (e.g., a hardware token or an SSH key).

Both types require a *ClientUI to handle user interactions (like prompts or confirmations) that the plugin might request during the (un)wrapping process.

import "filippo.io/age/plugin"

// For encryption (Recipient)
recipient, err := plugin.NewRecipient("age1pluginname1...", ui)

// For decryption (Identity)
identity, err := plugin.NewIdentity("AGE-PLUGIN-NAME-1...", ui)

While batchpass enables passphrase-based automation, the age ecosystem recommends using native keys for non-interactive workflows.

Native Key Pattern (Recommended):

1. Generate a key: age-keygen -o key.txt
2. Store the identity string in an environment variable: export AGE_SECRET=$(cat key.txt)
3. Encrypt/Decrypt using the identity: age -e -i <(echo "$AGE_SECRET") file.txt

Batchpass Pattern: Use batchpass only when you specifically need scrypt-based passphrase protection and want to automate the entry of that passphrase via environment variables.

Use age-keygen to generate new native age identity key pairs. By default, it generates a traditional identity and outputs it to standard output. The output includes the public key and the creation timestamp as comments. If the output is redirected away from a terminal, the public key is printed to standard error.

# Generate a new traditional identity
$ age-keygen

# Generate a new post-quantum identity
$ age-keygen -pq

The age-plugin-batchpass plugin allows you to perform passphrase-based encryption and decryption non-interactively by providing the passphrase through environment variables. This is useful for automation where you want to avoid manual password entry.

Warning: In most cases, using native age keys is preferred over passphrases for automation. You can achieve non-interactive encryption with native keys by storing a secret identity in an environment variable.

To use the plugin, invoke the age CLI with the -j batchpass flag and provide the passphrase via AGE_PASSPHRASE or AGE_PASSPHRASE_FD.

# Encrypting a file
AGE_PASSPHRASE=password age -e -j batchpass file.txt > file.txt.age

# Decrypting a file
AGE_PASSPHRASE=password age -d -j batchpass file.txt.age > file.txt

The age-plugin-batchpass plugin enables non-interactive passphrase-based encryption and decryption for the age CLI by using environment variables. This is useful for automation where a human cannot manually enter a passphrase.

Warning: For most automated use cases, it is recommended to use native keys (identity strings) instead of passphrases to avoid the performance overhead of scrypt and the security risks of managing passphrases in scripts.

age -e -j batchpass file.txt > file.txt.age
age -d -j batchpass file.txt.age > file.txt