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