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