1 | /**
|
---|
2 | * \file ecjpake.h
|
---|
3 | *
|
---|
4 | * \brief Elliptic curve J-PAKE
|
---|
5 | */
|
---|
6 | /*
|
---|
7 | * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
|
---|
8 | * SPDX-License-Identifier: Apache-2.0
|
---|
9 | *
|
---|
10 | * Licensed under the Apache License, Version 2.0 (the "License"); you may
|
---|
11 | * not use this file except in compliance with the License.
|
---|
12 | * You may obtain a copy of the License at
|
---|
13 | *
|
---|
14 | * http://www.apache.org/licenses/LICENSE-2.0
|
---|
15 | *
|
---|
16 | * Unless required by applicable law or agreed to in writing, software
|
---|
17 | * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
---|
18 | * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
19 | * See the License for the specific language governing permissions and
|
---|
20 | * limitations under the License.
|
---|
21 | *
|
---|
22 | * This file is part of mbed TLS (https://tls.mbed.org)
|
---|
23 | */
|
---|
24 | #ifndef MBEDTLS_ECJPAKE_H
|
---|
25 | #define MBEDTLS_ECJPAKE_H
|
---|
26 |
|
---|
27 | /*
|
---|
28 | * J-PAKE is a password-authenticated key exchange that allows deriving a
|
---|
29 | * strong shared secret from a (potentially low entropy) pre-shared
|
---|
30 | * passphrase, with forward secrecy and mutual authentication.
|
---|
31 | * https://en.wikipedia.org/wiki/Password_Authenticated_Key_Exchange_by_Juggling
|
---|
32 | *
|
---|
33 | * This file implements the Elliptic Curve variant of J-PAKE,
|
---|
34 | * as defined in Chapter 7.4 of the Thread v1.0 Specification,
|
---|
35 | * available to members of the Thread Group http://threadgroup.org/
|
---|
36 | *
|
---|
37 | * As the J-PAKE algorithm is inherently symmetric, so is our API.
|
---|
38 | * Each party needs to send its first round message, in any order, to the
|
---|
39 | * other party, then each sends its second round message, in any order.
|
---|
40 | * The payloads are serialized in a way suitable for use in TLS, but could
|
---|
41 | * also be use outside TLS.
|
---|
42 | */
|
---|
43 | #if !defined(MBEDTLS_CONFIG_FILE)
|
---|
44 | #include "config.h"
|
---|
45 | #else
|
---|
46 | #include MBEDTLS_CONFIG_FILE
|
---|
47 | #endif
|
---|
48 |
|
---|
49 | #include "ecp.h"
|
---|
50 | #include "md.h"
|
---|
51 |
|
---|
52 | #ifdef __cplusplus
|
---|
53 | extern "C" {
|
---|
54 | #endif
|
---|
55 |
|
---|
56 | /**
|
---|
57 | * Roles in the EC J-PAKE exchange
|
---|
58 | */
|
---|
59 | typedef enum {
|
---|
60 | MBEDTLS_ECJPAKE_CLIENT = 0, /**< Client */
|
---|
61 | MBEDTLS_ECJPAKE_SERVER, /**< Server */
|
---|
62 | } mbedtls_ecjpake_role;
|
---|
63 |
|
---|
64 | #if !defined(MBEDTLS_ECJPAKE_ALT)
|
---|
65 | /**
|
---|
66 | * EC J-PAKE context structure.
|
---|
67 | *
|
---|
68 | * J-PAKE is a symmetric protocol, except for the identifiers used in
|
---|
69 | * Zero-Knowledge Proofs, and the serialization of the second message
|
---|
70 | * (KeyExchange) as defined by the Thread spec.
|
---|
71 | *
|
---|
72 | * In order to benefit from this symmetry, we choose a different naming
|
---|
73 | * convetion from the Thread v1.0 spec. Correspondance is indicated in the
|
---|
74 | * description as a pair C: client name, S: server name
|
---|
75 | */
|
---|
76 | typedef struct mbedtls_ecjpake_context
|
---|
77 | {
|
---|
78 | const mbedtls_md_info_t *md_info; /**< Hash to use */
|
---|
79 | mbedtls_ecp_group grp; /**< Elliptic curve */
|
---|
80 | mbedtls_ecjpake_role role; /**< Are we client or server? */
|
---|
81 | int point_format; /**< Format for point export */
|
---|
82 |
|
---|
83 | mbedtls_ecp_point Xm1; /**< My public key 1 C: X1, S: X3 */
|
---|
84 | mbedtls_ecp_point Xm2; /**< My public key 2 C: X2, S: X4 */
|
---|
85 | mbedtls_ecp_point Xp1; /**< Peer public key 1 C: X3, S: X1 */
|
---|
86 | mbedtls_ecp_point Xp2; /**< Peer public key 2 C: X4, S: X2 */
|
---|
87 | mbedtls_ecp_point Xp; /**< Peer public key C: Xs, S: Xc */
|
---|
88 |
|
---|
89 | mbedtls_mpi xm1; /**< My private key 1 C: x1, S: x3 */
|
---|
90 | mbedtls_mpi xm2; /**< My private key 2 C: x2, S: x4 */
|
---|
91 |
|
---|
92 | mbedtls_mpi s; /**< Pre-shared secret (passphrase) */
|
---|
93 | } mbedtls_ecjpake_context;
|
---|
94 |
|
---|
95 | #else /* MBEDTLS_ECJPAKE_ALT */
|
---|
96 | #include "ecjpake_alt.h"
|
---|
97 | #endif /* MBEDTLS_ECJPAKE_ALT */
|
---|
98 |
|
---|
99 | /**
|
---|
100 | * \brief Initialize an ECJPAKE context.
|
---|
101 | *
|
---|
102 | * \param ctx The ECJPAKE context to initialize.
|
---|
103 | * This must not be \c NULL.
|
---|
104 | */
|
---|
105 | void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
|
---|
106 |
|
---|
107 | /**
|
---|
108 | * \brief Set up an ECJPAKE context for use.
|
---|
109 | *
|
---|
110 | * \note Currently the only values for hash/curve allowed by the
|
---|
111 | * standard are #MBEDTLS_MD_SHA256/#MBEDTLS_ECP_DP_SECP256R1.
|
---|
112 | *
|
---|
113 | * \param ctx The ECJPAKE context to set up. This must be initialized.
|
---|
114 | * \param role The role of the caller. This must be either
|
---|
115 | * #MBEDTLS_ECJPAKE_CLIENT or #MBEDTLS_ECJPAKE_SERVER.
|
---|
116 | * \param hash The identifier of the hash function to use,
|
---|
117 | * for example #MBEDTLS_MD_SHA256.
|
---|
118 | * \param curve The identifier of the elliptic curve to use,
|
---|
119 | * for example #MBEDTLS_ECP_DP_SECP256R1.
|
---|
120 | * \param secret The pre-shared secret (passphrase). This must be
|
---|
121 | * a readable buffer of length \p len Bytes. It need
|
---|
122 | * only be valid for the duration of this call.
|
---|
123 | * \param len The length of the pre-shared secret \p secret.
|
---|
124 | *
|
---|
125 | * \return \c 0 if successful.
|
---|
126 | * \return A negative error code on failure.
|
---|
127 | */
|
---|
128 | int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
|
---|
129 | mbedtls_ecjpake_role role,
|
---|
130 | mbedtls_md_type_t hash,
|
---|
131 | mbedtls_ecp_group_id curve,
|
---|
132 | const unsigned char *secret,
|
---|
133 | size_t len );
|
---|
134 |
|
---|
135 | /**
|
---|
136 | * \brief Check if an ECJPAKE context is ready for use.
|
---|
137 | *
|
---|
138 | * \param ctx The ECJPAKE context to check. This must be
|
---|
139 | * initialized.
|
---|
140 | *
|
---|
141 | * \return \c 0 if the context is ready for use.
|
---|
142 | * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.
|
---|
143 | */
|
---|
144 | int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx );
|
---|
145 |
|
---|
146 | /**
|
---|
147 | * \brief Generate and write the first round message
|
---|
148 | * (TLS: contents of the Client/ServerHello extension,
|
---|
149 | * excluding extension type and length bytes).
|
---|
150 | *
|
---|
151 | * \param ctx The ECJPAKE context to use. This must be
|
---|
152 | * initialized and set up.
|
---|
153 | * \param buf The buffer to write the contents to. This must be a
|
---|
154 | * writable buffer of length \p len Bytes.
|
---|
155 | * \param len The length of \p buf in Bytes.
|
---|
156 | * \param olen The address at which to store the total number
|
---|
157 | * of Bytes written to \p buf. This must not be \c NULL.
|
---|
158 | * \param f_rng The RNG function to use. This must not be \c NULL.
|
---|
159 | * \param p_rng The RNG parameter to be passed to \p f_rng. This
|
---|
160 | * may be \c NULL if \p f_rng doesn't use a context.
|
---|
161 | *
|
---|
162 | * \return \c 0 if successful.
|
---|
163 | * \return A negative error code on failure.
|
---|
164 | */
|
---|
165 | int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
|
---|
166 | unsigned char *buf, size_t len, size_t *olen,
|
---|
167 | int (*f_rng)(void *, unsigned char *, size_t),
|
---|
168 | void *p_rng );
|
---|
169 |
|
---|
170 | /**
|
---|
171 | * \brief Read and process the first round message
|
---|
172 | * (TLS: contents of the Client/ServerHello extension,
|
---|
173 | * excluding extension type and length bytes).
|
---|
174 | *
|
---|
175 | * \param ctx The ECJPAKE context to use. This must be initialized
|
---|
176 | * and set up.
|
---|
177 | * \param buf The buffer holding the first round message. This must
|
---|
178 | * be a readable buffer of length \p len Bytes.
|
---|
179 | * \param len The length in Bytes of \p buf.
|
---|
180 | *
|
---|
181 | * \return \c 0 if successful.
|
---|
182 | * \return A negative error code on failure.
|
---|
183 | */
|
---|
184 | int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
|
---|
185 | const unsigned char *buf,
|
---|
186 | size_t len );
|
---|
187 |
|
---|
188 | /**
|
---|
189 | * \brief Generate and write the second round message
|
---|
190 | * (TLS: contents of the Client/ServerKeyExchange).
|
---|
191 | *
|
---|
192 | * \param ctx The ECJPAKE context to use. This must be initialized,
|
---|
193 | * set up, and already have performed round one.
|
---|
194 | * \param buf The buffer to write the round two contents to.
|
---|
195 | * This must be a writable buffer of length \p len Bytes.
|
---|
196 | * \param len The size of \p buf in Bytes.
|
---|
197 | * \param olen The address at which to store the total number of Bytes
|
---|
198 | * written to \p buf. This must not be \c NULL.
|
---|
199 | * \param f_rng The RNG function to use. This must not be \c NULL.
|
---|
200 | * \param p_rng The RNG parameter to be passed to \p f_rng. This
|
---|
201 | * may be \c NULL if \p f_rng doesn't use a context.
|
---|
202 | *
|
---|
203 | * \return \c 0 if successful.
|
---|
204 | * \return A negative error code on failure.
|
---|
205 | */
|
---|
206 | int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
|
---|
207 | unsigned char *buf, size_t len, size_t *olen,
|
---|
208 | int (*f_rng)(void *, unsigned char *, size_t),
|
---|
209 | void *p_rng );
|
---|
210 |
|
---|
211 | /**
|
---|
212 | * \brief Read and process the second round message
|
---|
213 | * (TLS: contents of the Client/ServerKeyExchange).
|
---|
214 | *
|
---|
215 | * \param ctx The ECJPAKE context to use. This must be initialized
|
---|
216 | * and set up and already have performed round one.
|
---|
217 | * \param buf The buffer holding the second round message. This must
|
---|
218 | * be a readable buffer of length \p len Bytes.
|
---|
219 | * \param len The length in Bytes of \p buf.
|
---|
220 | *
|
---|
221 | * \return \c 0 if successful.
|
---|
222 | * \return A negative error code on failure.
|
---|
223 | */
|
---|
224 | int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
|
---|
225 | const unsigned char *buf,
|
---|
226 | size_t len );
|
---|
227 |
|
---|
228 | /**
|
---|
229 | * \brief Derive the shared secret
|
---|
230 | * (TLS: Pre-Master Secret).
|
---|
231 | *
|
---|
232 | * \param ctx The ECJPAKE context to use. This must be initialized,
|
---|
233 | * set up and have performed both round one and two.
|
---|
234 | * \param buf The buffer to write the derived secret to. This must
|
---|
235 | * be a writable buffer of length \p len Bytes.
|
---|
236 | * \param len The length of \p buf in Bytes.
|
---|
237 | * \param olen The address at which to store the total number of Bytes
|
---|
238 | * written to \p buf. This must not be \c NULL.
|
---|
239 | * \param f_rng The RNG function to use. This must not be \c NULL.
|
---|
240 | * \param p_rng The RNG parameter to be passed to \p f_rng. This
|
---|
241 | * may be \c NULL if \p f_rng doesn't use a context.
|
---|
242 | *
|
---|
243 | * \return \c 0 if successful.
|
---|
244 | * \return A negative error code on failure.
|
---|
245 | */
|
---|
246 | int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
|
---|
247 | unsigned char *buf, size_t len, size_t *olen,
|
---|
248 | int (*f_rng)(void *, unsigned char *, size_t),
|
---|
249 | void *p_rng );
|
---|
250 |
|
---|
251 | /**
|
---|
252 | * \brief This clears an ECJPAKE context and frees any
|
---|
253 | * embedded data structure.
|
---|
254 | *
|
---|
255 | * \param ctx The ECJPAKE context to free. This may be \c NULL,
|
---|
256 | * in which case this function does nothing. If it is not
|
---|
257 | * \c NULL, it must point to an initialized ECJPAKE context.
|
---|
258 | */
|
---|
259 | void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
|
---|
260 |
|
---|
261 | #if defined(MBEDTLS_SELF_TEST)
|
---|
262 |
|
---|
263 | /**
|
---|
264 | * \brief Checkup routine
|
---|
265 | *
|
---|
266 | * \return 0 if successful, or 1 if a test failed
|
---|
267 | */
|
---|
268 | int mbedtls_ecjpake_self_test( int verbose );
|
---|
269 |
|
---|
270 | #endif /* MBEDTLS_SELF_TEST */
|
---|
271 |
|
---|
272 | #ifdef __cplusplus
|
---|
273 | }
|
---|
274 | #endif
|
---|
275 |
|
---|
276 |
|
---|
277 | #endif /* ecjpake.h */
|
---|