testkit

Documentation

Overview

Package testkit provides utilities for generating chunked-encryption test vectors, including the ability to construct well-formed and malformed ciphertexts at the byte level.

Index

• Constants
• Variables
• type AEAD
• type TestVector
  • func NewTestVector(name string, aeadType AEAD) *TestVector
  • func (v *TestVector) AEADKey() []byte
  • func (v *TestVector) AEADType() AEAD
  • func (v *TestVector) AppendBytes(data []byte)
  • func (v *TestVector) BaseNonce() []byte
  • func (v *TestVector) Chunk(size int)
  • func (v *TestVector) ChunkWithPlaintext(plaintext []byte)
  • func (v *TestVector) Ciphertext() []byte
  • func (v *TestVector) Comment(c string)
  • func (v *TestVector) CommentString() string
  • func (v *TestVector) Context(ctx string)
  • func (v *TestVector) ContextString() string
  • func (v *TestVector) DeriveKeys(salt []byte) (commitment []byte)
  • func (v *TestVector) ExpandKey()
  • func (v *TestVector) ExpandKeyWithSalt(salt []byte)
  • func (v *TestVector) Expect() string
  • func (v *TestVector) ExpectFailure()
  • func (v *TestVector) ExpectHeaderFailure()
  • func (v *TestVector) ExpectPartialPayload(goodBytes int)
  • func (v *TestVector) ExpectSuccess()
  • func (v *TestVector) FlipByte(offsetFromEnd int, mask byte)
  • func (v *TestVector) InputKey() []byte
  • func (v *TestVector) Key(key []byte)
  • func (v *TestVector) Payload() []byte
  • func (v *TestVector) SetCounter(val uint64)
  • func (v *TestVector) Truncate(n int)

Constants

const ChunkOverhead = rawchunked.ChunkOverhead

const ChunkSize = rawchunked.ChunkSize

const CommitmentSize = 32

const HeaderSize = SaltSize + CommitmentSize

const SaltSize = 24

Variables

var AES128GCM = AEAD{
	Name: "AEAD_AES_128_GCM", KeySize: 16, NonceSize: 12,
	NewAEAD:   newAESGCM,
	Keystream: gcmKeystream,
}

var AES256GCM = AEAD{
	Name: "AEAD_AES_256_GCM", KeySize: 32, NonceSize: 12,
	NewAEAD:   newAESGCM,
	Keystream: gcmKeystream,
}

var TestKeyAES128 = []byte("YELLOW SUBMARINE")

var TestKeyAES256 = []byte("YELLOW SUBMARINE YELLOW SUBMARIN")

Types

type AEAD

type AEAD struct {
	// Name is the IANA AEAD name, e.g. "AEAD_AES_128_GCM".
	Name string
	// KeySize is the AEAD key size in bytes.
	KeySize int
	// NonceSize is the AEAD nonce size in bytes.
	NonceSize int
	// NewAEAD constructs a cipher.AEAD from a key.
	NewAEAD func(key []byte) cipher.AEAD
	// Keystream returns the AEAD's internal keystream for a given key and nonce.
	// Encrypting this as plaintext produces an all-zeros ciphertext body.
	Keystream func(key, nonce []byte, size int) []byte
}

AEAD identifies the AEAD algorithm used by a test vector.

type TestVector

type TestVector struct {
	Buf  bytes.Buffer // the full ciphertext being constructed
	Rand func(n int) []byte
	// contains filtered or unexported fields
}

func NewTestVector

func NewTestVector(name string, aeadType AEAD) *TestVector

func (*TestVector) AEADKey

func (v *TestVector) AEADKey() []byte

AEADKey returns the derived AEAD key.

func (*TestVector) AEADType

func (v *TestVector) AEADType() AEAD

AEADType returns the AEAD type for this vector.

func (*TestVector) AppendBytes

func (v *TestVector) AppendBytes(data []byte)

AppendBytes appends arbitrary bytes to the ciphertext buffer. This is for constructing malformed ciphertexts (e.g., trailing garbage, short chunks).

func (*TestVector) BaseNonce

func (v *TestVector) BaseNonce() []byte

BaseNonce returns the derived base nonce.

func (*TestVector) Chunk

func (v *TestVector) Chunk(size int)

Chunk encrypts size bytes of compressible plaintext and appends the encrypted chunk to Buf. The plaintext is chosen so the ciphertext body is all zeros, making the output highly compressible.

func (*TestVector) ChunkWithPlaintext

func (v *TestVector) ChunkWithPlaintext(plaintext []byte)

ChunkWithPlaintext encrypts the given plaintext and appends the encrypted chunk to Buf. It also appends the plaintext to the expected payload.

func (*TestVector) Ciphertext

func (v *TestVector) Ciphertext() []byte

Ciphertext returns the constructed ciphertext.

func (*TestVector) Comment

func (v *TestVector) Comment(c string)

func (*TestVector) CommentString

func (v *TestVector) CommentString() string

CommentString returns the comment.

func (*TestVector) Context

func (v *TestVector) Context(ctx string)

func (*TestVector) ContextString

func (v *TestVector) ContextString() string

ContextString returns the context for this vector.

func (*TestVector) DeriveKeys

func (v *TestVector) DeriveKeys(salt []byte) (commitment []byte)

DeriveKeys derives the AEAD key, base nonce, and commitment from the input key and the given salt. It does not write anything to Buf.

func (*TestVector) ExpandKey

func (v *TestVector) ExpandKey()

ExpandKey generates a random salt, derives keys, and writes the header (salt + commitment) to Buf.

func (*TestVector) ExpandKeyWithSalt

func (v *TestVector) ExpandKeyWithSalt(salt []byte)

ExpandKeyWithSalt derives keys from the given salt and writes the header (salt + commitment) to Buf.

func (*TestVector) Expect

func (v *TestVector) Expect() string

Expect returns the expected outcome.

func (*TestVector) ExpectFailure

func (v *TestVector) ExpectFailure()

func (*TestVector) ExpectHeaderFailure

func (v *TestVector) ExpectHeaderFailure()

ExpectHeaderFailure marks the vector as expecting a failure during header processing (e.g. wrong commitment). It clears the derived key material so that aead_key and base_nonce are omitted from the JSON, signaling that raw-level tests should be skipped.

func (*TestVector) ExpectPartialPayload

func (v *TestVector) ExpectPartialPayload(goodBytes int)

func (*TestVector) ExpectSuccess

func (v *TestVector) ExpectSuccess()

func (*TestVector) FlipByte

func (v *TestVector) FlipByte(offsetFromEnd int, mask byte)

FlipByte XORs the byte at the given offset from the end of the buffer.

func (*TestVector) InputKey

func (v *TestVector) InputKey() []byte

InputKey returns the input key for this vector.

func (*TestVector) Key

func (v *TestVector) Key(key []byte)

func (*TestVector) Payload

func (v *TestVector) Payload() []byte

Payload returns the expected plaintext payload.

func (*TestVector) SetCounter

func (v *TestVector) SetCounter(val uint64)

SetCounter sets the chunk counter to a specific value. This is for constructing vectors that test counter-related edge cases.

func (*TestVector) Truncate

func (v *TestVector) Truncate(n int)

Truncate removes the last n bytes from the buffer.