From ad3e1053031169b583d32ffd7ceab88bafc5ad3c Mon Sep 17 00:00:00 2001
From: kaleb-himes <kaleb@wolfssl.com>
Date: Tue, 19 Nov 2019 17:06:52 -0700
Subject: [PATCH 1/2] Add dox documentation for wc_ecc_make_key_ex

---
 doc/dox_comments/header_files/ecc.h | 70 ++++++++++++++++++++++-------
 1 file changed, 53 insertions(+), 17 deletions(-)

diff --git a/doc/dox_comments/header_files/ecc.h b/doc/dox_comments/header_files/ecc.h
index 0dec2a3ac..b720ba95f 100644
--- a/doc/dox_comments/header_files/ecc.h
+++ b/doc/dox_comments/header_files/ecc.h
@@ -55,35 +55,71 @@ int wc_ecc_make_key(WC_RNG* rng, int keysize, ecc_key* key);
 /*!
     \ingroup ECC
 
-    \brief Perform sanity checks on ecc key validity.
+    \brief Create an ECC key of specified size.
 
-    \return MP_OKAY Success, key is OK.
-    \return BAD_FUNC_ARG Returns if key is NULL.
-    \return ECC_INF_E Returns if wc_ecc_point_is_at_infinity returns 1.
+    \return MP_OKAY Success, key was created without issues.
+    \return BAD_FUNC_ARG Returns if key or rng structure is NULL.
+    \return INVALID_DEV_ID Returns if crypto callback set and bad device id.
+    \return ECC_BAD_ARG_E if keysize is invalid
+    \return ECC_CURVE_OID_E if invalid curve specified
 
-    \param key Pointer to key to check.
+    \param key Pointer to store the created key.
+    \param keysize size of key to be created in bytes (32-bytes = 256-bits)
+    \param rng Rng to be used in key creation
 
     _Example_
     \code
     ecc_key key;
+    int ret;
     WC_WC_RNG rng;
-    int check_result;
     wc_ecc_init(&key);
     wc_InitRng(&rng);
-    wc_ecc_make_key(&rng, 32, &key);
-    check_result = wc_ecc_check_key(&key);
+    ret = wc_ecc_make_key(&rng, 32, &key);
+    if (ret != MP_OKAY) {
+        // error handling
+    }
 
-    if (check_result == MP_OKAY)
-    {
-        // key check succeeded
-    }
-    else
-    {
-        // key check failed
-    }
     \endcode
 
-    \sa wc_ecc_point_is_at_infinity
+    \sa wc_ecc_make_key_ex
+*/
+WOLFSSL_API
+int wc_ecc_make_key_ex(WC_RNG* rng, int keysize, ecc_key* key, int curve_id);
+
+/*!
+    \ingroup ECC
+
+    \brief Create an ECC key of specified size.
+
+    \return MP_OKAY Success, key was created without issues.
+    \return BAD_FUNC_ARG Returns if key or rng structure is NULL.
+    \return INVALID_DEV_ID Returns if crypto callback set and bad device id.
+    \return ECC_BAD_ARG_E if keysize is invalid
+    \return ECC_CURVE_OID_E if invalid curve specified
+
+    \param key Pointer to store the created key.
+    \param keysize size of key to be created in bytes, set based on curveId
+    \param rng Rng to be used in key creation
+    \param curve_id Curve to use for key
+
+    _Example_
+    \code
+    ecc_key key;
+    int ret;
+    WC_WC_RNG rng;
+    wc_ecc_init(&key);
+    wc_InitRng(&rng);
+    int curveId = ECC_SECP521R1;
+    int keySize = wc_ecc_get_curve_size_from_id(curveId);
+    ret = wc_ecc_make_key(&rng, keySize, &key, curveId);
+    if (ret != MP_OKAY) {
+        // error handling
+    }
+
+    \endcode
+
+    \sa wc_ecc_make_key
+    \sa wc_ecc_get_curve_size_from_id
 */
 WOLFSSL_API
 int wc_ecc_check_key(ecc_key* key);

From 2607cf342933bc315802ea07f7ac88fcccd1b25e Mon Sep 17 00:00:00 2001
From: kaleb-himes <kaleb@wolfssl.com>
Date: Wed, 18 Dec 2019 10:55:20 -0700
Subject: [PATCH 2/2] Fix up based on peer feedback

---
 doc/dox_comments/header_files/ecc.h | 107 +++++++++++++++++-----------
 1 file changed, 66 insertions(+), 41 deletions(-)

diff --git a/doc/dox_comments/header_files/ecc.h b/doc/dox_comments/header_files/ecc.h
index b720ba95f..0299756fe 100644
--- a/doc/dox_comments/header_files/ecc.h
+++ b/doc/dox_comments/header_files/ecc.h
@@ -55,47 +55,36 @@ int wc_ecc_make_key(WC_RNG* rng, int keysize, ecc_key* key);
 /*!
     \ingroup ECC
 
-    \brief Create an ECC key of specified size.
+    \brief This function generates a new ecc_key and stores it in key.
 
-    \return MP_OKAY Success, key was created without issues.
-    \return BAD_FUNC_ARG Returns if key or rng structure is NULL.
-    \return INVALID_DEV_ID Returns if crypto callback set and bad device id.
-    \return ECC_BAD_ARG_E if keysize is invalid
-    \return ECC_CURVE_OID_E if invalid curve specified
-
-    \param key Pointer to store the created key.
-    \param keysize size of key to be created in bytes (32-bytes = 256-bits)
-    \param rng Rng to be used in key creation
-
-    _Example_
-    \code
-    ecc_key key;
-    int ret;
-    WC_WC_RNG rng;
-    wc_ecc_init(&key);
-    wc_InitRng(&rng);
-    ret = wc_ecc_make_key(&rng, 32, &key);
-    if (ret != MP_OKAY) {
-        // error handling
-    }
-
-    \endcode
-
-    \sa wc_ecc_make_key_ex
-*/
-WOLFSSL_API
-int wc_ecc_make_key_ex(WC_RNG* rng, int keysize, ecc_key* key, int curve_id);
-
-/*!
-    \ingroup ECC
-
-    \brief Create an ECC key of specified size.
-
-    \return MP_OKAY Success, key was created without issues.
-    \return BAD_FUNC_ARG Returns if key or rng structure is NULL.
-    \return INVALID_DEV_ID Returns if crypto callback set and bad device id.
-    \return ECC_BAD_ARG_E if keysize is invalid
-    \return ECC_CURVE_OID_E if invalid curve specified
+    \return 0 Returned on success.
+    \return ECC_BAD_ARG_E Returned if rng or key evaluate to NULL
+    \return BAD_FUNC_ARG Returned if the specified key size is not in the
+    correct range of supported keys
+    \return MEMORY_E Returned if there is an error allocating memory while
+    computing the ecc key
+    \return MP_INIT_E may be returned if there is an error while computing
+    the ecc key
+    \return MP_READ_E may be returned if there is an error while computing
+    the ecc key
+    \return MP_CMP_E may be returned if there is an error while computing the
+    ecc key
+    \return MP_INVMOD_E may be returned if there is an error while computing
+    the ecc key
+    \return MP_EXPTMOD_E may be returned if there is an error while computing
+    the ecc key
+    \return MP_MOD_E may be returned if there is an error while computing the
+    ecc key
+    \return MP_MUL_E may be returned if there is an error while computing the
+    ecc key
+    \return MP_ADD_E may be returned if there is an error while computing the
+    ecc key
+    \return MP_MULMOD_E may be returned if there is an error while computing
+    the ecc key
+    \return MP_TO_E may be returned if there is an error while computing the
+    ecc key
+    \return MP_MEM may be returned if there is an error while computing the
+    ecc key
 
     \param key Pointer to store the created key.
     \param keysize size of key to be created in bytes, set based on curveId
@@ -111,7 +100,7 @@ int wc_ecc_make_key_ex(WC_RNG* rng, int keysize, ecc_key* key, int curve_id);
     wc_InitRng(&rng);
     int curveId = ECC_SECP521R1;
     int keySize = wc_ecc_get_curve_size_from_id(curveId);
-    ret = wc_ecc_make_key(&rng, keySize, &key, curveId);
+    ret = wc_ecc_make_key_ex(&rng, keySize, &key, curveId);
     if (ret != MP_OKAY) {
         // error handling
     }
@@ -122,6 +111,42 @@ int wc_ecc_make_key_ex(WC_RNG* rng, int keysize, ecc_key* key, int curve_id);
     \sa wc_ecc_get_curve_size_from_id
 */
 WOLFSSL_API
+int wc_ecc_make_key_ex(WC_RNG* rng, int keysize, ecc_key* key, int curve_id);
+
+/*!
+    \ingroup ECC
+
+    \brief Perform sanity checks on ecc key validity.
+
+    \return MP_OKAY Success, key is OK.
+    \return BAD_FUNC_ARG Returns if key is NULL.
+    \return ECC_INF_E Returns if wc_ecc_point_is_at_infinity returns 1.
+
+    \param key Pointer to key to check.
+
+    _Example_
+    \code
+    ecc_key key;
+    WC_WC_RNG rng;
+    int check_result;
+    wc_ecc_init(&key);
+    wc_InitRng(&rng);
+    wc_ecc_make_key(&rng, 32, &key);
+    check_result = wc_ecc_check_key(&key);
+
+    if (check_result == MP_OKAY)
+    {
+        // key check succeeded
+    }
+    else
+    {
+        // key check failed
+    }
+    \endcode
+
+    \sa wc_ecc_point_is_at_infinity
+*/
+WOLFSSL_API
 int wc_ecc_check_key(ecc_key* key);
 
 /*!