keyfile

README

keyfile

The keyfile package provides an interface to read and write encryption keys and other sensitive secrets in a persistent format protected by a passphrase. The passphrase is expanded to an encryption key using the scrypt algorithm, and used to symmetrically encrypt key material with AES-256.

Documentation

Overview

Package keyfile provides an interface to read and write small secrets such as encryption keys in a persistent format protected by a passphrase.

Each secret is stored in a binary packet, inside which the secret is encrypted and authenticated with AES-256 in Galois Counter Mode (GCM). The encryption key is derived from a user passphrase using the scrypt algorithm.

The binary packet is structured as follows:

Pos          Len     Description
0            3       Format tag, "KF\x02" == "\x4b\x46\x02"
3            1       Length of key generation salt in bytes (slen)
4            1       Length of GCM nonce in bytes (nlen)
5            slen    Key generation salt
5+slen       nlen    GCM nonce
5+slen+nlen  dlen    The encrypted data packet (to end)

The data packet is encrypteed with AES-256 in GCM.

Index

• Variables
• func LoadKey(path string, pf func() (string, error)) ([]byte, error)
• type File
  • func New() *File
  • func Parse(data []byte) (*File, error)
  • func (f *File) Encode() []byte
  • func (f *File) Get(passphrase string) ([]byte, error)
  • func (f *File) Random(passphrase string, nbytes int) ([]byte, error)
  • func (f *File) Set(passphrase string, secret []byte) error

Variables

var (
	// ErrBadPassphrase is reported when a passphrase decrypt a key.
	ErrBadPassphrase = errors.New("invalid passphrase")

	// ErrNoKey is reported by Get when the keyfile has no key.
	ErrNoKey = errors.New("no key is present")

	// ErrBadPacket is reported when parsing an invalid keyfile packet.
	ErrBadPacket = errors.New("parse: bad packet")
)

Functions

func LoadKey

func LoadKey(path string, pf func() (string, error)) ([]byte, error)

LoadKey is a convenience function to load and decrypt the contents of a key from a stored binary-format keyfile. The pf function is called to obtain a passphrase.

Types

type File

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

A File represents a keyfile. A zero value is ready for use.

func New

func New() *File

New creates a new empty *File.

func Parse

func Parse(data []byte) (*File, error)

Parse parses a binary keyfile packet into a *File.

func (*File) Encode

func (f *File) Encode() []byte

Encode encodes f in binary format for storage, such that keyfile.Parse(f.Encode()) is equivalent to f.

func (*File) Get

func (f *File) Get(passphrase string) ([]byte, error)

Get decrypts and returns the key from f using the given passphrase. It returns ErrBadPassphrase if the key cannot be decrypted. It returns ErrNoKey if f is empty.

func (*File) Random

func (f *File) Random(passphrase string, nbytes int) ([]byte, error)

Random generates a random secret with the given length, encrypts it with the passphrase, and stores it in f, replacing any previous data. The generated secret is returned. It is an error if nbytes <= 0.

func (*File) Set

func (f *File) Set(passphrase string, secret []byte) error

Set encrypts the secret with the passphrase and stores it in f, replacing any previous data.