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