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