1 /** 2 * \file cmac.h 3 * 4 * \brief The Cipher-based Message Authentication Code (CMAC) Mode for 5 * Authentication. 6 */ 7 /* 8 * Copyright (C) 2015-2018, Arm Limited (or its affiliates), All Rights Reserved 9 * SPDX-License-Identifier: GPL-2.0 10 * 11 * This program is free software; you can redistribute it and/or modify 12 * it under the terms of the GNU General Public License as published by 13 * the Free Software Foundation; either version 2 of the License, or 14 * (at your option) any later version. 15 * 16 * This program is distributed in the hope that it will be useful, 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 19 * GNU General Public License for more details. 20 * 21 * You should have received a copy of the GNU General Public License along 22 * with this program; if not, write to the Free Software Foundation, Inc., 23 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 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 #define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A /**< CMAC hardware accelerator failed. */ 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 /** 73 * \brief This function sets the CMAC key, and prepares to authenticate 74 * the input data. 75 * Must be called with an initialized cipher context. 76 * 77 * \param ctx The cipher context used for the CMAC operation, initialized 78 * as one of the following types:<ul> 79 * <li>MBEDTLS_CIPHER_AES_128_ECB</li> 80 * <li>MBEDTLS_CIPHER_AES_192_ECB</li> 81 * <li>MBEDTLS_CIPHER_AES_256_ECB</li> 82 * <li>MBEDTLS_CIPHER_DES_EDE3_ECB</li></ul> 83 * \param key The CMAC key. 84 * \param keybits The length of the CMAC key in bits. 85 * Must be supported by the cipher. 86 * 87 * \return \c 0 on success, or a cipher-specific error code. 88 */ 89 int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx, 90 const unsigned char *key, size_t keybits ); 91 92 /** 93 * \brief This function feeds an input buffer into an ongoing CMAC 94 * computation. 95 * 96 * It is called between mbedtls_cipher_cmac_starts() or 97 * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish(). 98 * Can be called repeatedly. 99 * 100 * \param ctx The cipher context used for the CMAC operation. 101 * \param input The buffer holding the input data. 102 * \param ilen The length of the input data. 103 * 104 * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA 105 * if parameter verification fails. 106 */ 107 int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx, 108 const unsigned char *input, size_t ilen ); 109 110 /** 111 * \brief This function finishes the CMAC operation, and writes 112 * the result to the output buffer. 113 * 114 * It is called after mbedtls_cipher_cmac_update(). 115 * It can be followed by mbedtls_cipher_cmac_reset() and 116 * mbedtls_cipher_cmac_update(), or mbedtls_cipher_free(). 117 * 118 * \param ctx The cipher context used for the CMAC operation. 119 * \param output The output buffer for the CMAC checksum result. 120 * 121 * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA 122 * if parameter verification fails. 123 */ 124 int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx, 125 unsigned char *output ); 126 127 /** 128 * \brief This function prepares the authentication of another 129 * message with the same key as the previous CMAC 130 * operation. 131 * 132 * It is called after mbedtls_cipher_cmac_finish() 133 * and before mbedtls_cipher_cmac_update(). 134 * 135 * \param ctx The cipher context used for the CMAC operation. 136 * 137 * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA 138 * if parameter verification fails. 139 */ 140 int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx ); 141 142 /** 143 * \brief This function calculates the full generic CMAC 144 * on the input buffer with the provided key. 145 * 146 * The function allocates the context, performs the 147 * calculation, and frees the context. 148 * 149 * The CMAC result is calculated as 150 * output = generic CMAC(cmac key, input buffer). 151 * 152 * 153 * \param cipher_info The cipher information. 154 * \param key The CMAC key. 155 * \param keylen The length of the CMAC key in bits. 156 * \param input The buffer holding the input data. 157 * \param ilen The length of the input data. 158 * \param output The buffer for the generic CMAC result. 159 * 160 * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA 161 * if parameter verification fails. 162 */ 163 int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info, 164 const unsigned char *key, size_t keylen, 165 const unsigned char *input, size_t ilen, 166 unsigned char *output ); 167 168 #if defined(MBEDTLS_AES_C) 169 /** 170 * \brief This function implements the AES-CMAC-PRF-128 pseudorandom 171 * function, as defined in 172 * <em>RFC-4615: The Advanced Encryption Standard-Cipher-based 173 * Message Authentication Code-Pseudo-Random Function-128 174 * (AES-CMAC-PRF-128) Algorithm for the Internet Key 175 * Exchange Protocol (IKE).</em> 176 * 177 * \param key The key to use. 178 * \param key_len The key length in Bytes. 179 * \param input The buffer holding the input data. 180 * \param in_len The length of the input data in Bytes. 181 * \param output The buffer holding the generated 16 Bytes of 182 * pseudorandom output. 183 * 184 * \return \c 0 on success. 185 */ 186 int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len, 187 const unsigned char *input, size_t in_len, 188 unsigned char output[16] ); 189 #endif /* MBEDTLS_AES_C */ 190 191 #ifdef __cplusplus 192 } 193 #endif 194 195 #else /* !MBEDTLS_CMAC_ALT */ 196 #include "cmac_alt.h" 197 #endif /* !MBEDTLS_CMAC_ALT */ 198 199 #ifdef __cplusplus 200 extern "C" { 201 #endif 202 203 #if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) ) 204 /** 205 * \brief The CMAC checkup routine. 206 * 207 * \return \c 0 on success, or \c 1 on failure. 208 */ 209 int mbedtls_cmac_self_test( int verbose ); 210 #endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */ 211 212 #ifdef __cplusplus 213 } 214 #endif 215 216 #endif /* MBEDTLS_CMAC_H */ 217