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