common/mbedtls/ecjpake.h

   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     const mbedtls_md_info_t *md_info;   /**< Hash to use                    */
  76     mbedtls_ecp_group grp;              /**< Elliptic curve                 */
  77     mbedtls_ecjpake_role role;          /**< Are we client or server?       */
  78     int point_format;                   /**< Format for point export        */
  79
  80     mbedtls_ecp_point Xm1;              /**< My public key 1   C: X1, S: X3 */
  81     mbedtls_ecp_point Xm2;              /**< My public key 2   C: X2, S: X4 */
  82     mbedtls_ecp_point Xp1;              /**< Peer public key 1 C: X3, S: X1 */
  83     mbedtls_ecp_point Xp2;              /**< Peer public key 2 C: X4, S: X2 */
  84     mbedtls_ecp_point Xp;               /**< Peer public key   C: Xs, S: Xc */
  85
  86     mbedtls_mpi xm1;                    /**< My private key 1  C: x1, S: x3 */
  87     mbedtls_mpi xm2;                    /**< My private key 2  C: x2, S: x4 */
  88
  89     mbedtls_mpi s;                      /**< Pre-shared secret (passphrase) */
  90 } mbedtls_ecjpake_context;
  91
  92 #else  /* MBEDTLS_ECJPAKE_ALT */
  93 #include "ecjpake_alt.h"
  94 #endif /* MBEDTLS_ECJPAKE_ALT */
  95
  96 /**
  97  * \brief           Initialize an ECJPAKE context.
  98  *
  99  * \param ctx       The ECJPAKE context to initialize.
 100  *                  This must not be \c NULL.
 101  */
 102 void mbedtls_ecjpake_init(mbedtls_ecjpake_context *ctx);
 103
 104 /**
 105  * \brief           Set up an ECJPAKE context for use.
 106  *
 107  * \note            Currently the only values for hash/curve allowed by the
 108  *                  standard are #MBEDTLS_MD_SHA256/#MBEDTLS_ECP_DP_SECP256R1.
 109  *
 110  * \param ctx       The ECJPAKE context to set up. This must be initialized.
 111  * \param role      The role of the caller. This must be either
 112  *                  #MBEDTLS_ECJPAKE_CLIENT or #MBEDTLS_ECJPAKE_SERVER.
 113  * \param hash      The identifier of the hash function to use,
 114  *                  for example #MBEDTLS_MD_SHA256.
 115  * \param curve     The identifier of the elliptic curve to use,
 116  *                  for example #MBEDTLS_ECP_DP_SECP256R1.
 117  * \param secret    The pre-shared secret (passphrase). This must be
 118  *                  a readable buffer of length \p len Bytes. It need
 119  *                  only be valid for the duration of this call.
 120  * \param len       The length of the pre-shared secret \p secret.
 121  *
 122  * \return          \c 0 if successful.
 123  * \return          A negative error code on failure.
 124  */
 125 int mbedtls_ecjpake_setup(mbedtls_ecjpake_context *ctx,
 126                           mbedtls_ecjpake_role role,
 127                           mbedtls_md_type_t hash,
 128                           mbedtls_ecp_group_id curve,
 129                           const unsigned char *secret,
 130                           size_t len);
 131
 132 /**
 133  * \brief           Check if an ECJPAKE context is ready for use.
 134  *
 135  * \param ctx       The ECJPAKE context to check. This must be
 136  *                  initialized.
 137  *
 138  * \return          \c 0 if the context is ready for use.
 139  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.
 140  */
 141 int mbedtls_ecjpake_check(const mbedtls_ecjpake_context *ctx);
 142
 143 /**
 144  * \brief           Generate and write the first round message
 145  *                  (TLS: contents of the Client/ServerHello extension,
 146  *                  excluding extension type and length bytes).
 147  *
 148  * \param ctx       The ECJPAKE context to use. This must be
 149  *                  initialized and set up.
 150  * \param buf       The buffer to write the contents to. This must be a
 151  *                  writable buffer of length \p len Bytes.
 152  * \param len       The length of \p buf in Bytes.
 153  * \param olen      The address at which to store the total number
 154  *                  of Bytes written to \p buf. This must not be \c NULL.
 155  * \param f_rng     The RNG function to use. This must not be \c NULL.
 156  * \param p_rng     The RNG parameter to be passed to \p f_rng. This
 157  *                  may be \c NULL if \p f_rng doesn't use a context.
 158  *
 159  * \return          \c 0 if successful.
 160  * \return          A negative error code on failure.
 161  */
 162 int mbedtls_ecjpake_write_round_one(mbedtls_ecjpake_context *ctx,
 163                                     unsigned char *buf, size_t len, size_t *olen,
 164                                     int (*f_rng)(void *, unsigned char *, size_t),
 165                                     void *p_rng);
 166
 167 /**
 168  * \brief           Read and process the first round message
 169  *                  (TLS: contents of the Client/ServerHello extension,
 170  *                  excluding extension type and length bytes).
 171  *
 172  * \param ctx       The ECJPAKE context to use. This must be initialized
 173  *                  and set up.
 174  * \param buf       The buffer holding the first round message. This must
 175  *                  be a readable buffer of length \p len Bytes.
 176  * \param len       The length in Bytes of \p buf.
 177  *
 178  * \return          \c 0 if successful.
 179  * \return          A negative error code on failure.
 180  */
 181 int mbedtls_ecjpake_read_round_one(mbedtls_ecjpake_context *ctx,
 182                                    const unsigned char *buf,
 183                                    size_t len);
 184
 185 /**
 186  * \brief           Generate and write the second round message
 187  *                  (TLS: contents of the Client/ServerKeyExchange).
 188  *
 189  * \param ctx       The ECJPAKE context to use. This must be initialized,
 190  *                  set up, and already have performed round one.
 191  * \param buf       The buffer to write the round two contents to.
 192  *                  This must be a writable buffer of length \p len Bytes.
 193  * \param len       The size of \p buf in Bytes.
 194  * \param olen      The address at which to store the total number of Bytes
 195  *                  written to \p buf. This must not be \c NULL.
 196  * \param f_rng     The RNG function to use. This must not be \c NULL.
 197  * \param p_rng     The RNG parameter to be passed to \p f_rng. This
 198  *                  may be \c NULL if \p f_rng doesn't use a context.
 199  *
 200  * \return          \c 0 if successful.
 201  * \return          A negative error code on failure.
 202  */
 203 int mbedtls_ecjpake_write_round_two(mbedtls_ecjpake_context *ctx,
 204                                     unsigned char *buf, size_t len, size_t *olen,
 205                                     int (*f_rng)(void *, unsigned char *, size_t),
 206                                     void *p_rng);
 207
 208 /**
 209  * \brief           Read and process the second round message
 210  *                  (TLS: contents of the Client/ServerKeyExchange).
 211  *
 212  * \param ctx       The ECJPAKE context to use. This must be initialized
 213  *                  and set up and already have performed round one.
 214  * \param buf       The buffer holding the second round message. This must
 215  *                  be a readable buffer of length \p len Bytes.
 216  * \param len       The length in Bytes of \p buf.
 217  *
 218  * \return          \c 0 if successful.
 219  * \return          A negative error code on failure.
 220  */
 221 int mbedtls_ecjpake_read_round_two(mbedtls_ecjpake_context *ctx,
 222                                    const unsigned char *buf,
 223                                    size_t len);
 224
 225 /**
 226  * \brief           Derive the shared secret
 227  *                  (TLS: Pre-Master Secret).
 228  *
 229  * \param ctx       The ECJPAKE context to use. This must be initialized,
 230  *                  set up and have performed both round one and two.
 231  * \param buf       The buffer to write the derived secret to. This must
 232  *                  be a writable buffer of length \p len Bytes.
 233  * \param len       The length of \p buf in Bytes.
 234  * \param olen      The address at which to store the total number of Bytes
 235  *                  written to \p buf. This must not be \c NULL.
 236  * \param f_rng     The RNG function to use. This must not be \c NULL.
 237  * \param p_rng     The RNG parameter to be passed to \p f_rng. This
 238  *                  may be \c NULL if \p f_rng doesn't use a context.
 239  *
 240  * \return          \c 0 if successful.
 241  * \return          A negative error code on failure.
 242  */
 243 int mbedtls_ecjpake_derive_secret(mbedtls_ecjpake_context *ctx,
 244                                   unsigned char *buf, size_t len, size_t *olen,
 245                                   int (*f_rng)(void *, unsigned char *, size_t),
 246                                   void *p_rng);
 247
 248 /**
 249  * \brief           This clears an ECJPAKE context and frees any
 250  *                  embedded data structure.
 251  *
 252  * \param ctx       The ECJPAKE context to free. This may be \c NULL,
 253  *                  in which case this function does nothing. If it is not
 254  *                  \c NULL, it must point to an initialized ECJPAKE context.
 255  */
 256 void mbedtls_ecjpake_free(mbedtls_ecjpake_context *ctx);
 257
 258 #if defined(MBEDTLS_SELF_TEST)
 259
 260 /**
 261  * \brief          Checkup routine
 262  *
 263  * \return         0 if successful, or 1 if a test failed
 264  */
 265 int mbedtls_ecjpake_self_test(int verbose);
 266
 267 #endif /* MBEDTLS_SELF_TEST */
 268
 269 #ifdef __cplusplus
 270 }
 271 #endif
 272
 273
 274 #endif /* ecjpake.h */