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 #endif /* PSA_CRYPTO_RSA_H */ 204