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/agessh package.
Age encrypted files are binary and not malleable, for encoding them as text, use the filippo.io/age/armor package.
Index ¶
- Variables
- func Decrypt(src io.Reader, identities ...Identity) (io.Reader, error)
- func Encrypt(dst io.Writer, recipients ...Recipient) (io.WriteCloser, error)
- type Identity
- type IdentityMatcher
- type Recipient
- type ScryptIdentity
- type ScryptRecipient
- type Stanza
- type X25519Identity
- type X25519Recipient
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrIncorrectIdentity = errors.New("incorrect identity for recipient block")
Functions ¶
func Decrypt ¶
Decrypt 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" "encoding/hex" "fmt" "io" "log" "filippo.io/age" ) var fileContents, _ = hex.DecodeString("6167652d656e6372797074696f6e2e6f72" + "672f76310a2d3e20583235353139203868726c4d2b5a4247334464346646322b61353" + "8337a64544957446b382f5234316b43595a7376775457340a794f345059646c4d5744" + "4a2b437867554e527159355a30542f6d2b6733464368356a4978474c62435658630a2" + "d2d2d20492f696d65765a7a79383132304a537a6d4a6e6d6e2f4b4d6b337035413131" + "5638334e6b34316d394e50450a70c5e53624a1520753f92c5ad10ecab273ba4d61178" + "07713e83820417a1df2ca08182272c8f85c857734a1311a3b75e98d0eaf") var privateKey = "AGE-SECRET-KEY-184JMZMVQH3E6U0PSL869004Y3U2NYV7R30EU99CSEDNPH02YUVFSZW44VU" func main() { // 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. identity, err := age.ParseX25519Identity(privateKey) if err != nil { log.Fatalf("Failed to parse private key %q: %v", privateKey, err) } out := &bytes.Buffer{} f := bytes.NewReader(fileContents) r, err := age.Decrypt(f, identity) if err != nil { log.Fatalf("Failed to open encrypted file: %v", err) } 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 ¶
Encrypt returns a WriteCloser. Writes to the returned value 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 returned value 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 ¶
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.
type IdentityMatcher ¶
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 ¶
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
type ScryptRecipient ¶
type ScryptRecipient struct {
// contains filtered or unexported fields
}
ScryptRecipient is a password-based recipient.
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
type Stanza ¶
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, based on a Curve25519 scalar.
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 X25519Recipient 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
type X25519Recipient ¶
type X25519Recipient struct {
// contains filtered or unexported fields
}
X25519Recipient is the standard age public key, based on a Curve25519 point.
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
Directories ¶
Path | Synopsis |
---|---|
Package agessh provides age.Identity and age.Recipient implementations of types "ssh-rsa" and "ssh-ed25519", which allow reusing existing SSH key files for encryption with age-encryption.org/v1.
|
Package agessh provides age.Identity and age.Recipient implementations of types "ssh-rsa" and "ssh-ed25519", which allow reusing existing SSH key files for encryption with age-encryption.org/v1. |
Package armor provides a strict, streaming implementation of the ASCII armoring format for age files.
|
Package armor provides a strict, streaming implementation of the ASCII armoring format for age files. |
cmd
|
|
internal
|
|
bech32
Package bech32 is a modified version of the reference implementation of BIP173.
|
Package bech32 is a modified version of the reference implementation of BIP173. |
format
Package format implements the age file format.
|
Package format implements the age file format. |
stream
Package stream implements a variant of the STREAM chunked encryption scheme.
|
Package stream implements a variant of the STREAM chunked encryption scheme. |