1 /* 2 * PSA ECP 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_ECP_H 10 #define PSA_CRYPTO_ECP_H 11 12 #include <psa/crypto.h> 13 #include <mbedtls/ecp.h> 14 15 /** Load the contents of a key buffer into an internal ECP representation 16 * 17 * \param[in] type The type of key contained in \p data. 18 * \param[in] curve_bits The nominal bit-size of the curve. 19 * It must be consistent with the representation 20 * passed in \p data. 21 * This can be 0, in which case the bit-size 22 * is inferred from \p data_length (which is possible 23 * for all key types and representation formats 24 * formats that are currently supported or will 25 * be in the foreseeable future). 26 * \param[in] data The buffer from which to load the representation. 27 * \param[in] data_length The size in bytes of \p data. 28 * \param[out] p_ecp Returns a pointer to an ECP context on success. 29 * The caller is responsible for freeing both the 30 * contents of the context and the context itself 31 * when done. 32 */ 33 psa_status_t mbedtls_psa_ecp_load_representation(psa_key_type_t type, 34 size_t curve_bits, 35 const uint8_t *data, 36 size_t data_length, 37 mbedtls_ecp_keypair **p_ecp); 38 39 /** Import an ECP key in binary format. 40 * 41 * \note The signature of this function is that of a PSA driver 42 * import_key entry point. This function behaves as an import_key 43 * entry point as defined in the PSA driver interface specification for 44 * transparent drivers. 45 * 46 * \param[in] attributes The attributes for the key to import. 47 * \param[in] data The buffer containing the key data in import 48 * format. 49 * \param[in] data_length Size of the \p data buffer in bytes. 50 * \param[out] key_buffer The buffer containing the key data in output 51 * format. 52 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. This 53 * size is greater or equal to \p data_length. 54 * \param[out] key_buffer_length The length of the data written in \p 55 * key_buffer in bytes. 56 * \param[out] bits The key size in number of bits. 57 * 58 * \retval #PSA_SUCCESS The ECP key was imported successfully. 59 * \retval #PSA_ERROR_INVALID_ARGUMENT 60 * The key data is not correctly formatted. 61 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 62 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 63 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 64 */ 65 psa_status_t mbedtls_psa_ecp_import_key( 66 const psa_key_attributes_t *attributes, 67 const uint8_t *data, size_t data_length, 68 uint8_t *key_buffer, size_t key_buffer_size, 69 size_t *key_buffer_length, size_t *bits); 70 71 /** Export an ECP key to export representation 72 * 73 * \param[in] type The type of key (public/private) to export 74 * \param[in] ecp The internal ECP representation from which to export 75 * \param[out] data The buffer to export to 76 * \param[in] data_size The length of the buffer to export to 77 * \param[out] data_length The amount of bytes written to \p data 78 */ 79 psa_status_t mbedtls_psa_ecp_export_key(psa_key_type_t type, 80 mbedtls_ecp_keypair *ecp, 81 uint8_t *data, 82 size_t data_size, 83 size_t *data_length); 84 85 /** Export an ECP public key or the public part of an ECP key pair in binary 86 * format. 87 * 88 * \note The signature of this function is that of a PSA driver 89 * export_public_key entry point. This function behaves as an 90 * export_public_key entry point as defined in the PSA driver interface 91 * specification. 92 * 93 * \param[in] attributes The attributes for the key to export. 94 * \param[in] key_buffer Material or context of the key to export. 95 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 96 * \param[out] data Buffer where the key data is to be written. 97 * \param[in] data_size Size of the \p data buffer in bytes. 98 * \param[out] data_length On success, the number of bytes written in 99 * \p data 100 * 101 * \retval #PSA_SUCCESS The ECP public key was exported successfully. 102 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 103 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 104 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 105 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 106 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 107 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 108 */ 109 psa_status_t mbedtls_psa_ecp_export_public_key( 110 const psa_key_attributes_t *attributes, 111 const uint8_t *key_buffer, size_t key_buffer_size, 112 uint8_t *data, size_t data_size, size_t *data_length); 113 114 /** 115 * \brief Generate an ECP key. 116 * 117 * \note The signature of the function is that of a PSA driver generate_key 118 * entry point. 119 * 120 * \param[in] attributes The attributes for the ECP key to generate. 121 * \param[out] key_buffer Buffer where the key data is to be written. 122 * \param[in] key_buffer_size Size of \p key_buffer in bytes. 123 * \param[out] key_buffer_length On success, the number of bytes written in 124 * \p key_buffer. 125 * 126 * \retval #PSA_SUCCESS 127 * The key was successfully generated. 128 * \retval #PSA_ERROR_NOT_SUPPORTED 129 * Key length or type not supported. 130 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 131 * The size of \p key_buffer is too small. 132 */ 133 psa_status_t mbedtls_psa_ecp_generate_key( 134 const psa_key_attributes_t *attributes, 135 uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length); 136 137 /** Sign an already-calculated hash with ECDSA. 138 * 139 * \note The signature of this function is that of a PSA driver 140 * sign_hash entry point. This function behaves as a sign_hash 141 * entry point as defined in the PSA driver interface specification for 142 * transparent drivers. 143 * 144 * \param[in] attributes The attributes of the ECC key to use for the 145 * operation. 146 * \param[in] key_buffer The buffer containing the ECC key context. 147 * format. 148 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 149 * \param[in] alg Randomized or deterministic ECDSA algorithm. 150 * \param[in] hash The hash or message to sign. 151 * \param[in] hash_length Size of the \p hash buffer in bytes. 152 * \param[out] signature Buffer where the signature is to be written. 153 * \param[in] signature_size Size of the \p signature buffer in bytes. 154 * \param[out] signature_length On success, the number of bytes 155 * that make up the returned signature value. 156 * 157 * \retval #PSA_SUCCESS \emptydescription 158 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 159 * The size of the \p signature buffer is too small. You can 160 * determine a sufficient buffer size by calling 161 * #PSA_SIGN_OUTPUT_SIZE(\c PSA_KEY_TYPE_ECC_KEY_PAIR, \c key_bits, 162 * \p alg) where \c key_bits is the bit-size of the ECC key. 163 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 164 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 165 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 166 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 167 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 168 */ 169 psa_status_t mbedtls_psa_ecdsa_sign_hash( 170 const psa_key_attributes_t *attributes, 171 const uint8_t *key_buffer, size_t key_buffer_size, 172 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, 173 uint8_t *signature, size_t signature_size, size_t *signature_length); 174 175 /** 176 * \brief Verify an ECDSA hash or short message signature. 177 * 178 * \note The signature of this function is that of a PSA driver 179 * verify_hash entry point. This function behaves as a verify_hash 180 * entry point as defined in the PSA driver interface specification for 181 * transparent drivers. 182 * 183 * \param[in] attributes The attributes of the ECC key to use for the 184 * operation. 185 * \param[in] key_buffer The buffer containing the ECC key context. 186 * format. 187 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 188 * \param[in] alg Randomized or deterministic ECDSA algorithm. 189 * \param[in] hash The hash or message whose signature is to be 190 * verified. 191 * \param[in] hash_length Size of the \p hash buffer in bytes. 192 * \param[in] signature Buffer containing the signature to verify. 193 * \param[in] signature_length Size of the \p signature buffer in bytes. 194 * 195 * \retval #PSA_SUCCESS 196 * The signature is valid. 197 * \retval #PSA_ERROR_INVALID_SIGNATURE 198 * The calculation was performed successfully, but the passed 199 * signature is not a valid signature. 200 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 201 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 202 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 203 */ 204 psa_status_t mbedtls_psa_ecdsa_verify_hash( 205 const psa_key_attributes_t *attributes, 206 const uint8_t *key_buffer, size_t key_buffer_size, 207 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, 208 const uint8_t *signature, size_t signature_length); 209 210 #endif /* PSA_CRYPTO_ECP_H */ 211