aes12

README

aes12

This package modifies the AES-GCM implementation from Go's standard library to use 12 byte tag sizes. It is not intended for a general audience, and used in quic-go.

To make use of the in-place encryption / decryption feature, the dst parameter to Seal and Open should be 16 bytes longer than plaintext, not 12.

Command for testing:

go test . --bench=. && GOARCH=386 go test . --bench=.

The output (on my machine):

BenchmarkAESGCMSeal1K-8   	 3000000	       467 ns/op	2192.37 MB/s
BenchmarkAESGCMOpen1K-8   	 3000000	       416 ns/op	2456.72 MB/s
BenchmarkAESGCMSeal8K-8   	  500000	      2742 ns/op	2986.53 MB/s
BenchmarkAESGCMOpen8K-8   	  500000	      2791 ns/op	2934.65 MB/s
PASS
ok  	github.com/lucas-clemente/aes12	6.383s
BenchmarkAESGCMSeal1K-8   	   50000	     35233 ns/op	  29.06 MB/s
BenchmarkAESGCMOpen1K-8   	   50000	     34529 ns/op	  29.66 MB/s
BenchmarkAESGCMSeal8K-8   	    5000	    262678 ns/op	  31.19 MB/s
BenchmarkAESGCMOpen8K-8   	    5000	    267296 ns/op	  30.65 MB/s
PASS
ok  	github.com/lucas-clemente/aes12	6.972s

Documentation

Overview

package aes12 implements standard block cipher modes that can be wrapped around low-level block cipher implementations. See http://csrc.nist.gov/groups/ST/toolkit/BCM/current_modes.html and NIST Special Publication 800-38A.

package aes12 implements AES encryption (formerly Rijndael), as defined in U.S. Federal Information Processing Standards Publication 197.

Index

• Constants
• type AEAD
  • func NewGCM(cipher Block) (AEAD, error)
  • func NewGCMWithNonceSize(cipher Block, size int) (AEAD, error)
• type Block
  • func NewCipher(key []byte) (Block, error)
• type BlockMode
• type KeySizeError
  • func (k KeySizeError) Error() string
• type Stream

Constants

const BlockSize = 16

The AES block size in bytes.

Types

type AEAD

type AEAD interface {
	// NonceSize returns the size of the nonce that must be passed to Seal
	// and Open.
	NonceSize() int

	// Overhead returns the maximum difference between the lengths of a
	// plaintext and its ciphertext.
	Overhead() int

	// Seal encrypts and authenticates plaintext, authenticates the
	// additional data and appends the result to dst, returning the updated
	// slice. The nonce must be NonceSize() bytes long and unique for all
	// time, for a given key.
	//
	// The plaintext and dst may alias exactly or not at all. To reuse
	// plaintext's storage for the encrypted output, use plaintext[:0] as dst.
	Seal(dst, nonce, plaintext, additionalData []byte) []byte

	// Open decrypts and authenticates ciphertext, authenticates the
	// additional data and, if successful, appends the resulting plaintext
	// to dst, returning the updated slice. The nonce must be NonceSize()
	// bytes long and both it and the additional data must match the
	// value passed to Seal.
	//
	// The ciphertext and dst may alias exactly or not at all. To reuse
	// ciphertext's storage for the decrypted output, use ciphertext[:0] as dst.
	//
	// Even if the function fails, the contents of dst, up to its capacity,
	// may be overwritten.
	Open(dst, nonce, ciphertext, additionalData []byte) ([]byte, error)
}

AEAD is a cipher mode providing authenticated encryption with associated data. For a description of the methodology, see

https://en.wikipedia.org/wiki/Authenticated_encryption

func NewGCM

func NewGCM(cipher Block) (AEAD, error)

NewGCM returns the given 128-bit, block cipher wrapped in Galois Counter Mode with the standard nonce length.

func NewGCMWithNonceSize

func NewGCMWithNonceSize(cipher Block, size int) (AEAD, error)

NewGCMWithNonceSize returns the given 128-bit, block cipher wrapped in Galois Counter Mode, which accepts nonces of the given length.

Only use this function if you require compatibility with an existing cryptosystem that uses non-standard nonce lengths. All other users should use NewGCM, which is faster and more resistant to misuse.

type Block

type Block interface {
	// BlockSize returns the cipher's block size.
	BlockSize() int

	// Encrypt encrypts the first block in src into dst.
	// Dst and src may point at the same memory.
	Encrypt(dst, src []byte)

	// Decrypt decrypts the first block in src into dst.
	// Dst and src may point at the same memory.
	Decrypt(dst, src []byte)
}

A Block represents an implementation of block cipher using a given key. It provides the capability to encrypt or decrypt individual blocks. The mode implementations extend that capability to streams of blocks.

func NewCipher

func NewCipher(key []byte) (Block, error)

NewCipher creates and returns a new Block. The key argument should be the AES key, either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256.

type BlockMode

type BlockMode interface {
	// BlockSize returns the mode's block size.
	BlockSize() int

	// CryptBlocks encrypts or decrypts a number of blocks. The length of
	// src must be a multiple of the block size. Dst and src may point to
	// the same memory.
	CryptBlocks(dst, src []byte)
}

A BlockMode represents a block cipher running in a block-based mode (CBC, ECB etc).

type KeySizeError

type KeySizeError int

func (KeySizeError) Error

func (k KeySizeError) Error() string

type Stream

type Stream interface {
	// XORKeyStream XORs each byte in the given slice with a byte from the
	// cipher's key stream. Dst and src may point to the same memory.
	// If len(dst) < len(src), XORKeyStream should panic. It is acceptable
	// to pass a dst bigger than src, and in that case, XORKeyStream will
	// only update dst[:len(src)] and will not touch the rest of dst.
	XORKeyStream(dst, src []byte)
}

A Stream represents a stream cipher.