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