common/mbedtls/psa_crypto_rsa.h

   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
  65  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  66  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  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
 106  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
 107  * \retval #PSA_ERROR_HARDWARE_FAILURE
 108  * \retval #PSA_ERROR_CORRUPTION_DETECTED
 109  * \retval #PSA_ERROR_STORAGE_FAILURE
 110  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 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
 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
 168  * \retval #PSA_ERROR_INVALID_ARGUMENT
 169  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 170  * \retval #PSA_ERROR_CORRUPTION_DETECTED
 171  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
 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
 206  * \retval #PSA_ERROR_INVALID_ARGUMENT
 207  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
 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  * BEYOND THIS POINT, TEST DRIVER ENTRY POINTS ONLY.
 217  */
 218
 219 #if defined(PSA_CRYPTO_DRIVER_TEST)
 220
 221 psa_status_t mbedtls_transparent_test_driver_rsa_import_key(
 222     const psa_key_attributes_t *attributes,
 223     const uint8_t *data, size_t data_length,
 224     uint8_t *key_buffer, size_t key_buffer_size,
 225     size_t *key_buffer_length, size_t *bits);
 226
 227 psa_status_t mbedtls_transparent_test_driver_rsa_export_public_key(
 228     const psa_key_attributes_t *attributes,
 229     const uint8_t *key_buffer, size_t key_buffer_size,
 230     uint8_t *data, size_t data_size, size_t *data_length);
 231
 232 psa_status_t mbedtls_transparent_test_driver_rsa_generate_key(
 233     const psa_key_attributes_t *attributes,
 234     uint8_t *key, size_t key_size, size_t *key_length);
 235
 236 psa_status_t mbedtls_transparent_test_driver_rsa_sign_hash(
 237     const psa_key_attributes_t *attributes,
 238     const uint8_t *key_buffer, size_t key_buffer_size,
 239     psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
 240     uint8_t *signature, size_t signature_size, size_t *signature_length);
 241
 242 psa_status_t mbedtls_transparent_test_driver_rsa_verify_hash(
 243     const psa_key_attributes_t *attributes,
 244     const uint8_t *key_buffer, size_t key_buffer_size,
 245     psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
 246     const uint8_t *signature, size_t signature_length);
 247
 248 #endif /* PSA_CRYPTO_DRIVER_TEST */
 249
 250 #endif /* PSA_CRYPTO_RSA_H */