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 ¶
Examples ¶
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 ¶
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 ¶
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 ¶
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)
Output:
Types ¶
This section is empty.
Source Files