chacha20

README

chacha20

A pure Go implementation of the ChaCha20 stream cipher.

For documentation, check godoc.

Documentation

Overview

Package chacha20 provides a pure Go implementation of ChaCha20, a fast, secure stream cipher.

From Bernstein, Daniel J. "ChaCha, a variant of Salsa20." Workshop Record of SASC. 2008. (http://cr.yp.to/chacha/chacha-20080128.pdf):

ChaCha8 is a 256-bit stream cipher based on the 8-round cipher Salsa20/8.
The changes from Salsa20/8 to ChaCha8 are designed to improve diffusion per
round, conjecturally increasing resistance to cryptanalysis, while
preserving -- and often improving -- time per round. ChaCha12 and ChaCha20
are analogous modifications of the 12-round and 20-round ciphers Salsa20/12
and Salsa20/20. This paper presents the ChaCha family and explains the
differences between Salsa20 and ChaCha.

For more information, see http://cr.yp.to/chacha.html

Index

• Constants
• Variables
• func New(key []byte, nonce []byte) (cipher.Stream, error)
• func NewWithRounds(key []byte, nonce []byte, rounds uint8) (cipher.Stream, error)
• func NewXChaCha(key []byte, nonce []byte) (cipher.Stream, error)
• func NewXChaChaWithRounds(key []byte, nonce []byte, rounds uint8) (cipher.Stream, error)
• Bugs

Constants

const (
	// KeySize is the length of ChaCha20 keys, in bytes.
	KeySize = 32
	// NonceSize is the length of ChaCha20 nonces, in bytes.
	NonceSize = 8
	// XNonceSize is the length of XChaCha20 nonces, in bytes.
	XNonceSize = 24
)

Variables

var (
	// ErrInvalidKey is returned when the provided key is not 256 bits long.
	ErrInvalidKey = errors.New("invalid key length (must be 256 bits)")
	// ErrInvalidNonce is returned when the provided nonce is not 64 bits long.
	ErrInvalidNonce = errors.New("invalid nonce length (must be 64 bits)")
	// ErrInvalidXNonce is returned when the provided nonce is not 192 bits
	// long.
	ErrInvalidXNonce = errors.New("invalid nonce length (must be 192 bits)")
	// ErrInvalidRounds is returned when the provided rounds is not
	// 8, 12, or 20.
	ErrInvalidRounds = errors.New("invalid rounds number (must be 8, 12, or 20)")
)

Functions

func New

func New(key []byte, nonce []byte) (cipher.Stream, error)

New creates and returns a new cipher.Stream. The key argument must be 256 bits long, and the nonce argument must be 64 bits long. The nonce must be randomly generated or used only once. This Stream instance must not be used to encrypt more than 2^70 bytes (~1 zettabyte).

func NewWithRounds

func NewWithRounds(key []byte, nonce []byte, rounds uint8) (cipher.Stream, error)

NewWithRounds creates and returns a new cipher.Stream just like New but the rounds number of 8, 12, or 20 can be specified.

func NewXChaCha

func NewXChaCha(key []byte, nonce []byte) (cipher.Stream, error)

NewXChaCha creates and returns a new cipher.Stream. The key argument must be 256 bits long, and the nonce argument must be 192 bits long. The nonce must be randomly generated or only used once. This Stream instance must not be used to encrypt more than 2^70 bytes (~1 zetta byte).

func NewXChaChaWithRounds

func NewXChaChaWithRounds(key []byte, nonce []byte, rounds uint8) (cipher.Stream, error)

NewXChaChaWithRounds creates and returns a new cipher.Stream just like NewXChaCha but the rounds number of 8, 12, or 20 can be specified.

Notes

Bugs

• Totally untested on big-endian CPUs. Would very much appreciate someone with an ARM device giving this a swing.