gcm.h

00001 /**
00002  * \file gcm.h
00003  *
00004  * \brief This file contains GCM definitions and functions.
00005  *
00006  * The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined
00007  * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
00008  * (GCM), Natl. Inst. Stand. Technol.</em>
00009  *
00010  * For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
00011  * Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
00012  *
00013  */
00014 /*
00015  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00016  *  SPDX-License-Identifier: Apache-2.0
00017  *
00018  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00019  *  not use this file except in compliance with the License.
00020  *  You may obtain a copy of the License at
00021  *
00022  *  http://www.apache.org/licenses/LICENSE-2.0
00023  *
00024  *  Unless required by applicable law or agreed to in writing, software
00025  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00026  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00027  *  See the License for the specific language governing permissions and
00028  *  limitations under the License.
00029  *
00030  *  This file is part of Mbed TLS (https://tls.mbed.org)
00031  */
00032 
00033 #ifndef MBEDTLS_GCM_H
00034 #define MBEDTLS_GCM_H
00035 
00036 #include "cipher.h"
00037 
00038 #include <stdint.h>
00039 
00040 #define MBEDTLS_GCM_ENCRYPT     1
00041 #define MBEDTLS_GCM_DECRYPT     0
00042 
00043 #define MBEDTLS_ERR_GCM_AUTH_FAILED                       -0x0012  /**< Authenticated decryption failed. */
00044 #define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED                   -0x0013  /**< GCM hardware accelerator failed. */
00045 #define MBEDTLS_ERR_GCM_BAD_INPUT                         -0x0014  /**< Bad input parameters to function. */
00046 
00047 #ifdef __cplusplus
00048 extern "C" {
00049 #endif
00050 
00051 #if !defined(MBEDTLS_GCM_ALT)
00052 
00053 /**
00054  * \brief          The GCM context structure.
00055  */
00056 typedef struct {
00057     mbedtls_cipher_context_t cipher_ctx ;  /*!< The cipher context used. */
00058     uint64_t HL[16];                      /*!< Precalculated HTable low. */
00059     uint64_t HH[16];                      /*!< Precalculated HTable high. */
00060     uint64_t len ;                         /*!< The total length of the encrypted data. */
00061     uint64_t add_len ;                     /*!< The total length of the additional data. */
00062     unsigned char base_ectr[16];          /*!< The first ECTR for tag. */
00063     unsigned char y[16];                  /*!< The Y working value. */
00064     unsigned char buf[16];                /*!< The buf working value. */
00065     int mode;                             /*!< The operation to perform:
00066                                                #MBEDTLS_GCM_ENCRYPT or
00067                                                #MBEDTLS_GCM_DECRYPT. */
00068 }
00069 mbedtls_gcm_context;
00070 
00071 #else  /* !MBEDTLS_GCM_ALT */
00072 #include "gcm_alt.h"
00073 #endif /* !MBEDTLS_GCM_ALT */
00074 
00075 /**
00076  * \brief           This function initializes the specified GCM context,
00077  *                  to make references valid, and prepares the context
00078  *                  for mbedtls_gcm_setkey() or mbedtls_gcm_free().
00079  *
00080  *                  The function does not bind the GCM context to a particular
00081  *                  cipher, nor set the key. For this purpose, use
00082  *                  mbedtls_gcm_setkey().
00083  *
00084  * \param ctx       The GCM context to initialize.
00085  */
00086 void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
00087 
00088 /**
00089  * \brief           This function associates a GCM context with a
00090  *                  cipher algorithm and a key.
00091  *
00092  * \param ctx       The GCM context to initialize.
00093  * \param cipher    The 128-bit block cipher to use.
00094  * \param key       The encryption key.
00095  * \param keybits   The key size in bits. Valid options are:
00096  *                  <ul><li>128 bits</li>
00097  *                  <li>192 bits</li>
00098  *                  <li>256 bits</li></ul>
00099  *
00100  * \return          \c 0 on success.
00101  * \return          A cipher-specific error code on failure.
00102  */
00103 int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
00104                         mbedtls_cipher_id_t cipher,
00105                         const unsigned char *key,
00106                         unsigned int keybits );
00107 
00108 /**
00109  * \brief           This function performs GCM encryption or decryption of a buffer.
00110  *
00111  * \note            For encryption, the output buffer can be the same as the
00112  *                  input buffer. For decryption, the output buffer cannot be
00113  *                  the same as input buffer. If the buffers overlap, the output
00114  *                  buffer must trail at least 8 Bytes behind the input buffer.
00115  *
00116  * \param ctx       The GCM context to use for encryption or decryption.
00117  * \param mode      The operation to perform: #MBEDTLS_GCM_ENCRYPT or
00118  *                  #MBEDTLS_GCM_DECRYPT.
00119  * \param length    The length of the input data. This must be a multiple of
00120  *                  16 except in the last call before mbedtls_gcm_finish().
00121  * \param iv        The initialization vector.
00122  * \param iv_len    The length of the IV.
00123  * \param add       The buffer holding the additional data.
00124  * \param add_len   The length of the additional data.
00125  * \param input     The buffer holding the input data.
00126  * \param output    The buffer for holding the output data.
00127  * \param tag_len   The length of the tag to generate.
00128  * \param tag       The buffer for holding the tag.
00129  *
00130  * \return         \c 0 on success.
00131  */
00132 int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
00133                        int mode,
00134                        size_t length,
00135                        const unsigned char *iv,
00136                        size_t iv_len,
00137                        const unsigned char *add,
00138                        size_t add_len,
00139                        const unsigned char *input,
00140                        unsigned char *output,
00141                        size_t tag_len,
00142                        unsigned char *tag );
00143 
00144 /**
00145  * \brief           This function performs a GCM authenticated decryption of a
00146  *                  buffer.
00147  *
00148  * \note            For decryption, the output buffer cannot be the same as
00149  *                  input buffer. If the buffers overlap, the output buffer
00150  *                  must trail at least 8 Bytes behind the input buffer.
00151  *
00152  * \param ctx       The GCM context.
00153  * \param length    The length of the input data. This must be a multiple
00154  *                  of 16 except in the last call before mbedtls_gcm_finish().
00155  * \param iv        The initialization vector.
00156  * \param iv_len    The length of the IV.
00157  * \param add       The buffer holding the additional data.
00158  * \param add_len   The length of the additional data.
00159  * \param tag       The buffer holding the tag.
00160  * \param tag_len   The length of the tag.
00161  * \param input     The buffer holding the input data.
00162  * \param output    The buffer for holding the output data.
00163  *
00164  * \return         0 if successful and authenticated.
00165  * \return         #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
00166  */
00167 int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
00168                       size_t length,
00169                       const unsigned char *iv,
00170                       size_t iv_len,
00171                       const unsigned char *add,
00172                       size_t add_len,
00173                       const unsigned char *tag,
00174                       size_t tag_len,
00175                       const unsigned char *input,
00176                       unsigned char *output );
00177 
00178 /**
00179  * \brief           This function starts a GCM encryption or decryption
00180  *                  operation.
00181  *
00182  * \param ctx       The GCM context.
00183  * \param mode      The operation to perform: #MBEDTLS_GCM_ENCRYPT or
00184  *                  #MBEDTLS_GCM_DECRYPT.
00185  * \param iv        The initialization vector.
00186  * \param iv_len    The length of the IV.
00187  * \param add       The buffer holding the additional data, or NULL
00188  *                  if \p add_len is 0.
00189  * \param add_len   The length of the additional data. If 0,
00190  *                  \p add is NULL.
00191  *
00192  * \return          \c 0 on success.
00193  */
00194 int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
00195                 int mode,
00196                 const unsigned char *iv,
00197                 size_t iv_len,
00198                 const unsigned char *add,
00199                 size_t add_len );
00200 
00201 /**
00202  * \brief           This function feeds an input buffer into an ongoing GCM
00203  *                  encryption or decryption operation.
00204  *
00205  *    `             The function expects input to be a multiple of 16
00206  *                  Bytes. Only the last call before calling
00207  *                  mbedtls_gcm_finish() can be less than 16 Bytes.
00208  *
00209  * \note            For decryption, the output buffer cannot be the same as
00210  *                  input buffer. If the buffers overlap, the output buffer
00211  *                  must trail at least 8 Bytes behind the input buffer.
00212  *
00213  * \param ctx       The GCM context.
00214  * \param length    The length of the input data. This must be a multiple of
00215  *                  16 except in the last call before mbedtls_gcm_finish().
00216  * \param input     The buffer holding the input data.
00217  * \param output    The buffer for holding the output data.
00218  *
00219  * \return         \c 0 on success.
00220  * \return         #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
00221  */
00222 int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
00223                 size_t length,
00224                 const unsigned char *input,
00225                 unsigned char *output );
00226 
00227 /**
00228  * \brief           This function finishes the GCM operation and generates
00229  *                  the authentication tag.
00230  *
00231  *                  It wraps up the GCM stream, and generates the
00232  *                  tag. The tag can have a maximum length of 16 Bytes.
00233  *
00234  * \param ctx       The GCM context.
00235  * \param tag       The buffer for holding the tag.
00236  * \param tag_len   The length of the tag to generate. Must be at least four.
00237  *
00238  * \return          \c 0 on success.
00239  * \return          #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
00240  */
00241 int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
00242                 unsigned char *tag,
00243                 size_t tag_len );
00244 
00245 /**
00246  * \brief           This function clears a GCM context and the underlying
00247  *                  cipher sub-context.
00248  *
00249  * \param ctx       The GCM context to clear.
00250  */
00251 void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
00252 
00253 /**
00254  * \brief          The GCM checkup routine.
00255  *
00256  * \return         \c 0 on success.
00257  * \return         \c 1 on failure.
00258  */
00259 int mbedtls_gcm_self_test( int verbose );
00260 
00261 #ifdef __cplusplus
00262 }
00263 #endif
00264 
00265 
00266 #endif /* gcm.h */