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 The Mbed TLS Contributors 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 26 #ifndef MBEDTLS_CMAC_H 27 #define MBEDTLS_CMAC_H 28 29 #if !defined(MBEDTLS_CONFIG_FILE) 30 #include "mbedtls/config.h" 31 #else 32 #include MBEDTLS_CONFIG_FILE 33 #endif 34 35 #include "mbedtls/cipher.h" 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 /* MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED is deprecated and should not be used. */ 42 #define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A /**< CMAC hardware accelerator failed. */ 43 44 #define MBEDTLS_AES_BLOCK_SIZE 16 45 #define MBEDTLS_DES3_BLOCK_SIZE 8 46 47 #if defined(MBEDTLS_AES_C) 48 #define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /**< The longest block used by CMAC is that of AES. */ 49 #else 50 #define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /**< The longest block used by CMAC is that of 3DES. */ 51 #endif 52 53 #if !defined(MBEDTLS_CMAC_ALT) 54 55 /** 56 * The CMAC context structure. 57 */ 58 struct mbedtls_cmac_context_t 59 { 60 /** The internal state of the CMAC algorithm. */ 61 unsigned char state[MBEDTLS_CIPHER_BLKSIZE_MAX]; 62 63 /** Unprocessed data - either data that was not block aligned and is still 64 * pending processing, or the final block. */ 65 unsigned char unprocessed_block[MBEDTLS_CIPHER_BLKSIZE_MAX]; 66 67 /** The length of data pending processing. */ 68 size_t unprocessed_len; 69 }; 70 71 #else /* !MBEDTLS_CMAC_ALT */ 72 #include "cmac_alt.h" 73 #endif /* !MBEDTLS_CMAC_ALT */ 74 75 /** 76 * \brief Initialises and allocat cmac context memory 77 * Must be called with an initialized cipher context. 78 * 79 * \param ctx The cipher context used for the CMAC operation, initialized 80 * as one of the following types: MBEDTLS_CIPHER_AES_128_ECB, 81 * MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_256_ECB, 82 * or MBEDTLS_CIPHER_DES_EDE3_ECB. 83 * \return \c 0 on success. 84 * \return A cipher-specific error code on failure. 85 */ 86 int mbedtls_cipher_cmac_setup(mbedtls_cipher_context_t *ctx); 87 88 /** 89 * \brief This function sets the CMAC key, and prepares to authenticate 90 * the input data. 91 * Must be called with an initialized cipher context. 92 * 93 * \note When the CMAC implementation is supplied by an alternate 94 * implementation (through #MBEDTLS_CMAC_ALT), some ciphers 95 * may not be supported by that implementation, and thus 96 * return an error. Alternate implementations must support 97 * AES-128 and AES-256, and may support AES-192 and 3DES. 98 * 99 * \param ctx The cipher context used for the CMAC operation, initialized 100 * as one of the following types: MBEDTLS_CIPHER_AES_128_ECB, 101 * MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_256_ECB, 102 * or MBEDTLS_CIPHER_DES_EDE3_ECB. 103 * \param key The CMAC key. 104 * \param keybits The length of the CMAC key in bits. 105 * Must be supported by the cipher. 106 * 107 * \return \c 0 on success. 108 * \return A cipher-specific error code on failure. 109 */ 110 int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx, 111 const unsigned char *key, size_t keybits ); 112 113 /** 114 * \brief This function feeds an input buffer into an ongoing CMAC 115 * computation. 116 * 117 * It is called between mbedtls_cipher_cmac_starts() or 118 * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish(). 119 * Can be called repeatedly. 120 * 121 * \param ctx The cipher context used for the CMAC operation. 122 * \param input The buffer holding the input data. 123 * \param ilen The length of the input data. 124 * 125 * \return \c 0 on success. 126 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA 127 * if parameter verification fails. 128 */ 129 int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx, 130 const unsigned char *input, size_t ilen ); 131 132 /** 133 * \brief This function finishes the CMAC operation, and writes 134 * the result to the output buffer. 135 * 136 * It is called after mbedtls_cipher_cmac_update(). 137 * It can be followed by mbedtls_cipher_cmac_reset() and 138 * mbedtls_cipher_cmac_update(), or mbedtls_cipher_free(). 139 * 140 * \param ctx The cipher context used for the CMAC operation. 141 * \param output The output buffer for the CMAC checksum result. 142 * 143 * \return \c 0 on success. 144 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA 145 * if parameter verification fails. 146 */ 147 int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx, 148 unsigned char *output ); 149 150 /** 151 * \brief This function prepares the authentication of another 152 * message with the same key as the previous CMAC 153 * operation. 154 * 155 * It is called after mbedtls_cipher_cmac_finish() 156 * and before mbedtls_cipher_cmac_update(). 157 * 158 * \param ctx The cipher context used for the CMAC operation. 159 * 160 * \return \c 0 on success. 161 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA 162 * if parameter verification fails. 163 */ 164 int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx ); 165 166 /** 167 * \brief This function calculates the full generic CMAC 168 * on the input buffer with the provided key. 169 * 170 * The function allocates the context, performs the 171 * calculation, and frees the context. 172 * 173 * The CMAC result is calculated as 174 * output = generic CMAC(cmac key, input buffer). 175 * 176 * \note When the CMAC implementation is supplied by an alternate 177 * implementation (through #MBEDTLS_CMAC_ALT), some ciphers 178 * may not be supported by that implementation, and thus 179 * return an error. Alternate implementations must support 180 * AES-128 and AES-256, and may support AES-192 and 3DES. 181 * 182 * \param cipher_info The cipher information. 183 * \param key The CMAC key. 184 * \param keylen The length of the CMAC key in bits. 185 * \param input The buffer holding the input data. 186 * \param ilen The length of the input data. 187 * \param output The buffer for the generic CMAC result. 188 * 189 * \return \c 0 on success. 190 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA 191 * if parameter verification fails. 192 */ 193 int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info, 194 const unsigned char *key, size_t keylen, 195 const unsigned char *input, size_t ilen, 196 unsigned char *output ); 197 198 #if defined(MBEDTLS_AES_C) 199 /** 200 * \brief This function implements the AES-CMAC-PRF-128 pseudorandom 201 * function, as defined in 202 * <em>RFC-4615: The Advanced Encryption Standard-Cipher-based 203 * Message Authentication Code-Pseudo-Random Function-128 204 * (AES-CMAC-PRF-128) Algorithm for the Internet Key 205 * Exchange Protocol (IKE).</em> 206 * 207 * \param key The key to use. 208 * \param key_len The key length in Bytes. 209 * \param input The buffer holding the input data. 210 * \param in_len The length of the input data in Bytes. 211 * \param output The buffer holding the generated 16 Bytes of 212 * pseudorandom output. 213 * 214 * \return \c 0 on success. 215 */ 216 int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len, 217 const unsigned char *input, size_t in_len, 218 unsigned char output[16] ); 219 #endif /* MBEDTLS_AES_C */ 220 221 #if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) ) 222 /** 223 * \brief The CMAC checkup routine. 224 * 225 * \note In case the CMAC routines are provided by an alternative 226 * implementation (i.e. #MBEDTLS_CMAC_ALT is defined), the 227 * checkup routine will succeed even if the implementation does 228 * not support the less widely used AES-192 or 3DES primitives. 229 * The self-test requires at least AES-128 and AES-256 to be 230 * supported by the underlying implementation. 231 * 232 * \return \c 0 on success. 233 * \return \c 1 on failure. 234 */ 235 int mbedtls_cmac_self_test( int verbose ); 236 #endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */ 237 238 #ifdef __cplusplus 239 } 240 #endif 241 242 #endif /* MBEDTLS_CMAC_H */ 243