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 /** Load the public part of an internal ECP, if required. 40 * 41 * \param ecp The ECP context to load the public part for. 42 * 43 * \return PSA_SUCCESS on success, otherwise an MPI error. 44 */ 45 46 psa_status_t mbedtls_psa_ecp_load_public_part(mbedtls_ecp_keypair *ecp); 47 48 /** Import an ECP key in binary format. 49 * 50 * \note The signature of this function is that of a PSA driver 51 * import_key entry point. This function behaves as an import_key 52 * entry point as defined in the PSA driver interface specification for 53 * transparent drivers. 54 * 55 * \param[in] attributes The attributes for the key to import. 56 * \param[in] data The buffer containing the key data in import 57 * format. 58 * \param[in] data_length Size of the \p data buffer in bytes. 59 * \param[out] key_buffer The buffer containing the key data in output 60 * format. 61 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. This 62 * size is greater or equal to \p data_length. 63 * \param[out] key_buffer_length The length of the data written in \p 64 * key_buffer in bytes. 65 * \param[out] bits The key size in number of bits. 66 * 67 * \retval #PSA_SUCCESS The ECP key was imported successfully. 68 * \retval #PSA_ERROR_INVALID_ARGUMENT 69 * The key data is not correctly formatted. 70 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 71 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 72 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 73 */ 74 psa_status_t mbedtls_psa_ecp_import_key( 75 const psa_key_attributes_t *attributes, 76 const uint8_t *data, size_t data_length, 77 uint8_t *key_buffer, size_t key_buffer_size, 78 size_t *key_buffer_length, size_t *bits); 79 80 /** Export an ECP key to export representation 81 * 82 * \param[in] type The type of key (public/private) to export 83 * \param[in] ecp The internal ECP representation from which to export 84 * \param[out] data The buffer to export to 85 * \param[in] data_size The length of the buffer to export to 86 * \param[out] data_length The amount of bytes written to \p data 87 */ 88 psa_status_t mbedtls_psa_ecp_export_key(psa_key_type_t type, 89 mbedtls_ecp_keypair *ecp, 90 uint8_t *data, 91 size_t data_size, 92 size_t *data_length); 93 94 /** Export an ECP public key or the public part of an ECP key pair in binary 95 * format. 96 * 97 * \note The signature of this function is that of a PSA driver 98 * export_public_key entry point. This function behaves as an 99 * export_public_key entry point as defined in the PSA driver interface 100 * specification. 101 * 102 * \param[in] attributes The attributes for the key to export. 103 * \param[in] key_buffer Material or context of the key to export. 104 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 105 * \param[out] data Buffer where the key data is to be written. 106 * \param[in] data_size Size of the \p data buffer in bytes. 107 * \param[out] data_length On success, the number of bytes written in 108 * \p data 109 * 110 * \retval #PSA_SUCCESS The ECP public key was exported successfully. 111 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 112 * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription 113 * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription 114 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 115 * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription 116 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 117 */ 118 psa_status_t mbedtls_psa_ecp_export_public_key( 119 const psa_key_attributes_t *attributes, 120 const uint8_t *key_buffer, size_t key_buffer_size, 121 uint8_t *data, size_t data_size, size_t *data_length); 122 123 /** 124 * \brief Generate an ECP key. 125 * 126 * \note The signature of the function is that of a PSA driver generate_key 127 * entry point. 128 * 129 * \param[in] attributes The attributes for the ECP key to generate. 130 * \param[out] key_buffer Buffer where the key data is to be written. 131 * \param[in] key_buffer_size Size of \p key_buffer in bytes. 132 * \param[out] key_buffer_length On success, the number of bytes written in 133 * \p key_buffer. 134 * 135 * \retval #PSA_SUCCESS 136 * The key was successfully generated. 137 * \retval #PSA_ERROR_NOT_SUPPORTED 138 * Key length or type not supported. 139 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 140 * The size of \p key_buffer is too small. 141 */ 142 psa_status_t mbedtls_psa_ecp_generate_key( 143 const psa_key_attributes_t *attributes, 144 uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length); 145 146 /** Sign an already-calculated hash with ECDSA. 147 * 148 * \note The signature of this function is that of a PSA driver 149 * sign_hash entry point. This function behaves as a sign_hash 150 * entry point as defined in the PSA driver interface specification for 151 * transparent drivers. 152 * 153 * \param[in] attributes The attributes of the ECC key to use for the 154 * operation. 155 * \param[in] key_buffer The buffer containing the ECC key context. 156 * format. 157 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 158 * \param[in] alg Randomized or deterministic ECDSA algorithm. 159 * \param[in] hash The hash or message to sign. 160 * \param[in] hash_length Size of the \p hash buffer in bytes. 161 * \param[out] signature Buffer where the signature is to be written. 162 * \param[in] signature_size Size of the \p signature buffer in bytes. 163 * \param[out] signature_length On success, the number of bytes 164 * that make up the returned signature value. 165 * 166 * \retval #PSA_SUCCESS \emptydescription 167 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 168 * The size of the \p signature buffer is too small. You can 169 * determine a sufficient buffer size by calling 170 * #PSA_SIGN_OUTPUT_SIZE(\c PSA_KEY_TYPE_ECC_KEY_PAIR, \c key_bits, 171 * \p alg) where \c key_bits is the bit-size of the ECC key. 172 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 173 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 174 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 175 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 176 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 177 */ 178 psa_status_t mbedtls_psa_ecdsa_sign_hash( 179 const psa_key_attributes_t *attributes, 180 const uint8_t *key_buffer, size_t key_buffer_size, 181 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, 182 uint8_t *signature, size_t signature_size, size_t *signature_length); 183 184 /** 185 * \brief Verify an ECDSA hash or short message signature. 186 * 187 * \note The signature of this function is that of a PSA driver 188 * verify_hash entry point. This function behaves as a verify_hash 189 * entry point as defined in the PSA driver interface specification for 190 * transparent drivers. 191 * 192 * \param[in] attributes The attributes of the ECC key to use for the 193 * operation. 194 * \param[in] key_buffer The buffer containing the ECC key context. 195 * format. 196 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 197 * \param[in] alg Randomized or deterministic ECDSA algorithm. 198 * \param[in] hash The hash or message whose signature is to be 199 * verified. 200 * \param[in] hash_length Size of the \p hash buffer in bytes. 201 * \param[in] signature Buffer containing the signature to verify. 202 * \param[in] signature_length Size of the \p signature buffer in bytes. 203 * 204 * \retval #PSA_SUCCESS 205 * The signature is valid. 206 * \retval #PSA_ERROR_INVALID_SIGNATURE 207 * The calculation was performed successfully, but the passed 208 * signature is not a valid signature. 209 * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription 210 * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription 211 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 212 */ 213 psa_status_t mbedtls_psa_ecdsa_verify_hash( 214 const psa_key_attributes_t *attributes, 215 const uint8_t *key_buffer, size_t key_buffer_size, 216 psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, 217 const uint8_t *signature, size_t signature_length); 218 219 220 /** Perform a key agreement and return the raw ECDH shared secret. 221 * 222 * \note The signature of this function is that of a PSA driver 223 * key_agreement entry point. This function behaves as a key_agreement 224 * entry point as defined in the PSA driver interface specification for 225 * transparent drivers. 226 * 227 * \param[in] attributes The attributes of the key to use for the 228 * operation. 229 * \param[in] key_buffer The buffer containing the private key 230 * context. 231 * \param[in] key_buffer_size Size of the \p key_buffer buffer in 232 * bytes. 233 * \param[in] alg A key agreement algorithm that is 234 * compatible with the type of the key. 235 * \param[in] peer_key The buffer containing the key context 236 * of the peer's public key. 237 * \param[in] peer_key_length Size of the \p peer_key buffer in 238 * bytes. 239 * \param[out] shared_secret The buffer to which the shared secret 240 * is to be written. 241 * \param[in] shared_secret_size Size of the \p shared_secret buffer in 242 * bytes. 243 * \param[out] shared_secret_length On success, the number of bytes that make 244 * up the returned shared secret. 245 * \retval #PSA_SUCCESS 246 * Success. Shared secret successfully calculated. 247 * \retval #PSA_ERROR_INVALID_HANDLE \emptydescription 248 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 249 * \retval #PSA_ERROR_INVALID_ARGUMENT 250 * \p alg is not a key agreement algorithm, or 251 * \p private_key is not compatible with \p alg, 252 * or \p peer_key is not valid for \p alg or not compatible with 253 * \p private_key. 254 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 255 * \p shared_secret_size is too small 256 * \retval #PSA_ERROR_NOT_SUPPORTED 257 * \p alg is not a supported key agreement algorithm. 258 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 259 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 260 */ 261 psa_status_t mbedtls_psa_key_agreement_ecdh( 262 const psa_key_attributes_t *attributes, 263 const uint8_t *key_buffer, size_t key_buffer_size, 264 psa_algorithm_t alg, const uint8_t *peer_key, size_t peer_key_length, 265 uint8_t *shared_secret, size_t shared_secret_size, 266 size_t *shared_secret_length); 267 #endif /* PSA_CRYPTO_ECP_H */ 268
