gcm.h

00001 /**
00002  * \file gcm.h
00003  *
00004  * \brief Galois/Counter mode for 128-bit block ciphers
00005  *
00006  *  Copyright (C) 2006-2013, Brainspark B.V.
00007  *
00008  *  This file is part of PolarSSL (http://www.polarssl.org)
00009  *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
00010  *
00011  *  All rights reserved.
00012  *
00013  *  This program is free software; you can redistribute it and/or modify
00014  *  it under the terms of the GNU General Public License as published by
00015  *  the Free Software Foundation; either version 2 of the License, or
00016  *  (at your option) any later version.
00017  *
00018  *  This program is distributed in the hope that it will be useful,
00019  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00020  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00021  *  GNU General Public License for more details.
00022  *
00023  *  You should have received a copy of the GNU General Public License along
00024  *  with this program; if not, write to the Free Software Foundation, Inc.,
00025  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
00026  */
00027 #ifndef POLARSSL_GCM_H
00028 #define POLARSSL_GCM_H
00029 
00030 #include "cipher.h"
00031 
00032 #if defined(_MSC_VER) && !defined(EFIX64) && !defined(EFI32)
00033 #include <basetsd.h>
00034 typedef UINT32 uint32_t;
00035 typedef UINT64 uint64_t;
00036 #else
00037 #include <stdint.h>
00038 #endif
00039 
00040 #define GCM_ENCRYPT     1
00041 #define GCM_DECRYPT     0
00042 
00043 #define POLARSSL_ERR_GCM_AUTH_FAILED                       -0x0012  /**< Authenticated decryption failed. */
00044 #define POLARSSL_ERR_GCM_BAD_INPUT                         -0x0014  /**< Bad input parameters to function. */
00045 
00046 #ifdef __cplusplus
00047 extern "C" {
00048 #endif
00049 
00050 /**
00051  * \brief          GCM context structure
00052  */
00053 typedef struct {
00054     cipher_context_t cipher_ctx ;/*!< cipher context used */
00055     uint64_t HL[16];            /*!< Precalculated HTable */
00056     uint64_t HH[16];            /*!< Precalculated HTable */
00057     uint64_t len ;               /*!< Total data length */
00058     uint64_t add_len ;           /*!< Total add length */
00059     unsigned char base_ectr[16];/*!< First ECTR for tag */
00060     unsigned char y[16];        /*!< Y working value */
00061     unsigned char buf[16];      /*!< buf working value */
00062     int mode ;                   /*!< Encrypt or Decrypt */
00063 }
00064 gcm_context;
00065 
00066 /**
00067  * \brief           GCM initialization (encryption)
00068  *
00069  * \param ctx       GCM context to be initialized
00070  * \param cipher    cipher to use (a 128-bit block cipher)
00071  * \param key       encryption key
00072  * \param keysize   must be 128, 192 or 256
00073  *
00074  * \return          0 if successful, or a cipher specific error code
00075  */
00076 int gcm_init( gcm_context *ctx, cipher_id_t cipher, const unsigned char *key,
00077               unsigned int keysize );
00078 
00079 /**
00080  * \brief           GCM buffer encryption/decryption using a block cipher
00081  *
00082  * \note On encryption, the output buffer can be the same as the input buffer.
00083  *       On decryption, the output buffer cannot be the same as input buffer.
00084  *       If buffers overlap, the output buffer must trail at least 8 bytes
00085  *       behind the input buffer.
00086  *
00087  * \param ctx       GCM context
00088  * \param mode      GCM_ENCRYPT or GCM_DECRYPT
00089  * \param length    length of the input data
00090  * \param iv        initialization vector
00091  * \param iv_len    length of IV
00092  * \param add       additional data
00093  * \param add_len   length of additional data
00094  * \param input     buffer holding the input data
00095  * \param output    buffer for holding the output data
00096  * \param tag_len   length of the tag to generate
00097  * \param tag       buffer for holding the tag
00098  *
00099  * \return         0 if successful
00100  */
00101 int gcm_crypt_and_tag( gcm_context *ctx,
00102                        int mode,
00103                        size_t length,
00104                        const unsigned char *iv,
00105                        size_t iv_len,
00106                        const unsigned char *add,
00107                        size_t add_len,
00108                        const unsigned char *input,
00109                        unsigned char *output,
00110                        size_t tag_len,
00111                        unsigned char *tag );
00112 
00113 /**
00114  * \brief           GCM buffer authenticated decryption using a block cipher
00115  *
00116  * \note On decryption, the output buffer cannot be the same as input buffer.
00117  *       If buffers overlap, the output buffer must trail at least 8 bytes
00118  *       behind the input buffer.
00119  *
00120  * \param ctx       GCM context
00121  * \param length    length of the input data
00122  * \param iv        initialization vector
00123  * \param iv_len    length of IV
00124  * \param add       additional data
00125  * \param add_len   length of additional data
00126  * \param tag       buffer holding the tag
00127  * \param tag_len   length of the tag
00128  * \param input     buffer holding the input data
00129  * \param output    buffer for holding the output data
00130  *
00131  * \return         0 if successful and authenticated,
00132  *                 POLARSSL_ERR_GCM_AUTH_FAILED if tag does not match
00133  */
00134 int gcm_auth_decrypt( gcm_context *ctx,
00135                       size_t length,
00136                       const unsigned char *iv,
00137                       size_t iv_len,
00138                       const unsigned char *add,
00139                       size_t add_len,
00140                       const unsigned char *tag,
00141                       size_t tag_len,
00142                       const unsigned char *input,
00143                       unsigned char *output );
00144 
00145 /**
00146  * \brief           Generic GCM stream start function
00147  *
00148  * \param ctx       GCM context
00149  * \param mode      GCM_ENCRYPT or GCM_DECRYPT
00150  * \param iv        initialization vector
00151  * \param iv_len    length of IV
00152  * \param add       additional data (or NULL if length is 0)
00153  * \param add_len   length of additional data
00154  *
00155  * \return         0 if successful
00156  */
00157 int gcm_starts( gcm_context *ctx,
00158                 int mode,
00159                 const unsigned char *iv,
00160                 size_t iv_len,
00161                 const unsigned char *add,
00162                 size_t add_len );
00163 
00164 /**
00165  * \brief           Generic GCM update function. Encrypts/decrypts using the
00166  *                  given GCM context. Expects input to be a multiple of 16
00167  *                  bytes! Only the last call before gcm_finish() can be less
00168  *                  than 16 bytes!
00169  *
00170  * \note On decryption, the output buffer cannot be the same as input buffer.
00171  *       If buffers overlap, the output buffer must trail at least 8 bytes
00172  *       behind the input buffer.
00173  *
00174  * \param ctx       GCM context
00175  * \param length    length of the input data
00176  * \param input     buffer holding the input data
00177  * \param output    buffer for holding the output data
00178  *
00179  * \return         0 if successful or POLARSSL_ERR_GCM_BAD_INPUT
00180  */
00181 int gcm_update( gcm_context *ctx,
00182                 size_t length,
00183                 const unsigned char *input,
00184                 unsigned char *output );
00185 
00186 /**
00187  * \brief           Generic GCM finalisation function. Wraps up the GCM stream
00188  *                  and generates the tag. The tag can have a maximum length of
00189  *                  16 bytes.
00190  *
00191  * \param ctx       GCM context
00192  * \param tag       buffer for holding the tag (may be NULL if tag_len is 0)
00193  * \param tag_len   length of the tag to generate
00194  *
00195  * \return          0 if successful or POLARSSL_ERR_GCM_BAD_INPUT
00196  */
00197 int gcm_finish( gcm_context *ctx,
00198                 unsigned char *tag,
00199                 size_t tag_len );
00200 
00201 /**
00202  * \brief           Free a GCM context and underlying cipher sub-context
00203  *
00204  * \param ctx       GCM context to free
00205  */
00206 void gcm_free( gcm_context *ctx );
00207 
00208 /**
00209  * \brief          Checkup routine
00210  *
00211  * \return         0 if successful, or 1 if the test failed
00212  */
00213 int gcm_self_test( int verbose );
00214 
00215 #ifdef __cplusplus
00216 }
00217 #endif
00218 
00219 #endif /* gcm.h */
00220 
00221