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