p256-m_driver_entrypoints.h (9942B)
1 /* 2 * Driver entry points for p256-m 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 P256M_DRIVER_ENTRYPOINTS_H 10 #define P256M_DRIVER_ENTRYPOINTS_H 11 12 #if defined(MBEDTLS_PSA_P256M_DRIVER_ENABLED) 13 #ifndef PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT 14 #define PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT 15 #endif /* PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT */ 16 #endif /* MBEDTLS_PSA_P256M_DRIVER_ENABLED */ 17 18 #include "psa/crypto_types.h" 19 20 /** Import SECP256R1 key. 21 * 22 * \param[in] attributes The attributes of the key to use for the 23 * operation. 24 * \param[in] data The raw key material. For private keys 25 * this must be a big-endian integer of 32 26 * bytes; for public key this must be an 27 * uncompressed ECPoint (65 bytes). 28 * \param[in] data_length The size of the raw key material. 29 * \param[out] key_buffer The buffer to contain the key data in 30 * output format upon successful return. 31 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 32 * \param[out] key_buffer_length The length of the data written in \p 33 * key_buffer in bytes. 34 * \param[out] bits The bitsize of the key. 35 * 36 * \retval #PSA_SUCCESS 37 * Success. Keypair generated and stored in buffer. 38 * \retval #PSA_ERROR_NOT_SUPPORTED 39 * The input is not supported by this driver (not SECP256R1). 40 * \retval #PSA_ERROR_INVALID_ARGUMENT 41 * The input is invalid. 42 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 43 * \p key_buffer_size is too small. 44 */ 45 psa_status_t p256_transparent_import_key(const psa_key_attributes_t *attributes, 46 const uint8_t *data, 47 size_t data_length, 48 uint8_t *key_buffer, 49 size_t key_buffer_size, 50 size_t *key_buffer_length, 51 size_t *bits); 52 53 /** Export SECP256R1 public key, from the private key. 54 * 55 * \param[in] attributes The attributes of the key to use for the 56 * operation. 57 * \param[in] key_buffer The private key in the export format. 58 * \param[in] key_buffer_size The size of the private key in bytes. 59 * \param[out] data The buffer to contain the public key in 60 * the export format upon successful return. 61 * \param[in] data_size The size of the \p data buffer in bytes. 62 * \param[out] data_length The length written to \p data in bytes. 63 * 64 * \retval #PSA_SUCCESS 65 * Success. Keypair generated and stored in buffer. 66 * \retval #PSA_ERROR_NOT_SUPPORTED 67 * The input is not supported by this driver (not SECP256R1). 68 * \retval #PSA_ERROR_INVALID_ARGUMENT 69 * The input is invalid. 70 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 71 * \p key_buffer_size is too small. 72 */ 73 psa_status_t p256_transparent_export_public_key(const psa_key_attributes_t *attributes, 74 const uint8_t *key_buffer, 75 size_t key_buffer_size, 76 uint8_t *data, 77 size_t data_size, 78 size_t *data_length); 79 80 /** Generate SECP256R1 ECC Key Pair. 81 * Interface function which calls the p256-m key generation function and 82 * places it in the key buffer provided by the caller (Mbed TLS) in the 83 * correct format. For a SECP256R1 curve this is the 32 bit private key. 84 * 85 * \param[in] attributes The attributes of the key to use for the 86 * operation. 87 * \param[out] key_buffer The buffer to contain the key data in 88 * output format upon successful return. 89 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 90 * \param[out] key_buffer_length The length of the data written in \p 91 * key_buffer in bytes. 92 * 93 * \retval #PSA_SUCCESS 94 * Success. Keypair generated and stored in buffer. 95 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 96 * \p key_buffer_size is too small. 97 * \retval #PSA_ERROR_GENERIC_ERROR 98 * The internal RNG failed. 99 */ 100 psa_status_t p256_transparent_generate_key( 101 const psa_key_attributes_t *attributes, 102 uint8_t *key_buffer, 103 size_t key_buffer_size, 104 size_t *key_buffer_length); 105 106 /** Perform raw key agreement using p256-m's ECDH implementation 107 * \param[in] attributes The attributes of the key to use for the 108 * operation. 109 * \param[in] key_buffer The buffer containing the private key 110 * in the format specified by PSA. 111 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 112 * \param[in] alg A key agreement algorithm that is 113 * compatible with the type of the key. 114 * \param[in] peer_key The buffer containing the peer's public 115 * key in format specified by PSA. 116 * \param[in] peer_key_length Size of the \p peer_key buffer in 117 * bytes. 118 * \param[out] shared_secret The buffer to which the shared secret 119 * is to be written. 120 * \param[in] shared_secret_size Size of the \p shared_secret buffer in 121 * bytes. 122 * \param[out] shared_secret_length On success, the number of bytes that 123 * make up the returned shared secret. 124 * \retval #PSA_SUCCESS 125 * Success. Shared secret successfully calculated. 126 * \retval #PSA_ERROR_INVALID_ARGUMENT 127 * The input is invalid. 128 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 129 * \p shared_secret_size is too small. 130 */ 131 psa_status_t p256_transparent_key_agreement( 132 const psa_key_attributes_t *attributes, 133 const uint8_t *key_buffer, 134 size_t key_buffer_size, 135 psa_algorithm_t alg, 136 const uint8_t *peer_key, 137 size_t peer_key_length, 138 uint8_t *shared_secret, 139 size_t shared_secret_size, 140 size_t *shared_secret_length); 141 142 /** Sign an already-calculated hash with a private key using p256-m's ECDSA 143 * implementation 144 * \param[in] attributes The attributes of the key to use for the 145 * operation. 146 * \param[in] key_buffer The buffer containing the private key 147 * in the format specified by PSA. 148 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 149 * \param[in] alg A signature algorithm that is compatible 150 * with the type of the key. 151 * \param[in] hash The hash to sign. 152 * \param[in] hash_length Size of the \p hash buffer in bytes. 153 * \param[out] signature Buffer where signature is to be written. 154 * \param[in] signature_size Size of the \p signature buffer in bytes. 155 * \param[out] signature_length On success, the number of bytes 156 * that make up the returned signature value. 157 * 158 * \retval #PSA_SUCCESS 159 * Success. Hash was signed successfully. 160 * \retval #PSA_ERROR_INVALID_ARGUMENT 161 * The input is invalid. 162 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 163 * \p signature_size is too small. 164 * \retval #PSA_ERROR_GENERIC_ERROR 165 * The internal RNG failed. 166 */ 167 psa_status_t p256_transparent_sign_hash( 168 const psa_key_attributes_t *attributes, 169 const uint8_t *key_buffer, 170 size_t key_buffer_size, 171 psa_algorithm_t alg, 172 const uint8_t *hash, 173 size_t hash_length, 174 uint8_t *signature, 175 size_t signature_size, 176 size_t *signature_length); 177 178 /** Verify the signature of a hash using a SECP256R1 public key using p256-m's 179 * ECDSA implementation. 180 * 181 * \note p256-m expects a 64 byte public key, but the contents of the key 182 buffer may be the 32 byte keypair representation or the 65 byte 183 public key representation. As a result, this function calls 184 psa_driver_wrapper_export_public_key() to ensure the public key 185 can be passed to p256-m. 186 * 187 * \param[in] attributes The attributes of the key to use for the 188 * operation. 189 * 190 * \param[in] key_buffer The buffer containing the key 191 * in the format specified by PSA. 192 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 193 * \param[in] alg A signature algorithm that is compatible with 194 * the type of the key. 195 * \param[in] hash The hash whose signature is to be 196 * verified. 197 * \param[in] hash_length Size of the \p hash buffer in bytes. 198 * \param[in] signature Buffer containing the signature to verify. 199 * \param[in] signature_length Size of the \p signature buffer in bytes. 200 * 201 * \retval #PSA_SUCCESS 202 * The signature is valid. 203 * \retval #PSA_ERROR_INVALID_SIGNATURE 204 * The calculation was performed successfully, but the passed 205 * signature is not a valid signature. 206 * \retval #PSA_ERROR_INVALID_ARGUMENT 207 * The input is invalid. 208 */ 209 psa_status_t p256_transparent_verify_hash( 210 const psa_key_attributes_t *attributes, 211 const uint8_t *key_buffer, 212 size_t key_buffer_size, 213 psa_algorithm_t alg, 214 const uint8_t *hash, 215 size_t hash_length, 216 const uint8_t *signature, 217 size_t signature_length); 218 219 #endif /* P256M_DRIVER_ENTRYPOINTS_H */