1 /* 2 * PSA cipher 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_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 63 * \retval #PSA_ERROR_NOT_SUPPORTED 64 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 65 * \retval #PSA_ERROR_CORRUPTION_DETECTED 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 93 * \retval #PSA_ERROR_NOT_SUPPORTED 94 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 95 * \retval #PSA_ERROR_CORRUPTION_DETECTED 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 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 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 146 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 147 * The size of the \p output buffer is too small. 148 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 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 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 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 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] input Buffer containing the message to encrypt. 217 * \param[in] input_length Size of the \p input buffer in bytes. 218 * \param[in,out] output Buffer where the output is to be written. 219 * The core has generated and written the IV 220 * at the beginning of this buffer before 221 * this function is called. The size of the IV 222 * is PSA_CIPHER_IV_LENGTH( key_type, alg ) where 223 * \c key_type is the type of the key identified 224 * by \p key and \p alg is the cipher algorithm 225 * to compute. 226 * \param[in] output_size Size of the \p output buffer in bytes. 227 * \param[out] output_length On success, the number of bytes that make up 228 * the returned output. Initialized to zero 229 * by the core. 230 * 231 * \retval #PSA_SUCCESS 232 * \retval #PSA_ERROR_NOT_SUPPORTED 233 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 234 * \retval #PSA_ERROR_CORRUPTION_DETECTED 235 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 236 * The size of the \p output buffer is too small. 237 * \retval #PSA_ERROR_INVALID_ARGUMENT 238 * The size of \p iv is not acceptable for the chosen algorithm, 239 * or the chosen algorithm does not use an IV. 240 * The total input size passed to this operation is not valid for 241 * this particular algorithm. For example, the algorithm is a based 242 * on block cipher and requires a whole number of blocks, but the 243 * total input size is not a multiple of the block size. 244 * \retval #PSA_ERROR_INVALID_PADDING 245 * This is a decryption operation for an algorithm that includes 246 * padding, and the ciphertext does not contain valid padding. 247 */ 248 psa_status_t mbedtls_psa_cipher_encrypt( const psa_key_attributes_t *attributes, 249 const uint8_t *key_buffer, 250 size_t key_buffer_size, 251 psa_algorithm_t alg, 252 const uint8_t *input, 253 size_t input_length, 254 uint8_t *output, 255 size_t output_size, 256 size_t *output_length ); 257 258 /** Decrypt a message using a symmetric cipher. 259 * 260 * \note The signature of this function is that of a PSA driver 261 * cipher_decrypt entry point. This function behaves as a 262 * cipher_decrypt entry point as defined in the PSA driver 263 * interface specification for transparent drivers. 264 * 265 * \param[in] attributes The attributes of the key to use for the 266 * operation. 267 * \param[in] key_buffer The buffer containing the key context. 268 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 269 * \param[in] alg The cipher algorithm to compute 270 * (\c PSA_ALG_XXX value such that 271 * #PSA_ALG_IS_CIPHER(\p alg) is true). 272 * \param[in] input Buffer containing the iv and the ciphertext. 273 * \param[in] input_length Size of the \p input buffer in bytes. 274 * \param[out] output Buffer where the output is to be written. 275 * \param[in] output_size Size of the \p output buffer in bytes. 276 * \param[out] output_length On success, the number of bytes that make up 277 * the returned output. Initialized to zero 278 * by the core. 279 * 280 * \retval #PSA_SUCCESS 281 * \retval #PSA_ERROR_NOT_SUPPORTED 282 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY 283 * \retval #PSA_ERROR_CORRUPTION_DETECTED 284 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 285 * The size of the \p output buffer is too small. 286 * \retval #PSA_ERROR_INVALID_ARGUMENT 287 * The size of \p iv is not acceptable for the chosen algorithm, 288 * or the chosen algorithm does not use an IV. 289 * The total input size passed to this operation is not valid for 290 * this particular algorithm. For example, the algorithm is a based 291 * on block cipher and requires a whole number of blocks, but the 292 * total input size is not a multiple of the block size. 293 * \retval #PSA_ERROR_INVALID_PADDING 294 * This is a decryption operation for an algorithm that includes 295 * padding, and the ciphertext does not contain valid padding. 296 */ 297 psa_status_t mbedtls_psa_cipher_decrypt( const psa_key_attributes_t *attributes, 298 const uint8_t *key_buffer, 299 size_t key_buffer_size, 300 psa_algorithm_t alg, 301 const uint8_t *input, 302 size_t input_length, 303 uint8_t *output, 304 size_t output_size, 305 size_t *output_length ); 306 307 /* 308 * BEYOND THIS POINT, TEST DRIVER ENTRY POINTS ONLY. 309 */ 310 311 #if defined(PSA_CRYPTO_DRIVER_TEST) 312 psa_status_t mbedtls_transparent_test_driver_cipher_encrypt_setup( 313 mbedtls_psa_cipher_operation_t *operation, 314 const psa_key_attributes_t *attributes, 315 const uint8_t *key_buffer, size_t key_buffer_size, 316 psa_algorithm_t alg ); 317 318 psa_status_t mbedtls_transparent_test_driver_cipher_decrypt_setup( 319 mbedtls_psa_cipher_operation_t *operation, 320 const psa_key_attributes_t *attributes, 321 const uint8_t *key_buffer, size_t key_buffer_size, 322 psa_algorithm_t alg ); 323 324 psa_status_t mbedtls_transparent_test_driver_cipher_set_iv( 325 mbedtls_psa_cipher_operation_t *operation, 326 const uint8_t *iv, size_t iv_length ); 327 328 psa_status_t mbedtls_transparent_test_driver_cipher_update( 329 mbedtls_psa_cipher_operation_t *operation, 330 const uint8_t *input, size_t input_length, 331 uint8_t *output, size_t output_size, size_t *output_length ); 332 333 psa_status_t mbedtls_transparent_test_driver_cipher_finish( 334 mbedtls_psa_cipher_operation_t *operation, 335 uint8_t *output, size_t output_size, size_t *output_length ); 336 337 psa_status_t mbedtls_transparent_test_driver_cipher_abort( 338 mbedtls_psa_cipher_operation_t *operation ); 339 340 psa_status_t mbedtls_transparent_test_driver_cipher_encrypt( 341 const psa_key_attributes_t *attributes, 342 const uint8_t *key_buffer, 343 size_t key_buffer_size, 344 psa_algorithm_t alg, 345 const uint8_t *input, 346 size_t input_length, 347 uint8_t *output, 348 size_t output_size, 349 size_t *output_length ); 350 351 psa_status_t mbedtls_transparent_test_driver_cipher_decrypt( 352 const psa_key_attributes_t *attributes, 353 const uint8_t *key_buffer, 354 size_t key_buffer_size, 355 psa_algorithm_t alg, 356 const uint8_t *input, 357 size_t input_length, 358 uint8_t *output, 359 size_t output_size, 360 size_t *output_length ); 361 #endif /* PSA_CRYPTO_DRIVER_TEST */ 362 363 #endif /* PSA_CRYPTO_CIPHER_H */ 364