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