psa_crypto_aead.h (23895B)
1 /* 2 * PSA AEAD driver entry points 3 */ 4 /* 5 * Copyright The Mbed TLS Contributors 6 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 7 */ 8 9 #ifndef PSA_CRYPTO_AEAD_H 10 #define PSA_CRYPTO_AEAD_H 11 12 #include <psa/crypto.h> 13 14 /** 15 * \brief Process an authenticated encryption operation. 16 * 17 * \note The signature of this function is that of a PSA driver 18 * aead_encrypt entry point. This function behaves as an aead_encrypt 19 * entry point as defined in the PSA driver interface specification for 20 * transparent drivers. 21 * 22 * \param[in] attributes The attributes of the key to use for the 23 * operation. 24 * \param[in] key_buffer The buffer containing the key context. 25 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 26 * \param alg The AEAD algorithm to compute. 27 * \param[in] nonce Nonce or IV to use. 28 * \param nonce_length Size of the nonce buffer in bytes. This must 29 * be appropriate for the selected algorithm. 30 * The default nonce size is 31 * PSA_AEAD_NONCE_LENGTH(key_type, alg) where 32 * key_type is the type of key. 33 * \param[in] additional_data Additional data that will be authenticated 34 * but not encrypted. 35 * \param additional_data_length Size of additional_data in bytes. 36 * \param[in] plaintext Data that will be authenticated and encrypted. 37 * \param plaintext_length Size of plaintext in bytes. 38 * \param[out] ciphertext Output buffer for the authenticated and 39 * encrypted data. The additional data is not 40 * part of this output. For algorithms where the 41 * encrypted data and the authentication tag are 42 * defined as separate outputs, the 43 * authentication tag is appended to the 44 * encrypted data. 45 * \param ciphertext_size Size of the ciphertext buffer in bytes. This 46 * must be appropriate for the selected algorithm 47 * and key: 48 * - A sufficient output size is 49 * PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, 50 * plaintext_length) where key_type is the type 51 * of key. 52 * - PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE( 53 * plaintext_length) evaluates to the maximum 54 * ciphertext size of any supported AEAD 55 * encryption. 56 * \param[out] ciphertext_length On success, the size of the output in the 57 * ciphertext buffer. 58 * 59 * \retval #PSA_SUCCESS Success. 60 * \retval #PSA_ERROR_NOT_SUPPORTED 61 * \p alg is not supported. 62 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 63 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 64 * ciphertext_size is too small. 65 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 66 */ 67 psa_status_t mbedtls_psa_aead_encrypt( 68 const psa_key_attributes_t *attributes, 69 const uint8_t *key_buffer, size_t key_buffer_size, 70 psa_algorithm_t alg, 71 const uint8_t *nonce, size_t nonce_length, 72 const uint8_t *additional_data, size_t additional_data_length, 73 const uint8_t *plaintext, size_t plaintext_length, 74 uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length); 75 76 /** 77 * \brief Process an authenticated decryption operation. 78 * 79 * \note The signature of this function is that of a PSA driver 80 * aead_decrypt entry point. This function behaves as an aead_decrypt 81 * entry point as defined in the PSA driver interface specification for 82 * transparent drivers. 83 * 84 * \param[in] attributes The attributes of the key to use for the 85 * operation. 86 * \param[in] key_buffer The buffer containing the key context. 87 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 88 * \param alg The AEAD algorithm to compute. 89 * \param[in] nonce Nonce or IV to use. 90 * \param nonce_length Size of the nonce buffer in bytes. This must 91 * be appropriate for the selected algorithm. 92 * The default nonce size is 93 * PSA_AEAD_NONCE_LENGTH(key_type, alg) where 94 * key_type is the type of key. 95 * \param[in] additional_data Additional data that has been authenticated 96 * but not encrypted. 97 * \param additional_data_length Size of additional_data in bytes. 98 * \param[in] ciphertext Data that has been authenticated and 99 * encrypted. For algorithms where the encrypted 100 * data and the authentication tag are defined 101 * as separate inputs, the buffer contains 102 * encrypted data followed by the authentication 103 * tag. 104 * \param ciphertext_length Size of ciphertext in bytes. 105 * \param[out] plaintext Output buffer for the decrypted data. 106 * \param plaintext_size Size of the plaintext buffer in bytes. This 107 * must be appropriate for the selected algorithm 108 * and key: 109 * - A sufficient output size is 110 * PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, 111 * ciphertext_length) where key_type is the 112 * type of key. 113 * - PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE( 114 * ciphertext_length) evaluates to the maximum 115 * plaintext size of any supported AEAD 116 * decryption. 117 * \param[out] plaintext_length On success, the size of the output in the 118 * plaintext buffer. 119 * 120 * \retval #PSA_SUCCESS Success. 121 * \retval #PSA_ERROR_INVALID_SIGNATURE 122 * The cipher is not authentic. 123 * \retval #PSA_ERROR_NOT_SUPPORTED 124 * \p alg is not supported. 125 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 126 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 127 * plaintext_size is too small. 128 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 129 */ 130 psa_status_t mbedtls_psa_aead_decrypt( 131 const psa_key_attributes_t *attributes, 132 const uint8_t *key_buffer, size_t key_buffer_size, 133 psa_algorithm_t alg, 134 const uint8_t *nonce, size_t nonce_length, 135 const uint8_t *additional_data, size_t additional_data_length, 136 const uint8_t *ciphertext, size_t ciphertext_length, 137 uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length); 138 139 /** Set the key for a multipart authenticated encryption operation. 140 * 141 * \note The signature of this function is that of a PSA driver 142 * aead_encrypt_setup entry point. This function behaves as an 143 * aead_encrypt_setup entry point as defined in the PSA driver interface 144 * specification for transparent drivers. 145 * 146 * If an error occurs at any step after a call to 147 * mbedtls_psa_aead_encrypt_setup(), the operation is reset by the PSA core by a 148 * call to mbedtls_psa_aead_abort(). The PSA core may call 149 * mbedtls_psa_aead_abort() at any time after the operation has been 150 * initialized, and is required to when the operation is no longer needed. 151 * 152 * \param[in,out] operation The operation object to set up. It must have 153 * been initialized as per the documentation for 154 * #mbedtls_psa_aead_operation_t and not yet in 155 * use. 156 * \param[in] attributes The attributes of the key to use for the 157 * operation. 158 * \param[in] key_buffer The buffer containing the key context. 159 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 160 It must be consistent with the size in bits 161 recorded in \p attributes. 162 * \param alg The AEAD algorithm to compute 163 * (\c PSA_ALG_XXX value such that 164 * #PSA_ALG_IS_AEAD(\p alg) is true). 165 * 166 * \retval #PSA_SUCCESS 167 * Success. 168 * \retval #PSA_ERROR_INVALID_ARGUMENT 169 * An invalid block length was supplied. 170 * \retval #PSA_ERROR_NOT_SUPPORTED 171 * \p alg is not supported. 172 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 173 * Failed to allocate memory for key material 174 */ 175 psa_status_t mbedtls_psa_aead_encrypt_setup( 176 mbedtls_psa_aead_operation_t *operation, 177 const psa_key_attributes_t *attributes, 178 const uint8_t *key_buffer, 179 size_t key_buffer_size, 180 psa_algorithm_t alg); 181 182 /** Set the key for a multipart authenticated decryption operation. 183 * 184 * \note The signature of this function is that of a PSA driver 185 * aead_decrypt_setup entry point. This function behaves as an 186 * aead_decrypt_setup entry point as defined in the PSA driver interface 187 * specification for transparent drivers. 188 * 189 * If an error occurs at any step after a call to 190 * mbedtls_psa_aead_decrypt_setup(), the PSA core resets the operation by a 191 * call to mbedtls_psa_aead_abort(). The PSA core may call 192 * mbedtls_psa_aead_abort() at any time after the operation has been 193 * initialized, and is required to when the operation is no longer needed. 194 * 195 * \param[in,out] operation The operation object to set up. It must have 196 * been initialized as per the documentation for 197 * #mbedtls_psa_aead_operation_t and not yet in 198 * use. 199 * \param[in] attributes The attributes of the key to use for the 200 * operation. 201 * \param[in] key_buffer The buffer containing the key context. 202 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 203 It must be consistent with the size in bits 204 recorded in \p attributes. 205 * \param alg The AEAD algorithm to compute 206 * (\c PSA_ALG_XXX value such that 207 * #PSA_ALG_IS_AEAD(\p alg) is true). 208 * 209 * \retval #PSA_SUCCESS 210 * Success. 211 * \retval #PSA_ERROR_INVALID_ARGUMENT 212 * An invalid block length was supplied. 213 * \retval #PSA_ERROR_NOT_SUPPORTED 214 * \p alg is not supported. 215 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 216 * Failed to allocate memory for key material 217 */ 218 psa_status_t mbedtls_psa_aead_decrypt_setup( 219 mbedtls_psa_aead_operation_t *operation, 220 const psa_key_attributes_t *attributes, 221 const uint8_t *key_buffer, 222 size_t key_buffer_size, 223 psa_algorithm_t alg); 224 225 /** Set the nonce for an authenticated encryption or decryption operation. 226 * 227 * \note The signature of this function is that of a PSA driver aead_set_nonce 228 * entry point. This function behaves as an aead_set_nonce entry point as 229 * defined in the PSA driver interface specification for transparent 230 * drivers. 231 * 232 * This function sets the nonce for the authenticated 233 * encryption or decryption operation. 234 * 235 * The PSA core calls mbedtls_psa_aead_encrypt_setup() or 236 * mbedtls_psa_aead_decrypt_setup() before calling this function. 237 * 238 * If this function returns an error status, the PSA core will call 239 * mbedtls_psa_aead_abort(). 240 * 241 * \param[in,out] operation Active AEAD operation. 242 * \param[in] nonce Buffer containing the nonce to use. 243 * \param nonce_length Size of the nonce in bytes. 244 * 245 * \retval #PSA_SUCCESS 246 * Success. 247 * \retval #PSA_ERROR_INVALID_ARGUMENT 248 * The size of \p nonce is not acceptable for the chosen algorithm. 249 * \retval #PSA_ERROR_NOT_SUPPORTED 250 * Algorithm previously set is not supported in this configuration of 251 * the library. 252 */ 253 psa_status_t mbedtls_psa_aead_set_nonce( 254 mbedtls_psa_aead_operation_t *operation, 255 const uint8_t *nonce, 256 size_t nonce_length); 257 258 /** Declare the lengths of the message and additional data for AEAD. 259 * 260 * \note The signature of this function is that of a PSA driver aead_set_lengths 261 * entry point. This function behaves as an aead_set_lengths entry point 262 * as defined in the PSA driver interface specification for transparent 263 * drivers. 264 * 265 * The PSA core calls this function before calling mbedtls_psa_aead_update_ad() 266 * or mbedtls_psa_aead_update() if the algorithm for the operation requires it. 267 * If the algorithm does not require it, calling this function is optional, but 268 * if this function is called then the implementation must enforce the lengths. 269 * 270 * The PSA core may call this function before or after setting the nonce with 271 * mbedtls_psa_aead_set_nonce(). 272 * 273 * - For #PSA_ALG_CCM, calling this function is required. 274 * - For the other AEAD algorithms defined in this specification, calling 275 * this function is not required. 276 * 277 * If this function returns an error status, the PSA core calls 278 * mbedtls_psa_aead_abort(). 279 * 280 * \param[in,out] operation Active AEAD operation. 281 * \param ad_length Size of the non-encrypted additional 282 * authenticated data in bytes. 283 * \param plaintext_length Size of the plaintext to encrypt in bytes. 284 * 285 * \retval #PSA_SUCCESS 286 * Success. 287 * \retval #PSA_ERROR_INVALID_ARGUMENT 288 * At least one of the lengths is not acceptable for the chosen 289 * algorithm. 290 * \retval #PSA_ERROR_NOT_SUPPORTED 291 * Algorithm previously set is not supported in this configuration of 292 * the library. 293 */ 294 psa_status_t mbedtls_psa_aead_set_lengths( 295 mbedtls_psa_aead_operation_t *operation, 296 size_t ad_length, 297 size_t plaintext_length); 298 299 /** Pass additional data to an active AEAD operation. 300 * 301 * \note The signature of this function is that of a PSA driver 302 * aead_update_ad entry point. This function behaves as an aead_update_ad 303 * entry point as defined in the PSA driver interface specification for 304 * transparent drivers. 305 * 306 * Additional data is authenticated, but not encrypted. 307 * 308 * The PSA core can call this function multiple times to pass successive 309 * fragments of the additional data. It will not call this function after 310 * passing data to encrypt or decrypt with mbedtls_psa_aead_update(). 311 * 312 * Before calling this function, the PSA core will: 313 * 1. Call either mbedtls_psa_aead_encrypt_setup() or 314 * mbedtls_psa_aead_decrypt_setup(). 315 * 2. Set the nonce with mbedtls_psa_aead_set_nonce(). 316 * 317 * If this function returns an error status, the PSA core will call 318 * mbedtls_psa_aead_abort(). 319 * 320 * \param[in,out] operation Active AEAD operation. 321 * \param[in] input Buffer containing the fragment of 322 * additional data. 323 * \param input_length Size of the \p input buffer in bytes. 324 * 325 * \retval #PSA_SUCCESS 326 * Success. 327 * \retval #PSA_ERROR_NOT_SUPPORTED 328 * Algorithm previously set is not supported in this configuration of 329 * the library. 330 */ 331 psa_status_t mbedtls_psa_aead_update_ad( 332 mbedtls_psa_aead_operation_t *operation, 333 const uint8_t *input, 334 size_t input_length); 335 336 /** Encrypt or decrypt a message fragment in an active AEAD operation. 337 * 338 * \note The signature of this function is that of a PSA driver 339 * aead_update entry point. This function behaves as an aead_update entry 340 * point as defined in the PSA driver interface specification for 341 * transparent drivers. 342 * 343 * Before calling this function, the PSA core will: 344 * 1. Call either mbedtls_psa_aead_encrypt_setup() or 345 * mbedtls_psa_aead_decrypt_setup(). The choice of setup function 346 * determines whether this function encrypts or decrypts its input. 347 * 2. Set the nonce with mbedtls_psa_aead_set_nonce(). 348 * 3. Call mbedtls_psa_aead_update_ad() to pass all the additional data. 349 * 350 * If this function returns an error status, the PSA core will call 351 * mbedtls_psa_aead_abort(). 352 * 353 * This function does not require the input to be aligned to any 354 * particular block boundary. If the implementation can only process 355 * a whole block at a time, it must consume all the input provided, but 356 * it may delay the end of the corresponding output until a subsequent 357 * call to mbedtls_psa_aead_update(), mbedtls_psa_aead_finish() provides 358 * sufficient input. The amount of data that can be delayed in this way is 359 * bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE. 360 * 361 * \param[in,out] operation Active AEAD operation. 362 * \param[in] input Buffer containing the message fragment to 363 * encrypt or decrypt. 364 * \param input_length Size of the \p input buffer in bytes. 365 * \param[out] output Buffer where the output is to be written. 366 * \param output_size Size of the \p output buffer in bytes. 367 * This must be appropriate for the selected 368 * algorithm and key: 369 * - A sufficient output size is 370 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type, 371 * \c alg, \p input_length) where 372 * \c key_type is the type of key and \c alg is 373 * the algorithm that were used to set up the 374 * operation. 375 * - #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p 376 * input_length) evaluates to the maximum 377 * output size of any supported AEAD 378 * algorithm. 379 * \param[out] output_length On success, the number of bytes 380 * that make up the returned output. 381 * 382 * \retval #PSA_SUCCESS 383 * Success. 384 * 385 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 386 * The size of the \p output buffer is too small. 387 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type, \c alg, \p input_length) or 388 * #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p input_length) can be used to 389 * determine the required buffer size. 390 */ 391 psa_status_t mbedtls_psa_aead_update( 392 mbedtls_psa_aead_operation_t *operation, 393 const uint8_t *input, 394 size_t input_length, 395 uint8_t *output, 396 size_t output_size, 397 size_t *output_length); 398 399 /** Finish encrypting a message in an AEAD operation. 400 * 401 * \note The signature of this function is that of a PSA driver 402 * aead_finish entry point. This function behaves as an aead_finish entry 403 * point as defined in the PSA driver interface specification for 404 * transparent drivers. 405 * 406 * The operation must have been set up by the PSA core with 407 * mbedtls_psa_aead_encrypt_setup(). 408 * 409 * This function finishes the authentication of the additional data 410 * formed by concatenating the inputs passed to preceding calls to 411 * mbedtls_psa_aead_update_ad() with the plaintext formed by concatenating the 412 * inputs passed to preceding calls to mbedtls_psa_aead_update(). 413 * 414 * This function has two output buffers: 415 * - \p ciphertext contains trailing ciphertext that was buffered from 416 * preceding calls to mbedtls_psa_aead_update(). 417 * - \p tag contains the authentication tag. 418 * 419 * Whether or not this function returns successfully, the PSA core subsequently 420 * calls mbedtls_psa_aead_abort() to deactivate the operation. 421 * 422 * \param[in,out] operation Active AEAD operation. 423 * \param[out] ciphertext Buffer where the last part of the ciphertext 424 * is to be written. 425 * \param ciphertext_size Size of the \p ciphertext buffer in bytes. 426 * This must be appropriate for the selected 427 * algorithm and key: 428 * - A sufficient output size is 429 * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c key_type, 430 * \c alg) where \c key_type is the type of key 431 * and \c alg is the algorithm that were used to 432 * set up the operation. 433 * - #PSA_AEAD_FINISH_OUTPUT_MAX_SIZE evaluates to 434 * the maximum output size of any supported AEAD 435 * algorithm. 436 * \param[out] ciphertext_length On success, the number of bytes of 437 * returned ciphertext. 438 * \param[out] tag Buffer where the authentication tag is 439 * to be written. 440 * \param tag_size Size of the \p tag buffer in bytes. 441 * This must be appropriate for the selected 442 * algorithm and key: 443 * - The exact tag size is #PSA_AEAD_TAG_LENGTH(\c 444 * key_type, \c key_bits, \c alg) where 445 * \c key_type and \c key_bits are the type and 446 * bit-size of the key, and \c alg are the 447 * algorithm that were used in the call to 448 * mbedtls_psa_aead_encrypt_setup(). 449 * - #PSA_AEAD_TAG_MAX_SIZE evaluates to the 450 * maximum tag size of any supported AEAD 451 * algorithm. 452 * \param[out] tag_length On success, the number of bytes 453 * that make up the returned tag. 454 * 455 * \retval #PSA_SUCCESS 456 * Success. 457 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 458 * The size of the \p tag buffer is too small. 459 * #PSA_AEAD_TAG_LENGTH(\c key_type, key_bits, \c alg) or 460 * #PSA_AEAD_TAG_MAX_SIZE can be used to determine the required \p tag 461 * buffer size. 462 */ 463 psa_status_t mbedtls_psa_aead_finish( 464 mbedtls_psa_aead_operation_t *operation, 465 uint8_t *ciphertext, 466 size_t ciphertext_size, 467 size_t *ciphertext_length, 468 uint8_t *tag, 469 size_t tag_size, 470 size_t *tag_length); 471 472 /** Abort an AEAD operation. 473 * 474 * \note The signature of this function is that of a PSA driver 475 * aead_abort entry point. This function behaves as an aead_abort entry 476 * point as defined in the PSA driver interface specification for 477 * transparent drivers. 478 * 479 * Aborting an operation frees all associated resources except for the 480 * \p operation structure itself. Once aborted, the operation object 481 * can be reused for another operation by the PSA core by it calling 482 * mbedtls_psa_aead_encrypt_setup() or mbedtls_psa_aead_decrypt_setup() again. 483 * 484 * The PSA core may call this function any time after the operation object has 485 * been initialized as described in #mbedtls_psa_aead_operation_t. 486 * 487 * In particular, calling mbedtls_psa_aead_abort() after the operation has been 488 * terminated by a call to mbedtls_psa_aead_abort() or 489 * mbedtls_psa_aead_finish() is safe and has no effect. 490 * 491 * \param[in,out] operation Initialized AEAD operation. 492 * 493 * \retval #PSA_SUCCESS 494 * Success. 495 */ 496 psa_status_t mbedtls_psa_aead_abort( 497 mbedtls_psa_aead_operation_t *operation); 498 499 #endif /* PSA_CRYPTO_AEAD_H */