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 * This file is provided under the Apache License 2.0, or the 14 * GNU General Public License v2.0 or later. 15 * 16 * ********** 17 * Apache License 2.0: 18 * 19 * Licensed under the Apache License, Version 2.0 (the "License"); you may 20 * not use this file except in compliance with the License. 21 * You may obtain a copy of the License at 22 * 23 * http://www.apache.org/licenses/LICENSE-2.0 24 * 25 * Unless required by applicable law or agreed to in writing, software 26 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 27 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 28 * See the License for the specific language governing permissions and 29 * limitations under the License. 30 * 31 * ********** 32 * 33 * ********** 34 * GNU General Public License v2.0 or later: 35 * 36 * This program is free software; you can redistribute it and/or modify 37 * it under the terms of the GNU General Public License as published by 38 * the Free Software Foundation; either version 2 of the License, or 39 * (at your option) any later version. 40 * 41 * This program is distributed in the hope that it will be useful, 42 * but WITHOUT ANY WARRANTY; without even the implied warranty of 43 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 44 * GNU General Public License for more details. 45 * 46 * You should have received a copy of the GNU General Public License along 47 * with this program; if not, write to the Free Software Foundation, Inc., 48 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 49 * 50 * ********** 51 */ 52 53 #ifndef MBEDTLS_CMAC_H 54 #define MBEDTLS_CMAC_H 55 56 #if !defined(MBEDTLS_CONFIG_FILE) 57 #include "config.h" 58 #else 59 #include MBEDTLS_CONFIG_FILE 60 #endif 61 62 #include "cipher.h" 63 64 #ifdef __cplusplus 65 extern "C" { 66 #endif 67 68 /* MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED is deprecated and should not be used. */ 69 #define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A /**< CMAC hardware accelerator failed. */ 70 71 #define MBEDTLS_AES_BLOCK_SIZE 16 72 #define MBEDTLS_DES3_BLOCK_SIZE 8 73 74 #if defined(MBEDTLS_AES_C) 75 #define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /**< The longest block used by CMAC is that of AES. */ 76 #else 77 #define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /**< The longest block used by CMAC is that of 3DES. */ 78 #endif 79 80 #if !defined(MBEDTLS_CMAC_ALT) 81 82 /** 83 * The CMAC context structure. 84 */ 85 struct mbedtls_cmac_context_t 86 { 87 /** The internal state of the CMAC algorithm. */ 88 unsigned char state[MBEDTLS_CIPHER_BLKSIZE_MAX]; 89 90 /** Unprocessed data - either data that was not block aligned and is still 91 * pending processing, or the final block. */ 92 unsigned char unprocessed_block[MBEDTLS_CIPHER_BLKSIZE_MAX]; 93 94 /** The length of data pending processing. */ 95 size_t unprocessed_len; 96 }; 97 98 #else /* !MBEDTLS_CMAC_ALT */ 99 #include "cmac_alt.h" 100 #endif /* !MBEDTLS_CMAC_ALT */ 101 102 /** 103 * \brief This function sets the CMAC key, and prepares to authenticate 104 * the input data. 105 * Must be called with an initialized cipher context. 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 * It is called between mbedtls_cipher_cmac_starts() or 126 * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish(). 127 * Can be called repeatedly. 128 * 129 * \param ctx The cipher context used for the CMAC operation. 130 * \param input The buffer holding the input data. 131 * \param ilen The length of the input data. 132 * 133 * \return \c 0 on success. 134 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA 135 * if parameter verification fails. 136 */ 137 int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx, 138 const unsigned char *input, size_t ilen ); 139 140 /** 141 * \brief This function finishes the CMAC operation, and writes 142 * the result to the output buffer. 143 * 144 * It is called after mbedtls_cipher_cmac_update(). 145 * It can be followed by mbedtls_cipher_cmac_reset() and 146 * mbedtls_cipher_cmac_update(), or mbedtls_cipher_free(). 147 * 148 * \param ctx The cipher context used for the CMAC operation. 149 * \param output The output buffer for the CMAC checksum result. 150 * 151 * \return \c 0 on success. 152 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA 153 * if parameter verification fails. 154 */ 155 int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx, 156 unsigned char *output ); 157 158 /** 159 * \brief This function prepares the authentication of another 160 * message with the same key as the previous CMAC 161 * operation. 162 * 163 * It is called after mbedtls_cipher_cmac_finish() 164 * and before mbedtls_cipher_cmac_update(). 165 * 166 * \param ctx The cipher context used for the CMAC operation. 167 * 168 * \return \c 0 on success. 169 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA 170 * if parameter verification fails. 171 */ 172 int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx ); 173 174 /** 175 * \brief This function calculates the full generic CMAC 176 * on the input buffer with the provided key. 177 * 178 * The function allocates the context, performs the 179 * calculation, and frees the context. 180 * 181 * The CMAC result is calculated as 182 * output = generic CMAC(cmac key, input buffer). 183 * 184 * 185 * \param cipher_info The cipher information. 186 * \param key The CMAC key. 187 * \param keylen The length of the CMAC key in bits. 188 * \param input The buffer holding the input data. 189 * \param ilen The length of the input data. 190 * \param output The buffer for the generic CMAC result. 191 * 192 * \return \c 0 on success. 193 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA 194 * if parameter verification fails. 195 */ 196 int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info, 197 const unsigned char *key, size_t keylen, 198 const unsigned char *input, size_t ilen, 199 unsigned char *output ); 200 201 #if defined(MBEDTLS_AES_C) 202 /** 203 * \brief This function implements the AES-CMAC-PRF-128 pseudorandom 204 * function, as defined in 205 * <em>RFC-4615: The Advanced Encryption Standard-Cipher-based 206 * Message Authentication Code-Pseudo-Random Function-128 207 * (AES-CMAC-PRF-128) Algorithm for the Internet Key 208 * Exchange Protocol (IKE).</em> 209 * 210 * \param key The key to use. 211 * \param key_len The key length in Bytes. 212 * \param input The buffer holding the input data. 213 * \param in_len The length of the input data in Bytes. 214 * \param output The buffer holding the generated 16 Bytes of 215 * pseudorandom output. 216 * 217 * \return \c 0 on success. 218 */ 219 int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len, 220 const unsigned char *input, size_t in_len, 221 unsigned char output[16] ); 222 #endif /* MBEDTLS_AES_C */ 223 224 #if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) ) 225 /** 226 * \brief The CMAC checkup routine. 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