1 /** 2 * \file aes.h 3 * \brief Header defining the API for OQS AES 4 * 5 * SPDX-License-Identifier: MIT 6 */ 7 8 #ifndef OQS_AES_H 9 #define OQS_AES_H 10 11 #include <stdint.h> 12 #include <stdlib.h> 13 14 #define AES256_KEYBYTES 32 15 #define AESCTR_NONCEBYTES 12 16 #define AES_BLOCKBYTES 16 17 18 typedef void *aes256ctx; 19 20 #define aes256_ecb_keyexp(r, key) OQS_AES256_ECB_load_schedule((key), (r), 1); 21 #define aes256_ecb(out, in, nblocks, ctx) OQS_AES256_ECB_enc_sch((in), (nblocks) * AES_BLOCKBYTES, *(ctx), (out)); 22 #define aes256_ctr_keyexp(r, key) OQS_AES256_CTR_load_schedule((key), (r)); 23 #define aes256_ctr(out, outlen, iv, ctx) OQS_AES256_CTR_sch((iv), AESCTR_NONCEBYTES, *(ctx), (out), (outlen)) 24 #define aes256_ctx_release(ctx) OQS_AES256_free_schedule(*(ctx)); 25 26 27 /** copied from common.h **/ 28 29 #define OQS_EXIT_IF_NULLPTR(x) \ 30 do { \ 31 if ( (x) == (void*)0 ) \ 32 exit(EXIT_FAILURE); \ 33 } while (0) 34 35 /** copied from common.c **/ 36 37 /** 38 * Zeros out `len` bytes of memory starting at `ptr`. 39 * 40 * Designed to be protected against optimizing compilers which try to remove 41 * "unnecessary" operations. Should be used for all buffers containing secret 42 * data. 43 * 44 * @param[in] ptr The start of the memory to zero out. 45 * @param[in] len The number of bytes to zero out. 46 */ 47 void OQS_MEM_cleanse(void *ptr, size_t len); 48 49 /** 50 * Zeros out `len` bytes of memory starting at `ptr`, then frees `ptr`. 51 * 52 * Can be called with `ptr = NULL`, in which case no operation is performed. 53 * 54 * Designed to be protected against optimizing compilers which try to remove 55 * "unnecessary" operations. Should be used for all buffers containing secret 56 * data. 57 * 58 * @param[in] ptr The start of the memory to zero out and free. 59 * @param[in] len The number of bytes to zero out. 60 */ 61 void OQS_MEM_secure_free(void *ptr, size_t len); 62 63 64 65 /** 66 * Function to fill a key schedule given an initial key for use in ECB mode. 67 * 68 * @param key Initial Key. 69 * @param schedule Abstract data structure for a key schedule. 70 * @param for_encryption 1 if key schedule is for encryption, 0 if for decryption. 71 */ 72 void OQS_AES128_ECB_load_schedule(const uint8_t *key, void **schedule, int for_encryption); 73 74 /** 75 * Function to free a key schedule. 76 * 77 * @param schedule Schedule generated with OQS_AES128_ECB_load_schedule(). 78 */ 79 void OQS_AES128_free_schedule(void *schedule); 80 81 /** 82 * Function to encrypt blocks of plaintext using ECB mode. 83 * A schedule based on the key is generated and used internally. 84 * 85 * @param plaintext Plaintext to be encrypted. 86 * @param plaintext_len Length on the plaintext in bytes. Must be a multiple of 16. 87 * @param key Key to be used for encryption. 88 * @param ciphertext Pointer to a block of memory which >= in size to the plaintext block. The result will be written here. 89 */ 90 void OQS_AES128_ECB_enc(const uint8_t *plaintext, const size_t plaintext_len, const uint8_t *key, uint8_t *ciphertext); 91 92 /** 93 * Function to decrypt blocks of plaintext using ECB mode. 94 * A schedule based on the key is generated and used internally. 95 * 96 * @param ciphertext Ciphertext to be decrypted. 97 * @param ciphertext_len Length on the ciphertext in bytes. Must be a multiple of 16. 98 * @param key Key to be used for encryption. 99 * @param plaintext Pointer to a block of memory which >= in size to the ciphertext block. The result will be written here. 100 */ 101 void OQS_AES128_ECB_dec(const uint8_t *ciphertext, const size_t ciphertext_len, const uint8_t *key, uint8_t *plaintext); 102 103 /** 104 * Same as OQS_AES128_ECB_enc() except a schedule generated by 105 * OQS_AES128_ECB_load_schedule() is passed rather then a key. This is faster 106 * if the same schedule is used for multiple encryptions since it does 107 * not have to be regenerated from the key. 108 */ 109 void OQS_AES128_ECB_enc_sch(const uint8_t *plaintext, const size_t plaintext_len, const void *schedule, uint8_t *ciphertext); 110 111 /** 112 * Same as OQS_AES128_ECB_dec() except a schedule generated by 113 * OQS_AES128_ECB_load_schedule() is passed rather then a key. This is faster 114 * if the same schedule is used for multiple encryptions since it does 115 * not have to be regenerated from the key. 116 */ 117 void OQS_AES128_ECB_dec_sch(const uint8_t *ciphertext, const size_t ciphertext_len, const void *schedule, uint8_t *plaintext); 118 119 /** 120 * Function to fill a key schedule given an initial key for use in ECB mode. 121 * 122 * @param key Initial Key. 123 * @param schedule Abstract data structure for a key schedule. 124 * @param for_encryption 1 if key schedule is for encryption, 0 if for decryption. 125 */ 126 void OQS_AES256_ECB_load_schedule(const uint8_t *key, void **schedule, int for_encryption); 127 128 /** 129 * Function to fill a key schedule given an initial key for use in CTR mode. 130 * 131 * @param key Initial Key. 132 * @param schedule Abstract data structure for a key schedule. 133 */ 134 void OQS_AES256_CTR_load_schedule(const uint8_t *key, void **schedule); 135 136 /** 137 * Function to free a key schedule. 138 * 139 * @param schedule Schedule generated with OQS_AES256_ECB_load_schedule 140 * or OQS_AES256_CTR_load_schedule. 141 */ 142 void OQS_AES256_free_schedule(void *schedule); 143 144 /** 145 * Function to encrypt blocks of plaintext using ECB mode. 146 * A schedule based on the key is generated and used internally. 147 * 148 * @param plaintext Plaintext to be encrypted. 149 * @param plaintext_len Length on the plaintext in bytes. Must be a multiple of 16. 150 * @param key Key to be used for encryption. 151 * @param ciphertext Pointer to a block of memory which >= in size to the plaintext block. The result will be written here. 152 */ 153 void OQS_AES256_ECB_enc(const uint8_t *plaintext, const size_t plaintext_len, const uint8_t *key, uint8_t *ciphertext); 154 155 /** 156 * Function to decrypt blocks of plaintext using ECB mode. 157 * A schedule based on the key is generated and used internally. 158 * 159 * @param ciphertext Ciphertext to be decrypted. 160 * @param ciphertext_len Length on the ciphertext in bytes. Must be a multiple of 16. 161 * @param key Key to be used for encryption. 162 * @param plaintext Pointer to a block of memory which >= in size to the ciphertext block. The result will be written here. 163 */ 164 void OQS_AES256_ECB_dec(const uint8_t *ciphertext, const size_t ciphertext_len, const uint8_t *key, uint8_t *plaintext); 165 166 /** 167 * Same as OQS_AES256_ECB_enc() except a schedule generated by 168 * OQS_AES256_ECB_load_schedule() is passed rather then a key. This is faster 169 * if the same schedule is used for multiple encryptions since it does 170 * not have to be regenerated from the key. 171 */ 172 void OQS_AES256_ECB_enc_sch(const uint8_t *plaintext, const size_t plaintext_len, const void *schedule, uint8_t *ciphertext); 173 174 /** 175 * Same as OQS_AES256_ECB_dec() except a schedule generated by 176 * OQS_AES256_ECB_load_schedule() is passed rather then a key. This is faster 177 * if the same schedule is used for multiple encryptions since it does 178 * not have to be regenerated from the key. 179 */ 180 void OQS_AES256_ECB_dec_sch(const uint8_t *ciphertext, const size_t ciphertext_len, const void *schedule, uint8_t *plaintext); 181 182 /** 183 * AES counter mode keystream generator. A scheduled generated by 184 * OQS_AES256_CTR_load_schedule() is passed rather then a key. 185 * 186 * Handles a 12- or 16-byte IV. If a 12-byte IV is given, then 4 counter 187 * bytes are initialized to all zeros. 188 * 189 * @param iv 12- or 16-byte initialization vector. 190 * @param iv_len Lengh of IV in bytes. 191 * @param schedule Abstract data structure for a key schedule. 192 * @param out Pointer to a block of memory which is big enough to contain out_len bytes; the result will be written here. 193 * @param out_len Length of output bytes to generate. 194 */ 195 void OQS_AES256_CTR_sch(const uint8_t *iv, size_t iv_len, const void *schedule, uint8_t *out, size_t out_len); 196 197 #if defined(__cplusplus) 198 } // extern "C" 199 #endif 200 201 #endif // OQS_AES_H 202