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 mbedtls_gcm_context
00057 {
00058     mbedtls_cipher_context_t cipher_ctx ;  /*!< The cipher context used. */
00059     uint64_t HL [16];                      /*!< Precalculated HTable low. */
00060     uint64_t HH [16];                      /*!< Precalculated HTable high. */
00061     uint64_t len ;                         /*!< The total length of the encrypted data. */
00062     uint64_t add_len ;                     /*!< The total length of the additional data. */
00063     unsigned char base_ectr [16];          /*!< The first ECTR for tag. */
00064     unsigned char y [16];                  /*!< The Y working value. */
00065     unsigned char buf [16];                /*!< The buf working value. */
00066     int mode ;                             /*!< The operation to perform:
00067                                                #MBEDTLS_GCM_ENCRYPT or
00068                                                #MBEDTLS_GCM_DECRYPT. */
00069 }
00070 mbedtls_gcm_context;
00071 
00072 #else  /* !MBEDTLS_GCM_ALT */
00073 #include "gcm_alt.h"
00074 #endif /* !MBEDTLS_GCM_ALT */
00075 
00076 /**
00077  * \brief           This function initializes the specified GCM context,
00078  *                  to make references valid, and prepares the context
00079  *                  for mbedtls_gcm_setkey() or mbedtls_gcm_free().
00080  *
00081  *                  The function does not bind the GCM context to a particular
00082  *                  cipher, nor set the key. For this purpose, use
00083  *                  mbedtls_gcm_setkey().
00084  *
00085  * \param ctx       The GCM context to initialize.
00086  */
00087 void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
00088 
00089 /**
00090  * \brief           This function associates a GCM context with a
00091  *                  cipher algorithm and a key.
00092  *
00093  * \param ctx       The GCM context to initialize.
00094  * \param cipher    The 128-bit block cipher to use.
00095  * \param key       The encryption key.
00096  * \param keybits   The key size in bits. Valid options are:
00097  *                  <ul><li>128 bits</li>
00098  *                  <li>192 bits</li>
00099  *                  <li>256 bits</li></ul>
00100  *
00101  * \return          \c 0 on success.
00102  * \return          A cipher-specific error code on failure.
00103  */
00104 int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
00105                         mbedtls_cipher_id_t cipher,
00106                         const unsigned char *key,
00107                         unsigned int keybits );
00108 
00109 /**
00110  * \brief           This function performs GCM encryption or decryption of a buffer.
00111  *
00112  * \note            For encryption, the output buffer can be the same as the
00113  *                  input buffer. For decryption, the output buffer cannot be
00114  *                  the same as input buffer. If the buffers overlap, the output
00115  *                  buffer must trail at least 8 Bytes behind the input buffer.
00116  *
00117  * \warning         When this function performs a decryption, it outputs the
00118  *                  authentication tag and does not verify that the data is
00119  *                  authentic. You should use this function to perform encryption
00120  *                  only. For decryption, use mbedtls_gcm_auth_decrypt() instead.
00121  *
00122  * \param ctx       The GCM context to use for encryption or decryption.
00123  * \param mode      The operation to perform:
00124  *                  - #MBEDTLS_GCM_ENCRYPT to perform authenticated encryption.
00125  *                    The ciphertext is written to \p output and the
00126  *                    authentication tag is written to \p tag.
00127  *                  - #MBEDTLS_GCM_DECRYPT to perform decryption.
00128  *                    The plaintext is written to \p output and the
00129  *                    authentication tag is written to \p tag.
00130  *                    Note that this mode is not recommended, because it does
00131  *                    not verify the authenticity of the data. For this reason,
00132  *                    you should use mbedtls_gcm_auth_decrypt() instead of
00133  *                    calling this function in decryption mode.
00134  * \param length    The length of the input data, which is equal to the length
00135  *                  of the output data.
00136  * \param iv        The initialization vector.
00137  * \param iv_len    The length of the IV.
00138  * \param add       The buffer holding the additional data.
00139  * \param add_len   The length of the additional data.
00140  * \param input     The buffer holding the input data. Its size is \b length.
00141  * \param output    The buffer for holding the output data. It must have room
00142  *                  for \b length bytes.
00143  * \param tag_len   The length of the tag to generate.
00144  * \param tag       The buffer for holding the tag.
00145  *
00146  * \return          \c 0 if the encryption or decryption was performed
00147  *                  successfully. Note that in #MBEDTLS_GCM_DECRYPT mode,
00148  *                  this does not indicate that the data is authentic.
00149  * \return          #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid.
00150  * \return          #MBEDTLS_ERR_GCM_HW_ACCEL_FAILED or a cipher-specific
00151  *                  error code if the encryption or decryption failed.
00152  */
00153 int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
00154                        int mode,
00155                        size_t length,
00156                        const unsigned char *iv,
00157                        size_t iv_len,
00158                        const unsigned char *add,
00159                        size_t add_len,
00160                        const unsigned char *input,
00161                        unsigned char *output,
00162                        size_t tag_len,
00163                        unsigned char *tag );
00164 
00165 /**
00166  * \brief           This function performs a GCM authenticated decryption of a
00167  *                  buffer.
00168  *
00169  * \note            For decryption, the output buffer cannot be the same as
00170  *                  input buffer. If the buffers overlap, the output buffer
00171  *                  must trail at least 8 Bytes behind the input buffer.
00172  *
00173  * \param ctx       The GCM context.
00174  * \param length    The length of the ciphertext to decrypt, which is also
00175  *                  the length of the decrypted plaintext.
00176  * \param iv        The initialization vector.
00177  * \param iv_len    The length of the IV.
00178  * \param add       The buffer holding the additional data.
00179  * \param add_len   The length of the additional data.
00180  * \param tag       The buffer holding the tag to verify.
00181  * \param tag_len   The length of the tag to verify.
00182  * \param input     The buffer holding the ciphertext. Its size is \b length.
00183  * \param output    The buffer for holding the decrypted plaintext. It must
00184  *                  have room for \b length bytes.
00185  *
00186  * \return          \c 0 if successful and authenticated.
00187  * \return          #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
00188  * \return          #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid.
00189  * \return          #MBEDTLS_ERR_GCM_HW_ACCEL_FAILED or a cipher-specific
00190  *                  error code if the decryption failed.
00191  */
00192 int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
00193                       size_t length,
00194                       const unsigned char *iv,
00195                       size_t iv_len,
00196                       const unsigned char *add,
00197                       size_t add_len,
00198                       const unsigned char *tag,
00199                       size_t tag_len,
00200                       const unsigned char *input,
00201                       unsigned char *output );
00202 
00203 /**
00204  * \brief           This function starts a GCM encryption or decryption
00205  *                  operation.
00206  *
00207  * \param ctx       The GCM context.
00208  * \param mode      The operation to perform: #MBEDTLS_GCM_ENCRYPT or
00209  *                  #MBEDTLS_GCM_DECRYPT.
00210  * \param iv        The initialization vector.
00211  * \param iv_len    The length of the IV.
00212  * \param add       The buffer holding the additional data, or NULL
00213  *                  if \p add_len is 0.
00214  * \param add_len   The length of the additional data. If 0,
00215  *                  \p add is NULL.
00216  *
00217  * \return          \c 0 on success.
00218  */
00219 int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
00220                 int mode,
00221                 const unsigned char *iv,
00222                 size_t iv_len,
00223                 const unsigned char *add,
00224                 size_t add_len );
00225 
00226 /**
00227  * \brief           This function feeds an input buffer into an ongoing GCM
00228  *                  encryption or decryption operation.
00229  *
00230  *    `             The function expects input to be a multiple of 16
00231  *                  Bytes. Only the last call before calling
00232  *                  mbedtls_gcm_finish() can be less than 16 Bytes.
00233  *
00234  * \note            For decryption, the output buffer cannot be the same as
00235  *                  input buffer. If the buffers overlap, the output buffer
00236  *                  must trail at least 8 Bytes behind the input buffer.
00237  *
00238  * \param ctx       The GCM context.
00239  * \param length    The length of the input data. This must be a multiple of
00240  *                  16 except in the last call before mbedtls_gcm_finish().
00241  * \param input     The buffer holding the input data.
00242  * \param output    The buffer for holding the output data.
00243  *
00244  * \return         \c 0 on success.
00245  * \return         #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
00246  */
00247 int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
00248                 size_t length,
00249                 const unsigned char *input,
00250                 unsigned char *output );
00251 
00252 /**
00253  * \brief           This function finishes the GCM operation and generates
00254  *                  the authentication tag.
00255  *
00256  *                  It wraps up the GCM stream, and generates the
00257  *                  tag. The tag can have a maximum length of 16 Bytes.
00258  *
00259  * \param ctx       The GCM context.
00260  * \param tag       The buffer for holding the tag.
00261  * \param tag_len   The length of the tag to generate. Must be at least four.
00262  *
00263  * \return          \c 0 on success.
00264  * \return          #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
00265  */
00266 int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
00267                 unsigned char *tag,
00268                 size_t tag_len );
00269 
00270 /**
00271  * \brief           This function clears a GCM context and the underlying
00272  *                  cipher sub-context.
00273  *
00274  * \param ctx       The GCM context to clear.
00275  */
00276 void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
00277 
00278 /**
00279  * \brief          The GCM checkup routine.
00280  *
00281  * \return         \c 0 on success.
00282  * \return         \c 1 on failure.
00283  */
00284 int mbedtls_gcm_self_test( int verbose );
00285 
00286 #ifdef __cplusplus
00287 }
00288 #endif
00289 
00290 
00291 #endif /* gcm.h */