147 lines
3.2 KiB
Text
147 lines
3.2 KiB
Text
.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)
|