common/mbedtls/cmac.h

   1 /**
   2  * \file cmac.h
   3  *
   4  * \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>.
   8  */
   9 /*
  10  *  Copyright The Mbed TLS Contributors
  11  *  SPDX-License-Identifier: Apache-2.0
  12  *
  13  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  14  *  not use this file except in compliance with the License.
  15  *  You may obtain a copy of the License at
  16  *
  17  *  http://www.apache.org/licenses/LICENSE-2.0
  18  *
  19  *  Unless required by applicable law or agreed to in writing, software
  20  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  21  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  22  *  See the License for the specific language governing permissions and
  23  *  limitations under the License.
  24  */
  25
  26 #ifndef MBEDTLS_CMAC_H
  27 #define MBEDTLS_CMAC_H
  28
  29 #if !defined(MBEDTLS_CONFIG_FILE)
  30 #include "mbedtls/config.h"
  31 #else
  32 #include MBEDTLS_CONFIG_FILE
  33 #endif
  34
  35 #include "mbedtls/cipher.h"
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /* MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED is deprecated and should not be used. */
  42 #define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A  /**< CMAC hardware accelerator failed. */
  43
  44 #define MBEDTLS_AES_BLOCK_SIZE          16
  45 #define MBEDTLS_DES3_BLOCK_SIZE         8
  46
  47 #if defined(MBEDTLS_AES_C)
  48 #define MBEDTLS_CIPHER_BLKSIZE_MAX      16  /**< The longest block used by CMAC is that of AES. */
  49 #else
  50 #define MBEDTLS_CIPHER_BLKSIZE_MAX      8   /**< The longest block used by CMAC is that of 3DES. */
  51 #endif
  52
  53 #if !defined(MBEDTLS_CMAC_ALT)
  54
  55 /**
  56  * The CMAC context structure.
  57  */
  58 struct mbedtls_cmac_context_t {
  59     /** The internal state of the CMAC algorithm.  */
  60     unsigned char       state[MBEDTLS_CIPHER_BLKSIZE_MAX];
  61
  62     /** Unprocessed data - either data that was not block aligned and is still
  63      *  pending processing, or the final block. */
  64     unsigned char       unprocessed_block[MBEDTLS_CIPHER_BLKSIZE_MAX];
  65
  66     /** The length of data pending processing. */
  67     size_t              unprocessed_len;
  68 };
  69
  70 #else  /* !MBEDTLS_CMAC_ALT */
  71 #include "cmac_alt.h"
  72 #endif /* !MBEDTLS_CMAC_ALT */
  73
  74 /**
  75  * \brief               This function sets the CMAC key, and prepares to authenticate
  76  *                      the input data.
  77  *                      Must be called with an initialized cipher context.
  78  *
  79  * \param ctx           The cipher context used for the CMAC operation, initialized
  80  *                      as one of the following types: MBEDTLS_CIPHER_AES_128_ECB,
  81  *                      MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_256_ECB,
  82  *                      or MBEDTLS_CIPHER_DES_EDE3_ECB.
  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.
  88  * \return              A cipher-specific error code on failure.
  89  */
  90 int mbedtls_cipher_cmac_starts(mbedtls_cipher_context_t *ctx,
  91                                const unsigned char *key, size_t keybits);
  92
  93 /**
  94  * \brief               This function feeds an input buffer into an ongoing CMAC
  95  *                      computation.
  96  *
  97  *                      It is called between mbedtls_cipher_cmac_starts() or
  98  *                      mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish().
  99  *                      Can be called repeatedly.
 100  *
 101  * \param ctx           The cipher context used for the CMAC operation.
 102  * \param input         The buffer holding the input data.
 103  * \param ilen          The length of the input data.
 104  *
 105  * \return             \c 0 on success.
 106  * \return             #MBEDTLS_ERR_MD_BAD_INPUT_DATA
 107  *                     if parameter verification fails.
 108  */
 109 int mbedtls_cipher_cmac_update(mbedtls_cipher_context_t *ctx,
 110                                const unsigned char *input, size_t ilen);
 111
 112 /**
 113  * \brief               This function finishes the CMAC operation, and writes
 114  *                      the result to the output buffer.
 115  *
 116  *                      It is called after mbedtls_cipher_cmac_update().
 117  *                      It can be followed by mbedtls_cipher_cmac_reset() and
 118  *                      mbedtls_cipher_cmac_update(), or mbedtls_cipher_free().
 119  *
 120  * \param ctx           The cipher context used for the CMAC operation.
 121  * \param output        The output buffer for the CMAC checksum result.
 122  *
 123  * \return              \c 0 on success.
 124  * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA
 125  *                      if parameter verification fails.
 126  */
 127 int mbedtls_cipher_cmac_finish(mbedtls_cipher_context_t *ctx,
 128                                unsigned char *output);
 129
 130 /**
 131  * \brief               This function prepares the authentication of another
 132  *                      message with the same key as the previous CMAC
 133  *                      operation.
 134  *
 135  *                      It is called after mbedtls_cipher_cmac_finish()
 136  *                      and before mbedtls_cipher_cmac_update().
 137  *
 138  * \param ctx           The cipher context used for the CMAC operation.
 139  *
 140  * \return              \c 0 on success.
 141  * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA
 142  *                      if parameter verification fails.
 143  */
 144 int mbedtls_cipher_cmac_reset(mbedtls_cipher_context_t *ctx);
 145
 146 /**
 147  * \brief               This function calculates the full generic CMAC
 148  *                      on the input buffer with the provided key.
 149  *
 150  *                      The function allocates the context, performs the
 151  *                      calculation, and frees the context.
 152  *
 153  *                      The CMAC result is calculated as
 154  *                      output = generic CMAC(cmac key, input buffer).
 155  *
 156  *
 157  * \param cipher_info   The cipher information.
 158  * \param key           The CMAC key.
 159  * \param keylen        The length of the CMAC key in bits.
 160  * \param input         The buffer holding the input data.
 161  * \param ilen          The length of the input data.
 162  * \param output        The buffer for the generic CMAC result.
 163  *
 164  * \return              \c 0 on success.
 165  * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA
 166  *                      if parameter verification fails.
 167  */
 168 int mbedtls_cipher_cmac(const mbedtls_cipher_info_t *cipher_info,
 169                         const unsigned char *key, size_t keylen,
 170                         const unsigned char *input, size_t ilen,
 171                         unsigned char *output);
 172
 173 #if defined(MBEDTLS_AES_C)
 174 /**
 175  * \brief           This function implements the AES-CMAC-PRF-128 pseudorandom
 176  *                  function, as defined in
 177  *                  <em>RFC-4615: The Advanced Encryption Standard-Cipher-based
 178  *                  Message Authentication Code-Pseudo-Random Function-128
 179  *                  (AES-CMAC-PRF-128) Algorithm for the Internet Key
 180  *                  Exchange Protocol (IKE).</em>
 181  *
 182  * \param key       The key to use.
 183  * \param key_len   The key length in Bytes.
 184  * \param input     The buffer holding the input data.
 185  * \param in_len    The length of the input data in Bytes.
 186  * \param output    The buffer holding the generated 16 Bytes of
 187  *                  pseudorandom output.
 188  *
 189  * \return          \c 0 on success.
 190  */
 191 int mbedtls_aes_cmac_prf_128(const unsigned char *key, size_t key_len,
 192                              const unsigned char *input, size_t in_len,
 193                              unsigned char output[16]);
 194 #endif /* MBEDTLS_AES_C */
 195
 196 #if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) )
 197 /**
 198  * \brief          The CMAC checkup routine.
 199  *
 200  * \return         \c 0 on success.
 201  * \return         \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 */