Polish API and documentation
diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h
index 56bf397..59e80e5 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 @@
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 @@
*/
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 @@
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 @@
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 @@
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 (*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 @@
* 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 @@
* \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