chacha20poly1305

README

chacha20poly1305

Deprecated: This is a legacy implementation. New users should use x/crypto/chacha20poly1305 which exclusively implements RFC7539.

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

Benchmark

BenchmarkDraftChaCha20Poly1305Codahale/1M-8         	     200	   8841226 ns/op	 118.60 MB/s	[codahale/chacha20poly1305]
BenchmarkRFCChaCha20Poly1305/1M-8                   	    2000	   1190440 ns/op	 880.83 MB/s	[tmthrgd/chacha20poly1305 - AVX only]
BenchmarkDraftChaCha20Poly1305/1M-8                 	    1000	   1219685 ns/op	 859.71 MB/s	[tmthrgd/chacha20poly1305 - AVX only]
BenchmarkXCryptoChaCha20Poly1305/1M-8               	    2000	   1071064 ns/op	 979.00 MB/s	[x/crypto/chacha20poly1305 - AVX only]
BenchmarkAESGCM/1M-8                                	    2000	    864059 ns/op	1213.55 MB/s	[crypto/aes crypto/cipher]

License

Unless otherwise noted, the chacha20poly1305 source files are distributed under The MIT License found in the LICENSE file.

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

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

Examples

• NewDraft
• NewRFC

Constants

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

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 panicked when the provided nonce is the wrong size.
	ErrInvalidNonce = errors.New("invalid nonce size")
)

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. New behaves like NewDraft.

In most cases either NewRFC or NewDraft should be used instead.

This is maintained for compatibility reasons.

func NewDraft

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

NewDraft creates a new AEAD instance using the given key. The key must be exactly 256 bits long. The returned cipher is an implementation of the draft-agl-tls-chacha20poly1305-03 AEAD construct.

Example

key := readSecretKey(KeySize) // must be 256 bits long

c, err := NewDraft(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

func NewRFC

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

NewRFC creates a new AEAD instance using the given key. The key must be exactly 256 bits long. The returned cipher is an implementation of the RFC7539 AEAD construct.

Example

key := readSecretKey(KeySize) // must be 256 bits long

c, err := NewRFC(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)