1 /** 2 * \file ccm.h 3 * 4 * \brief This file provides an API for the CCM authenticated encryption 5 * mode for block ciphers. 6 * 7 * CCM combines Counter mode encryption with CBC-MAC authentication 8 * for 128-bit block ciphers. 9 * 10 * Input to CCM includes the following elements: 11 * <ul><li>Payload - data that is both authenticated and encrypted.</li> 12 * <li>Associated data (Adata) - data that is authenticated but not 13 * encrypted, For example, a header.</li> 14 * <li>Nonce - A unique value that is assigned to the payload and the 15 * associated data.</li></ul> 16 * 17 * Definition of CCM: 18 * http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf 19 * RFC 3610 "Counter with CBC-MAC (CCM)" 20 * 21 * Related: 22 * RFC 5116 "An Interface and Algorithms for Authenticated Encryption" 23 * 24 * Definition of CCM*: 25 * IEEE 802.15.4 - IEEE Standard for Local and metropolitan area networks 26 * Integer representation is fixed most-significant-octet-first order and 27 * the representation of octets is most-significant-bit-first order. This is 28 * consistent with RFC 3610. 29 */ 30 /* 31 * Copyright The Mbed TLS Contributors 32 * SPDX-License-Identifier: Apache-2.0 33 * 34 * Licensed under the Apache License, Version 2.0 (the "License"); you may 35 * not use this file except in compliance with the License. 36 * You may obtain a copy of the License at 37 * 38 * http://www.apache.org/licenses/LICENSE-2.0 39 * 40 * Unless required by applicable law or agreed to in writing, software 41 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 42 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 43 * See the License for the specific language governing permissions and 44 * limitations under the License. 45 */ 46 47 #ifndef MBEDTLS_CCM_H 48 #define MBEDTLS_CCM_H 49 50 #if !defined(MBEDTLS_CONFIG_FILE) 51 #include "mbedtls/config.h" 52 #else 53 #include MBEDTLS_CONFIG_FILE 54 #endif 55 56 #include "mbedtls/cipher.h" 57 58 /** Bad input parameters to the function. */ 59 #define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D 60 /** Authenticated decryption failed. */ 61 #define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F 62 63 /* MBEDTLS_ERR_CCM_HW_ACCEL_FAILED is deprecated and should not be used. */ 64 /** CCM hardware accelerator failed. */ 65 #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 66 67 #ifdef __cplusplus 68 extern "C" { 69 #endif 70 71 #if !defined(MBEDTLS_CCM_ALT) 72 // Regular implementation 73 // 74 75 /** 76 * \brief The CCM context-type definition. The CCM context is passed 77 * to the APIs called. 78 */ 79 typedef struct mbedtls_ccm_context 80 { 81 mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */ 82 } 83 mbedtls_ccm_context; 84 85 #else /* MBEDTLS_CCM_ALT */ 86 #include "ccm_alt.h" 87 #endif /* MBEDTLS_CCM_ALT */ 88 89 /** 90 * \brief This function initializes the specified CCM context, 91 * to make references valid, and prepare the context 92 * for mbedtls_ccm_setkey() or mbedtls_ccm_free(). 93 * 94 * \param ctx The CCM context to initialize. This must not be \c NULL. 95 */ 96 void mbedtls_ccm_init( mbedtls_ccm_context *ctx ); 97 98 /** 99 * \brief This function initializes the CCM context set in the 100 * \p ctx parameter and sets the encryption key. 101 * 102 * \param ctx The CCM context to initialize. This must be an initialized 103 * context. 104 * \param cipher The 128-bit block cipher to use. 105 * \param key The encryption key. This must not be \c NULL. 106 * \param keybits The key size in bits. This must be acceptable by the cipher. 107 * 108 * \return \c 0 on success. 109 * \return A CCM or cipher-specific error code on failure. 110 */ 111 int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx, 112 mbedtls_cipher_id_t cipher, 113 const unsigned char *key, 114 unsigned int keybits ); 115 116 /** 117 * \brief This function releases and clears the specified CCM context 118 * and underlying cipher sub-context. 119 * 120 * \param ctx The CCM context to clear. If this is \c NULL, the function 121 * has no effect. Otherwise, this must be initialized. 122 */ 123 void mbedtls_ccm_free( mbedtls_ccm_context *ctx ); 124 125 /** 126 * \brief This function encrypts a buffer using CCM. 127 * 128 * \note The tag is written to a separate buffer. To concatenate 129 * the \p tag with the \p output, as done in <em>RFC-3610: 130 * Counter with CBC-MAC (CCM)</em>, use 131 * \p tag = \p output + \p length, and make sure that the 132 * output buffer is at least \p length + \p tag_len wide. 133 * 134 * \param ctx The CCM context to use for encryption. This must be 135 * initialized and bound to a key. 136 * \param length The length of the input data in Bytes. 137 * \param iv The initialization vector (nonce). This must be a readable 138 * buffer of at least \p iv_len Bytes. 139 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 140 * or 13. The length L of the message length field is 141 * 15 - \p iv_len. 142 * \param add The additional data field. If \p add_len is greater than 143 * zero, \p add must be a readable buffer of at least that 144 * length. 145 * \param add_len The length of additional data in Bytes. 146 * This must be less than `2^16 - 2^8`. 147 * \param input The buffer holding the input data. If \p length is greater 148 * than zero, \p input must be a readable buffer of at least 149 * that length. 150 * \param output The buffer holding the output data. If \p length is greater 151 * than zero, \p output must be a writable buffer of at least 152 * that length. 153 * \param tag The buffer holding the authentication field. This must be a 154 * writable buffer of at least \p tag_len Bytes. 155 * \param tag_len The length of the authentication field to generate in Bytes: 156 * 4, 6, 8, 10, 12, 14 or 16. 157 * 158 * \return \c 0 on success. 159 * \return A CCM or cipher-specific error code on failure. 160 */ 161 int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, 162 const unsigned char *iv, size_t iv_len, 163 const unsigned char *add, size_t add_len, 164 const unsigned char *input, unsigned char *output, 165 unsigned char *tag, size_t tag_len ); 166 167 /** 168 * \brief This function encrypts a buffer using CCM*. 169 * 170 * \note The tag is written to a separate buffer. To concatenate 171 * the \p tag with the \p output, as done in <em>RFC-3610: 172 * Counter with CBC-MAC (CCM)</em>, use 173 * \p tag = \p output + \p length, and make sure that the 174 * output buffer is at least \p length + \p tag_len wide. 175 * 176 * \note When using this function in a variable tag length context, 177 * the tag length has to be encoded into the \p iv passed to 178 * this function. 179 * 180 * \param ctx The CCM context to use for encryption. This must be 181 * initialized and bound to a key. 182 * \param length The length of the input data in Bytes. 183 * \param iv The initialization vector (nonce). This must be a readable 184 * buffer of at least \p iv_len Bytes. 185 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 186 * or 13. The length L of the message length field is 187 * 15 - \p iv_len. 188 * \param add The additional data field. This must be a readable buffer of 189 * at least \p add_len Bytes. 190 * \param add_len The length of additional data in Bytes. 191 * This must be less than 2^16 - 2^8. 192 * \param input The buffer holding the input data. If \p length is greater 193 * than zero, \p input must be a readable buffer of at least 194 * that length. 195 * \param output The buffer holding the output data. If \p length is greater 196 * than zero, \p output must be a writable buffer of at least 197 * that length. 198 * \param tag The buffer holding the authentication field. This must be a 199 * writable buffer of at least \p tag_len Bytes. 200 * \param tag_len The length of the authentication field to generate in Bytes: 201 * 0, 4, 6, 8, 10, 12, 14 or 16. 202 * 203 * \warning Passing \c 0 as \p tag_len means that the message is no 204 * longer authenticated. 205 * 206 * \return \c 0 on success. 207 * \return A CCM or cipher-specific error code on failure. 208 */ 209 int mbedtls_ccm_star_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, 210 const unsigned char *iv, size_t iv_len, 211 const unsigned char *add, size_t add_len, 212 const unsigned char *input, unsigned char *output, 213 unsigned char *tag, size_t tag_len ); 214 215 /** 216 * \brief This function performs a CCM authenticated decryption of a 217 * buffer. 218 * 219 * \param ctx The CCM context to use for decryption. This must be 220 * initialized and bound to a key. 221 * \param length The length of the input data in Bytes. 222 * \param iv The initialization vector (nonce). This must be a readable 223 * buffer of at least \p iv_len Bytes. 224 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 225 * or 13. The length L of the message length field is 226 * 15 - \p iv_len. 227 * \param add The additional data field. This must be a readable buffer 228 * of at least that \p add_len Bytes.. 229 * \param add_len The length of additional data in Bytes. 230 * This must be less than 2^16 - 2^8. 231 * \param input The buffer holding the input data. If \p length is greater 232 * than zero, \p input must be a readable buffer of at least 233 * that length. 234 * \param output The buffer holding the output data. If \p length is greater 235 * than zero, \p output must be a writable buffer of at least 236 * that length. 237 * \param tag The buffer holding the authentication field. This must be a 238 * readable buffer of at least \p tag_len Bytes. 239 * \param tag_len The length of the authentication field to generate in Bytes: 240 * 4, 6, 8, 10, 12, 14 or 16. 241 * 242 * \return \c 0 on success. This indicates that the message is authentic. 243 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 244 * \return A cipher-specific error code on calculation failure. 245 */ 246 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, 247 const unsigned char *iv, size_t iv_len, 248 const unsigned char *add, size_t add_len, 249 const unsigned char *input, unsigned char *output, 250 const unsigned char *tag, size_t tag_len ); 251 252 /** 253 * \brief This function performs a CCM* authenticated decryption of a 254 * buffer. 255 * 256 * \note When using this function in a variable tag length context, 257 * the tag length has to be decoded from \p iv and passed to 258 * this function as \p tag_len. (\p tag needs to be adjusted 259 * accordingly.) 260 * 261 * \param ctx The CCM context to use for decryption. This must be 262 * initialized and bound to a key. 263 * \param length The length of the input data in Bytes. 264 * \param iv The initialization vector (nonce). This must be a readable 265 * buffer of at least \p iv_len Bytes. 266 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 267 * or 13. The length L of the message length field is 268 * 15 - \p iv_len. 269 * \param add The additional data field. This must be a readable buffer of 270 * at least that \p add_len Bytes. 271 * \param add_len The length of additional data in Bytes. 272 * This must be less than 2^16 - 2^8. 273 * \param input The buffer holding the input data. If \p length is greater 274 * than zero, \p input must be a readable buffer of at least 275 * that length. 276 * \param output The buffer holding the output data. If \p length is greater 277 * than zero, \p output must be a writable buffer of at least 278 * that length. 279 * \param tag The buffer holding the authentication field. This must be a 280 * readable buffer of at least \p tag_len Bytes. 281 * \param tag_len The length of the authentication field in Bytes. 282 * 0, 4, 6, 8, 10, 12, 14 or 16. 283 * 284 * \warning Passing \c 0 as \p tag_len means that the message is nos 285 * longer authenticated. 286 * 287 * \return \c 0 on success. 288 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 289 * \return A cipher-specific error code on calculation failure. 290 */ 291 int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, 292 const unsigned char *iv, size_t iv_len, 293 const unsigned char *add, size_t add_len, 294 const unsigned char *input, unsigned char *output, 295 const unsigned char *tag, size_t tag_len ); 296 297 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C) 298 /** 299 * \brief The CCM checkup routine. 300 * 301 * \return \c 0 on success. 302 * \return \c 1 on failure. 303 */ 304 int mbedtls_ccm_self_test( int verbose ); 305 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */ 306 307 #ifdef __cplusplus 308 } 309 #endif 310 311 #endif /* MBEDTLS_CCM_H */ 312