1 /** 2 * \file gcm.h 3 * 4 * \brief Galois/Counter mode for 128-bit block ciphers 5 * 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 7 * SPDX-License-Identifier: Apache-2.0 8 * 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may 10 * not use this file except in compliance with the License. 11 * You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, software 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18 * See the License for the specific language governing permissions and 19 * limitations under the License. 20 * 21 * This file is part of mbed TLS (https://tls.mbed.org) 22 */ 23 #ifndef MBEDTLS_GCM_H 24 #define MBEDTLS_GCM_H 25 26 #include "cipher.h" 27 28 #include <stdint.h> 29 30 #define MBEDTLS_GCM_ENCRYPT 1 31 #define MBEDTLS_GCM_DECRYPT 0 32 33 #define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012 /**< Authenticated decryption failed. */ 34 #define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014 /**< Bad input parameters to function. */ 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * \brief GCM context structure 42 */ 43 typedef struct { 44 mbedtls_cipher_context_t cipher_ctx;/*!< cipher context used */ 45 uint64_t HL[16]; /*!< Precalculated HTable */ 46 uint64_t HH[16]; /*!< Precalculated HTable */ 47 uint64_t len; /*!< Total data length */ 48 uint64_t add_len; /*!< Total add length */ 49 unsigned char base_ectr[16];/*!< First ECTR for tag */ 50 unsigned char y[16]; /*!< Y working value */ 51 unsigned char buf[16]; /*!< buf working value */ 52 int mode; /*!< Encrypt or Decrypt */ 53 } 54 mbedtls_gcm_context; 55 56 /** 57 * \brief Initialize GCM context (just makes references valid) 58 * Makes the context ready for mbedtls_gcm_setkey() or 59 * mbedtls_gcm_free(). 60 * 61 * \param ctx GCM context to initialize 62 */ 63 void mbedtls_gcm_init( mbedtls_gcm_context *ctx ); 64 65 /** 66 * \brief GCM initialization (encryption) 67 * 68 * \param ctx GCM context to be initialized 69 * \param cipher cipher to use (a 128-bit block cipher) 70 * \param key encryption key 71 * \param keybits must be 128, 192 or 256 72 * 73 * \return 0 if successful, or a cipher specific error code 74 */ 75 int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx, 76 mbedtls_cipher_id_t cipher, 77 const unsigned char *key, 78 unsigned int keybits ); 79 80 /** 81 * \brief GCM buffer encryption/decryption using a block cipher 82 * 83 * \note On encryption, the output buffer can be the same as the input buffer. 84 * On decryption, the output buffer cannot be the same as input buffer. 85 * If buffers overlap, the output buffer must trail at least 8 bytes 86 * behind the input buffer. 87 * 88 * \param ctx GCM context 89 * \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT 90 * \param length length of the input data 91 * \param iv initialization vector 92 * \param iv_len length of IV 93 * \param add additional data 94 * \param add_len length of additional data 95 * \param input buffer holding the input data 96 * \param output buffer for holding the output data 97 * \param tag_len length of the tag to generate 98 * \param tag buffer for holding the tag 99 * 100 * \return 0 if successful 101 */ 102 int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, 103 int mode, 104 size_t length, 105 const unsigned char *iv, 106 size_t iv_len, 107 const unsigned char *add, 108 size_t add_len, 109 const unsigned char *input, 110 unsigned char *output, 111 size_t tag_len, 112 unsigned char *tag ); 113 114 /** 115 * \brief GCM buffer authenticated decryption using a block cipher 116 * 117 * \note On decryption, the output buffer cannot be the same as input buffer. 118 * If buffers overlap, the output buffer must trail at least 8 bytes 119 * behind the input buffer. 120 * 121 * \param ctx GCM context 122 * \param length length of the input data 123 * \param iv initialization vector 124 * \param iv_len length of IV 125 * \param add additional data 126 * \param add_len length of additional data 127 * \param tag buffer holding the tag 128 * \param tag_len length of the tag 129 * \param input buffer holding the input data 130 * \param output buffer for holding the output data 131 * 132 * \return 0 if successful and authenticated, 133 * MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match 134 */ 135 int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, 136 size_t length, 137 const unsigned char *iv, 138 size_t iv_len, 139 const unsigned char *add, 140 size_t add_len, 141 const unsigned char *tag, 142 size_t tag_len, 143 const unsigned char *input, 144 unsigned char *output ); 145 146 /** 147 * \brief Generic GCM stream start function 148 * 149 * \param ctx GCM context 150 * \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT 151 * \param iv initialization vector 152 * \param iv_len length of IV 153 * \param add additional data (or NULL if length is 0) 154 * \param add_len length of additional data 155 * 156 * \return 0 if successful 157 */ 158 int mbedtls_gcm_starts( mbedtls_gcm_context *ctx, 159 int mode, 160 const unsigned char *iv, 161 size_t iv_len, 162 const unsigned char *add, 163 size_t add_len ); 164 165 /** 166 * \brief Generic GCM update function. Encrypts/decrypts using the 167 * given GCM context. Expects input to be a multiple of 16 168 * bytes! Only the last call before mbedtls_gcm_finish() can be less 169 * than 16 bytes! 170 * 171 * \note On decryption, the output buffer cannot be the same as input buffer. 172 * If buffers overlap, the output buffer must trail at least 8 bytes 173 * behind the input buffer. 174 * 175 * \param ctx GCM context 176 * \param length length of the input data 177 * \param input buffer holding the input data 178 * \param output buffer for holding the output data 179 * 180 * \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT 181 */ 182 int mbedtls_gcm_update( mbedtls_gcm_context *ctx, 183 size_t length, 184 const unsigned char *input, 185 unsigned char *output ); 186 187 /** 188 * \brief Generic GCM finalisation function. Wraps up the GCM stream 189 * and generates the tag. The tag can have a maximum length of 190 * 16 bytes. 191 * 192 * \param ctx GCM context 193 * \param tag buffer for holding the tag 194 * \param tag_len length of the tag to generate (must be at least 4) 195 * 196 * \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT 197 */ 198 int mbedtls_gcm_finish( mbedtls_gcm_context *ctx, 199 unsigned char *tag, 200 size_t tag_len ); 201 202 /** 203 * \brief Free a GCM context and underlying cipher sub-context 204 * 205 * \param ctx GCM context to free 206 */ 207 void mbedtls_gcm_free( mbedtls_gcm_context *ctx ); 208 209 /** 210 * \brief Checkup routine 211 * 212 * \return 0 if successful, or 1 if the test failed 213 */ 214 int mbedtls_gcm_self_test( int verbose ); 215 216 #ifdef __cplusplus 217 } 218 #endif 219 220 #endif /* gcm.h */ 221
