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 * \param[in] attributes The attributes for the RSA key to generate. 109 * \param[in] custom_data The public exponent to use. 110 * This can be a null pointer if 111 * \c params_data_length is 0. 112 * \param custom_data_length Length of \p custom_data in bytes. 113 * This can be 0, in which case the 114 * public exponent will be 65537. 115 * \param[out] key_buffer Buffer where the key data is to be written. 116 * \param[in] key_buffer_size Size of \p key_buffer in bytes. 117 * \param[out] key_buffer_length On success, the number of bytes written in 118 * \p key_buffer. 119 * 120 * \retval #PSA_SUCCESS 121 * The key was successfully generated. 122 * \retval #PSA_ERROR_NOT_SUPPORTED 123 * Key length or type not supported. 124 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 125 * The size of \p key_buffer is too small. 126 */ 127 psa_status_t mbedtls_psa_rsa_generate_key( 128 const psa_key_attributes_t *attributes, 129 const uint8_t *custom_data, size_t custom_data_length, 130 uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length); 131 132 /** Sign an already-calculated hash with an RSA private key. 133 * 134 * \note The signature of this function is that of a PSA driver 135 * sign_hash entry point. This function behaves as a sign_hash 136 * entry point as defined in the PSA driver interface specification for 137 * transparent drivers. 138 * 139 * \param[in] attributes The attributes of the RSA key to use for the 140 * operation. 141 * \param[in] key_buffer The buffer containing the RSA key context. 142 * format. 143 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 144 * \param[in] alg A signature algorithm that is compatible with 145 * an RSA key. 146 * \param[in] hash The hash or message to sign. 147 * \param[in] hash_length Size of the \p hash buffer in bytes. 148 * \param[out] signature Buffer where the signature is to be written. 149 * \param[in] signature_size Size of the \p signature buffer in bytes. 150 * \param[out] signature_length On success, the number of bytes 151 * that make up the returned signature value. 152 * 153 * \retval #PSA_SUCCESS \emptydescription 154 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 155 * The size of the \p signature buffer is too small. You can 156 * determine a sufficient buffer size by calling 157 * #PSA_SIGN_OUTPUT_SIZE(\c PSA_KEY_TYPE_RSA_KEY_PAIR, \c key_bits, 158 * \p alg) where \c key_bits is the bit-size of the RSA key. 159 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 160 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 161 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 162 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 163 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 164 */ 165 psa_status_t mbedtls_psa_rsa_sign_hash( 166 const psa_key_attributes_t *attributes, 167 const uint8_t *key_buffer, size_t key_buffer_size, 168 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, 169 uint8_t *signature, size_t signature_size, size_t *signature_length); 170 171 /** 172 * \brief Verify the signature a hash or short message using a public RSA key. 173 * 174 * \note The signature of this function is that of a PSA driver 175 * verify_hash entry point. This function behaves as a verify_hash 176 * entry point as defined in the PSA driver interface specification for 177 * transparent drivers. 178 * 179 * \param[in] attributes The attributes of the RSA key to use for the 180 * operation. 181 * \param[in] key_buffer The buffer containing the RSA key context. 182 * format. 183 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 184 * \param[in] alg A signature algorithm that is compatible with 185 * an RSA key. 186 * \param[in] hash The hash or message whose signature is to be 187 * verified. 188 * \param[in] hash_length Size of the \p hash buffer in bytes. 189 * \param[in] signature Buffer containing the signature to verify. 190 * \param[in] signature_length Size of the \p signature buffer in bytes. 191 * 192 * \retval #PSA_SUCCESS 193 * The signature is valid. 194 * \retval #PSA_ERROR_INVALID_SIGNATURE 195 * The calculation was performed successfully, but the passed 196 * signature is not a valid signature. 197 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 198 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 199 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 200 */ 201 psa_status_t mbedtls_psa_rsa_verify_hash( 202 const psa_key_attributes_t *attributes, 203 const uint8_t *key_buffer, size_t key_buffer_size, 204 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, 205 const uint8_t *signature, size_t signature_length); 206 207 /** 208 * \brief Encrypt a short message with a public key. 209 * 210 * \param attributes The attributes for the key to import. 211 * \param key_buffer Buffer where the key data is to be written. 212 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 213 * \param input_length Size of the \p input buffer in bytes. 214 * \param[in] salt A salt or label, if supported by the 215 * encryption algorithm. 216 * If the algorithm does not support a 217 * salt, pass \c NULL. 218 * If the algorithm supports an optional 219 * salt and you do not want to pass a salt, 220 * pass \c NULL. 221 * 222 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 223 * supported. 224 * \param salt_length Size of the \p salt buffer in bytes. 225 * If \p salt is \c NULL, pass 0. 226 * \param[out] output Buffer where the encrypted message is to 227 * be written. 228 * \param output_size Size of the \p output buffer in bytes. 229 * \param[out] output_length On success, the number of bytes 230 * that make up the returned output. 231 * 232 * \retval #PSA_SUCCESS \emptydescription 233 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 234 * The size of the \p output buffer is too small. You can 235 * determine a sufficient buffer size by calling 236 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 237 * where \c key_type and \c key_bits are the type and bit-size 238 * respectively of \p key. 239 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 240 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 241 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 242 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 243 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 244 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 245 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 246 * \retval #PSA_ERROR_BAD_STATE 247 * The library has not been previously initialized by psa_crypto_init(). 248 * It is implementation-dependent whether a failure to initialize 249 * results in this error code. 250 */ 251 psa_status_t mbedtls_psa_asymmetric_encrypt(const psa_key_attributes_t *attributes, 252 const uint8_t *key_buffer, 253 size_t key_buffer_size, 254 psa_algorithm_t alg, 255 const uint8_t *input, 256 size_t input_length, 257 const uint8_t *salt, 258 size_t salt_length, 259 uint8_t *output, 260 size_t output_size, 261 size_t *output_length); 262 263 /** 264 * \brief Decrypt a short message with a private key. 265 * 266 * \param attributes The attributes for the key to import. 267 * \param key_buffer Buffer where the key data is to be written. 268 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 269 * \param[in] input The message to decrypt. 270 * \param input_length Size of the \p input buffer in bytes. 271 * \param[in] salt A salt or label, if supported by the 272 * encryption algorithm. 273 * If the algorithm does not support a 274 * salt, pass \c NULL. 275 * If the algorithm supports an optional 276 * salt and you do not want to pass a salt, 277 * pass \c NULL. 278 * 279 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 280 * supported. 281 * \param salt_length Size of the \p salt buffer in bytes. 282 * If \p salt is \c NULL, pass 0. 283 * \param[out] output Buffer where the decrypted message is to 284 * be written. 285 * \param output_size Size of the \c output buffer in bytes. 286 * \param[out] output_length On success, the number of bytes 287 * that make up the returned output. 288 * 289 * \retval #PSA_SUCCESS \emptydescription 290 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 291 * The size of the \p output buffer is too small. You can 292 * determine a sufficient buffer size by calling 293 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 294 * where \c key_type and \c key_bits are the type and bit-size 295 * respectively of \p key. 296 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 297 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 298 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 299 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 300 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 301 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 302 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 303 * \retval #PSA_ERROR_INVALID_PADDING \emptydescription 304 * \retval #PSA_ERROR_BAD_STATE 305 * The library has not been previously initialized by psa_crypto_init(). 306 * It is implementation-dependent whether a failure to initialize 307 * results in this error code. 308 */ 309 psa_status_t mbedtls_psa_asymmetric_decrypt(const psa_key_attributes_t *attributes, 310 const uint8_t *key_buffer, 311 size_t key_buffer_size, 312 psa_algorithm_t alg, 313 const uint8_t *input, 314 size_t input_length, 315 const uint8_t *salt, 316 size_t salt_length, 317 uint8_t *output, 318 size_t output_size, 319 size_t *output_length); 320 321 #endif /* PSA_CRYPTO_RSA_H */ 322
