encryption

Documentation

Overview

Package encryption provides support for encrypting and decrypting data and files with granular key management.

It is assumed that the data being encrypted is archival and long lived.

The key management scheme supports arbitrary ciphers and many keys, the intent being to easily support using different keys per file. The encryption algorithm, blocksize, HMAC are determined by the choice of key management scheme.

The encryption interface supports both traditional block-based and AEAD APIs.

Encrypted files are layered on top of the encoding/recordio format whereby the first record in the file is used to store a header containing the necessary metadata to decrypt the remaining records in the file. For such files a single key is used to encrypt all of the data within the file. The recordio format encrypts each record as an independent block with its own encryption metadata (eg. IV, HMAC) and hence is not suitable for use with lots of small records due to the space overhead of this metadata.

The format of the header record is: crc32 of the marshalled Key Descriptor JSON record. JSON encoding of KeyDescriptor

The format of each encrypted record is: Initialization Vector (IV) encrypted(HMAC(plaintext) + plaintext)

Index

• func Register(name string, registry KeyRegistry) error
• func SetRandSource(rd io.Reader)
• type Decrypter
  • func NewDecrypter(kd KeyDescriptor) (Decrypter, error)
• type Encrypter
  • func NewEncrypter(kd KeyDescriptor) (Encrypter, error)
• type IV
  • func (iv IV) MarshalJSON() ([]byte, error)
  • func (iv *IV) UnmarshalJSON(data []byte) error
• type KeyDescriptor
• type KeyID
  • func (id KeyID) MarshalJSON() ([]byte, error)
  • func (id *KeyID) UnmarshalJSON(data []byte) error
• type KeyRegistry
  • func Lookup(name string) (KeyRegistry, error)

Functions

func Register

func Register(name string, registry KeyRegistry) error

Register registers a new KeyRegistry using the supplied name.

func SetRandSource

func SetRandSource(rd io.Reader)

SetRandSource sets the source of random numbers be used and is intended for primarily for testing purposes.

Types

type Decrypter

type Decrypter interface {
	// PlaintextSize returns the size of the decrypted plaintext
	// that will result from decrypting the supplied ciphertext.
	// Note that this size will include any checksums enrypted
	// with the original plaintext.
	PlaintextSize(ciphertext []byte) int
	// Decrypt decrypts the ciphertext in src into plaintext stored in dst and
	// returns slices that contain the checksum of the original plaintext
	// and the plaintext. dst should be at least PlainTextSize() bytes big.
	Decrypt(src, dst []byte) (sum, plaintext []byte, err error)
}

Decrypter defines decryption methods.

func NewDecrypter

func NewDecrypter(kd KeyDescriptor) (Decrypter, error)

NewDecrypter returns a new decrypter.

type Encrypter

type Encrypter interface {
	// CipherrextSize returns the size of the ciphertext that
	// that will result from supplied plaintext. It should be used
	// to size the slice supplied to Encrypt.
	CiphertextSize(plaintext []byte) int

	// CiphertextSizeSlices returns the size of the ciphertext that
	// will result from the supplied plaintext slices. It should be used
	// to size the slice supplied to EncryptSlices.
	CiphertextSizeSlices(plaintexts ...[]byte) int

	// Encrypt encrypts the plaintext in src into ciphertext in
	// dst. dst must be at least CiphertextSize() bytes large.
	Encrypt(src, dst []byte) error

	// EncryptSlices encrypts the plaintext slices as a single
	// block. It is intended to avoid the need for an external copy
	// to obtain a single buffer for use with Encrypt. The slices
	// will be decrypted as a single block.
	EncryptSlices(dst []byte, src ...[]byte) error
}

Encrypter defines encryption methods.

func NewEncrypter

func NewEncrypter(kd KeyDescriptor) (Encrypter, error)

NewEncrypter returns a new encrypter. The implementation it returns uses an encrypted HMAC/SHA512 checksum of the plaintext to ensure integrity. The format of a block is: Initialization Vector (IV) encrypted(HMAC(plaintext) + plaintext)

type IV

type IV []byte

IV represents the initialization vector used to encrypt a block.

func (IV) MarshalJSON

func (iv IV) MarshalJSON() ([]byte, error)

MarshalJSON marshals an IV as a hex encoded string.

func (*IV) UnmarshalJSON

func (iv *IV) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals a hex encoded string into an IV.

type KeyDescriptor

type KeyDescriptor struct {
	Registry string                 `json:"registry"`
	ID       KeyID                  `json:"keyid"`
	Options  map[string]interface{} `json:"options,omitempty"`
}

KeyDescriptor represents a given key and any associated options.

type KeyID

type KeyID []byte

KeyID represents the ID used to identify a particular key.

func (KeyID) MarshalJSON

func (id KeyID) MarshalJSON() ([]byte, error)

MarshalJSON marshals a KeyID as a hex encoded string.

func (*KeyID) UnmarshalJSON

func (id *KeyID) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals a hex encoded string into a KeyID.

type KeyRegistry

type KeyRegistry interface {
	GenerateKey() (ID []byte, err error)
	BlockSize() int
	HMACSize() int
	NewBlock(ID []byte, opts ...interface{}) (hmac hash.Hash, block cipher.Block, err error)
	NewGCM(block cipher.Block, opts ...interface{}) (aead cipher.AEAD, err error)
}

KeyRegistry represents a database of keys for a particular cipher, ie. implementations of KeyRegistry manage the keys for a particular cipher. AEAD is supported by wrapping the block ciphers provided.

func Lookup

func Lookup(name string) (KeyRegistry, error)

Lookup returns the key registry, if any, named by the supplied name.