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 #if !defined(MBEDTLS_ECJPAKE_ALT)
00048 
00049 #ifdef __cplusplus
00050 extern "C" {
00051 #endif
00052 
00053 /**
00054  * Roles in the EC J-PAKE exchange
00055  */
00056 typedef enum {
00057     MBEDTLS_ECJPAKE_CLIENT = 0,         /**< Client                         */
00058     MBEDTLS_ECJPAKE_SERVER,             /**< Server                         */
00059 } mbedtls_ecjpake_role;
00060 
00061 /**
00062  * EC J-PAKE context structure.
00063  *
00064  * J-PAKE is a symmetric protocol, except for the identifiers used in
00065  * Zero-Knowledge Proofs, and the serialization of the second message
00066  * (KeyExchange) as defined by the Thread spec.
00067  *
00068  * In order to benefit from this symmetry, we choose a different naming
00069  * convetion from the Thread v1.0 spec. Correspondance is indicated in the
00070  * description as a pair C: client name, S: server name
00071  */
00072 typedef struct
00073 {
00074     const mbedtls_md_info_t *md_info;   /**< Hash to use                    */
00075     mbedtls_ecp_group grp;              /**< Elliptic curve                 */
00076     mbedtls_ecjpake_role role;          /**< Are we client or server?       */
00077     int point_format;                   /**< Format for point export        */
00078 
00079     mbedtls_ecp_point Xm1;              /**< My public key 1   C: X1, S: X3 */
00080     mbedtls_ecp_point Xm2;              /**< My public key 2   C: X2, S: X4 */
00081     mbedtls_ecp_point Xp1;              /**< Peer public key 1 C: X3, S: X1 */
00082     mbedtls_ecp_point Xp2;              /**< Peer public key 2 C: X4, S: X2 */
00083     mbedtls_ecp_point Xp;               /**< Peer public key   C: Xs, S: Xc */
00084 
00085     mbedtls_mpi xm1;                    /**< My private key 1  C: x1, S: x3 */
00086     mbedtls_mpi xm2;                    /**< My private key 2  C: x2, S: x4 */
00087 
00088     mbedtls_mpi s;                      /**< Pre-shared secret (passphrase) */
00089 } mbedtls_ecjpake_context;
00090 
00091 /**
00092  * \brief           Initialize a context
00093  *                  (just makes it ready for setup() or free()).
00094  *
00095  * \param ctx       context to initialize
00096  */
00097 void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
00098 
00099 /**
00100  * \brief           Set up a context for use
00101  *
00102  * \note            Currently the only values for hash/curve allowed by the
00103  *                  standard are MBEDTLS_MD_SHA256/MBEDTLS_ECP_DP_SECP256R1.
00104  *
00105  * \param ctx       context to set up
00106  * \param role      Our role: client or server
00107  * \param hash      hash function to use (MBEDTLS_MD_XXX)
00108  * \param curve     elliptic curve identifier (MBEDTLS_ECP_DP_XXX)
00109  * \param secret    pre-shared secret (passphrase)
00110  * \param len       length of the shared secret
00111  *
00112  * \return          0 if successfull,
00113  *                  a negative error code otherwise
00114  */
00115 int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
00116                            mbedtls_ecjpake_role role,
00117                            mbedtls_md_type_t hash,
00118                            mbedtls_ecp_group_id curve,
00119                            const unsigned char *secret,
00120                            size_t len );
00121 
00122 /**
00123  * \brief           Check if a context is ready for use
00124  *
00125  * \param ctx       Context to check
00126  *
00127  * \return          0 if the context is ready for use,
00128  *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
00129  */
00130 int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx );
00131 
00132 /**
00133  * \brief           Generate and write the first round message
00134  *                  (TLS: contents of the Client/ServerHello extension,
00135  *                  excluding extension type and length bytes)
00136  *
00137  * \param ctx       Context to use
00138  * \param buf       Buffer to write the contents to
00139  * \param len       Buffer size
00140  * \param olen      Will be updated with the number of bytes written
00141  * \param f_rng     RNG function
00142  * \param p_rng     RNG parameter
00143  *
00144  * \return          0 if successfull,
00145  *                  a negative error code otherwise
00146  */
00147 int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
00148                             unsigned char *buf, size_t len, size_t *olen,
00149                             int (*f_rng)(void *, unsigned char *, size_t),
00150                             void *p_rng );
00151 
00152 /**
00153  * \brief           Read and process the first round message
00154  *                  (TLS: contents of the Client/ServerHello extension,
00155  *                  excluding extension type and length bytes)
00156  *
00157  * \param ctx       Context to use
00158  * \param buf       Pointer to extension contents
00159  * \param len       Extension length
00160  *
00161  * \return          0 if successfull,
00162  *                  a negative error code otherwise
00163  */
00164 int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
00165                                     const unsigned char *buf,
00166                                     size_t len );
00167 
00168 /**
00169  * \brief           Generate and write the second round message
00170  *                  (TLS: contents of the Client/ServerKeyExchange)
00171  *
00172  * \param ctx       Context to use
00173  * \param buf       Buffer to write the contents to
00174  * \param len       Buffer size
00175  * \param olen      Will be updated with the number of bytes written
00176  * \param f_rng     RNG function
00177  * \param p_rng     RNG parameter
00178  *
00179  * \return          0 if successfull,
00180  *                  a negative error code otherwise
00181  */
00182 int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
00183                             unsigned char *buf, size_t len, size_t *olen,
00184                             int (*f_rng)(void *, unsigned char *, size_t),
00185                             void *p_rng );
00186 
00187 /**
00188  * \brief           Read and process the second round message
00189  *                  (TLS: contents of the Client/ServerKeyExchange)
00190  *
00191  * \param ctx       Context to use
00192  * \param buf       Pointer to the message
00193  * \param len       Message length
00194  *
00195  * \return          0 if successfull,
00196  *                  a negative error code otherwise
00197  */
00198 int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
00199                                     const unsigned char *buf,
00200                                     size_t len );
00201 
00202 /**
00203  * \brief           Derive the shared secret
00204  *                  (TLS: Pre-Master Secret)
00205  *
00206  * \param ctx       Context to use
00207  * \param buf       Buffer to write the contents to
00208  * \param len       Buffer size
00209  * \param olen      Will be updated with the number of bytes written
00210  * \param f_rng     RNG function
00211  * \param p_rng     RNG parameter
00212  *
00213  * \return          0 if successfull,
00214  *                  a negative error code otherwise
00215  */
00216 int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
00217                             unsigned char *buf, size_t len, size_t *olen,
00218                             int (*f_rng)(void *, unsigned char *, size_t),
00219                             void *p_rng );
00220 
00221 /**
00222  * \brief           Free a context's content
00223  *
00224  * \param ctx       context to free
00225  */
00226 void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
00227 
00228 #ifdef __cplusplus
00229 }
00230 #endif
00231 
00232 #else  /* MBEDTLS_ECJPAKE_ALT */
00233 #include "ecjpake_alt.h"
00234 #endif /* MBEDTLS_ECJPAKE_ALT */
00235 
00236 #if defined(MBEDTLS_SELF_TEST)
00237 
00238 #ifdef __cplusplus
00239 extern "C" {
00240 #endif
00241 
00242 /**
00243  * \brief          Checkup routine
00244  *
00245  * \return         0 if successful, or 1 if a test failed
00246  */
00247 int mbedtls_ecjpake_self_test( int verbose );
00248 
00249 #ifdef __cplusplus
00250 }
00251 #endif
00252 
00253 #endif /* MBEDTLS_SELF_TEST */
00254 
00255 #endif /* ecjpake.h */