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 with AES-256 in CTR mode. 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\x01" == "\x4b\x46\x01"
3           1       Length of initialization vector in bytes (ilen)
4           1       Length of key generation salt in bytes (slen)
5           ilen    Initialization vector
5+ilen      slen    Key generation salt
5+ilen+slen 4+dlen  The encrypted data packet (see below)

The data packet is encrypted with AES-256 in CTR mode. The plaintext packet for user data of dlen bytes has this format:

Pos    Len   Description
0      4     IEEE CRC32 of (init + salt + userData); network byte order
4      dlen  User data

Thus, the minimum syntactically valid file is 9 bytes in length, with ilen = slen = dlen = 0, the format tag, and the 4-byte CRC.

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.