sys/man/2/aes

   1 .TH AES 2
   2 .SH NAME
   3 setupAESstate, \
   4 aesCBCencrypt, \
   5 aesCBCdecrypt, \
   6 aesCFBencrypt, \
   7 aesCFBdecrypt, \
   8 aesOFBencrypt, \
   9 aes_xts_encrypt, aes_xts_decrypt, \
  10 setupAESGCMstate, \
  11 aesgcm_setiv, aesgcm_encrypt, aesgcm_decrypt \
  12 - advanced encryption standard (rijndael)
  13 .SH SYNOPSIS
  14 .B #include <u.h>
  15 .br
  16 .B #include <libc.h>
  17 .br
  18 .B #include <mp.h>
  19 .br
  20 .B #include <libsec.h>
  21 .PP
  22 .in +0.5i
  23 .ti -0.5i
  24 .PP
  25 .B
  26 void    aes_encrypt(ulong rk[], int Nr, uchar pt[16], uchar ct[16])
  27 .PP
  28 .B
  29 void    aes_decrypt(ulong rk[], int Nr, uchar ct[16], uchar pt[16])
  30 .PP
  31 .B
  32 void    setupAESstate(AESstate *s, uchar key[], int nkey, uchar *ivec)
  33 .PP
  34 .B
  35 void    aesCBCencrypt(uchar *p, int len, AESstate *s)
  36 .PP
  37 .B
  38 void    aesCBCdecrypt(uchar *p, int len, AESstate *s)
  39 .PP
  40 .B
  41 void    aesCFBencrypt(uchar *p, int len, AESstate *s)
  42 .PP
  43 .B
  44 void    aesCFBdecrypt(uchar *p, int len, AESstate *s)
  45 .PP
  46 .B
  47 void    aesOFBencrypt(uchar *p, int len, AESstate *s)
  48 .PP
  49 .B
  50 void    aes_xts_encrypt(AESstate *tweak, AESstate *ecb, uvlong sectorNumber, uchar *input, uchar *output, ulong len)
  51 .PP
  52 .B
  53 void    aes_xts_decrypt(AESstate *tweak, AESstate *ecb, uvlong sectorNumber, uchar *input, uchar *output, ulong len)
  54 .PP
  55 .B
  56 void    setupAESGCMstate(AESGCMstate *s, uchar *key, int keylen, uchar *iv, int ivlen)
  57 .PP
  58 .B
  59 void    aesgcm_setiv(AESGCMstate *s, uchar *iv, int ivlen)
  60 .PP
  61 .B
  62 void    aesgcm_encrypt(uchar *dat, ulong ndat, uchar *aad, ulong naad, uchar tag[16], AESGCMstate *s)
  63 .PP
  64 .B
  65 int     aesgcm_decrypt(uchar *dat, ulong ndat, uchar *aad, ulong naad, uchar tag[16], AESGCMstate *s)
  66 .SH DESCRIPTION
  67 AES (a.k.a. Rijndael) has replaced DES as the preferred
  68 block cipher.
  69 .I Aes_encrypt
  70 and
  71 .I aes_decrypt
  72 are the block ciphers, corresponding to
  73 .IR des (2)'s
  74 .IR block_cipher .
  75 .I AesCBCencrypt
  76 and
  77 .I aesCBCdecrypt
  78 implement cipher-block-chaining encryption.
  79 .IR AesCFBencrypt ,
  80 .I aesCFBdecrypt
  81 and
  82 .I aesOFBencrypt
  83 implement cipher-feedback- and output-feedback-mode
  84 stream cipher encryption.
  85 .I Aes_xts_encrypt
  86 and
  87 .I aes_xts_decrypt
  88 implement the XTS-AES tweakable block cipher, per IEEE 1619-2017 (see bugs below).
  89 .IR SetupAESstate
  90 is used to initialize the state of the above encryption modes.
  91 The expanded roundkey parameters
  92 .I rk
  93 and
  94 .I Nr
  95 of
  96 .I aes_encrypt
  97 and
  98 .I aes_decrypt
  99 are returned in
 100 .I AESstate.ekey
 101 and
 102 .I AESstate.dkey
 103 with the corresponding number of rounds in
 104 .IR AESstate.rounds .
 105 .IR SetupAESGCMstate ,
 106 .IR aesgcm_setiv ,
 107 .I aesgcm_encrypt
 108 and
 109 .I aesgcm_decrypt
 110 implement Galois/Counter Mode (GCM) authenticated encryption with associated data (AEAD).
 111 Before encryption or decryption, a new initialization vector (nonce) has to be set with
 112 .I aesgcm_setiv
 113 or by calling
 114 .I setupAESGCMstate
 115 with non-zero
 116 .I iv
 117 and
 118 .I ivlen
 119 arguments.
 120 Aesgcm_decrypt returns zero when authentication and decryption where successfull and
 121 non-zero otherwise.
 122 All ciphering is performed in place.
 123 The byte keysize
 124 .I nkey
 125 should be 16, 24, or 32.
 126 The initialization vector
 127 .I ivec
 128 of
 129 .I AESbsize
 130 bytes should be random enough to be unlikely to be reused
 131 but does not need to be
 132 cryptographically strongly unpredictable.
 133 .SH SOURCE
 134 .B /sys/src/libsec
 135 .SH SEE ALSO
 136 .I aescbc
 137 in
 138 .IR secstore (1),
 139 .IR mp (2),
 140 .IR blowfish (2),
 141 .IR des (2),
 142 .IR dsa (2),
 143 .IR elgamal (2),
 144 .IR rc4 (2),
 145 .IR rsa (2),
 146 .IR sechash (2),
 147 .IR prime (2),
 148 .IR rand (2)
 149 .br
 150 .B http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
 151 .SH BUGS
 152 Because of the way that non-multiple-of-16 buffers are handled,
 153 .I aesCBCdecrypt
 154 must be fed buffers of the same size as the
 155 .I aesCBCencrypt
 156 calls that encrypted it.
 157 .PP
 158 The functions
 159 .I aes_xts_encrypt
 160 an
 161 .I aes_xts_decrypt
 162 abort on a non-multiple-of-16 length as ciphertext stealing
 163 is not implemented.