sdk/include/reactos/libs/mbedtls/gcm.h

   1 /**
   2  * \file gcm.h
   3  *
   4  * \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined
   5  *        in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
   6  *        (GCM), Natl. Inst. Stand. Technol.</em>
   7  *
   8  * For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
   9  * Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
  10  *
  11  */
  12 /*
  13  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  14  *  SPDX-License-Identifier: GPL-2.0
  15  *
  16  *  This program is free software; you can redistribute it and/or modify
  17  *  it under the terms of the GNU General Public License as published by
  18  *  the Free Software Foundation; either version 2 of the License, or
  19  *  (at your option) any later version.
  20  *
  21  *  This program is distributed in the hope that it will be useful,
  22  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  23  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  24  *  GNU General Public License for more details.
  25  *
  26  *  You should have received a copy of the GNU General Public License along
  27  *  with this program; if not, write to the Free Software Foundation, Inc.,
  28  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  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 #include "cipher.h"
  37
  38 #include <stdint.h>
  39
  40 #define MBEDTLS_GCM_ENCRYPT     1
  41 #define MBEDTLS_GCM_DECRYPT     0
  42
  43 #define MBEDTLS_ERR_GCM_AUTH_FAILED                       -0x0012  /**< Authenticated decryption failed. */
  44 #define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED                   -0x0013  /**< GCM hardware accelerator failed. */
  45 #define MBEDTLS_ERR_GCM_BAD_INPUT                         -0x0014  /**< Bad input parameters to function. */
  46
  47 #if !defined(MBEDTLS_GCM_ALT)
  48
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif
  52
  53 /**
  54  * \brief          The GCM context structure.
  55  */
  56 typedef struct {
  57     mbedtls_cipher_context_t cipher_ctx;  /*!< The cipher context used. */
  58     uint64_t HL[16];                      /*!< Precalculated HTable low. */
  59     uint64_t HH[16];                      /*!< Precalculated HTable high. */
  60     uint64_t len;                         /*!< The total length of the encrypted data. */
  61     uint64_t add_len;                     /*!< The total length of the additional data. */
  62     unsigned char base_ectr[16];          /*!< The first ECTR for tag. */
  63     unsigned char y[16];                  /*!< The Y working value. */
  64     unsigned char buf[16];                /*!< The buf working value. */
  65     int mode;                             /*!< The operation to perform:
  66                                                #MBEDTLS_GCM_ENCRYPT or
  67                                                #MBEDTLS_GCM_DECRYPT. */
  68 }
  69 mbedtls_gcm_context;
  70
  71 /**
  72  * \brief           This function initializes the specified GCM context,
  73  *                  to make references valid, and prepares the context
  74  *                  for mbedtls_gcm_setkey() or mbedtls_gcm_free().
  75  *
  76  *                  The function does not bind the GCM context to a particular
  77  *                  cipher, nor set the key. For this purpose, use
  78  *                  mbedtls_gcm_setkey().
  79  *
  80  * \param ctx       The GCM context to initialize.
  81  */
  82 void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
  83
  84 /**
  85  * \brief           This function associates a GCM context with a
  86  *                  cipher algorithm and a key.
  87  *
  88  * \param ctx       The GCM context to initialize.
  89  * \param cipher    The 128-bit block cipher to use.
  90  * \param key       The encryption key.
  91  * \param keybits   The key size in bits. Valid options are:
  92  *                  <ul><li>128 bits</li>
  93  *                  <li>192 bits</li>
  94  *                  <li>256 bits</li></ul>
  95  *
  96  * \return          \c 0 on success, or a cipher specific error code.
  97  */
  98 int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
  99                         mbedtls_cipher_id_t cipher,
 100                         const unsigned char *key,
 101                         unsigned int keybits );
 102
 103 /**
 104  * \brief           This function performs GCM encryption or decryption of a buffer.
 105  *
 106  * \note For encryption, the output buffer can be the same as the input buffer.
 107  *       For decryption, the output buffer cannot be the same as input buffer.
 108  *       If the buffers overlap, the output buffer must trail at least 8 Bytes
 109  *       behind the input buffer.
 110  *
 111  * \warning         When this function performs a decryption, it outputs the
 112  *                  authentication tag and does not verify that the data is
 113  *                  authentic. You should use this function to perform encryption
 114  *                  only. For decryption, use mbedtls_gcm_auth_decrypt() instead.
 115  *
 116  * \param ctx       The GCM context to use for encryption or decryption.
 117  * \param mode      The operation to perform:
 118  *                  - #MBEDTLS_GCM_ENCRYPT to perform authenticated encryption.
 119  *                    The ciphertext is written to \p output and the
 120  *                    authentication tag is written to \p tag.
 121  *                  - #MBEDTLS_GCM_DECRYPT to perform decryption.
 122  *                    The plaintext is written to \p output and the
 123  *                    authentication tag is written to \p tag.
 124  *                    Note that this mode is not recommended, because it does
 125  *                    not verify the authenticity of the data. For this reason,
 126  *                    you should use mbedtls_gcm_auth_decrypt() instead of
 127  *                    calling this function in decryption mode.
 128  * \param length    The length of the input data, which is equal to the length
 129  *                  of the output data.
 130  * \param iv        The initialization vector.
 131  * \param iv_len    The length of the IV.
 132  * \param add       The buffer holding the additional data.
 133  * \param add_len   The length of the additional data.
 134  * \param input     The buffer holding the input data. Its size is \b length.
 135  * \param output    The buffer for holding the output data. It must have room
 136  *                  for \b length bytes.
 137  * \param tag_len   The length of the tag to generate.
 138  * \param tag       The buffer for holding the tag.
 139  *
 140  * \return          \c 0 if the encryption or decryption was performed
 141  *                  successfully. Note that in #MBEDTLS_GCM_DECRYPT mode,
 142  *                  this does not indicate that the data is authentic.
 143  * \return          #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid.
 144  * \return          #MBEDTLS_ERR_GCM_HW_ACCEL_FAILED or a cipher-specific
 145  *                  error code if the encryption or decryption failed.
 146  */
 147 int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
 148                        int mode,
 149                        size_t length,
 150                        const unsigned char *iv,
 151                        size_t iv_len,
 152                        const unsigned char *add,
 153                        size_t add_len,
 154                        const unsigned char *input,
 155                        unsigned char *output,
 156                        size_t tag_len,
 157                        unsigned char *tag );
 158
 159 /**
 160  * \brief           This function performs a GCM authenticated decryption of a
 161  *                  buffer.
 162  *
 163  * \note For decryption, the output buffer cannot be the same as input buffer.
 164  *       If the buffers overlap, the output buffer must trail at least 8 Bytes
 165  *       behind the input buffer.
 166  *
 167  * \param ctx       The GCM context.
 168  * \param length    The length of the ciphertext to decrypt, which is also
 169  *                  the length of the decrypted plaintext.
 170  * \param iv        The initialization vector.
 171  * \param iv_len    The length of the IV.
 172  * \param add       The buffer holding the additional data.
 173  * \param add_len   The length of the additional data.
 174  * \param tag       The buffer holding the tag to verify.
 175  * \param tag_len   The length of the tag to verify.
 176  * \param input     The buffer holding the ciphertext. Its size is \b length.
 177  * \param output    The buffer for holding the decrypted plaintext. It must
 178  *                  have room for \b length bytes.
 179  *
 180  * \return          \c 0 if successful and authenticated.
 181  * \return          #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
 182  * \return          #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid.
 183  * \return          #MBEDTLS_ERR_GCM_HW_ACCEL_FAILED or a cipher-specific
 184  *                  error code if the decryption failed.
 185  */
 186 int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
 187                       size_t length,
 188                       const unsigned char *iv,
 189                       size_t iv_len,
 190                       const unsigned char *add,
 191                       size_t add_len,
 192                       const unsigned char *tag,
 193                       size_t tag_len,
 194                       const unsigned char *input,
 195                       unsigned char *output );
 196
 197 /**
 198  * \brief           This function starts a GCM encryption or decryption
 199  *                  operation.
 200  *
 201  * \param ctx       The GCM context.
 202  * \param mode      The operation to perform: #MBEDTLS_GCM_ENCRYPT or
 203  *                  #MBEDTLS_GCM_DECRYPT.
 204  * \param iv        The initialization vector.
 205  * \param iv_len    The length of the IV.
 206  * \param add       The buffer holding the additional data, or NULL if \p add_len is 0.
 207  * \param add_len   The length of the additional data. If 0, \p  add is NULL.
 208  *
 209  * \return         \c 0 on success.
 210  */
 211 int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
 212                 int mode,
 213                 const unsigned char *iv,
 214                 size_t iv_len,
 215                 const unsigned char *add,
 216                 size_t add_len );
 217
 218 /**
 219  * \brief           This function feeds an input buffer into an ongoing GCM
 220  *                  encryption or decryption operation.
 221  *
 222  *    `             The function expects input to be a multiple of 16
 223  *                  Bytes. Only the last call before calling
 224  *                  mbedtls_gcm_finish() can be less than 16 Bytes.
 225  *
 226  * \note For decryption, the output buffer cannot be the same as input buffer.
 227  *       If the buffers overlap, the output buffer must trail at least 8 Bytes
 228  *       behind the input buffer.
 229  *
 230  * \param ctx       The GCM context.
 231  * \param length    The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
 232  * \param input     The buffer holding the input data.
 233  * \param output    The buffer for holding the output data.
 234  *
 235  * \return         \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
 236  */
 237 int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
 238                 size_t length,
 239                 const unsigned char *input,
 240                 unsigned char *output );
 241
 242 /**
 243  * \brief           This function finishes the GCM operation and generates
 244  *                  the authentication tag.
 245  *
 246  *                  It wraps up the GCM stream, and generates the
 247  *                  tag. The tag can have a maximum length of 16 Bytes.
 248  *
 249  * \param ctx       The GCM context.
 250  * \param tag       The buffer for holding the tag.
 251  * \param tag_len   The length of the tag to generate. Must be at least four.
 252  *
 253  * \return          \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
 254  */
 255 int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
 256                 unsigned char *tag,
 257                 size_t tag_len );
 258
 259 /**
 260  * \brief           This function clears a GCM context and the underlying
 261  *                  cipher sub-context.
 262  *
 263  * \param ctx       The GCM context to clear.
 264  */
 265 void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
 266
 267 #ifdef __cplusplus
 268 }
 269 #endif
 270
 271 #else  /* !MBEDTLS_GCM_ALT */
 272 #include "gcm_alt.h"
 273 #endif /* !MBEDTLS_GCM_ALT */
 274
 275 #ifdef __cplusplus
 276 extern "C" {
 277 #endif
 278
 279 /**
 280  * \brief          The GCM checkup routine.
 281  *
 282  * \return         \c 0 on success, or \c 1 on failure.
 283  */
 284 int mbedtls_gcm_self_test( int verbose );
 285
 286 #ifdef __cplusplus
 287 }
 288 #endif
 289
 290
 291 #endif /* gcm.h */