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