1/*
2 *  PSA RSA layer on top of Mbed TLS crypto
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_RSA_H
10#define PSA_CRYPTO_RSA_H
11
12#include <psa/crypto.h>
13#include <mbedtls/rsa.h>
14
15/** Load the contents of a key buffer into an internal RSA representation
16 *
17 * \param[in] type          The type of key contained in \p data.
18 * \param[in] data          The buffer from which to load the representation.
19 * \param[in] data_length   The size in bytes of \p data.
20 * \param[out] p_rsa        Returns a pointer to an RSA context on success.
21 *                          The caller is responsible for freeing both the
22 *                          contents of the context and the context itself
23 *                          when done.
24 */
25psa_status_t mbedtls_psa_rsa_load_representation(psa_key_type_t type,
26                                                 const uint8_t *data,
27                                                 size_t data_length,
28                                                 mbedtls_rsa_context **p_rsa);
29
30/** Import an RSA key in binary format.
31 *
32 * \note The signature of this function is that of a PSA driver
33 *       import_key entry point. This function behaves as an import_key
34 *       entry point as defined in the PSA driver interface specification for
35 *       transparent drivers.
36 *
37 * \param[in]  attributes       The attributes for the key to import.
38 * \param[in]  data             The buffer containing the key data in import
39 *                              format.
40 * \param[in]  data_length      Size of the \p data buffer in bytes.
41 * \param[out] key_buffer       The buffer containing the key data in output
42 *                              format.
43 * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes. This
44 *                              size is greater or equal to \p data_length.
45 * \param[out] key_buffer_length  The length of the data written in \p
46 *                                key_buffer in bytes.
47 * \param[out] bits             The key size in number of bits.
48 *
49 * \retval #PSA_SUCCESS  The RSA key was imported successfully.
50 * \retval #PSA_ERROR_INVALID_ARGUMENT
51 *         The key data is not correctly formatted.
52 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
53 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
54 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
55 */
56psa_status_t mbedtls_psa_rsa_import_key(
57    const psa_key_attributes_t *attributes,
58    const uint8_t *data, size_t data_length,
59    uint8_t *key_buffer, size_t key_buffer_size,
60    size_t *key_buffer_length, size_t *bits);
61
62/** Export an RSA key to export representation
63 *
64 * \param[in] type          The type of key (public/private) to export
65 * \param[in] rsa           The internal RSA representation from which to export
66 * \param[out] data         The buffer to export to
67 * \param[in] data_size     The length of the buffer to export to
68 * \param[out] data_length  The amount of bytes written to \p data
69 */
70psa_status_t mbedtls_psa_rsa_export_key(psa_key_type_t type,
71                                        mbedtls_rsa_context *rsa,
72                                        uint8_t *data,
73                                        size_t data_size,
74                                        size_t *data_length);
75
76/** Export a public RSA key or the public part of an RSA key pair in binary
77 *  format.
78 *
79 * \note The signature of this function is that of a PSA driver
80 *       export_public_key entry point. This function behaves as an
81 *       export_public_key entry point as defined in the PSA driver interface
82 *       specification.
83 *
84 * \param[in]  attributes       The attributes for the key to export.
85 * \param[in]  key_buffer       Material or context of the key to export.
86 * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
87 * \param[out] data             Buffer where the key data is to be written.
88 * \param[in]  data_size        Size of the \p data buffer in bytes.
89 * \param[out] data_length      On success, the number of bytes written in
90 *                              \p data.
91 *
92 * \retval #PSA_SUCCESS  The RSA public key was exported successfully.
93 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
94 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
95 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
96 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
97 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
98 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
99 */
100psa_status_t mbedtls_psa_rsa_export_public_key(
101    const psa_key_attributes_t *attributes,
102    const uint8_t *key_buffer, size_t key_buffer_size,
103    uint8_t *data, size_t data_size, size_t *data_length);
104
105/**
106 * \brief Generate an RSA key.
107 *
108 * \note The signature of the function is that of a PSA driver generate_key
109 *       entry point.
110 *
111 * \param[in]  attributes         The attributes for the RSA key to generate.
112 * \param[in]  params             Production parameters for the key
113 *                                generation. This function only uses
114 *                                `params->data`,
115 *                                which contains the public exponent.
116 *                                This can be a null pointer if
117 *                                \c params_data_length is 0.
118 * \param params_data_length      Length of `params->data` in bytes.
119 *                                This can be 0, in which case the
120 *                                public exponent will be 65537.
121 * \param[out] key_buffer         Buffer where the key data is to be written.
122 * \param[in]  key_buffer_size    Size of \p key_buffer in bytes.
123 * \param[out] key_buffer_length  On success, the number of bytes written in
124 *                                \p key_buffer.
125 *
126 * \retval #PSA_SUCCESS
127 *         The key was successfully generated.
128 * \retval #PSA_ERROR_NOT_SUPPORTED
129 *         Key length or type not supported.
130 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
131 *         The size of \p key_buffer is too small.
132 */
133psa_status_t mbedtls_psa_rsa_generate_key(
134    const psa_key_attributes_t *attributes,
135    const psa_key_production_parameters_t *params, size_t params_data_length,
136    uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length);
137
138/** Sign an already-calculated hash with an RSA private key.
139 *
140 * \note The signature of this function is that of a PSA driver
141 *       sign_hash entry point. This function behaves as a sign_hash
142 *       entry point as defined in the PSA driver interface specification for
143 *       transparent drivers.
144 *
145 * \param[in]  attributes       The attributes of the RSA key to use for the
146 *                              operation.
147 * \param[in]  key_buffer       The buffer containing the RSA key context.
148 *                              format.
149 * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
150 * \param[in]  alg              A signature algorithm that is compatible with
151 *                              an RSA key.
152 * \param[in]  hash             The hash or message to sign.
153 * \param[in]  hash_length      Size of the \p hash buffer in bytes.
154 * \param[out] signature        Buffer where the signature is to be written.
155 * \param[in]  signature_size   Size of the \p signature buffer in bytes.
156 * \param[out] signature_length On success, the number of bytes
157 *                              that make up the returned signature value.
158 *
159 * \retval #PSA_SUCCESS \emptydescription
160 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
161 *         The size of the \p signature buffer is too small. You can
162 *         determine a sufficient buffer size by calling
163 *         #PSA_SIGN_OUTPUT_SIZE(\c PSA_KEY_TYPE_RSA_KEY_PAIR, \c key_bits,
164 *         \p alg) where \c key_bits is the bit-size of the RSA key.
165 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
166 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
167 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
168 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
169 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
170 */
171psa_status_t mbedtls_psa_rsa_sign_hash(
172    const psa_key_attributes_t *attributes,
173    const uint8_t *key_buffer, size_t key_buffer_size,
174    psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
175    uint8_t *signature, size_t signature_size, size_t *signature_length);
176
177/**
178 * \brief Verify the signature a hash or short message using a public RSA key.
179 *
180 * \note The signature of this function is that of a PSA driver
181 *       verify_hash entry point. This function behaves as a verify_hash
182 *       entry point as defined in the PSA driver interface specification for
183 *       transparent drivers.
184 *
185 * \param[in]  attributes       The attributes of the RSA key to use for the
186 *                              operation.
187 * \param[in]  key_buffer       The buffer containing the RSA key context.
188 *                              format.
189 * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
190 * \param[in]  alg              A signature algorithm that is compatible with
191 *                              an RSA key.
192 * \param[in]  hash             The hash or message whose signature is to be
193 *                              verified.
194 * \param[in]  hash_length      Size of the \p hash buffer in bytes.
195 * \param[in]  signature        Buffer containing the signature to verify.
196 * \param[in]  signature_length Size of the \p signature buffer in bytes.
197 *
198 * \retval #PSA_SUCCESS
199 *         The signature is valid.
200 * \retval #PSA_ERROR_INVALID_SIGNATURE
201 *         The calculation was performed successfully, but the passed
202 *         signature is not a valid signature.
203 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
204 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
205 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
206 */
207psa_status_t mbedtls_psa_rsa_verify_hash(
208    const psa_key_attributes_t *attributes,
209    const uint8_t *key_buffer, size_t key_buffer_size,
210    psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
211    const uint8_t *signature, size_t signature_length);
212
213/**
214 * \brief Encrypt a short message with a public key.
215 *
216 * \param attributes            The attributes for the key to import.
217 * \param key_buffer            Buffer where the key data is to be written.
218 * \param key_buffer_size       Size of the \p key_buffer buffer in bytes.
219 * \param input_length          Size of the \p input buffer in bytes.
220 * \param[in] salt              A salt or label, if supported by the
221 *                              encryption algorithm.
222 *                              If the algorithm does not support a
223 *                              salt, pass \c NULL.
224 *                              If the algorithm supports an optional
225 *                              salt and you do not want to pass a salt,
226 *                              pass \c NULL.
227 *
228 *                              - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
229 *                                supported.
230 * \param salt_length           Size of the \p salt buffer in bytes.
231 *                              If \p salt is \c NULL, pass 0.
232 * \param[out] output           Buffer where the encrypted message is to
233 *                              be written.
234 * \param output_size           Size of the \p output buffer in bytes.
235 * \param[out] output_length    On success, the number of bytes
236 *                              that make up the returned output.
237 *
238 * \retval #PSA_SUCCESS \emptydescription
239 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
240 *         The size of the \p output buffer is too small. You can
241 *         determine a sufficient buffer size by calling
242 *         #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
243 *         where \c key_type and \c key_bits are the type and bit-size
244 *         respectively of \p key.
245 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
246 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
247 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
248 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
249 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
250 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
251 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
252 * \retval #PSA_ERROR_BAD_STATE
253 *         The library has not been previously initialized by psa_crypto_init().
254 *         It is implementation-dependent whether a failure to initialize
255 *         results in this error code.
256 */
257psa_status_t mbedtls_psa_asymmetric_encrypt(const psa_key_attributes_t *attributes,
258                                            const uint8_t *key_buffer,
259                                            size_t key_buffer_size,
260                                            psa_algorithm_t alg,
261                                            const uint8_t *input,
262                                            size_t input_length,
263                                            const uint8_t *salt,
264                                            size_t salt_length,
265                                            uint8_t *output,
266                                            size_t output_size,
267                                            size_t *output_length);
268
269/**
270 * \brief Decrypt a short message with a private key.
271 *
272 * \param attributes            The attributes for the key to import.
273 * \param key_buffer            Buffer where the key data is to be written.
274 * \param key_buffer_size       Size of the \p key_buffer buffer in bytes.
275 * \param[in] input             The message to decrypt.
276 * \param input_length          Size of the \p input buffer in bytes.
277 * \param[in] salt              A salt or label, if supported by the
278 *                              encryption algorithm.
279 *                              If the algorithm does not support a
280 *                              salt, pass \c NULL.
281 *                              If the algorithm supports an optional
282 *                              salt and you do not want to pass a salt,
283 *                              pass \c NULL.
284 *
285 *                              - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
286 *                                supported.
287 * \param salt_length           Size of the \p salt buffer in bytes.
288 *                              If \p salt is \c NULL, pass 0.
289 * \param[out] output           Buffer where the decrypted message is to
290 *                              be written.
291 * \param output_size           Size of the \c output buffer in bytes.
292 * \param[out] output_length    On success, the number of bytes
293 *                              that make up the returned output.
294 *
295 * \retval #PSA_SUCCESS \emptydescription
296 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
297 *         The size of the \p output buffer is too small. You can
298 *         determine a sufficient buffer size by calling
299 *         #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
300 *         where \c key_type and \c key_bits are the type and bit-size
301 *         respectively of \p key.
302 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
303 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
304 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
305 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
306 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
307 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
308 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
309 * \retval #PSA_ERROR_INVALID_PADDING \emptydescription
310 * \retval #PSA_ERROR_BAD_STATE
311 *         The library has not been previously initialized by psa_crypto_init().
312 *         It is implementation-dependent whether a failure to initialize
313 *         results in this error code.
314 */
315psa_status_t mbedtls_psa_asymmetric_decrypt(const psa_key_attributes_t *attributes,
316                                            const uint8_t *key_buffer,
317                                            size_t key_buffer_size,
318                                            psa_algorithm_t alg,
319                                            const uint8_t *input,
320                                            size_t input_length,
321                                            const uint8_t *salt,
322                                            size_t salt_length,
323                                            uint8_t *output,
324                                            size_t output_size,
325                                            size_t *output_length);
326
327#endif /* PSA_CRYPTO_RSA_H */
328