mbedtls/private/cmac.h

0001 /**
0002  * \file cmac.h
0003  *
0004  * \brief This file contains CMAC definitions and functions.
0005  *
0006  * The Cipher-based Message Authentication Code (CMAC) Mode for
0007  * Authentication is defined in <em>RFC-4493: The AES-CMAC Algorithm</em>.
0008  * It is supported with AES and DES.
0009  */
0010 /*
0011  *  Copyright The Mbed TLS Contributors
0012  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0013  */
0014
0015 #ifndef MBEDTLS_CMAC_H
0016 #define MBEDTLS_CMAC_H
0017 #include "mbedtls/private_access.h"
0018
0019 #include "tf-psa-crypto/build_info.h"
0020
0021 #include "mbedtls/private/cipher.h"
0022
0023 #ifdef __cplusplus
0024 extern "C" {
0025 #endif
0026
0027 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)
0028 #define MBEDTLS_AES_BLOCK_SIZE          16
0029 #define MBEDTLS_DES3_BLOCK_SIZE         8
0030
0031 /* We don't support Camellia or ARIA in this module */
0032 #if defined(MBEDTLS_AES_C)
0033 #define MBEDTLS_CMAC_MAX_BLOCK_SIZE      16  /**< The longest block used by CMAC is that of AES. */
0034 #else
0035 #define MBEDTLS_CMAC_MAX_BLOCK_SIZE      8   /**< The longest block used by CMAC is that of 3DES. */
0036 #endif /* MBEDTLS_AES_C */
0037 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */
0038
0039 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
0040 /** The longest block supported by the cipher module.
0041  *
0042  * \deprecated
0043  * For the maximum block size of a cipher supported by the CMAC module,
0044  * use MBEDTLS_CMAC_MAX_BLOCK_SIZE.
0045  * For the maximum block size of a cipher supported by the cipher module,
0046  * use #MBEDTLS_MAX_BLOCK_LENGTH.
0047  */
0048 /* Before Mbed TLS 3.5, this was the maximum block size supported by the CMAC
0049  * module, so it didn't take Camellia or ARIA into account. Since the name
0050  * of the macro doesn't even convey "CMAC", this was misleading. Now the size
0051  * is sufficient for any cipher, but the name is defined in cmac.h for
0052  * backward compatibility. */
0053 #define MBEDTLS_CIPHER_BLKSIZE_MAX MBEDTLS_MAX_BLOCK_LENGTH
0054 #endif /* MBEDTLS_DEPRECATED_REMOVED */
0055
0056 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)
0057 /**
0058  * The CMAC context structure.
0059  */
0060 struct mbedtls_cmac_context_t {
0061     /** The internal state of the CMAC algorithm.  */
0062     unsigned char       MBEDTLS_PRIVATE(state)[MBEDTLS_CMAC_MAX_BLOCK_SIZE];
0063
0064     /** Unprocessed data - either data that was not block aligned and is still
0065      *  pending processing, or the final block. */
0066     unsigned char       MBEDTLS_PRIVATE(unprocessed_block)[MBEDTLS_CMAC_MAX_BLOCK_SIZE];
0067
0068     /** The length of data pending processing. */
0069     size_t              MBEDTLS_PRIVATE(unprocessed_len);
0070 };
0071
0072 /**
0073  * \brief               This function starts a new CMAC computation
0074  *                      by setting the CMAC key, and preparing to authenticate
0075  *                      the input data.
0076  *                      It must be called with an initialized cipher context.
0077  *
0078  *                      Once this function has completed, data can be supplied
0079  *                      to the CMAC computation by calling
0080  *                      mbedtls_cipher_cmac_update().
0081  *
0082  *                      To start a CMAC computation using the same key as a previous
0083  *                      CMAC computation, use mbedtls_cipher_cmac_finish().
0084  *
0085  * \param ctx           The cipher context used for the CMAC operation, initialized
0086  *                      as one of the following types: MBEDTLS_CIPHER_AES_128_ECB,
0087  *                      MBEDTLS_CIPHER_AES_192_ECB or MBEDTLS_CIPHER_AES_256_ECB.
0088  * \param key           The CMAC key.
0089  * \param keybits       The length of the CMAC key in bits.
0090  *                      Must be supported by the cipher.
0091  *
0092  * \return              \c 0 on success.
0093  * \return              A cipher-specific error code on failure.
0094  */
0095 int mbedtls_cipher_cmac_starts(mbedtls_cipher_context_t *ctx,
0096                                const unsigned char *key, size_t keybits);
0097
0098 /**
0099  * \brief               This function feeds an input buffer into an ongoing CMAC
0100  *                      computation.
0101  *
0102  *                      The CMAC computation must have previously been started
0103  *                      by calling mbedtls_cipher_cmac_starts() or
0104  *                      mbedtls_cipher_cmac_reset().
0105  *
0106  *                      Call this function as many times as needed to input the
0107  *                      data to be authenticated.
0108  *                      Once all of the required data has been input,
0109  *                      call mbedtls_cipher_cmac_finish() to obtain the result
0110  *                      of the CMAC operation.
0111  *
0112  * \param ctx           The cipher context used for the CMAC operation.
0113  * \param input         The buffer holding the input data.
0114  * \param ilen          The length of the input data.
0115  *
0116  * \return             \c 0 on success.
0117  * \return             #MBEDTLS_ERR_MD_BAD_INPUT_DATA
0118  *                     if parameter verification fails.
0119  */
0120 int mbedtls_cipher_cmac_update(mbedtls_cipher_context_t *ctx,
0121                                const unsigned char *input, size_t ilen);
0122
0123 /**
0124  * \brief               This function finishes an ongoing CMAC operation, and
0125  *                      writes the result to the output buffer.
0126  *
0127  *                      It should be followed either by
0128  *                      mbedtls_cipher_cmac_reset(), which starts another CMAC
0129  *                      operation with the same key, or mbedtls_cipher_free(),
0130  *                      which clears the cipher context.
0131  *
0132  * \param ctx           The cipher context used for the CMAC operation.
0133  * \param output        The output buffer for the CMAC checksum result.
0134  *
0135  * \return              \c 0 on success.
0136  * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA
0137  *                      if parameter verification fails.
0138  */
0139 int mbedtls_cipher_cmac_finish(mbedtls_cipher_context_t *ctx,
0140                                unsigned char *output);
0141
0142 /**
0143  * \brief               This function starts a new CMAC operation with the same
0144  *                      key as the previous one.
0145  *
0146  *                      It should be called after finishing the previous CMAC
0147  *                      operation with mbedtls_cipher_cmac_finish().
0148  *                      After calling this function,
0149  *                      call mbedtls_cipher_cmac_update() to supply the new
0150  *                      CMAC operation with data.
0151  *
0152  * \param ctx           The cipher context used for the CMAC operation.
0153  *
0154  * \return              \c 0 on success.
0155  * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA
0156  *                      if parameter verification fails.
0157  */
0158 int mbedtls_cipher_cmac_reset(mbedtls_cipher_context_t *ctx);
0159
0160 /**
0161  * \brief               This function calculates the full generic CMAC
0162  *                      on the input buffer with the provided key.
0163  *
0164  *                      The function allocates the context, performs the
0165  *                      calculation, and frees the context.
0166  *
0167  *                      The CMAC result is calculated as
0168  *                      output = generic CMAC(cmac key, input buffer).
0169  *
0170  * \param cipher_info   The cipher information.
0171  * \param key           The CMAC key.
0172  * \param keylen        The length of the CMAC key in bits.
0173  * \param input         The buffer holding the input data.
0174  * \param ilen          The length of the input data.
0175  * \param output        The buffer for the generic CMAC result.
0176  *
0177  * \return              \c 0 on success.
0178  * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA
0179  *                      if parameter verification fails.
0180  */
0181 int mbedtls_cipher_cmac(const mbedtls_cipher_info_t *cipher_info,
0182                         const unsigned char *key, size_t keylen,
0183                         const unsigned char *input, size_t ilen,
0184                         unsigned char *output);
0185
0186 #if defined(MBEDTLS_AES_C)
0187 /**
0188  * \brief           This function implements the AES-CMAC-PRF-128 pseudorandom
0189  *                  function, as defined in
0190  *                  <em>RFC-4615: The Advanced Encryption Standard-Cipher-based
0191  *                  Message Authentication Code-Pseudo-Random Function-128
0192  *                  (AES-CMAC-PRF-128) Algorithm for the Internet Key
0193  *                  Exchange Protocol (IKE).</em>
0194  *
0195  * \param key       The key to use.
0196  * \param key_len   The key length in Bytes.
0197  * \param input     The buffer holding the input data.
0198  * \param in_len    The length of the input data in Bytes.
0199  * \param output    The buffer holding the generated 16 Bytes of
0200  *                  pseudorandom output.
0201  *
0202  * \return          \c 0 on success.
0203  */
0204 int mbedtls_aes_cmac_prf_128(const unsigned char *key, size_t key_len,
0205                              const unsigned char *input, size_t in_len,
0206                              unsigned char output[16]);
0207 #endif /* MBEDTLS_AES_C */
0208
0209 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
0210 /**
0211  * \brief          The CMAC checkup routine.
0212  *
0213  *
0214  * \return         \c 0 on success.
0215  * \return         \c 1 on failure.
0216  */
0217 int mbedtls_cmac_self_test(int verbose);
0218 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C*/
0219
0220 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */
0221
0222 #ifdef __cplusplus
0223 }
0224 #endif
0225
0226 #endif /* MBEDTLS_CMAC_H */