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 setupAESXCBCstate, aesXCBCmac, \
  11 setupAESGCMstate, \
  12 aesgcm_setiv, aesgcm_encrypt, aesgcm_decrypt \
  13 - advanced encryption standard (rijndael)
  14 .SH SYNOPSIS
  15 .B #include <u.h>
  16 .br
  17 .B #include <libc.h>
  18 .br
  19 .B #include <mp.h>
  20 .br
  21 .B #include <libsec.h>
  22 .PP
  23 .in +0.5i
  24 .ti -0.5i
  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 keybytes, 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    setupAESXCBCstate(AESstate *s)
  57 .PP
  58 .B
  59 void    aesXCBCmac(uchar *p, int len, AESstate *s)
  60 .PP
  61 .B
  62 void    setupAESGCMstate(AESGCMstate *s, uchar *key, int keylen, uchar *iv, int ivlen)
  63 .PP
  64 .B
  65 void    aesgcm_setiv(AESGCMstate *s, uchar *iv, int ivlen)
  66 .PP
  67 .B
  68 void    aesgcm_encrypt(uchar *dat, ulong ndat, uchar *aad, ulong naad, uchar tag[16], AESGCMstate *s)
  69 .PP
  70 .B
  71 int     aesgcm_decrypt(uchar *dat, ulong ndat, uchar *aad, ulong naad, uchar tag[16], AESGCMstate *s)
  72 .SH DESCRIPTION
  73 AES (a.k.a. Rijndael) has replaced DES as the preferred
  74 block cipher.
  75 .I Aes_encrypt
  76 and
  77 .I aes_decrypt
  78 are the block ciphers, corresponding to
  79 .IR des (2)'s
  80 .IR block_cipher .
  81 .IR AesCBCencrypt ,
  82 and
  83 .I aesCBCdecrypt
  84 implement cipher-block-chaining encryption.
  85 .IR AesCFBencrypt ,
  86 .I aesCFBdecrypt
  87 and
  88 .I aesOFBencrypt
  89 implement cipher-feedback- and output-feedback-mode
  90 stream cipher encryption.
  91 .I Aes_xts_encrypt
  92 and
  93 .I aes_xts_decrypt
  94 implement the XTS-AES tweakable block cipher, per IEEE 1619-2017 (see bugs below).
  95 .IR SetupAESstate
  96 is used to initialize the state of the above encryption modes.
  97 .I SetupAESXCBCstate
  98 and
  99 .I aesXCBCmac
 100 implement AES XCBC message authentication, per RFC 3566.
 101 .IR SetupAESGCMstate ,
 102 .IR aesgcm_setiv ,
 103 .I aesgcm_encrypt
 104 and
 105 .I aesgcm_decrypt
 106 implement Galois/Counter Mode (GCM) authenticated encryption with associated data (AEAD).
 107 Before encryption or decryption, a new initialization vector (nonce) has to be set with
 108 .I aesgcm_setiv
 109 or by calling
 110 .I setupAESGCMstate
 111 with non-zero
 112 .I iv
 113 and
 114 .I ivlen
 115 arguments.
 116 Aesgcm_decrypt returns zero when authentication and decryption where successfull and
 117 non-zero otherwise.
 118 All ciphering is performed in place.
 119 .I Keybytes
 120 should be 16, 24, or 32.
 121 The initialization vector
 122 .I ivec
 123 of
 124 .I AESbsize
 125 bytes should be random enough to be unlikely to be reused
 126 but does not need to be
 127 cryptographically strongly unpredictable.
 128 .SH SOURCE
 129 .B /sys/src/libsec
 130 .SH SEE ALSO
 131 .I aescbc
 132 in
 133 .IR secstore (1),
 134 .IR mp (2),
 135 .IR blowfish (2),
 136 .IR des (2),
 137 .IR dsa (2),
 138 .IR elgamal (2),
 139 .IR rc4 (2),
 140 .IR rsa (2),
 141 .IR sechash (2),
 142 .IR prime (2),
 143 .IR rand (2)
 144 .br
 145 .B http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
 146 .SH BUGS
 147 The functions
 148 .IR aes_encrypt ,
 149 .IR aes_decrypt ,
 150 .IR setupAESXCBCstate ,
 151 and
 152 .IR aesXCBCmac
 153 have not yet been verified by running test vectors through them.
 154 .PP
 155 Because of the way that non-multiple-of-16 buffers are handled,
 156 .I aesCBCdecrypt
 157 must be fed buffers of the same size as the
 158 .I aesCBCencrypt
 159 calls that encrypted it.
 160 .PP
 161 The functions
 162 .I aes_xts_encrypt
 163 an
 164 .I aes_xts_decrypt
 165 abort on a non-multiple-of-16 length as ciphertext stealing
 166 is not implemented.