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 */ 25 psa_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 */ 56 psa_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 */ 70 psa_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 */ 100 psa_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 */ 133 psa_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 */ 171 psa_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 */ 207 psa_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 */ 257 psa_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 */ 315 psa_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
