/** * \file gcm.h * * \brief Galois/Counter mode for 128-bit block ciphers * * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); you may * not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * * This file is part of mbed TLS (https://tls.mbed.org) */ #ifndef MBEDTLS_GCM_H #define MBEDTLS_GCM_H #include "cipher.h" #include #define MBEDTLS_GCM_ENCRYPT 1 #define MBEDTLS_GCM_DECRYPT 0 #define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012 /**< Authenticated decryption failed. */ #define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014 /**< Bad input parameters to function. */ #ifdef __cplusplus extern "C" { #endif /** * \brief GCM context structure */ typedef struct { mbedtls_cipher_context_t cipher_ctx;/*!< cipher context used */ uint64_t HL[16]; /*!< Precalculated HTable */ uint64_t HH[16]; /*!< Precalculated HTable */ uint64_t len; /*!< Total data length */ uint64_t add_len; /*!< Total add length */ unsigned char base_ectr[16];/*!< First ECTR for tag */ unsigned char y[16]; /*!< Y working value */ unsigned char buf[16]; /*!< buf working value */ int mode; /*!< Encrypt or Decrypt */ } mbedtls_gcm_context; /** * \brief Initialize GCM context (just makes references valid) * Makes the context ready for mbedtls_gcm_setkey() or * mbedtls_gcm_free(). * * \param ctx GCM context to initialize */ void mbedtls_gcm_init( mbedtls_gcm_context *ctx ); /** * \brief GCM initialization (encryption) * * \param ctx GCM context to be initialized * \param cipher cipher to use (a 128-bit block cipher) * \param key encryption key * \param keybits must be 128, 192 or 256 * * \return 0 if successful, or a cipher specific error code */ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx, mbedtls_cipher_id_t cipher, const unsigned char *key, unsigned int keybits ); /** * \brief GCM buffer encryption/decryption using a block cipher * * \note On encryption, the output buffer can be the same as the input buffer. * On decryption, the output buffer cannot be the same as input buffer. * If buffers overlap, the output buffer must trail at least 8 bytes * behind the input buffer. * * \param ctx GCM context * \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT * \param length length of the input data * \param iv initialization vector * \param iv_len length of IV * \param add additional data * \param add_len length of additional data * \param input buffer holding the input data * \param output buffer for holding the output data * \param tag_len length of the tag to generate * \param tag buffer for holding the tag * * \return 0 if successful */ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, int mode, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, size_t tag_len, unsigned char *tag ); /** * \brief GCM buffer authenticated decryption using a block cipher * * \note On decryption, the output buffer cannot be the same as input buffer. * If buffers overlap, the output buffer must trail at least 8 bytes * behind the input buffer. * * \param ctx GCM context * \param length length of the input data * \param iv initialization vector * \param iv_len length of IV * \param add additional data * \param add_len length of additional data * \param tag buffer holding the tag * \param tag_len length of the tag * \param input buffer holding the input data * \param output buffer for holding the output data * * \return 0 if successful and authenticated, * MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match */ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *tag, size_t tag_len, const unsigned char *input, unsigned char *output ); /** * \brief Generic GCM stream start function * * \param ctx GCM context * \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT * \param iv initialization vector * \param iv_len length of IV * \param add additional data (or NULL if length is 0) * \param add_len length of additional data * * \return 0 if successful */ int mbedtls_gcm_starts( mbedtls_gcm_context *ctx, int mode, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len ); /** * \brief Generic GCM update function. Encrypts/decrypts using the * given GCM context. Expects input to be a multiple of 16 * bytes! Only the last call before mbedtls_gcm_finish() can be less * than 16 bytes! * * \note On decryption, the output buffer cannot be the same as input buffer. * If buffers overlap, the output buffer must trail at least 8 bytes * behind the input buffer. * * \param ctx GCM context * \param length length of the input data * \param input buffer holding the input data * \param output buffer for holding the output data * * \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT */ int mbedtls_gcm_update( mbedtls_gcm_context *ctx, size_t length, const unsigned char *input, unsigned char *output ); /** * \brief Generic GCM finalisation function. Wraps up the GCM stream * and generates the tag. The tag can have a maximum length of * 16 bytes. * * \param ctx GCM context * \param tag buffer for holding the tag (may be NULL if tag_len is 0) * \param tag_len length of the tag to generate * * \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT */ int mbedtls_gcm_finish( mbedtls_gcm_context *ctx, unsigned char *tag, size_t tag_len ); /** * \brief Free a GCM context and underlying cipher sub-context * * \param ctx GCM context to free */ void mbedtls_gcm_free( mbedtls_gcm_context *ctx ); /** * \brief Checkup routine * * \return 0 if successful, or 1 if the test failed */ int mbedtls_gcm_self_test( int verbose ); #ifdef __cplusplus } #endif #endif /* gcm.h */