EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-05-10 08:44:50
0001 /** 0002 * \file ccm.h 0003 * 0004 * \brief This file provides an API for the CCM authenticated encryption 0005 * mode for block ciphers. 0006 * 0007 * CCM combines Counter mode encryption with CBC-MAC authentication 0008 * for 128-bit block ciphers. 0009 * 0010 * Input to CCM includes the following elements: 0011 * <ul><li>Payload - data that is both authenticated and encrypted.</li> 0012 * <li>Associated data (Adata) - data that is authenticated but not 0013 * encrypted, For example, a header.</li> 0014 * <li>Nonce - A unique value that is assigned to the payload and the 0015 * associated data.</li></ul> 0016 * 0017 * Definition of CCM: 0018 * http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf 0019 * RFC 3610 "Counter with CBC-MAC (CCM)" 0020 * 0021 * Related: 0022 * RFC 5116 "An Interface and Algorithms for Authenticated Encryption" 0023 * 0024 * Definition of CCM*: 0025 * IEEE 802.15.4 - IEEE Standard for Local and metropolitan area networks 0026 * Integer representation is fixed most-significant-octet-first order and 0027 * the representation of octets is most-significant-bit-first order. This is 0028 * consistent with RFC 3610. 0029 */ 0030 /* 0031 * Copyright The Mbed TLS Contributors 0032 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 0033 */ 0034 0035 #ifndef MBEDTLS_CCM_H 0036 #define MBEDTLS_CCM_H 0037 #include "mbedtls/private_access.h" 0038 0039 #include "tf-psa-crypto/build_info.h" 0040 0041 #include "mbedtls/private/cipher.h" 0042 0043 #if defined(MBEDTLS_BLOCK_CIPHER_C) 0044 #include "mbedtls/private/block_cipher.h" 0045 #endif 0046 0047 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS) 0048 #define MBEDTLS_CCM_DECRYPT 0 0049 #define MBEDTLS_CCM_ENCRYPT 1 0050 #define MBEDTLS_CCM_STAR_DECRYPT 2 0051 #define MBEDTLS_CCM_STAR_ENCRYPT 3 0052 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */ 0053 0054 /** Bad input parameters to the function. */ 0055 #define MBEDTLS_ERR_CCM_BAD_INPUT PSA_ERROR_INVALID_ARGUMENT 0056 /** Authenticated decryption failed. */ 0057 #define MBEDTLS_ERR_CCM_AUTH_FAILED PSA_ERROR_INVALID_SIGNATURE 0058 0059 #ifdef __cplusplus 0060 extern "C" { 0061 #endif 0062 0063 /** 0064 * \brief The CCM context-type definition. The CCM context is passed 0065 * to the APIs called. 0066 */ 0067 typedef struct mbedtls_ccm_context { 0068 unsigned char MBEDTLS_PRIVATE(y)[16]; /*!< The Y working buffer */ 0069 unsigned char MBEDTLS_PRIVATE(ctr)[16]; /*!< The counter buffer */ 0070 size_t MBEDTLS_PRIVATE(plaintext_len); /*!< Total plaintext length */ 0071 size_t MBEDTLS_PRIVATE(add_len); /*!< Total authentication data length */ 0072 size_t MBEDTLS_PRIVATE(tag_len); /*!< Total tag length */ 0073 size_t MBEDTLS_PRIVATE(processed); /*!< Track how many bytes of input data 0074 were processed (chunked input). 0075 Used independently for both auth data 0076 and plaintext/ciphertext. 0077 This variable is set to zero after 0078 auth data input is finished. */ 0079 unsigned int MBEDTLS_PRIVATE(q); /*!< The Q working value */ 0080 unsigned int MBEDTLS_PRIVATE(mode); /*!< The operation to perform: 0081 MBEDTLS_CCM_ENCRYPT or 0082 MBEDTLS_CCM_DECRYPT or 0083 MBEDTLS_CCM_STAR_ENCRYPT or 0084 MBEDTLS_CCM_STAR_DECRYPT. */ 0085 #if defined(MBEDTLS_BLOCK_CIPHER_C) 0086 mbedtls_block_cipher_context_t MBEDTLS_PRIVATE(block_cipher_ctx); /*!< The cipher context used. */ 0087 #else 0088 mbedtls_cipher_context_t MBEDTLS_PRIVATE(cipher_ctx); /*!< The cipher context used. */ 0089 #endif 0090 int MBEDTLS_PRIVATE(state); /*!< Working value holding context's 0091 state. Used for chunked data input */ 0092 } 0093 mbedtls_ccm_context; 0094 0095 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS) 0096 /** 0097 * \brief This function initializes the specified CCM context, 0098 * to make references valid, and prepare the context 0099 * for mbedtls_ccm_setkey() or mbedtls_ccm_free(). 0100 * 0101 * \param ctx The CCM context to initialize. This must not be \c NULL. 0102 */ 0103 void mbedtls_ccm_init(mbedtls_ccm_context *ctx); 0104 0105 /** 0106 * \brief This function initializes the CCM context set in the 0107 * \p ctx parameter and sets the encryption key. 0108 * 0109 * \param ctx The CCM context to initialize. This must be an initialized 0110 * context. 0111 * \param cipher The 128-bit block cipher to use. 0112 * \param key The encryption key. This must not be \c NULL. 0113 * \param keybits The key size in bits. This must be acceptable by the cipher. 0114 * 0115 * \return \c 0 on success. 0116 * \return A CCM or cipher-specific error code on failure. 0117 */ 0118 int mbedtls_ccm_setkey(mbedtls_ccm_context *ctx, 0119 mbedtls_cipher_id_t cipher, 0120 const unsigned char *key, 0121 unsigned int keybits); 0122 0123 /** 0124 * \brief This function releases and clears the specified CCM context 0125 * and underlying cipher sub-context. 0126 * 0127 * \param ctx The CCM context to clear. If this is \c NULL, the function 0128 * has no effect. Otherwise, this must be initialized. 0129 */ 0130 void mbedtls_ccm_free(mbedtls_ccm_context *ctx); 0131 0132 /** 0133 * \brief This function encrypts a buffer using CCM. 0134 * 0135 * \note The tag is written to a separate buffer. To concatenate 0136 * the \p tag with the \p output, as done in <em>RFC-3610: 0137 * Counter with CBC-MAC (CCM)</em>, use 0138 * \p tag = \p output + \p length, and make sure that the 0139 * output buffer is at least \p length + \p tag_len wide. 0140 * 0141 * \param ctx The CCM context to use for encryption. This must be 0142 * initialized and bound to a key. 0143 * \param length The length of the input data in Bytes. 0144 * \param iv The initialization vector (nonce). This must be a readable 0145 * buffer of at least \p iv_len Bytes. 0146 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 0147 * or 13. The length L of the message length field is 0148 * 15 - \p iv_len. 0149 * \param ad The additional data field. If \p ad_len is greater than 0150 * zero, \p ad must be a readable buffer of at least that 0151 * length. 0152 * \param ad_len The length of additional data in Bytes. 0153 * This must be less than `2^16 - 2^8`. 0154 * \param input The buffer holding the input data. If \p length is greater 0155 * than zero, \p input must be a readable buffer of at least 0156 * that length. 0157 * \param output The buffer holding the output data. If \p length is greater 0158 * than zero, \p output must be a writable buffer of at least 0159 * that length. 0160 * \param tag The buffer holding the authentication field. This must be a 0161 * writable buffer of at least \p tag_len Bytes. 0162 * \param tag_len The length of the authentication field to generate in Bytes: 0163 * 4, 6, 8, 10, 12, 14 or 16. 0164 * 0165 * \return \c 0 on success. 0166 * \return A CCM or cipher-specific error code on failure. 0167 */ 0168 int mbedtls_ccm_encrypt_and_tag(mbedtls_ccm_context *ctx, size_t length, 0169 const unsigned char *iv, size_t iv_len, 0170 const unsigned char *ad, size_t ad_len, 0171 const unsigned char *input, unsigned char *output, 0172 unsigned char *tag, size_t tag_len); 0173 0174 /** 0175 * \brief This function encrypts a buffer using CCM*. 0176 * 0177 * \note The tag is written to a separate buffer. To concatenate 0178 * the \p tag with the \p output, as done in <em>RFC-3610: 0179 * Counter with CBC-MAC (CCM)</em>, use 0180 * \p tag = \p output + \p length, and make sure that the 0181 * output buffer is at least \p length + \p tag_len wide. 0182 * 0183 * \note When using this function in a variable tag length context, 0184 * the tag length has to be encoded into the \p iv passed to 0185 * this function. 0186 * 0187 * \param ctx The CCM context to use for encryption. This must be 0188 * initialized and bound to a key. 0189 * \param length The length of the input data in Bytes. 0190 * For tag length = 0, input length is ignored. 0191 * \param iv The initialization vector (nonce). This must be a readable 0192 * buffer of at least \p iv_len Bytes. 0193 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 0194 * or 13. The length L of the message length field is 0195 * 15 - \p iv_len. 0196 * \param ad The additional data field. This must be a readable buffer of 0197 * at least \p ad_len Bytes. 0198 * \param ad_len The length of additional data in Bytes. 0199 * This must be less than 2^16 - 2^8. 0200 * \param input The buffer holding the input data. If \p length is greater 0201 * than zero, \p input must be a readable buffer of at least 0202 * that length. 0203 * \param output The buffer holding the output data. If \p length is greater 0204 * than zero, \p output must be a writable buffer of at least 0205 * that length. 0206 * \param tag The buffer holding the authentication field. This must be a 0207 * writable buffer of at least \p tag_len Bytes. 0208 * \param tag_len The length of the authentication field to generate in Bytes: 0209 * 0, 4, 6, 8, 10, 12, 14 or 16. 0210 * 0211 * \warning Passing \c 0 as \p tag_len means that the message is no 0212 * longer authenticated. 0213 * 0214 * \return \c 0 on success. 0215 * \return A CCM or cipher-specific error code on failure. 0216 */ 0217 int mbedtls_ccm_star_encrypt_and_tag(mbedtls_ccm_context *ctx, size_t length, 0218 const unsigned char *iv, size_t iv_len, 0219 const unsigned char *ad, size_t ad_len, 0220 const unsigned char *input, unsigned char *output, 0221 unsigned char *tag, size_t tag_len); 0222 0223 /** 0224 * \brief This function performs a CCM authenticated decryption of a 0225 * buffer. 0226 * 0227 * \param ctx The CCM context to use for decryption. This must be 0228 * initialized and bound to a key. 0229 * \param length The length of the input data in Bytes. 0230 * \param iv The initialization vector (nonce). This must be a readable 0231 * buffer of at least \p iv_len Bytes. 0232 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 0233 * or 13. The length L of the message length field is 0234 * 15 - \p iv_len. 0235 * \param ad The additional data field. This must be a readable buffer 0236 * of at least that \p ad_len Bytes.. 0237 * \param ad_len The length of additional data in Bytes. 0238 * This must be less than 2^16 - 2^8. 0239 * \param input The buffer holding the input data. If \p length is greater 0240 * than zero, \p input must be a readable buffer of at least 0241 * that length. 0242 * \param output The buffer holding the output data. If \p length is greater 0243 * than zero, \p output must be a writable buffer of at least 0244 * that length. 0245 * \param tag The buffer holding the authentication field. This must be a 0246 * readable buffer of at least \p tag_len Bytes. 0247 * \param tag_len The length of the authentication field to generate in Bytes: 0248 * 4, 6, 8, 10, 12, 14 or 16. 0249 * 0250 * \return \c 0 on success. This indicates that the message is authentic. 0251 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 0252 * \return A cipher-specific error code on calculation failure. 0253 */ 0254 int mbedtls_ccm_auth_decrypt(mbedtls_ccm_context *ctx, size_t length, 0255 const unsigned char *iv, size_t iv_len, 0256 const unsigned char *ad, size_t ad_len, 0257 const unsigned char *input, unsigned char *output, 0258 const unsigned char *tag, size_t tag_len); 0259 0260 /** 0261 * \brief This function performs a CCM* authenticated decryption of a 0262 * buffer. 0263 * 0264 * \note When using this function in a variable tag length context, 0265 * the tag length has to be decoded from \p iv and passed to 0266 * this function as \p tag_len. (\p tag needs to be adjusted 0267 * accordingly.) 0268 * 0269 * \param ctx The CCM context to use for decryption. This must be 0270 * initialized and bound to a key. 0271 * \param length The length of the input data in Bytes. 0272 * For tag length = 0, input length is ignored. 0273 * \param iv The initialization vector (nonce). This must be a readable 0274 * buffer of at least \p iv_len Bytes. 0275 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 0276 * or 13. The length L of the message length field is 0277 * 15 - \p iv_len. 0278 * \param ad The additional data field. This must be a readable buffer of 0279 * at least that \p ad_len Bytes. 0280 * \param ad_len The length of additional data in Bytes. 0281 * This must be less than 2^16 - 2^8. 0282 * \param input The buffer holding the input data. If \p length is greater 0283 * than zero, \p input must be a readable buffer of at least 0284 * that length. 0285 * \param output The buffer holding the output data. If \p length is greater 0286 * than zero, \p output must be a writable buffer of at least 0287 * that length. 0288 * \param tag The buffer holding the authentication field. This must be a 0289 * readable buffer of at least \p tag_len Bytes. 0290 * \param tag_len The length of the authentication field in Bytes. 0291 * 0, 4, 6, 8, 10, 12, 14 or 16. 0292 * 0293 * \warning Passing \c 0 as \p tag_len means that the message is nos 0294 * longer authenticated. 0295 * 0296 * \return \c 0 on success. 0297 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 0298 * \return A cipher-specific error code on calculation failure. 0299 */ 0300 int mbedtls_ccm_star_auth_decrypt(mbedtls_ccm_context *ctx, size_t length, 0301 const unsigned char *iv, size_t iv_len, 0302 const unsigned char *ad, size_t ad_len, 0303 const unsigned char *input, unsigned char *output, 0304 const unsigned char *tag, size_t tag_len); 0305 0306 /** 0307 * \brief This function starts a CCM encryption or decryption 0308 * operation. 0309 * 0310 * This function and mbedtls_ccm_set_lengths() must be called 0311 * before calling mbedtls_ccm_update_ad() or 0312 * mbedtls_ccm_update(). This function can be called before 0313 * or after mbedtls_ccm_set_lengths(). 0314 * 0315 * \note This function is not implemented in Mbed TLS yet. 0316 * 0317 * \param ctx The CCM context. This must be initialized. 0318 * \param mode The operation to perform: MBEDTLS_CCM_ENCRYPT or 0319 * MBEDTLS_CCM_DECRYPT or MBEDTLS_CCM_STAR_ENCRYPT or 0320 * MBEDTLS_CCM_STAR_DECRYPT. 0321 * \param iv The initialization vector. This must be a readable buffer 0322 * of at least \p iv_len Bytes. 0323 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 0324 * or 13. The length L of the message length field is 0325 * 15 - \p iv_len. 0326 * 0327 * \return \c 0 on success. 0328 * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: 0329 * \p ctx is in an invalid state, 0330 * \p mode is invalid, 0331 * \p iv_len is invalid (lower than \c 7 or greater than 0332 * \c 13). 0333 */ 0334 int mbedtls_ccm_starts(mbedtls_ccm_context *ctx, 0335 int mode, 0336 const unsigned char *iv, 0337 size_t iv_len); 0338 0339 /** 0340 * \brief This function declares the lengths of the message 0341 * and additional data for a CCM encryption or decryption 0342 * operation. 0343 * 0344 * This function and mbedtls_ccm_starts() must be called 0345 * before calling mbedtls_ccm_update_ad() or 0346 * mbedtls_ccm_update(). This function can be called before 0347 * or after mbedtls_ccm_starts(). 0348 * 0349 * \note This function is not implemented in Mbed TLS yet. 0350 * 0351 * \param ctx The CCM context. This must be initialized. 0352 * \param total_ad_len The total length of additional data in bytes. 0353 * This must be less than `2^16 - 2^8`. 0354 * \param plaintext_len The length in bytes of the plaintext to encrypt or 0355 * result of the decryption (thus not encompassing the 0356 * additional data that are not encrypted). 0357 * \param tag_len The length of the tag to generate in Bytes: 0358 * 4, 6, 8, 10, 12, 14 or 16. 0359 * For CCM*, zero is also valid. 0360 * 0361 * \return \c 0 on success. 0362 * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: 0363 * \p ctx is in an invalid state, 0364 * \p total_ad_len is greater than \c 0xFF00. 0365 */ 0366 int mbedtls_ccm_set_lengths(mbedtls_ccm_context *ctx, 0367 size_t total_ad_len, 0368 size_t plaintext_len, 0369 size_t tag_len); 0370 0371 /** 0372 * \brief This function feeds an input buffer as associated data 0373 * (authenticated but not encrypted data) in a CCM 0374 * encryption or decryption operation. 0375 * 0376 * You may call this function zero, one or more times 0377 * to pass successive parts of the additional data. The 0378 * lengths \p ad_len of the data parts should eventually add 0379 * up exactly to the total length of additional data 0380 * \c total_ad_len passed to mbedtls_ccm_set_lengths(). You 0381 * may not call this function after calling 0382 * mbedtls_ccm_update(). 0383 * 0384 * \note This function is not implemented in Mbed TLS yet. 0385 * 0386 * \param ctx The CCM context. This must have been started with 0387 * mbedtls_ccm_starts(), the lengths of the message and 0388 * additional data must have been declared with 0389 * mbedtls_ccm_set_lengths() and this must not have yet 0390 * received any input with mbedtls_ccm_update(). 0391 * \param ad The buffer holding the additional data, or \c NULL 0392 * if \p ad_len is \c 0. 0393 * \param ad_len The length of the additional data. If \c 0, 0394 * \p ad may be \c NULL. 0395 * 0396 * \return \c 0 on success. 0397 * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: 0398 * \p ctx is in an invalid state, 0399 * total input length too long. 0400 */ 0401 int mbedtls_ccm_update_ad(mbedtls_ccm_context *ctx, 0402 const unsigned char *ad, 0403 size_t ad_len); 0404 0405 /** 0406 * \brief This function feeds an input buffer into an ongoing CCM 0407 * encryption or decryption operation. 0408 * 0409 * You may call this function zero, one or more times 0410 * to pass successive parts of the input: the plaintext to 0411 * encrypt, or the ciphertext (not including the tag) to 0412 * decrypt. After the last part of the input, call 0413 * mbedtls_ccm_finish(). The lengths \p input_len of the 0414 * data parts should eventually add up exactly to the 0415 * plaintext length \c plaintext_len passed to 0416 * mbedtls_ccm_set_lengths(). 0417 * 0418 * This function may produce output in one of the following 0419 * ways: 0420 * - Immediate output: the output length is always equal 0421 * to the input length. 0422 * - Buffered output: except for the last part of input data, 0423 * the output consists of a whole number of 16-byte blocks. 0424 * If the total input length so far (not including 0425 * associated data) is 16 \* *B* + *A* with *A* < 16 then 0426 * the total output length is 16 \* *B*. 0427 * For the last part of input data, the output length is 0428 * equal to the input length plus the number of bytes (*A*) 0429 * buffered in the previous call to the function (if any). 0430 * The function uses the plaintext length 0431 * \c plaintext_len passed to mbedtls_ccm_set_lengths() 0432 * to detect the last part of input data. 0433 * 0434 * In particular: 0435 * - It is always correct to call this function with 0436 * \p output_size >= \p input_len + 15. 0437 * - If \p input_len is a multiple of 16 for all the calls 0438 * to this function during an operation (not necessary for 0439 * the last one) then it is correct to use \p output_size 0440 * =\p input_len. 0441 * 0442 * \note This function is not implemented in Mbed TLS yet. 0443 * 0444 * \param ctx The CCM context. This must have been started with 0445 * mbedtls_ccm_starts() and the lengths of the message and 0446 * additional data must have been declared with 0447 * mbedtls_ccm_set_lengths(). 0448 * \param input The buffer holding the input data. If \p input_len 0449 * is greater than zero, this must be a readable buffer 0450 * of at least \p input_len bytes. 0451 * \param input_len The length of the input data in bytes. 0452 * \param output The buffer for the output data. If \p output_size 0453 * is greater than zero, this must be a writable buffer of 0454 * at least \p output_size bytes. 0455 * \param output_size The size of the output buffer in bytes. 0456 * See the function description regarding the output size. 0457 * \param output_len On success, \p *output_len contains the actual 0458 * length of the output written in \p output. 0459 * On failure, the content of \p *output_len is 0460 * unspecified. 0461 * 0462 * \return \c 0 on success. 0463 * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: 0464 * \p ctx is in an invalid state, 0465 * total input length too long, 0466 * or \p output_size too small. 0467 */ 0468 int mbedtls_ccm_update(mbedtls_ccm_context *ctx, 0469 const unsigned char *input, size_t input_len, 0470 unsigned char *output, size_t output_size, 0471 size_t *output_len); 0472 0473 /** 0474 * \brief This function finishes the CCM operation and generates 0475 * the authentication tag. 0476 * 0477 * It wraps up the CCM stream, and generates the 0478 * tag. The tag can have a maximum length of 16 Bytes. 0479 * 0480 * \note This function is not implemented in Mbed TLS yet. 0481 * 0482 * \param ctx The CCM context. This must have been started with 0483 * mbedtls_ccm_starts() and the lengths of the message and 0484 * additional data must have been declared with 0485 * mbedtls_ccm_set_lengths(). 0486 * \param tag The buffer for holding the tag. If \p tag_len is greater 0487 * than zero, this must be a writable buffer of at least \p 0488 * tag_len Bytes. 0489 * \param tag_len The length of the tag. Must match the tag length passed to 0490 * mbedtls_ccm_set_lengths() function. 0491 * 0492 * \return \c 0 on success. 0493 * \return #MBEDTLS_ERR_CCM_BAD_INPUT on failure: 0494 * \p ctx is in an invalid state, 0495 * invalid value of \p tag_len, 0496 * the total amount of additional data passed to 0497 * mbedtls_ccm_update_ad() was lower than the total length of 0498 * additional data \c total_ad_len passed to 0499 * mbedtls_ccm_set_lengths(), 0500 * the total amount of input data passed to 0501 * mbedtls_ccm_update() was lower than the plaintext length 0502 * \c plaintext_len passed to mbedtls_ccm_set_lengths(). 0503 */ 0504 int mbedtls_ccm_finish(mbedtls_ccm_context *ctx, 0505 unsigned char *tag, size_t tag_len); 0506 0507 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_CCM_GCM_CAN_AES) 0508 /** 0509 * \brief The CCM checkup routine. 0510 * 0511 * \return \c 0 on success. 0512 * \return \c 1 on failure. 0513 */ 0514 int mbedtls_ccm_self_test(int verbose); 0515 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */ 0516 0517 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */ 0518 0519 #ifdef __cplusplus 0520 } 0521 #endif 0522 0523 #endif /* MBEDTLS_CCM_H */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|