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.
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 */ 00018 /* 00019 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved 00020 * SPDX-License-Identifier: Apache-2.0 00021 * 00022 * Licensed under the Apache License, Version 2.0 (the "License"); you may 00023 * not use this file except in compliance with the License. 00024 * You may obtain a copy of the License at 00025 * 00026 * http://www.apache.org/licenses/LICENSE-2.0 00027 * 00028 * Unless required by applicable law or agreed to in writing, software 00029 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 00030 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00031 * See the License for the specific language governing permissions and 00032 * limitations under the License. 00033 * 00034 * This file is part of Mbed TLS (https://tls.mbed.org) 00035 */ 00036 00037 #ifndef MBEDTLS_CCM_H 00038 #define MBEDTLS_CCM_H 00039 00040 #include "cipher.h" 00041 00042 #define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to the function. */ 00043 #define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */ 00044 #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */ 00045 00046 00047 #ifdef __cplusplus 00048 extern "C" { 00049 #endif 00050 00051 #if !defined(MBEDTLS_CCM_ALT) 00052 // Regular implementation 00053 // 00054 00055 /** 00056 * \brief The CCM context-type definition. The CCM context is passed 00057 * to the APIs called. 00058 */ 00059 typedef struct { 00060 mbedtls_cipher_context_t cipher_ctx ; /*!< The cipher context used. */ 00061 } 00062 mbedtls_ccm_context; 00063 00064 #else /* MBEDTLS_CCM_ALT */ 00065 #include "ccm_alt.h" 00066 #endif /* MBEDTLS_CCM_ALT */ 00067 00068 /** 00069 * \brief This function initializes the specified CCM context, 00070 * to make references valid, and prepare the context 00071 * for mbedtls_ccm_setkey() or mbedtls_ccm_free(). 00072 * 00073 * \param ctx The CCM context to initialize. 00074 */ 00075 void mbedtls_ccm_init( mbedtls_ccm_context *ctx ); 00076 00077 /** 00078 * \brief This function initializes the CCM context set in the 00079 * \p ctx parameter and sets the encryption key. 00080 * 00081 * \param ctx The CCM context to initialize. 00082 * \param cipher The 128-bit block cipher to use. 00083 * \param key The encryption key. 00084 * \param keybits The key size in bits. This must be acceptable by the cipher. 00085 * 00086 * \return \c 0 on success. 00087 * \return A CCM or cipher-specific error code on failure. 00088 */ 00089 int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx, 00090 mbedtls_cipher_id_t cipher, 00091 const unsigned char *key, 00092 unsigned int keybits ); 00093 00094 /** 00095 * \brief This function releases and clears the specified CCM context 00096 * and underlying cipher sub-context. 00097 * 00098 * \param ctx The CCM context to clear. 00099 */ 00100 void mbedtls_ccm_free( mbedtls_ccm_context *ctx ); 00101 00102 /** 00103 * \brief This function encrypts a buffer using CCM. 00104 * 00105 * 00106 * \note The tag is written to a separate buffer. To concatenate 00107 * the \p tag with the \p output, as done in <em>RFC-3610: 00108 * Counter with CBC-MAC (CCM)</em>, use 00109 * \p tag = \p output + \p length, and make sure that the 00110 * output buffer is at least \p length + \p tag_len wide. 00111 * 00112 * \param ctx The CCM context to use for encryption. 00113 * \param length The length of the input data in Bytes. 00114 * \param iv Initialization vector (nonce). 00115 * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13. 00116 * \param add The additional data field. 00117 * \param add_len The length of additional data in Bytes. 00118 * Must be less than 2^16 - 2^8. 00119 * \param input The buffer holding the input data. 00120 * \param output The buffer holding the output data. 00121 * Must be at least \p length Bytes wide. 00122 * \param tag The buffer holding the tag. 00123 * \param tag_len The length of the tag to generate in Bytes: 00124 * 4, 6, 8, 10, 12, 14 or 16. 00125 * 00126 * \return \c 0 on success. 00127 * \return A CCM or cipher-specific error code on failure. 00128 */ 00129 int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, 00130 const unsigned char *iv, size_t iv_len, 00131 const unsigned char *add, size_t add_len, 00132 const unsigned char *input, unsigned char *output, 00133 unsigned char *tag, size_t tag_len ); 00134 00135 /** 00136 * \brief This function performs a CCM authenticated decryption of a 00137 * buffer. 00138 * 00139 * \param ctx The CCM context to use for decryption. 00140 * \param length The length of the input data in Bytes. 00141 * \param iv Initialization vector. 00142 * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13. 00143 * \param add The additional data field. 00144 * \param add_len The length of additional data in Bytes. 00145 * Must be less than 2^16 - 2^8. 00146 * \param input The buffer holding the input data. 00147 * \param output The buffer holding the output data. 00148 * Must be at least \p length Bytes wide. 00149 * \param tag The buffer holding the tag. 00150 * \param tag_len The length of the tag in Bytes. 00151 * 4, 6, 8, 10, 12, 14 or 16. 00152 * 00153 * \return \c 0 on success. This indicates that the message is authentic. 00154 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 00155 * \return A cipher-specific error code on calculation failure. 00156 */ 00157 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, 00158 const unsigned char *iv, size_t iv_len, 00159 const unsigned char *add, size_t add_len, 00160 const unsigned char *input, unsigned char *output, 00161 const unsigned char *tag, size_t tag_len ); 00162 00163 00164 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C) 00165 /** 00166 * \brief The CCM checkup routine. 00167 * 00168 * \return \c 0 on success. 00169 * \return \c 1 on failure. 00170 */ 00171 int mbedtls_ccm_self_test( int verbose ); 00172 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */ 00173 00174 #ifdef __cplusplus 00175 } 00176 #endif 00177 00178 #endif /* MBEDTLS_CCM_H */
Generated on Tue Jul 12 2022 12:43:38 by
