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