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 #endif /* PSA_CRYPTO_AEAD_H */ 140