1 /*
2  *  PSA crypto core internal interfaces
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_CORE_H
22 #define PSA_CRYPTO_CORE_H
23 
24 #include "mbedtls/build_info.h"
25 
26 #include "psa/crypto.h"
27 #include "psa/crypto_se_driver.h"
28 
29 /** Constant-time buffer comparison
30  *
31  * \param[in]  a    Left-hand buffer for comparison.
32  * \param[in]  b    Right-hand buffer for comparison.
33  * \param n         Amount of bytes to compare.
34  *
35  * \return 0 if the buffer contents are equal, non-zero otherwise
36  */
mbedtls_psa_safer_memcmp(const uint8_t * a,const uint8_t * b,size_t n)37 static inline int mbedtls_psa_safer_memcmp(
38     const uint8_t *a, const uint8_t *b, size_t n )
39 {
40     size_t i;
41     unsigned char diff = 0;
42 
43     for( i = 0; i < n; i++ )
44         diff |= a[i] ^ b[i];
45 
46     return( diff );
47 }
48 
49 /** The data structure representing a key slot, containing key material
50  * and metadata for one key.
51  */
52 typedef struct
53 {
54     psa_core_key_attributes_t attr;
55 
56     /*
57      * Number of locks on the key slot held by the library.
58      *
59      * This counter is incremented by one each time a library function
60      * retrieves through one of the dedicated internal API a pointer to the
61      * key slot.
62      *
63      * This counter is decremented by one each time a library function stops
64      * accessing the key slot and states it by calling the
65      * psa_unlock_key_slot() API.
66      *
67      * This counter is used to prevent resetting the key slot while the library
68      * may access it. For example, such control is needed in the following
69      * scenarios:
70      * . In case of key slot starvation, all key slots contain the description
71      *   of a key, and the library asks for the description of a persistent
72      *   key not present in the key slots, the key slots currently accessed by
73      *   the library cannot be reclaimed to free a key slot to load the
74      *   persistent key.
75      * . In case of a multi-threaded application where one thread asks to close
76      *   or purge or destroy a key while it is in used by the library through
77      *   another thread.
78      */
79     size_t lock_count;
80 
81     /* Dynamically allocated key data buffer.
82      * Format as specified in psa_export_key(). */
83     struct key_data
84     {
85         uint8_t *data;
86         size_t bytes;
87     } key;
88 } psa_key_slot_t;
89 
90 /* A mask of key attribute flags used only internally.
91  * Currently there aren't any. */
92 #define PSA_KA_MASK_INTERNAL_ONLY (     \
93         0 )
94 
95 /** Test whether a key slot is occupied.
96  *
97  * A key slot is occupied iff the key type is nonzero. This works because
98  * no valid key can have 0 as its key type.
99  *
100  * \param[in] slot      The key slot to test.
101  *
102  * \return 1 if the slot is occupied, 0 otherwise.
103  */
psa_is_key_slot_occupied(const psa_key_slot_t * slot)104 static inline int psa_is_key_slot_occupied( const psa_key_slot_t *slot )
105 {
106     return( slot->attr.type != 0 );
107 }
108 
109 /** Test whether a key slot is locked.
110  *
111  * A key slot is locked iff its lock counter is strictly greater than 0.
112  *
113  * \param[in] slot  The key slot to test.
114  *
115  * \return 1 if the slot is locked, 0 otherwise.
116  */
psa_is_key_slot_locked(const psa_key_slot_t * slot)117 static inline int psa_is_key_slot_locked( const psa_key_slot_t *slot )
118 {
119     return( slot->lock_count > 0 );
120 }
121 
122 /** Retrieve flags from psa_key_slot_t::attr::core::flags.
123  *
124  * \param[in] slot      The key slot to query.
125  * \param mask          The mask of bits to extract.
126  *
127  * \return The key attribute flags in the given slot,
128  *         bitwise-anded with \p mask.
129  */
psa_key_slot_get_flags(const psa_key_slot_t * slot,uint16_t mask)130 static inline uint16_t psa_key_slot_get_flags( const psa_key_slot_t *slot,
131                                                uint16_t mask )
132 {
133     return( slot->attr.flags & mask );
134 }
135 
136 /** Set flags in psa_key_slot_t::attr::core::flags.
137  *
138  * \param[in,out] slot  The key slot to modify.
139  * \param mask          The mask of bits to modify.
140  * \param value         The new value of the selected bits.
141  */
psa_key_slot_set_flags(psa_key_slot_t * slot,uint16_t mask,uint16_t value)142 static inline void psa_key_slot_set_flags( psa_key_slot_t *slot,
143                                            uint16_t mask,
144                                            uint16_t value )
145 {
146     slot->attr.flags = ( ( ~mask & slot->attr.flags ) |
147                               ( mask & value ) );
148 }
149 
150 /** Turn on flags in psa_key_slot_t::attr::core::flags.
151  *
152  * \param[in,out] slot  The key slot to modify.
153  * \param mask          The mask of bits to set.
154  */
psa_key_slot_set_bits_in_flags(psa_key_slot_t * slot,uint16_t mask)155 static inline void psa_key_slot_set_bits_in_flags( psa_key_slot_t *slot,
156                                                    uint16_t mask )
157 {
158     slot->attr.flags |= mask;
159 }
160 
161 /** Turn off flags in psa_key_slot_t::attr::core::flags.
162  *
163  * \param[in,out] slot  The key slot to modify.
164  * \param mask          The mask of bits to clear.
165  */
psa_key_slot_clear_bits(psa_key_slot_t * slot,uint16_t mask)166 static inline void psa_key_slot_clear_bits( psa_key_slot_t *slot,
167                                             uint16_t mask )
168 {
169     slot->attr.flags &= ~mask;
170 }
171 
172 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
173 /** Get the SE slot number of a key from the key slot storing its description.
174  *
175  * \param[in]  slot  The key slot to query. This must be a key slot storing
176  *                   the description of a key of a dynamically registered
177  *                   secure element, otherwise the behaviour is undefined.
178  */
psa_key_slot_get_slot_number(const psa_key_slot_t * slot)179 static inline psa_key_slot_number_t psa_key_slot_get_slot_number(
180     const psa_key_slot_t *slot )
181 {
182     return( *( (psa_key_slot_number_t *)( slot->key.data ) ) );
183 }
184 #endif
185 
186 /** Get the description of a key given its identifier and policy constraints
187  *  and lock it.
188  *
189  * The key must have allow all the usage flags set in \p usage. If \p alg is
190  * nonzero, the key must allow operations with this algorithm. If \p alg is
191  * zero, the algorithm is not checked.
192  *
193  * In case of a persistent key, the function loads the description of the key
194  * into a key slot if not already done.
195  *
196  * On success, the returned key slot is locked. It is the responsibility of
197  * the caller to unlock the key slot when it does not access it anymore.
198  */
199 psa_status_t psa_get_and_lock_key_slot_with_policy( mbedtls_svc_key_id_t key,
200                                                     psa_key_slot_t **p_slot,
201                                                     psa_key_usage_t usage,
202                                                     psa_algorithm_t alg );
203 
204 /** Completely wipe a slot in memory, including its policy.
205  *
206  * Persistent storage is not affected.
207  *
208  * \param[in,out] slot  The key slot to wipe.
209  *
210  * \retval #PSA_SUCCESS
211  *         Success. This includes the case of a key slot that was
212  *         already fully wiped.
213  * \retval #PSA_ERROR_CORRUPTION_DETECTED
214  */
215 psa_status_t psa_wipe_key_slot( psa_key_slot_t *slot );
216 
217 /** Try to allocate a buffer to an empty key slot.
218  *
219  * \param[in,out] slot          Key slot to attach buffer to.
220  * \param[in] buffer_length     Requested size of the buffer.
221  *
222  * \retval #PSA_SUCCESS
223  *         The buffer has been successfully allocated.
224  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
225  *         Not enough memory was available for allocation.
226  * \retval #PSA_ERROR_ALREADY_EXISTS
227  *         Trying to allocate a buffer to a non-empty key slot.
228  */
229 psa_status_t psa_allocate_buffer_to_slot( psa_key_slot_t *slot,
230                                           size_t buffer_length );
231 
232 /** Wipe key data from a slot. Preserves metadata such as the policy. */
233 psa_status_t psa_remove_key_data_from_memory( psa_key_slot_t *slot );
234 
235 /** Copy key data (in export format) into an empty key slot.
236  *
237  * This function assumes that the slot does not contain
238  * any key material yet. On failure, the slot content is unchanged.
239  *
240  * \param[in,out] slot          Key slot to copy the key into.
241  * \param[in] data              Buffer containing the key material.
242  * \param data_length           Size of the key buffer.
243  *
244  * \retval #PSA_SUCCESS
245  *         The key has been copied successfully.
246  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
247  *         Not enough memory was available for allocation of the
248  *         copy buffer.
249  * \retval #PSA_ERROR_ALREADY_EXISTS
250  *         There was other key material already present in the slot.
251  */
252 psa_status_t psa_copy_key_material_into_slot( psa_key_slot_t *slot,
253                                               const uint8_t *data,
254                                               size_t data_length );
255 
256 /** Convert an mbed TLS error code to a PSA error code
257  *
258  * \note This function is provided solely for the convenience of
259  *       Mbed TLS and may be removed at any time without notice.
260  *
261  * \param ret           An mbed TLS-thrown error code
262  *
263  * \return              The corresponding PSA error code
264  */
265 psa_status_t mbedtls_to_psa_error( int ret );
266 
267 /** Import a key in binary format.
268  *
269  * \note The signature of this function is that of a PSA driver
270  *       import_key entry point. This function behaves as an import_key
271  *       entry point as defined in the PSA driver interface specification for
272  *       transparent drivers.
273  *
274  * \param[in]  attributes       The attributes for the key to import.
275  * \param[in]  data             The buffer containing the key data in import
276  *                              format.
277  * \param[in]  data_length      Size of the \p data buffer in bytes.
278  * \param[out] key_buffer       The buffer to contain the key data in output
279  *                              format upon successful return.
280  * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes. This
281  *                              size is greater or equal to \p data_length.
282  * \param[out] key_buffer_length  The length of the data written in \p
283  *                                key_buffer in bytes.
284  * \param[out] bits             The key size in number of bits.
285  *
286  * \retval #PSA_SUCCESS  The key was imported successfully.
287  * \retval #PSA_ERROR_INVALID_ARGUMENT
288  *         The key data is not correctly formatted.
289  * \retval #PSA_ERROR_NOT_SUPPORTED
290  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
291  * \retval #PSA_ERROR_CORRUPTION_DETECTED
292  */
293 psa_status_t psa_import_key_into_slot(
294     const psa_key_attributes_t *attributes,
295     const uint8_t *data, size_t data_length,
296     uint8_t *key_buffer, size_t key_buffer_size,
297     size_t *key_buffer_length, size_t *bits );
298 
299 /** Export a key in binary format
300  *
301  * \note The signature of this function is that of a PSA driver export_key
302  *       entry point. This function behaves as an export_key entry point as
303  *       defined in the PSA driver interface specification.
304  *
305  * \param[in]  attributes       The attributes for the key to export.
306  * \param[in]  key_buffer       Material or context of the key to export.
307  * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
308  * \param[out] data             Buffer where the key data is to be written.
309  * \param[in]  data_size        Size of the \p data buffer in bytes.
310  * \param[out] data_length      On success, the number of bytes written in
311  *                              \p data
312  *
313  * \retval #PSA_SUCCESS  The key was exported successfully.
314  * \retval #PSA_ERROR_NOT_SUPPORTED
315  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
316  * \retval #PSA_ERROR_HARDWARE_FAILURE
317  * \retval #PSA_ERROR_CORRUPTION_DETECTED
318  * \retval #PSA_ERROR_STORAGE_FAILURE
319  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
320  */
321 psa_status_t psa_export_key_internal(
322     const psa_key_attributes_t *attributes,
323     const uint8_t *key_buffer, size_t key_buffer_size,
324     uint8_t *data, size_t data_size, size_t *data_length );
325 
326 /** Export a public key or the public part of a key pair in binary format.
327  *
328  * \note The signature of this function is that of a PSA driver
329  *       export_public_key entry point. This function behaves as an
330  *       export_public_key entry point as defined in the PSA driver interface
331  *       specification.
332  *
333  * \param[in]  attributes       The attributes for the key to export.
334  * \param[in]  key_buffer       Material or context of the key to export.
335  * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
336  * \param[out] data             Buffer where the key data is to be written.
337  * \param[in]  data_size        Size of the \p data buffer in bytes.
338  * \param[out] data_length      On success, the number of bytes written in
339  *                              \p data
340  *
341  * \retval #PSA_SUCCESS  The public key was exported successfully.
342  * \retval #PSA_ERROR_NOT_SUPPORTED
343  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
344  * \retval #PSA_ERROR_HARDWARE_FAILURE
345  * \retval #PSA_ERROR_CORRUPTION_DETECTED
346  * \retval #PSA_ERROR_STORAGE_FAILURE
347  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
348  */
349 psa_status_t psa_export_public_key_internal(
350     const psa_key_attributes_t *attributes,
351     const uint8_t *key_buffer, size_t key_buffer_size,
352     uint8_t *data, size_t data_size, size_t *data_length );
353 
354 /**
355  * \brief Generate a key.
356  *
357  * \note The signature of the function is that of a PSA driver generate_key
358  *       entry point.
359  *
360  * \param[in]  attributes         The attributes for the key to generate.
361  * \param[out] key_buffer         Buffer where the key data is to be written.
362  * \param[in]  key_buffer_size    Size of \p key_buffer in bytes.
363  * \param[out] key_buffer_length  On success, the number of bytes written in
364  *                                \p key_buffer.
365  *
366  * \retval #PSA_SUCCESS
367  *         The key was generated successfully.
368  * \retval #PSA_ERROR_INVALID_ARGUMENT
369  * \retval #PSA_ERROR_NOT_SUPPORTED
370  *         Key size in bits or type not supported.
371  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
372  *         The size of \p key_buffer is too small.
373  */
374 psa_status_t psa_generate_key_internal( const psa_key_attributes_t *attributes,
375                                         uint8_t *key_buffer,
376                                         size_t key_buffer_size,
377                                         size_t *key_buffer_length );
378 
379 /** Sign a message with a private key. For hash-and-sign algorithms,
380  *  this includes the hashing step.
381  *
382  * \note The signature of this function is that of a PSA driver
383  *       sign_message entry point. This function behaves as a sign_message
384  *       entry point as defined in the PSA driver interface specification for
385  *       transparent drivers.
386  *
387  * \note This function will call the driver for psa_sign_hash
388  *       and go through driver dispatch again.
389  *
390  * \param[in]  attributes       The attributes of the key to use for the
391  *                              operation.
392  * \param[in]  key_buffer       The buffer containing the key context.
393  * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
394  * \param[in]  alg              A signature algorithm that is compatible with
395  *                              the type of the key.
396  * \param[in]  input            The input message to sign.
397  * \param[in]  input_length     Size of the \p input buffer in bytes.
398  * \param[out] signature        Buffer where the signature is to be written.
399  * \param[in]  signature_size   Size of the \p signature buffer in bytes.
400  * \param[out] signature_length On success, the number of bytes
401  *                              that make up the returned signature value.
402  *
403  * \retval #PSA_SUCCESS
404  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
405  *         The size of the \p signature buffer is too small. You can
406  *         determine a sufficient buffer size by calling
407  *         #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
408  *         where \c key_type and \c key_bits are the type and bit-size
409  *         respectively of the key.
410  * \retval #PSA_ERROR_NOT_SUPPORTED
411  * \retval #PSA_ERROR_INVALID_ARGUMENT
412  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
413  * \retval #PSA_ERROR_CORRUPTION_DETECTED
414  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
415  */
416 psa_status_t psa_sign_message_builtin(
417     const psa_key_attributes_t *attributes,
418     const uint8_t *key_buffer, size_t key_buffer_size,
419     psa_algorithm_t alg, const uint8_t *input, size_t input_length,
420     uint8_t *signature, size_t signature_size, size_t *signature_length );
421 
422 /** Verify the signature of a message with a public key, using
423  *  a hash-and-sign verification algorithm.
424  *
425  * \note The signature of this function is that of a PSA driver
426  *       verify_message entry point. This function behaves as a verify_message
427  *       entry point as defined in the PSA driver interface specification for
428  *       transparent drivers.
429  *
430  * \note This function will call the driver for psa_verify_hash
431  *       and go through driver dispatch again.
432  *
433  * \param[in]  attributes       The attributes of the key to use for the
434  *                              operation.
435  * \param[in]  key_buffer       The buffer containing the key context.
436  * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
437  * \param[in]  alg              A signature algorithm that is compatible with
438  *                              the type of the key.
439  * \param[in]  input            The message whose signature is to be verified.
440  * \param[in]  input_length     Size of the \p input buffer in bytes.
441  * \param[in]  signature        Buffer containing the signature to verify.
442  * \param[in]  signature_length Size of the \p signature buffer in bytes.
443  *
444  * \retval #PSA_SUCCESS
445  *         The signature is valid.
446  * \retval #PSA_ERROR_INVALID_SIGNATURE
447  *         The calculation was performed successfully, but the passed
448  *         signature is not a valid signature.
449  * \retval #PSA_ERROR_NOT_SUPPORTED
450  * \retval #PSA_ERROR_INVALID_ARGUMENT
451  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
452  */
453 psa_status_t psa_verify_message_builtin(
454     const psa_key_attributes_t *attributes,
455     const uint8_t *key_buffer, size_t key_buffer_size,
456     psa_algorithm_t alg, const uint8_t *input, size_t input_length,
457     const uint8_t *signature, size_t signature_length );
458 
459 /** Sign an already-calculated hash with a private key.
460  *
461  * \note The signature of this function is that of a PSA driver
462  *       sign_hash entry point. This function behaves as a sign_hash
463  *       entry point as defined in the PSA driver interface specification for
464  *       transparent drivers.
465  *
466  * \param[in]  attributes       The attributes of the key to use for the
467  *                              operation.
468  * \param[in]  key_buffer       The buffer containing the key context.
469  * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
470  * \param[in]  alg              A signature algorithm that is compatible with
471  *                              the type of the key.
472  * \param[in]  hash             The hash or message to sign.
473  * \param[in]  hash_length      Size of the \p hash buffer in bytes.
474  * \param[out] signature        Buffer where the signature is to be written.
475  * \param[in]  signature_size   Size of the \p signature buffer in bytes.
476  * \param[out] signature_length On success, the number of bytes
477  *                              that make up the returned signature value.
478  *
479  * \retval #PSA_SUCCESS
480  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
481  *         The size of the \p signature buffer is too small. You can
482  *         determine a sufficient buffer size by calling
483  *         #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
484  *         where \c key_type and \c key_bits are the type and bit-size
485  *         respectively of the key.
486  * \retval #PSA_ERROR_NOT_SUPPORTED
487  * \retval #PSA_ERROR_INVALID_ARGUMENT
488  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
489  * \retval #PSA_ERROR_CORRUPTION_DETECTED
490  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
491  */
492 psa_status_t psa_sign_hash_builtin(
493     const psa_key_attributes_t *attributes,
494     const uint8_t *key_buffer, size_t key_buffer_size,
495     psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
496     uint8_t *signature, size_t signature_size, size_t *signature_length );
497 
498 /**
499  * \brief Verify the signature a hash or short message using a public key.
500  *
501  * \note The signature of this function is that of a PSA driver
502  *       verify_hash entry point. This function behaves as a verify_hash
503  *       entry point as defined in the PSA driver interface specification for
504  *       transparent drivers.
505  *
506  * \param[in]  attributes       The attributes of the key to use for the
507  *                              operation.
508  * \param[in]  key_buffer       The buffer containing the key context.
509  * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
510  * \param[in]  alg              A signature algorithm that is compatible with
511  *                              the type of the key.
512  * \param[in]  hash             The hash or message whose signature is to be
513  *                              verified.
514  * \param[in]  hash_length      Size of the \p hash buffer in bytes.
515  * \param[in]  signature        Buffer containing the signature to verify.
516  * \param[in]  signature_length Size of the \p signature buffer in bytes.
517  *
518  * \retval #PSA_SUCCESS
519  *         The signature is valid.
520  * \retval #PSA_ERROR_INVALID_SIGNATURE
521  *         The calculation was performed successfully, but the passed
522  *         signature is not a valid signature.
523  * \retval #PSA_ERROR_NOT_SUPPORTED
524  * \retval #PSA_ERROR_INVALID_ARGUMENT
525  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
526  */
527 psa_status_t psa_verify_hash_builtin(
528     const psa_key_attributes_t *attributes,
529     const uint8_t *key_buffer, size_t key_buffer_size,
530     psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
531     const uint8_t *signature, size_t signature_length );
532 
533 /**
534  * \brief Validate the key bit size for unstructured keys.
535  *
536  * \note  Check that the bit size is acceptable for a given key type for
537  *        unstructured keys.
538  *
539  * \param[in]  type  The key type
540  * \param[in]  bits  The number of bits of the key
541  *
542  * \retval #PSA_SUCCESS
543  *         The key type and size are valid.
544  * \retval #PSA_ERROR_INVALID_ARGUMENT
545  *         The size in bits of the key is not valid.
546  * \retval #PSA_ERROR_NOT_SUPPORTED
547  *         The type and/or the size in bits of the key or the combination of
548  *         the two is not supported.
549  */
550 psa_status_t psa_validate_unstructured_key_bit_size( psa_key_type_t type,
551                                                      size_t bits );
552 
553 /** Perform a key agreement and return the raw shared secret, using
554     built-in raw key agreement functions.
555  *
556  * \note The signature of this function is that of a PSA driver
557  *       key_agreement entry point. This function behaves as a key_agreement
558  *       entry point as defined in the PSA driver interface specification for
559  *       transparent drivers.
560  *
561  * \param[in]  attributes           The attributes of the key to use for the
562  *                                  operation.
563  * \param[in]  key_buffer           The buffer containing the private key
564  *                                  context.
565  * \param[in]  key_buffer_size      Size of the \p key_buffer buffer in
566  *                                  bytes.
567  * \param[in]  alg                  A key agreement algorithm that is
568  *                                  compatible with the type of the key.
569  * \param[in]  peer_key             The buffer containing the key context
570  *                                  of the peer's public key.
571  * \param[in]  peer_key_length      Size of the \p peer_key buffer in
572  *                                  bytes.
573  * \param[out] shared_secret        The buffer to which the shared secret
574  *                                  is to be written.
575  * \param[in]  shared_secret_size   Size of the \p shared_secret buffer in
576  *                                  bytes.
577  * \param[out] shared_secret_length On success, the number of bytes that make
578  *                                  up the returned shared secret.
579  * \retval #PSA_SUCCESS
580  *         Success. Shared secret successfully calculated.
581  * \retval #PSA_ERROR_INVALID_HANDLE
582  * \retval #PSA_ERROR_NOT_PERMITTED
583  * \retval #PSA_ERROR_INVALID_ARGUMENT
584  *         \p alg is not a key agreement algorithm, or
585  *         \p private_key is not compatible with \p alg,
586  *         or \p peer_key is not valid for \p alg or not compatible with
587  *         \p private_key.
588  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
589  *         \p shared_secret_size is too small
590  * \retval #PSA_ERROR_NOT_SUPPORTED
591  *         \p alg is not a supported key agreement algorithm.
592  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
593  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
594  * \retval #PSA_ERROR_HARDWARE_FAILURE
595  * \retval #PSA_ERROR_CORRUPTION_DETECTED
596  * \retval #PSA_ERROR_STORAGE_FAILURE
597  * \retval #PSA_ERROR_BAD_STATE
598  */
599 psa_status_t psa_key_agreement_raw_builtin(
600     const psa_key_attributes_t *attributes,
601     const uint8_t *key_buffer,
602     size_t key_buffer_size,
603     psa_algorithm_t alg,
604     const uint8_t *peer_key,
605     size_t peer_key_length,
606     uint8_t *shared_secret,
607     size_t shared_secret_size,
608     size_t *shared_secret_length );
609 
610 #endif /* PSA_CRYPTO_CORE_H */
611