Eric Tsai / mbedtls

Modified mbed TLS headers for AES functionality only to reduce build size

Dependents:   BLE_Gateway_Linker_fix BLE_Gateway

Fork of mbedtls by sandbox

mbedtls/gcm.h@5:f09f5ed830ca, 2017-07-10 (annotated)

Committer:
electronichamsters
Date:
Mon Jul 10 04:00:25 2017 +0000
Revision:
5:f09f5ed830ca
Parent:
1:24750b9ad5ef 
working gateway

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Christopher Haster 1:24750b9ad5ef 1 /**
Christopher Haster 1:24750b9ad5ef 2 * \file gcm.h
Christopher Haster 1:24750b9ad5ef 3 *
Christopher Haster 1:24750b9ad5ef 4 * \brief Galois/Counter mode for 128-bit block ciphers
Christopher Haster 1:24750b9ad5ef 5 *
Christopher Haster 1:24750b9ad5ef 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
Christopher Haster 1:24750b9ad5ef 7 * SPDX-License-Identifier: Apache-2.0
Christopher Haster 1:24750b9ad5ef 8 *
Christopher Haster 1:24750b9ad5ef 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
Christopher Haster 1:24750b9ad5ef 10 * not use this file except in compliance with the License.
Christopher Haster 1:24750b9ad5ef 11 * You may obtain a copy of the License at
Christopher Haster 1:24750b9ad5ef 12 *
Christopher Haster 1:24750b9ad5ef 13 * http://www.apache.org/licenses/LICENSE-2.0
Christopher Haster 1:24750b9ad5ef 14 *
Christopher Haster 1:24750b9ad5ef 15 * Unless required by applicable law or agreed to in writing, software
Christopher Haster 1:24750b9ad5ef 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
Christopher Haster 1:24750b9ad5ef 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Christopher Haster 1:24750b9ad5ef 18 * See the License for the specific language governing permissions and
Christopher Haster 1:24750b9ad5ef 19 * limitations under the License.
Christopher Haster 1:24750b9ad5ef 20 *
Christopher Haster 1:24750b9ad5ef 21 * This file is part of mbed TLS (https://tls.mbed.org)
Christopher Haster 1:24750b9ad5ef 22 */
Christopher Haster 1:24750b9ad5ef 23 #ifndef MBEDTLS_GCM_H
Christopher Haster 1:24750b9ad5ef 24 #define MBEDTLS_GCM_H
Christopher Haster 1:24750b9ad5ef 25
Christopher Haster 1:24750b9ad5ef 26 #include "cipher.h"
Christopher Haster 1:24750b9ad5ef 27
Christopher Haster 1:24750b9ad5ef 28 #include <stdint.h>
Christopher Haster 1:24750b9ad5ef 29
Christopher Haster 1:24750b9ad5ef 30 #define MBEDTLS_GCM_ENCRYPT 1
Christopher Haster 1:24750b9ad5ef 31 #define MBEDTLS_GCM_DECRYPT 0
Christopher Haster 1:24750b9ad5ef 32
Christopher Haster 1:24750b9ad5ef 33 #define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012 /**< Authenticated decryption failed. */
Christopher Haster 1:24750b9ad5ef 34 #define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014 /**< Bad input parameters to function. */
Christopher Haster 1:24750b9ad5ef 35
Christopher Haster 1:24750b9ad5ef 36 #ifdef __cplusplus
Christopher Haster 1:24750b9ad5ef 37 extern "C" {
Christopher Haster 1:24750b9ad5ef 38 #endif
Christopher Haster 1:24750b9ad5ef 39
Christopher Haster 1:24750b9ad5ef 40 /**
Christopher Haster 1:24750b9ad5ef 41 * \brief GCM context structure
Christopher Haster 1:24750b9ad5ef 42 */
Christopher Haster 1:24750b9ad5ef 43 typedef struct {
Christopher Haster 1:24750b9ad5ef 44 mbedtls_cipher_context_t cipher_ctx;/*!< cipher context used */
Christopher Haster 1:24750b9ad5ef 45 uint64_t HL[16]; /*!< Precalculated HTable */
Christopher Haster 1:24750b9ad5ef 46 uint64_t HH[16]; /*!< Precalculated HTable */
Christopher Haster 1:24750b9ad5ef 47 uint64_t len; /*!< Total data length */
Christopher Haster 1:24750b9ad5ef 48 uint64_t add_len; /*!< Total add length */
Christopher Haster 1:24750b9ad5ef 49 unsigned char base_ectr[16];/*!< First ECTR for tag */
Christopher Haster 1:24750b9ad5ef 50 unsigned char y[16]; /*!< Y working value */
Christopher Haster 1:24750b9ad5ef 51 unsigned char buf[16]; /*!< buf working value */
Christopher Haster 1:24750b9ad5ef 52 int mode; /*!< Encrypt or Decrypt */
Christopher Haster 1:24750b9ad5ef 53 }
Christopher Haster 1:24750b9ad5ef 54 mbedtls_gcm_context;
Christopher Haster 1:24750b9ad5ef 55
Christopher Haster 1:24750b9ad5ef 56 /**
Christopher Haster 1:24750b9ad5ef 57 * \brief Initialize GCM context (just makes references valid)
Christopher Haster 1:24750b9ad5ef 58 * Makes the context ready for mbedtls_gcm_setkey() or
Christopher Haster 1:24750b9ad5ef 59 * mbedtls_gcm_free().
Christopher Haster 1:24750b9ad5ef 60 *
Christopher Haster 1:24750b9ad5ef 61 * \param ctx GCM context to initialize
Christopher Haster 1:24750b9ad5ef 62 */
Christopher Haster 1:24750b9ad5ef 63 void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
Christopher Haster 1:24750b9ad5ef 64
Christopher Haster 1:24750b9ad5ef 65 /**
Christopher Haster 1:24750b9ad5ef 66 * \brief GCM initialization (encryption)
Christopher Haster 1:24750b9ad5ef 67 *
Christopher Haster 1:24750b9ad5ef 68 * \param ctx GCM context to be initialized
Christopher Haster 1:24750b9ad5ef 69 * \param cipher cipher to use (a 128-bit block cipher)
Christopher Haster 1:24750b9ad5ef 70 * \param key encryption key
Christopher Haster 1:24750b9ad5ef 71 * \param keybits must be 128, 192 or 256
Christopher Haster 1:24750b9ad5ef 72 *
Christopher Haster 1:24750b9ad5ef 73 * \return 0 if successful, or a cipher specific error code
Christopher Haster 1:24750b9ad5ef 74 */
Christopher Haster 1:24750b9ad5ef 75 int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
Christopher Haster 1:24750b9ad5ef 76 mbedtls_cipher_id_t cipher,
Christopher Haster 1:24750b9ad5ef 77 const unsigned char *key,
Christopher Haster 1:24750b9ad5ef 78 unsigned int keybits );
Christopher Haster 1:24750b9ad5ef 79
Christopher Haster 1:24750b9ad5ef 80 /**
Christopher Haster 1:24750b9ad5ef 81 * \brief GCM buffer encryption/decryption using a block cipher
Christopher Haster 1:24750b9ad5ef 82 *
Christopher Haster 1:24750b9ad5ef 83 * \note On encryption, the output buffer can be the same as the input buffer.
Christopher Haster 1:24750b9ad5ef 84 * On decryption, the output buffer cannot be the same as input buffer.
Christopher Haster 1:24750b9ad5ef 85 * If buffers overlap, the output buffer must trail at least 8 bytes
Christopher Haster 1:24750b9ad5ef 86 * behind the input buffer.
Christopher Haster 1:24750b9ad5ef 87 *
Christopher Haster 1:24750b9ad5ef 88 * \param ctx GCM context
Christopher Haster 1:24750b9ad5ef 89 * \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT
Christopher Haster 1:24750b9ad5ef 90 * \param length length of the input data
Christopher Haster 1:24750b9ad5ef 91 * \param iv initialization vector
Christopher Haster 1:24750b9ad5ef 92 * \param iv_len length of IV
Christopher Haster 1:24750b9ad5ef 93 * \param add additional data
Christopher Haster 1:24750b9ad5ef 94 * \param add_len length of additional data
Christopher Haster 1:24750b9ad5ef 95 * \param input buffer holding the input data
Christopher Haster 1:24750b9ad5ef 96 * \param output buffer for holding the output data
Christopher Haster 1:24750b9ad5ef 97 * \param tag_len length of the tag to generate
Christopher Haster 1:24750b9ad5ef 98 * \param tag buffer for holding the tag
Christopher Haster 1:24750b9ad5ef 99 *
Christopher Haster 1:24750b9ad5ef 100 * \return 0 if successful
Christopher Haster 1:24750b9ad5ef 101 */
Christopher Haster 1:24750b9ad5ef 102 int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
Christopher Haster 1:24750b9ad5ef 103 int mode,
Christopher Haster 1:24750b9ad5ef 104 size_t length,
Christopher Haster 1:24750b9ad5ef 105 const unsigned char *iv,
Christopher Haster 1:24750b9ad5ef 106 size_t iv_len,
Christopher Haster 1:24750b9ad5ef 107 const unsigned char *add,
Christopher Haster 1:24750b9ad5ef 108 size_t add_len,
Christopher Haster 1:24750b9ad5ef 109 const unsigned char *input,
Christopher Haster 1:24750b9ad5ef 110 unsigned char *output,
Christopher Haster 1:24750b9ad5ef 111 size_t tag_len,
Christopher Haster 1:24750b9ad5ef 112 unsigned char *tag );
Christopher Haster 1:24750b9ad5ef 113
Christopher Haster 1:24750b9ad5ef 114 /**
Christopher Haster 1:24750b9ad5ef 115 * \brief GCM buffer authenticated decryption using a block cipher
Christopher Haster 1:24750b9ad5ef 116 *
Christopher Haster 1:24750b9ad5ef 117 * \note On decryption, the output buffer cannot be the same as input buffer.
Christopher Haster 1:24750b9ad5ef 118 * If buffers overlap, the output buffer must trail at least 8 bytes
Christopher Haster 1:24750b9ad5ef 119 * behind the input buffer.
Christopher Haster 1:24750b9ad5ef 120 *
Christopher Haster 1:24750b9ad5ef 121 * \param ctx GCM context
Christopher Haster 1:24750b9ad5ef 122 * \param length length of the input data
Christopher Haster 1:24750b9ad5ef 123 * \param iv initialization vector
Christopher Haster 1:24750b9ad5ef 124 * \param iv_len length of IV
Christopher Haster 1:24750b9ad5ef 125 * \param add additional data
Christopher Haster 1:24750b9ad5ef 126 * \param add_len length of additional data
Christopher Haster 1:24750b9ad5ef 127 * \param tag buffer holding the tag
Christopher Haster 1:24750b9ad5ef 128 * \param tag_len length of the tag
Christopher Haster 1:24750b9ad5ef 129 * \param input buffer holding the input data
Christopher Haster 1:24750b9ad5ef 130 * \param output buffer for holding the output data
Christopher Haster 1:24750b9ad5ef 131 *
Christopher Haster 1:24750b9ad5ef 132 * \return 0 if successful and authenticated,
Christopher Haster 1:24750b9ad5ef 133 * MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match
Christopher Haster 1:24750b9ad5ef 134 */
Christopher Haster 1:24750b9ad5ef 135 int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
Christopher Haster 1:24750b9ad5ef 136 size_t length,
Christopher Haster 1:24750b9ad5ef 137 const unsigned char *iv,
Christopher Haster 1:24750b9ad5ef 138 size_t iv_len,
Christopher Haster 1:24750b9ad5ef 139 const unsigned char *add,
Christopher Haster 1:24750b9ad5ef 140 size_t add_len,
Christopher Haster 1:24750b9ad5ef 141 const unsigned char *tag,
Christopher Haster 1:24750b9ad5ef 142 size_t tag_len,
Christopher Haster 1:24750b9ad5ef 143 const unsigned char *input,
Christopher Haster 1:24750b9ad5ef 144 unsigned char *output );
Christopher Haster 1:24750b9ad5ef 145
Christopher Haster 1:24750b9ad5ef 146 /**
Christopher Haster 1:24750b9ad5ef 147 * \brief Generic GCM stream start function
Christopher Haster 1:24750b9ad5ef 148 *
Christopher Haster 1:24750b9ad5ef 149 * \param ctx GCM context
Christopher Haster 1:24750b9ad5ef 150 * \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT
Christopher Haster 1:24750b9ad5ef 151 * \param iv initialization vector
Christopher Haster 1:24750b9ad5ef 152 * \param iv_len length of IV
Christopher Haster 1:24750b9ad5ef 153 * \param add additional data (or NULL if length is 0)
Christopher Haster 1:24750b9ad5ef 154 * \param add_len length of additional data
Christopher Haster 1:24750b9ad5ef 155 *
Christopher Haster 1:24750b9ad5ef 156 * \return 0 if successful
Christopher Haster 1:24750b9ad5ef 157 */
Christopher Haster 1:24750b9ad5ef 158 int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
Christopher Haster 1:24750b9ad5ef 159 int mode,
Christopher Haster 1:24750b9ad5ef 160 const unsigned char *iv,
Christopher Haster 1:24750b9ad5ef 161 size_t iv_len,
Christopher Haster 1:24750b9ad5ef 162 const unsigned char *add,
Christopher Haster 1:24750b9ad5ef 163 size_t add_len );
Christopher Haster 1:24750b9ad5ef 164
Christopher Haster 1:24750b9ad5ef 165 /**
Christopher Haster 1:24750b9ad5ef 166 * \brief Generic GCM update function. Encrypts/decrypts using the
Christopher Haster 1:24750b9ad5ef 167 * given GCM context. Expects input to be a multiple of 16
Christopher Haster 1:24750b9ad5ef 168 * bytes! Only the last call before mbedtls_gcm_finish() can be less
Christopher Haster 1:24750b9ad5ef 169 * than 16 bytes!
Christopher Haster 1:24750b9ad5ef 170 *
Christopher Haster 1:24750b9ad5ef 171 * \note On decryption, the output buffer cannot be the same as input buffer.
Christopher Haster 1:24750b9ad5ef 172 * If buffers overlap, the output buffer must trail at least 8 bytes
Christopher Haster 1:24750b9ad5ef 173 * behind the input buffer.
Christopher Haster 1:24750b9ad5ef 174 *
Christopher Haster 1:24750b9ad5ef 175 * \param ctx GCM context
Christopher Haster 1:24750b9ad5ef 176 * \param length length of the input data
Christopher Haster 1:24750b9ad5ef 177 * \param input buffer holding the input data
Christopher Haster 1:24750b9ad5ef 178 * \param output buffer for holding the output data
Christopher Haster 1:24750b9ad5ef 179 *
Christopher Haster 1:24750b9ad5ef 180 * \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT
Christopher Haster 1:24750b9ad5ef 181 */
Christopher Haster 1:24750b9ad5ef 182 int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
Christopher Haster 1:24750b9ad5ef 183 size_t length,
Christopher Haster 1:24750b9ad5ef 184 const unsigned char *input,
Christopher Haster 1:24750b9ad5ef 185 unsigned char *output );
Christopher Haster 1:24750b9ad5ef 186
Christopher Haster 1:24750b9ad5ef 187 /**
Christopher Haster 1:24750b9ad5ef 188 * \brief Generic GCM finalisation function. Wraps up the GCM stream
Christopher Haster 1:24750b9ad5ef 189 * and generates the tag. The tag can have a maximum length of
Christopher Haster 1:24750b9ad5ef 190 * 16 bytes.
Christopher Haster 1:24750b9ad5ef 191 *
Christopher Haster 1:24750b9ad5ef 192 * \param ctx GCM context
Christopher Haster 1:24750b9ad5ef 193 * \param tag buffer for holding the tag (may be NULL if tag_len is 0)
Christopher Haster 1:24750b9ad5ef 194 * \param tag_len length of the tag to generate
Christopher Haster 1:24750b9ad5ef 195 *
Christopher Haster 1:24750b9ad5ef 196 * \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT
Christopher Haster 1:24750b9ad5ef 197 */
Christopher Haster 1:24750b9ad5ef 198 int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
Christopher Haster 1:24750b9ad5ef 199 unsigned char *tag,
Christopher Haster 1:24750b9ad5ef 200 size_t tag_len );
Christopher Haster 1:24750b9ad5ef 201
Christopher Haster 1:24750b9ad5ef 202 /**
Christopher Haster 1:24750b9ad5ef 203 * \brief Free a GCM context and underlying cipher sub-context
Christopher Haster 1:24750b9ad5ef 204 *
Christopher Haster 1:24750b9ad5ef 205 * \param ctx GCM context to free
Christopher Haster 1:24750b9ad5ef 206 */
Christopher Haster 1:24750b9ad5ef 207 void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
Christopher Haster 1:24750b9ad5ef 208
Christopher Haster 1:24750b9ad5ef 209 /**
Christopher Haster 1:24750b9ad5ef 210 * \brief Checkup routine
Christopher Haster 1:24750b9ad5ef 211 *
Christopher Haster 1:24750b9ad5ef 212 * \return 0 if successful, or 1 if the test failed
Christopher Haster 1:24750b9ad5ef 213 */
Christopher Haster 1:24750b9ad5ef 214 int mbedtls_gcm_self_test( int verbose );
Christopher Haster 1:24750b9ad5ef 215
Christopher Haster 1:24750b9ad5ef 216 #ifdef __cplusplus
Christopher Haster 1:24750b9ad5ef 217 }
Christopher Haster 1:24750b9ad5ef 218 #endif
Christopher Haster 1:24750b9ad5ef 219
Christopher Haster 1:24750b9ad5ef 220 #endif /* gcm.h */