src/libpolarssl/gcm.h

   1 /**
   2  * \file gcm.h
   3  *
   4  * \brief Galois/Counter mode for 128-bit block ciphers
   5  *
   6  *  Copyright (C) 2006-2013, Brainspark B.V.
   7  *
   8  *  This file is part of PolarSSL (http://www.polarssl.org)
   9  *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
  10  *
  11  *  All rights reserved.
  12  *
  13  *  This program is free software; you can redistribute it and/or modify
  14  *  it under the terms of the GNU General Public License as published by
  15  *  the Free Software Foundation; either version 2 of the License, or
  16  *  (at your option) any later version.
  17  *
  18  *  This program is distributed in the hope that it will be useful,
  19  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  *  GNU General Public License for more details.
  22  *
  23  *  You should have received a copy of the GNU General Public License along
  24  *  with this program; if not, write to the Free Software Foundation, Inc.,
  25  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  26  */
  27 #ifndef POLARSSL_GCM_H
  28 #define POLARSSL_GCM_H
  29
  30 #include "cipher.h"
  31
  32 #if defined(_MSC_VER) && !defined(EFIX64) && !defined(EFI32)
  33 #include <basetsd.h>
  34 typedef UINT32 uint32_t;
  35 typedef UINT64 uint64_t;
  36 #else
  37 #include <stdint.h>
  38 #endif
  39
  40 #define GCM_ENCRYPT     1
  41 #define GCM_DECRYPT     0
  42
  43 #define POLARSSL_ERR_GCM_AUTH_FAILED                       -0x0012  /**< Authenticated decryption failed. */
  44 #define POLARSSL_ERR_GCM_BAD_INPUT                         -0x0014  /**< Bad input parameters to function. */
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 /**
  51  * \brief          GCM context structure
  52  */
  53 typedef struct {
  54     cipher_context_t cipher_ctx;/*!< cipher context used */
  55     uint64_t HL[16];            /*!< Precalculated HTable */
  56     uint64_t HH[16];            /*!< Precalculated HTable */
  57     uint64_t len;               /*!< Total data length */
  58     uint64_t add_len;           /*!< Total add length */
  59     unsigned char base_ectr[16];/*!< First ECTR for tag */
  60     unsigned char y[16];        /*!< Y working value */
  61     unsigned char buf[16];      /*!< buf working value */
  62     int mode;                   /*!< Encrypt or Decrypt */
  63 }
  64 gcm_context;
  65
  66 /**
  67  * \brief           GCM initialization (encryption)
  68  *
  69  * \param ctx       GCM context to be initialized
  70  * \param cipher    cipher to use (a 128-bit block cipher)
  71  * \param key       encryption key
  72  * \param keysize   must be 128, 192 or 256
  73  *
  74  * \return          0 if successful, or a cipher specific error code
  75  */
  76 int gcm_init( gcm_context *ctx, cipher_id_t cipher, const unsigned char *key,
  77               unsigned int keysize );
  78
  79 /**
  80  * \brief           GCM buffer encryption/decryption using a block cipher
  81  *
  82  * \note On encryption, the output buffer can be the same as the input buffer.
  83  *       On decryption, the output buffer cannot be the same as input buffer.
  84  *       If buffers overlap, the output buffer must trail at least 8 bytes
  85  *       behind the input buffer.
  86  *
  87  * \param ctx       GCM context
  88  * \param mode      GCM_ENCRYPT or GCM_DECRYPT
  89  * \param length    length of the input data
  90  * \param iv        initialization vector
  91  * \param iv_len    length of IV
  92  * \param add       additional data
  93  * \param add_len   length of additional data
  94  * \param input     buffer holding the input data
  95  * \param output    buffer for holding the output data
  96  * \param tag_len   length of the tag to generate
  97  * \param tag       buffer for holding the tag
  98  *
  99  * \return         0 if successful
 100  */
 101 int gcm_crypt_and_tag( gcm_context *ctx,
 102                        int mode,
 103                        size_t length,
 104                        const unsigned char *iv,
 105                        size_t iv_len,
 106                        const unsigned char *add,
 107                        size_t add_len,
 108                        const unsigned char *input,
 109                        unsigned char *output,
 110                        size_t tag_len,
 111                        unsigned char *tag );
 112
 113 /**
 114  * \brief           GCM buffer authenticated decryption using a block cipher
 115  *
 116  * \note On decryption, the output buffer cannot be the same as input buffer.
 117  *       If buffers overlap, the output buffer must trail at least 8 bytes
 118  *       behind the input buffer.
 119  *
 120  * \param ctx       GCM context
 121  * \param length    length of the input data
 122  * \param iv        initialization vector
 123  * \param iv_len    length of IV
 124  * \param add       additional data
 125  * \param add_len   length of additional data
 126  * \param tag       buffer holding the tag
 127  * \param tag_len   length of the tag
 128  * \param input     buffer holding the input data
 129  * \param output    buffer for holding the output data
 130  *
 131  * \return         0 if successful and authenticated,
 132  *                 POLARSSL_ERR_GCM_AUTH_FAILED if tag does not match
 133  */
 134 int gcm_auth_decrypt( gcm_context *ctx,
 135                       size_t length,
 136                       const unsigned char *iv,
 137                       size_t iv_len,
 138                       const unsigned char *add,
 139                       size_t add_len,
 140                       const unsigned char *tag,
 141                       size_t tag_len,
 142                       const unsigned char *input,
 143                       unsigned char *output );
 144
 145 /**
 146  * \brief           Generic GCM stream start function
 147  *
 148  * \param ctx       GCM context
 149  * \param mode      GCM_ENCRYPT or GCM_DECRYPT
 150  * \param iv        initialization vector
 151  * \param iv_len    length of IV
 152  * \param add       additional data (or NULL if length is 0)
 153  * \param add_len   length of additional data
 154  *
 155  * \return         0 if successful
 156  */
 157 int gcm_starts( gcm_context *ctx,
 158                 int mode,
 159                 const unsigned char *iv,
 160                 size_t iv_len,
 161                 const unsigned char *add,
 162                 size_t add_len );
 163
 164 /**
 165  * \brief           Generic GCM update function. Encrypts/decrypts using the
 166  *                  given GCM context. Expects input to be a multiple of 16
 167  *                  bytes! Only the last call before gcm_finish() can be less
 168  *                  than 16 bytes!
 169  *
 170  * \note On decryption, the output buffer cannot be the same as input buffer.
 171  *       If buffers overlap, the output buffer must trail at least 8 bytes
 172  *       behind the input buffer.
 173  *
 174  * \param ctx       GCM context
 175  * \param length    length of the input data
 176  * \param input     buffer holding the input data
 177  * \param output    buffer for holding the output data
 178  *
 179  * \return         0 if successful or POLARSSL_ERR_GCM_BAD_INPUT
 180  */
 181 int gcm_update( gcm_context *ctx,
 182                 size_t length,
 183                 const unsigned char *input,
 184                 unsigned char *output );
 185
 186 /**
 187  * \brief           Generic GCM finalisation function. Wraps up the GCM stream
 188  *                  and generates the tag. The tag can have a maximum length of
 189  *                  16 bytes.
 190  *
 191  * \param ctx       GCM context
 192  * \param tag       buffer for holding the tag (may be NULL if tag_len is 0)
 193  * \param tag_len   length of the tag to generate
 194  *
 195  * \return          0 if successful or POLARSSL_ERR_GCM_BAD_INPUT
 196  */
 197 int gcm_finish( gcm_context *ctx,
 198                 unsigned char *tag,
 199                 size_t tag_len );
 200
 201 /**
 202  * \brief           Free a GCM context and underlying cipher sub-context
 203  *
 204  * \param ctx       GCM context to free
 205  */
 206 void gcm_free( gcm_context *ctx );
 207
 208 /**
 209  * \brief          Checkup routine
 210  *
 211  * \return         0 if successful, or 1 if the test failed
 212  */
 213 int gcm_self_test( int verbose );
 214
 215 #ifdef __cplusplus
 216 }
 217 #endif
 218
 219 #endif /* gcm.h */