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