chacha20poly1305

README

chacha20poly1305

An implementation of the chacha20poly1305 AEAD construction from draft-agl-tls-chacha20poly1305-03.

For documentation, check godoc.

Documentation

Overview

Package chacha20poly1305 implements the AEAD_CHACHA20_POLY1305 algorithm, which combines ChaCha20, a secure stream cipher, with Poly1305, a secure MAC function.

ChaCha20 is run with the given key and nonce and with the two counter
words set to zero. The first 32 bytes of the 64 byte output are saved to
become the one-time key for Poly1305. The remainder of the output is
discarded. The first counter input word is set to one and the plaintext
is encrypted by XORing it with the output of invocations of the ChaCha20
function as needed, incrementing the first counter word after each block
and overflowing into the second.  (In the case of the TLS, limits on the
plaintext size mean that the first counter word will never overflow in
practice.)

The Poly1305 key is used to calculate a tag for the following input: the
concatenation of the number of bytes of additional data, the additional
data itself, the number of bytes of ciphertext and the ciphertext
itself. Numbers are represented as 8-byte, little-endian values.  The
resulting tag is appended to the ciphertext, resulting in the output of
the AEAD operation.

(http://tools.ietf.org/html/draft-agl-tls-chacha20poly1305-04)

The AEAD (Athenticated Encryption with Associated Data) construction provides a unified API for sealing messages in a way which provides both confidentiality *and* integrity. Unlike unauthenticated modes like CBC, AEAD algorithms are resistant to chosen ciphertext attacks, such as padding oracle attacks, etc., and add only 16 bytes of overhead.

AEAD_CHACHA20_POLY1305 has a significant speed advantage over other AEAD algorithms like AES-GCM, as well as being extremely resistant to timing attacks.

Index

• Variables
• func New(key []byte) (cipher.AEAD, error)

Examples

• New

Variables

var (
	// ErrAuthFailed is returned when the message authentication is invalid due
	// to tampering.
	ErrAuthFailed = errors.New("message authentication failed")

	// ErrInvalidKey is returned when the provided key is the wrong size.
	ErrInvalidKey = errors.New("invalid key size")

	// ErrInvalidNonce is returned when the provided nonce is the wrong size.
	ErrInvalidNonce = errors.New("invalid nonce size")

	// KeySize is the required size of ChaCha20 keys.
	KeySize = chacha20.KeySize
)

Functions

func New

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

New creates a new AEAD instance using the given key. The key must be exactly 256 bits long.

Example

package main

import (
	"fmt"

	"github.com/codahale/chacha20poly1305"
)

func readSecretKey(i int) []byte {
	return make([]byte, i)
}

func readRandomNonce(i int) []byte {
	return make([]byte, i)
}

func main() {
	key := readSecretKey(chacha20poly1305.KeySize) // must be 256 bits long

	c, err := chacha20poly1305.New(key)
	if err != nil {
		panic(err)
	}

	nonce := readRandomNonce(c.NonceSize()) // must be generated by crypto/rand
	plaintext := []byte("yay for me")
	data := []byte("whoah yeah")
	ciphertext := c.Seal(nil, nonce, plaintext, data)

	fmt.Printf("%x\n", ciphertext)
}

Output:

e6669e9e333e4a5af5df2b8d1669cbdc175bb32da46484e6e358