cmac.h 7.6 KB

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