cmac.h

00001 /**
00002  * \file cmac.h
00003  *
00004  * \brief The Cipher-based Message Authentication Code (CMAC) Mode for
00005  *        Authentication.
00006  */
00007 /*
00008  *  Copyright (C) 2015-2018, Arm Limited (or its affiliates), All Rights Reserved
00009  *  SPDX-License-Identifier: Apache-2.0
00010  *
00011  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00012  *  not use this file except in compliance with the License.
00013  *  You may obtain a copy of the License at
00014  *
00015  *  http://www.apache.org/licenses/LICENSE-2.0
00016  *
00017  *  Unless required by applicable law or agreed to in writing, software
00018  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00019  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00020  *  See the License for the specific language governing permissions and
00021  *  limitations under the License.
00022  *
00023  *  This file is part of Mbed TLS (https://tls.mbed.org)
00024  */
00025 
00026 #ifndef MBEDTLS_CMAC_H
00027 #define MBEDTLS_CMAC_H
00028 
00029 #include "mbedtls/cipher.h"
00030 
00031 #ifdef __cplusplus
00032 extern "C" {
00033 #endif
00034 
00035 #define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A  /**< CMAC hardware accelerator failed. */
00036 
00037 #define MBEDTLS_AES_BLOCK_SIZE          16
00038 #define MBEDTLS_DES3_BLOCK_SIZE         8
00039 
00040 #if defined(MBEDTLS_AES_C)
00041 #define MBEDTLS_CIPHER_BLKSIZE_MAX      16  /* The longest block used by CMAC is that of AES. */
00042 #else
00043 #define MBEDTLS_CIPHER_BLKSIZE_MAX      8   /* The longest block used by CMAC is that of 3DES. */
00044 #endif
00045 
00046 #if !defined(MBEDTLS_CMAC_ALT)
00047 
00048 /**
00049  * The CMAC context structure.
00050  */
00051 struct mbedtls_cmac_context_t
00052 {
00053     /** The internal state of the CMAC algorithm.  */
00054     unsigned char       state[MBEDTLS_CIPHER_BLKSIZE_MAX];
00055 
00056     /** Unprocessed data - either data that was not block aligned and is still
00057      *  pending processing, or the final block. */
00058     unsigned char       unprocessed_block[MBEDTLS_CIPHER_BLKSIZE_MAX];
00059 
00060     /** The length of data pending processing. */
00061     size_t              unprocessed_len;
00062 };
00063 
00064 /**
00065  * \brief               This function sets the CMAC key, and prepares to authenticate
00066  *                      the input data.
00067  *                      Must be called with an initialized cipher context.
00068  *
00069  * \param ctx           The cipher context used for the CMAC operation, initialized
00070  *                      as one of the following types:<ul>
00071  *                      <li>MBEDTLS_CIPHER_AES_128_ECB</li>
00072  *                      <li>MBEDTLS_CIPHER_AES_192_ECB</li>
00073  *                      <li>MBEDTLS_CIPHER_AES_256_ECB</li>
00074  *                      <li>MBEDTLS_CIPHER_DES_EDE3_ECB</li></ul>
00075  * \param key           The CMAC key.
00076  * \param keybits       The length of the CMAC key in bits.
00077  *                      Must be supported by the cipher.
00078  *
00079  * \return              \c 0 on success, or a cipher-specific error code.
00080  */
00081 int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
00082                                 const unsigned char *key, size_t keybits );
00083 
00084 /**
00085  * \brief               This function feeds an input buffer into an ongoing CMAC
00086  *                      computation.
00087  *
00088  *                      It is called between mbedtls_cipher_cmac_starts() or
00089  *                      mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish().
00090  *                      Can be called repeatedly.
00091  *
00092  * \param ctx           The cipher context used for the CMAC operation.
00093  * \param input         The buffer holding the input data.
00094  * \param ilen          The length of the input data.
00095  *
00096  * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
00097  *                      if parameter verification fails.
00098  */
00099 int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
00100                                 const unsigned char *input, size_t ilen );
00101 
00102 /**
00103  * \brief               This function finishes the CMAC operation, and writes
00104  *                      the result to the output buffer.
00105  *
00106  *                      It is called after mbedtls_cipher_cmac_update().
00107  *                      It can be followed by mbedtls_cipher_cmac_reset() and
00108  *                      mbedtls_cipher_cmac_update(), or mbedtls_cipher_free().
00109  *
00110  * \param ctx           The cipher context used for the CMAC operation.
00111  * \param output        The output buffer for the CMAC checksum result.
00112  *
00113  * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
00114  *                      if parameter verification fails.
00115  */
00116 int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
00117                                 unsigned char *output );
00118 
00119 /**
00120  * \brief               This function prepares the authentication of another
00121  *                      message with the same key as the previous CMAC
00122  *                      operation.
00123  *
00124  *                      It is called after mbedtls_cipher_cmac_finish()
00125  *                      and before mbedtls_cipher_cmac_update().
00126  *
00127  * \param ctx           The cipher context used for the CMAC operation.
00128  *
00129  * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
00130  *                      if parameter verification fails.
00131  */
00132 int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx );
00133 
00134 /**
00135  * \brief               This function calculates the full generic CMAC
00136  *                      on the input buffer with the provided key.
00137  *
00138  *                      The function allocates the context, performs the
00139  *                      calculation, and frees the context.
00140  *
00141  *                      The CMAC result is calculated as
00142  *                      output = generic CMAC(cmac key, input buffer).
00143  *
00144  *
00145  * \param cipher_info   The cipher information.
00146  * \param key           The CMAC key.
00147  * \param keylen        The length of the CMAC key in bits.
00148  * \param input         The buffer holding the input data.
00149  * \param ilen          The length of the input data.
00150  * \param output        The buffer for the generic CMAC result.
00151  *
00152  * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
00153  *                      if parameter verification fails.
00154  */
00155 int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
00156                          const unsigned char *key, size_t keylen,
00157                          const unsigned char *input, size_t ilen,
00158                          unsigned char *output );
00159 
00160 #if defined(MBEDTLS_AES_C)
00161 /**
00162  * \brief           This function implements the AES-CMAC-PRF-128 pseudorandom
00163  *                  function, as defined in
00164  *                  <em>RFC-4615: The Advanced Encryption Standard-Cipher-based
00165  *                  Message Authentication Code-Pseudo-Random Function-128
00166  *                  (AES-CMAC-PRF-128) Algorithm for the Internet Key
00167  *                  Exchange Protocol (IKE).</em>
00168  *
00169  * \param key       The key to use.
00170  * \param key_len   The key length in Bytes.
00171  * \param input     The buffer holding the input data.
00172  * \param in_len    The length of the input data in Bytes.
00173  * \param output    The buffer holding the generated 16 Bytes of
00174  *                  pseudorandom output.
00175  *
00176  * \return          \c 0 on success.
00177  */
00178 int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len,
00179                               const unsigned char *input, size_t in_len,
00180                               unsigned char output[16] );
00181 #endif /* MBEDTLS_AES_C */
00182 
00183 #ifdef __cplusplus
00184 }
00185 #endif
00186 
00187 #else  /* !MBEDTLS_CMAC_ALT */
00188 #include "cmac_alt.h"
00189 #endif /* !MBEDTLS_CMAC_ALT */
00190 
00191 #ifdef __cplusplus
00192 extern "C" {
00193 #endif
00194 
00195 #if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) )
00196 /**
00197  * \brief          The CMAC checkup routine.
00198  *
00199  * \return         \c 0 on success, or \c 1 on failure.
00200  */
00201 int mbedtls_cmac_self_test( int verbose );
00202 #endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */
00203 
00204 #ifdef __cplusplus
00205 }
00206 #endif
00207 
00208 #endif /* MBEDTLS_CMAC_H */