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 #endif /* PSA_CRYPTO_AEAD */ 152