Doug Anson / mbedTLSLibrary

mbed TLS library

Dependents:   HTTPClient-SSL WS_SERVER

include/polarssl/gcm.h@0:137634ff4186, 2015-06-11 (annotated)

Committer:
ansond
Date:
Thu Jun 11 03:27:03 2015 +0000
Revision:
0:137634ff4186
initial commit

Who changed what in which revision?

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