blob: 5ed8a77799b92bc78dd41426469afdca85b0aad7 [file] [log] [blame]
Ronald Cron0ff57952021-03-08 16:46:35 +01001/*
Dave Rodgman0877dc82022-11-02 09:29:35 +00002 * PSA cipher driver entry points and associated auxiliary functions
Ronald Cron0ff57952021-03-08 16:46:35 +01003 */
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
Ronald Cron75e6ae22021-03-17 14:46:05 +010024#include <mbedtls/cipher.h>
Ronald Cron0ff57952021-03-08 16:46:35 +010025#include <psa/crypto.h>
26
Valerio Setti4a249822023-10-18 12:34:54 +020027/** 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[in] alg PSA cipher algorithm identifier
32 * \param[in] key_type PSA key type
33 * \param[in,out] key_bits Size of the key in bits. The value provided in input
34 * might be updated if necessary.
35 * \param[out] mode Mbed TLS cipher mode
36 * \param[out] cipher_id Mbed TLS cipher algorithm identifier
37 *
38 * \return On success \c PSA_SUCCESS is returned and key_bits, mode and cipher_id
39 * are properly updated.
40 * \c PSA_ERROR_NOT_SUPPORTED is returned if the cipher algorithm is not
41 * supported.
42 */
43
44psa_status_t mbedtls_cipher_values_from_psa(psa_algorithm_t alg, psa_key_type_t key_type,
45 size_t *key_bits, mbedtls_cipher_mode_t *mode,
46 mbedtls_cipher_id_t *cipher_id);
47
Valerio Setti2c2aded2023-08-25 09:22:19 +020048#if defined(MBEDTLS_CIPHER_C)
Dave Rodgman16304472022-11-02 09:25:38 +000049/** Get Mbed TLS cipher information given the cipher algorithm PSA identifier
50 * as well as the PSA type and size of the key to be used with the cipher
51 * algorithm.
52 *
53 * \param alg PSA cipher algorithm identifier
54 * \param key_type PSA key type
55 * \param key_bits Size of the key in bits
56 * \param[out] cipher_id Mbed TLS cipher algorithm identifier
57 *
58 * \return The Mbed TLS cipher information of the cipher algorithm.
59 * \c NULL if the PSA cipher algorithm is not supported.
60 */
61const mbedtls_cipher_info_t *mbedtls_cipher_info_from_psa(
62 psa_algorithm_t alg, psa_key_type_t key_type, size_t key_bits,
Gilles Peskine449bd832023-01-11 14:50:10 +010063 mbedtls_cipher_id_t *cipher_id);
Valerio Setti2c2aded2023-08-25 09:22:19 +020064#endif /* MBEDTLS_CIPHER_C */
Dave Rodgman16304472022-11-02 09:25:38 +000065
Ronald Crond6d28882020-12-14 14:56:02 +010066/**
67 * \brief Set the key for a multipart symmetric encryption operation.
68 *
69 * \note The signature of this function is that of a PSA driver
70 * cipher_encrypt_setup entry point. This function behaves as a
71 * cipher_encrypt_setup entry point as defined in the PSA driver
72 * interface specification for transparent drivers.
73 *
74 * \param[in,out] operation The operation object to set up. It has been
75 * initialized as per the documentation for
76 * #psa_cipher_operation_t and not yet in use.
77 * \param[in] attributes The attributes of the key to use for the
78 * operation.
79 * \param[in] key_buffer The buffer containing the key context.
80 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
81 * \param[in] alg The cipher algorithm to compute
82 * (\c PSA_ALG_XXX value such that
83 * #PSA_ALG_IS_CIPHER(\p alg) is true).
84 *
Gilles Peskineed733552023-02-14 19:21:09 +010085 * \retval #PSA_SUCCESS \emptydescription
86 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
87 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
88 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
Ronald Crond6d28882020-12-14 14:56:02 +010089 */
90psa_status_t mbedtls_psa_cipher_encrypt_setup(
Ronald Cron6e412a72021-03-10 09:58:47 +010091 mbedtls_psa_cipher_operation_t *operation,
Ronald Crond6d28882020-12-14 14:56:02 +010092 const psa_key_attributes_t *attributes,
93 const uint8_t *key_buffer, size_t key_buffer_size,
Gilles Peskine449bd832023-01-11 14:50:10 +010094 psa_algorithm_t alg);
Ronald Crond6d28882020-12-14 14:56:02 +010095
96/**
97 * \brief Set the key for a multipart symmetric decryption operation.
98 *
99 * \note The signature of this function is that of a PSA driver
100 * cipher_decrypt_setup entry point. This function behaves as a
101 * cipher_decrypt_setup entry point as defined in the PSA driver
102 * interface specification for transparent drivers.
103 *
104 * \param[in,out] operation The operation object to set up. It has been
105 * initialized as per the documentation for
106 * #psa_cipher_operation_t and not yet in use.
107 * \param[in] attributes The attributes of the key to use for the
108 * operation.
109 * \param[in] key_buffer The buffer containing the key context.
110 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
111 * \param[in] alg The cipher algorithm to compute
112 * (\c PSA_ALG_XXX value such that
113 * #PSA_ALG_IS_CIPHER(\p alg) is true).
114 *
Gilles Peskineed733552023-02-14 19:21:09 +0100115 * \retval #PSA_SUCCESS \emptydescription
116 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
117 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
118 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
Ronald Crond6d28882020-12-14 14:56:02 +0100119 */
120psa_status_t mbedtls_psa_cipher_decrypt_setup(
Ronald Cron6e412a72021-03-10 09:58:47 +0100121 mbedtls_psa_cipher_operation_t *operation,
Ronald Crond6d28882020-12-14 14:56:02 +0100122 const psa_key_attributes_t *attributes,
123 const uint8_t *key_buffer, size_t key_buffer_size,
Gilles Peskine449bd832023-01-11 14:50:10 +0100124 psa_algorithm_t alg);
Ronald Crond6d28882020-12-14 14:56:02 +0100125
Ronald Cron6d051732020-10-01 14:10:20 +0200126/** Set the IV for a symmetric encryption or decryption operation.
127 *
128 * This function sets the IV (initialization vector), nonce
129 * or initial counter value for the encryption or decryption operation.
130 *
131 * \note The signature of this function is that of a PSA driver
132 * cipher_set_iv entry point. This function behaves as a
133 * cipher_set_iv 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] iv Buffer containing the IV to use.
Ronald Crona0d68172021-03-26 10:15:08 +0100138 * \param[in] iv_length Size of the IV in bytes. It is guaranteed by
139 * the core to be less or equal to
140 * PSA_CIPHER_IV_MAX_SIZE.
Ronald Cron6d051732020-10-01 14:10:20 +0200141 *
Gilles Peskineed733552023-02-14 19:21:09 +0100142 * \retval #PSA_SUCCESS \emptydescription
Ronald Cron6d051732020-10-01 14:10:20 +0200143 * \retval #PSA_ERROR_INVALID_ARGUMENT
144 * The size of \p iv is not acceptable for the chosen algorithm,
145 * or the chosen algorithm does not use an IV.
Gilles Peskineed733552023-02-14 19:21:09 +0100146 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
Ronald Cron6d051732020-10-01 14:10:20 +0200147 */
148psa_status_t mbedtls_psa_cipher_set_iv(
Ronald Cron6e412a72021-03-10 09:58:47 +0100149 mbedtls_psa_cipher_operation_t *operation,
Gilles Peskine449bd832023-01-11 14:50:10 +0100150 const uint8_t *iv, size_t iv_length);
Ronald Cron6d051732020-10-01 14:10:20 +0200151
152/** Encrypt or decrypt a message fragment in an active cipher operation.
153 *
154 * \note The signature of this function is that of a PSA driver
155 * cipher_update entry point. This function behaves as a
156 * cipher_update entry point as defined in the PSA driver
157 * interface specification for transparent drivers.
158 *
159 * \param[in,out] operation Active cipher operation.
160 * \param[in] input Buffer containing the message fragment to
161 * encrypt or decrypt.
162 * \param[in] input_length Size of the \p input buffer in bytes.
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 *
Gilles Peskineed733552023-02-14 19:21:09 +0100168 * \retval #PSA_SUCCESS \emptydescription
Ronald Cron6d051732020-10-01 14:10:20 +0200169 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
170 * The size of the \p output buffer is too small.
Gilles Peskineed733552023-02-14 19:21:09 +0100171 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
Ronald Cron6d051732020-10-01 14:10:20 +0200172 */
173psa_status_t mbedtls_psa_cipher_update(
Ronald Cron6e412a72021-03-10 09:58:47 +0100174 mbedtls_psa_cipher_operation_t *operation,
Ronald Cron6d051732020-10-01 14:10:20 +0200175 const uint8_t *input, size_t input_length,
Gilles Peskine449bd832023-01-11 14:50:10 +0100176 uint8_t *output, size_t output_size, size_t *output_length);
Ronald Cron6d051732020-10-01 14:10:20 +0200177
178/** Finish encrypting or decrypting a message in a cipher operation.
179 *
180 * \note The signature of this function is that of a PSA driver
181 * cipher_finish entry point. This function behaves as a
182 * cipher_finish entry point as defined in the PSA driver
183 * interface specification for transparent drivers.
184 *
185 * \param[in,out] operation Active cipher operation.
186 * \param[out] output Buffer where the output is to be written.
187 * \param[in] output_size Size of the \p output buffer in bytes.
188 * \param[out] output_length On success, the number of bytes
189 * that make up the returned output.
190 *
Gilles Peskineed733552023-02-14 19:21:09 +0100191 * \retval #PSA_SUCCESS \emptydescription
Ronald Cron6d051732020-10-01 14:10:20 +0200192 * \retval #PSA_ERROR_INVALID_ARGUMENT
193 * The total input size passed to this operation is not valid for
194 * this particular algorithm. For example, the algorithm is a based
195 * on block cipher and requires a whole number of blocks, but the
196 * total input size is not a multiple of the block size.
197 * \retval #PSA_ERROR_INVALID_PADDING
198 * This is a decryption operation for an algorithm that includes
199 * padding, and the ciphertext does not contain valid padding.
200 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
201 * The size of the \p output buffer is too small.
Gilles Peskineed733552023-02-14 19:21:09 +0100202 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
Ronald Cron6d051732020-10-01 14:10:20 +0200203 */
204psa_status_t mbedtls_psa_cipher_finish(
Ronald Cron6e412a72021-03-10 09:58:47 +0100205 mbedtls_psa_cipher_operation_t *operation,
Gilles Peskine449bd832023-01-11 14:50:10 +0100206 uint8_t *output, size_t output_size, size_t *output_length);
Ronald Cron6d051732020-10-01 14:10:20 +0200207
208/** Abort a cipher operation.
209 *
210 * Aborting an operation frees all associated resources except for the
211 * \p operation structure itself. Once aborted, the operation object
212 * can be reused for another operation.
213 *
214 * \note The signature of this function is that of a PSA driver
215 * cipher_abort entry point. This function behaves as a
216 * cipher_abort entry point as defined in the PSA driver
217 * interface specification for transparent drivers.
218 *
219 * \param[in,out] operation Initialized cipher operation.
220 *
Gilles Peskineed733552023-02-14 19:21:09 +0100221 * \retval #PSA_SUCCESS \emptydescription
Ronald Cron6d051732020-10-01 14:10:20 +0200222 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100223psa_status_t mbedtls_psa_cipher_abort(mbedtls_psa_cipher_operation_t *operation);
Ronald Cron6d051732020-10-01 14:10:20 +0200224
gabor-mezei-arma9449a02021-03-25 11:17:10 +0100225/** Encrypt a message using a symmetric cipher.
226 *
227 * \note The signature of this function is that of a PSA driver
228 * cipher_encrypt entry point. This function behaves as a
229 * cipher_encrypt entry point as defined in the PSA driver
230 * interface specification for transparent drivers.
231 *
232 * \param[in] attributes The attributes of the key to use for the
233 * operation.
234 * \param[in] key_buffer The buffer containing the key context.
235 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
236 * \param[in] alg The cipher algorithm to compute
237 * (\c PSA_ALG_XXX value such that
238 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Ronald Cron9b674282021-07-09 09:19:35 +0200239 * \param[in] iv Buffer containing the IV for encryption. The
240 * IV has been generated by the core.
241 * \param[in] iv_length Size of the \p iv in bytes.
242 * \param[in] input Buffer containing the message to encrypt.
243 * \param[in] input_length Size of the \p input buffer in bytes.
gabor-mezei-arma9449a02021-03-25 11:17:10 +0100244 * \param[in,out] output Buffer where the output is to be written.
gabor-mezei-arm3f860e42021-06-29 16:39:49 +0200245 * \param[in] output_size Size of the \p output buffer in bytes.
gabor-mezei-arm90fceea2021-06-25 15:43:07 +0200246 * \param[out] output_length On success, the number of bytes that make up
247 * the returned output. Initialized to zero
248 * by the core.
gabor-mezei-arma9449a02021-03-25 11:17:10 +0100249 *
Gilles Peskineed733552023-02-14 19:21:09 +0100250 * \retval #PSA_SUCCESS \emptydescription
251 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
252 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
253 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
gabor-mezei-arma9449a02021-03-25 11:17:10 +0100254 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
255 * The size of the \p output buffer is too small.
256 * \retval #PSA_ERROR_INVALID_ARGUMENT
Ronald Cron9b674282021-07-09 09:19:35 +0200257 * The size \p iv_length is not acceptable for the chosen algorithm,
gabor-mezei-arma9449a02021-03-25 11:17:10 +0100258 * or the chosen algorithm does not use an IV.
259 * The total input size passed to this operation is not valid for
260 * this particular algorithm. For example, the algorithm is a based
261 * on block cipher and requires a whole number of blocks, but the
262 * total input size is not a multiple of the block size.
263 * \retval #PSA_ERROR_INVALID_PADDING
264 * This is a decryption operation for an algorithm that includes
265 * padding, and the ciphertext does not contain valid padding.
266 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100267psa_status_t mbedtls_psa_cipher_encrypt(const psa_key_attributes_t *attributes,
268 const uint8_t *key_buffer,
269 size_t key_buffer_size,
270 psa_algorithm_t alg,
271 const uint8_t *iv,
272 size_t iv_length,
273 const uint8_t *input,
274 size_t input_length,
275 uint8_t *output,
276 size_t output_size,
277 size_t *output_length);
gabor-mezei-arma9449a02021-03-25 11:17:10 +0100278
279/** Decrypt a message using a symmetric cipher.
280 *
281 * \note The signature of this function is that of a PSA driver
282 * cipher_decrypt entry point. This function behaves as a
283 * cipher_decrypt entry point as defined in the PSA driver
284 * interface specification for transparent drivers.
285 *
286 * \param[in] attributes The attributes of the key to use for the
287 * operation.
288 * \param[in] key_buffer The buffer containing the key context.
289 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
290 * \param[in] alg The cipher algorithm to compute
291 * (\c PSA_ALG_XXX value such that
292 * #PSA_ALG_IS_CIPHER(\p alg) is true).
gabor-mezei-arm90fceea2021-06-25 15:43:07 +0200293 * \param[in] input Buffer containing the iv and the ciphertext.
gabor-mezei-arma9449a02021-03-25 11:17:10 +0100294 * \param[in] input_length Size of the \p input buffer in bytes.
295 * \param[out] output Buffer where the output is to be written.
296 * \param[in] output_size Size of the \p output buffer in bytes.
gabor-mezei-arm90fceea2021-06-25 15:43:07 +0200297 * \param[out] output_length On success, the number of bytes that make up
298 * the returned output. Initialized to zero
299 * by the core.
gabor-mezei-arma9449a02021-03-25 11:17:10 +0100300 *
Gilles Peskineed733552023-02-14 19:21:09 +0100301 * \retval #PSA_SUCCESS \emptydescription
302 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
303 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
304 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
gabor-mezei-arma9449a02021-03-25 11:17:10 +0100305 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
306 * The size of the \p output buffer is too small.
307 * \retval #PSA_ERROR_INVALID_ARGUMENT
308 * The size of \p iv is not acceptable for the chosen algorithm,
309 * or the chosen algorithm does not use an IV.
310 * The total input size passed to this operation is not valid for
311 * this particular algorithm. For example, the algorithm is a based
312 * on block cipher and requires a whole number of blocks, but the
313 * total input size is not a multiple of the block size.
314 * \retval #PSA_ERROR_INVALID_PADDING
315 * This is a decryption operation for an algorithm that includes
316 * padding, and the ciphertext does not contain valid padding.
317 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100318psa_status_t mbedtls_psa_cipher_decrypt(const psa_key_attributes_t *attributes,
319 const uint8_t *key_buffer,
320 size_t key_buffer_size,
321 psa_algorithm_t alg,
322 const uint8_t *input,
323 size_t input_length,
324 uint8_t *output,
325 size_t output_size,
326 size_t *output_length);
gabor-mezei-arma9449a02021-03-25 11:17:10 +0100327
Ronald Cron0ff57952021-03-08 16:46:35 +0100328#endif /* PSA_CRYPTO_CIPHER_H */