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 35 #ifndef MBEDTLS_CCM_H 36 #define MBEDTLS_CCM_H 37 #include "mbedtls/private_access.h" 38 39 #include "mbedtls/build_info.h" 40 41 #include "mbedtls/cipher.h" 42 43 #define MBEDTLS_CCM_DECRYPT 0 44 #define MBEDTLS_CCM_ENCRYPT 1 45 #define MBEDTLS_CCM_STAR_DECRYPT 2 46 #define MBEDTLS_CCM_STAR_ENCRYPT 3 47 48 /** Bad input parameters to the function. */ 49 #define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D 50 /** Authenticated decryption failed. */ 51 #define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F 52 53 #ifdef __cplusplus 54 extern "C" { 55 #endif 56 57 #if !defined(MBEDTLS_CCM_ALT) 58 // Regular implementation 59 // 60 61 /** 62 * \brief The CCM context-type definition. The CCM context is passed 63 * to the APIs called. 64 */ 65 typedef struct mbedtls_ccm_context { 66 unsigned char MBEDTLS_PRIVATE(y)[16]; /*!< The Y working buffer */ 67 unsigned char MBEDTLS_PRIVATE(ctr)[16]; /*!< The counter buffer */ 68 size_t MBEDTLS_PRIVATE(plaintext_len); /*!< Total plaintext length */ 69 size_t MBEDTLS_PRIVATE(add_len); /*!< Total authentication data length */ 70 size_t MBEDTLS_PRIVATE(tag_len); /*!< Total tag length */ 71 size_t MBEDTLS_PRIVATE(processed); /*!< Track how many bytes of input data 72 were processed (chunked input). 73 Used independently for both auth data 74 and plaintext/ciphertext. 75 This variable is set to zero after 76 auth data input is finished. */ 77 unsigned int MBEDTLS_PRIVATE(q); /*!< The Q working value */ 78 unsigned int MBEDTLS_PRIVATE(mode); /*!< The operation to perform: 79 #MBEDTLS_CCM_ENCRYPT or 80 #MBEDTLS_CCM_DECRYPT or 81 #MBEDTLS_CCM_STAR_ENCRYPT or 82 #MBEDTLS_CCM_STAR_DECRYPT. */ 83 mbedtls_cipher_context_t MBEDTLS_PRIVATE(cipher_ctx); /*!< The cipher context used. */ 84 int MBEDTLS_PRIVATE(state); /*!< Working value holding context's 85 state. Used for chunked data input */ 86 } 87 mbedtls_ccm_context; 88 89 #else /* MBEDTLS_CCM_ALT */ 90 #include "ccm_alt.h" 91 #endif /* MBEDTLS_CCM_ALT */ 92 93 /** 94 * \brief This function initializes the specified CCM context, 95 * to make references valid, and prepare the context 96 * for mbedtls_ccm_setkey() or mbedtls_ccm_free(). 97 * 98 * \param ctx The CCM context to initialize. This must not be \c NULL. 99 */ 100 void mbedtls_ccm_init(mbedtls_ccm_context *ctx); 101 102 /** 103 * \brief This function initializes the CCM context set in the 104 * \p ctx parameter and sets the encryption key. 105 * 106 * \param ctx The CCM context to initialize. This must be an initialized 107 * context. 108 * \param cipher The 128-bit block cipher to use. 109 * \param key The encryption key. This must not be \c NULL. 110 * \param keybits The key size in bits. This must be acceptable by the cipher. 111 * 112 * \return \c 0 on success. 113 * \return A CCM or cipher-specific error code on failure. 114 */ 115 int mbedtls_ccm_setkey(mbedtls_ccm_context *ctx, 116 mbedtls_cipher_id_t cipher, 117 const unsigned char *key, 118 unsigned int keybits); 119 120 /** 121 * \brief This function releases and clears the specified CCM context 122 * and underlying cipher sub-context. 123 * 124 * \param ctx The CCM context to clear. If this is \c NULL, the function 125 * has no effect. Otherwise, this must be initialized. 126 */ 127 void mbedtls_ccm_free(mbedtls_ccm_context *ctx); 128 129 /** 130 * \brief This function encrypts a buffer using CCM. 131 * 132 * \note The tag is written to a separate buffer. To concatenate 133 * the \p tag with the \p output, as done in <em>RFC-3610: 134 * Counter with CBC-MAC (CCM)</em>, use 135 * \p tag = \p output + \p length, and make sure that the 136 * output buffer is at least \p length + \p tag_len wide. 137 * 138 * \param ctx The CCM context to use for encryption. This must be 139 * initialized and bound to a key. 140 * \param length The length of the input data in Bytes. 141 * \param iv The initialization vector (nonce). This must be a readable 142 * buffer of at least \p iv_len Bytes. 143 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 144 * or 13. The length L of the message length field is 145 * 15 - \p iv_len. 146 * \param ad The additional data field. If \p ad_len is greater than 147 * zero, \p ad must be a readable buffer of at least that 148 * length. 149 * \param ad_len The length of additional data in Bytes. 150 * This must be less than `2^16 - 2^8`. 151 * \param input The buffer holding the input data. If \p length is greater 152 * than zero, \p input must be a readable buffer of at least 153 * that length. 154 * \param output The buffer holding the output data. If \p length is greater 155 * than zero, \p output must be a writable buffer of at least 156 * that length. 157 * \param tag The buffer holding the authentication field. This must be a 158 * writable buffer of at least \p tag_len Bytes. 159 * \param tag_len The length of the authentication field to generate in Bytes: 160 * 4, 6, 8, 10, 12, 14 or 16. 161 * 162 * \return \c 0 on success. 163 * \return A CCM or cipher-specific error code on failure. 164 */ 165 int mbedtls_ccm_encrypt_and_tag(mbedtls_ccm_context *ctx, size_t length, 166 const unsigned char *iv, size_t iv_len, 167 const unsigned char *ad, size_t ad_len, 168 const unsigned char *input, unsigned char *output, 169 unsigned char *tag, size_t tag_len); 170 171 /** 172 * \brief This function encrypts a buffer using CCM*. 173 * 174 * \note The tag is written to a separate buffer. To concatenate 175 * the \p tag with the \p output, as done in <em>RFC-3610: 176 * Counter with CBC-MAC (CCM)</em>, use 177 * \p tag = \p output + \p length, and make sure that the 178 * output buffer is at least \p length + \p tag_len wide. 179 * 180 * \note When using this function in a variable tag length context, 181 * the tag length has to be encoded into the \p iv passed to 182 * this function. 183 * 184 * \param ctx The CCM context to use for encryption. This must be 185 * initialized and bound to a key. 186 * \param length The length of the input data in Bytes. 187 * For tag length = 0, input length is ignored. 188 * \param iv The initialization vector (nonce). This must be a readable 189 * buffer of at least \p iv_len Bytes. 190 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 191 * or 13. The length L of the message length field is 192 * 15 - \p iv_len. 193 * \param ad The additional data field. This must be a readable buffer of 194 * at least \p ad_len Bytes. 195 * \param ad_len The length of additional data in Bytes. 196 * This must be less than 2^16 - 2^8. 197 * \param input The buffer holding the input data. If \p length is greater 198 * than zero, \p input must be a readable buffer of at least 199 * that length. 200 * \param output The buffer holding the output data. If \p length is greater 201 * than zero, \p output must be a writable buffer of at least 202 * that length. 203 * \param tag The buffer holding the authentication field. This must be a 204 * writable buffer of at least \p tag_len Bytes. 205 * \param tag_len The length of the authentication field to generate in Bytes: 206 * 0, 4, 6, 8, 10, 12, 14 or 16. 207 * 208 * \warning Passing \c 0 as \p tag_len means that the message is no 209 * longer authenticated. 210 * 211 * \return \c 0 on success. 212 * \return A CCM or cipher-specific error code on failure. 213 */ 214 int mbedtls_ccm_star_encrypt_and_tag(mbedtls_ccm_context *ctx, size_t length, 215 const unsigned char *iv, size_t iv_len, 216 const unsigned char *ad, size_t ad_len, 217 const unsigned char *input, unsigned char *output, 218 unsigned char *tag, size_t tag_len); 219 220 /** 221 * \brief This function performs a CCM authenticated decryption of a 222 * buffer. 223 * 224 * \param ctx The CCM context to use for decryption. This must be 225 * initialized and bound to a key. 226 * \param length The length of the input data in Bytes. 227 * \param iv The initialization vector (nonce). This must be a readable 228 * buffer of at least \p iv_len Bytes. 229 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 230 * or 13. The length L of the message length field is 231 * 15 - \p iv_len. 232 * \param ad The additional data field. This must be a readable buffer 233 * of at least that \p ad_len Bytes.. 234 * \param ad_len The length of additional data in Bytes. 235 * This must be less than 2^16 - 2^8. 236 * \param input The buffer holding the input data. If \p length is greater 237 * than zero, \p input must be a readable buffer of at least 238 * that length. 239 * \param output The buffer holding the output data. If \p length is greater 240 * than zero, \p output must be a writable buffer of at least 241 * that length. 242 * \param tag The buffer holding the authentication field. This must be a 243 * readable buffer of at least \p tag_len Bytes. 244 * \param tag_len The length of the authentication field to generate in Bytes: 245 * 4, 6, 8, 10, 12, 14 or 16. 246 * 247 * \return \c 0 on success. This indicates that the message is authentic. 248 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 249 * \return A cipher-specific error code on calculation failure. 250 */ 251 int mbedtls_ccm_auth_decrypt(mbedtls_ccm_context *ctx, size_t length, 252 const unsigned char *iv, size_t iv_len, 253 const unsigned char *ad, size_t ad_len, 254 const unsigned char *input, unsigned char *output, 255 const unsigned char *tag, size_t tag_len); 256 257 /** 258 * \brief This function performs a CCM* authenticated decryption of a 259 * buffer. 260 * 261 * \note When using this function in a variable tag length context, 262 * the tag length has to be decoded from \p iv and passed to 263 * this function as \p tag_len. (\p tag needs to be adjusted 264 * accordingly.) 265 * 266 * \param ctx The CCM context to use for decryption. This must be 267 * initialized and bound to a key. 268 * \param length The length of the input data in Bytes. 269 * For tag length = 0, input length is ignored. 270 * \param iv The initialization vector (nonce). This must be a readable 271 * buffer of at least \p iv_len Bytes. 272 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 273 * or 13. The length L of the message length field is 274 * 15 - \p iv_len. 275 * \param ad The additional data field. This must be a readable buffer of 276 * at least that \p ad_len Bytes. 277 * \param ad_len The length of additional data in Bytes. 278 * This must be less than 2^16 - 2^8. 279 * \param input The buffer holding the input data. If \p length is greater 280 * than zero, \p input must be a readable buffer of at least 281 * that length. 282 * \param output The buffer holding the output data. If \p length is greater 283 * than zero, \p output must be a writable buffer of at least 284 * that length. 285 * \param tag The buffer holding the authentication field. This must be a 286 * readable buffer of at least \p tag_len Bytes. 287 * \param tag_len The length of the authentication field in Bytes. 288 * 0, 4, 6, 8, 10, 12, 14 or 16. 289 * 290 * \warning Passing \c 0 as \p tag_len means that the message is nos 291 * longer authenticated. 292 * 293 * \return \c 0 on success. 294 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 295 * \return A cipher-specific error code on calculation failure. 296 */ 297 int mbedtls_ccm_star_auth_decrypt(mbedtls_ccm_context *ctx, size_t length, 298 const unsigned char *iv, size_t iv_len, 299 const unsigned char *ad, size_t ad_len, 300 const unsigned char *input, unsigned char *output, 301 const unsigned char *tag, size_t tag_len); 302 303 /** 304 * \brief This function starts a CCM encryption or decryption 305 * operation. 306 * 307 * This function and mbedtls_ccm_set_lengths() must be called 308 * before calling mbedtls_ccm_update_ad() or 309 * mbedtls_ccm_update(). This function can be called before 310 * or after mbedtls_ccm_set_lengths(). 311 * 312 * \note This function is not implemented in Mbed TLS yet. 313 * 314 * \param ctx The CCM context. This must be initialized. 315 * \param mode The operation to perform: #MBEDTLS_CCM_ENCRYPT or 316 * #MBEDTLS_CCM_DECRYPT or #MBEDTLS_CCM_STAR_ENCRYPT or 317 * #MBEDTLS_CCM_STAR_DECRYPT. 318 * \param iv The initialization vector. This must be a readable buffer 319 * of at least \p iv_len Bytes. 320 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 321 * or 13. The length L of the message length field is 322 * 15 - \p iv_len. 323 * 324 * \return \c 0 on success. 325 * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: 326 * \p ctx is in an invalid state, 327 * \p mode is invalid, 328 * \p iv_len is invalid (lower than \c 7 or greater than 329 * \c 13). 330 */ 331 int mbedtls_ccm_starts(mbedtls_ccm_context *ctx, 332 int mode, 333 const unsigned char *iv, 334 size_t iv_len); 335 336 /** 337 * \brief This function declares the lengths of the message 338 * and additional data for a CCM encryption or decryption 339 * operation. 340 * 341 * This function and mbedtls_ccm_starts() must be called 342 * before calling mbedtls_ccm_update_ad() or 343 * mbedtls_ccm_update(). This function can be called before 344 * or after mbedtls_ccm_starts(). 345 * 346 * \note This function is not implemented in Mbed TLS yet. 347 * 348 * \param ctx The CCM context. This must be initialized. 349 * \param total_ad_len The total length of additional data in bytes. 350 * This must be less than `2^16 - 2^8`. 351 * \param plaintext_len The length in bytes of the plaintext to encrypt or 352 * result of the decryption (thus not encompassing the 353 * additional data that are not encrypted). 354 * \param tag_len The length of the tag to generate in Bytes: 355 * 4, 6, 8, 10, 12, 14 or 16. 356 * For CCM*, zero is also valid. 357 * 358 * \return \c 0 on success. 359 * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: 360 * \p ctx is in an invalid state, 361 * \p total_ad_len is greater than \c 0xFF00. 362 */ 363 int mbedtls_ccm_set_lengths(mbedtls_ccm_context *ctx, 364 size_t total_ad_len, 365 size_t plaintext_len, 366 size_t tag_len); 367 368 /** 369 * \brief This function feeds an input buffer as associated data 370 * (authenticated but not encrypted data) in a CCM 371 * encryption or decryption operation. 372 * 373 * You may call this function zero, one or more times 374 * to pass successive parts of the additional data. The 375 * lengths \p ad_len of the data parts should eventually add 376 * up exactly to the total length of additional data 377 * \c total_ad_len passed to mbedtls_ccm_set_lengths(). You 378 * may not call this function after calling 379 * mbedtls_ccm_update(). 380 * 381 * \note This function is not implemented in Mbed TLS yet. 382 * 383 * \param ctx The CCM context. This must have been started with 384 * mbedtls_ccm_starts(), the lengths of the message and 385 * additional data must have been declared with 386 * mbedtls_ccm_set_lengths() and this must not have yet 387 * received any input with mbedtls_ccm_update(). 388 * \param ad The buffer holding the additional data, or \c NULL 389 * if \p ad_len is \c 0. 390 * \param ad_len The length of the additional data. If \c 0, 391 * \p ad may be \c NULL. 392 * 393 * \return \c 0 on success. 394 * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: 395 * \p ctx is in an invalid state, 396 * total input length too long. 397 */ 398 int mbedtls_ccm_update_ad(mbedtls_ccm_context *ctx, 399 const unsigned char *ad, 400 size_t ad_len); 401 402 /** 403 * \brief This function feeds an input buffer into an ongoing CCM 404 * encryption or decryption operation. 405 * 406 * You may call this function zero, one or more times 407 * to pass successive parts of the input: the plaintext to 408 * encrypt, or the ciphertext (not including the tag) to 409 * decrypt. After the last part of the input, call 410 * mbedtls_ccm_finish(). The lengths \p input_len of the 411 * data parts should eventually add up exactly to the 412 * plaintext length \c plaintext_len passed to 413 * mbedtls_ccm_set_lengths(). 414 * 415 * This function may produce output in one of the following 416 * ways: 417 * - Immediate output: the output length is always equal 418 * to the input length. 419 * - Buffered output: except for the last part of input data, 420 * the output consists of a whole number of 16-byte blocks. 421 * If the total input length so far (not including 422 * associated data) is 16 \* *B* + *A* with *A* < 16 then 423 * the total output length is 16 \* *B*. 424 * For the last part of input data, the output length is 425 * equal to the input length plus the number of bytes (*A*) 426 * buffered in the previous call to the function (if any). 427 * The function uses the plaintext length 428 * \c plaintext_len passed to mbedtls_ccm_set_lengths() 429 * to detect the last part of input data. 430 * 431 * In particular: 432 * - It is always correct to call this function with 433 * \p output_size >= \p input_len + 15. 434 * - If \p input_len is a multiple of 16 for all the calls 435 * to this function during an operation (not necessary for 436 * the last one) then it is correct to use \p output_size 437 * =\p input_len. 438 * 439 * \note This function is not implemented in Mbed TLS yet. 440 * 441 * \param ctx The CCM context. This must have been started with 442 * mbedtls_ccm_starts() and the lengths of the message and 443 * additional data must have been declared with 444 * mbedtls_ccm_set_lengths(). 445 * \param input The buffer holding the input data. If \p input_len 446 * is greater than zero, this must be a readable buffer 447 * of at least \p input_len bytes. 448 * \param input_len The length of the input data in bytes. 449 * \param output The buffer for the output data. If \p output_size 450 * is greater than zero, this must be a writable buffer of 451 * at least \p output_size bytes. 452 * \param output_size The size of the output buffer in bytes. 453 * See the function description regarding the output size. 454 * \param output_len On success, \p *output_len contains the actual 455 * length of the output written in \p output. 456 * On failure, the content of \p *output_len is 457 * unspecified. 458 * 459 * \return \c 0 on success. 460 * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: 461 * \p ctx is in an invalid state, 462 * total input length too long, 463 * or \p output_size too small. 464 */ 465 int mbedtls_ccm_update(mbedtls_ccm_context *ctx, 466 const unsigned char *input, size_t input_len, 467 unsigned char *output, size_t output_size, 468 size_t *output_len); 469 470 /** 471 * \brief This function finishes the CCM operation and generates 472 * the authentication tag. 473 * 474 * It wraps up the CCM stream, and generates the 475 * tag. The tag can have a maximum length of 16 Bytes. 476 * 477 * \note This function is not implemented in Mbed TLS yet. 478 * 479 * \param ctx The CCM context. This must have been started with 480 * mbedtls_ccm_starts() and the lengths of the message and 481 * additional data must have been declared with 482 * mbedtls_ccm_set_lengths(). 483 * \param tag The buffer for holding the tag. If \p tag_len is greater 484 * than zero, this must be a writable buffer of at least \p 485 * tag_len Bytes. 486 * \param tag_len The length of the tag. Must match the tag length passed to 487 * mbedtls_ccm_set_lengths() function. 488 * 489 * \return \c 0 on success. 490 * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: 491 * \p ctx is in an invalid state, 492 * invalid value of \p tag_len, 493 * the total amount of additional data passed to 494 * mbedtls_ccm_update_ad() was lower than the total length of 495 * additional data \c total_ad_len passed to 496 * mbedtls_ccm_set_lengths(), 497 * the total amount of input data passed to 498 * mbedtls_ccm_update() was lower than the plaintext length 499 * \c plaintext_len passed to mbedtls_ccm_set_lengths(). 500 */ 501 int mbedtls_ccm_finish(mbedtls_ccm_context *ctx, 502 unsigned char *tag, size_t tag_len); 503 504 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C) 505 /** 506 * \brief The CCM checkup routine. 507 * 508 * \return \c 0 on success. 509 * \return \c 1 on failure. 510 */ 511 int mbedtls_ccm_self_test(int verbose); 512 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */ 513 514 #ifdef __cplusplus 515 } 516 #endif 517 518 #endif /* MBEDTLS_CCM_H */ 519
