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