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
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] iv                Buffer containing the IV for encryption. The
217  *                              IV has been generated by the core.
218  * \param[in] iv_length         Size of the \p iv in bytes.
219  * \param[in] input             Buffer containing the message to encrypt.
220  * \param[in] input_length      Size of the \p input buffer in bytes.
221  * \param[in,out] output        Buffer where the output is to be written.
222  * \param[in]  output_size      Size of the \p output buffer in bytes.
223  * \param[out] output_length    On success, the number of bytes that make up
224  *                              the returned output. Initialized to zero
225  *                              by the core.
226  *
227  * \retval #PSA_SUCCESS
228  * \retval #PSA_ERROR_NOT_SUPPORTED
229  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
230  * \retval #PSA_ERROR_CORRUPTION_DETECTED
231  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
232  *         The size of the \p output buffer is too small.
233  * \retval #PSA_ERROR_INVALID_ARGUMENT
234  *         The size \p iv_length is not acceptable for the chosen algorithm,
235  *         or the chosen algorithm does not use an IV.
236  *         The total input size passed to this operation is not valid for
237  *         this particular algorithm. For example, the algorithm is a based
238  *         on block cipher and requires a whole number of blocks, but the
239  *         total input size is not a multiple of the block size.
240  * \retval #PSA_ERROR_INVALID_PADDING
241  *         This is a decryption operation for an algorithm that includes
242  *         padding, and the ciphertext does not contain valid padding.
243  */
244 psa_status_t mbedtls_psa_cipher_encrypt( const psa_key_attributes_t *attributes,
245                                          const uint8_t *key_buffer,
246                                          size_t key_buffer_size,
247                                          psa_algorithm_t alg,
248                                          const uint8_t *iv,
249                                          size_t iv_length,
250                                          const uint8_t *input,
251                                          size_t input_length,
252                                          uint8_t *output,
253                                          size_t output_size,
254                                          size_t *output_length );
255 
256 /** Decrypt a message using a symmetric cipher.
257  *
258  * \note The signature of this function is that of a PSA driver
259  *       cipher_decrypt entry point. This function behaves as a
260  *       cipher_decrypt entry point as defined in the PSA driver
261  *       interface specification for transparent drivers.
262  *
263  * \param[in]  attributes       The attributes of the key to use for the
264  *                              operation.
265  * \param[in]  key_buffer       The buffer containing the key context.
266  * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
267  * \param[in]  alg              The cipher algorithm to compute
268  *                              (\c PSA_ALG_XXX value such that
269  *                              #PSA_ALG_IS_CIPHER(\p alg) is true).
270  * \param[in]  input            Buffer containing the iv and the ciphertext.
271  * \param[in]  input_length     Size of the \p input buffer in bytes.
272  * \param[out] output           Buffer where the output is to be written.
273  * \param[in]  output_size      Size of the \p output buffer in bytes.
274  * \param[out] output_length    On success, the number of bytes that make up
275  *                              the returned output. Initialized to zero
276  *                              by the core.
277  *
278  * \retval #PSA_SUCCESS
279  * \retval #PSA_ERROR_NOT_SUPPORTED
280  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
281  * \retval #PSA_ERROR_CORRUPTION_DETECTED
282  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
283  *         The size of the \p output buffer is too small.
284  * \retval #PSA_ERROR_INVALID_ARGUMENT
285  *         The size of \p iv is not acceptable for the chosen algorithm,
286  *         or the chosen algorithm does not use an IV.
287  *         The total input size passed to this operation is not valid for
288  *         this particular algorithm. For example, the algorithm is a based
289  *         on block cipher and requires a whole number of blocks, but the
290  *         total input size is not a multiple of the block size.
291  * \retval #PSA_ERROR_INVALID_PADDING
292  *         This is a decryption operation for an algorithm that includes
293  *         padding, and the ciphertext does not contain valid padding.
294  */
295 psa_status_t mbedtls_psa_cipher_decrypt( const psa_key_attributes_t *attributes,
296                                          const uint8_t *key_buffer,
297                                          size_t key_buffer_size,
298                                          psa_algorithm_t alg,
299                                          const uint8_t *input,
300                                          size_t input_length,
301                                          uint8_t *output,
302                                          size_t output_size,
303                                          size_t *output_length );
304 
305 #endif /* PSA_CRYPTO_CIPHER_H */
306