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