1 /*
2  *  PSA FFDH 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_FFDH_H
10 #define PSA_CRYPTO_FFDH_H
11 
12 #include <psa/crypto.h>
13 
14 /** Perform a key agreement and return the FFDH shared secret.
15  *
16  * \param[in]  attributes           The attributes of the key to use for the
17  *                                  operation.
18  * \param[in]  peer_key             The buffer containing the key context
19  *                                  of the peer's public key.
20  * \param[in]  peer_key_length      Size of the \p peer_key buffer in
21  *                                  bytes.
22  * \param[in]  key_buffer           The buffer containing the private key
23  *                                  context.
24  * \param[in]  key_buffer_size      Size of the \p key_buffer buffer in
25  *                                  bytes.
26  * \param[out] shared_secret        The buffer to which the shared secret
27  *                                  is to be written.
28  * \param[in]  shared_secret_size   Size of the \p shared_secret buffer in
29  *                                  bytes.
30  * \param[out] shared_secret_length On success, the number of bytes that make
31  *                                  up the returned shared secret.
32  * \retval #PSA_SUCCESS
33  *         Success. Shared secret successfully calculated.
34  * \retval #PSA_ERROR_INVALID_ARGUMENT
35  *         \p key_buffer_size, \p peer_key_length, \p shared_secret_size
36  *         do not match
37  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY   \emptydescription
38  * \retval #PSA_ERROR_CORRUPTION_DETECTED   \emptydescription
39  */
40 psa_status_t mbedtls_psa_ffdh_key_agreement(
41     const psa_key_attributes_t *attributes,
42     const uint8_t *peer_key,
43     size_t peer_key_length,
44     const uint8_t *key_buffer,
45     size_t key_buffer_size,
46     uint8_t *shared_secret,
47     size_t shared_secret_size,
48     size_t *shared_secret_length);
49 
50 /** Export a public key or the public part of a DH key pair in binary format.
51  *
52  * \param[in]  attributes       The attributes for the key to export.
53  * \param[in]  key_buffer       Material or context of the key to export.
54  * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes.
55  * \param[out] data             Buffer where the key data is to be written.
56  * \param[in]  data_size        Size of the \p data buffer in bytes.
57  * \param[out] data_length      On success, the number of bytes written in
58  *                              \p data
59  *
60  * \retval #PSA_SUCCESS  The public key was exported successfully.
61  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
62  *         The size of \p key_buffer is too small.
63  * \retval #PSA_ERROR_NOT_PERMITTED         \emptydescription
64  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY   \emptydescription
65  * \retval #PSA_ERROR_CORRUPTION_DETECTED   \emptydescription
66  */
67 psa_status_t mbedtls_psa_ffdh_export_public_key(
68     const psa_key_attributes_t *attributes,
69     const uint8_t *key_buffer,
70     size_t key_buffer_size,
71     uint8_t *data,
72     size_t data_size,
73     size_t *data_length);
74 
75 /**
76  * \brief Generate DH key.
77  *
78  * \note The signature of the function is that of a PSA driver generate_key
79  *       entry point.
80  *
81  * \param[in]  attributes         The attributes for the key to generate.
82  * \param[out] key_buffer         Buffer where the key data is to be written.
83  * \param[in]  key_buffer_size    Size of \p key_buffer in bytes.
84  * \param[out] key_buffer_length  On success, the number of bytes written in
85  *                                \p key_buffer.
86  *
87  * \retval #PSA_SUCCESS
88  *         The key was generated successfully.
89  * \retval #PSA_ERROR_NOT_SUPPORTED
90  *         Key size in bits is invalid.
91  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
92  *         The size of \p key_buffer is too small.
93  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY   \emptydescription
94  * \retval #PSA_ERROR_CORRUPTION_DETECTED   \emptydescription
95  */
96 psa_status_t mbedtls_psa_ffdh_generate_key(
97     const psa_key_attributes_t *attributes,
98     uint8_t *key_buffer,
99     size_t key_buffer_size,
100     size_t *key_buffer_length);
101 
102 /**
103  * \brief Import DH key.
104  *
105  * \note The signature of the function is that of a PSA driver import_key
106  *       entry point.
107  *
108  * \param[in]  attributes       The attributes for the key to import.
109  * \param[in]  data             The buffer containing the key data in import
110  *                              format.
111  * \param[in]  data_length      Size of the \p data buffer in bytes.
112  * \param[out] key_buffer       The buffer containing the key data in output
113  *                              format.
114  * \param[in]  key_buffer_size  Size of the \p key_buffer buffer in bytes. This
115  *                              size is greater or equal to \p data_length.
116  * \param[out] key_buffer_length  The length of the data written in \p
117  *                                key_buffer in bytes.
118  * \param[out] bits             The key size in number of bits.
119  *
120  * \retval #PSA_SUCCESS
121  *         The key was generated successfully.
122  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
123  *         The size of \p key_buffer is too small.
124  */
125 psa_status_t mbedtls_psa_ffdh_import_key(
126     const psa_key_attributes_t *attributes,
127     const uint8_t *data, size_t data_length,
128     uint8_t *key_buffer, size_t key_buffer_size,
129     size_t *key_buffer_length, size_t *bits);
130 
131 #endif /* PSA_CRYPTO_FFDH_H */
132