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 OR GPL-2.0-or-later 33 * 34 * This file is provided under the Apache License 2.0, or the 35 * GNU General Public License v2.0 or later. 36 * 37 * ********** 38 * Apache License 2.0: 39 * 40 * Licensed under the Apache License, Version 2.0 (the "License"); you may 41 * not use this file except in compliance with the License. 42 * You may obtain a copy of the License at 43 * 44 * http://www.apache.org/licenses/LICENSE-2.0 45 * 46 * Unless required by applicable law or agreed to in writing, software 47 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 48 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 49 * See the License for the specific language governing permissions and 50 * limitations under the License. 51 * 52 * ********** 53 * 54 * ********** 55 * GNU General Public License v2.0 or later: 56 * 57 * This program is free software; you can redistribute it and/or modify 58 * it under the terms of the GNU General Public License as published by 59 * the Free Software Foundation; either version 2 of the License, or 60 * (at your option) any later version. 61 * 62 * This program is distributed in the hope that it will be useful, 63 * but WITHOUT ANY WARRANTY; without even the implied warranty of 64 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 65 * GNU General Public License for more details. 66 * 67 * You should have received a copy of the GNU General Public License along 68 * with this program; if not, write to the Free Software Foundation, Inc., 69 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 70 * 71 * ********** 72 */ 73 74 #ifndef MBEDTLS_CCM_H 75 #define MBEDTLS_CCM_H 76 77 #if !defined(MBEDTLS_CONFIG_FILE) 78 #include "config.h" 79 #else 80 #include MBEDTLS_CONFIG_FILE 81 #endif 82 83 #include "cipher.h" 84 85 #define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to the function. */ 86 #define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */ 87 88 /* MBEDTLS_ERR_CCM_HW_ACCEL_FAILED is deprecated and should not be used. */ 89 #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */ 90 91 #ifdef __cplusplus 92 extern "C" { 93 #endif 94 95 #if !defined(MBEDTLS_CCM_ALT) 96 // Regular implementation 97 // 98 99 /** 100 * \brief The CCM context-type definition. The CCM context is passed 101 * to the APIs called. 102 */ 103 typedef struct mbedtls_ccm_context 104 { 105 mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */ 106 } 107 mbedtls_ccm_context; 108 109 #else /* MBEDTLS_CCM_ALT */ 110 #include "ccm_alt.h" 111 #endif /* MBEDTLS_CCM_ALT */ 112 113 /** 114 * \brief This function initializes the specified CCM context, 115 * to make references valid, and prepare the context 116 * for mbedtls_ccm_setkey() or mbedtls_ccm_free(). 117 * 118 * \param ctx The CCM context to initialize. This must not be \c NULL. 119 */ 120 void mbedtls_ccm_init( mbedtls_ccm_context *ctx ); 121 122 /** 123 * \brief This function initializes the CCM context set in the 124 * \p ctx parameter and sets the encryption key. 125 * 126 * \param ctx The CCM context to initialize. This must be an initialized 127 * context. 128 * \param cipher The 128-bit block cipher to use. 129 * \param key The encryption key. This must not be \c NULL. 130 * \param keybits The key size in bits. This must be acceptable by the cipher. 131 * 132 * \return \c 0 on success. 133 * \return A CCM or cipher-specific error code on failure. 134 */ 135 int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx, 136 mbedtls_cipher_id_t cipher, 137 const unsigned char *key, 138 unsigned int keybits ); 139 140 /** 141 * \brief This function releases and clears the specified CCM context 142 * and underlying cipher sub-context. 143 * 144 * \param ctx The CCM context to clear. If this is \c NULL, the function 145 * has no effect. Otherwise, this must be initialized. 146 */ 147 void mbedtls_ccm_free( mbedtls_ccm_context *ctx ); 148 149 /** 150 * \brief This function encrypts a buffer using CCM. 151 * 152 * \note The tag is written to a separate buffer. To concatenate 153 * the \p tag with the \p output, as done in <em>RFC-3610: 154 * Counter with CBC-MAC (CCM)</em>, use 155 * \p tag = \p output + \p length, and make sure that the 156 * output buffer is at least \p length + \p tag_len wide. 157 * 158 * \param ctx The CCM context to use for encryption. This must be 159 * initialized and bound to a key. 160 * \param length The length of the input data in Bytes. 161 * \param iv The initialization vector (nonce). This must be a readable 162 * buffer of at least \p iv_len Bytes. 163 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 164 * or 13. The length L of the message length field is 165 * 15 - \p iv_len. 166 * \param add The additional data field. If \p add_len is greater than 167 * zero, \p add must be a readable buffer of at least that 168 * length. 169 * \param add_len The length of additional data in Bytes. 170 * This must be less than `2^16 - 2^8`. 171 * \param input The buffer holding the input data. If \p length is greater 172 * than zero, \p input must be a readable buffer of at least 173 * that length. 174 * \param output The buffer holding the output data. If \p length is greater 175 * than zero, \p output must be a writable buffer of at least 176 * that length. 177 * \param tag The buffer holding the authentication field. This must be a 178 * writable buffer of at least \p tag_len Bytes. 179 * \param tag_len The length of the authentication field to generate in Bytes: 180 * 4, 6, 8, 10, 12, 14 or 16. 181 * 182 * \return \c 0 on success. 183 * \return A CCM or cipher-specific error code on failure. 184 */ 185 int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, 186 const unsigned char *iv, size_t iv_len, 187 const unsigned char *add, size_t add_len, 188 const unsigned char *input, unsigned char *output, 189 unsigned char *tag, size_t tag_len ); 190 191 /** 192 * \brief This function encrypts a buffer using CCM*. 193 * 194 * \note The tag is written to a separate buffer. To concatenate 195 * the \p tag with the \p output, as done in <em>RFC-3610: 196 * Counter with CBC-MAC (CCM)</em>, use 197 * \p tag = \p output + \p length, and make sure that the 198 * output buffer is at least \p length + \p tag_len wide. 199 * 200 * \note When using this function in a variable tag length context, 201 * the tag length has to be encoded into the \p iv passed to 202 * this function. 203 * 204 * \param ctx The CCM context to use for encryption. This must be 205 * initialized and bound to a key. 206 * \param length The length of the input data in Bytes. 207 * \param iv The initialization vector (nonce). This must be a readable 208 * buffer of at least \p iv_len Bytes. 209 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 210 * or 13. The length L of the message length field is 211 * 15 - \p iv_len. 212 * \param add The additional data field. This must be a readable buffer of 213 * at least \p add_len Bytes. 214 * \param add_len The length of additional data in Bytes. 215 * This must be less than 2^16 - 2^8. 216 * \param input The buffer holding the input data. If \p length is greater 217 * than zero, \p input must be a readable buffer of at least 218 * that length. 219 * \param output The buffer holding the output data. If \p length is greater 220 * than zero, \p output must be a writable buffer of at least 221 * that length. 222 * \param tag The buffer holding the authentication field. This must be a 223 * writable buffer of at least \p tag_len Bytes. 224 * \param tag_len The length of the authentication field to generate in Bytes: 225 * 0, 4, 6, 8, 10, 12, 14 or 16. 226 * 227 * \warning Passing \c 0 as \p tag_len means that the message is no 228 * longer authenticated. 229 * 230 * \return \c 0 on success. 231 * \return A CCM or cipher-specific error code on failure. 232 */ 233 int mbedtls_ccm_star_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, 234 const unsigned char *iv, size_t iv_len, 235 const unsigned char *add, size_t add_len, 236 const unsigned char *input, unsigned char *output, 237 unsigned char *tag, size_t tag_len ); 238 239 /** 240 * \brief This function performs a CCM authenticated decryption of a 241 * buffer. 242 * 243 * \param ctx The CCM context to use for decryption. This must be 244 * initialized and bound to a key. 245 * \param length The length of the input data in Bytes. 246 * \param iv The initialization vector (nonce). This must be a readable 247 * buffer of at least \p iv_len Bytes. 248 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 249 * or 13. The length L of the message length field is 250 * 15 - \p iv_len. 251 * \param add The additional data field. This must be a readable buffer 252 * of at least that \p add_len Bytes.. 253 * \param add_len The length of additional data in Bytes. 254 * This must be less than 2^16 - 2^8. 255 * \param input The buffer holding the input data. If \p length is greater 256 * than zero, \p input must be a readable buffer of at least 257 * that length. 258 * \param output The buffer holding the output data. If \p length is greater 259 * than zero, \p output must be a writable buffer of at least 260 * that length. 261 * \param tag The buffer holding the authentication field. This must be a 262 * readable buffer of at least \p tag_len Bytes. 263 * \param tag_len The length of the authentication field to generate in Bytes: 264 * 4, 6, 8, 10, 12, 14 or 16. 265 * 266 * \return \c 0 on success. This indicates that the message is authentic. 267 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 268 * \return A cipher-specific error code on calculation failure. 269 */ 270 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, 271 const unsigned char *iv, size_t iv_len, 272 const unsigned char *add, size_t add_len, 273 const unsigned char *input, unsigned char *output, 274 const unsigned char *tag, size_t tag_len ); 275 276 /** 277 * \brief This function performs a CCM* authenticated decryption of a 278 * buffer. 279 * 280 * \note When using this function in a variable tag length context, 281 * the tag length has to be decoded from \p iv and passed to 282 * this function as \p tag_len. (\p tag needs to be adjusted 283 * accordingly.) 284 * 285 * \param ctx The CCM context to use for decryption. This must be 286 * initialized and bound to a key. 287 * \param length The length of the input data in Bytes. 288 * \param iv The initialization vector (nonce). This must be a readable 289 * buffer of at least \p iv_len Bytes. 290 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 291 * or 13. The length L of the message length field is 292 * 15 - \p iv_len. 293 * \param add The additional data field. This must be a readable buffer of 294 * at least that \p add_len Bytes. 295 * \param add_len The length of additional data in Bytes. 296 * This must be less than 2^16 - 2^8. 297 * \param input The buffer holding the input data. If \p length is greater 298 * than zero, \p input must be a readable buffer of at least 299 * that length. 300 * \param output The buffer holding the output data. If \p length is greater 301 * than zero, \p output must be a writable buffer of at least 302 * that length. 303 * \param tag The buffer holding the authentication field. This must be a 304 * readable buffer of at least \p tag_len Bytes. 305 * \param tag_len The length of the authentication field in Bytes. 306 * 0, 4, 6, 8, 10, 12, 14 or 16. 307 * 308 * \warning Passing \c 0 as \p tag_len means that the message is nos 309 * longer authenticated. 310 * 311 * \return \c 0 on success. 312 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 313 * \return A cipher-specific error code on calculation failure. 314 */ 315 int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, 316 const unsigned char *iv, size_t iv_len, 317 const unsigned char *add, size_t add_len, 318 const unsigned char *input, unsigned char *output, 319 const unsigned char *tag, size_t tag_len ); 320 321 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C) 322 /** 323 * \brief The CCM checkup routine. 324 * 325 * \return \c 0 on success. 326 * \return \c 1 on failure. 327 */ 328 int mbedtls_ccm_self_test( int verbose ); 329 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */ 330 331 #ifdef __cplusplus 332 } 333 #endif 334 335 #endif /* MBEDTLS_CCM_H */ 336