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