aes

Documentation

Overview

Package aes transforms values for storage at rest using AES-GCM.

Index

• Constants
• func GenerateKey(length int) (key []byte, err error)
• func NewCBCTransformer(block cipher.Block) value.Transformer
• func NewGCMTransformer(block cipher.Block) (value.Transformer, error)
• func NewGCMTransformerWithUniqueKeyUnsafe() (value.Transformer, []byte, error)
• func NewHKDFExtendedNonceGCMTransformer(seed []byte) (value.Transformer, error)

Constants

const (
	MinSeedSizeExtendedNonceGCM
)

Functions

func GenerateKey

func GenerateKey(length int) (key []byte, err error)

GenerateKey generates a random key using system randomness.

func NewCBCTransformer

func NewCBCTransformer(block cipher.Block) value.Transformer

NewCBCTransformer takes the given block cipher and performs encryption and decryption on the given data.

func NewGCMTransformer

func NewGCMTransformer(block cipher.Block) (value.Transformer, error)

NewGCMTransformer takes the given block cipher and performs encryption and decryption on the given data. It implements AEAD encryption of the provided values given a cipher.Block algorithm. The authenticated data provided as part of the value.Context method must match when the same value is set to and loaded from storage. In order to ensure that values cannot be copied by an attacker from a location under their control, use characteristics of the storage location (such as the etcd key) as part of the authenticated data.

Because this mode requires a generated IV and IV reuse is a known weakness of AES-GCM, keys must be rotated before a birthday attack becomes feasible. NIST SP 800-38D (http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf) recommends using the same key with random 96-bit nonces (the default nonce length) no more than 2^32 times, and therefore transformers using this implementation *must* ensure they allow for frequent key rotation. Future work should include investigation of AES-GCM-SIV as an alternative to random nonces.

func NewGCMTransformerWithUniqueKeyUnsafe

func NewGCMTransformerWithUniqueKeyUnsafe() (value.Transformer, []byte, error)

NewGCMTransformerWithUniqueKeyUnsafe is the same as NewGCMTransformer but is unsafe for general use because it makes assumptions about the key underlying the block cipher. Specifically, it uses a 96-bit nonce where the first 32 bits are random data and the remaining 64 bits are a monotonically incrementing atomic counter. This means that the key must be randomly generated on process startup and must never be used for encryption outside the lifetime of the process. Unlike NewGCMTransformer, this function is immune to the birthday attack and thus the key can be used for 2^64-1 writes without rotation. Furthermore, cryptographic wear out of AES-GCM with a sequential nonce occurs after 2^64 encryptions, which is not a concern for our use cases. Even if that occurs, the nonce counter would overflow and crash the process. We have no concerns around plaintext length because all stored items are small (less than 2 MB). To prevent the chance of the block cipher being accidentally re-used, it is not taken in as input. Instead, a new random key is generated and returned on every invocation of this function. This key is used as the input to the block cipher. If the key is stored and retrieved at a later point, it can be passed to NewGCMTransformer(aes.NewCipher(key)) to construct a transformer capable of decrypting values encrypted by this transformer (that transformer must not be used for encryption).

func NewHKDFExtendedNonceGCMTransformer

func NewHKDFExtendedNonceGCMTransformer(seed []byte) (value.Transformer, error)

NewHKDFExtendedNonceGCMTransformer is the same as NewGCMTransformer but trades storage, memory and CPU to work around the limitations of AES-GCM's 12 byte nonce size. The input seed is assumed to be a cryptographically strong slice of MinSeedSizeExtendedNonceGCM+ random bytes. Unlike NewGCMTransformer, this function is immune to the birthday attack because a new key is generated per encryption via a key derivation function: KDF(seed, random_bytes) -> key. The derived key is only used once as an AES-GCM key with a random 12 byte nonce. This avoids any concerns around cryptographic wear out (by either number of encryptions or the amount of data being encrypted). Speaking on the cryptographic safety, the limit on the number of operations that can be preformed with a single seed with derived keys and randomly generated nonces is not practically reachable. Thus, the scheme does not impose any specific requirements on the seed rotation schedule. Reusing the same seed is safe to do over time and across process restarts. Whenever a new seed is needed, the caller should generate it via GenerateKey(MinSeedSizeExtendedNonceGCM). In regard to KMSv2, organization standards or compliance policies around rotation may require that the seed be rotated at some interval. This can be implemented externally by rotating the key encryption key via a key ID change.