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 */
45psa_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
58psa_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 */
86psa_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 */
100psa_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 */
130psa_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 */
154psa_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 */
190psa_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 */
225psa_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 */
273psa_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