gcm.h

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