git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/ecjpake.h

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