gcm.h 7.6 KB

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