common/mbedtls/gcm.h

   1 /**
   2  * \file gcm.h
   3  *
   4  * \brief This file contains GCM definitions and functions.
   5  *
   6  * The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined
   7  * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
   8  * (GCM), Natl. Inst. Stand. Technol.</em>
   9  *
  10  * For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
  11  * Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
  12  *
  13  */
  14 /*
  15  *  Copyright The Mbed TLS Contributors
  16  *  SPDX-License-Identifier: Apache-2.0
  17  *
  18  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  19  *  not use this file except in compliance with the License.
  20  *  You may obtain a copy of the License at
  21  *
  22  *  http://www.apache.org/licenses/LICENSE-2.0
  23  *
  24  *  Unless required by applicable law or agreed to in writing, software
  25  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  26  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  27  *  See the License for the specific language governing permissions and
  28  *  limitations under the License.
  29  */
  30
  31 #ifndef MBEDTLS_GCM_H
  32 #define MBEDTLS_GCM_H
  33
  34 #if !defined(MBEDTLS_CONFIG_FILE)
  35 #include "mbedtls/config.h"
  36 #else
  37 #include MBEDTLS_CONFIG_FILE
  38 #endif
  39
  40 #include "mbedtls/cipher.h"
  41
  42 #include <stdint.h>
  43
  44 #define MBEDTLS_GCM_ENCRYPT     1
  45 #define MBEDTLS_GCM_DECRYPT     0
  46
  47 #define MBEDTLS_ERR_GCM_AUTH_FAILED                       -0x0012  /**< Authenticated decryption failed. */
  48
  49 /* MBEDTLS_ERR_GCM_HW_ACCEL_FAILED is deprecated and should not be used. */
  50 #define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED                   -0x0013  /**< GCM hardware accelerator failed. */
  51
  52 #define MBEDTLS_ERR_GCM_BAD_INPUT                         -0x0014  /**< Bad input parameters to function. */
  53
  54 #ifdef __cplusplus
  55 extern "C" {
  56 #endif
  57
  58 #if !defined(MBEDTLS_GCM_ALT)
  59
  60 /**
  61  * \brief          The GCM context structure.
  62  */
  63 typedef struct mbedtls_gcm_context {
  64     mbedtls_cipher_context_t cipher_ctx;  /*!< The cipher context used. */
  65     uint64_t HL[16];                      /*!< Precalculated HTable low. */
  66     uint64_t HH[16];                      /*!< Precalculated HTable high. */
  67     uint64_t len;                         /*!< The total length of the encrypted data. */
  68     uint64_t add_len;                     /*!< The total length of the additional data. */
  69     unsigned char base_ectr[16];          /*!< The first ECTR for tag. */
  70     unsigned char y[16];                  /*!< The Y working value. */
  71     unsigned char buf[16];                /*!< The buf working value. */
  72     int mode;                             /*!< The operation to perform:
  73                                                #MBEDTLS_GCM_ENCRYPT or
  74                                                #MBEDTLS_GCM_DECRYPT. */
  75 }
  76 mbedtls_gcm_context;
  77
  78 #else  /* !MBEDTLS_GCM_ALT */
  79 #include "gcm_alt.h"
  80 #endif /* !MBEDTLS_GCM_ALT */
  81
  82 /**
  83  * \brief           This function initializes the specified GCM context,
  84  *                  to make references valid, and prepares the context
  85  *                  for mbedtls_gcm_setkey() or mbedtls_gcm_free().
  86  *
  87  *                  The function does not bind the GCM context to a particular
  88  *                  cipher, nor set the key. For this purpose, use
  89  *                  mbedtls_gcm_setkey().
  90  *
  91  * \param ctx       The GCM context to initialize. This must not be \c NULL.
  92  */
  93 void mbedtls_gcm_init(mbedtls_gcm_context *ctx);
  94
  95 /**
  96  * \brief           This function associates a GCM context with a
  97  *                  cipher algorithm and a key.
  98  *
  99  * \param ctx       The GCM context. This must be initialized.
 100  * \param cipher    The 128-bit block cipher to use.
 101  * \param key       The encryption key. This must be a readable buffer of at
 102  *                  least \p keybits bits.
 103  * \param keybits   The key size in bits. Valid options are:
 104  *                  <ul><li>128 bits</li>
 105  *                  <li>192 bits</li>
 106  *                  <li>256 bits</li></ul>
 107  *
 108  * \return          \c 0 on success.
 109  * \return          A cipher-specific error code on failure.
 110  */
 111 int mbedtls_gcm_setkey(mbedtls_gcm_context *ctx,
 112                        mbedtls_cipher_id_t cipher,
 113                        const unsigned char *key,
 114                        unsigned int keybits);
 115
 116 /**
 117  * \brief           This function performs GCM encryption or decryption of a buffer.
 118  *
 119  * \note            For encryption, the output buffer can be the same as the
 120  *                  input buffer. For decryption, the output buffer cannot be
 121  *                  the same as input buffer. If the buffers overlap, the output
 122  *                  buffer must trail at least 8 Bytes behind the input buffer.
 123  *
 124  * \warning         When this function performs a decryption, it outputs the
 125  *                  authentication tag and does not verify that the data is
 126  *                  authentic. You should use this function to perform encryption
 127  *                  only. For decryption, use mbedtls_gcm_auth_decrypt() instead.
 128  *
 129  * \param ctx       The GCM context to use for encryption or decryption. This
 130  *                  must be initialized.
 131  * \param mode      The operation to perform:
 132  *                  - #MBEDTLS_GCM_ENCRYPT to perform authenticated encryption.
 133  *                    The ciphertext is written to \p output and the
 134  *                    authentication tag is written to \p tag.
 135  *                  - #MBEDTLS_GCM_DECRYPT to perform decryption.
 136  *                    The plaintext is written to \p output and the
 137  *                    authentication tag is written to \p tag.
 138  *                    Note that this mode is not recommended, because it does
 139  *                    not verify the authenticity of the data. For this reason,
 140  *                    you should use mbedtls_gcm_auth_decrypt() instead of
 141  *                    calling this function in decryption mode.
 142  * \param length    The length of the input data, which is equal to the length
 143  *                  of the output data.
 144  * \param iv        The initialization vector. This must be a readable buffer of
 145  *                  at least \p iv_len Bytes.
 146  * \param iv_len    The length of the IV.
 147  * \param add       The buffer holding the additional data. This must be of at
 148  *                  least that size in Bytes.
 149  * \param add_len   The length of the additional data.
 150  * \param input     The buffer holding the input data. If \p length is greater
 151  *                  than zero, this must be a readable buffer of at least that
 152  *                  size in Bytes.
 153  * \param output    The buffer for holding the output data. If \p length is greater
 154  *                  than zero, this must be a writable buffer of at least that
 155  *                  size in Bytes.
 156  * \param tag_len   The length of the tag to generate.
 157  * \param tag       The buffer for holding the tag. This must be a writable
 158  *                  buffer of at least \p tag_len Bytes.
 159  *
 160  * \return          \c 0 if the encryption or decryption was performed
 161  *                  successfully. Note that in #MBEDTLS_GCM_DECRYPT mode,
 162  *                  this does not indicate that the data is authentic.
 163  * \return          #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are
 164  *                  not valid or a cipher-specific error code if the encryption
 165  *                  or decryption failed.
 166  */
 167 int mbedtls_gcm_crypt_and_tag(mbedtls_gcm_context *ctx,
 168                               int mode,
 169                               size_t length,
 170                               const unsigned char *iv,
 171                               size_t iv_len,
 172                               const unsigned char *add,
 173                               size_t add_len,
 174                               const unsigned char *input,
 175                               unsigned char *output,
 176                               size_t tag_len,
 177                               unsigned char *tag);
 178
 179 /**
 180  * \brief           This function performs a GCM authenticated decryption of a
 181  *                  buffer.
 182  *
 183  * \note            For decryption, the output buffer cannot be the same as
 184  *                  input buffer. If the buffers overlap, the output buffer
 185  *                  must trail at least 8 Bytes behind the input buffer.
 186  *
 187  * \param ctx       The GCM context. This must be initialized.
 188  * \param length    The length of the ciphertext to decrypt, which is also
 189  *                  the length of the decrypted plaintext.
 190  * \param iv        The initialization vector. This must be a readable buffer
 191  *                  of at least \p iv_len Bytes.
 192  * \param iv_len    The length of the IV.
 193  * \param add       The buffer holding the additional data. This must be of at
 194  *                  least that size in Bytes.
 195  * \param add_len   The length of the additional data.
 196  * \param tag       The buffer holding the tag to verify. This must be a
 197  *                  readable buffer of at least \p tag_len Bytes.
 198  * \param tag_len   The length of the tag to verify.
 199  * \param input     The buffer holding the ciphertext. If \p length is greater
 200  *                  than zero, this must be a readable buffer of at least that
 201  *                  size.
 202  * \param output    The buffer for holding the decrypted plaintext. If \p length
 203  *                  is greater than zero, this must be a writable buffer of at
 204  *                  least that size.
 205  *
 206  * \return          \c 0 if successful and authenticated.
 207  * \return          #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
 208  * \return          #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are
 209  *                  not valid or a cipher-specific error code if the decryption
 210  *                  failed.
 211  */
 212 int mbedtls_gcm_auth_decrypt(mbedtls_gcm_context *ctx,
 213                              size_t length,
 214                              const unsigned char *iv,
 215                              size_t iv_len,
 216                              const unsigned char *add,
 217                              size_t add_len,
 218                              const unsigned char *tag,
 219                              size_t tag_len,
 220                              const unsigned char *input,
 221                              unsigned char *output);
 222
 223 /**
 224  * \brief           This function starts a GCM encryption or decryption
 225  *                  operation.
 226  *
 227  * \param ctx       The GCM context. This must be initialized.
 228  * \param mode      The operation to perform: #MBEDTLS_GCM_ENCRYPT or
 229  *                  #MBEDTLS_GCM_DECRYPT.
 230  * \param iv        The initialization vector. This must be a readable buffer of
 231  *                  at least \p iv_len Bytes.
 232  * \param iv_len    The length of the IV.
 233  * \param add       The buffer holding the additional data, or \c NULL
 234  *                  if \p add_len is \c 0.
 235  * \param add_len   The length of the additional data. If \c 0,
 236  *                  \p add may be \c NULL.
 237  *
 238  * \return          \c 0 on success.
 239  */
 240 int mbedtls_gcm_starts(mbedtls_gcm_context *ctx,
 241                        int mode,
 242                        const unsigned char *iv,
 243                        size_t iv_len,
 244                        const unsigned char *add,
 245                        size_t add_len);
 246
 247 /**
 248  * \brief           This function feeds an input buffer into an ongoing GCM
 249  *                  encryption or decryption operation.
 250  *
 251  *    `             The function expects input to be a multiple of 16
 252  *                  Bytes. Only the last call before calling
 253  *                  mbedtls_gcm_finish() can be less than 16 Bytes.
 254  *
 255  * \note            For decryption, the output buffer cannot be the same as
 256  *                  input buffer. If the buffers overlap, the output buffer
 257  *                  must trail at least 8 Bytes behind the input buffer.
 258  *
 259  * \param ctx       The GCM context. This must be initialized.
 260  * \param length    The length of the input data. This must be a multiple of
 261  *                  16 except in the last call before mbedtls_gcm_finish().
 262  * \param input     The buffer holding the input data. If \p length is greater
 263  *                  than zero, this must be a readable buffer of at least that
 264  *                  size in Bytes.
 265  * \param output    The buffer for holding the output data. If \p length is
 266  *                  greater than zero, this must be a writable buffer of at
 267  *                  least that size in Bytes.
 268  *
 269  * \return         \c 0 on success.
 270  * \return         #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
 271  */
 272 int mbedtls_gcm_update(mbedtls_gcm_context *ctx,
 273                        size_t length,
 274                        const unsigned char *input,
 275                        unsigned char *output);
 276
 277 /**
 278  * \brief           This function finishes the GCM operation and generates
 279  *                  the authentication tag.
 280  *
 281  *                  It wraps up the GCM stream, and generates the
 282  *                  tag. The tag can have a maximum length of 16 Bytes.
 283  *
 284  * \param ctx       The GCM context. This must be initialized.
 285  * \param tag       The buffer for holding the tag. This must be a writable
 286  *                  buffer of at least \p tag_len Bytes.
 287  * \param tag_len   The length of the tag to generate. This must be at least
 288  *                  four.
 289  *
 290  * \return          \c 0 on success.
 291  * \return          #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
 292  */
 293 int mbedtls_gcm_finish(mbedtls_gcm_context *ctx,
 294                        unsigned char *tag,
 295                        size_t tag_len);
 296
 297 /**
 298  * \brief           This function clears a GCM context and the underlying
 299  *                  cipher sub-context.
 300  *
 301  * \param ctx       The GCM context to clear. If this is \c NULL, the call has
 302  *                  no effect. Otherwise, this must be initialized.
 303  */
 304 void mbedtls_gcm_free(mbedtls_gcm_context *ctx);
 305
 306 #if defined(MBEDTLS_SELF_TEST)
 307
 308 /**
 309  * \brief          The GCM checkup routine.
 310  *
 311  * \return         \c 0 on success.
 312  * \return         \c 1 on failure.
 313  */
 314 int mbedtls_gcm_self_test(int verbose);
 315
 316 #endif /* MBEDTLS_SELF_TEST */
 317
 318 #ifdef __cplusplus
 319 }
 320 #endif
 321
 322
 323 #endif /* gcm.h */