NCBI C++ ToolKit
psa_crypto_rsa.h
Go to the documentation of this file.

Go to the SVN repository for this file.

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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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 */
Platform Security Architecture cryptography module.
static const struct attribute attributes[]
Definition: attributes.c:165
static SQLCHAR output[256]
Definition: print.c:5
char data[12]
Definition: iconv.c:80
unsigned char uint8_t
uint16_t psa_key_type_t
Encoding of a key type.
Definition: crypto_types.h:78
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:134
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:59
static int input()
psa_status_t mbedtls_psa_asymmetric_encrypt(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, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)
Encrypt a short message with a public key.
psa_status_t mbedtls_psa_rsa_generate_key(const psa_key_attributes_t *attributes, const psa_key_production_parameters_t *params, size_t params_data_length, uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length)
Generate an RSA key.
psa_status_t mbedtls_psa_rsa_verify_hash(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)
Verify the signature a hash or short message using a public RSA key.
psa_status_t mbedtls_psa_asymmetric_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, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)
Decrypt a short message with a private key.
psa_status_t mbedtls_psa_rsa_import_key(const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length, size_t *bits)
Import an RSA key in binary format.
psa_status_t mbedtls_psa_rsa_export_key(psa_key_type_t type, mbedtls_rsa_context *rsa, uint8_t *data, size_t data_size, size_t *data_length)
Export an RSA key to export representation.
psa_status_t mbedtls_psa_rsa_load_representation(psa_key_type_t type, const uint8_t *data, size_t data_length, mbedtls_rsa_context **p_rsa)
Load the contents of a key buffer into an internal RSA representation.
psa_status_t mbedtls_psa_rsa_sign_hash(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, uint8_t *signature, size_t signature_size, size_t *signature_length)
Sign an already-calculated hash with an RSA private key.
psa_status_t mbedtls_psa_rsa_export_public_key(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, uint8_t *data, size_t data_size, size_t *data_length)
Export a public RSA key or the public part of an RSA key pair in binary format.
This file provides an API for the RSA public-key cryptosystem.
Definition: _hash_fun.h:40
The RSA context structure.
Definition: rsa.h:85
Definition: type.c:6
Modified on Tue Jul 23 17:51:34 2024 by modify_doxy.py rev. 669887