ccm.h

00001 /**
00002  * \file ccm.h
00003  *
00004  * \brief This file provides an API for the CCM authenticated encryption
00005  *        mode for block ciphers.
00006  *
00007  * CCM combines Counter mode encryption with CBC-MAC authentication
00008  * for 128-bit block ciphers.
00009  *
00010  * Input to CCM includes the following elements:
00011  * <ul><li>Payload - data that is both authenticated and encrypted.</li>
00012  * <li>Associated data (Adata) - data that is authenticated but not
00013  * encrypted, For example, a header.</li>
00014  * <li>Nonce - A unique value that is assigned to the payload and the
00015  * associated data.</li></ul>
00016  *
00017  * Definition of CCM:
00018  * http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf
00019  * RFC 3610 "Counter with CBC-MAC (CCM)"
00020  *
00021  * Related:
00022  * RFC 5116 "An Interface and Algorithms for Authenticated Encryption"
00023  *
00024  * Definition of CCM*:
00025  * IEEE 802.15.4 - IEEE Standard for Local and metropolitan area networks
00026  * Integer representation is fixed most-significant-octet-first order and
00027  * the representation of octets is most-significant-bit-first order. This is
00028  * consistent with RFC 3610.
00029  */
00030 /*
00031  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00032  *  SPDX-License-Identifier: Apache-2.0
00033  *
00034  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00035  *  not use this file except in compliance with the License.
00036  *  You may obtain a copy of the License at
00037  *
00038  *  http://www.apache.org/licenses/LICENSE-2.0
00039  *
00040  *  Unless required by applicable law or agreed to in writing, software
00041  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00042  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00043  *  See the License for the specific language governing permissions and
00044  *  limitations under the License.
00045  *
00046  *  This file is part of Mbed TLS (https://tls.mbed.org)
00047  */
00048 
00049 #ifndef MBEDTLS_CCM_H
00050 #define MBEDTLS_CCM_H
00051 
00052 #if !defined(MBEDTLS_CONFIG_FILE)
00053 #include "mbedtls/config.h"
00054 #else
00055 #include MBEDTLS_CONFIG_FILE
00056 #endif
00057 
00058 #include "mbedtls/cipher.h"
00059 
00060 #define MBEDTLS_ERR_CCM_BAD_INPUT       -0x000D /**< Bad input parameters to the function. */
00061 #define MBEDTLS_ERR_CCM_AUTH_FAILED     -0x000F /**< Authenticated decryption failed. */
00062 
00063 /* MBEDTLS_ERR_CCM_HW_ACCEL_FAILED is deprecated and should not be used. */
00064 #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
00065 
00066 #ifdef __cplusplus
00067 extern "C" {
00068 #endif
00069 
00070 #if !defined(MBEDTLS_CCM_ALT)
00071 // Regular implementation
00072 //
00073 
00074 /**
00075  * \brief    The CCM context-type definition. The CCM context is passed
00076  *           to the APIs called.
00077  */
00078 typedef struct mbedtls_ccm_context
00079 {
00080     mbedtls_cipher_context_t cipher_ctx ;    /*!< The cipher context used. */
00081 }
00082 mbedtls_ccm_context;
00083 
00084 #else  /* MBEDTLS_CCM_ALT */
00085 #include "ccm_alt.h"
00086 #endif /* MBEDTLS_CCM_ALT */
00087 
00088 /**
00089  * \brief           This function initializes the specified CCM context,
00090  *                  to make references valid, and prepare the context
00091  *                  for mbedtls_ccm_setkey() or mbedtls_ccm_free().
00092  *
00093  * \param ctx       The CCM context to initialize. This must not be \c NULL.
00094  */
00095 void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
00096 
00097 /**
00098  * \brief           This function initializes the CCM context set in the
00099  *                  \p ctx parameter and sets the encryption key.
00100  *
00101  * \param ctx       The CCM context to initialize. This must be an initialized
00102  *                  context.
00103  * \param cipher    The 128-bit block cipher to use.
00104  * \param key       The encryption key. This must not be \c NULL.
00105  * \param keybits   The key size in bits. This must be acceptable by the cipher.
00106  *
00107  * \return          \c 0 on success.
00108  * \return          A CCM or cipher-specific error code on failure.
00109  */
00110 int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
00111                         mbedtls_cipher_id_t cipher,
00112                         const unsigned char *key,
00113                         unsigned int keybits );
00114 
00115 /**
00116  * \brief   This function releases and clears the specified CCM context
00117  *          and underlying cipher sub-context.
00118  *
00119  * \param ctx       The CCM context to clear. If this is \c NULL, the function
00120  *                  has no effect. Otherwise, this must be initialized.
00121  */
00122 void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
00123 
00124 /**
00125  * \brief           This function encrypts a buffer using CCM.
00126  *
00127  * \note            The tag is written to a separate buffer. To concatenate
00128  *                  the \p tag with the \p output, as done in <em>RFC-3610:
00129  *                  Counter with CBC-MAC (CCM)</em>, use
00130  *                  \p tag = \p output + \p length, and make sure that the
00131  *                  output buffer is at least \p length + \p tag_len wide.
00132  *
00133  * \param ctx       The CCM context to use for encryption. This must be
00134  *                  initialized and bound to a key.
00135  * \param length    The length of the input data in Bytes.
00136  * \param iv        The initialization vector (nonce). This must be a readable
00137  *                  buffer of at least \p iv_len Bytes.
00138  * \param iv_len    The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
00139  *                  or 13. The length L of the message length field is
00140  *                  15 - \p iv_len.
00141  * \param add       The additional data field. If \p add_len is greater than
00142  *                  zero, \p add must be a readable buffer of at least that
00143  *                  length.
00144  * \param add_len   The length of additional data in Bytes.
00145  *                  This must be less than `2^16 - 2^8`.
00146  * \param input     The buffer holding the input data. If \p length is greater
00147  *                  than zero, \p input must be a readable buffer of at least
00148  *                  that length.
00149  * \param output    The buffer holding the output data. If \p length is greater
00150  *                  than zero, \p output must be a writable buffer of at least
00151  *                  that length.
00152  * \param tag       The buffer holding the authentication field. This must be a
00153  *                  readable buffer of at least \p tag_len Bytes.
00154  * \param tag_len   The length of the authentication field to generate in Bytes:
00155  *                  4, 6, 8, 10, 12, 14 or 16.
00156  *
00157  * \return          \c 0 on success.
00158  * \return          A CCM or cipher-specific error code on failure.
00159  */
00160 int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
00161                          const unsigned char *iv, size_t iv_len,
00162                          const unsigned char *add, size_t add_len,
00163                          const unsigned char *input, unsigned char *output,
00164                          unsigned char *tag, size_t tag_len );
00165 
00166 /**
00167  * \brief           This function encrypts a buffer using CCM*.
00168  *
00169  * \note            The tag is written to a separate buffer. To concatenate
00170  *                  the \p tag with the \p output, as done in <em>RFC-3610:
00171  *                  Counter with CBC-MAC (CCM)</em>, use
00172  *                  \p tag = \p output + \p length, and make sure that the
00173  *                  output buffer is at least \p length + \p tag_len wide.
00174  *
00175  * \note            When using this function in a variable tag length context,
00176  *                  the tag length has to be encoded into the \p iv passed to
00177  *                  this function.
00178  *
00179  * \param ctx       The CCM context to use for encryption. This must be
00180  *                  initialized and bound to a key.
00181  * \param length    The length of the input data in Bytes.
00182  * \param iv        The initialization vector (nonce). This must be a readable
00183  *                  buffer of at least \p iv_len Bytes.
00184  * \param iv_len    The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
00185  *                  or 13. The length L of the message length field is
00186  *                  15 - \p iv_len.
00187  * \param add       The additional data field. This must be a readable buffer of
00188  *                  at least \p add_len Bytes.
00189  * \param add_len   The length of additional data in Bytes.
00190  *                  This must be less than 2^16 - 2^8.
00191  * \param input     The buffer holding the input data. If \p length is greater
00192  *                  than zero, \p input must be a readable buffer of at least
00193  *                  that length.
00194  * \param output    The buffer holding the output data. If \p length is greater
00195  *                  than zero, \p output must be a writable buffer of at least
00196  *                  that length.
00197  * \param tag       The buffer holding the authentication field. This must be a
00198  *                  readable buffer of at least \p tag_len Bytes.
00199  * \param tag_len   The length of the authentication field to generate in Bytes:
00200  *                  0, 4, 6, 8, 10, 12, 14 or 16.
00201  *
00202  * \warning         Passing \c 0 as \p tag_len means that the message is no
00203  *                  longer authenticated.
00204  *
00205  * \return          \c 0 on success.
00206  * \return          A CCM or cipher-specific error code on failure.
00207  */
00208 int mbedtls_ccm_star_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
00209                          const unsigned char *iv, size_t iv_len,
00210                          const unsigned char *add, size_t add_len,
00211                          const unsigned char *input, unsigned char *output,
00212                          unsigned char *tag, size_t tag_len );
00213 
00214 /**
00215  * \brief           This function performs a CCM authenticated decryption of a
00216  *                  buffer.
00217  *
00218  * \param ctx       The CCM context to use for decryption. This must be
00219  *                  initialized and bound to a key.
00220  * \param length    The length of the input data in Bytes.
00221  * \param iv        The initialization vector (nonce). This must be a readable
00222  *                  buffer of at least \p iv_len Bytes.
00223  * \param iv_len    The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
00224  *                  or 13. The length L of the message length field is
00225  *                  15 - \p iv_len.
00226  * \param add       The additional data field. This must be a readable buffer
00227  *                  of at least that \p add_len Bytes..
00228  * \param add_len   The length of additional data in Bytes.
00229  *                  This must be less than 2^16 - 2^8.
00230  * \param input     The buffer holding the input data. If \p length is greater
00231  *                  than zero, \p input must be a readable buffer of at least
00232  *                  that length.
00233  * \param output    The buffer holding the output data. If \p length is greater
00234  *                  than zero, \p output must be a writable buffer of at least
00235  *                  that length.
00236  * \param tag       The buffer holding the authentication field. This must be a
00237  *                  readable buffer of at least \p tag_len Bytes.
00238  * \param tag_len   The length of the authentication field to generate in Bytes:
00239  *                  4, 6, 8, 10, 12, 14 or 16.
00240  *
00241  * \return          \c 0 on success. This indicates that the message is authentic.
00242  * \return          #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
00243  * \return          A cipher-specific error code on calculation failure.
00244  */
00245 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
00246                       const unsigned char *iv, size_t iv_len,
00247                       const unsigned char *add, size_t add_len,
00248                       const unsigned char *input, unsigned char *output,
00249                       const unsigned char *tag, size_t tag_len );
00250 
00251 /**
00252  * \brief           This function performs a CCM* authenticated decryption of a
00253  *                  buffer.
00254  *
00255  * \note            When using this function in a variable tag length context,
00256  *                  the tag length has to be decoded from \p iv and passed to
00257  *                  this function as \p tag_len. (\p tag needs to be adjusted
00258  *                  accordingly.)
00259  *
00260  * \param ctx       The CCM context to use for decryption. This must be
00261  *                  initialized and bound to a key.
00262  * \param length    The length of the input data in Bytes.
00263  * \param iv        The initialization vector (nonce). This must be a readable
00264  *                  buffer of at least \p iv_len Bytes.
00265  * \param iv_len    The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
00266  *                  or 13. The length L of the message length field is
00267  *                  15 - \p iv_len.
00268  * \param add       The additional data field. This must be a readable buffer of
00269  *                  at least that \p add_len Bytes.
00270  * \param add_len   The length of additional data in Bytes.
00271  *                  This must be less than 2^16 - 2^8.
00272  * \param input     The buffer holding the input data. If \p length is greater
00273  *                  than zero, \p input must be a readable buffer of at least
00274  *                  that length.
00275  * \param output    The buffer holding the output data. If \p length is greater
00276  *                  than zero, \p output must be a writable buffer of at least
00277  *                  that length.
00278  * \param tag       The buffer holding the authentication field. This must be a
00279  *                  readable buffer of at least \p tag_len Bytes.
00280  * \param tag_len   The length of the authentication field in Bytes.
00281  *                  0, 4, 6, 8, 10, 12, 14 or 16.
00282  *
00283  * \warning         Passing \c 0 as \p tag_len means that the message is nos
00284  *                  longer authenticated.
00285  *
00286  * \return          \c 0 on success.
00287  * \return          #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
00288  * \return          A cipher-specific error code on calculation failure.
00289  */
00290 int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
00291                       const unsigned char *iv, size_t iv_len,
00292                       const unsigned char *add, size_t add_len,
00293                       const unsigned char *input, unsigned char *output,
00294                       const unsigned char *tag, size_t tag_len );
00295 
00296 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
00297 /**
00298  * \brief          The CCM checkup routine.
00299  *
00300  * \return         \c 0 on success.
00301  * \return         \c 1 on failure.
00302  */
00303 int mbedtls_ccm_self_test( int verbose );
00304 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
00305 
00306 #ifdef __cplusplus
00307 }
00308 #endif
00309 
00310 #endif /* MBEDTLS_CCM_H */