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