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