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