Provide symmetric API for the first round
diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h
index 8d624d4..8dc8244 100644
--- a/include/mbedtls/ecjpake.h
+++ b/include/mbedtls/ecjpake.h
@@ -27,8 +27,17 @@
* Implementation based on Chapter 7.4 of the Thread v1.0 Specification,
* available from the Thread Group http://threadgroup.org/
*
- * This file implements the EC J-PAKE algorithm, with payload serializations
+ * J-PAKE is a password-authenticated key exchange that allows deriving a
+ * strong shared secret from a (potentially low entropy) pre-shared
+ * passphrase, with forward secrecy and mutual authentication.
+ * https://en.wikipedia.org/wiki/Password_Authenticated_Key_Exchange_by_Juggling
+ *
+ * This file implements the EC J-PAKE algorithm with payload serializations
* suitable for use in TLS, but the result could be used outside TLS.
+ *
+ * As the J-PAKE algorithm is inherently symmetric, so is our API.
+ * Each party needs to send its first round message, in any order, to the
+ * other party, then each sends its second round message, in any order.
*/
#include "ecp.h"
@@ -107,8 +116,9 @@
size_t len );
/*
- * \brief Generate and write contents of ClientHello extension
- * (excluding extension type and length bytes)
+ * \brief Generate and write the first round message
+ * (TLS: contents of the Client/ServerHello extension,
+ * excluding extension type and length bytes)
*
* \param ctx Context to use
* \param buf Buffer to write the contents to
@@ -120,13 +130,14 @@
* \return 0 if successfull,
* a negative error code otherwise
*/
-int mbedtls_ecjpake_tls_write_client_ext( mbedtls_ecjpake_context *ctx,
+int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
/*
- * \brief Read and process contents of the ClientHello extension
- * (excluding extension type and length bytes)
+ * \brief Generate and write the first round message
+ * (TLS: contents of the Client/ServerHello extension,
+ * excluding extension type and length bytes)
*
* \param ctx Context to use
* \param buf Pointer to extension contents
@@ -135,43 +146,9 @@
* \return 0 if successfull,
* a negative error code otherwise
*/
-int mbedtls_ecjpake_tls_read_client_ext( mbedtls_ecjpake_context *ctx,
- const unsigned char *buf,
- size_t len );
-
-/*
- * \brief Generate and write contents of ServerHello extension
- * (excluding extension type and length bytes)
- *
- * \param ctx Context to use
- * \param buf Buffer to write the contents to
- * \param len Buffer size
- * \param olen Will be updated with the number of bytes written
- * \param f_rng RNG function
- * \param p_rng RNG parameter
- *
- * \return 0 if successfull,
- * a negative error code otherwise
- */
-int mbedtls_ecjpake_tls_write_server_ext( mbedtls_ecjpake_context *ctx,
- unsigned char *buf, size_t len, size_t *olen,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng );
-
-/*
- * \brief Read and process contents of the ServerHello extension
- * (excluding extension type and length bytes)
- *
- * \param ctx Context to use
- * \param buf Pointer to extension contents
- * \param len Extension length
- *
- * \return 0 if successfull,
- * a negative error code otherwise
- */
-int mbedtls_ecjpake_tls_read_server_ext( mbedtls_ecjpake_context *ctx,
- const unsigned char *buf,
- size_t len );
+int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
+ const unsigned char *buf,
+ size_t len );
/*
* \brief Generate and write ServerECJPAKEParams
diff --git a/library/ecjpake.c b/library/ecjpake.c
index 0795c1d..08d54d7 100644
--- a/library/ecjpake.c
+++ b/library/ecjpake.c
@@ -464,11 +464,11 @@
}
/*
- * Read the contents of the ClientHello extension
+ * Read and process the first round message
*/
-int mbedtls_ecjpake_tls_read_client_ext( mbedtls_ecjpake_context *ctx,
- const unsigned char *buf,
- size_t len )
+int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
+ const unsigned char *buf,
+ size_t len )
{
return( ecjpake_kkpp_read( ctx->md_info, &ctx->grp, &ctx->grp.G,
&ctx->Xp1, &ctx->Xp2, ID_PEER,
@@ -476,34 +476,9 @@
}
/*
- * Read the contents of the ServerHello extension
+ * Generate and write the first round message
*/
-int mbedtls_ecjpake_tls_read_server_ext( mbedtls_ecjpake_context *ctx,
- const unsigned char *buf,
- size_t len )
-{
- return( ecjpake_kkpp_read( ctx->md_info, &ctx->grp, &ctx->grp.G,
- &ctx->Xp1, &ctx->Xp2, ID_PEER,
- buf, len ) );
-}
-
-/*
- * Generate the contents of the ClientHello extension
- */
-int mbedtls_ecjpake_tls_write_client_ext( mbedtls_ecjpake_context *ctx,
- unsigned char *buf, size_t len, size_t *olen,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng )
-{
- return( ecjpake_kkpp_write( ctx->md_info, &ctx->grp, &ctx->grp.G,
- &ctx->xm1, &ctx->Xm1, &ctx->xm2, &ctx->Xm2,
- ID_MINE, buf, len, olen, f_rng, p_rng ) );
-}
-
-/*
- * Generate the contents of the ServerHello extension
- */
-int mbedtls_ecjpake_tls_write_server_ext( mbedtls_ecjpake_context *ctx,
+int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng )
@@ -1047,15 +1022,15 @@
if( verbose != 0 )
mbedtls_printf( " ECJPAKE test #1 (random handshake): " );
- TEST_ASSERT( mbedtls_ecjpake_tls_write_client_ext( &cli,
+ TEST_ASSERT( mbedtls_ecjpake_write_round_one( &cli,
buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 );
- TEST_ASSERT( mbedtls_ecjpake_tls_read_client_ext( &srv, buf, len ) == 0 );
+ TEST_ASSERT( mbedtls_ecjpake_read_round_one( &srv, buf, len ) == 0 );
- TEST_ASSERT( mbedtls_ecjpake_tls_write_server_ext( &srv,
+ TEST_ASSERT( mbedtls_ecjpake_write_round_one( &srv,
buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 );
- TEST_ASSERT( mbedtls_ecjpake_tls_read_server_ext( &cli, buf, len ) == 0 );
+ TEST_ASSERT( mbedtls_ecjpake_read_round_one( &cli, buf, len ) == 0 );
TEST_ASSERT( mbedtls_ecjpake_tls_write_server_params( &srv,
buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 );
@@ -1088,7 +1063,7 @@
ecjpake_test_x2, sizeof( ecjpake_test_x2 ) ) );
/* Server reads client ext */
- TEST_ASSERT( mbedtls_ecjpake_tls_read_client_ext( &srv,
+ TEST_ASSERT( mbedtls_ecjpake_read_round_one( &srv,
ecjpake_test_cli_ext,
sizeof( ecjpake_test_cli_ext ) ) == 0 );
@@ -1098,7 +1073,7 @@
ecjpake_test_x4, sizeof( ecjpake_test_x4 ) ) );
/* Client reads server ext and key exchange */
- TEST_ASSERT( mbedtls_ecjpake_tls_read_server_ext( &cli,
+ TEST_ASSERT( mbedtls_ecjpake_read_round_one( &cli,
ecjpake_test_srv_ext,
sizeof( ecjpake_test_srv_ext ) ) == 0 );