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 7 * 8 * Licensed under the Apache License, Version 2.0 (the "License"); you may 9 * not use this file except in compliance with the License. 10 * You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 */ 20 21 #ifndef PSA_CRYPTO_RSA_H 22 #define PSA_CRYPTO_RSA_H 23 24 #include <psa/crypto.h> 25 #include <mbedtls/rsa.h> 26 27 /** Load the contents of a key buffer into an internal RSA representation 28 * 29 * \param[in] type The type of key contained in \p data. 30 * \param[in] data The buffer from which to load the representation. 31 * \param[in] data_length The size in bytes of \p data. 32 * \param[out] p_rsa Returns a pointer to an RSA context on success. 33 * The caller is responsible for freeing both the 34 * contents of the context and the context itself 35 * when done. 36 */ 37 psa_status_t mbedtls_psa_rsa_load_representation(psa_key_type_t type, 38 const uint8_t *data, 39 size_t data_length, 40 mbedtls_rsa_context **p_rsa); 41 42 /** Import an RSA key in binary format. 43 * 44 * \note The signature of this function is that of a PSA driver 45 * import_key entry point. This function behaves as an import_key 46 * entry point as defined in the PSA driver interface specification for 47 * transparent drivers. 48 * 49 * \param[in] attributes The attributes for the key to import. 50 * \param[in] data The buffer containing the key data in import 51 * format. 52 * \param[in] data_length Size of the \p data buffer in bytes. 53 * \param[out] key_buffer The buffer containing the key data in output 54 * format. 55 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. This 56 * size is greater or equal to \p data_length. 57 * \param[out] key_buffer_length The length of the data written in \p 58 * key_buffer in bytes. 59 * \param[out] bits The key size in number of bits. 60 * 61 * \retval #PSA_SUCCESS The RSA key was imported successfully. 62 * \retval #PSA_ERROR_INVALID_ARGUMENT 63 * The key data is not correctly formatted. 64 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 65 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 66 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 67 */ 68 psa_status_t mbedtls_psa_rsa_import_key( 69 const psa_key_attributes_t *attributes, 70 const uint8_t *data, size_t data_length, 71 uint8_t *key_buffer, size_t key_buffer_size, 72 size_t *key_buffer_length, size_t *bits); 73 74 /** Export an RSA key to export representation 75 * 76 * \param[in] type The type of key (public/private) to export 77 * \param[in] rsa The internal RSA representation from which to export 78 * \param[out] data The buffer to export to 79 * \param[in] data_size The length of the buffer to export to 80 * \param[out] data_length The amount of bytes written to \p data 81 */ 82 psa_status_t mbedtls_psa_rsa_export_key(psa_key_type_t type, 83 mbedtls_rsa_context *rsa, 84 uint8_t *data, 85 size_t data_size, 86 size_t *data_length); 87 88 /** Export a public RSA key or the public part of an RSA key pair in binary 89 * format. 90 * 91 * \note The signature of this function is that of a PSA driver 92 * export_public_key entry point. This function behaves as an 93 * export_public_key entry point as defined in the PSA driver interface 94 * specification. 95 * 96 * \param[in] attributes The attributes for the key to export. 97 * \param[in] key_buffer Material or context of the key to export. 98 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 99 * \param[out] data Buffer where the key data is to be written. 100 * \param[in] data_size Size of the \p data buffer in bytes. 101 * \param[out] data_length On success, the number of bytes written in 102 * \p data. 103 * 104 * \retval #PSA_SUCCESS The RSA public key was exported successfully. 105 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 106 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 107 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 108 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 109 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 110 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 111 */ 112 psa_status_t mbedtls_psa_rsa_export_public_key( 113 const psa_key_attributes_t *attributes, 114 const uint8_t *key_buffer, size_t key_buffer_size, 115 uint8_t *data, size_t data_size, size_t *data_length); 116 117 /** 118 * \brief Generate an RSA key. 119 * 120 * \note The signature of the function is that of a PSA driver generate_key 121 * entry point. 122 * 123 * \param[in] attributes The attributes for the RSA key to generate. 124 * \param[out] key_buffer Buffer where the key data is to be written. 125 * \param[in] key_buffer_size Size of \p key_buffer in bytes. 126 * \param[out] key_buffer_length On success, the number of bytes written in 127 * \p key_buffer. 128 * 129 * \retval #PSA_SUCCESS 130 * The key was successfully generated. 131 * \retval #PSA_ERROR_NOT_SUPPORTED 132 * Key length or type not supported. 133 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 134 * The size of \p key_buffer is too small. 135 */ 136 psa_status_t mbedtls_psa_rsa_generate_key( 137 const psa_key_attributes_t *attributes, 138 uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length); 139 140 /** Sign an already-calculated hash with an RSA private key. 141 * 142 * \note The signature of this function is that of a PSA driver 143 * sign_hash entry point. This function behaves as a sign_hash 144 * entry point as defined in the PSA driver interface specification for 145 * transparent drivers. 146 * 147 * \param[in] attributes The attributes of the RSA key to use for the 148 * operation. 149 * \param[in] key_buffer The buffer containing the RSA key context. 150 * format. 151 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 152 * \param[in] alg A signature algorithm that is compatible with 153 * an RSA key. 154 * \param[in] hash The hash or message to sign. 155 * \param[in] hash_length Size of the \p hash buffer in bytes. 156 * \param[out] signature Buffer where the signature is to be written. 157 * \param[in] signature_size Size of the \p signature buffer in bytes. 158 * \param[out] signature_length On success, the number of bytes 159 * that make up the returned signature value. 160 * 161 * \retval #PSA_SUCCESS \emptydescription 162 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 163 * The size of the \p signature buffer is too small. You can 164 * determine a sufficient buffer size by calling 165 * #PSA_SIGN_OUTPUT_SIZE(\c PSA_KEY_TYPE_RSA_KEY_PAIR, \c key_bits, 166 * \p alg) where \c key_bits is the bit-size of the RSA key. 167 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 168 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 169 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 170 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 171 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 172 */ 173 psa_status_t mbedtls_psa_rsa_sign_hash( 174 const psa_key_attributes_t *attributes, 175 const uint8_t *key_buffer, size_t key_buffer_size, 176 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, 177 uint8_t *signature, size_t signature_size, size_t *signature_length); 178 179 /** 180 * \brief Verify the signature a hash or short message using a public RSA key. 181 * 182 * \note The signature of this function is that of a PSA driver 183 * verify_hash entry point. This function behaves as a verify_hash 184 * entry point as defined in the PSA driver interface specification for 185 * transparent drivers. 186 * 187 * \param[in] attributes The attributes of the RSA key to use for the 188 * operation. 189 * \param[in] key_buffer The buffer containing the RSA key context. 190 * format. 191 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 192 * \param[in] alg A signature algorithm that is compatible with 193 * an RSA key. 194 * \param[in] hash The hash or message whose signature is to be 195 * verified. 196 * \param[in] hash_length Size of the \p hash buffer in bytes. 197 * \param[in] signature Buffer containing the signature to verify. 198 * \param[in] signature_length Size of the \p signature buffer in bytes. 199 * 200 * \retval #PSA_SUCCESS 201 * The signature is valid. 202 * \retval #PSA_ERROR_INVALID_SIGNATURE 203 * The calculation was performed successfully, but the passed 204 * signature is not a valid signature. 205 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 206 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 207 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 208 */ 209 psa_status_t mbedtls_psa_rsa_verify_hash( 210 const psa_key_attributes_t *attributes, 211 const uint8_t *key_buffer, size_t key_buffer_size, 212 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, 213 const uint8_t *signature, size_t signature_length); 214 215 /** 216 * \brief Encrypt a short message with a public key. 217 * 218 * \param attributes The attributes for the key to import. 219 * \param key_buffer Buffer where the key data is to be written. 220 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 221 * \param input_length Size of the \p input buffer in bytes. 222 * \param[in] salt A salt or label, if supported by the 223 * encryption algorithm. 224 * If the algorithm does not support a 225 * salt, pass \c NULL. 226 * If the algorithm supports an optional 227 * salt and you do not want to pass a salt, 228 * pass \c NULL. 229 * 230 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 231 * supported. 232 * \param salt_length Size of the \p salt buffer in bytes. 233 * If \p salt is \c NULL, pass 0. 234 * \param[out] output Buffer where the encrypted message is to 235 * be written. 236 * \param output_size Size of the \p output buffer in bytes. 237 * \param[out] output_length On success, the number of bytes 238 * that make up the returned output. 239 * 240 * \retval #PSA_SUCCESS \emptydescription 241 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 242 * The size of the \p output buffer is too small. You can 243 * determine a sufficient buffer size by calling 244 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 245 * where \c key_type and \c key_bits are the type and bit-size 246 * respectively of \p key. 247 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 248 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 249 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 250 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 251 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 252 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 253 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 254 * \retval #PSA_ERROR_BAD_STATE 255 * The library has not been previously initialized by psa_crypto_init(). 256 * It is implementation-dependent whether a failure to initialize 257 * results in this error code. 258 */ 259 psa_status_t mbedtls_psa_asymmetric_encrypt(const psa_key_attributes_t *attributes, 260 const uint8_t *key_buffer, 261 size_t key_buffer_size, 262 psa_algorithm_t alg, 263 const uint8_t *input, 264 size_t input_length, 265 const uint8_t *salt, 266 size_t salt_length, 267 uint8_t *output, 268 size_t output_size, 269 size_t *output_length); 270 271 /** 272 * \brief Decrypt a short message with a private key. 273 * 274 * \param attributes The attributes for the key to import. 275 * \param key_buffer Buffer where the key data is to be written. 276 * \param key_buffer_size Size of the \p key_buffer buffer in bytes. 277 * \param[in] input The message to decrypt. 278 * \param input_length Size of the \p input buffer in bytes. 279 * \param[in] salt A salt or label, if supported by the 280 * encryption algorithm. 281 * If the algorithm does not support a 282 * salt, pass \c NULL. 283 * If the algorithm supports an optional 284 * salt and you do not want to pass a salt, 285 * pass \c NULL. 286 * 287 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is 288 * supported. 289 * \param salt_length Size of the \p salt buffer in bytes. 290 * If \p salt is \c NULL, pass 0. 291 * \param[out] output Buffer where the decrypted message is to 292 * be written. 293 * \param output_size Size of the \c output buffer in bytes. 294 * \param[out] output_length On success, the number of bytes 295 * that make up the returned output. 296 * 297 * \retval #PSA_SUCCESS \emptydescription 298 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 299 * The size of the \p output buffer is too small. You can 300 * determine a sufficient buffer size by calling 301 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg) 302 * where \c key_type and \c key_bits are the type and bit-size 303 * respectively of \p key. 304 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 305 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 306 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 307 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 308 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 309 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 310 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 311 * \retval #PSA_ERROR_INVALID_PADDING \emptydescription 312 * \retval #PSA_ERROR_BAD_STATE 313 * The library has not been previously initialized by psa_crypto_init(). 314 * It is implementation-dependent whether a failure to initialize 315 * results in this error code. 316 */ 317 psa_status_t mbedtls_psa_asymmetric_decrypt(const psa_key_attributes_t *attributes, 318 const uint8_t *key_buffer, 319 size_t key_buffer_size, 320 psa_algorithm_t alg, 321 const uint8_t *input, 322 size_t input_length, 323 const uint8_t *salt, 324 size_t salt_length, 325 uint8_t *output, 326 size_t output_size, 327 size_t *output_length); 328 329 #endif /* PSA_CRYPTO_RSA_H */ 330