Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
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 */
Generated on Tue Jul 12 2022 13:54:04 by
