age

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.

Backwards compatibility

Files encrypted with a stable version (not alpha, beta, or release candidate) of age, or with any v1.0.0 beta or release candidate, will decrypt with any later versions of the v1 API. This might change in v2, in which case v1 will be maintained with security fixes for compatibility with older files.

If decrypting an older file poses a security risk, doing so might require an explicit opt-in in the API.

Index

• Variables
• func Decrypt(src io.Reader, identities ...Identity) (io.Reader, error)
• func DecryptByX25519PrivateKey(in []byte, privateKey, prefix string) (out []byte, err error)
• func Encrypt(dst io.Writer, recipients ...Recipient) (io.WriteCloser, error)
• func EncryptByX25519PublicKey(in []byte, publicKey, prefix string) (out []byte, err error)
• type Identity
• type NoIdentityMatchError
  • func (*NoIdentityMatchError) Error() string
• type Recipient
• type ScryptRecipient
  • 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) PrivateKey(prefix string) (private string, err error)
  • func (i *X25519Identity) PublicKey(prefix string) (public string, err error)
  • func (i *X25519Identity) Recipient() *X25519Recipient
  • func (i *X25519Identity) String() string
  • func (i *X25519Identity) Unwrap(stanzas []*Stanza) ([]byte, error)
• type X25519Recipient
  • func ParseX25519Recipient(s string) (*X25519Recipient, error)
  • func (r *X25519Recipient) String() string
  • func (r *X25519Recipient) Wrap(fileKey []byte) ([]*Stanza, error)

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.

func DecryptByX25519PrivateKey

func DecryptByX25519PrivateKey(in []byte, privateKey, prefix string) (out []byte, err error)

DecryptByX25519PrivateKey decrypt the bytes by private key, add by xiaoyang-chen.

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.

func EncryptByX25519PublicKey

func EncryptByX25519PublicKey(in []byte, publicKey, prefix string) (out []byte, err error)

EncryptByX25519PublicKey encrypt the bytes by public key, add by xiaoyang-chen.

Types

type Identity

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

An Identity is passed to Decrypt to unwrap an opaque file key from a recipient stanza. It can be for example a secret key like X25519Identity, a plugin, or a custom implementation.

Unwrap must return an error wrapping ErrIncorrectIdentity if none of the recipient stanzas match the identity, any other error will be considered fatal.

Most age API users won't need to interact with this directly, and should instead pass Recipient implementations to Encrypt and Identity implementations to Decrypt.

type NoIdentityMatchError

type NoIdentityMatchError struct {
	// Errors is a slice of all the errors returned to Decrypt by the Unwrap
	// calls it made. They all wrap ErrIncorrectIdentity.
	Errors []error
}

NoIdentityMatchError is returned by Decrypt when none of the supplied identities match the encrypted file.

func (*NoIdentityMatchError) Error

func (*NoIdentityMatchError) Error() string

type Recipient

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

A Recipient is passed to Encrypt to wrap an opaque file key to one or more recipient stanza(s). It can be for example a public key like X25519Recipient, a plugin, or a custom implementation.

Most age API users won't need to interact with this directly, and should instead pass Recipient implementations to Encrypt and Identity implementations to Decrypt.

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 (*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.

Most age API users won't need to interact with this directly, and should instead pass Recipient implementations to Encrypt and Identity implementations to Decrypt.

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.

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) PrivateKey

func (i *X25519Identity) PrivateKey(prefix string) (private string, err error)

PrivateKey returns the Bech32 private key(Upper) with prefix encoding of i, add by xiaoyang-chen.

func (*X25519Identity) PublicKey

func (i *X25519Identity) PublicKey(prefix string) (public string, err error)

PublicKey returns the Bech32 public key encoding of i, add by xiaoyang-chen.

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) Unwrap

func (i *X25519Identity) Unwrap(stanzas []*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) Wrap

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