ecjpake.h

00001 /**
00002  * \file ecjpake.h
00003  *
00004  * \brief Elliptic curve J-PAKE
00005  */
00006 /*
00007  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00008  *  SPDX-License-Identifier: Apache-2.0
00009  *
00010  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00011  *  not use this file except in compliance with the License.
00012  *  You may obtain a copy of the License at
00013  *
00014  *  http://www.apache.org/licenses/LICENSE-2.0
00015  *
00016  *  Unless required by applicable law or agreed to in writing, software
00017  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00018  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00019  *  See the License for the specific language governing permissions and
00020  *  limitations under the License.
00021  *
00022  *  This file is part of mbed TLS (https://tls.mbed.org)
00023  */
00024 #ifndef MBEDTLS_ECJPAKE_H
00025 #define MBEDTLS_ECJPAKE_H
00026 
00027 /*
00028  * J-PAKE is a password-authenticated key exchange that allows deriving a
00029  * strong shared secret from a (potentially low entropy) pre-shared
00030  * passphrase, with forward secrecy and mutual authentication.
00031  * https://en.wikipedia.org/wiki/Password_Authenticated_Key_Exchange_by_Juggling
00032  *
00033  * This file implements the Elliptic Curve variant of J-PAKE,
00034  * as defined in Chapter 7.4 of the Thread v1.0 Specification,
00035  * available to members of the Thread Group http://threadgroup.org/
00036  *
00037  * As the J-PAKE algorithm is inherently symmetric, so is our API.
00038  * Each party needs to send its first round message, in any order, to the
00039  * other party, then each sends its second round message, in any order.
00040  * The payloads are serialized in a way suitable for use in TLS, but could
00041  * also be use outside TLS.
00042  */
00043 
00044 #include "ecp.h"
00045 #include "md.h"
00046 
00047 #ifdef __cplusplus
00048 extern "C" {
00049 #endif
00050 
00051 /**
00052  * Roles in the EC J-PAKE exchange
00053  */
00054 typedef enum {
00055     MBEDTLS_ECJPAKE_CLIENT = 0,         /**< Client                         */
00056     MBEDTLS_ECJPAKE_SERVER,             /**< Server                         */
00057 } mbedtls_ecjpake_role;
00058 
00059 #if !defined(MBEDTLS_ECJPAKE_ALT)
00060 /**
00061  * EC J-PAKE context structure.
00062  *
00063  * J-PAKE is a symmetric protocol, except for the identifiers used in
00064  * Zero-Knowledge Proofs, and the serialization of the second message
00065  * (KeyExchange) as defined by the Thread spec.
00066  *
00067  * In order to benefit from this symmetry, we choose a different naming
00068  * convetion from the Thread v1.0 spec. Correspondance is indicated in the
00069  * description as a pair C: client name, S: server name
00070  */
00071 typedef struct mbedtls_ecjpake_context
00072 {
00073     const mbedtls_md_info_t *md_info;   /**< Hash to use                    */
00074     mbedtls_ecp_group grp;              /**< Elliptic curve                 */
00075     mbedtls_ecjpake_role role;          /**< Are we client or server?       */
00076     int point_format;                   /**< Format for point export        */
00077 
00078     mbedtls_ecp_point Xm1;              /**< My public key 1   C: X1, S: X3 */
00079     mbedtls_ecp_point Xm2;              /**< My public key 2   C: X2, S: X4 */
00080     mbedtls_ecp_point Xp1;              /**< Peer public key 1 C: X3, S: X1 */
00081     mbedtls_ecp_point Xp2;              /**< Peer public key 2 C: X4, S: X2 */
00082     mbedtls_ecp_point Xp;               /**< Peer public key   C: Xs, S: Xc */
00083 
00084     mbedtls_mpi xm1;                    /**< My private key 1  C: x1, S: x3 */
00085     mbedtls_mpi xm2;                    /**< My private key 2  C: x2, S: x4 */
00086 
00087     mbedtls_mpi s;                      /**< Pre-shared secret (passphrase) */
00088 } mbedtls_ecjpake_context;
00089 
00090 #else  /* MBEDTLS_ECJPAKE_ALT */
00091 #include "ecjpake_alt.h"
00092 #endif /* MBEDTLS_ECJPAKE_ALT */
00093 
00094 /**
00095  * \brief           Initialize a context
00096  *                  (just makes it ready for setup() or free()).
00097  *
00098  * \param ctx       context to initialize
00099  */
00100 void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
00101 
00102 /**
00103  * \brief           Set up a context for use
00104  *
00105  * \note            Currently the only values for hash/curve allowed by the
00106  *                  standard are MBEDTLS_MD_SHA256/MBEDTLS_ECP_DP_SECP256R1.
00107  *
00108  * \param ctx       context to set up
00109  * \param role      Our role: client or server
00110  * \param hash      hash function to use (MBEDTLS_MD_XXX)
00111  * \param curve     elliptic curve identifier (MBEDTLS_ECP_DP_XXX)
00112  * \param secret    pre-shared secret (passphrase)
00113  * \param len       length of the shared secret
00114  *
00115  * \return          0 if successfull,
00116  *                  a negative error code otherwise
00117  */
00118 int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
00119                            mbedtls_ecjpake_role role,
00120                            mbedtls_md_type_t hash,
00121                            mbedtls_ecp_group_id curve,
00122                            const unsigned char *secret,
00123                            size_t len );
00124 
00125 /**
00126  * \brief           Check if a context is ready for use
00127  *
00128  * \param ctx       Context to check
00129  *
00130  * \return          0 if the context is ready for use,
00131  *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
00132  */
00133 int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx );
00134 
00135 /**
00136  * \brief           Generate and write the first round message
00137  *                  (TLS: contents of the Client/ServerHello extension,
00138  *                  excluding extension type and length bytes)
00139  *
00140  * \param ctx       Context to use
00141  * \param buf       Buffer to write the contents to
00142  * \param len       Buffer size
00143  * \param olen      Will be updated with the number of bytes written
00144  * \param f_rng     RNG function
00145  * \param p_rng     RNG parameter
00146  *
00147  * \return          0 if successfull,
00148  *                  a negative error code otherwise
00149  */
00150 int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
00151                             unsigned char *buf, size_t len, size_t *olen,
00152                             int (*f_rng)(void *, unsigned char *, size_t),
00153                             void *p_rng );
00154 
00155 /**
00156  * \brief           Read and process the first round message
00157  *                  (TLS: contents of the Client/ServerHello extension,
00158  *                  excluding extension type and length bytes)
00159  *
00160  * \param ctx       Context to use
00161  * \param buf       Pointer to extension contents
00162  * \param len       Extension length
00163  *
00164  * \return          0 if successfull,
00165  *                  a negative error code otherwise
00166  */
00167 int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
00168                                     const unsigned char *buf,
00169                                     size_t len );
00170 
00171 /**
00172  * \brief           Generate and write the second round message
00173  *                  (TLS: contents of the Client/ServerKeyExchange)
00174  *
00175  * \param ctx       Context to use
00176  * \param buf       Buffer to write the contents to
00177  * \param len       Buffer size
00178  * \param olen      Will be updated with the number of bytes written
00179  * \param f_rng     RNG function
00180  * \param p_rng     RNG parameter
00181  *
00182  * \return          0 if successfull,
00183  *                  a negative error code otherwise
00184  */
00185 int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
00186                             unsigned char *buf, size_t len, size_t *olen,
00187                             int (*f_rng)(void *, unsigned char *, size_t),
00188                             void *p_rng );
00189 
00190 /**
00191  * \brief           Read and process the second round message
00192  *                  (TLS: contents of the Client/ServerKeyExchange)
00193  *
00194  * \param ctx       Context to use
00195  * \param buf       Pointer to the message
00196  * \param len       Message length
00197  *
00198  * \return          0 if successfull,
00199  *                  a negative error code otherwise
00200  */
00201 int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
00202                                     const unsigned char *buf,
00203                                     size_t len );
00204 
00205 /**
00206  * \brief           Derive the shared secret
00207  *                  (TLS: Pre-Master Secret)
00208  *
00209  * \param ctx       Context to use
00210  * \param buf       Buffer to write the contents to
00211  * \param len       Buffer size
00212  * \param olen      Will be updated with the number of bytes written
00213  * \param f_rng     RNG function
00214  * \param p_rng     RNG parameter
00215  *
00216  * \return          0 if successfull,
00217  *                  a negative error code otherwise
00218  */
00219 int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
00220                             unsigned char *buf, size_t len, size_t *olen,
00221                             int (*f_rng)(void *, unsigned char *, size_t),
00222                             void *p_rng );
00223 
00224 /**
00225  * \brief           Free a context's content
00226  *
00227  * \param ctx       context to free
00228  */
00229 void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
00230 
00231 
00232 
00233 #if defined(MBEDTLS_SELF_TEST)
00234 
00235 /**
00236  * \brief          Checkup routine
00237  *
00238  * \return         0 if successful, or 1 if a test failed
00239  */
00240 int mbedtls_ecjpake_self_test( int verbose );
00241 
00242 #endif /* MBEDTLS_SELF_TEST */
00243 
00244 #ifdef __cplusplus
00245 }
00246 #endif
00247 
00248 
00249 #endif /* ecjpake.h */