blob: 97b86fc42b169bb9ec26859c46520940617dd300 [file] [log] [blame]
Robert Cragie3d23b1d2015-12-15 07:38:11 +00001/**
2 * \file cmac.h
3 *
Rose Zadik8c154932018-03-27 10:45:16 +01004 * \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>.
Gilles Peskine16bb83c2023-06-14 17:42:26 +02008 * It is supported with AES and DES.
Darryl Greena40a1012018-01-05 15:33:17 +00009 */
10/*
Bence Szépkúti1e148272020-08-07 13:07:28 +020011 * Copyright The Mbed TLS Contributors
Dave Rodgman16799db2023-11-02 19:47:20 +000012 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Robert Cragie3d23b1d2015-12-15 07:38:11 +000013 */
Rose Zadik380d05d2018-01-25 21:52:41 +000014
Robert Cragie3d23b1d2015-12-15 07:38:11 +000015#ifndef MBEDTLS_CMAC_H
16#define MBEDTLS_CMAC_H
Mateusz Starzyk846f0212021-05-19 19:44:07 +020017#include "mbedtls/private_access.h"
Robert Cragie3d23b1d2015-12-15 07:38:11 +000018
Bence Szépkútic662b362021-05-27 11:25:03 +020019#include "mbedtls/build_info.h"
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050020
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010021#include "mbedtls/cipher.h"
Robert Cragie3d23b1d2015-12-15 07:38:11 +000022
23#ifdef __cplusplus
24extern "C" {
25#endif
26
Simon Butcher69283e52016-10-06 12:49:58 +010027#define MBEDTLS_AES_BLOCK_SIZE 16
28#define MBEDTLS_DES3_BLOCK_SIZE 8
29
Gilles Peskine16bb83c2023-06-14 17:42:26 +020030/* We don't support Camellia or ARIA in this module */
Simon Butcher327398a2016-10-05 14:09:11 +010031#if defined(MBEDTLS_AES_C)
Gilles Peskine7282a9e2023-06-14 17:49:02 +020032#define MBEDTLS_CMAC_MAX_BLOCK_SIZE 16 /**< The longest block used by CMAC is that of AES. */
Simon Butcher327398a2016-10-05 14:09:11 +010033#else
Gilles Peskine7282a9e2023-06-14 17:49:02 +020034#define MBEDTLS_CMAC_MAX_BLOCK_SIZE 8 /**< The longest block used by CMAC is that of 3DES. */
Simon Butcher327398a2016-10-05 14:09:11 +010035#endif
36
Gilles Peskinec453e2e2023-06-14 17:54:38 +020037#if !defined(MBEDTLS_DEPRECATED_REMOVED)
Gilles Peskine7282a9e2023-06-14 17:49:02 +020038/** The longest block supported by the cipher module.
39 *
40 * \deprecated
41 * For the maximum block size of a cipher supported by the CMAC module,
42 * use #MBEDTLS_CMAC_MAX_BLOCK_SIZE.
43 * For the maximum block size of a cipher supported by the cipher module,
44 * use #MBEDTLS_MAX_BLOCK_LENGTH.
45 */
46/* Before Mbed TLS 3.5, this was the maximum block size supported by the CMAC
47 * module, so it didn't take Camellia or ARIA into account. Since the name
48 * of the macro doesn't even convey "CMAC", this was misleading. Now the size
49 * is sufficient for any cipher, but the name is defined in cmac.h for
50 * backward compatibility. */
51#define MBEDTLS_CIPHER_BLKSIZE_MAX MBEDTLS_MAX_BLOCK_LENGTH
Gilles Peskinec453e2e2023-06-14 17:54:38 +020052#endif /* MBEDTLS_DEPRECATED_REMOVED */
Gilles Peskine7282a9e2023-06-14 17:49:02 +020053
Steven Cooreman63342772017-04-04 11:47:16 +020054#if !defined(MBEDTLS_CMAC_ALT)
55
Robert Cragie3d23b1d2015-12-15 07:38:11 +000056/**
Rose Zadik380d05d2018-01-25 21:52:41 +000057 * The CMAC context structure.
Robert Cragie3d23b1d2015-12-15 07:38:11 +000058 */
Gilles Peskine449bd832023-01-11 14:50:10 +010059struct mbedtls_cmac_context_t {
Rose Zadik380d05d2018-01-25 21:52:41 +000060 /** The internal state of the CMAC algorithm. */
Gilles Peskine9e930e22023-06-14 17:52:54 +020061 unsigned char MBEDTLS_PRIVATE(state)[MBEDTLS_CMAC_MAX_BLOCK_SIZE];
Simon Butcher327398a2016-10-05 14:09:11 +010062
Andres AGa592dcc2016-10-06 15:23:39 +010063 /** Unprocessed data - either data that was not block aligned and is still
Rose Zadik380d05d2018-01-25 21:52:41 +000064 * pending processing, or the final block. */
Gilles Peskine9e930e22023-06-14 17:52:54 +020065 unsigned char MBEDTLS_PRIVATE(unprocessed_block)[MBEDTLS_CMAC_MAX_BLOCK_SIZE];
Simon Butcher327398a2016-10-05 14:09:11 +010066
Rose Zadik380d05d2018-01-25 21:52:41 +000067 /** The length of data pending processing. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +020068 size_t MBEDTLS_PRIVATE(unprocessed_len);
Simon Butcher8308a442016-10-05 15:12:59 +010069};
Robert Cragie3d23b1d2015-12-15 07:38:11 +000070
Ron Eldor4e6d55d2018-02-07 16:36:15 +020071#else /* !MBEDTLS_CMAC_ALT */
72#include "cmac_alt.h"
73#endif /* !MBEDTLS_CMAC_ALT */
74
Robert Cragie3d23b1d2015-12-15 07:38:11 +000075/**
David Horstmann3d5dfa52021-12-06 18:58:02 +000076 * \brief This function starts a new CMAC computation
77 * by setting the CMAC key, and preparing to authenticate
Rose Zadik380d05d2018-01-25 21:52:41 +000078 * the input data.
David Horstmann3d5dfa52021-12-06 18:58:02 +000079 * It must be called with an initialized cipher context.
80 *
81 * Once this function has completed, data can be supplied
82 * to the CMAC computation by calling
83 * mbedtls_cipher_cmac_update().
84 *
85 * To start a CMAC computation using the same key as a previous
86 * CMAC computation, use mbedtls_cipher_cmac_finish().
Robert Cragie3d23b1d2015-12-15 07:38:11 +000087 *
Steven Cooremanc338cef2021-04-26 11:24:44 +020088 * \note When the CMAC implementation is supplied by an alternate
89 * implementation (through #MBEDTLS_CMAC_ALT), some ciphers
90 * may not be supported by that implementation, and thus
91 * return an error. Alternate implementations must support
92 * AES-128 and AES-256, and may support AES-192 and 3DES.
93 *
Rose Zadik380d05d2018-01-25 21:52:41 +000094 * \param ctx The cipher context used for the CMAC operation, initialized
Rose Zadik8c154932018-03-27 10:45:16 +010095 * as one of the following types: MBEDTLS_CIPHER_AES_128_ECB,
96 * MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_256_ECB,
97 * or MBEDTLS_CIPHER_DES_EDE3_ECB.
Rose Zadik380d05d2018-01-25 21:52:41 +000098 * \param key The CMAC key.
99 * \param keybits The length of the CMAC key in bits.
100 * Must be supported by the cipher.
Simon Butcher327398a2016-10-05 14:09:11 +0100101 *
Rose Zadikc138bb72018-04-16 11:11:25 +0100102 * \return \c 0 on success.
103 * \return A cipher-specific error code on failure.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000104 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100105int mbedtls_cipher_cmac_starts(mbedtls_cipher_context_t *ctx,
106 const unsigned char *key, size_t keybits);
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000107
108/**
Rose Zadik380d05d2018-01-25 21:52:41 +0000109 * \brief This function feeds an input buffer into an ongoing CMAC
110 * computation.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000111 *
David Horstmann3d5dfa52021-12-06 18:58:02 +0000112 * The CMAC computation must have previously been started
113 * by calling mbedtls_cipher_cmac_starts() or
114 * mbedtls_cipher_cmac_reset().
115 *
116 * Call this function as many times as needed to input the
117 * data to be authenticated.
118 * Once all of the required data has been input,
119 * call mbedtls_cipher_cmac_finish() to obtain the result
120 * of the CMAC operation.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000121 *
Rose Zadik380d05d2018-01-25 21:52:41 +0000122 * \param ctx The cipher context used for the CMAC operation.
123 * \param input The buffer holding the input data.
124 * \param ilen The length of the input data.
125 *
Rose Zadikc138bb72018-04-16 11:11:25 +0100126 * \return \c 0 on success.
127 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
Rose Zadik8c154932018-03-27 10:45:16 +0100128 * if parameter verification fails.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000129 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100130int mbedtls_cipher_cmac_update(mbedtls_cipher_context_t *ctx,
131 const unsigned char *input, size_t ilen);
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000132
133/**
David Horstmann3d5dfa52021-12-06 18:58:02 +0000134 * \brief This function finishes an ongoing CMAC operation, and
135 * writes the result to the output buffer.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000136 *
David Horstmann3d5dfa52021-12-06 18:58:02 +0000137 * It should be followed either by
138 * mbedtls_cipher_cmac_reset(), which starts another CMAC
139 * operation with the same key, or mbedtls_cipher_free(),
140 * which clears the cipher context.
Simon Butcher327398a2016-10-05 14:09:11 +0100141 *
Rose Zadik380d05d2018-01-25 21:52:41 +0000142 * \param ctx The cipher context used for the CMAC operation.
143 * \param output The output buffer for the CMAC checksum result.
144 *
Rose Zadikc138bb72018-04-16 11:11:25 +0100145 * \return \c 0 on success.
146 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
Rose Zadik380d05d2018-01-25 21:52:41 +0000147 * if parameter verification fails.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000148 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100149int mbedtls_cipher_cmac_finish(mbedtls_cipher_context_t *ctx,
150 unsigned char *output);
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000151
152/**
David Horstmann3d5dfa52021-12-06 18:58:02 +0000153 * \brief This function starts a new CMAC operation with the same
154 * key as the previous one.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000155 *
David Horstmann3d5dfa52021-12-06 18:58:02 +0000156 * It should be called after finishing the previous CMAC
157 * operation with mbedtls_cipher_cmac_finish().
158 * After calling this function,
159 * call mbedtls_cipher_cmac_update() to supply the new
160 * CMAC operation with data.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000161 *
Rose Zadik380d05d2018-01-25 21:52:41 +0000162 * \param ctx The cipher context used for the CMAC operation.
163 *
Rose Zadikc138bb72018-04-16 11:11:25 +0100164 * \return \c 0 on success.
165 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
Rose Zadik380d05d2018-01-25 21:52:41 +0000166 * if parameter verification fails.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000167 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100168int mbedtls_cipher_cmac_reset(mbedtls_cipher_context_t *ctx);
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000169
170/**
Rose Zadik380d05d2018-01-25 21:52:41 +0000171 * \brief This function calculates the full generic CMAC
172 * on the input buffer with the provided key.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000173 *
Rose Zadik380d05d2018-01-25 21:52:41 +0000174 * The function allocates the context, performs the
175 * calculation, and frees the context.
Simon Butcher327398a2016-10-05 14:09:11 +0100176 *
Rose Zadik380d05d2018-01-25 21:52:41 +0000177 * The CMAC result is calculated as
178 * output = generic CMAC(cmac key, input buffer).
179 *
Steven Cooremanc338cef2021-04-26 11:24:44 +0200180 * \note When the CMAC implementation is supplied by an alternate
181 * implementation (through #MBEDTLS_CMAC_ALT), some ciphers
182 * may not be supported by that implementation, and thus
183 * return an error. Alternate implementations must support
184 * AES-128 and AES-256, and may support AES-192 and 3DES.
Rose Zadik380d05d2018-01-25 21:52:41 +0000185 *
186 * \param cipher_info The cipher information.
187 * \param key The CMAC key.
188 * \param keylen The length of the CMAC key in bits.
189 * \param input The buffer holding the input data.
190 * \param ilen The length of the input data.
191 * \param output The buffer for the generic CMAC result.
192 *
Rose Zadikc138bb72018-04-16 11:11:25 +0100193 * \return \c 0 on success.
194 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA
Rose Zadik380d05d2018-01-25 21:52:41 +0000195 * if parameter verification fails.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000196 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100197int mbedtls_cipher_cmac(const mbedtls_cipher_info_t *cipher_info,
198 const unsigned char *key, size_t keylen,
199 const unsigned char *input, size_t ilen,
200 unsigned char *output);
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000201
Simon Butcher69283e52016-10-06 12:49:58 +0100202#if defined(MBEDTLS_AES_C)
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000203/**
Rose Zadik380d05d2018-01-25 21:52:41 +0000204 * \brief This function implements the AES-CMAC-PRF-128 pseudorandom
205 * function, as defined in
206 * <em>RFC-4615: The Advanced Encryption Standard-Cipher-based
207 * Message Authentication Code-Pseudo-Random Function-128
208 * (AES-CMAC-PRF-128) Algorithm for the Internet Key
209 * Exchange Protocol (IKE).</em>
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000210 *
Rose Zadik380d05d2018-01-25 21:52:41 +0000211 * \param key The key to use.
212 * \param key_len The key length in Bytes.
213 * \param input The buffer holding the input data.
214 * \param in_len The length of the input data in Bytes.
215 * \param output The buffer holding the generated 16 Bytes of
216 * pseudorandom output.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000217 *
Rose Zadik380d05d2018-01-25 21:52:41 +0000218 * \return \c 0 on success.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000219 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100220int mbedtls_aes_cmac_prf_128(const unsigned char *key, size_t key_len,
221 const unsigned char *input, size_t in_len,
222 unsigned char output[16]);
Brian Murrayb439d452016-05-19 16:02:42 -0700223#endif /* MBEDTLS_AES_C */
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000224
Gilles Peskine449bd832023-01-11 14:50:10 +0100225#if defined(MBEDTLS_SELF_TEST) && (defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C))
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000226/**
Rose Zadik380d05d2018-01-25 21:52:41 +0000227 * \brief The CMAC checkup routine.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000228 *
Steven Cooreman894b9c42021-04-23 08:19:43 +0200229 * \note In case the CMAC routines are provided by an alternative
230 * implementation (i.e. #MBEDTLS_CMAC_ALT is defined), the
231 * checkup routine will succeed even if the implementation does
232 * not support the less widely used AES-192 or 3DES primitives.
233 * The self-test requires at least AES-128 and AES-256 to be
234 * supported by the underlying implementation.
235 *
Rose Zadik8c154932018-03-27 10:45:16 +0100236 * \return \c 0 on success.
237 * \return \c 1 on failure.
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000238 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100239int mbedtls_cmac_self_test(int verbose);
Brian Murrayb439d452016-05-19 16:02:42 -0700240#endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */
Robert Cragie3d23b1d2015-12-15 07:38:11 +0000241
242#ifdef __cplusplus
243}
244#endif
245
246#endif /* MBEDTLS_CMAC_H */