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