etm

README

etm

A Go implementation of AES/CBC/HMAC-based AEAD constructions from draft-mcgrew-aead-aes-cbc-hmac-sha2-02.

For documentation, check godoc.

Documentation

Overview

Package etm provides a set of Encrypt-Then-MAC AEAD implementations, which combine block ciphers like AES with HMACs.

AEADs

An AEAD (Authenticated Encryption with Associated Data) construction provides a unified API for sealing messages in a way which provides both confidentiality *and* integrity.

This not only prevents malicious tampering but also eliminates online attacks like padding oracle attacks which can allow an attacker to recover plaintexts without knowledge of the secret key (e.g., Lucky 13 attack, BEAST attack, etc.).

By rejecting ciphertexts which have been modified, these types of attacks are eliminated.

Constructions

This package implements five proposed standards:

AEAD_AES_128_CBC_HMAC_SHA_256
AEAD_AES_192_CBC_HMAC_SHA_384
AEAD_AES_256_CBC_HMAC_SHA_384
AEAD_AES_256_CBC_HMAC_SHA_512
AEAD_AES_128_CBC_HMAC_SHA1

All five constructions combine AES in CBC mode with an HMAC, but vary in the degree of security offered and the amount of overhead required. See http://tools.ietf.org/html/draft-mcgrew-aead-aes-cbc-hmac-sha2-02 for full technical details.

AES-128-CBC-HMAC-SHA-256

AEAD_AES_128_CBC_HMAC_SHA_256 requires a 32-byte key, provides 128 bits of security for both confidentiality and integrity, and adds up to 56 bytes of overhead per message.

AES-192-CBC-HMAC-SHA-384

AEAD_AES_192_CBC_HMAC_SHA_384 requires a 48-byte key, provides 192 bits of security for both confidentiality and integrity, and adds up to 64 bytes of overhead per message.

AES-256-CBC-HMAC-SHA-384

AEAD_AES_256_CBC_HMAC_SHA_384 requires a 56-byte key, provides 256 bits of security for confidentiality, provides 192 bits of security for integrity, and adds up to 64 bytes of overhead per message.

AES-256-CBC-HMAC-SHA-512

AEAD_AES_256_CBC_HMAC_SHA_512 requires a 64-byte key, provides 256 bits of security for both confidentiality and integrity, and adds up to 72 bytes of overhead per message.

AES-128-CBC-HMAC-SHA1

AEAD_AES_128_CBC_HMAC_SHA1 requires a 36-byte key, provides 128 bits of security for confidentiality, provides 96 bits of security for integrity, and adds up to 52 bytes of overhead per message. (This construction uses SHA-1, and should only be used when the use of SHA2 is not possible.)

Example

key := []byte("yellow submarine was a love song")
plaintext := []byte("this is a secret value")
data := []byte("this is a public value")

aead, err := NewAES128SHA256(key)
if err != nil {
	fmt.Println(err)
	return
}

nonce := make([]byte, aead.NonceSize())
io.ReadFull(rand.Reader, nonce)

ciphertext := aead.Seal(nil, nonce, plaintext, data)

secret, err := aead.Open(nil, nil, ciphertext, data)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Println(string(secret))

Output:

this is a secret value

Index

• func NewAES128SHA1(key []byte) (cipher.AEAD, error)
• func NewAES128SHA256(key []byte) (cipher.AEAD, error)
• func NewAES192SHA384(key []byte) (cipher.AEAD, error)
• func NewAES256SHA384(key []byte) (cipher.AEAD, error)
• func NewAES256SHA512(key []byte) (cipher.AEAD, error)

Examples

• Package

Functions

func NewAES128SHA1

func NewAES128SHA1(key []byte) (cipher.AEAD, error)

NewAES128SHA1 returns an AEAD_AES_128_CBC_HMAC_SHA1 instance given a 36-byte key or an error if the key is the wrong size. AEAD_AES_128_CBC_HMAC_SHA1 combines AES-128 in CBC mode with HMAC-SHA1-96.

func NewAES128SHA256

func NewAES128SHA256(key []byte) (cipher.AEAD, error)

NewAES128SHA256 returns an AEAD_AES_128_CBC_HMAC_SHA_256 instance given a 32-byte key or an error if the key is the wrong size. AEAD_AES_128_CBC_HMAC_SHA_256 combines AES-128 in CBC mode with HMAC-SHA-256-128.

func NewAES192SHA384

func NewAES192SHA384(key []byte) (cipher.AEAD, error)

NewAES192SHA384 returns an AEAD_AES_192_CBC_HMAC_SHA_384 instance given a 48-byte key or an error if the key is the wrong size. AEAD_AES_192_CBC_HMAC_SHA_384 combines AES-192 in CBC mode with HMAC-SHA-384-192.

func NewAES256SHA384

func NewAES256SHA384(key []byte) (cipher.AEAD, error)

NewAES256SHA384 returns an AEAD_AES_256_CBC_HMAC_SHA_384 instance given a 56-byte key or an error if the key is the wrong size. AEAD_AES_256_CBC_HMAC_SHA_384 combines AES-256 in CBC mode with HMAC-SHA-384-192.

func NewAES256SHA512

func NewAES256SHA512(key []byte) (cipher.AEAD, error)

NewAES256SHA512 returns an AEAD_AES_256_CBC_HMAC_SHA_512 instance given a 64-byte key or an error if the key is the wrong size. AEAD_AES_256_CBC_HMAC_SHA_512 combines AES-256 in CBC mode with HMAC-SHA-512-256.