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 */
40psa_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 */
67psa_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 */
96psa_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 */
125psa_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