1 /** 2 * \file gcm.h 3 * 4 * \brief This file contains GCM definitions and functions. 5 * 6 * The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined 7 * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation 8 * (GCM), Natl. Inst. Stand. Technol.</em> 9 * 10 * For more information on GCM, see <em>NIST SP 800-38D: Recommendation for 11 * Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>. 12 * 13 */ 14 /* 15 * Copyright The Mbed TLS Contributors 16 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 17 */ 18 19 #ifndef MBEDTLS_GCM_H 20 #define MBEDTLS_GCM_H 21 #include "mbedtls/private_access.h" 22 23 #include "mbedtls/build_info.h" 24 25 #include "mbedtls/cipher.h" 26 27 #if defined(MBEDTLS_BLOCK_CIPHER_C) 28 #include "mbedtls/block_cipher.h" 29 #endif 30 31 #include <stdint.h> 32 33 #define MBEDTLS_GCM_ENCRYPT 1 34 #define MBEDTLS_GCM_DECRYPT 0 35 36 /** Authenticated decryption failed. */ 37 #define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012 38 /** Bad input parameters to function. */ 39 #define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014 40 /** An output buffer is too small. */ 41 #define MBEDTLS_ERR_GCM_BUFFER_TOO_SMALL -0x0016 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 #if !defined(MBEDTLS_GCM_ALT) 48 49 #if defined(MBEDTLS_GCM_LARGE_TABLE) 50 #define MBEDTLS_GCM_HTABLE_SIZE 256 51 #else 52 #define MBEDTLS_GCM_HTABLE_SIZE 16 53 #endif 54 55 /** 56 * \brief The GCM context structure. 57 */ 58 typedef struct mbedtls_gcm_context { 59 #if defined(MBEDTLS_BLOCK_CIPHER_C) 60 mbedtls_block_cipher_context_t MBEDTLS_PRIVATE(block_cipher_ctx); /*!< The cipher context used. */ 61 #else 62 mbedtls_cipher_context_t MBEDTLS_PRIVATE(cipher_ctx); /*!< The cipher context used. */ 63 #endif 64 uint64_t MBEDTLS_PRIVATE(H)[MBEDTLS_GCM_HTABLE_SIZE][2]; /*!< Precalculated HTable. */ 65 uint64_t MBEDTLS_PRIVATE(len); /*!< The total length of the encrypted data. */ 66 uint64_t MBEDTLS_PRIVATE(add_len); /*!< The total length of the additional data. */ 67 unsigned char MBEDTLS_PRIVATE(base_ectr)[16]; /*!< The first ECTR for tag. */ 68 unsigned char MBEDTLS_PRIVATE(y)[16]; /*!< The Y working value. */ 69 unsigned char MBEDTLS_PRIVATE(buf)[16]; /*!< The buf working value. */ 70 unsigned char MBEDTLS_PRIVATE(mode); /*!< The operation to perform: 71 #MBEDTLS_GCM_ENCRYPT or 72 #MBEDTLS_GCM_DECRYPT. */ 73 unsigned char MBEDTLS_PRIVATE(acceleration); /*!< The acceleration to use. */ 74 } 75 mbedtls_gcm_context; 76 77 #else /* !MBEDTLS_GCM_ALT */ 78 #include "gcm_alt.h" 79 #endif /* !MBEDTLS_GCM_ALT */ 80 81 /** 82 * \brief This function initializes the specified GCM context, 83 * to make references valid, and prepares the context 84 * for mbedtls_gcm_setkey() or mbedtls_gcm_free(). 85 * 86 * The function does not bind the GCM context to a particular 87 * cipher, nor set the key. For this purpose, use 88 * mbedtls_gcm_setkey(). 89 * 90 * \param ctx The GCM context to initialize. This must not be \c NULL. 91 */ 92 void mbedtls_gcm_init(mbedtls_gcm_context *ctx); 93 94 /** 95 * \brief This function associates a GCM context with a 96 * cipher algorithm and a key. 97 * 98 * \param ctx The GCM context. This must be initialized. 99 * \param cipher The 128-bit block cipher to use. 100 * \param key The encryption key. This must be a readable buffer of at 101 * least \p keybits bits. 102 * \param keybits The key size in bits. Valid options are: 103 * <ul><li>128 bits</li> 104 * <li>192 bits</li> 105 * <li>256 bits</li></ul> 106 * 107 * \return \c 0 on success. 108 * \return A cipher-specific error code on failure. 109 */ 110 int mbedtls_gcm_setkey(mbedtls_gcm_context *ctx, 111 mbedtls_cipher_id_t cipher, 112 const unsigned char *key, 113 unsigned int keybits); 114 115 /** 116 * \brief This function performs GCM encryption or decryption of a buffer. 117 * 118 * \note For encryption, the output buffer can be the same as the 119 * input buffer. For decryption, the output buffer cannot be 120 * the same as input buffer. If the buffers overlap, the output 121 * buffer must trail at least 8 Bytes behind the input buffer. 122 * 123 * \warning When this function performs a decryption, it outputs the 124 * authentication tag and does not verify that the data is 125 * authentic. You should use this function to perform encryption 126 * only. For decryption, use mbedtls_gcm_auth_decrypt() instead. 127 * 128 * \param ctx The GCM context to use for encryption or decryption. This 129 * must be initialized. 130 * \param mode The operation to perform: 131 * - #MBEDTLS_GCM_ENCRYPT to perform authenticated encryption. 132 * The ciphertext is written to \p output and the 133 * authentication tag is written to \p tag. 134 * - #MBEDTLS_GCM_DECRYPT to perform decryption. 135 * The plaintext is written to \p output and the 136 * authentication tag is written to \p tag. 137 * Note that this mode is not recommended, because it does 138 * not verify the authenticity of the data. For this reason, 139 * you should use mbedtls_gcm_auth_decrypt() instead of 140 * calling this function in decryption mode. 141 * \param length The length of the input data, which is equal to the length 142 * of the output data. 143 * \param iv The initialization vector. This must be a readable buffer of 144 * at least \p iv_len Bytes. 145 * \param iv_len The length of the IV. 146 * \param add The buffer holding the additional data. This must be of at 147 * least that size in Bytes. 148 * \param add_len The length of the additional data. 149 * \param input The buffer holding the input data. If \p length is greater 150 * than zero, this must be a readable buffer of at least that 151 * size in Bytes. 152 * \param output The buffer for holding the output data. If \p length is greater 153 * than zero, this must be a writable buffer of at least that 154 * size in Bytes. 155 * \param tag_len The length of the tag to generate. 156 * \param tag The buffer for holding the tag. This must be a writable 157 * buffer of at least \p tag_len Bytes. 158 * 159 * \return \c 0 if the encryption or decryption was performed 160 * successfully. Note that in #MBEDTLS_GCM_DECRYPT mode, 161 * this does not indicate that the data is authentic. 162 * \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are 163 * not valid or a cipher-specific error code if the encryption 164 * or decryption failed. 165 */ 166 int mbedtls_gcm_crypt_and_tag(mbedtls_gcm_context *ctx, 167 int mode, 168 size_t length, 169 const unsigned char *iv, 170 size_t iv_len, 171 const unsigned char *add, 172 size_t add_len, 173 const unsigned char *input, 174 unsigned char *output, 175 size_t tag_len, 176 unsigned char *tag); 177 178 /** 179 * \brief This function performs a GCM authenticated decryption of a 180 * buffer. 181 * 182 * \note For decryption, the output buffer cannot be the same as 183 * input buffer. If the buffers overlap, the output buffer 184 * must trail at least 8 Bytes behind the input buffer. 185 * 186 * \param ctx The GCM context. This must be initialized. 187 * \param length The length of the ciphertext to decrypt, which is also 188 * the length of the decrypted plaintext. 189 * \param iv The initialization vector. This must be a readable buffer 190 * of at least \p iv_len Bytes. 191 * \param iv_len The length of the IV. 192 * \param add The buffer holding the additional data. This must be of at 193 * least that size in Bytes. 194 * \param add_len The length of the additional data. 195 * \param tag The buffer holding the tag to verify. This must be a 196 * readable buffer of at least \p tag_len Bytes. 197 * \param tag_len The length of the tag to verify. 198 * \param input The buffer holding the ciphertext. If \p length is greater 199 * than zero, this must be a readable buffer of at least that 200 * size. 201 * \param output The buffer for holding the decrypted plaintext. If \p length 202 * is greater than zero, this must be a writable buffer of at 203 * least that size. 204 * 205 * \return \c 0 if successful and authenticated. 206 * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match. 207 * \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are 208 * not valid or a cipher-specific error code if the decryption 209 * failed. 210 */ 211 int mbedtls_gcm_auth_decrypt(mbedtls_gcm_context *ctx, 212 size_t length, 213 const unsigned char *iv, 214 size_t iv_len, 215 const unsigned char *add, 216 size_t add_len, 217 const unsigned char *tag, 218 size_t tag_len, 219 const unsigned char *input, 220 unsigned char *output); 221 222 /** 223 * \brief This function starts a GCM encryption or decryption 224 * operation. 225 * 226 * \param ctx The GCM context. This must be initialized. 227 * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or 228 * #MBEDTLS_GCM_DECRYPT. 229 * \param iv The initialization vector. This must be a readable buffer of 230 * at least \p iv_len Bytes. 231 * \param iv_len The length of the IV. 232 * 233 * \return \c 0 on success. 234 */ 235 int mbedtls_gcm_starts(mbedtls_gcm_context *ctx, 236 int mode, 237 const unsigned char *iv, 238 size_t iv_len); 239 240 /** 241 * \brief This function feeds an input buffer as associated data 242 * (authenticated but not encrypted data) in a GCM 243 * encryption or decryption operation. 244 * 245 * Call this function after mbedtls_gcm_starts() to pass 246 * the associated data. If the associated data is empty, 247 * you do not need to call this function. You may not 248 * call this function after calling mbedtls_cipher_update(). 249 * 250 * \param ctx The GCM context. This must have been started with 251 * mbedtls_gcm_starts() and must not have yet received 252 * any input with mbedtls_gcm_update(). 253 * \param add The buffer holding the additional data, or \c NULL 254 * if \p add_len is \c 0. 255 * \param add_len The length of the additional data. If \c 0, 256 * \p add may be \c NULL. 257 * 258 * \return \c 0 on success. 259 */ 260 int mbedtls_gcm_update_ad(mbedtls_gcm_context *ctx, 261 const unsigned char *add, 262 size_t add_len); 263 264 /** 265 * \brief This function feeds an input buffer into an ongoing GCM 266 * encryption or decryption operation. 267 * 268 * You may call this function zero, one or more times 269 * to pass successive parts of the input: the plaintext to 270 * encrypt, or the ciphertext (not including the tag) to 271 * decrypt. After the last part of the input, call 272 * mbedtls_gcm_finish(). 273 * 274 * This function may produce output in one of the following 275 * ways: 276 * - Immediate output: the output length is always equal 277 * to the input length. 278 * - Buffered output: the output consists of a whole number 279 * of 16-byte blocks. If the total input length so far 280 * (not including associated data) is 16 \* *B* + *A* 281 * with *A* < 16 then the total output length is 16 \* *B*. 282 * 283 * In particular: 284 * - It is always correct to call this function with 285 * \p output_size >= \p input_length + 15. 286 * - If \p input_length is a multiple of 16 for all the calls 287 * to this function during an operation, then it is 288 * correct to use \p output_size = \p input_length. 289 * 290 * \note For decryption, the output buffer cannot be the same as 291 * input buffer. If the buffers overlap, the output buffer 292 * must trail at least 8 Bytes behind the input buffer. 293 * 294 * \param ctx The GCM context. This must be initialized. 295 * \param input The buffer holding the input data. If \p input_length 296 * is greater than zero, this must be a readable buffer 297 * of at least \p input_length bytes. 298 * \param input_length The length of the input data in bytes. 299 * \param output The buffer for the output data. If \p output_size 300 * is greater than zero, this must be a writable buffer of 301 * of at least \p output_size bytes. 302 * \param output_size The size of the output buffer in bytes. 303 * See the function description regarding the output size. 304 * \param output_length On success, \p *output_length contains the actual 305 * length of the output written in \p output. 306 * On failure, the content of \p *output_length is 307 * unspecified. 308 * 309 * \return \c 0 on success. 310 * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure: 311 * total input length too long, 312 * unsupported input/output buffer overlap detected, 313 * or \p output_size too small. 314 */ 315 int mbedtls_gcm_update(mbedtls_gcm_context *ctx, 316 const unsigned char *input, size_t input_length, 317 unsigned char *output, size_t output_size, 318 size_t *output_length); 319 320 /** 321 * \brief This function finishes the GCM operation and generates 322 * the authentication tag. 323 * 324 * It wraps up the GCM stream, and generates the 325 * tag. The tag can have a maximum length of 16 Bytes. 326 * 327 * \param ctx The GCM context. This must be initialized. 328 * \param tag The buffer for holding the tag. This must be a writable 329 * buffer of at least \p tag_len Bytes. 330 * \param tag_len The length of the tag to generate. This must be at least 331 * four. 332 * \param output The buffer for the final output. 333 * If \p output_size is nonzero, this must be a writable 334 * buffer of at least \p output_size bytes. 335 * \param output_size The size of the \p output buffer in bytes. 336 * This must be large enough for the output that 337 * mbedtls_gcm_update() has not produced. In particular: 338 * - If mbedtls_gcm_update() produces immediate output, 339 * or if the total input size is a multiple of \c 16, 340 * then mbedtls_gcm_finish() never produces any output, 341 * so \p output_size can be \c 0. 342 * - \p output_size never needs to be more than \c 15. 343 * \param output_length On success, \p *output_length contains the actual 344 * length of the output written in \p output. 345 * On failure, the content of \p *output_length is 346 * unspecified. 347 * 348 * \return \c 0 on success. 349 * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure: 350 * invalid value of \p tag_len, 351 * or \p output_size too small. 352 */ 353 int mbedtls_gcm_finish(mbedtls_gcm_context *ctx, 354 unsigned char *output, size_t output_size, 355 size_t *output_length, 356 unsigned char *tag, size_t tag_len); 357 358 /** 359 * \brief This function clears a GCM context and the underlying 360 * cipher sub-context. 361 * 362 * \param ctx The GCM context to clear. If this is \c NULL, the call has 363 * no effect. Otherwise, this must be initialized. 364 */ 365 void mbedtls_gcm_free(mbedtls_gcm_context *ctx); 366 367 #if defined(MBEDTLS_SELF_TEST) 368 369 /** 370 * \brief The GCM checkup routine. 371 * 372 * \return \c 0 on success. 373 * \return \c 1 on failure. 374 */ 375 int mbedtls_gcm_self_test(int verbose); 376 377 #endif /* MBEDTLS_SELF_TEST */ 378 379 #ifdef __cplusplus 380 } 381 #endif 382 383 384 #endif /* gcm.h */ 385
