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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Register ¶
func Register(name string, registry KeyRegistry) error
Register registers a new KeyRegistry using the supplied name.
func SetRandSource ¶
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 ¶
MarshalJSON marshals an IV as a hex encoded string.
func (*IV) UnmarshalJSON ¶
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 ¶
MarshalJSON marshals a KeyID as a hex encoded string.
func (*KeyID) UnmarshalJSON ¶
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.
Source Files