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