base: github.com/grailbio/base/crypto/encryption Index | Files

package encryption

import "github.com/grailbio/base/crypto/encryption"

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

Package Files

doc.go encryption.go iv.go registry.go

func Register Uses

func Register(name string, registry KeyRegistry) error

Register registers a new KeyRegistry using the supplied name.

func SetRandSource Uses

func SetRandSource(rd io.Reader)

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

type Decrypter Uses

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 Uses

func NewDecrypter(kd KeyDescriptor) (Decrypter, error)

NewDecrypter returns a new decrypter.

type Encrypter Uses

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 Uses

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 Uses

type IV []byte

IV represents the initialization vector used to encrypt a block.

func (IV) MarshalJSON Uses

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

MarshalJSON marshals an IV as a hex encoded string.

func (*IV) UnmarshalJSON Uses

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

UnmarshalJSON unmarshals a hex encoded string into an IV.

type KeyDescriptor Uses

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 Uses

type KeyID []byte

KeyID represents the ID used to identify a particular key.

func (KeyID) MarshalJSON Uses

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

MarshalJSON marshals a KeyID as a hex encoded string.

func (*KeyID) UnmarshalJSON Uses

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

UnmarshalJSON unmarshals a hex encoded string into a KeyID.

type KeyRegistry Uses

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 Uses

func Lookup(name string) (KeyRegistry, error)

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

Package encryption imports 8 packages (graph). Updated 2019-01-13. Refresh now. Tools for package owners.