diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h index 8d624d439..8dc8244e7 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 @@ int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx, 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 @@ int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx, * \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 @@ int mbedtls_ecjpake_tls_write_client_ext( mbedtls_ecjpake_context *ctx, * \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 0795c1d4f..08d54d79a 100644 --- a/library/ecjpake.c +++ b/library/ecjpake.c @@ -464,11 +464,11 @@ cleanup: } /* - * 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 @@ int mbedtls_ecjpake_tls_read_client_ext( mbedtls_ecjpake_context *ctx, } /* - * 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 @@ int mbedtls_ecjpake_self_test( int verbose ) 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 @@ int mbedtls_ecjpake_self_test( int verbose ) 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 @@ int mbedtls_ecjpake_self_test( int verbose ) 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 );