diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h index 56bf39739..59e80e50e 100644 --- a/include/mbedtls/ecjpake.h +++ b/include/mbedtls/ecjpake.h @@ -24,20 +24,20 @@ #define MBEDTLS_ECJPAKE_H /* - * Implementation based on Chapter 7.4 of the Thread v1.0 Specification, - * available from the Thread Group http://threadgroup.org/ - * * 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. + * This file implements the Elliptic Curve variant of J-PAKE, + * as defined in Chapter 7.4 of the Thread v1.0 Specification, + * available to members of the Thread Group http://threadgroup.org/ * * 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. + * The payloads are serialized in a way suitable for use in TLS, but could + * also be use outside TLS. */ #include "ecp.h" @@ -84,7 +84,7 @@ typedef struct mbedtls_mpi s; /**< Pre-shared secret (passphrase) */ } mbedtls_ecjpake_context; -/* +/** * \brief Initialize a context * (just makes it ready for setup() or free()). * @@ -92,7 +92,7 @@ typedef struct */ void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx ); -/* +/** * \brief Set up a context for use * * \note Currently the only values for hash/curve allowed by the @@ -115,7 +115,7 @@ int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx, const unsigned char *secret, size_t len ); -/* +/** * \brief Generate and write the first round message * (TLS: contents of the Client/ServerHello extension, * excluding extension type and length bytes) @@ -134,8 +134,9 @@ 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 Generate and write the first round message + +/** + * \brief Read and process the first round message * (TLS: contents of the Client/ServerHello extension, * excluding extension type and length bytes) * @@ -150,9 +151,9 @@ int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx, const unsigned char *buf, size_t len ); -/* - * \brief Generate and write ClientECJPAKEParams - * (the contents for the ClientKeyExchange) +/** + * \brief Generate and write the second round message + * (TLS: contents of the Client/ServerKeyExchange) * * \param ctx Context to use * \param buf Buffer to write the contents to @@ -169,9 +170,9 @@ int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); -/* - * \brief Read and process ClientECJPAKEParams - * (the contents for the ClientKeyExchange) +/** + * \brief Read and process the second round message + * (TLS: contents of the Client/ServerKeyExchange) * * \param ctx Context to use * \param buf Pointer to the message @@ -181,11 +182,12 @@ int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx, * a negative error code otherwise */ int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx, - const unsigned char *buf, - size_t len ); + const unsigned char *buf, + size_t len ); -/* - * \brief Derive the Pre-Master Secret used by TLS +/** + * \brief Derive the shared secret + * (TLS: Pre-Master Secret) * * \param ctx * \param buf Buffer to write the contents to @@ -197,12 +199,12 @@ int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx, * \return 0 if successfull, * a negative error code otherwise */ -int mbedtls_ecjpake_tls_derive_pms( mbedtls_ecjpake_context *ctx, +int mbedtls_ecjpake_derive_secret( 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 Free a context's content * * \param ctx context to free diff --git a/library/ecjpake.c b/library/ecjpake.c index e09d74279..b0fda2013 100644 --- a/library/ecjpake.c +++ b/library/ecjpake.c @@ -647,7 +647,7 @@ cleanup: /* * Derive PMS (7.4.2.7 / 7.4.2.8) */ -int mbedtls_ecjpake_tls_derive_pms( mbedtls_ecjpake_context *ctx, +int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx, unsigned char *buf, size_t len, size_t *olen, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ) @@ -946,7 +946,7 @@ int mbedtls_ecjpake_self_test( int verbose ) TEST_ASSERT( mbedtls_ecjpake_read_round_two( &cli, buf, len ) == 0 ); - TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &cli, + TEST_ASSERT( mbedtls_ecjpake_derive_secret( &cli, pms, sizeof( pms ), &pmslen, ecjpake_lgc, NULL ) == 0 ); TEST_ASSERT( mbedtls_ecjpake_write_round_two( &cli, @@ -954,7 +954,7 @@ int mbedtls_ecjpake_self_test( int verbose ) TEST_ASSERT( mbedtls_ecjpake_read_round_two( &srv, buf, len ) == 0 ); - TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &srv, + TEST_ASSERT( mbedtls_ecjpake_derive_secret( &srv, buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 ); TEST_ASSERT( len == pmslen ); @@ -996,7 +996,7 @@ int mbedtls_ecjpake_self_test( int verbose ) sizeof( ecjpake_test_cli_kx ) ) == 0 ); /* Server derives PMS */ - TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &srv, + TEST_ASSERT( mbedtls_ecjpake_derive_secret( &srv, buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 ); TEST_ASSERT( len == sizeof( ecjpake_test_pms ) ); @@ -1005,7 +1005,7 @@ int mbedtls_ecjpake_self_test( int verbose ) memset( buf, 0, len ); /* Avoid interferences with next step */ /* Client derives PMS */ - TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &cli, + TEST_ASSERT( mbedtls_ecjpake_derive_secret( &cli, buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 ); TEST_ASSERT( len == sizeof( ecjpake_test_pms ) );