agekd

README

Age (Deterministic) Key Derivation

AgeKD is a Go library that can be used to derive age X25519 identities deterministically from keys or passwords.

This package does not provide a CLI. If you need that functionality, check out age-keygen-deterministic.

See the upstream age documentation for further guidance on working with age identities and recipients.

When would you use this?

• You already have key material and want to use it for age operations.
• Your execution environment has the capability to generate cryptographically secure keys, but it prevents your program from persisting custom keys.
• You want to programmatically derive age identities from passwords.

Installation

Inside your project folder, run:

go get github.com/awnumar/agekd

Usage

To generate an age identity from a high-entropy key:

identity, err := agekd.X25519IdentityFromKey(key, nil)
if err != nil {
    // handle error
}
_ = identity // *age.X25519Identity

To generate multiple age identities from a single key, specify a salt:

identity, err := agekd.X25519IdentityFromKey(key, []byte("hello"))

To generate an age identity from a password:

identity, err := agekd.X25519IdentityFromPassword(password, nil)

The default Argon2id parameters are:

DefaultArgon2idTime    uint32 = 4
DefaultArgon2idMemory  uint32 = 6291456 // KiB = 6 GiB
DefaultArgon2idThreads uint8  = 8

which takes ~3s per hash on an AMD 5800X3D 8-Core CPU. You can select your own parameters with:

identity, err := agekd.X25519IdentityFromPasswordWithParameters(password, nil, time, memory, threads)

For guidance on Argon2id parameter selection, refer to rfc9106.

Licensing

Unless otherwise specified within a file, this code is distributed under the MIT license.

The bech32 package was copied verbatim from https://github.com/FiloSottile/age/tree/v1.2.0/internal/bech32

Documentation

Index

• Constants
• func X25519IdentityFromKey(key, salt []byte) (*age.X25519Identity, error)
• func X25519IdentityFromPassword(password, salt []byte) (*age.X25519Identity, error)
• func X25519IdentityFromPasswordWithParameters(password, salt []byte, argon2idTime, argon2idMemory uint32, ...) (*age.X25519Identity, error)

Constants

const (
	DefaultArgon2idTime    uint32 = 4
	DefaultArgon2idMemory  uint32 = 6291456 // KiB = 6 GiB
	DefaultArgon2idThreads uint8  = 8
)

Functions

func X25519IdentityFromKey

func X25519IdentityFromKey(key, salt []byte) (*age.X25519Identity, error)

X25519IdentityFromKey derives an age identity from a high-entropy key. Callers are responsible for ensuring that the provided key is suitably generated, e.g. by reading it from crypto/rand.

func X25519IdentityFromPassword

func X25519IdentityFromPassword(password, salt []byte) (*age.X25519Identity, error)

X25519IdentityFromPassword derives an age identity from a password using Argon2id, with strong default parameters.

func X25519IdentityFromPasswordWithParameters

func X25519IdentityFromPasswordWithParameters(password, salt []byte, argon2idTime, argon2idMemory uint32, argon2idThreads uint8) (*age.X25519Identity, error)

X25519IdentityFromPasswordWithParameters derives an age identity from a password, with custom Argon2id parameters.