[398] | 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 */
|
---|