age

README

age

age is a simple, modern and secure file encryption tool, format, and library.

It features small explicit keys, no config options, and UNIX-style composability.

$ age-keygen -o key.txt
Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
$ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
$ age -d -i key.txt data.tar.gz.age > data.tar.gz

The format specification is at age-encryption.org/v1. To discuss the spec or other age related topics, please email the mailing list at age-dev@googlegroups.com. age was designed by @Benjojo12 and @FiloSottile.

An alternative interoperable Rust implementation is available at github.com/str4d/rage.

Usage

Usage:
    age -r RECIPIENT [-a] [-o OUTPUT] [INPUT]
    age --decrypt [-i KEY] [-o OUTPUT] [INPUT]

Options:
    -o, --output OUTPUT         Write the result to the file at path OUTPUT.
    -a, --armor                 Encrypt to a PEM encoded format.
    -p, --passphrase            Encrypt with a passphrase.
    -r, --recipient RECIPIENT   Encrypt to the specified RECIPIENT. Can be repeated.
    -d, --decrypt               Decrypt the input to the output.
    -i, --identity KEY          Use the private key file at path KEY. Can be repeated.

INPUT defaults to standard input, and OUTPUT defaults to standard output.

RECIPIENT can be an age public key, as generated by age-keygen, ("age1...")
or an SSH public key ("ssh-ed25519 AAAA...", "ssh-rsa AAAA...").

KEY is a path to a file with age secret keys, one per line
(ignoring "#" prefixed comments and empty lines), or to an SSH key file.
Multiple keys can be provided, and any unused ones will be ignored.

Multiple recipients

Files can be encrypted to multiple recipients by repeating -r/--recipient. Every recipient will be able to decrypt the file.

$ age -o example.jpg.age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \
    -r age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg example.jpg

Passphrases

Files can be encrypted with a passphrase by using -p/--passphrase. By default age will automatically generate a secure passphrase. Passphrase protected files are automatically detected at decrypt time.

$ age -p secrets.txt > secrets.txt.age
Enter passphrase (leave empty to autogenerate a secure one):
Using the autogenerated passphrase "release-response-step-brand-wrap-ankle-pair-unusual-sword-train".
$ age -d secrets.txt.age > secrets.txt
Enter passphrase:

SSH keys

As a convenience feature, age also supports encrypting to ssh-rsa and ssh-ed25519 SSH public keys, and decrypting with the respective private key file. (ssh-agent is not supported.)

$ cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIZDRcvS8PnhXr30WKSKmf7WKKi92ACUa5nW589WukJz filippo@Bistromath.local
$ age -r "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIZDRcvS8PnhXr30WKSKmf7WKKi92ACUa5nW589WukJz" example.jpg > example.jpg.age
$ age -d -i ~/.ssh/id_ed25519 example.jpg.age > example.jpg

Note that SSH key support employs more complex cryptography, and embeds a public key tag in the encrypted file, making it possible to track files that are encrypted to a specific public key.

Installation

On macOS or Linux, you can use Homebrew:

brew tap filippo.io/age https://filippo.io/age
brew install age

On Windows, Linux, and macOS, you can use the pre-built binaries.

If your system has Go 1.13+, you can build from source:

git clone https://filippo.io/age && cd age
go build -o . filippo.io/age/cmd/...

On Arch Linux, age is available from AUR as age or age-git:

git clone https://aur.archlinux.org/age.git
cd age
makepkg -si

On OpenBSD -current and 6.7+, you can use the port:

pkg_add age

On all supported versions of FreeBSD, you can build the security/age port or use pkg:

pkg install age

Help from new packagers is very welcome.

Documentation

Overview

Package age implements file encryption according to the age-encryption.org/v1 specification.

For most use cases, use the Encrypt and Decrypt functions with X25519Recipient and X25519Identity. If passphrase encryption is required, use ScryptRecipient and ScryptIdentity. For compatibility with existing SSH keys use the filippo.io/age/agessh package.

Age encrypted files are binary and not malleable. For encoding them as text, use the filippo.io/age/armor package.

Key management

Age does not have a global keyring. Instead, since age keys are small, textual, and cheap, you are encoraged to generate dedicated keys for each task and application.

Recipient public keys can be passed around as command line flags and in config files, while secret keys should be stored in dedicated files, through secret management systems, or as environment variables.

There is no default path for age keys. Instead, they should be stored at application-specific paths. The CLI supports files where private keys are listed one per line, ignoring empty lines and lines starting with "#". These files can be parsed with ParseIdentities.

When integrating age into a new system, it's recommended that you only support X25519 keys, and not SSH keys. The latter are supported for manual encryption operations. If you need to tie into existing key management infrastructure, you might want to consider implementing your own Recipient and Identity.

Index

• Variables
• func Decrypt(src io.Reader, identities ...Identity) (io.Reader, error)
• func Encrypt(dst io.Writer, recipients ...Recipient) (io.WriteCloser, error)
• type Identity
  • func ParseIdentities(f io.Reader) ([]Identity, error)
• type IdentityMatcher
• type Recipient
• type ScryptIdentity
  • func NewScryptIdentity(password string) (*ScryptIdentity, error)
  • func (i *ScryptIdentity) SetMaxWorkFactor(logN int)
  • func (*ScryptIdentity) Type() string
  • func (i *ScryptIdentity) Unwrap(block *Stanza) ([]byte, error)
• type ScryptRecipient
  • func NewScryptRecipient(password string) (*ScryptRecipient, error)
  • func (r *ScryptRecipient) SetWorkFactor(logN int)
  • func (*ScryptRecipient) Type() string
  • func (r *ScryptRecipient) Wrap(fileKey []byte) (*Stanza, error)
• type Stanza
• type X25519Identity
  • func GenerateX25519Identity() (*X25519Identity, error)
  • func ParseX25519Identity(s string) (*X25519Identity, error)
  • func (i *X25519Identity) Recipient() *X25519Recipient
  • func (i *X25519Identity) String() string
  • func (*X25519Identity) Type() string
  • func (i *X25519Identity) Unwrap(block *Stanza) ([]byte, error)
• type X25519Recipient
  • func ParseX25519Recipient(s string) (*X25519Recipient, error)
  • func (r *X25519Recipient) String() string
  • func (*X25519Recipient) Type() string
  • func (r *X25519Recipient) Wrap(fileKey []byte) (*Stanza, error)

Examples

• Decrypt
• Encrypt
• GenerateX25519Identity
• ParseIdentities

Variables

var ErrIncorrectIdentity = errors.New("incorrect identity for recipient block")

Functions

func Decrypt

func Decrypt(src io.Reader, identities ...Identity) (io.Reader, error)

Decrypt decrypts a file encrypted to one or more identities.

It returns a Reader reading the decrypted plaintext of the age file read from src. All identities will be tried until one successfully decrypts the file.

Example

package main

import (
	"bytes"
	"fmt"
	"io"
	"log"
	"os"

	"filippo.io/age"
)

// DO NOT hardcode the private key. Store it in a secret storage solution,
// on disk if the local machine is trusted, or have the user provide it.
var privateKey string

func main() {
	identity, err := age.ParseX25519Identity(privateKey)
	if err != nil {
		log.Fatalf("Failed to parse private key: %v", err)
	}

	f, err := os.Open("testdata/example.age")
	if err != nil {
		log.Fatalf("Failed to open file: %v", err)
	}

	r, err := age.Decrypt(f, identity)
	if err != nil {
		log.Fatalf("Failed to open encrypted file: %v", err)
	}
	out := &bytes.Buffer{}
	if _, err := io.Copy(out, r); err != nil {
		log.Fatalf("Failed to read encrypted file: %v", err)
	}

	fmt.Printf("File contents: %q\n", out.Bytes())
}

Output:

File contents: "Black lives matter."

func Encrypt

func Encrypt(dst io.Writer, recipients ...Recipient) (io.WriteCloser, error)

Encrypt encrypts a file to one or more recipients.

Writes to the returned WriteCloser are encrypted and written to dst as an age file. Every recipient will be able to decrypt the file.

The caller must call Close on the WriteCloser when done for the last chunk to be encrypted and flushed to dst.

Example

package main

import (
	"bytes"
	"fmt"
	"io"
	"log"

	"filippo.io/age"
)

func main() {
	publicKey := "age1cy0su9fwf3gf9mw868g5yut09p6nytfmmnktexz2ya5uqg9vl9sss4euqm"
	recipient, err := age.ParseX25519Recipient(publicKey)
	if err != nil {
		log.Fatalf("Failed to parse public key %q: %v", publicKey, err)
	}

	out := &bytes.Buffer{}

	w, err := age.Encrypt(out, recipient)
	if err != nil {
		log.Fatalf("Failed to create encrypted file: %v", err)
	}
	if _, err := io.WriteString(w, "Black lives matter."); err != nil {
		log.Fatalf("Failed to write to encrypted file: %v", err)
	}
	if err := w.Close(); err != nil {
		log.Fatalf("Failed to close encrypted file: %v", err)
	}

	fmt.Printf("Encrypted file size: %d\n", out.Len())
}

Output:

Encrypted file size: 219

Types

type Identity

type Identity interface {
	Type() string
	Unwrap(block *Stanza) (fileKey []byte, err error)
}

An Identity is a private key or other value that can decrypt an opaque file key from a recipient stanza.

Unwrap must return ErrIncorrectIdentity for recipient blocks that don't match the identity, any other error might be considered fatal.

func ParseIdentities

func ParseIdentities(f io.Reader) ([]Identity, error)

ParseIdentities parses a file with one or more private key encodings, one per line. Empty lines and lines starting with "#" are ignored.

This is the same syntax as the private key files accepted by the CLI, except the CLI also accepts SSH private keys, which are not recommended for the average application.

Currently, all returned values are of type X25519Identity, but different types might be returned in the future.

Example

package main

import (
	"bytes"
	"fmt"
	"io"
	"log"
	"os"

	"filippo.io/age"
)

func main() {
	keyFile, err := os.Open("testdata/keys.txt")
	if err != nil {
		log.Fatalf("Failed to open private keys file: %v", err)
	}
	identities, err := age.ParseIdentities(keyFile)
	if err != nil {
		log.Fatalf("Failed to parse private key: %v", err)
	}

	f, err := os.Open("testdata/example.age")
	if err != nil {
		log.Fatalf("Failed to open file: %v", err)
	}

	r, err := age.Decrypt(f, identities...)
	if err != nil {
		log.Fatalf("Failed to open encrypted file: %v", err)
	}
	out := &bytes.Buffer{}
	if _, err := io.Copy(out, r); err != nil {
		log.Fatalf("Failed to read encrypted file: %v", err)
	}

	fmt.Printf("File contents: %q\n", out.Bytes())
}

Output:

File contents: "Black lives matter."

type IdentityMatcher

type IdentityMatcher interface {
	Identity
	Match(block *Stanza) error
}

IdentityMatcher can be optionally implemented by an Identity that can communicate whether it can decrypt a recipient stanza without decrypting it.

If an Identity implements IdentityMatcher, its Unwrap method will only be invoked on blocks for which Match returned nil. Match must return ErrIncorrectIdentity for recipient blocks that don't match the identity, any other error might be considered fatal.

type Recipient

type Recipient interface {
	Type() string
	Wrap(fileKey []byte) (*Stanza, error)
}

A Recipient is a public key or other value that can encrypt an opaque file key to a recipient stanza.

type ScryptIdentity

type ScryptIdentity struct {
	// contains filtered or unexported fields
}

ScryptIdentity is a password-based identity.

func NewScryptIdentity

func NewScryptIdentity(password string) (*ScryptIdentity, error)

NewScryptIdentity returns a new ScryptIdentity with the provided password.

func (*ScryptIdentity) SetMaxWorkFactor

func (i *ScryptIdentity) SetMaxWorkFactor(logN int)

SetMaxWorkFactor sets the maximum accepted scrypt work factor to 2^logN. It must be called before Unwrap.

This caps the amount of work that Decrypt might have to do to process received files. If SetMaxWorkFactor is not called, a fairly high default is used, which might not be suitable for systems processing untrusted files.

func (*ScryptIdentity) Type

func (*ScryptIdentity) Type() string

func (*ScryptIdentity) Unwrap

func (i *ScryptIdentity) Unwrap(block *Stanza) ([]byte, error)

type ScryptRecipient

type ScryptRecipient struct {
	// contains filtered or unexported fields
}

ScryptRecipient is a password-based recipient. Anyone with the password can decrypt the message.

If a ScryptRecipient is used, it must be the only recipient for the file: it can't be mixed with other recipient types and can't be used multiple times for the same file.

Its use is not recommended for automated systems, which should prefer X25519Recipient.

func NewScryptRecipient

func NewScryptRecipient(password string) (*ScryptRecipient, error)

NewScryptRecipient returns a new ScryptRecipient with the provided password.

func (*ScryptRecipient) SetWorkFactor

func (r *ScryptRecipient) SetWorkFactor(logN int)

SetWorkFactor sets the scrypt work factor to 2^logN. It must be called before Wrap.

If SetWorkFactor is not called, a reasonable default is used.

func (*ScryptRecipient) Type

func (*ScryptRecipient) Type() string

func (*ScryptRecipient) Wrap

func (r *ScryptRecipient) Wrap(fileKey []byte) (*Stanza, error)

type Stanza

type Stanza struct {
	Type string
	Args []string
	Body []byte
}

A Stanza is a section of the age header that encapsulates the file key as encrypted to a specific recipient.

type X25519Identity

type X25519Identity struct {
	// contains filtered or unexported fields
}

X25519Identity is the standard age private key, which can decrypt messages encrypted to the corresponding X25519Recipient.

func GenerateX25519Identity

func GenerateX25519Identity() (*X25519Identity, error)

GenerateX25519Identity randomly generates a new X25519Identity.

Example

package main

import (
	"fmt"
	"log"

	"filippo.io/age"
)

func main() {
	identity, err := age.GenerateX25519Identity()
	if err != nil {
		log.Fatalf("Failed to generate key pair: %v", err)
	}

	fmt.Printf("Public key: %s...\n", identity.Recipient().String()[:4])
	fmt.Printf("Private key: %s...\n", identity.String()[:16])
}

Output:

Public key: age1...
Private key: AGE-SECRET-KEY-1...

func ParseX25519Identity

func ParseX25519Identity(s string) (*X25519Identity, error)

ParseX25519Identity returns a new X25519Identity from a Bech32 private key encoding with the "AGE-SECRET-KEY-1" prefix.

func (*X25519Identity) Recipient

func (i *X25519Identity) Recipient() *X25519Recipient

Recipient returns the public X25519Recipient value corresponding to i.

func (*X25519Identity) String

func (i *X25519Identity) String() string

String returns the Bech32 private key encoding of i.

func (*X25519Identity) Type

func (*X25519Identity) Type() string

func (*X25519Identity) Unwrap

func (i *X25519Identity) Unwrap(block *Stanza) ([]byte, error)

type X25519Recipient

type X25519Recipient struct {
	// contains filtered or unexported fields
}

X25519Recipient is the standard age public key. Messages encrypted to this recipient can be decrypted with the corresponding X25519Identity.

This recipient is anonymous, in the sense that an attacker can't tell from the message alone if it is encrypted to a certain recipient.

func ParseX25519Recipient

func ParseX25519Recipient(s string) (*X25519Recipient, error)

ParseX25519Recipient returns a new X25519Recipient from a Bech32 public key encoding with the "age1" prefix.

func (*X25519Recipient) String

func (r *X25519Recipient) String() string

String returns the Bech32 public key encoding of r.

func (*X25519Recipient) Type

func (*X25519Recipient) Type() string

func (*X25519Recipient) Wrap

func (r *X25519Recipient) Wrap(fileKey []byte) (*Stanza, error)