stream

README

stream

The OAE2 STREAM algorithm.

Security

Disclosure

This project uses full disclosure. If you find a security bug in an implementation, please e-mail me or create a GitHub issue.

Disclaimer

You should only use cryptography libraries that have been reviewed by cryptographers or cryptography engineers. While I am a cryptography engineer, I'm not your cryptography engineer, and I have not had this project reviewed by any other cryptographers.

Documentation

Overview

Package stream implements OAE2 STREAM.

OAE stands for Online Authenticated Encryption. Here, the term "online" means plaintext and ciphertext can be encrypted and decrypted, respectively, with one left-to-right pass stream. In other words, it supports streaming.

OAE2 is a simple construction: the plaintext is broken into chunks and each chunk is encrypted separately. A counter nonce is used to ensure unique nonces and to provider ordering.

This package implements STREAM using XChaCha20-Poly1305. Each plaintext chunk_n in {0, 1, ..., N-2} is exactly 64 KiB with the final plaintext chunk_{N-1} being an arbitrary size less than or equal to 64 KiB. In other words, every chunk is the same size, except the final chunk may be a smaller.

Borrowing from Hoang and Shen [tink], this package adds a random prefix to the nonces, increasing the concrete security bound. More specifically:

prefix counter eof
  152    32     8  bits

The EOF byte signals the end of the stream. Without an explicit EOF signal the stream could be susceptible to truncation attacks.

As always, it is not a good idea to act on a plaintext until the entire message has been verified.

References:

[stream]: https://eprint.iacr.org/2015/189.pdf
[tink]: https://eprint.iacr.org/2020/1019.pdf
[hkdf]: https://tools.ietf.org/html/rfc5869

Index

• Constants
• func NewReader(r io.Reader, key []byte, opts ...Option) (io.Reader, error)
• func NewWriter(w io.Writer, key []byte, opts ...Option) (io.WriteCloser, error)
• type Option
  • func WithAdditionalData(data []byte) Option
  • func WithInfo(info []byte) Option
  • func WithRand(r io.Reader) Option

Constants

const (
	// ChunkSize is the size of a plaintext chunk.
	ChunkSize = 1 << 16
)

Functions

func NewReader

func NewReader(r io.Reader, key []byte, opts ...Option) (io.Reader, error)

NewReader creates a ReadCloser that reads plaintext from r.

func NewWriter

func NewWriter(w io.Writer, key []byte, opts ...Option) (io.WriteCloser, error)

NewWriter creates a WriteCloser that writes ciphertext to w.

NewWriter derives the actual encryption key with HKDF.

In general, it is unsafe to reuse a key.

Types

type Option

type Option func(*option)

Option configures NewReader and NewWriter.

func WithAdditionalData

func WithAdditionalData(data []byte) Option

WithAdditionalData sets additional authenticated data used in each encryption.

Additional data is typically used to bind the ciphertext to a particular contect.

By default, no additional data is used.

func WithInfo

func WithInfo(info []byte) Option

WithInfo sets the HKDF 'info' parameter used when deriving the encryption key.

The info parameter is typically used to bind the key to a particular context hkdf.

By default, the info parameter is not used.

func WithRand

func WithRand(r io.Reader) Option

WithRand sets the Reader that supplies randomness to NewWriter.

By default, rand.Reader is used.