1/*
2 *  PSA PAKE layer on top of Mbed TLS software 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_PAKE_H
22#define PSA_CRYPTO_PAKE_H
23
24#include <psa/crypto.h>
25
26/** Set the session information for a password-authenticated key exchange.
27 *
28 * \note The signature of this function is that of a PSA driver
29 *       pake_setup entry point. This function behaves as a pake_setup
30 *       entry point as defined in the PSA driver interface specification for
31 *       transparent drivers.
32 *
33 * \param[in,out] operation     The operation object to set up. It must have
34 *                              been initialized but not set up yet.
35 * \param[in] inputs            Inputs required for PAKE operation (role, password,
36 *                              key lifetime, cipher suite)
37 *
38 * \retval #PSA_SUCCESS
39 *         Success.
40 * \retval #PSA_ERROR_NOT_SUPPORTED
41 *         The algorithm in \p cipher_suite is not a supported PAKE algorithm,
42 *         or the PAKE primitive in \p cipher_suite is not supported or not
43 *         compatible with the PAKE algorithm, or the hash algorithm in
44 *         \p cipher_suite is not supported or not compatible with the PAKE
45 *         algorithm and primitive.
46 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
47 * \retval #PSA_ERROR_CORRUPTION_DETECTED
48 */
49psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation,
50                                    const psa_crypto_driver_pake_inputs_t *inputs);
51
52
53/** Get output for a step of a password-authenticated key exchange.
54 *
55 * \note The signature of this function is that of a PSA driver
56 *       pake_output entry point. This function behaves as a pake_output
57 *       entry point as defined in the PSA driver interface specification for
58 *       transparent drivers.
59 *
60 * \param[in,out] operation    Active PAKE operation.
61 * \param step                 The step of the algorithm for which the output is
62 *                             requested.
63 * \param[out] output          Buffer where the output is to be written in the
64 *                             format appropriate for this driver \p step. Refer to
65 *                             the documentation of psa_crypto_driver_pake_step_t for
66 *                             more information.
67 * \param output_size          Size of the \p output buffer in bytes. This must
68 *                             be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \p
69 *                             primitive, \p step) where \p alg and
70 *                             \p primitive are the PAKE algorithm and primitive
71 *                             in the operation's cipher suite, and \p step is
72 *                             the output step.
73 *
74 * \param[out] output_length   On success, the number of bytes of the returned
75 *                             output.
76 *
77 * \retval #PSA_SUCCESS
78 *         Success.
79 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
80 *         The size of the \p output buffer is too small.
81 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
82 * \retval #PSA_ERROR_CORRUPTION_DETECTED
83 * \retval #PSA_ERROR_DATA_CORRUPT
84 * \retval #PSA_ERROR_DATA_INVALID
85 */
86psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation,
87                                     psa_crypto_driver_pake_step_t step,
88                                     uint8_t *output,
89                                     size_t output_size,
90                                     size_t *output_length);
91
92/** Provide input for a step of a password-authenticated key exchange.
93 *
94 * \note The signature of this function is that of a PSA driver
95 *       pake_input entry point. This function behaves as a pake_input
96 *       entry point as defined in the PSA driver interface specification for
97 *       transparent drivers.
98 *
99 * \note The core checks that input_length is smaller than PSA_PAKE_INPUT_MAX_SIZE.
100 *
101 * \param[in,out] operation    Active PAKE operation.
102 * \param step                 The driver step for which the input is provided.
103 * \param[in] input            Buffer containing the input in the format
104 *                             appropriate for this \p step. Refer to the
105 *                             documentation of psa_crypto_driver_pake_step_t
106 *                             for more information.
107 * \param input_length         Size of the \p input buffer in bytes.
108 *
109 * \retval #PSA_SUCCESS
110 *         Success.
111 * \retval #PSA_ERROR_INVALID_SIGNATURE
112 *         The verification fails for a zero-knowledge input step.
113 * \retval #PSA_ERROR_INVALID_ARGUMENT
114 *         the \p input is not valid for the \p operation's algorithm, cipher suite
115 *         or \p step.
116 * \retval #PSA_ERROR_NOT_SUPPORTED
117 *         the \p input is not supported for the \p operation's algorithm, cipher
118 *         suite or \p step.
119 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
120 * \retval #PSA_ERROR_CORRUPTION_DETECTED
121 * \retval #PSA_ERROR_DATA_CORRUPT
122 * \retval #PSA_ERROR_DATA_INVALID
123 */
124psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation,
125                                    psa_crypto_driver_pake_step_t step,
126                                    const uint8_t *input,
127                                    size_t input_length);
128
129/** Get implicitly confirmed shared secret from a PAKE.
130 *
131 * \note The signature of this function is that of a PSA driver
132 *       pake_get_implicit_key entry point. This function behaves as a
133 *       pake_get_implicit_key entry point as defined in the PSA driver
134 *       interface specification for transparent drivers.
135 *
136 * \param[in,out] operation    Active PAKE operation.
137 * \param[out] output          Output buffer for implicit key.
138 * \param      output_size     Size of the output buffer in bytes.
139 * \param[out] output_length   On success, the number of bytes of the implicit key.
140 *
141 * \retval #PSA_SUCCESS
142 *         Success.
143 * \retval #PSA_ERROR_NOT_SUPPORTED
144 *         Input from a PAKE is not supported by the algorithm in the \p output
145 *         key derivation operation.
146 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
147 * \retval #PSA_ERROR_CORRUPTION_DETECTED
148 * \retval #PSA_ERROR_DATA_CORRUPT
149 * \retval #PSA_ERROR_DATA_INVALID
150 */
151psa_status_t mbedtls_psa_pake_get_implicit_key(
152    mbedtls_psa_pake_operation_t *operation,
153    uint8_t *output, size_t output_size,
154    size_t *output_length);
155
156/** Abort a PAKE operation.
157 *
158 * \note The signature of this function is that of a PSA driver
159 *       pake_abort entry point. This function behaves as a pake_abort
160 *       entry point as defined in the PSA driver interface specification for
161 *       transparent drivers.
162 *
163 * \param[in,out] operation    The operation to abort.
164 *
165 * \retval #PSA_SUCCESS
166 *         Success.
167 * \retval #PSA_ERROR_CORRUPTION_DETECTED
168 */
169psa_status_t mbedtls_psa_pake_abort(mbedtls_psa_pake_operation_t *operation);
170
171#endif /* PSA_CRYPTO_PAKE_H */
172