noncebased

Documentation

Overview

Package noncebased provides a reusable streaming AEAD framework.

It tackles the segment handling portions of the nonce based online encryption scheme proposed in "Online Authenticated-Encryption and its Nonce-Reuse Misuse-Resistance" by Hoang, Reyhanitabar, Rogaway and Vizár (https://eprint.iacr.org/2015/189.pdf).

In this scheme, the format of a ciphertext is:

header || segment_0 || segment_1 || ... || segment_k.

The format of header is:

headerLength || salt || nonce_prefix

headerLength is 1 byte which documents the size of the header and can be obtained via HeaderLength(). In principle, headerLength is redundant information, since the length of the header can be determined from the key size.

salt is a salt used in the key derivation.

nonce_prefix is a prefix for all per-segment nonces.

segment_i is the i-th segment of the ciphertext. The size of segment_1 .. segment_{k-1} is ciphertextSegmentSize. segment_0 is shorter, so that segment_0 plus additional data of size firstCiphertextSegmentOffset (e.g. the header) aligns with ciphertextSegmentSize.

The first segment size will be:

ciphertextSegmentSize - HeaderLength() - firstCiphertextSegmentOffset.

Index

• Variables
• type Reader
  • func NewReader(params ReaderParams) (*Reader, error)
  • func (r *Reader) Read(p []byte) (int, error)
• type ReaderParams
• type SegmentDecrypter
• type SegmentEncrypter
• type Writer
  • func NewWriter(params WriterParams) (*Writer, error)
  • func (w *Writer) Close() error
  • func (w *Writer) Write(p []byte) (int, error)
• type WriterParams

Variables

var (
	// ErrNonceSizeTooShort indicates that the specified nonce size isn't large
	// enough to hold the nonce prefix, counter and last segment flag.
	ErrNonceSizeTooShort = errors.New("nonce size too short")

	// ErrCiphertextSegmentTooShort indicates the the ciphertext segment being
	// processed is too short.
	ErrCiphertextSegmentTooShort = errors.New("ciphertext segment too short")

	// ErrTooManySegments indicates that the ciphertext has too many segments.
	ErrTooManySegments = errors.New("too many segments")
)

Types

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader facilitates the decryption of ciphertexts created using a Writer.

The scheme used for decrypting segments is specified by providing a SegmentDecrypter implementation. The implementation must align with the SegmentEncrypter used in the Writer.

func NewReader

func NewReader(params ReaderParams) (*Reader, error)

NewReader creates a new Reader instance.

func (*Reader) Read

func (r *Reader) Read(p []byte) (int, error)

Read decrypts data from underlying reader and passes it to p.

type ReaderParams

type ReaderParams struct {
	// R is the underlying reader being wrapped.
	R io.Reader

	// SegmentDecrypter provides a method for decrypting segments.
	SegmentDecrypter SegmentDecrypter

	// NonceSize is the length of generated nonces. It must match the NonceSize
	// of the Writer used to create the ciphertext.
	NonceSize int

	// NoncePrefix is a constant that all nocnes throughout the ciphertext start
	// with. It's extracted from the header of the ciphertext.
	NoncePrefix []byte

	// The size of the ciphertext segments.
	CiphertextSegmentSize int

	// FirstCiphertexSegmentOffset indicates where the ciphertext actually begins
	// in R. This allows for the existence of overhead in the stream unrelated to
	// this encryption scheme.
	FirstCiphertextSegmentOffset int
}

ReaderParams contains the options for instantiating a Reader via NewReader().

type SegmentDecrypter

type SegmentDecrypter interface {
	DecryptSegment(segment, nonce []byte) ([]byte, error)
}

SegmentDecrypter facilitates implementing various streaming AEAD encryption modes.

type SegmentEncrypter

type SegmentEncrypter interface {
	EncryptSegment(segment, nonce []byte) ([]byte, error)
}

SegmentEncrypter facilitates implementing various streaming AEAD encryption modes.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer provides a framework for ingesting plaintext data and writing encrypted data to the wrapped io.Writer. The scheme used for encrypting segments is specified by providing a SegmentEncrypter implementation.

func NewWriter

func NewWriter(params WriterParams) (*Writer, error)

NewWriter creates a new Writer instance.

func (*Writer) Close

func (w *Writer) Close() error

Close encrypts the remaining data, flushes it to the underlying writer and closes this writer.

func (*Writer) Write

func (w *Writer) Write(p []byte) (int, error)

Write encrypts passed data and passes the encrypted data to the underlying writer.

type WriterParams

type WriterParams struct {
	// W is the underlying writer being wrapped.
	W io.Writer

	// SegmentEncrypter provides a method for encrypting segments.
	SegmentEncrypter SegmentEncrypter

	// NonceSize is the length of generated nonces. It must be at least 5 +
	// len(NoncePrefix). It can be longer, but longer nonces introduce more
	// overhead in the resultant ciphertext.
	NonceSize int

	// NoncePrefix is a constant that all nonces throughout the ciphertext will
	// start with. It's length must be at least 5 bytes shorter than NonceSize.
	NoncePrefix []byte

	// The size of the segments which the plaintext will be split into.
	PlaintextSegmentSize int

	// FirstCiphertexSegmentOffset indicates where the ciphertext should begin in
	// W. This allows for the existence of overhead in the stream unrelated to
	// this encryption scheme.
	FirstCiphertextSegmentOffset int
}

WriterParams contains the options for instantiating a Writer via NewWriter().