sys/man/2/chacha

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