1 /* 2 * PSA cipher driver entry points and associated auxiliary functions 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_CIPHER_H 22 #define PSA_CRYPTO_CIPHER_H 23 24 #include <mbedtls/cipher.h> 25 #include <psa/crypto.h> 26 27 /** Get Mbed TLS cipher information given the cipher algorithm PSA identifier 28 * as well as the PSA type and size of the key to be used with the cipher 29 * algorithm. 30 * 31 * \param alg PSA cipher algorithm identifier 32 * \param key_type PSA key type 33 * \param key_bits Size of the key in bits 34 * \param[out] cipher_id Mbed TLS cipher algorithm identifier 35 * 36 * \return The Mbed TLS cipher information of the cipher algorithm. 37 * \c NULL if the PSA cipher algorithm is not supported. 38 */ 39 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_psa( 40 psa_algorithm_t alg, psa_key_type_t key_type, size_t key_bits, 41 mbedtls_cipher_id_t *cipher_id); 42 43 /** 44 * \brief Set the key for a multipart symmetric encryption operation. 45 * 46 * \note The signature of this function is that of a PSA driver 47 * cipher_encrypt_setup entry point. This function behaves as a 48 * cipher_encrypt_setup entry point as defined in the PSA driver 49 * interface specification for transparent drivers. 50 * 51 * \param[in,out] operation The operation object to set up. It has been 52 * initialized as per the documentation for 53 * #psa_cipher_operation_t and not yet in use. 54 * \param[in] attributes The attributes of the key to use for the 55 * operation. 56 * \param[in] key_buffer The buffer containing the key context. 57 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 58 * \param[in] alg The cipher algorithm to compute 59 * (\c PSA_ALG_XXX value such that 60 * #PSA_ALG_IS_CIPHER(\p alg) is true). 61 * 62 * \retval #PSA_SUCCESS \emptydescription 63 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 64 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 65 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 66 */ 67 psa_status_t mbedtls_psa_cipher_encrypt_setup( 68 mbedtls_psa_cipher_operation_t *operation, 69 const psa_key_attributes_t *attributes, 70 const uint8_t *key_buffer, size_t key_buffer_size, 71 psa_algorithm_t alg); 72 73 /** 74 * \brief Set the key for a multipart symmetric decryption operation. 75 * 76 * \note The signature of this function is that of a PSA driver 77 * cipher_decrypt_setup entry point. This function behaves as a 78 * cipher_decrypt_setup entry point as defined in the PSA driver 79 * interface specification for transparent drivers. 80 * 81 * \param[in,out] operation The operation object to set up. It has been 82 * initialized as per the documentation for 83 * #psa_cipher_operation_t and not yet in use. 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[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 88 * \param[in] alg The cipher algorithm to compute 89 * (\c PSA_ALG_XXX value such that 90 * #PSA_ALG_IS_CIPHER(\p alg) is true). 91 * 92 * \retval #PSA_SUCCESS \emptydescription 93 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 94 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 95 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 96 */ 97 psa_status_t mbedtls_psa_cipher_decrypt_setup( 98 mbedtls_psa_cipher_operation_t *operation, 99 const psa_key_attributes_t *attributes, 100 const uint8_t *key_buffer, size_t key_buffer_size, 101 psa_algorithm_t alg); 102 103 /** Set the IV for a symmetric encryption or decryption operation. 104 * 105 * This function sets the IV (initialization vector), nonce 106 * or initial counter value for the encryption or decryption operation. 107 * 108 * \note The signature of this function is that of a PSA driver 109 * cipher_set_iv entry point. This function behaves as a 110 * cipher_set_iv entry point as defined in the PSA driver 111 * interface specification for transparent drivers. 112 * 113 * \param[in,out] operation Active cipher operation. 114 * \param[in] iv Buffer containing the IV to use. 115 * \param[in] iv_length Size of the IV in bytes. It is guaranteed by 116 * the core to be less or equal to 117 * PSA_CIPHER_IV_MAX_SIZE. 118 * 119 * \retval #PSA_SUCCESS \emptydescription 120 * \retval #PSA_ERROR_INVALID_ARGUMENT 121 * The size of \p iv is not acceptable for the chosen algorithm, 122 * or the chosen algorithm does not use an IV. 123 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 124 */ 125 psa_status_t mbedtls_psa_cipher_set_iv( 126 mbedtls_psa_cipher_operation_t *operation, 127 const uint8_t *iv, size_t iv_length); 128 129 /** Encrypt or decrypt a message fragment in an active cipher operation. 130 * 131 * \note The signature of this function is that of a PSA driver 132 * cipher_update entry point. This function behaves as a 133 * cipher_update entry point as defined in the PSA driver 134 * interface specification for transparent drivers. 135 * 136 * \param[in,out] operation Active cipher operation. 137 * \param[in] input Buffer containing the message fragment to 138 * encrypt or decrypt. 139 * \param[in] input_length Size of the \p input buffer in bytes. 140 * \param[out] output Buffer where the output is to be written. 141 * \param[in] output_size Size of the \p output buffer in bytes. 142 * \param[out] output_length On success, the number of bytes 143 * that make up the returned output. 144 * 145 * \retval #PSA_SUCCESS \emptydescription 146 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 147 * The size of the \p output buffer is too small. 148 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 149 */ 150 psa_status_t mbedtls_psa_cipher_update( 151 mbedtls_psa_cipher_operation_t *operation, 152 const uint8_t *input, size_t input_length, 153 uint8_t *output, size_t output_size, size_t *output_length); 154 155 /** Finish encrypting or decrypting a message in a cipher operation. 156 * 157 * \note The signature of this function is that of a PSA driver 158 * cipher_finish entry point. This function behaves as a 159 * cipher_finish entry point as defined in the PSA driver 160 * interface specification for transparent drivers. 161 * 162 * \param[in,out] operation Active cipher operation. 163 * \param[out] output Buffer where the output is to be written. 164 * \param[in] output_size Size of the \p output buffer in bytes. 165 * \param[out] output_length On success, the number of bytes 166 * that make up the returned output. 167 * 168 * \retval #PSA_SUCCESS \emptydescription 169 * \retval #PSA_ERROR_INVALID_ARGUMENT 170 * The total input size passed to this operation is not valid for 171 * this particular algorithm. For example, the algorithm is a based 172 * on block cipher and requires a whole number of blocks, but the 173 * total input size is not a multiple of the block size. 174 * \retval #PSA_ERROR_INVALID_PADDING 175 * This is a decryption operation for an algorithm that includes 176 * padding, and the ciphertext does not contain valid padding. 177 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 178 * The size of the \p output buffer is too small. 179 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 180 */ 181 psa_status_t mbedtls_psa_cipher_finish( 182 mbedtls_psa_cipher_operation_t *operation, 183 uint8_t *output, size_t output_size, size_t *output_length); 184 185 /** Abort a cipher operation. 186 * 187 * Aborting an operation frees all associated resources except for the 188 * \p operation structure itself. Once aborted, the operation object 189 * can be reused for another operation. 190 * 191 * \note The signature of this function is that of a PSA driver 192 * cipher_abort entry point. This function behaves as a 193 * cipher_abort entry point as defined in the PSA driver 194 * interface specification for transparent drivers. 195 * 196 * \param[in,out] operation Initialized cipher operation. 197 * 198 * \retval #PSA_SUCCESS \emptydescription 199 */ 200 psa_status_t mbedtls_psa_cipher_abort(mbedtls_psa_cipher_operation_t *operation); 201 202 /** Encrypt a message using a symmetric cipher. 203 * 204 * \note The signature of this function is that of a PSA driver 205 * cipher_encrypt entry point. This function behaves as a 206 * cipher_encrypt entry point as defined in the PSA driver 207 * interface specification for transparent drivers. 208 * 209 * \param[in] attributes The attributes of the key to use for the 210 * operation. 211 * \param[in] key_buffer The buffer containing the key context. 212 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 213 * \param[in] alg The cipher algorithm to compute 214 * (\c PSA_ALG_XXX value such that 215 * #PSA_ALG_IS_CIPHER(\p alg) is true). 216 * \param[in] iv Buffer containing the IV for encryption. The 217 * IV has been generated by the core. 218 * \param[in] iv_length Size of the \p iv in bytes. 219 * \param[in] input Buffer containing the message to encrypt. 220 * \param[in] input_length Size of the \p input buffer in bytes. 221 * \param[in,out] output Buffer where the output is to be written. 222 * \param[in] output_size Size of the \p output buffer in bytes. 223 * \param[out] output_length On success, the number of bytes that make up 224 * the returned output. Initialized to zero 225 * by the core. 226 * 227 * \retval #PSA_SUCCESS \emptydescription 228 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 229 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 230 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 231 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 232 * The size of the \p output buffer is too small. 233 * \retval #PSA_ERROR_INVALID_ARGUMENT 234 * The size \p iv_length is not acceptable for the chosen algorithm, 235 * or the chosen algorithm does not use an IV. 236 * The total input size passed to this operation is not valid for 237 * this particular algorithm. For example, the algorithm is a based 238 * on block cipher and requires a whole number of blocks, but the 239 * total input size is not a multiple of the block size. 240 * \retval #PSA_ERROR_INVALID_PADDING 241 * This is a decryption operation for an algorithm that includes 242 * padding, and the ciphertext does not contain valid padding. 243 */ 244 psa_status_t mbedtls_psa_cipher_encrypt(const psa_key_attributes_t *attributes, 245 const uint8_t *key_buffer, 246 size_t key_buffer_size, 247 psa_algorithm_t alg, 248 const uint8_t *iv, 249 size_t iv_length, 250 const uint8_t *input, 251 size_t input_length, 252 uint8_t *output, 253 size_t output_size, 254 size_t *output_length); 255 256 /** Decrypt a message using a symmetric cipher. 257 * 258 * \note The signature of this function is that of a PSA driver 259 * cipher_decrypt entry point. This function behaves as a 260 * cipher_decrypt entry point as defined in the PSA driver 261 * interface specification for transparent drivers. 262 * 263 * \param[in] attributes The attributes of the key to use for the 264 * operation. 265 * \param[in] key_buffer The buffer containing the key context. 266 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 267 * \param[in] alg The cipher algorithm to compute 268 * (\c PSA_ALG_XXX value such that 269 * #PSA_ALG_IS_CIPHER(\p alg) is true). 270 * \param[in] input Buffer containing the iv and the ciphertext. 271 * \param[in] input_length Size of the \p input buffer in bytes. 272 * \param[out] output Buffer where the output is to be written. 273 * \param[in] output_size Size of the \p output buffer in bytes. 274 * \param[out] output_length On success, the number of bytes that make up 275 * the returned output. Initialized to zero 276 * by the core. 277 * 278 * \retval #PSA_SUCCESS \emptydescription 279 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 280 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 281 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 282 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 283 * The size of the \p output buffer is too small. 284 * \retval #PSA_ERROR_INVALID_ARGUMENT 285 * The size of \p iv is not acceptable for the chosen algorithm, 286 * or the chosen algorithm does not use an IV. 287 * The total input size passed to this operation is not valid for 288 * this particular algorithm. For example, the algorithm is a based 289 * on block cipher and requires a whole number of blocks, but the 290 * total input size is not a multiple of the block size. 291 * \retval #PSA_ERROR_INVALID_PADDING 292 * This is a decryption operation for an algorithm that includes 293 * padding, and the ciphertext does not contain valid padding. 294 */ 295 psa_status_t mbedtls_psa_cipher_decrypt(const psa_key_attributes_t *attributes, 296 const uint8_t *key_buffer, 297 size_t key_buffer_size, 298 psa_algorithm_t alg, 299 const uint8_t *input, 300 size_t input_length, 301 uint8_t *output, 302 size_t output_size, 303 size_t *output_length); 304 305 #endif /* PSA_CRYPTO_CIPHER_H */ 306