git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/gcm.h

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