age Modern Encryption

age cheatsheet — encrypt files with age-keygen, recipient keys, SSH keys, and passphrase. age -r pubkey -o out.age file. The simple GPG alternative.

7 min read

What it is

age is a simple, modern, and secure file encryption tool that uses a hybrid encryption approach. You reach for age when you need to encrypt files for specific recipients or when you want a straightforward, auditable encryption solution.

Installation

Linux

# Using Nix (recommended)
nix-env -iA nixpkgs.age

# Download binary from GitHub releases
curl -LO https://github.com/FiloSottile/age/releases/download/v1.1.1/age-v1.1.1-linux-amd64.tar.gz
tar -zxvf age-v1.1.1-linux-amd64.tar.gz
sudo mv age/age /usr/local/bin/
sudo mv age/age-keygen /usr/local/bin/

macOS

# Using Homebrew
brew install age

# Download binary from GitHub releases
curl -LO https://github.com/FiloSottile/age/releases/download/v1.1.1/age-v1.1.1-macos-amd64.tar.gz
tar -zxvf age-v1.1.1-macos-amd64.tar.gz
sudo mv age/age /usr/local/bin/
sudo mv age/age-keygen /usr/local/bin/

Windows

Download the appropriate .zip file from the age releases page on GitHub and extract the age.exe and age-keygen.exe binaries to a directory in your system’s PATH.

Core Concepts

  • Public Key Cryptography: age uses public-key cryptography to associate encrypted data with specific recipients. Each recipient has a public key (which can be shared) and a private key (which must be kept secret).
  • Hybrid Encryption: For efficiency, age encrypts the actual file content with a symmetric secret key. This symmetric key is then encrypted multiple times, once for each recipient’s public key. This is faster than encrypting the entire file with asymmetric encryption.
  • Identity: An "identity" in age is essentially a private key. You can have multiple identities, each with a corresponding public key. When you encrypt a file, you specify the public keys of the intended recipients. When you decrypt, age uses your private key (identity) to find the symmetric key needed to decrypt the file.
  • Key Management: age supports several ways to manage identities:
    • Files: Private keys can be stored in files (e.g., ~/.config/age/key.txt).
    • Hardware Security Modules (HSMs): Via the FIDO2 standard.
    • SSH Agent: Using your existing SSH keys.
    • Passphrase Protection: Private keys stored in files can be protected with a passphrase.

Commands / Usage

Key Management

Generating a new identity (private key)

age-keygen

This command will interactively prompt you to create a new identity. It will ask if you want to protect it with a passphrase. It will output your public key and your private key. The private key is typically saved to ~/.config/age/key.txt.

Showing your public key

age-keygen -y

This command prints your public key to standard output. You share this with others so they can encrypt files for you.

Loading an identity from a file

age -i ~/.ssh/id_ed25519 --decrypt secret.txt.age

Use the -i flag to specify a file containing your private key (identity) for decryption or encryption. This can also be an SSH private key.

Loading identities from an agent

age -a --decrypt secret.txt.age

Use the -a flag to tell age to look for identities in an SSH agent. This is useful if you’re using your SSH keys with age.

Encryption

Encrypting a file for one or more recipients

age -r "age1xl5q..." -r "recipient@example.com" -o encrypted.txt.age original.txt
  • -r "age1xl5q...": Specifies a recipient’s public key (as a string).
  • -r "recipient@example.com": Specifies a recipient’s public key managed by an SSH agent or a key file named recipient@example.com.pub.
  • -o encrypted.txt.age: Specifies the output file name. If omitted, output goes to standard output.
  • original.txt: The file to encrypt.

If no -o is specified, the encrypted output is sent to stdout:

age -r "age1xl5q..." README.md > README.md.age

Encrypting standard input

cat important_data.csv | age -r "age1xl5q..." -o important_data.csv.age

Encrypts data piped from standard input.

Encrypting with a passphrase (for self-encryption)

age -p -o secret.txt.age secret.txt
  • -p: Prompts for a passphrase to encrypt the file. This is useful for encrypting files that only you will decrypt later. The file can only be decrypted if you know the passphrase.

Specifying a recipient’s public key file

age -r recipient.pub -o encrypted.txt.age original.txt
  • -r recipient.pub: Specifies a file containing the recipient’s public key.

Decryption

Decrypting a file with a specific identity

age -i ~/.config/age/key.txt -o original.txt encrypted.txt.age
  • -i ~/.config/age/key.txt: Specifies the private key (identity) file to use for decryption. If omitted, age will look in ~/.config/age/key.txt and use an SSH agent if available.
  • -o original.txt: Specifies the output file name. If omitted, output goes to standard output.
  • encrypted.txt.age: The encrypted file.

Decrypting standard output

age -i ~/.config/age/key.txt secret.txt.age > secret.txt

Decrypts the file and sends the plaintext to standard output.

Decrypting using an SSH agent

age -a -o original.txt encrypted.txt.age
  • -a: Tells age to use identities available in the SSH agent.

Decrypting a file encrypted with a passphrase

age -o original.txt encrypted.txt.age

If the file was encrypted with a passphrase using -p, age will automatically prompt for the passphrase when you attempt to decrypt it.

Other

Staging (for reproducible builds, not for encryption)

age --staging --encrypt --output=manifest.txt.age original.txt

This feature is not for encrypting files. It’s for creating reproducible builds by encrypting a manifest file that lists the contents of a directory. It’s a more advanced use case.

Version

age --version

Displays the installed version of age.

Common Patterns

Encrypting a file for yourself and a colleague

# On your machine:
age -r "age1xl5q..." -r colleague.pub -o important_doc.txt.age important_doc.txt

# Colleague receives important_doc.txt.age and uses their private key (e.g., from SSH agent)
age -a -o important_doc.txt important_doc.txt.age

This encrypts important_doc.txt so that both you (using age1xl5q...) and your colleague (using colleague.pub) can decrypt it.

Encrypting a sensitive file with a passphrase

age -p -o my_secrets.env.age .my_secrets.env

Encrypts .my_secrets.env using a passphrase. Only someone who knows the passphrase can decrypt it.

Decrypting a file and piping it to another command

age -i ~/.config/age/key.txt secret.txt.age | grep "API_KEY"

Decrypts secret.txt.age and pipes the plaintext content to grep to find a specific line.

Managing multiple recipients and a passphrase-protected file

# Encrypt for Alice, Bob, and yourself (using a passphrase)
age -r alice@example.com -r bob.pub -p -o sensitive_data.enc data.csv

# Decrypt using your passphrase
age -o data.csv sensitive_data.enc

# Bob decrypts using his SSH agent key
age -a -o data.csv sensitive_data.enc

Using age with a custom key file location

# Encrypt, specifying recipient's public key file
age -r ./keys/alice.pub -o encrypted_for_alice.txt.age data.txt

# Decrypt, specifying your private key file
age -i ./my_keys/private.key -o data.txt encrypted_for_alice.txt.age

Gotchas

  • No Key Revocation: age does not have a built-in mechanism for revoking access. If you encrypt a file for someone and later want to revoke their access, you must re-encrypt the file with new recipients and potentially remove the old recipient’s public key from future encryption operations.
  • Public Key Format: Ensure you are using the correct format for public keys. They start with age1... or can be .pub files. If you’re using SSH keys, age expects them to be in the standard OpenSSH format.
  • Output Redirection: When encrypting or decrypting to standard output (by omitting -o), be mindful of where the data is going. If you forget to redirect it or pipe it, it will print to your terminal, which might expose sensitive information.
  • Identity File Permissions: Private key files (~/.config/age/key.txt, etc.) should have strict permissions (e.g., chmod 600 ~/.config/age/key.txt) to prevent unauthorized access.
  • SSH Agent Compatibility: While age works with SSH agents, ensure your SSH agent is running and has the correct keys added. Sometimes, specific SSH key types might have better compatibility than others.
  • Passphrase Strength: If you use the -p flag for passphrase encryption, choose a strong, unique passphrase. age does not enforce passphrase complexity, so it’s up to the user.