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