cmac.h 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213
  1. /**
  2. * \file cmac.h
  3. *
  4. * \brief This file contains CMAC definitions and functions.
  5. *
  6. * The Cipher-based Message Authentication Code (CMAC) Mode for
  7. * Authentication is defined in <em>RFC-4493: The AES-CMAC Algorithm</em>.
  8. */
  9. /*
  10. * Copyright (C) 2015-2018, Arm Limited (or its affiliates), All Rights Reserved
  11. * SPDX-License-Identifier: Apache-2.0
  12. *
  13. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  14. * not use this file except in compliance with the License.
  15. * You may obtain a copy of the License at
  16. *
  17. * http://www.apache.org/licenses/LICENSE-2.0
  18. *
  19. * Unless required by applicable law or agreed to in writing, software
  20. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  21. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  22. * See the License for the specific language governing permissions and
  23. * limitations under the License.
  24. *
  25. * This file is part of Mbed TLS (https://tls.mbed.org)
  26. */
  27. #ifndef MBEDTLS_CMAC_H
  28. #define MBEDTLS_CMAC_H
  29. #if !defined(MBEDTLS_CONFIG_FILE)
  30. #include "config.h"
  31. #else
  32. #include MBEDTLS_CONFIG_FILE
  33. #endif
  34. #include "cipher.h"
  35. #ifdef __cplusplus
  36. extern "C" {
  37. #endif
  38. /* MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED is deprecated and should not be used. */
  39. #define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A /**< CMAC hardware accelerator failed. */
  40. #define MBEDTLS_AES_BLOCK_SIZE 16
  41. #define MBEDTLS_DES3_BLOCK_SIZE 8
  42. #if defined(MBEDTLS_AES_C)
  43. #define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /**< The longest block used by CMAC is that of AES. */
  44. #else
  45. #define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /**< The longest block used by CMAC is that of 3DES. */
  46. #endif
  47. #if !defined(MBEDTLS_CMAC_ALT)
  48. /**
  49. * The CMAC context structure.
  50. */
  51. struct mbedtls_cmac_context_t
  52. {
  53. /** The internal state of the CMAC algorithm. */
  54. unsigned char state[MBEDTLS_CIPHER_BLKSIZE_MAX];
  55. /** Unprocessed data - either data that was not block aligned and is still
  56. * pending processing, or the final block. */
  57. unsigned char unprocessed_block[MBEDTLS_CIPHER_BLKSIZE_MAX];
  58. /** The length of data pending processing. */
  59. size_t unprocessed_len;
  60. };
  61. #else /* !MBEDTLS_CMAC_ALT */
  62. #include "cmac_alt.h"
  63. #endif /* !MBEDTLS_CMAC_ALT */
  64. /**
  65. * \brief This function sets the CMAC key, and prepares to authenticate
  66. * the input data.
  67. * Must be called with an initialized cipher context.
  68. *
  69. * \param ctx The cipher context used for the CMAC operation, initialized
  70. * as one of the following types: MBEDTLS_CIPHER_AES_128_ECB,
  71. * MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_256_ECB,
  72. * or MBEDTLS_CIPHER_DES_EDE3_ECB.
  73. * \param key The CMAC key.
  74. * \param keybits The length of the CMAC key in bits.
  75. * Must be supported by the cipher.
  76. *
  77. * \return \c 0 on success.
  78. * \return A cipher-specific error code on failure.
  79. */
  80. int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
  81. const unsigned char *key, size_t keybits );
  82. /**
  83. * \brief This function feeds an input buffer into an ongoing CMAC
  84. * computation.
  85. *
  86. * It is called between mbedtls_cipher_cmac_starts() or
  87. * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish().
  88. * Can be called repeatedly.
  89. *
  90. * \param ctx The cipher context used for the CMAC operation.
  91. * \param input The buffer holding the input data.
  92. * \param ilen The length of the input data.
  93. *
  94. * \return \c 0 on success.
  95. * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
  96. * if parameter verification fails.
  97. */
  98. int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
  99. const unsigned char *input, size_t ilen );
  100. /**
  101. * \brief This function finishes the CMAC operation, and writes
  102. * the result to the output buffer.
  103. *
  104. * It is called after mbedtls_cipher_cmac_update().
  105. * It can be followed by mbedtls_cipher_cmac_reset() and
  106. * mbedtls_cipher_cmac_update(), or mbedtls_cipher_free().
  107. *
  108. * \param ctx The cipher context used for the CMAC operation.
  109. * \param output The output buffer for the CMAC checksum result.
  110. *
  111. * \return \c 0 on success.
  112. * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
  113. * if parameter verification fails.
  114. */
  115. int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
  116. unsigned char *output );
  117. /**
  118. * \brief This function prepares the authentication of another
  119. * message with the same key as the previous CMAC
  120. * operation.
  121. *
  122. * It is called after mbedtls_cipher_cmac_finish()
  123. * and before mbedtls_cipher_cmac_update().
  124. *
  125. * \param ctx The cipher context used for the CMAC operation.
  126. *
  127. * \return \c 0 on success.
  128. * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
  129. * if parameter verification fails.
  130. */
  131. int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx );
  132. /**
  133. * \brief This function calculates the full generic CMAC
  134. * on the input buffer with the provided key.
  135. *
  136. * The function allocates the context, performs the
  137. * calculation, and frees the context.
  138. *
  139. * The CMAC result is calculated as
  140. * output = generic CMAC(cmac key, input buffer).
  141. *
  142. *
  143. * \param cipher_info The cipher information.
  144. * \param key The CMAC key.
  145. * \param keylen The length of the CMAC key in bits.
  146. * \param input The buffer holding the input data.
  147. * \param ilen The length of the input data.
  148. * \param output The buffer for the generic CMAC result.
  149. *
  150. * \return \c 0 on success.
  151. * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
  152. * if parameter verification fails.
  153. */
  154. int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
  155. const unsigned char *key, size_t keylen,
  156. const unsigned char *input, size_t ilen,
  157. unsigned char *output );
  158. #if defined(MBEDTLS_AES_C)
  159. /**
  160. * \brief This function implements the AES-CMAC-PRF-128 pseudorandom
  161. * function, as defined in
  162. * <em>RFC-4615: The Advanced Encryption Standard-Cipher-based
  163. * Message Authentication Code-Pseudo-Random Function-128
  164. * (AES-CMAC-PRF-128) Algorithm for the Internet Key
  165. * Exchange Protocol (IKE).</em>
  166. *
  167. * \param key The key to use.
  168. * \param key_len The key length in Bytes.
  169. * \param input The buffer holding the input data.
  170. * \param in_len The length of the input data in Bytes.
  171. * \param output The buffer holding the generated 16 Bytes of
  172. * pseudorandom output.
  173. *
  174. * \return \c 0 on success.
  175. */
  176. int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len,
  177. const unsigned char *input, size_t in_len,
  178. unsigned char output[16] );
  179. #endif /* MBEDTLS_AES_C */
  180. #if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) )
  181. /**
  182. * \brief The CMAC checkup routine.
  183. *
  184. * \return \c 0 on success.
  185. * \return \c 1 on failure.
  186. */
  187. int mbedtls_cmac_self_test( int verbose );
  188. #endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */
  189. #ifdef __cplusplus
  190. }
  191. #endif
  192. #endif /* MBEDTLS_CMAC_H */