1 /* 2 * GCM block cipher, ESP DMA hardware accelerated version 3 * Based on mbedTLS FIPS-197 compliant version. 4 * 5 * SPDX-FileCopyrightText: The Mbed TLS Contributors 6 * 7 * SPDX-License-Identifier: Apache-2.0 8 * 9 * SPDX-FileContributor: 2016-2022 Espressif Systems (Shanghai) CO LTD 10 */ 11 #pragma once 12 13 #include "aes/esp_aes.h" 14 #include "mbedtls/cipher.h" 15 #include "soc/lldesc.h" 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 typedef enum { 22 ESP_AES_GCM_STATE_INIT, 23 ESP_AES_GCM_STATE_START, 24 ESP_AES_GCM_STATE_UPDATE, 25 ESP_AES_GCM_STATE_FINISH 26 } esp_aes_gcm_state; 27 /** 28 * \brief The GCM context structure. 29 */ 30 typedef struct { 31 uint8_t H[16]; /*!< Initial hash value */ 32 uint8_t ghash[16]; /*!< GHASH value. */ 33 uint8_t J0[16]; 34 uint64_t HL[16]; /*!< Precalculated HTable low. */ 35 uint64_t HH[16]; /*!< Precalculated HTable high. */ 36 uint8_t ori_j0[16]; /*!< J0 from first iteration. */ 37 const uint8_t *iv; 38 size_t iv_len; /*!< The length of IV. */ 39 uint64_t aad_len; /*!< The total length of the additional data. */ 40 size_t data_len; 41 int mode; 42 const unsigned char *aad; /*!< The additional data. */ 43 esp_aes_context aes_ctx; 44 esp_aes_gcm_state gcm_state; 45 /* Software context needed for soft fallback for non-AES ciphers */ 46 void *ctx_soft; 47 } esp_gcm_context; 48 49 50 /** 51 * \brief This function initializes the specified GCM context 52 * 53 * \param ctx The GCM context to initialize. 54 */ 55 void esp_aes_gcm_init( esp_gcm_context *ctx); 56 57 /** 58 * \brief This function associates a GCM context with a 59 * key. 60 * 61 * \param ctx The GCM context to initialize. 62 * \param cipher The 128-bit block cipher to use. 63 * \param key The encryption key. 64 * \param keybits The key size in bits. Valid options are: 65 * <ul><li>128 bits</li> 66 * <li>192 bits</li> 67 * <li>256 bits</li></ul> 68 * 69 * \return \c 0 on success. 70 * \return A cipher-specific error code on failure. 71 */ 72 int esp_aes_gcm_setkey( esp_gcm_context *ctx, 73 mbedtls_cipher_id_t cipher, 74 const unsigned char *key, 75 unsigned int keybits ); 76 77 /** 78 * \brief This function starts a GCM encryption or decryption 79 * operation. 80 * 81 * \param ctx The GCM context. This must be initialized. 82 * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or 83 * #MBEDTLS_GCM_DECRYPT. 84 * \param iv The initialization vector. This must be a readable buffer of 85 * at least \p iv_len Bytes. 86 * \param iv_len The length of the IV. 87 * 88 * \return \c 0 on success. 89 */ 90 int esp_aes_gcm_starts( esp_gcm_context *ctx, 91 int mode, 92 const unsigned char *iv, 93 size_t iv_len ); 94 95 /** 96 * \brief This function feeds an input buffer as associated data 97 * (authenticated but not encrypted data) in a GCM 98 * encryption or decryption operation. 99 * 100 * Call this function after mbedtls_gcm_starts() to pass 101 * the associated data. If the associated data is empty, 102 * you do not need to call this function. You may not 103 * call this function after calling mbedtls_cipher_update(). 104 * 105 * \param ctx The GCM context. This must have been started with 106 * mbedtls_gcm_starts() and must not have yet received 107 * any input with mbedtls_gcm_update(). 108 * \param aad The buffer holding the additional data, or \c NULL 109 * if \p aad_len is \c 0. 110 * \param aad_len The length of the additional data. If \c 0, 111 * \p add may be \c NULL. 112 * 113 * \return \c 0 on success. 114 */ 115 int esp_aes_gcm_update_ad( esp_gcm_context *ctx, 116 const unsigned char *aad, 117 size_t aad_len ); 118 119 /** 120 * \brief This function feeds an input buffer into an ongoing GCM 121 * encryption or decryption operation. 122 * 123 * You may call this function zero, one or more times 124 * to pass successive parts of the input: the plaintext to 125 * encrypt, or the ciphertext (not including the tag) to 126 * decrypt. After the last part of the input, call 127 * mbedtls_gcm_finish(). 128 * 129 * This function may produce output in one of the following 130 * ways: 131 * - Immediate output: the output length is always equal 132 * to the input length. 133 * - Buffered output: the output consists of a whole number 134 * of 16-byte blocks. If the total input length so far 135 * (not including associated data) is 16 \* *B* + *A* 136 * with *A* < 16 then the total output length is 16 \* *B*. 137 * 138 * In particular: 139 * - It is always correct to call this function with 140 * \p output_size >= \p input_length + 15. 141 * - If \p input_length is a multiple of 16 for all the calls 142 * to this function during an operation, then it is 143 * correct to use \p output_size = \p input_length. 144 * 145 * \note For decryption, the output buffer cannot be the same as 146 * input buffer. If the buffers overlap, the output buffer 147 * must trail at least 8 Bytes behind the input buffer. 148 * 149 * \param ctx The GCM context. This must be initialized. 150 * \param input The buffer holding the input data. If \p input_length 151 * is greater than zero, this must be a readable buffer 152 * of at least \p input_length bytes. 153 * \param input_length The length of the input data in bytes. 154 * \param output The buffer for the output data. If \p output_size 155 * is greater than zero, this must be a writable buffer of 156 * of at least \p output_size bytes. 157 * \param output_size The size of the output buffer in bytes. 158 * See the function description regarding the output size. 159 * \param output_length On success, \p *output_length contains the actual 160 * length of the output written in \p output. 161 * On failure, the content of \p *output_length is 162 * unspecified. 163 * 164 * \return \c 0 on success. 165 * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure: 166 * total input length too long, 167 * unsupported input/output buffer overlap detected, 168 * or \p output_size too small. 169 */ 170 int esp_aes_gcm_update( esp_gcm_context *ctx, 171 const unsigned char *input, size_t input_length, 172 unsigned char *output, size_t output_size, 173 size_t *output_length ); 174 175 /** 176 * \brief This function finishes the GCM operation and generates 177 * the authentication tag. 178 * 179 * It wraps up the GCM stream, and generates the 180 * tag. The tag can have a maximum length of 16 Bytes. 181 * 182 * \param ctx The GCM context. This must be initialized. 183 * \param tag The buffer for holding the tag. This must be a writable 184 * buffer of at least \p tag_len Bytes. 185 * \param tag_len The length of the tag to generate. This must be at least 186 * four. 187 * \param output The buffer for the final output. 188 * If \p output_size is nonzero, this must be a writable 189 * buffer of at least \p output_size bytes. 190 * \param output_size The size of the \p output buffer in bytes. 191 * This must be large enough for the output that 192 * mbedtls_gcm_update() has not produced. In particular: 193 * - If mbedtls_gcm_update() produces immediate output, 194 * or if the total input size is a multiple of \c 16, 195 * then mbedtls_gcm_finish() never produces any output, 196 * so \p output_size can be \c 0. 197 * - \p output_size never needs to be more than \c 15. 198 * \param output_length On success, \p *output_length contains the actual 199 * length of the output written in \p output. 200 * On failure, the content of \p *output_length is 201 * unspecified. 202 * 203 * \return \c 0 on success. 204 * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure: 205 * invalid value of \p tag_len, 206 * or \p output_size too small. 207 */ 208 int esp_aes_gcm_finish( esp_gcm_context *ctx, 209 unsigned char *output, size_t output_size, 210 size_t *output_length, 211 unsigned char *tag, size_t tag_len ); 212 213 /** 214 * \brief This function clears a GCM context 215 * 216 * \param ctx The GCM context to clear. 217 */ 218 void esp_aes_gcm_free( esp_gcm_context *ctx); 219 220 /** 221 * \brief This function performs GCM encryption or decryption of a buffer. 222 * 223 * \note For encryption, the output buffer can be the same as the 224 * input buffer. For decryption, the output buffer cannot be 225 * the same as input buffer. If the buffers overlap, the output 226 * buffer must trail at least 8 Bytes behind the input buffer. 227 * 228 * \param ctx The GCM context to use for encryption or decryption. 229 * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or 230 * #MBEDTLS_GCM_DECRYPT. 231 * \param length The length of the input data. This must be a multiple of 232 * 16 except in the last call before mbedtls_gcm_finish(). 233 * \param iv The initialization vector. 234 * \param iv_len The length of the IV. 235 * \param aad The buffer holding the additional data. 236 * \param aad_len The length of the additional data. 237 * \param input The buffer holding the input data. 238 * \param output The buffer for holding the output data. 239 * \param tag_len The length of the tag to generate. 240 * \param tag The buffer for holding the tag. 241 * 242 * \return \c 0 on success. 243 */ 244 int esp_aes_gcm_crypt_and_tag( esp_gcm_context *ctx, 245 int mode, 246 size_t length, 247 const unsigned char *iv, 248 size_t iv_len, 249 const unsigned char *aad, 250 size_t aad_len, 251 const unsigned char *input, 252 unsigned char *output, 253 size_t tag_len, 254 unsigned char *tag ); 255 256 257 /** 258 * \brief This function performs a GCM authenticated decryption of a 259 * buffer. 260 * 261 * \note For decryption, the output buffer cannot be the same as 262 * input buffer. If the buffers overlap, the output buffer 263 * must trail at least 8 Bytes behind the input buffer. 264 * 265 * \param ctx The GCM context. 266 * \param length The length of the input data. This must be a multiple 267 * of 16 except in the last call before mbedtls_gcm_finish(). 268 * \param iv The initialization vector. 269 * \param iv_len The length of the IV. 270 * \param aad The buffer holding the additional data. 271 * \param aad_len The length of the additional data. 272 * \param tag The buffer holding the tag. 273 * \param tag_len The length of the tag. 274 * \param input The buffer holding the input data. 275 * \param output The buffer for holding the output data. 276 * 277 * \return 0 if successful and authenticated. 278 * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match. 279 */ 280 int esp_aes_gcm_auth_decrypt( esp_gcm_context *ctx, 281 size_t length, 282 const unsigned char *iv, 283 size_t iv_len, 284 const unsigned char *aad, 285 size_t aad_len, 286 const unsigned char *tag, 287 size_t tag_len, 288 const unsigned char *input, 289 unsigned char *output ); 290 291 #ifdef __cplusplus 292 } 293 #endif 294
