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