sys/man/2/chacha

   1 .TH CHACHA 2
   2 .SH NAME
   3 setupChachastate, chacha_setblock, chacha_setiv, chacha_encrypt, chacha_encrypt2, hchacha, ccpoly_encrypt, ccpoly_decrypt \- chacha encryption
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .br
   9 .B #include <libsec.h>
  10 .PP
  11 .B
  12 void setupChachastate(Chachastate *s, uchar key[], ulong keylen, uchar *iv, ulong ivlen, int rounds)
  13 .PP
  14 .B
  15 void chacha_encrypt(uchar *data, ulong len, Chachastate *s)
  16 .PP
  17 .B
  18 void chacha_encrypt2(uchar *src, uchar *dst, ulong len, Chachastate *s)
  19 .PP
  20 .B
  21 void chacha_setblock(Chachastate *s, u64int blockno)
  22 .PP
  23 .B
  24 void chacha_setiv(Chachastate *s, uchar *iv);
  25 .PP
  26 .B
  27 void hchacha(uchar h[32], uchar *key, ulong keylen, uchar nonce[16], int rounds);
  28 .PP
  29 .B
  30 void ccpoly_encrypt(uchar *dat, ulong ndat, uchar *aad, ulong naad, uchar tag[16], Chachastate *cs);
  31 .PP
  32 .B
  33 int ccpoly_decrypt(uchar *dat, ulong ndat, uchar *aad, ulong naad, uchar tag[16], Chachastate *cs);
  34 .SH DESCRIPTION
  35 .PP
  36 Chacha is D J Berstein's symmetric stream cipher, as modified by RFC7539. It supports
  37 keys of 256 bits (128 bits is supported here for special purposes). It has an underlying block size of 64 bytes
  38 (named as constant
  39 .BR ChachaBsize ).
  40 .PP
  41 .I SetupChachastate
  42 takes a reference to a
  43 .B Chachastate
  44 structure, a
  45 .I key
  46 of
  47 .I keylen
  48 bytes, which should normally be
  49 .BR ChachaKeylen ,
  50 a
  51 .I iv
  52 or nonce of
  53 .I ivlen
  54 bytes (can be
  55 .BR ChachaIVlen =12 ,
  56 .B 8
  57 or
  58 .BR XChachaIVlen =24 ;
  59 set to all zeros if the
  60 .I iv
  61 argument is nil),
  62 and the number of
  63 .I rounds
  64 (set to the default of 20 if the argument is zero).
  65 With a key length of 256 bits (32 bytes), a nonce of 96 bits (12 bytes)
  66 and 20
  67 .IR rounds ,
  68 the function implements the Chacha20 encryption function of RFC7539.
  69 .PP
  70 .I Chacha_encrypt
  71 encrypts
  72 .I len
  73 bytes of
  74 .I buf
  75 in place using the
  76 .B Chachastate
  77 in
  78 .IR s .
  79 .I Len
  80 can be any byte length.
  81 Encryption and decryption are the same operation given the same starting state
  82 .IR s .
  83 .PP
  84 .I Chacha_encrypt2
  85 is similar, but encrypts
  86 .I len
  87 bytes of
  88 .I src
  89 into
  90 .I dst
  91 without modifying
  92 .IR src .
  93 .PP
  94 .I Chacha_setblock
  95 sets the Chacha block counter for the next encryption to
  96 .IR blockno ,
  97 allowing seeking in an encrypted stream.
  98 .PP
  99 .I Chacha_setiv
 100 sets the the initialization vector (nonce) to
 101 .IR iv .
 102 .PP
 103 .I Hchacha
 104 is a key expansion function that takes a 128 or 256-bit key
 105 and a 128-bit nonce and produces a new 256-bit key.
 106 .PP
 107 .I Ccpoly_encrypt
 108 and
 109 .I ccpoly_decrypt
 110 implement authenticated encryption with associated data (AEAD)
 111 using Chacha cipher and Poly1305 message authentication code
 112 as specified in RFC7539.
 113 These routines require a
 114 .I Chachastate
 115 that has been setup with a new (per key unique) initialization
 116 vector (nonce) on each invocation. The referenced data
 117 .IR dat [ ndat ]
 118 is in-place encrypted or decrypted.
 119 .I Ccpoly_encrypt
 120 produces a 16 byte authentication
 121 .IR tag ,
 122 while
 123 .I ccpoly_decrypt
 124 verifies the
 125 .IR tag ,
 126 returning zero on success or negative on a mismatch.
 127 The
 128 .IR aad [ naad ]
 129 arguments refer to the additional authenticated data
 130 that is included in the
 131 .I tag
 132 calculation, but not encrypted.
 133 .SH SOURCE
 134 .B /sys/src/libsec
 135 .SH SEE ALSO
 136 .IR mp (2),
 137 .IR aes (2),
 138 .IR blowfish (2),
 139 .IR des (2),
 140 .IR dsa (2),
 141 .IR elgamal (2),
 142 .IR rc4 (2),
 143 .IR rsa (2),
 144 .IR salsa (2),
 145 .IR sechash (2),
 146 .IR prime (2),
 147 .IR rand (2)