plan9fox/sys/man/2/chacha

.TH CHACHA 2
.SH NAME
setupChachastate, chacha_setblock, chacha_setiv, chacha_encrypt, chacha_encrypt2, hchacha, ccpoly_encrypt, ccpoly_decrypt \- chacha encryption
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <libsec.h>
.PP
.B
void setupChachastate(Chachastate *s, uchar key[], ulong keylen, uchar *iv, ulong ivlen, int rounds)
.PP
.B
void chacha_encrypt(uchar *data, ulong len, Chachastate *s)
.PP
.B
void chacha_encrypt2(uchar *src, uchar *dst, ulong len, Chachastate *s)
.PP
.B
void chacha_setblock(Chachastate *s, u64int blockno)
.PP
.B
void chacha_setiv(Chachastate *s, uchar *iv);
.PP
.B
void hchacha(uchar h[32], uchar *key, ulong keylen, uchar nonce[16], int rounds);
.PP
.B
void ccpoly_encrypt(uchar *dat, ulong ndat, uchar *aad, ulong naad, uchar tag[16], Chachastate *cs);
.PP
.B
int ccpoly_decrypt(uchar *dat, ulong ndat, uchar *aad, ulong naad, uchar tag[16], Chachastate *cs);
.SH DESCRIPTION
.PP
Chacha is D J Berstein's symmetric stream cipher, as modified by RFC7539. It supports
keys of 256 bits (128 bits is supported here for special purposes). It has an underlying block size of 64 bytes
(named as constant
.BR ChachaBsize ).
.PP
.I SetupChachastate
takes a reference to a
.B Chachastate
structure, a
.I key
of
.I keylen
bytes, which should normally be
.BR ChachaKeylen ,
a
.I iv
or nonce of
.I ivlen
bytes (can be
.BR ChachaIVlen =12 ,
.B 8
or
.BR XChachaIVlen =24 ;
set to all zeros if the
.I iv
argument is nil),
and the number of
.I rounds
(set to the default of 20 if the argument is zero).
With a key length of 256 bits (32 bytes), a nonce of 96 bits (12 bytes)
and 20
.IR rounds ,
the function implements the Chacha20 encryption function of RFC7539.
.PP
.I Chacha_encrypt
encrypts
.I len
bytes of
.I buf
in place using the
.B Chachastate
in
.IR s .
.I Len
can be any byte length.
Encryption and decryption are the same operation given the same starting state
.IR s .
.PP
.I Chacha_encrypt2
is similar, but encrypts
.I len
bytes of
.I src
into
.I dst
without modifying
.IR src .
.PP
.I Chacha_setblock
sets the Chacha block counter for the next encryption to
.IR blockno ,
allowing seeking in an encrypted stream.
.PP
.I Chacha_setiv
sets the the initialization vector (nonce) to
.IR iv .
.PP
.I Hchacha
is a key expansion function that takes a 128 or 256-bit key 
and a 128-bit nonce and produces a new 256-bit key.
.PP
.I Ccpoly_encrypt
and
.I ccpoly_decrypt
implement authenticated encryption with associated data (AEAD)
using Chacha cipher and Poly1305 message authentication code
as specified in RFC7539.
These routines require a
.I Chachastate
that has been setup with a new (per key unique) initialization
vector (nonce) on each invocation. The referenced data
.IR dat [ ndat ]
is in-place encrypted or decrypted.
.I Ccpoly_encrypt
produces a 16 byte authentication
.IR tag ,
while
.I ccpoly_decrypt
verifies the
.IR tag ,
returning zero on success or negative on a mismatch.
The
.IR aad [ naad ]
arguments refer to the additional authenticated data
that is included in the
.I tag
calculation, but not encrypted.
.SH SOURCE
.B /sys/src/libsec
.SH SEE ALSO
.IR mp (2),
.IR aes (2),
.IR blowfish (2),
.IR des (2),
.IR dsa (2),
.IR elgamal (2),
.IR rc4 (2),
.IR rsa (2),
.IR salsa (2),
.IR sechash (2),
.IR prime (2),
.IR rand (2)