reactos/sdk/include/reactos/libs/mbedtls/ecjpake.h

   1 /**
   2  * \file ecjpake.h
   3  *
   4  * \brief Elliptic curve J-PAKE
   5  *
   6  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
   7  *  SPDX-License-Identifier: GPL-2.0
   8  *
   9  *  This program is free software; you can redistribute it and/or modify
  10  *  it under the terms of the GNU General Public License as published by
  11  *  the Free Software Foundation; either version 2 of the License, or
  12  *  (at your option) any later version.
  13  *
  14  *  This program is distributed in the hope that it will be useful,
  15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  *  GNU General Public License for more details.
  18  *
  19  *  You should have received a copy of the GNU General Public License along
  20  *  with this program; if not, write to the Free Software Foundation, Inc.,
  21  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  22  *
  23  *  This file is part of mbed TLS (https://tls.mbed.org)
  24  */
  25 #ifndef MBEDTLS_ECJPAKE_H
  26 #define MBEDTLS_ECJPAKE_H
  27
  28 /*
  29  * J-PAKE is a password-authenticated key exchange that allows deriving a
  30  * strong shared secret from a (potentially low entropy) pre-shared
  31  * passphrase, with forward secrecy and mutual authentication.
  32  * https://en.wikipedia.org/wiki/Password_Authenticated_Key_Exchange_by_Juggling
  33  *
  34  * This file implements the Elliptic Curve variant of J-PAKE,
  35  * as defined in Chapter 7.4 of the Thread v1.0 Specification,
  36  * available to members of the Thread Group http://threadgroup.org/
  37  *
  38  * As the J-PAKE algorithm is inherently symmetric, so is our API.
  39  * Each party needs to send its first round message, in any order, to the
  40  * other party, then each sends its second round message, in any order.
  41  * The payloads are serialized in a way suitable for use in TLS, but could
  42  * also be use outside TLS.
  43  */
  44
  45 #include "ecp.h"
  46 #include "md.h"
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 /**
  53  * Roles in the EC J-PAKE exchange
  54  */
  55 typedef enum {
  56     MBEDTLS_ECJPAKE_CLIENT = 0,         /**< Client                         */
  57     MBEDTLS_ECJPAKE_SERVER,             /**< Server                         */
  58 } mbedtls_ecjpake_role;
  59
  60 /**
  61  * EC J-PAKE context structure.
  62  *
  63  * J-PAKE is a symmetric protocol, except for the identifiers used in
  64  * Zero-Knowledge Proofs, and the serialization of the second message
  65  * (KeyExchange) as defined by the Thread spec.
  66  *
  67  * In order to benefit from this symmetry, we choose a different naming
  68  * convetion from the Thread v1.0 spec. Correspondance is indicated in the
  69  * description as a pair C: client name, S: server name
  70  */
  71 typedef struct
  72 {
  73     const mbedtls_md_info_t *md_info;   /**< Hash to use                    */
  74     mbedtls_ecp_group grp;              /**< Elliptic curve                 */
  75     mbedtls_ecjpake_role role;          /**< Are we client or server?       */
  76     int point_format;                   /**< Format for point export        */
  77
  78     mbedtls_ecp_point Xm1;              /**< My public key 1   C: X1, S: X3 */
  79     mbedtls_ecp_point Xm2;              /**< My public key 2   C: X2, S: X4 */
  80     mbedtls_ecp_point Xp1;              /**< Peer public key 1 C: X3, S: X1 */
  81     mbedtls_ecp_point Xp2;              /**< Peer public key 2 C: X4, S: X2 */
  82     mbedtls_ecp_point Xp;               /**< Peer public key   C: Xs, S: Xc */
  83
  84     mbedtls_mpi xm1;                    /**< My private key 1  C: x1, S: x3 */
  85     mbedtls_mpi xm2;                    /**< My private key 2  C: x2, S: x4 */
  86
  87     mbedtls_mpi s;                      /**< Pre-shared secret (passphrase) */
  88 } mbedtls_ecjpake_context;
  89
  90 /**
  91  * \brief           Initialize a context
  92  *                  (just makes it ready for setup() or free()).
  93  *
  94  * \param ctx       context to initialize
  95  */
  96 void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
  97
  98 /**
  99  * \brief           Set up a context for use
 100  *
 101  * \note            Currently the only values for hash/curve allowed by the
 102  *                  standard are MBEDTLS_MD_SHA256/MBEDTLS_ECP_DP_SECP256R1.
 103  *
 104  * \param ctx       context to set up
 105  * \param role      Our role: client or server
 106  * \param hash      hash function to use (MBEDTLS_MD_XXX)
 107  * \param curve     elliptic curve identifier (MBEDTLS_ECP_DP_XXX)
 108  * \param secret    pre-shared secret (passphrase)
 109  * \param len       length of the shared secret
 110  *
 111  * \return          0 if successfull,
 112  *                  a negative error code otherwise
 113  */
 114 int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
 115                            mbedtls_ecjpake_role role,
 116                            mbedtls_md_type_t hash,
 117                            mbedtls_ecp_group_id curve,
 118                            const unsigned char *secret,
 119                            size_t len );
 120
 121 /*
 122  * \brief           Check if a context is ready for use
 123  *
 124  * \param ctx       Context to check
 125  *
 126  * \return          0 if the context is ready for use,
 127  *                  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       Context to use
 137  * \param buf       Buffer to write the contents to
 138  * \param len       Buffer size
 139  * \param olen      Will be updated with the number of bytes written
 140  * \param f_rng     RNG function
 141  * \param p_rng     RNG parameter
 142  *
 143  * \return          0 if successfull,
 144  *                  a negative error code otherwise
 145  */
 146 int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
 147                             unsigned char *buf, size_t len, size_t *olen,
 148                             int (*f_rng)(void *, unsigned char *, size_t),
 149                             void *p_rng );
 150
 151 /**
 152  * \brief           Read and process the first round message
 153  *                  (TLS: contents of the Client/ServerHello extension,
 154  *                  excluding extension type and length bytes)
 155  *
 156  * \param ctx       Context to use
 157  * \param buf       Pointer to extension contents
 158  * \param len       Extension length
 159  *
 160  * \return          0 if successfull,
 161  *                  a negative error code otherwise
 162  */
 163 int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
 164                                     const unsigned char *buf,
 165                                     size_t len );
 166
 167 /**
 168  * \brief           Generate and write the second round message
 169  *                  (TLS: contents of the Client/ServerKeyExchange)
 170  *
 171  * \param ctx       Context to use
 172  * \param buf       Buffer to write the contents to
 173  * \param len       Buffer size
 174  * \param olen      Will be updated with the number of bytes written
 175  * \param f_rng     RNG function
 176  * \param p_rng     RNG parameter
 177  *
 178  * \return          0 if successfull,
 179  *                  a negative error code otherwise
 180  */
 181 int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
 182                             unsigned char *buf, size_t len, size_t *olen,
 183                             int (*f_rng)(void *, unsigned char *, size_t),
 184                             void *p_rng );
 185
 186 /**
 187  * \brief           Read and process the second round message
 188  *                  (TLS: contents of the Client/ServerKeyExchange)
 189  *
 190  * \param ctx       Context to use
 191  * \param buf       Pointer to the message
 192  * \param len       Message length
 193  *
 194  * \return          0 if successfull,
 195  *                  a negative error code otherwise
 196  */
 197 int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
 198                                     const unsigned char *buf,
 199                                     size_t len );
 200
 201 /**
 202  * \brief           Derive the shared secret
 203  *                  (TLS: Pre-Master Secret)
 204  *
 205  * \param ctx       Context to use
 206  * \param buf       Buffer to write the contents to
 207  * \param len       Buffer size
 208  * \param olen      Will be updated with the number of bytes written
 209  * \param f_rng     RNG function
 210  * \param p_rng     RNG parameter
 211  *
 212  * \return          0 if successfull,
 213  *                  a negative error code otherwise
 214  */
 215 int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
 216                             unsigned char *buf, size_t len, size_t *olen,
 217                             int (*f_rng)(void *, unsigned char *, size_t),
 218                             void *p_rng );
 219
 220 /**
 221  * \brief           Free a context's content
 222  *
 223  * \param ctx       context to free
 224  */
 225 void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
 226
 227 #if defined(MBEDTLS_SELF_TEST)
 228 /**
 229  * \brief          Checkup routine
 230  *
 231  * \return         0 if successful, or 1 if a test failed
 232  */
 233 int mbedtls_ecjpake_self_test( int verbose );
 234 #endif
 235
 236 #ifdef __cplusplus
 237 }
 238 #endif
 239
 240 #endif /* ecjpake.h */