Merge pull request #3047 from SparkiDev/curve448_dox

Add Doxygen documentation for Curve448/Ed448

doc/dox_comments/header_files/curve25519.h

@@ -1,33 +1,38 @@
 /*!
     \ingroup Curve25519
 
-    \brief This function generates a curve25519 key using the given random
+    \brief This function generates a Curve25519 key using the given random
     number generator, rng, of the size given (keysize), and stores it in
     the given curve25519_key structure. It should be called after the key
-    structure has been initialized through wc_curve25519_init.
+    structure has been initialized through wc_curve25519_init().
 
     \return 0 Returned on successfully generating the key and and storing
-    it in the given curve25519_key structure
+    it in the given curve25519_key structure.
-    \return ECC_BAD_ARG_E Returned if rng or key evaluate to NULL, or
+    \return ECC_BAD_ARG_E Returned if the input keysize does not correspond to
-    the input keysize does not correspond to the keysize for a
+    the keysize for a curve25519 key (32 bytes).
-    curve25519 key ( 32 bytes)
     \return RNG_FAILURE_E Returned if the rng internal status is not
-    DRBG_OK or if there is in generating the next random block with rng
+    DRBG_OK or if there is in generating the next random block with rng.
+    \return BAD_FUNC_ARG Returned if any of the input parameters passed in
+    are NULL.
 
-    \param rng pointer to the RNG object used to generate the ecc key
+    \param [in] rng Pointer to the RNG object used to generate the ecc key.
-    \param keysize size of the key to generate. Must be 32 bytes for curve25519
+    \param [in] keysize Size of the key to generate. Must be 32 bytes for
-    \param key pointer to the curve25519_key structure in which to
+    curve25519.
-    store the generated key
+    \param [in,out] key Pointer to the curve25519_key structure in which to
+    store the generated key.
 
     _Example_
     \code
+    int ret;
+
     curve25519_key key;
     wc_curve25519_init(&key); // initialize key
     WC_RNG rng;
     wc_InitRng(&rng); // initialize random number generator
 
-    if( wc_curve25519_make_key(&rng, 32, &key) != 0) {
+    ret = wc_curve25519_make_key(&rng, 32, &key);
-    	// making 25519 key
+    if (ret != 0) {
+        // error making Curve25519 key
     }
     \endcode
 
@@ -44,30 +49,32 @@ int wc_curve25519_make_key(WC_RNG* rng, int keysize, curve25519_key* key);
     buffer out and assigns the variable of the secret key to outlen. Only
     supports big endian.
 
-    \return 0 Returned on successfully computing a shared secret key
+    \return 0 Returned on successfully computing a shared secret key.
     \return BAD_FUNC_ARG Returned if any of the input parameters passed in
-    are NULL
+    are NULL.
     \return ECC_BAD_ARG_E Returned if the first bit of the public key is
-    set, to avoid implementation fingerprinting
+    set, to avoid implementation fingerprinting.
 
-    \param private_key pointer to the curve25519_key structure initialized
+    \param [in] private_key Pointer to the curve25519_key structure initialized
-    with the user’s private key
+    with the user’s private key.
-    \param public_key pointer to the  curve25519_key structure containing
+    \param [in] public_key Pointer to the  curve25519_key structure containing
-    the received public key
+    the received public key.
-    \param out pointer to a buffer in which to store the 32 byte computed
+    \param [out] out Pointer to a buffer in which to store the 32 byte computed
-    secret key
+    secret key.
-    \param outlen pointer in which to store the length written to the
+    \param [in,out] outlen Pointer in which to store the length written to the
-    output buffer
+    output buffer.
 
     _Example_
     \code
+    int ret;
+
     byte sharedKey[32];
     word32 keySz;
     curve25519_key privKey, pubKey;
     // initialize both keys
 
-    if ( wc_curve25519_shared_secret(&privKey, &pubKey, sharedKey,
+    ret = wc_curve25519_shared_secret(&privKey, &pubKey, sharedKey, &keySz);
-    &keySz) != 0 ) {
+    if (ret != 0) {
         // error generating shared key
     }
     \endcode
@@ -89,33 +96,36 @@ int wc_curve25519_shared_secret(curve25519_key* private_key,
     buffer out and assigns the variable of the secret key to outlen. Supports
     both big and little endian.
 
-    \return 0 Returned on successfully computing a shared secret key
+    \return 0 Returned on successfully computing a shared secret key.
     \return BAD_FUNC_ARG Returned if any of the input parameters passed in
-    are NULL
+    are NULL.
     \return ECC_BAD_ARG_E Returned if the first bit of the public key is set,
-    to avoid implementation fingerprinting
+    to avoid implementation fingerprinting.
 
-    \param private_key pointer to the curve25519_key structure initialized
+    \param [in] private_key Pointer to the curve25519_key structure initialized
-    with the user’s private key
+    with the user’s private key.
-    \param public_key pointer to the  curve25519_key structure containing
+    \param [in] public_key Pointer to the  curve25519_key structure containing
-    the received public key
+    the received public key.
-    \param out pointer to a buffer in which to store the 32 byte computed
+    \param [out] out Pointer to a buffer in which to store the 32 byte computed
-    secret key
+    secret key.
-    \param outlen pointer in which to store the length written to the output
+    \param pin,out] outlen Pointer in which to store the length written to the
-    buffer
+    output buffer.
-    \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
+    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
     form to use.
 
     _Example_
     \code
+    int ret;
+
     byte sharedKey[32];
     word32 keySz;
 
     curve25519_key privKey, pubKey;
     // initialize both keys
 
-    if ( wc_curve25519_shared_secret_ex(&privKey, &pubKey, sharedKey, &keySz,
+    ret = wc_curve25519_shared_secret_ex(&privKey, &pubKey, sharedKey, &keySz,
-    EC25519_BIG_ENDIAN) != 0 ) {
+             EC25519_BIG_ENDIAN);
+    if (ret != 0) {
         // error generating shared key
     }
     \endcode
@@ -132,14 +142,14 @@ int wc_curve25519_shared_secret_ex(curve25519_key* private_key,
 /*!
     \ingroup Curve25519
 
-    \brief This function initializes a curve25519 key. It should be called
+    \brief This function initializes a Curve25519 key. It should be called
-    before generating a key for the structure with wc_curve25519_init and
+    before generating a key for the structure.
-    before using the key to encrypt data.
 
     \return 0 Returned on successfully initializing the curve25519_key
-    structure
+    structure.
+    \return BAD_FUNC_ARG Returned when key is NULL.
 
-    \param key pointer to the curve25519_key structure to initialize
+    \param [in,out] key Pointer to the curve25519_key structure to initialize.
 
     _Example_
     \code
@@ -156,11 +166,9 @@ int wc_curve25519_init(curve25519_key* key);
 /*!
     \ingroup Curve25519
 
-    \brief This function frees a curve 25519 object.
+    \brief This function frees a Curve25519 object.
 
-    \return none No returns.
+    \param [in,out] key Pointer to the key object to free.
-
-    \param key pointer to the key object to free
 
     _Example_
     \code
@@ -180,24 +188,26 @@ void wc_curve25519_free(curve25519_key* key);
 
     \brief This function imports a curve25519 private key only. (Big endian).
 
-    \return 0 Success
+    \return 0 Returned on successfully importing private key.
     \return BAD_FUNC_ARG Returns if key or priv is null.
-    \return ECC_BAD_ARG_E Returns if privSz is not equal to
+    \return ECC_BAD_ARG_E Returns if privSz is not equal to CURVE25519_KEY_SIZE.
-    wc_curve25519_size(key).
 
-    \param priv Private key buffer
+    \param [in] priv Pointer to a buffer containing the private key to import.
-    \param privSz Size of private key buffer.
+    \param [in] privSz Length of the private key to import.
-    \param key The curve25519_key structure to store the private key.
+    \param [in,out] key Pointer to the structure in which to store the imported
+    key.
 
     _Example_
     \code
+    int ret;
+
     byte priv[] = { Contents of private key };
     curve25519_key key;
     wc_curve25519_init(&key);
 
-    if(wc_curve25519_import_private(priv, sizeof(priv), &key) != 0)
+    ret = wc_curve25519_import_private(priv, sizeof(priv), &key);
-    {
+    if (ret != 0) {
-        // Some error was thrown
+        // error importing keys
     }
     \endcode
 
@@ -213,33 +223,35 @@ int wc_curve25519_import_private(const byte* priv, word32 privSz,
 
     \brief curve25519 private key import only. (Big or Little endian).
 
-    \return 0 Success
+    \return 0 Returned on successfully importing private key.
-    \return  Returns if key or priv is null.
+    \return BAD_FUNC_ARG Returns if key or priv is null.
-    \return ECC_BAD_ARG_E Returns if privSz is not equal to
+    \return ECC_BAD_ARG_E Returns if privSz is not equal to CURVE25519_KEY_SIZE.
-    wc_curve25519_size(key).
 
-    \param priv Buffer for private key.
+    \param [in] priv Pointer to a buffer containing the private key to import.
-    \param privSz Size of private key buffer.
+    \param [in] privSz Length of the private key to import.
-    \param key The curve25519_key structure to store the private key.
+    \param [in,out] key Pointer to the structure in which to store the imported
-    \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to
+    key.
+    \param [in]  endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to
     set which form to use.
 
     _Example_
     \code
+    int ret;
+
     byte priv[] = { // Contents of private key };
     curve25519_key key;
     wc_curve25519_init(&key);
 
-    if(wc_curve25519_import_private_ex(priv, sizeof(priv), &key,
+    ret = wc_curve25519_import_private_ex(priv, sizeof(priv), &key,
-    EC25519_BIG_ENDIAN) != 0)
+            EC25519_BIG_ENDIAN);
-    {
+    if (ret != 0) {
-       // Some error was thrown
+        // error importing keys
     }
 
     \endcode
 
     \sa wc_curve25519_import_private
-    \sa wc_curbe25519_size
+    \sa wc_curve25519_size
 */
 WOLFSSL_API
 int wc_curve25519_import_private_ex(const byte* priv, word32 privSz,
@@ -252,15 +264,16 @@ int wc_curve25519_import_private_ex(const byte* priv, word32 privSz,
     curve25519_key structure.  Big endian only.
 
     \return 0 Returned on importing into the curve25519_key structure
-    \return ECC_BAD_ARG_E Returned if any of the input parameters
+    \return BAD_FUNC_ARG Returns if any of the input parameters are null.
-    are NULL, or the input key’s key size does not match the public
+    \return ECC_BAD_ARG_E Returned if the input key’s key size does not match
-    or private key sizes
+    the public or private key sizes.
 
-    \param priv pointer to a buffer containing the private key to import
+    \param [in] priv Pointer to a buffer containing the private key to import.
-    \param privSz length of the private key to import
+    \param [in] privSz Length of the private key to import.
-    \param pub pointer to a buffer containing the public key to import
+    \param [in] pub Pointer to a buffer containing the public key to import.
-    \param pubSz length of the public key to import
+    \param [in] pubSz Length of the public key to import.
-    \param key pointer to the structure in which to store the imported keys
+    \param [in,out] key Pointer to the structure in which to store the imported
+    keys.
 
     _Example_
     \code
@@ -296,15 +309,17 @@ int wc_curve25519_import_private_raw(const byte* priv, word32 privSz,
     \brief This function imports a public-private key pair into a curve25519_key structure.  Supports both big and little endian.
 
     \return 0 Returned on importing into the curve25519_key structure
-    \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL,
+    \return BAD_FUNC_ARG Returns if any of the input parameters are null.
-    or the input key’s key size does not match the public or private key sizes
+    \return ECC_BAD_ARG_E Returned if or the input key’s key size does not match
+    the public or private key sizes
 
-    \param priv pointer to a buffer containing the private key to import
+    \param [in] priv Pointer to a buffer containing the private key to import.
-    \param privSz length of the private key to import
+    \param [in] privSz Length of the private key to import.
-    \param pub pointer to a buffer containing the public key to import
+    \param [in] pub Pointer to a buffer containing the public key to import.
-    \param pubSz length of the public key to import
+    \param [in] pubSz Length of the public key to import.
-    \param key pointer to the structure in which to store the imported keys
+    \param [in,out] key Pointer to the structure in which to store the imported
-    \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set
+    keys.
+    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set
     which form to use.
 
     _Example_
@@ -328,7 +343,7 @@ int wc_curve25519_import_private_raw(const byte* priv, word32 privSz,
     \sa wc_curve25519_init
     \sa wc_curve25519_make_key
     \sa wc_curve25519_import_public
-    \sa wc_curve25519_export_private_rawm
+    \sa wc_curve25519_export_private_raw
     \sa wc_curve25519_import_private_raw
 */
 WOLFSSL_API
@@ -344,13 +359,14 @@ int wc_curve25519_import_private_raw_ex(const byte* priv, word32 privSz,
     of the exported key. Big Endian only.
 
     \return 0 Returned on successfully exporting the private key from the
-    curve25519_key structure
+    curve25519_key structure.
     \return BAD_FUNC_ARG Returned if any input parameters are NULL.
     \return ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.
 
-    \param key pointer to the structure from which to export the key
+    \param [in] key Pointer to the structure from which to export the key.
-    \param out pointer to the buffer in which to store the exported key
+    \param [out] out Pointer to the buffer in which to store the exported key.
-    \param outLen will store the bytes written to the output buffer
+    \param [in,out] outLen On in, is the size of the out in bytes.
+    On out, will store the bytes written to the output buffer.
 
     _Example_
     \code
@@ -384,14 +400,15 @@ int wc_curve25519_export_private_raw(curve25519_key* key, byte* out,
     of the exported key.  Can specify whether it's big or little endian.
 
     \return 0 Returned on successfully exporting the private key from the
-    curve25519_key structure
+    curve25519_key structure.
     \return BAD_FUNC_ARG Returned if any input parameters are NULL.
     \return ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.
 
-    \param key pointer to the structure from which to export the key
+    \param [in] key Pointer to the structure from which to export the key.
-    \param out pointer to the buffer in which to store the exported key
+    \param [out] out Pointer to the buffer in which to store the exported key.
-    \param outLen will store the bytes written to the output buffer
+    \param [in,out] outLen On in, is the size of the out in bytes.
-    \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
+    On out, will store the bytes written to the output buffer.
+    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
     form to use.
 
     _Example_
@@ -426,16 +443,15 @@ int wc_curve25519_export_private_raw_ex(curve25519_key* key, byte* out,
     stores it in the  curve25519_key structure.
 
     \return 0 Returned on successfully importing the public key into the
-    curve25519_key structure
+    curve25519_key structure.
-    \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL,
+    \return ECC_BAD_ARG_E Returned if the inLen parameter does not match the key
-    or if the inLen
+    size of the key structure.
-parameter does not match the key size of the key structure.
     \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
 
-    \param in pointer to the buffer containing the public key to import
+    \param [in] in Pointer to the buffer containing the public key to import.
-    \param inLen length of the public key to import
+    \param [in] inLen Length of the public key to import.
-    \param key pointer to the curve25519_key structure in which to store
+    \param [in,out] key Pointer to the curve25519_key structure in which to
-    the key
+    store the key.
 
     _Example_
     \code
@@ -449,14 +465,16 @@ parameter does not match the key size of the key structure.
 
     ret = wc_curve25519_import_public(pub,sizeof(pub), &key);
     if (ret != 0) {
-	    // error exporting key
+        // error importing key
     }
     \endcode
 
     \sa wc_curve25519_init
     \sa wc_curve25519_export_public
     \sa wc_curve25519_import_private_raw
-    \sa wc_curve25519_public_ex
+    \sa wc_curve25519_import_public_ex
+    \sa wc_curve25519_check_public
+    \sa wc_curve25519_size
 */
 WOLFSSL_API
 int wc_curve25519_import_public(const byte* in, word32 inLen,
@@ -468,22 +486,23 @@ int wc_curve25519_import_public(const byte* in, word32 inLen,
     \brief This function imports a public key from the given in buffer and
     stores it in the  curve25519_key structure.
 
-    \brief 0 Returned on successfully importing the public key into the
+    \return 0 Returned on successfully importing the public key into the
-    curve25519_key structure
+    curve25519_key structure.
-    \brief ECC_BAD_ARG_E Returned if the inLen parameter does not match the
+    \return ECC_BAD_ARG_E Returned if the inLen parameter does not match the
-    key size of the key structure
+    key size of the key structure.
-    \brief BAD_FUNC_ARG Returned if any of the input parameters are NULL.
+    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
 
-    \param in pointer to the buffer containing the public key to import
+    \param [in] in Pointer to the buffer containing the public key to import.
-    \param inLen length of the public key to import
+    \param [in] inLen Length of the public key to import.
-    \param key pointer to the curve25519_key structure in which to store
+    \param [in,out] key Pointer to the curve25519_key structure in which to
-    the key
+    store the key.
-    \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
+    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
     form to use.
 
     _Example_
     \code
     int ret;
+
     byte pub[32];
     // initialize pub with public key
     curve25519_key key;
@@ -492,7 +511,7 @@ int wc_curve25519_import_public(const byte* in, word32 inLen,
     ret = wc_curve25519_import_public_ex(pub, sizeof(pub), &key,
             EC25519_BIG_ENDIAN);
     if (ret != 0) {
-    	// error exporting key
+        // error importing key
     }
     \endcode
 
@@ -500,7 +519,8 @@ int wc_curve25519_import_public(const byte* in, word32 inLen,
     \sa wc_curve25519_export_public
     \sa wc_curve25519_import_private_raw
     \sa wc_curve25519_import_public
-    \sa wc_25519_size
+    \sa wc_curve25519_check_public
+    \sa wc_curve25519_size
 */
 WOLFSSL_API
 int wc_curve25519_import_public_ex(const byte* in, word32 inLen,
@@ -509,23 +529,63 @@ int wc_curve25519_import_public_ex(const byte* in, word32 inLen,
 /*!
     \ingroup Curve25519
 
-    \brief This function exports a public key from the given key structure and
+    \brief This function checks that a public key buffer holds a valid
-    stores the result in the out buffer. Big endian only.
+    Curve25519 key value given the endian ordering.
 
-    \return 0 Returned on successfully exporting the public key from the
+    \return 0 Returned when the public key value is valid.
-    curve25519_key structure
+    \return ECC_BAD_ARG_E Returned if the public key value is not valid.
-    \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL
+    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
 
-    \param key pointer to the curve25519_key structure in from which to
+    \param [in] pub Pointer to the buffer containing the public key to check.
-    export the key
+    \param [in] pubLen Length of the public key to check.
-    \param out pointer to the buffer in which to store the public key
+    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
-    \param outLen will store the bytes written to the output buffer
+    form to use.
 
     _Example_
     \code
     int ret;
+
+    byte pub[] = { Contents of public key };
+
+    ret = wc_curve25519_check_public_ex(pub, sizeof(pub), EC25519_BIG_ENDIAN);
+    if (ret != 0) {
+        // error importing key
+    }
+    \endcode
+
+    \sa wc_curve25519_init
+    \sa wc_curve25519_import_public
+    \sa wc_curve25519_import_public_ex
+    \sa wc_curve25519_size
+*/
+WOLFSSL_API
+int wc_curve25519_check_public(const byte* pub, word32 pubSz, int endian);
+
+/*!
+    \ingroup Curve25519
+
+    \brief This function exports a public key from the given key structure and
+    stores the result in the out buffer. Big endian only.
+
+    \return 0 Returned on successfully exporting the public key from the
+    curve25519_key structure.
+    \return ECC_BAD_ARG_E Returned if outLen is less than
+    CURVE25519_PUB_KEY_SIZE.
+    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
+
+    \param [in] key Pointer to the curve25519_key structure in from which to
+    export the key.
+    \param [out] out Pointer to the buffer in which to store the public key.
+    \param [in,out] outLen On in, is the size of the out in bytes.
+    On out, will store the bytes written to the output buffer.
+
+    _Example_
+    \code
+    int ret;
+
     byte pub[32];
     int pubSz;
+
     curve25519_key key;
     // initialize and make key
     ret = wc_curve25519_export_public(&key, pub, &pubSz);
@@ -548,14 +608,17 @@ int wc_curve25519_export_public(curve25519_key* key, byte* out, word32* outLen);
     stores the result in the out buffer. Supports both big and little endian.
 
     \return 0 Returned on successfully exporting the public key from the
-    curve25519_key structure
+    curve25519_key structure.
-    \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL
+    \return ECC_BAD_ARG_E Returned if outLen is less than
+    CURVE25519_PUB_KEY_SIZE.
+    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
 
-    \param key pointer to the curve25519_key structure in from which to
+    \param [in] key Pointer to the curve25519_key structure in from which to
-    export the key
+    export the key.
-    \param out pointer to the buffer in which to store the public key
+    \param [out] out Pointer to the buffer in which to store the public key.
-    \param outLen will store the bytes written to the output buffer
+    \param [in,out] outLen On in, is the size of the out in bytes.
-    \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
+    On out, will store the bytes written to the output buffer.
+    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
     form to use.
 
     _Example_
@@ -564,6 +627,7 @@ int wc_curve25519_export_public(curve25519_key* key, byte* out, word32* outLen);
 
     byte pub[32];
     int pubSz;
+
     curve25519_key key;
     // initialize and make key
 
@@ -584,21 +648,27 @@ int wc_curve25519_export_public_ex(curve25519_key* key, byte* out,
 /*!
     \ingroup Curve25519
 
-    \brief Export curve25519 key pair.  Big endian only.
+    \brief Export Curve25519 key pair.  Big endian only.
 
-    \return 0 Success
+    \return 0 Returned on successfully exporting the key pair from the
+    curve25519_key structure.
     \return BAD_FUNC_ARG Returned if any input parameters are NULL.
-    \return ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.
+    \return ECC_BAD_ARG_E Returned if privSz is less than CURVE25519_KEY_SIZE or
+    pubSz is less than CURVE25519_PUB_KEY_SIZE.
 
-    \param key Description
+    \param [in] key Pointer to the curve448_key structure in from which to
-    \param priv Private key buffer.
+    export the key pair.
-    \param privSz Size of private key buffer.
+    \param [out] priv Pointer to the buffer in which to store the private key.
-    \param pub Public key buffer.
+    \param [in,out] privSz On in, is the size of the priv buffer in bytes.
-    \param pubSz Size of public key buffer.
+    On out, will store the bytes written to the priv buffer.
+    \param [out] pub Pointer to the buffer in which to store the public key.
+    \param [in,out] pubSz On in, is the size of the pub buffer in bytes.
+    On out, will store the bytes written to the pub buffer.
 
     _Example_
     \code
     int ret;
+
     byte pub[32];
     byte priv[32];
     int pubSz;
@@ -615,7 +685,6 @@ int wc_curve25519_export_public_ex(curve25519_key* key, byte* out,
 
     \sa wc_curve25519_export_key_raw_ex
     \sa wc_curve25519_export_private_raw
-    \sa wc_curve25519_export_public_raw
 */
 WOLFSSL_API
 int wc_curve25519_export_key_raw(curve25519_key* key,
@@ -627,16 +696,21 @@ int wc_curve25519_export_key_raw(curve25519_key* key,
 
     \brief Export curve25519 key pair.  Big or little endian.
 
-    \return 0 Success
+    \return 0 Returned on successfully exporting the key pair from the
+    curve25519_key structure.
     \return BAD_FUNC_ARG Returned if any input parameters are NULL.
-    \return ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.
+    \return ECC_BAD_ARG_E Returned if privSz is less than CURVE25519_KEY_SIZE or
+    pubSz is less than CURVE25519_PUB_KEY_SIZE.
 
-    \param key Description
+    \param [in] key Pointer to the curve448_key structure in from which to
-    \param priv Private key buffer.
+    export the key pair.
-    \param privSz Size of private key buffer.
+    \param [out] priv Pointer to the buffer in which to store the private key.
-    \param pub Public key buffer.
+    \param [in,out] privSz On in, is the size of the priv buffer in bytes.
-    \param pubSz Size of public key buffer.
+    On out, will store the bytes written to the priv buffer.
-    \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
+    \param [out] pub Pointer to the buffer in which to store the public key.
+    \param [in,out] pubSz On in, is the size of the pub buffer in bytes.
+    On out, will store the bytes written to the pub buffer.
+    \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
     form to use.
 
     _Example_
@@ -677,14 +751,16 @@ int wc_curve25519_export_key_raw_ex(curve25519_key* key,
     returns the size of the key.
     \return 0 Returned if key is NULL
 
-    \param key pointer to the curve25519_key structure in for which to
+    \param [in] key Pointer to the curve25519_key structure in for which to
-    determine the key size
+    determine the key size.
 
     _Example_
     \code
+    int keySz;
+
     curve25519_key key;
     // initialize and make key
-    int keySz;
+
     keySz = wc_curve25519_size(&key);
     \endcode
 

doc/dox_comments/header_files/curve448.h

@@ -0,0 +1,768 @@
+/*!
+    \ingroup Curve448
+
+    \brief This function generates a Curve448 key using the given random
+    number generator, rng, of the size given (keysize), and stores it in
+    the given curve448_key structure. It should be called after the key
+    structure has been initialized through wc_curve448_init().
+
+    \return 0 Returned on successfully generating the key and and storing
+    it in the given curve448_key structure.
+    \return ECC_BAD_ARG_E Returned if the input keysize does not correspond to
+    the keysize for a curve448 key (56 bytes).
+    \return RNG_FAILURE_E Returned if the rng internal status is not
+    DRBG_OK or if there is in generating the next random block with rng.
+    \return BAD_FUNC_ARG Returned if any of the input parameters passed in
+    are NULL.
+
+    \param [in] rng Pointer to the RNG object used to generate the ecc key.
+    \param [in] keysize Size of the key to generate. Must be 56 bytes for
+    curve448.
+    \param [in,out] key Pointer to the curve448_key structure in which to
+    store the generated key.
+
+    _Example_
+    \code
+    int ret;
+
+    curve448_key key;
+    wc_curve448_init(&key); // initialize key
+    WC_RNG rng;
+    wc_InitRng(&rng); // initialize random number generator
+
+    ret = wc_curve448_make_key(&rng, 56, &key);
+    if (ret != 0) {
+        // error making Curve448 key
+    }
+    \endcode
+
+    \sa wc_curve448_init
+*/
+WOLFSSL_API
+int wc_curve448_make_key(WC_RNG* rng, int keysize, curve448_key* key);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function computes a shared secret key given a secret private
+    key and a received public key. It stores the generated secret key in the
+    buffer out and assigns the variable of the secret key to outlen. Only
+    supports big endian.
+
+    \return 0 Returned on successfully computing a shared secret key
+    \return BAD_FUNC_ARG Returned if any of the input parameters passed in
+    are NULL
+
+    \param [in] private_key Pointer to the curve448_key structure initialized
+    with the user’s private key.
+    \param [in] public_key Pointer to the  curve448_key structure containing
+    the received public key.
+    \param [out] out Pointer to a buffer in which to store the 56 byte computed
+    secret key.
+    \param [in,out] outlen Pointer in which to store the length written to the
+    output buffer.
+
+    _Example_
+    \code
+    int ret;
+
+    byte sharedKey[56];
+    word32 keySz;
+    curve448_key privKey, pubKey;
+    // initialize both keys
+
+    ret = wc_curve448_shared_secret(&privKey, &pubKey, sharedKey, &keySz);
+    if (ret != 0) {
+        // error generating shared key
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_make_key
+    \sa wc_curve448_shared_secret_ex
+*/
+WOLFSSL_API
+int wc_curve448_shared_secret(curve448_key* private_key,
+                                curve448_key* public_key,
+                                byte* out, word32* outlen);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function computes a shared secret key given a secret private
+    key and a received public key. It stores the generated secret key in the
+    buffer out and assigns the variable of the secret key to outlen. Supports
+    both big and little endian.
+
+    \return 0 Returned on successfully computing a shared secret key.
+    \return BAD_FUNC_ARG Returned if any of the input parameters passed in
+    are NULL.
+
+    \param [in] private_key Pointer to the curve448_key structure initialized
+    with the user’s private key.
+    \param [in] public_key Pointer to the  curve448_key structure containing
+    the received public key.
+    \param [out] out Pointer to a buffer in which to store the 56 byte computed
+    secret key.
+    \param [in,out] outlen Pointer in which to store the length written to the
+    output buffer.
+    \param [in] endian EC448_BIG_ENDIAN or EC448_LITTLE_ENDIAN to set which
+    form to use.
+
+    _Example_
+    \code
+    int ret;
+
+    byte sharedKey[56];
+    word32 keySz;
+
+    curve448_key privKey, pubKey;
+    // initialize both keys
+
+    ret = wc_curve448_shared_secret_ex(&privKey, &pubKey, sharedKey, &keySz,
+            EC448_BIG_ENDIAN);
+    if (ret != 0) {
+        // error generating shared key
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_make_key
+    \sa wc_curve448_shared_secret
+*/
+WOLFSSL_API
+int wc_curve448_shared_secret_ex(curve448_key* private_key,
+                                   curve448_key* public_key,
+                                   byte* out, word32* outlen, int endian);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function initializes a Curve448 key. It should be called
+    before generating a key for the structure.
+
+    \return 0 Returned on successfully initializing the curve448_key structure.
+    \return BAD_FUNC_ARG Returned when key is NULL.
+
+    \param [in,out] key Pointer to the curve448_key structure to initialize.
+
+    _Example_
+    \code
+    curve448_key key;
+    wc_curve448_init(&key); // initialize key
+    // make key and proceed to encryption
+    \endcode
+
+    \sa wc_curve448_make_key
+*/
+WOLFSSL_API
+int wc_curve448_init(curve448_key* key);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function frees a Curve448 object.
+
+    \param [in,out] key Pointer to the key object to free.
+
+    _Example_
+    \code
+    curve448_key privKey;
+    // initialize key, use it to generate shared secret key
+    wc_curve448_free(&privKey);
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_make_key
+*/
+WOLFSSL_API
+void wc_curve448_free(curve448_key* key);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function imports a curve448 private key only. (Big endian).
+
+    \return 0 Returned on successfully importing private key.
+    \return BAD_FUNC_ARG Returns if key or priv is null.
+    \return ECC_BAD_ARG_E Returns if privSz is not equal to CURVE448_KEY_SIZE.
+
+    \param [in] priv Pointer to a buffer containing the private key to import.
+    \param [in] privSz Length of the private key to import.
+    \param [in,out] key Pointer to the structure in which to store the imported
+    key.
+
+    _Example_
+    \code
+    int ret;
+
+    byte priv[] = { Contents of private key };
+    curve448_key key;
+    wc_curve448_init(&key);
+
+    ret = wc_curve448_import_private(priv, sizeof(priv), &key);
+    if (ret != 0) {
+        // error importing key
+    }
+    \endcode
+
+    \sa wc_curve448_import_private_ex
+    \sa wc_curve448_size
+*/
+WOLFSSL_API
+int wc_curve448_import_private(const byte* priv, word32 privSz,
+                                 curve448_key* key);
+
+/*!
+    \ingroup Curve448
+
+    \brief curve448 private key import only. (Big or Little endian).
+
+    \return 0 Returned on successfully importing private key.
+    \return BAD_FUNC_ARG Returns if key or priv is null.
+    \return ECC_BAD_ARG_E Returns if privSz is not equal to CURVE448_KEY_SIZE.
+
+    \param [in] priv Pointer to a buffer containing the private key to import.
+    \param [in] privSz Length of the private key to import.
+    \param [in,out] key Pointer to the structure in which to store the imported
+    key.
+    \param [in] endian EC448_BIG_ENDIAN or EC448_LITTLE_ENDIAN to
+    set which form to use.
+
+    _Example_
+    \code
+    int ret;
+
+    byte priv[] = { // Contents of private key };
+    curve448_key key;
+    wc_curve448_init(&key);
+
+    ret = wc_curve448_import_private_ex(priv, sizeof(priv), &key,
+            EC448_BIG_ENDIAN);
+    if (ret != 0) {
+        // error importing key
+    }
+
+    \endcode
+
+    \sa wc_curve448_import_private
+    \sa wc_curve448_size
+*/
+WOLFSSL_API
+int wc_curve448_import_private_ex(const byte* priv, word32 privSz,
+                                    curve448_key* key, int endian);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function imports a public-private key pair into a
+    curve448_key structure.  Big endian only.
+
+    \return 0 Returned on importing into the curve448_key structure.
+    \return BAD_FUNC_ARG Returns if any of the input parameters are null.
+    \return ECC_BAD_ARG_E Returned if the input key’s key size does not match
+    the public or private key sizes.
+
+    \param [in] priv Pointer to a buffer containing the private key to import.
+    \param [in] privSz Length of the private key to import.
+    \param [in] pub Pointer to a buffer containing the public key to import.
+    \param [in] pubSz Length of the public key to import.
+    \param [in,out] key Pointer to the structure in which to store the imported
+    keys
+
+    _Example_
+    \code
+    int ret;
+
+    byte priv[56];
+    byte pub[56];
+    // initialize with public and private keys
+    curve448_key key;
+
+    wc_curve448_init(&key);
+    // initialize key
+
+    ret = wc_curve448_import_private_raw(&priv, sizeof(priv), pub, sizeof(pub),
+            &key);
+    if (ret != 0) {
+        // error importing keys
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_make_key
+    \sa wc_curve448_import_public
+    \sa wc_curve448_export_private_raw
+*/
+WOLFSSL_API
+int wc_curve448_import_private_raw(const byte* priv, word32 privSz,
+                            const byte* pub, word32 pubSz, curve448_key* key);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function imports a public-private key pair into a curve448_key structure.  Supports both big and little endian.
+
+    \return 0 Returned on importing into the curve448_key structure.
+    \return BAD_FUNC_ARG Returns if any of the input parameters are null.
+    \return ECC_BAD_ARG_E Returned if the input key’s key size does not match
+    the public or private key sizes.
+
+    \param [in] priv Pointer to a buffer containing the private key to import.
+    \param [in] privSz Length of the private key to import.
+    \param [in] pub Pointer to a buffer containing the public key to import.
+    \param [in] pubSz Length of the public key to import.
+    \param [in,out] key Pointer to the structure in which to store the imported
+    keys.
+    \param [in]  endian EC448_BIG_ENDIAN or EC448_LITTLE_ENDIAN to set
+    which form to use.
+
+    _Example_
+    \code
+    int ret;
+
+    byte priv[56];
+    byte pub[56];
+    // initialize with public and private keys
+    curve448_key key;
+
+    wc_curve448_init(&key);
+    // initialize key
+
+    ret = wc_curve448_import_private_raw_ex(&priv, sizeof(priv), pub,
+            sizeof(pub), &key, EC448_BIG_ENDIAN);
+    if (ret != 0) {
+        // error importing keys
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_make_key
+    \sa wc_curve448_import_public
+    \sa wc_curve448_export_private_raw
+    \sa wc_curve448_import_private_raw
+*/
+WOLFSSL_API
+int wc_curve448_import_private_raw_ex(const byte* priv, word32 privSz,
+                                        const byte* pub, word32 pubSz,
+                                        curve448_key* key, int endian);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function exports a private key from a curve448_key structure
+    and stores it in the given out buffer. It also sets outLen to be the size
+    of the exported key. Big Endian only.
+
+    \return 0 Returned on successfully exporting the private key from the
+    curve448_key structure.
+    \return BAD_FUNC_ARG Returned if any input parameters are NULL.
+    \return ECC_BAD_ARG_E Returned if wc_curve448_size() is not equal to key.
+
+    \param [in] key Pointer to the structure from which to export the key.
+    \param [out] out Pointer to the buffer in which to store the exported key.
+    \param [in,out] outLen On in, is the size of the out in bytes.
+    On out, will store the bytes written to the output buffer.
+
+    _Example_
+    \code
+    int ret;
+    byte priv[56];
+    int privSz;
+
+    curve448_key key;
+    // initialize and make key
+
+    ret = wc_curve448_export_private_raw(&key, priv, &privSz);
+    if (ret != 0) {
+        // error exporting key
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_make_key
+    \sa wc_curve448_import_private_raw
+    \sa wc_curve448_export_private_raw_ex
+*/
+WOLFSSL_API
+int wc_curve448_export_private_raw(curve448_key* key, byte* out,
+                                     word32* outLen);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function exports a private key from a curve448_key structure
+    and stores it in the given out buffer. It also sets outLen to be the size
+    of the exported key.  Can specify whether it's big or little endian.
+
+    \return 0 Returned on successfully exporting the private key from the
+    curve448_key structure.
+    \return BAD_FUNC_ARG Returned if any input parameters are NULL.
+    \return ECC_BAD_ARG_E Returned if wc_curve448_size() is not equal to key.
+
+    \param [in] key Pointer to the structure from which to export the key.
+    \param [out] out Pointer to the buffer in which to store the exported key.
+    \param [in,out] outLen On in, is the size of the out in bytes.
+    On out, will store the bytes written to the output buffer.
+    \param [in] endian EC448_BIG_ENDIAN or EC448_LITTLE_ENDIAN to set which
+    form to use.
+
+    _Example_
+    \code
+    int ret;
+
+    byte priv[56];
+    int privSz;
+    curve448_key key;
+    // initialize and make key
+    ret = wc_curve448_export_private_raw_ex(&key, priv, &privSz,
+            EC448_BIG_ENDIAN);
+    if (ret != 0) {
+        // error exporting key
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_make_key
+    \sa wc_curve448_import_private_raw
+    \sa wc_curve448_export_private_raw
+    \sa wc_curve448_size
+*/
+WOLFSSL_API
+int wc_curve448_export_private_raw_ex(curve448_key* key, byte* out,
+                                        word32* outLen, int endian);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function imports a public key from the given in buffer and
+    stores it in the  curve448_key structure.
+
+    \return 0 Returned on successfully importing the public key into the
+    curve448_key structure.
+    \return ECC_BAD_ARG_E Returned if the inLen parameter does not match the key
+    size of the key structure.
+    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
+
+    \param [in] in Pointer to the buffer containing the public key to import.
+    \param [in] inLen Length of the public key to import.
+    \param [in,out] key Pointer to the curve448_key structure in which to store
+    the key.
+
+    _Example_
+    \code
+    int ret;
+
+    byte pub[56];
+    // initialize pub with public key
+
+    curve448_key key;
+    // initialize key
+
+    ret = wc_curve448_import_public(pub,sizeof(pub), &key);
+    if (ret != 0) {
+        // error importing key
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_export_public
+    \sa wc_curve448_import_private_raw
+    \sa wc_curve448_import_public_ex
+    \sa wc_curve448_check_public
+    \sa wc_curve448_size
+*/
+WOLFSSL_API
+int wc_curve448_import_public(const byte* in, word32 inLen,
+                                curve448_key* key);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function imports a public key from the given in buffer and
+    stores it in the  curve448_key structure.
+
+    \return 0 Returned on successfully importing the public key into the
+    curve448_key structure.
+    \return ECC_BAD_ARG_E Returned if the inLen parameter does not match the
+    key size of the key structure.
+    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
+
+    \param [in] in Pointer to the buffer containing the public key to import.
+    \param [in] inLen Length of the public key to import.
+    \param [in,out] key Pointer to the curve448_key structure in which to store
+    the key.
+    \param [in] endian EC448_BIG_ENDIAN or EC448_LITTLE_ENDIAN to set which
+    form to use.
+
+    _Example_
+    \code
+    int ret;
+
+    byte pub[56];
+    // initialize pub with public key
+    curve448_key key;
+    // initialize key
+
+    ret = wc_curve448_import_public_ex(pub, sizeof(pub), &key,
+            EC448_BIG_ENDIAN);
+    if (ret != 0) {
+        // error importing key
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_export_public
+    \sa wc_curve448_import_private_raw
+    \sa wc_curve448_import_public
+    \sa wc_curve448_check_public
+    \sa wc_curve448_size
+*/
+WOLFSSL_API
+int wc_curve448_import_public_ex(const byte* in, word32 inLen,
+                                   curve448_key* key, int endian);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function checks that a public key buffer holds a valid
+    Curve448 key value given the endian ordering.
+
+    \return 0 Returned when the public key value is valid.
+    \return ECC_BAD_ARG_E Returned if the public key value is not valid.
+    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
+
+    \param [in] pub Pointer to the buffer containing the public key to check.
+    \param [in] pubLen Length of the public key to check.
+    \param [in] endian EC448_BIG_ENDIAN or EC448_LITTLE_ENDIAN to set which
+    form to use.
+
+    _Example_
+    \code
+    int ret;
+
+    byte pub[] = { Contents of public key };
+
+    ret = wc_curve448_check_public_ex(pub, sizeof(pub), EC448_BIG_ENDIAN);
+    if (ret != 0) {
+        // error importing key
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_import_public
+    \sa wc_curve448_import_public_ex
+    \sa wc_curve448_size
+*/
+WOLFSSL_API
+int wc_curve448_check_public(const byte* pub, word32 pubSz, int endian);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function exports a public key from the given key structure and
+    stores the result in the out buffer. Big endian only.
+
+    \return 0 Returned on successfully exporting the public key from the
+    curve448_key structure.
+    \return ECC_BAD_ARG_E Returned if outLen is less than CURVE448_PUB_KEY_SIZE.
+    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
+
+    \param [in] key Pointer to the curve448_key structure in from which to
+    export the key.
+    \param [out] out Pointer to the buffer in which to store the public key.
+    \param [in,out] outLen On in, is the size of the out in bytes.
+    On out, will store the bytes written to the output buffer.
+
+    _Example_
+    \code
+    int ret;
+
+    byte pub[56];
+    int pubSz;
+
+    curve448_key key;
+    // initialize and make key
+
+    ret = wc_curve448_export_public(&key, pub, &pubSz);
+    if (ret != 0) {
+        // error exporting key
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_export_private_raw
+    \sa wc_curve448_import_public
+*/
+WOLFSSL_API
+int wc_curve448_export_public(curve448_key* key, byte* out, word32* outLen);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function exports a public key from the given key structure and
+    stores the result in the out buffer. Supports both big and little endian.
+
+    \return 0 Returned on successfully exporting the public key from the
+    curve448_key structure.
+    \return ECC_BAD_ARG_E Returned if outLen is less than CURVE448_PUB_KEY_SIZE.
+    \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
+
+    \param [in] key Pointer to the curve448_key structure in from which to
+    export the key.
+    \param [out] out Pointer to the buffer in which to store the public key.
+    \param [in,out] outLen On in, is the size of the out in bytes.
+    On out, will store the bytes written to the output buffer.
+    \param [in] endian EC448_BIG_ENDIAN or EC448_LITTLE_ENDIAN to set which
+    form to use.
+
+    _Example_
+    \code
+    int ret;
+
+    byte pub[56];
+    int pubSz;
+
+    curve448_key key;
+    // initialize and make key
+
+    ret = wc_curve448_export_public_ex(&key, pub, &pubSz, EC448_BIG_ENDIAN);
+    if (ret != 0) {
+        // error exporting key
+    }
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_export_private_raw
+    \sa wc_curve448_import_public
+*/
+WOLFSSL_API
+int wc_curve448_export_public_ex(curve448_key* key, byte* out,
+                                   word32* outLen, int endian);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function exports a key pair from the given key structure and
+    stores the result in the out buffer. Big endian only.
+
+    \return 0 Returned on successfully exporting the key pair from the
+    curve448_key structure.
+    \return BAD_FUNC_ARG Returned if any input parameters are NULL.
+    \return ECC_BAD_ARG_E Returned if privSz is less than CURVE448_KEY_SIZE or
+    pubSz is less than CURVE448_PUB_KEY_SIZE.
+
+    \param [in] key Pointer to the curve448_key structure in from which to
+    export the key pair.
+    \param [out] priv Pointer to the buffer in which to store the private key.
+    \param [in,out] privSz On in, is the size of the priv buffer in bytes.
+    On out, will store the bytes written to the priv buffer.
+    \param [out] pub Pointer to the buffer in which to store the public key.
+    \param [in,out] pubSz On in, is the size of the pub buffer in bytes.
+    On out, will store the bytes written to the pub buffer.
+
+    _Example_
+    \code
+    int ret;
+
+    byte pub[56];
+    byte priv[56];
+    int pubSz;
+    int privSz;
+
+    curve448_key key;
+    // initialize and make key
+
+    ret = wc_curve448_export_key_raw(&key, priv, &privSz, pub, &pubSz);
+    if (ret != 0) {
+        // error exporting key
+    }
+    \endcode
+
+    \sa wc_curve448_export_key_raw_ex
+    \sa wc_curve448_export_private_raw
+*/
+WOLFSSL_API
+int wc_curve448_export_key_raw(curve448_key* key,
+                                 byte* priv, word32 *privSz,
+                                 byte* pub, word32 *pubSz);
+
+/*!
+    \ingroup Curve448
+
+    \brief Export curve448 key pair.  Big or little endian.
+    \brief This function exports a key pair from the given key structure and
+    stores the result in the out buffer. Big or little endian.
+
+    \return 0 Success
+    \return BAD_FUNC_ARG Returned if any input parameters are NULL.
+    \return ECC_BAD_ARG_E Returned if privSz is less than CURVE448_KEY_SIZE or
+    pubSz is less than CURVE448_PUB_KEY_SIZE.
+
+    \param [in] key Pointer to the curve448_key structure in from which to
+    export the key pair.
+    \param [out] priv Pointer to the buffer in which to store the private key.
+    \param [in,out] privSz On in, is the size of the priv buffer in bytes.
+    On out, will store the bytes written to the priv buffer.
+    \param [out] pub Pointer to the buffer in which to store the public key.
+    \param [in,out] pubSz On in, is the size of the pub buffer in bytes.
+    On out, will store the bytes written to the pub buffer.
+    \param [in] endian EC448_BIG_ENDIAN or EC448_LITTLE_ENDIAN to set which
+    form to use.
+
+    _Example_
+    \code
+    int ret;
+
+    byte pub[56];
+    byte priv[56];
+    int pubSz;
+    int privSz;
+
+    curve448_key key;
+    // initialize and make key
+
+    ret = wc_curve448_export_key_raw_ex(&key,priv, &privSz, pub, &pubSz,
+            EC448_BIG_ENDIAN);
+    if (ret != 0) {
+        // error exporting key
+    }
+    \endcode
+
+    \sa wc_curve448_export_key_raw
+    \sa wc_curve448_export_private_raw_ex
+    \sa wc_curve448_export_public_ex
+*/
+WOLFSSL_API
+int wc_curve448_export_key_raw_ex(curve448_key* key,
+                                    byte* priv, word32 *privSz,
+                                    byte* pub, word32 *pubSz,
+                                    int endian);
+
+/*!
+    \ingroup Curve448
+
+    \brief This function returns the key size of the given key structure.
+
+    \return Success Given a valid, initialized curve448_key structure,
+    returns the size of the key.
+    \return 0 Returned if key is NULL.
+
+    \param [in] key Pointer to the curve448_key structure in for which to
+    determine the key size.
+
+    _Example_
+    \code
+    int keySz;
+
+    curve448_key key;
+    // initialize and make key
+
+    keySz = wc_curve448_size(&key);
+    \endcode
+
+    \sa wc_curve448_init
+    \sa wc_curve448_make_key
+*/
+WOLFSSL_API
+int wc_curve448_size(curve448_key* key);

doc/dox_comments/header_files/doxygen_groups.h

@@ -7,10 +7,12 @@
     \defgroup ChaCha Algorithms - ChaCha
     \defgroup ChaCha20Poly1305 Algorithms - ChaCha20_Poly1305
     \defgroup Curve25519 Algorithms - Curve25519
+    \defgroup Curve448 Algorithms - Curve448
     \defgroup DSA Algorithms - DSA
     \defgroup Diffie-Hellman Algorithms - Diffie-Hellman
     \defgroup ECC Algorithms - ECC
     \defgroup ED25519 Algorithms - ED25519
+    \defgroup ED448 Algorithms - ED448
     \defgroup HC128 Algorithms - HC-128
     \defgroup HMAC Algorithms - HMAC
     \defgroup IDEA Algorithms - IDEA

doc/dox_comments/header_files/doxygen_pages.h

@@ -33,10 +33,12 @@
         <li>\ref ChaCha</li>
         <li>\ref ChaCha20Poly1305</li>
         <li>\ref Curve25519</li>
+        <li>\ref Curve448</li>
         <li>\ref DSA</li>
         <li>\ref Diffie-Hellman</li>
         <li>\ref ECC</li>
         <li>\ref ED25519</li>
+        <li>\ref ED448</li>
         <li>\ref HC128</li>
         <li>\ref HMAC</li>
         <li>\ref IDEA</li>

doc/dox_comments/header_files/ed25519.h

@@ -1,26 +1,77 @@
 /*!
     \ingroup ED25519
 
-    \brief This function generates a new ed25519_key and stores it in key.
+    \brief This function generates the Ed25519 public key from the private key.
+    It stores the public key in the buffer pubKey, and sets the bytes
+    written to this buffer in pubKeySz.
 
-    \return 0 Returned upon successfully making an ed25519_key
+    \return 0 Returned upon successfully making the public key.
-    \return BAD_FUNC_ARG Returned if rng or key evaluate to NULL, or if the
+    \return BAD_FUNC_ARG Returned ifi key or pubKey evaluate to NULL, or if the
-    specified key size is not 32 bytes (ed25519 has 32 byte keys)
+    specified key size is not 32 bytes (Ed25519 has 32 byte keys).
     \return MEMORY_E Returned if there is an error allocating memory
-    during function execution
+    during function execution.
 
-    \param rng pointer to an initialized RNG object with which to
+    \param [in] key Pointer to the ed25519_key for which to generate a key.
-    generate the key
+    \param [out] out Pointer to the buffer in which to store the public key.
-    \param keysize length of key to generate. Should always be 32 for ed25519
+    \param [in,out] outLen Pointer to a word32 object with the size available
-    \param key pointer to the ed25519_key for which to generate a key
+    in out. Set with the number of bytes written to out after successfully
+    exporting the public key.
 
     _Example_
     \code
+    int ret;
+
     ed25519_key key;
+    byte priv[] = { initialize with 32 byte private key };
+    byte pub[32];
+    word32 pubSz = sizeof(pub);
+
     wc_ed25519_init(&key);
+    wc_ed25519_import_private_only(priv, sizeof(priv), &key);
+    ret = wc_ed25519_make_public(&key, pub, &pubSz);
+    if (ret != 0) {
+        // error making public key
+    }
+    \endcode
+
+    \sa wc_ed25519_init
+    \sa wc_ed25519_import_private_only
+    \sa wc_ed25519_make_key
+*/
+WOLFSSL_API
+int wc_ed25519_make_public(ed25519_key* key, unsigned char* pubKey,
+                           word32 pubKeySz);
+
+/*!
+    \ingroup ED25519
+
+    \brief This function generates a new Ed25519 key and stores it in key.
+
+    \return 0 Returned upon successfully making an ed25519_key.
+    \return BAD_FUNC_ARG Returned if rng or key evaluate to NULL, or if the
+    specified key size is not 32 bytes (Ed25519 has 32 byte keys).
+    \return MEMORY_E Returned if there is an error allocating memory
+    during function execution.
+
+    \param [in] rng Pointer to an initialized RNG object with which to
+    generate the key.
+    \param [in] keysize Length of key to generate. Should always be 32 for
+    Ed25519.
+    \param [in,out] key Pointer to the ed25519_key for which to generate a key.
+
+    _Example_
+    \code
+    int ret;
+
     WC_RNG rng;
+    ed25519_key key;
+
     wc_InitRng(&rng);
-    wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
+    wc_ed25519_init(&key);
+    wc_ed25519_make_key(&rng, 32, &key);
+    if (ret != 0) {
+        // error making key
+    }
     \endcode
 
     \sa wc_ed25519_init
@@ -31,23 +82,23 @@ int wc_ed25519_make_key(WC_RNG* rng, int keysize, ed25519_key* key);
 /*!
     \ingroup ED25519
 
-    \brief This function signs a message digest using an ed25519_key object
+    \brief This function signs a message using an ed25519_key object
     to guarantee authenticity.
 
     \return 0 Returned upon successfully generating a signature for the
-    message digest
+    message.
-    \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
+    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
-    NULL, or if the output buffer is too small to store the generated signature
+    NULL, or if the output buffer is too small to store the generated signature.
     \return MEMORY_E Returned if there is an error allocating memory during
-    function execution
+    function execution.
 
-    \param in pointer to the buffer containing the message to sign
+    \param [in] in Pointer to the buffer containing the message to sign.
-    \param inlen length of the message to sign
+    \param [in] inlen Length of the message to sign.
-    \param out buffer in which to store the generated signature
+    \param [out] out Buffer in which to store the generated signature.
-    \param outlen max length of the output buffer. Will store the bytes
+    \param [in,out] outlen Maximum length of the output buffer. Will store the
-    written to out upon successfully generating a message signature
+    bytes written to out upon successfully generating a message signature.
-    \param key pointer to a private ed25519_key with which to generate the
+    \param [in] key Pointer to a private ed25519_key with which to generate the
-    signature
+    signature.
 
     _Example_
     \code
@@ -57,7 +108,7 @@ int wc_ed25519_make_key(WC_RNG* rng, int keysize, ed25519_key* key);
 
     byte sig[64]; // will hold generated signature
     sigSz = sizeof(sig);
-    byte message[] = { // initialize with message };
+    byte message[] = { initialize with message };
 
     wc_InitRng(&rng); // initialize rng
     wc_ed25519_init(&key); // initialize key
@@ -68,6 +119,9 @@ int wc_ed25519_make_key(WC_RNG* rng, int keysize, ed25519_key* key);
     }
     \endcode
 
+    \sa wc_ed25519ctx_sign_msg
+    \sa wc_ed25519ph_sign_hash
+    \sa wc_ed25519ph_sign_msg
     \sa wc_ed25519_verify_msg
 */
 WOLFSSL_API
@@ -77,50 +131,390 @@ int wc_ed25519_sign_msg(const byte* in, word32 inlen, byte* out,
 /*!
     \ingroup ED25519
 
-    \brief This function verifies the ed25519 signature of a message to ensure
+    \brief This function signs a message using an ed25519_key object
-    authenticity. It returns the answer through stat, with 1 corresponding to
+    to guarantee authenticity. The context is part of the data signed.
+
+    \return 0 Returned upon successfully generating a signature for the
+    message.
+    \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
+    NULL, or if the output buffer is too small to store the generated signature.
+    \return MEMORY_E Returned if there is an error allocating memory during
+    function execution.
+
+    \param [in] in Pointer to the buffer containing the message to sign.
+    \param [in] inlen Length of the message to sign.
+    \param [out] out Buffer in which to store the generated signature.
+    \param [in,out] outlen Maximum length of the output buffer. Will store the
+    bytes written to out upon successfully generating a message signature.
+    \param [in] key Pointer to a private ed25519_key with which to generate the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    message is being signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed25519_key key;
+    WC_RNG rng;
+    int ret, sigSz;
+
+    byte sig[64]; // will hold generated signature
+    sigSz = sizeof(sig);
+    byte message[] = { initialize with message };
+    byte context[] = { initialize with context of signing };
+
+    wc_InitRng(&rng); // initialize rng
+    wc_ed25519_init(&key); // initialize key
+    wc_ed25519_make_key(&rng, 32, &key); // make public/private key pair
+    ret = wc_ed25519ctx_sign_msg(message, sizeof(message), sig, &sigSz, &key,
+            context, sizeof(context));
+    if (ret != 0) {
+        // error generating message signature
+    }
+    \endcode
+
+    \sa wc_ed25519_sign_msg
+    \sa wc_ed25519ph_sign_hash
+    \sa wc_ed25519ph_sign_msg
+    \sa wc_ed25519_verify_msg
+*/
+WOLFSSL_API
+int wc_ed25519ctx_sign_msg(const byte* in, word32 inlen, byte* out,
+                        word32 *outlen, ed25519_key* key,
+                        const byte* context, byte contextLen);
+
+/*!
+    \ingroup ED25519
+
+    \brief This function signs a message digest using an ed25519_key object
+    to guarantee authenticity. The context is included as part of the data
+    signed. The message is pre-hashed before signature calculation. The hash
+    algorithm used to create message digest must be SHAKE-256.
+
+    \return 0 Returned upon successfully generating a signature for the
+    message digest.
+    \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
+    NULL, or if the output buffer is too small to store the generated signature.
+    \return MEMORY_E Returned if there is an error allocating memory during
+    function execution.
+
+    \param [in] hash Pointer to the buffer containing the hash of the message
+    to sign.
+    \param [in] hashLen Length of the hash of the message to sign.
+    \param [out] out Buffer in which to store the generated signature.
+    \param [in,out] outlen Maximum length of the output buffer. Will store the
+    bytes written to out upon successfully generating a message signature.
+    \param [in] key Pointer to a private ed25519_key with which to generate the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    message is being signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed25519_key key;
+    WC_RNG rng;
+    int ret, sigSz;
+
+    byte sig[64]; // will hold generated signature
+    sigSz = sizeof(sig);
+    byte hash[] = { initialize with SHA-512 hash of message };
+    byte context[] = { initialize with context of signing };
+
+    wc_InitRng(&rng); // initialize rng
+    wc_ed25519_init(&key); // initialize key
+    wc_ed25519_make_key(&rng, 32, &key); // make public/private key pair
+    ret = wc_ed25519ph_sign_hash(hash, sizeof(hash), sig, &sigSz, &key,
+            context, sizeof(context));
+    if (ret != 0) {
+        // error generating message signature
+    }
+    \endcode
+
+    \sa wc_ed25519_sign_msg
+    \sa wc_ed25519ctx_sign_msg
+    \sa wc_ed25519ph_sign_msg
+    \sa wc_ed25519_verify_msg
+*/
+WOLFSSL_API
+int wc_ed25519ph_sign_hash(const byte* hash, word32 hashLen, byte* out,
+                           word32 *outLen, ed25519_key* key,
+                           const byte* context, byte contextLen);
+
+/*!
+    \ingroup ED25519
+
+    \brief This function signs a message using an ed25519_key object
+    to guarantee authenticity. The context is included as part of the data
+    signed. The message is pre-hashed before signature calculation.
+
+    \return 0 Returned upon successfully generating a signature for the
+    message.
+    \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
+    NULL, or if the output buffer is too small to store the generated signature.
+    \return MEMORY_E Returned if there is an error allocating memory during
+    function execution.
+
+    \param [in] in Pointer to the buffer containing the message to sign.
+    \param [in] inlen Length of the message to sign.
+    \param [out] out Buffer in which to store the generated signature.
+    \param [in,out] outlen Maximum length of the output buffer. Will store the
+    bytes written to out upon successfully generating a message signature.
+    \param [in] key Pointer to a private ed25519_key with which to generate the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    message is being signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed25519_key key;
+    WC_RNG rng;
+    int ret, sigSz;
+
+    byte sig[64]; // will hold generated signature
+    sigSz = sizeof(sig);
+    byte message[] = { initialize with message };
+    byte context[] = { initialize with context of signing };
+
+    wc_InitRng(&rng); // initialize rng
+    wc_ed25519_init(&key); // initialize key
+    wc_ed25519_make_key(&rng, 32, &key); // make public/private key pair
+    ret = wc_ed25519ph_sign_msg(message, sizeof(message), sig, &sigSz, &key,
+            context, sizeof(context));
+    if (ret != 0) {
+        // error generating message signature
+    }
+    \endcode
+
+    \sa wc_ed25519_sign_msg
+    \sa wc_ed25519ctx_sign_msg
+    \sa wc_ed25519ph_sign_hash
+    \sa wc_ed25519_verify_msg
+*/
+WOLFSSL_API
+int wc_ed25519ph_sign_msg(const byte* in, word32 inlen, byte* out,
+                        word32 *outlen, ed25519_key* key,
+                        const byte* context, byte contextLen);
+
+/*!
+    \ingroup ED25519
+
+    \brief This function verifies the Ed25519 signature of a message to ensure
+    authenticity. It returns the answer through res, with 1 corresponding to
     a valid signature, and 0 corresponding to an invalid signature.
 
     \return 0 Returned upon successfully performing the signature
-    verification. Note: This does not mean that the signature is verified.
+    verification and authentication.
-    The authenticity information is stored instead in stat
     \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
-    NULL, or if the siglen does not match the actual length of a signature
+    NULL, or if the siglen does not match the actual length of a signature.
-    \return 1 Returned if verification completes, but the signature generated
+    \return SIG_VERIFY_E Returned if verification completes, but the signature
-    does not match the signature provided
+    generated does not match the signature provided.
 
-     \param sig pointer to the buffer containing the signature to verify
+    \param [in] sig Pointer to the buffer containing the signature to verify.
-     \param siglen length of the signature to verify
+    \param [in] siglen Length of the signature to verify.
-     \param msg pointer to the buffer containing the message to verify
+    \param [in] msg Pointer to the buffer containing the message to verify.
-     \param msglen length of the message to verify
+    \param [in] msgLen Length of the message to verify.
-     \param stat pointer to the result of the verification. 1 indicates the
+    \param [out] res Pointer to the result of the verification. 1 indicates the
-    message was successfully verified
+    message was successfully verified.
-     \param key pointer to a public ed25519 key with which to verify the
+    \param [in] key Pointer to a public Ed25519 key with which to verify the
-    signature
+    signature.
 
     _Example_
     \code
     ed25519_key key;
     int ret, verified = 0;
 
-    byte sig[] { // initialize with received signature };
+    byte sig[] { initialize with received signature };
-    byte msg[] = { // initialize with message };
+    byte msg[] = { initialize with message };
     // initialize key with received public key
-    ret = wc_ed25519_verify_msg(sig, sizeof(sig), msg, sizeof(msg),
+    ret = wc_ed25519_verify_msg(sig, sizeof(sig), msg, sizeof(msg), &verified,
-    &verified, &key);
+            &key);
-
+    if (ret < 0) {
-    if ( return < 0 ) {
         // error performing verification
     } else if (verified == 0)
         // the signature is invalid
     }
     \endcode
 
+    \sa wc_ed25519ctx_verify_msg
+    \sa wc_ed25519ph_verify_hash
+    \sa wc_ed25519ph_verify_msg
     \sa wc_ed25519_sign_msg
 */
 WOLFSSL_API
 int wc_ed25519_verify_msg(const byte* sig, word32 siglen, const byte* msg,
-                          word32 msglen, int* stat, ed25519_key* key);
+                          word32 msgLen, int* ret, ed25519_key* key);
+
+/*!
+    \ingroup ED25519
+
+    \brief This function verifies the Ed25519 signature of a message to ensure
+    authenticity. The context is included as part of the data
+    verified. It returns the answer through res, with 1 corresponding to
+    a valid signature, and 0 corresponding to an invalid signature.
+
+    \return 0 Returned upon successfully performing the signature
+    verification and authentication.
+    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
+    NULL, or if the siglen does not match the actual length of a signature.
+    \return SIG_VERIFY_E Returned if verification completes, but the signature
+    generated does not match the signature provided.
+
+    \param [in] sig Pointer to the buffer containing the signature to verify.
+    \param [in] siglen Length of the signature to verify.
+    \param [in] msg Pointer to the buffer containing the message to verify.
+    \param [in] msgLen Length of the message to verify.
+    \param [out] res Pointer to the result of the verification. 1 indicates the
+    message was successfully verified.
+    \param [in] key Pointer to a public Ed25519 key with which to verify the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    the message was signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed25519_key key;
+    int ret, verified = 0;
+
+    byte sig[] { initialize with received signature };
+    byte msg[] = { initialize with message };
+    byte context[] = { initialize with context of signature };
+    // initialize key with received public key
+    ret = wc_ed25519ctx_verify_msg(sig, sizeof(sig), msg, sizeof(msg),
+            &verified, &key, );
+    if (ret < 0) {
+        // error performing verification
+    } else if (verified == 0)
+        // the signature is invalid
+    }
+    \endcode
+
+    \sa wc_ed25519_verify_msg
+    \sa wc_ed25519ph_verify_hash
+    \sa wc_ed25519ph_verify_msg
+    \sa wc_ed25519_sign_msg
+*/
+WOLFSSL_API
+int wc_ed25519ctx_verify_msg(const byte* sig, word32 siglen, const byte* msg,
+                             word32 msgLen, int* ret, ed25519_key* key,
+                             const byte* context, byte contextLen);
+
+/*!
+    \ingroup ED25519
+
+    \brief This function verifies the Ed25519 signature of the digest of a
+    message to ensure authenticity. The context is included as part of the data
+    verified. The hash is the pre-hashed message before signature calculation.
+    The hash algorithm used to create message digest must be SHA-512.
+    The answer is returned through res, with 1 corresponding to a valid
+    signature, and 0 corresponding to an invalid signature.
+
+
+    \return 0 Returned upon successfully performing the signature
+    verification and authentication.
+    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
+    NULL, or if the siglen does not match the actual length of a signature.
+    \return SIG_VERIFY_E Returned if verification completes, but the signature
+    generated does not match the signature provided.
+
+    \param [in] sig Pointer to the buffer containing the signature to verify.
+    \param [in] siglen Length of the signature to verify.
+    \param [in] hash Pointer to the buffer containing the hash of the message
+    to verify.
+    \param [in] hashLen Length of the hash to verify.
+    \param [out] res Pointer to the result of the verification. 1 indicates the
+    message was successfully verified.
+    \param [in] key Pointer to a public Ed25519 key with which to verify the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    the message was signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed25519_key key;
+    int ret, verified = 0;
+
+    byte sig[] { initialize with received signature };
+    byte hash[] = { initialize with SHA-512 hash of message };
+    byte context[] = { initialize with context of signature };
+    // initialize key with received public key
+    ret = wc_ed25519ph_verify_hash(sig, sizeof(sig), msg, sizeof(msg),
+            &verified, &key, );
+    if (ret < 0) {
+        // error performing verification
+    } else if (verified == 0)
+        // the signature is invalid
+    }
+    \endcode
+
+    \sa wc_ed25519_verify_msg
+    \sa wc_ed25519ctx_verify_msg
+    \sa wc_ed25519ph_verify_msg
+    \sa wc_ed25519_sign_msg
+*/
+WOLFSSL_API
+int wc_ed25519ph_verify_hash(const byte* sig, word32 siglen, const byte* hash,
+                             word32 hashLen, int* ret, ed25519_key* key,
+                             const byte* context, byte contextLen);
+
+/*!
+    \ingroup ED25519
+
+    \brief This function verifies the Ed25519 signature of a message to ensure
+    authenticity. The context is included as part of the data
+    verified. The message is pre-hashed before verification. It returns the
+    answer through res, with 1 corresponding to a valid signature, and 0
+    corresponding to an invalid signature.
+
+    \return 0 Returned upon successfully performing the signature
+    verification and authentication.
+    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
+    NULL, or if the siglen does not match the actual length of a signature.
+    \return SIG_VERIFY_E Returned if verification completes, but the signature
+    generated does not match the signature provided.
+
+    \param [in] sig Pointer to the buffer containing the signature to verify.
+    \param [in] siglen Length of the signature to verify.
+    \param [in] msg Pointer to the buffer containing the message to verify.
+    \param [in] msgLen Length of the message to verify.
+    \param [out] res Pointer to the result of the verification. 1 indicates the
+    message was successfully verified.
+    \param [in] key Pointer to a public Ed25519 key with which to verify the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    the message was signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed25519_key key;
+    int ret, verified = 0;
+
+    byte sig[] { initialize with received signature };
+    byte msg[] = { initialize with message };
+    byte context[] = { initialize with context of signature };
+    // initialize key with received public key
+    ret = wc_ed25519ctx_verify_msg(sig, sizeof(sig), msg, sizeof(msg),
+            &verified, &key, );
+    if (ret < 0) {
+        // error performing verification
+    } else if (verified == 0)
+        // the signature is invalid
+    }
+    \endcode
+
+    \sa wc_ed25519_verify_msg
+    \sa wc_ed25519ph_verify_hash
+    \sa wc_ed25519ph_verify_msg
+    \sa wc_ed25519_sign_msg
+*/
+WOLFSSL_API
+int wc_ed25519ph_verify_msg(const byte* sig, word32 siglen, const byte* msg,
+                            word32 msgLen, int* ret, ed25519_key* key,
+                            const byte* context, byte contextLen);
 
 /*!
     \ingroup ED25519
@@ -128,10 +522,10 @@ int wc_ed25519_verify_msg(const byte* sig, word32 siglen, const byte* msg,
     \brief This function initializes an ed25519_key object for future use
     with message verification.
 
-    \return 0 Returned upon successfully initializing the ed25519_key object
+    \return 0 Returned upon successfully initializing the ed25519_key object.
-    \return BAD_FUNC_ARG Returned if key is NULL
+    \return BAD_FUNC_ARG Returned if key is NULL.
 
-    \param key pointer to the ed25519_key object to initialize
+    \param [in,out] key Pointer to the ed25519_key object to initialize.
 
     _Example_
     \code
@@ -148,11 +542,9 @@ int wc_ed25519_init(ed25519_key* key);
 /*!
     \ingroup ED25519
 
-    \brief This function frees an ed25519 object after it has been used.
+    \brief This function frees an Ed25519 object after it has been used.
 
-    \return none No returns.
+    \param [in,out] key Pointer to the ed25519_key object to free
-
-    \param key pointer to the ed25519_key object to free
 
     _Example_
     \code
@@ -174,19 +566,19 @@ void wc_ed25519_free(ed25519_key* key);
     containing the public key. This function will handle both compressed and
     uncompressed keys.
 
-    \return 0 Returned on successfully importing the ed25519_key
+    \return 0 Returned on successfully importing the ed25519_key.
     \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is
-    less than the size of an ed25519 key
+    less than the size of an Ed25519 key.
 
-    \param in pointer to the buffer containing the public key
+    \param [in] in Pointer to the buffer containing the public key.
-    \param inLen length of the buffer containing the public key
+    \param [in] inLen Length of the buffer containing the public key.
-    \param key pointer to the ed25519_key object in which to store the
+    \param [in,out] key Pointer to the ed25519_key object in which to store the
-    public key
+    public key.
 
     _Example_
     \code
     int ret;
-    byte pub[] = { // initialize ed25519 public key };
+    byte pub[] = { initialize Ed25519 public key };
 
     ed_25519 key;
     wc_ed25519_init_key(&key);
@@ -205,38 +597,78 @@ int wc_ed25519_import_public(const byte* in, word32 inLen, ed25519_key* key);
 /*!
     \ingroup ED25519
 
-    \brief This function imports a public/private ed25519 key pair from a
+    \brief This function imports an Ed25519 private key only from a
-    pair of buffers. This function will handle both compressed and
+    buffer.
-    uncompressed keys.
 
-    \return 0 Returned on successfully importing the ed25519_key
+    \return 0 Returned on successfully importing the Ed25519 key.
     \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if
-    either privSz or pubSz are less than the size of an ed25519 key
+    privSz is less than ED25519_KEY_SIZE.
 
-    \param priv pointer to the buffer containing the private key
+    \param [in] priv Pointer to the buffer containing the private key.
-    \param privSz size of the private key
+    \param [in] privSz Length of the private key.
-    \param pub pointer to the buffer containing the public key
+    \param [in] pub Pointer to the buffer containing the public key.
-    \param pubSz length of the public key
+    \param [in] pubSz Length of the public key.
-    \param key pointer to the ed25519_key object in which to store the
+    \param [in,out] key Pointer to the ed25519_key object in which to store the
-    imported private/public key pair
+    imported private key.
 
     _Example_
     \code
     int ret;
-    byte priv[] = { // initialize with 32 byte private key };
+    byte priv[] = { initialize with 32 byte private key };
-    byte pub[]  = { // initialize with the corresponding public key };
 
     ed25519_key key;
     wc_ed25519_init_key(&key);
-    ret = wc_ed25519_import_private_key(priv, sizeof(priv), pub,
+    ret = wc_ed25519_import_private_key(priv, sizeof(priv), &key);
-    sizeof(pub), &key);
+    if (ret != 0) {
+        // error importing private key
+    }
+    \endcode
+
+    \sa wc_ed25519_import_public
+    \sa wc_ed25519_import_private_key
+    \sa wc_ed25519_export_private_only
+*/
+WOLFSSL_API
+int wc_ed25519_import_private_only(const byte* priv, word32 privSz,
+                                   ed25519_key* key);
+
+/*!
+    \ingroup ED25519
+
+    \brief This function imports a public/private Ed25519 key pair from a
+    pair of buffers. This function will handle both compressed and
+    uncompressed keys.
+
+    \return 0 Returned on successfully importing the ed25519_key.
+    \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if
+    either privSz is less than ED25519_KEY_SIZE or pubSz is less than
+    ED25519_PUB_KEY_SIZE.
+
+    \param [in] priv Pointer to the buffer containing the private key.
+    \param [in] privSz Length of the private key.
+    \param [in] pub Pointer to the buffer containing the public key.
+    \param [in] pubSz Length of the public key.
+    \param [in,out] key Pointer to the ed25519_key object in which to store the
+    imported private/public key pair.
+
+    _Example_
+    \code
+    int ret;
+    byte priv[] = { initialize with 32 byte private key };
+    byte pub[]  = { initialize with the corresponding public key };
+
+    ed25519_key key;
+    wc_ed25519_init_key(&key);
+    ret = wc_ed25519_import_private_key(priv, sizeof(priv), pub, sizeof(pub),
+            &key);
     if (ret != 0) {
         // error importing key
     }
     \endcode
 
-    \sa wc_ed25519_import_public_key
+    \sa wc_ed25519_import_public
-    \sa wc_ed25519_export_private_only
+    \sa wc_ed25519_import_private_only
+    \sa wc_ed25519_export_private
 */
 WOLFSSL_API
 int wc_ed25519_import_private_key(const byte* priv, word32 privSz,
@@ -249,18 +681,18 @@ int wc_ed25519_import_private_key(const byte* priv, word32 privSz,
     structure. It stores the public key in the buffer out, and sets the bytes
     written to this buffer in outLen.
 
-    \return 0 Returned upon successfully exporting the public key
+    \return 0 Returned upon successfully exporting the public key.
-    \return BAD_FUNC_ARG Returned if any of the input values evaluate to NULL
+    \return BAD_FUNC_ARG Returned if any of the input values evaluate to NULL.
     \return BUFFER_E Returned if the buffer provided is not large enough to
     store the private key. Upon returning this error, the function sets the
-    size required in outLen
+    size required in outLen.
 
-    \param key pointer to an ed25519_key structure from which to export the
+    \param [in] key Pointer to an ed25519_key structure from which to export the
-    public key
+    public key.
-    \param out pointer to the buffer in which to store the public key
+    \param [out] out Pointer to the buffer in which to store the public key.
-    \param outLen pointer to a word32 object with the size available in out.
+    \param [in,out] outLen Pointer to a word32 object with the size available
-    Set with the number of bytes written to out after successfully exporting
+    in out. Set with the number of bytes written to out after successfully
-    the private key
+    exporting the public key.
 
     _Example_
     \code
@@ -277,7 +709,7 @@ int wc_ed25519_import_private_key(const byte* priv, word32 privSz,
     }
     \endcode
 
-    \sa wc_ed25519_import_public_key
+    \sa wc_ed25519_import_public
     \sa wc_ed25519_export_private_only
 */
 WOLFSSL_API
@@ -290,17 +722,17 @@ int wc_ed25519_export_public(ed25519_key*, byte* out, word32* outLen);
     structure. It stores the private key in the buffer out, and sets
     the bytes written to this buffer in outLen.
 
-    \return 0 Returned upon successfully exporting the private key
+    \return 0 Returned upon successfully exporting the private key.
-    \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL
+    \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL.
     \return BUFFER_E Returned if the buffer provided is not large enough
-    to store the private key
+    to store the private key.
 
-    \param key pointer to an ed25519_key structure from which to export
+    \param [in] key Pointer to an ed25519_key structure from which to export
-    the private key
+    the private key.
-    \param out pointer to the buffer in which to store the private key
+    \param [out] out Pointer to the buffer in which to store the private key.
-    \param outLen pointer to a word32 object with the size available in
+    \param [in,out] outLen Pointer to a word32 object with the size available in
     out. Set with the number of bytes written to out after successfully
-    exporting the private key
+    exporting the private key.
 
     _Example_
     \code
@@ -325,16 +757,21 @@ int wc_ed25519_export_private_only(ed25519_key* key, byte* out, word32* outLen);
 /*!
     \ingroup ED25519
 
-    \brief Export the private key, including public part.
+    \brief This function exports the key pair from an ed25519_key
+    structure. It stores the key pair in the buffer out, and sets
+    the bytes written to this buffer in outLen.
 
-    \return 0 Success
+    \return 0 Returned upon successfully exporting the key pair.
-    \return BAD_FUNC_ARG Returns if any argument is null.
+    \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL.
-    \return BUFFER_E Returns if outLen is less than ED25519_PRV_KEY_SIZE
+    \return BUFFER_E Returned if the buffer provided is not large enough
+    to store the key pair.
 
-    \param key ed25519_key struct to export from.
+    \param [in] key Pointer to an ed25519_key structure from which to export
-    \param out Destination for private key.
+    the key pair.
-    \param outLen Max length of output, set to the length of the exported
+    \param [out] out Pointer to the buffer in which to store the key pair.
-    private key.
+    \param [in,out] outLen Pointer to a word32 object with the size available in
+    out. Set with the number of bytes written to out after successfully
+    exporting the key pair.
 
     _Example_
     \code
@@ -344,18 +781,18 @@ int wc_ed25519_export_private_only(ed25519_key* key, byte* out, word32* outLen);
     WC_RNG rng;
     wc_InitRng(&rng);
 
-    wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
+    wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte Ed25519 key
 
-    byte out[32]; // out needs to be a sufficient buffer size
+    byte out[64]; // out needs to be a sufficient buffer size
     word32 outLen = sizeof(out);
     int key_size = wc_ed25519_export_private(&key, out, &outLen);
-    if(key_size == BUFFER_E)
+    if (key_size == BUFFER_E) {
-    {
         // Check size of out compared to outLen to see if function reset outLen
     }
     \endcode
 
-    \sa none
+    \sa wc_ed25519_import_private_key
+    \sa wc_ed25519_export_private_only
 */
 WOLFSSL_API
 int wc_ed25519_export_private(ed25519_key* key, byte* out, word32* outLen);
@@ -363,18 +800,26 @@ int wc_ed25519_export_private(ed25519_key* key, byte* out, word32* outLen);
 /*!
     \ingroup ED25519
 
-    \brief Export full private key and public key.
+    \brief This function exports the private and public key separately from an
+    ed25519_key structure. It stores the private key in the buffer priv, and
+    sets the bytes written to this buffer in privSz. It stores the public key
+    in the buffer pub, and sets the bytes written to this buffer in pubSz.
 
-    \return 0 Success
+    \return 0 Returned upon successfully exporting the key pair.
-    \return BAD_FUNC_ARG: Returns if any argument is null.
+    \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL.
-    \return BUFFER_E: Returns if outLen is less than ED25519_PRV_KEY_SIZE
+    \return BUFFER_E Returned if the buffer provided is not large enough
-    or ED25519_PUB_KEY_SIZE
+    to store the key pair.
 
-    \param key The ed25519_key structure to export to.
+    \param [in] key Pointer to an ed25519_key structure from which to export
-    \param priv Byte array to store private key.
+    the key pair.
-    \param privSz Size of priv buffer.
+    \param [out] priv Pointer to the buffer in which to store the private key.
-    \param pub Byte array to store public key.
+    \param [in,out] privSz Pointer to a word32 object with the size available in
-    \param pubSz Size of pub buffer.
+    out. Set with the number of bytes written to out after successfully
+    exporting the private key.
+    \param [out] pub Pointer to the buffer in which to store the public key.
+    \param [in,out] pubSz Pointer to a word32 object with the size available in
+    out. Set with the number of bytes written to out after successfully
+    exporting the public key.
 
     _Example_
     \code
@@ -404,14 +849,45 @@ int wc_ed25519_export_key(ed25519_key* key,
 /*!
     \ingroup ED25519
 
-    \brief This function returns the key size of an ed25519_key structure,
+    \brief This function checks the public key in ed25519_key structure matches
-    or 32 bytes.
+    the private key.
 
-    \return Success Given a valid key, returns ED25519_KEY_SIZE (32 bytes)
+    \return 0 Returned if the private and public key matched.
-    \return BAD_FUNC_ARGS Returned if the given key is NULL
+    \return BAD_FUNC_ARGS Returned if the given key is NULL.
 
-    \param key pointer to an ed25519_key structure for which to get the
+    \param [in] key Pointer to an ed25519_key structure holding a private and
-    key size
+    public key.
+
+    _Example_
+    \code
+    int ret;
+    byte priv[] = { initialize with 57 byte private key };
+    byte pub[]  = { initialize with the corresponding public key };
+
+    ed25519_key key;
+    wc_ed25519_init_key(&key);
+    wc_ed25519_import_private_key(priv, sizeof(priv), pub, sizeof(pub), &key);
+    ret = wc_ed25519_check_key(&key);
+    if (ret != 0) {
+        // error checking key
+    }
+    \endcode
+
+    \sa wc_ed25519_import_private_key
+*/
+WOLFSSL_API
+int wc_ed25519_check_key(ed25519_key* key);
+
+/*!
+    \ingroup ED25519
+
+    \brief This function returns the size of an Ed25519 - 32 bytes.
+
+    \return ED25519_KEY_SIZE The size of a valid private key (32 bytes).
+    \return BAD_FUNC_ARGS Returned if the given key is NULL.
+
+    \param [in] key Pointer to an ed25519_key structure for which to get the
+    key size.
 
     _Example_
     \code
@@ -432,12 +908,14 @@ int wc_ed25519_size(ed25519_key* key);
 /*!
     \ingroup ED25519
 
-    \brief Returns the private key size (secret + public) in bytes.
+    \brief This function returns the private key size (secret + public) in
+    bytes.
 
-    \return BAD_FUNC_ARG Returns if key argument is null.
+    \return ED25519_PRV_KEY_SIZE The size of the private key (64 bytes).
-    \return ED25519_PRV_KEY_SIZE The size of the private key.
+    \return BAD_FUNC_ARG Returned if key argument is NULL.
 
-    \param key The ed25119_key struct
+    \param [in] key Pointer to an ed25519_key structure for which to get the
+    key size.
 
     _Example_
     \code
@@ -447,11 +925,11 @@ int wc_ed25519_size(ed25519_key* key);
     WC_RNG rng;
     wc_InitRng(&rng);
 
-    wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
+    wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte Ed25519 key
     int key_size = wc_ed25519_priv_size(&key);
     \endcode
 
-    \sa wc_ed25119_pub_size
+    \sa wc_ed25519_pub_size
 */
 WOLFSSL_API
 int wc_ed25519_priv_size(ed25519_key* key);
@@ -459,12 +937,14 @@ int wc_ed25519_priv_size(ed25519_key* key);
 /*!
     \ingroup ED25519
 
-    \brief Returns the compressed key size in bytes (public key).
+    \brief This function returns the compressed key size in bytes (public key).
 
-    \return BAD_FUNC_ARG returns if key is null.
+    \return ED25519_PUB_KEY_SIZE The size of the compressed public key
-    \return ED25519_PUB_KEY_SIZE Size of key.
+    (32 bytes).
+    \return BAD_FUNC_ARG Returns if key argument is NULL.
 
-    \param key Pointer to the ed25519_key struct.
+    \param [in] key Pointer to an ed25519_key structure for which to get the
+    key size.
 
     _Example_
     \code
@@ -473,7 +953,7 @@ int wc_ed25519_priv_size(ed25519_key* key);
     WC_RNG rng;
     wc_InitRng(&rng);
 
-    wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
+    wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte Ed25519 key
     int key_size = wc_ed25519_pub_size(&key);
     \endcode
 
@@ -485,13 +965,13 @@ int wc_ed25519_pub_size(ed25519_key* key);
 /*!
     \ingroup ED25519
 
-    \brief This function returns the size of an ed25519 signature (64 in bytes).
+    \brief This function returns the size of an Ed25519 signature (64 in bytes).
 
-    \return Success Given a valid key, returns ED25519_SIG_SIZE (64 in bytes)
+    \return ED25519_SIG_SIZE The size of an Ed25519 signature (64 bytes).
-    \return 0 Returned if the given key is NULL
+    \return BAD_FUNC_ARG Returns if key argument is NULL.
 
-    \param key pointer to an ed25519_key structure for which to get the
+    \param [in] key Pointer to an ed25519_key structure for which to get the
-    signature size
+    signature size.
 
     _Example_
     \code

doc/dox_comments/header_files/ed448.h

@@ -0,0 +1,872 @@
+/*!
+    \ingroup ED448
+
+    \brief This function generates the Ed448 public key from the private key.
+    It stores the public key in the buffer pubKey, and sets the bytes
+    written to this buffer in pubKeySz.
+
+    \return 0 Returned upon successfully making the public key.
+    \return BAD_FUNC_ARG Returned ifi key or pubKey evaluate to NULL, or if the
+    specified key size is not 57 bytes (Ed448 has 57 byte keys).
+    \return MEMORY_E Returned if there is an error allocating memory
+    during function execution.
+
+    \param [in] key Pointer to the ed448_key for which to generate a key.
+    \param [out] out Pointer to the buffer in which to store the public key.
+    \param [in,out] outLen Pointer to a word32 object with the size available
+    in out. Set with the number of bytes written to out after successfully
+    exporting the public key.
+
+    _Example_
+    \code
+    int ret;
+
+    ed448_key key;
+    byte priv[] = { initialize with 57 byte private key };
+    byte pub[57];
+    word32 pubSz = sizeof(pub);
+
+    wc_ed448_init(&key);
+    wc_ed448_import_private_only(priv, sizeof(priv), &key);
+    ret = wc_ed448_make_public(&key, pub, &pubSz);
+    if (ret != 0) {
+        // error making public key
+    }
+    \endcode
+
+    \sa wc_ed448_init
+    \sa wc_ed448_import_private_only
+    \sa wc_ed448_make_key
+*/
+WOLFSSL_API
+int wc_ed448_make_public(ed448_key* key, unsigned char* pubKey,
+                         word32 pubKeySz);
+
+/*!
+    \ingroup ED448
+
+    \brief This function generates a new Ed448 key and stores it in key.
+
+    \return 0 Returned upon successfully making an ed448_key.
+    \return BAD_FUNC_ARG Returned if rng or key evaluate to NULL, or if the
+    specified key size is not 57 bytes (Ed448 has 57 byte keys).
+    \return MEMORY_E Returned if there is an error allocating memory
+    during function execution.
+
+    \param [in] rng Pointer to an initialized RNG object with which to
+    generate the key.
+    \param [in] keysize Length of key to generate. Should always be 57 for
+    Ed448.
+    \param [in,out] key Pointer to the ed448_key for which to generate a key.
+
+    _Example_
+    \code
+    int ret;
+
+    WC_RNG rng;
+    ed448_key key;
+
+    wc_InitRng(&rng);
+    wc_ed448_init(&key);
+    ret = wc_ed448_make_key(&rng, 57, &key);
+    if (ret != 0) {
+        // error making key
+    }
+    \endcode
+
+    \sa wc_ed448_init
+*/
+WOLFSSL_API
+int wc_ed448_make_key(WC_RNG* rng, int keysize, ed448_key* key);
+
+/*!
+    \ingroup ED448
+
+    \brief This function signs a message using an ed448_key object
+    to guarantee authenticity.
+
+    \return 0 Returned upon successfully generating a signature for the
+    message.
+    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
+    NULL, or if the output buffer is too small to store the generated signature.
+    \return MEMORY_E Returned if there is an error allocating memory during
+    function execution.
+
+    \param [in] in Pointer to the buffer containing the message to sign.
+    \param [in] inlen Length of the message to sign.
+    \param [out] out Buffer in which to store the generated signature.
+    \param [in,out] outlen Maximum length of the output buffer. Will store the
+    bytes written to out upon successfully generating a message signature.
+    \param [in] key Pointer to a private ed448_key with which to generate the
+    signature.
+
+    _Example_
+    \code
+    ed448_key key;
+    WC_RNG rng;
+    int ret, sigSz;
+
+    byte sig[114]; // will hold generated signature
+    sigSz = sizeof(sig);
+    byte message[] = { initialize with message };
+
+    wc_InitRng(&rng); // initialize rng
+    wc_ed448_init(&key); // initialize key
+    wc_ed448_make_key(&rng, 57, &key); // make public/private key pair
+    ret = wc_ed448_sign_msg(message, sizeof(message), sig, &sigSz, &key);
+    if (ret != 0 ) {
+        // error generating message signature
+    }
+    \endcode
+
+    \sa wc_ed448ph_sign_hash
+    \sa wc_ed448ph_sign_msg
+    \sa wc_ed448_verify_msg
+*/
+WOLFSSL_API
+int wc_ed448_sign_msg(const byte* in, word32 inlen, byte* out,
+                        word32 *outlen, ed448_key* key);
+
+/*!
+    \ingroup ED448
+
+    \brief This function signs a message digest using an ed448_key object
+    to guarantee authenticity. The context is included as part of the data
+    signed. The hash is the pre-hashed message before signature calculation.
+    The hash algorithm used to create message digest must be SHAKE-256.
+
+    \return 0 Returned upon successfully generating a signature for the
+    message digest.
+    \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
+    NULL, or if the output buffer is too small to store the generated signature.
+    \return MEMORY_E Returned if there is an error allocating memory during
+    function execution.
+
+    \param [in] hash Pointer to the buffer containing the hash of the message
+    to sign.
+    \param [in] hashLen Length of the hash of the message to sign.
+    \param [out] out Buffer in which to store the generated signature.
+    \param [in,out] outlen Maximum length of the output buffer. Will store the
+    bytes written to out upon successfully generating a message signature.
+    \param [in] key Pointer to a private ed448_key with which to generate the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    message is being signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed448_key key;
+    WC_RNG rng;
+    int ret, sigSz;
+
+    byte sig[114]; // will hold generated signature
+    sigSz = sizeof(sig);
+    byte hash[] = { initialize with SHAKE-256 hash of message };
+    byte context[] = { initialize with context of signing };
+
+    wc_InitRng(&rng); // initialize rng
+    wc_ed448_init(&key); // initialize key
+    wc_ed448_make_key(&rng, 57, &key); // make public/private key pair
+    ret = wc_ed448ph_sign_hash(hash, sizeof(hash), sig, &sigSz, &key,
+            context, sizeof(context));
+    if (ret != 0) {
+        // error generating message signature
+    }
+    \endcode
+
+    \sa wc_ed448_sign_msg
+    \sa wc_ed448ph_sign_msg
+    \sa wc_ed448ph_verify_hash
+*/
+WOLFSSL_API
+int wc_ed448ph_sign_hash(const byte* hash, word32 hashLen, byte* out,
+                         word32 *outLen, ed448_key* key,
+                         const byte* context, byte contextLen);
+
+/*!
+    \ingroup ED448
+
+    \brief This function signs a message using an ed448_key object
+    to guarantee authenticity. The context is included as part of the data
+    signed. The message is pre-hashed before signature calculation.
+
+    \return 0 Returned upon successfully generating a signature for the
+    message.
+    \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
+    NULL, or if the output buffer is too small to store the generated signature.
+    \return MEMORY_E Returned if there is an error allocating memory during
+    function execution.
+
+    \param [in] in Pointer to the buffer containing the message to sign.
+    \param [in] inlen Length of the message to sign.
+    \param [out] out Buffer in which to store the generated signature.
+    \param [in,out] outlen Maximum length of the output buffer. Will store the
+    bytes written to out upon successfully generating a message signature.
+    \param [in] key Pointer to a private ed448_key with which to generate the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    message is being signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed448_key key;
+    WC_RNG rng;
+    int ret, sigSz;
+
+    byte sig[114]; // will hold generated signature
+    sigSz = sizeof(sig);
+    byte message[] = { initialize with message };
+    byte context[] = { initialize with context of signing };
+
+    wc_InitRng(&rng); // initialize rng
+    wc_ed448_init(&key); // initialize key
+    wc_ed448_make_key(&rng, 57, &key); // make public/private key pair
+    ret = wc_ed448ph_sign_msg(message, sizeof(message), sig, &sigSz, &key,
+            context, sizeof(context));
+    if (ret != 0) {
+        // error generating message signature
+    }
+    \endcode
+
+    \sa wc_ed448_sign_msg
+    \sa wc_ed448ph_sign_hash
+    \sa wc_ed448ph_verify_msg
+*/
+WOLFSSL_API
+int wc_ed448ph_sign_msg(const byte* in, word32 inLen, byte* out,
+                        word32 *outLen, ed448_key* key, const byte* context,
+                        byte contextLen);
+
+/*!
+    \ingroup ED448
+
+    \brief This function verifies the Ed448 signature of a message to ensure
+    authenticity. The context is included as part of the data
+    verified. The answer is returned through res, with 1 corresponding to
+    a valid signature, and 0 corresponding to an invalid signature.
+
+    \return 0 Returned upon successfully performing the signature
+    verification and authentication.
+    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
+    NULL, or if the siglen does not match the actual length of a signature.
+    \return SIG_VERIFY_E Returned if verification completes, but the signature
+    generated does not match the signature provided.
+
+    \param [in] sig Pointer to the buffer containing the signature to verify.
+    \param [in] siglen Length of the signature to verify.
+    \param [in] msg Pointer to the buffer containing the message to verify.
+    \param [in] msgLen Length of the message to verify.
+    \param [in] key Pointer to a public Ed448 key with which to verify the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    the message was signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed448_key key;
+    int ret, verified = 0;
+
+    byte sig[] { initialize with received signature };
+    byte msg[] = { initialize with message };
+    byte context[] = { initialize with context of signature };
+    // initialize key with received public key
+    ret = wc_ed448_verify_msg(sig, sizeof(sig), msg, sizeof(msg), &verified,
+            &key, context, sizeof(context));
+    if (ret < 0) {
+        // error performing verification
+    } else if (verified == 0)
+        // the signature is invalid
+    }
+    \endcode
+
+    \sa wc_ed448ph_verify_hash
+    \sa wc_ed448ph_verify_msg
+    \sa wc_ed448_sign_msg
+*/
+WOLFSSL_API
+int wc_ed448_verify_msg(const byte* sig, word32 siglen, const byte* msg,
+                          word32 msgLen, int* res, ed448_key* key,
+                          const byte* context, byte contextLen);
+
+/*!
+    \ingroup ED448
+
+    \brief This function verifies the Ed448 signature of the digest of a message
+    to ensure authenticity. The context is included as part of the data
+    verified. The hash is the pre-hashed message before signature calculation.
+    The hash algorithm used to create message digest must be SHAKE-256.
+    The answer is returned through res, with 1 corresponding to a valid
+    signature, and 0 corresponding to an invalid signature.
+
+    \return 0 Returned upon successfully performing the signature
+    verification and authentication.
+    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
+    NULL, or if the siglen does not match the actual length of a signature.
+    \return SIG_VERIFY_E Returned if verification completes, but the signature
+    generated does not match the signature provided.
+
+    \param [in] sig Pointer to the buffer containing the signature to verify.
+    \param [in] siglen Length of the signature to verify.
+    \param [in] hash Pointer to the buffer containing the hash of the message
+    to verify.
+    \param [in] hashLen Length of the hash to verify.
+    \param [in] key Pointer to a public Ed448 key with which to verify the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    the message was signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed448_key key;
+    int ret, verified = 0;
+
+    byte sig[] { initialize with received signature };
+    byte hash[] = { initialize with SHAKE-256 hash of message };
+    byte context[] = { initialize with context of signature };
+    // initialize key with received public key
+    ret = wc_ed448ph_verify_hash(sig, sizeof(sig), hash, sizeof(hash),
+            &verified, &key, context, sizeof(context));
+    if (ret < 0) {
+        // error performing verification
+    } else if (verified == 0)
+        // the signature is invalid
+    }
+    \endcode
+
+    \sa wc_ed448_verify_msg
+    \sa wc_ed448ph_verify_msg
+    \sa wc_ed448ph_sign_hash
+*/
+WOLFSSL_API
+int wc_ed448ph_verify_hash(const byte* sig, word32 siglen, const byte* hash,
+                          word32 hashlen, int* res, ed448_key* key,
+                          const byte* context, byte contextLen);
+
+/*!
+    \ingroup ED448
+
+    \brief This function verifies the Ed448 signature of a message to ensure
+    authenticity. The context is included as part of the data
+    verified. The message is pre-hashed before verification. The answer is
+    returned through res, with 1 corresponding to a valid signature, and 0
+    corresponding to an invalid signature.
+
+    \return 0 Returned upon successfully performing the signature
+    verification and authentication.
+    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
+    NULL, or if the siglen does not match the actual length of a signature.
+    \return SIG_VERIFY_E Returned if verification completes, but the signature
+    generated does not match the signature provided.
+
+    \param [in] sig Pointer to the buffer containing the signature to verify.
+    \param [in] siglen Length of the signature to verify.
+    \param [in] msg Pointer to the buffer containing the message to verify.
+    \param [in] msgLen Length of the message to verify.
+    \param [in] key Pointer to a public Ed448 key with which to verify the
+    signature.
+    \param [in] context Pointer to the buffer containing the context for which
+    the message was signed.
+    \param [in] contextLen Length of the context buffer.
+
+    _Example_
+    \code
+    ed448_key key;
+    int ret, verified = 0;
+
+    byte sig[] { initialize with received signature };
+    byte msg[] = { initialize with message };
+    byte context[] = { initialize with context of signature };
+    // initialize key with received public key
+    ret = wc_ed448ph_verify_msg(sig, sizeof(sig), msg, sizeof(msg), &verified,
+            &key, context, sizeof(context));
+    if (ret < 0) {
+        // error performing verification
+    } else if (verified == 0)
+        // the signature is invalid
+    }
+    \endcode
+
+    \sa wc_ed448_verify_msg
+    \sa wc_ed448ph_verify_hash
+    \sa wc_ed448ph_sign_msg
+*/
+WOLFSSL_API
+int wc_ed448ph_verify_msg(const byte* sig, word32 siglen, const byte* msg,
+                          word32 msgLen, int* res, ed448_key* key,
+                          const byte* context, byte contextLen);
+
+/*!
+    \ingroup ED448
+
+    \brief This function initializes an ed448_key object for future use
+    with message verification.
+
+    \return 0 Returned upon successfully initializing the ed448_key object.
+    \return BAD_FUNC_ARG Returned if key is NULL.
+
+    \param [in,out] key Pointer to the ed448_key object to initialize.
+
+    _Example_
+    \code
+    ed448_key key;
+    wc_ed448_init(&key);
+    \endcode
+
+    \sa wc_ed448_make_key
+    \sa wc_ed448_free
+*/
+WOLFSSL_API
+int wc_ed448_init(ed448_key* key);
+
+/*!
+    \ingroup ED448
+
+    \brief This function frees an Ed448 object after it has been used.
+
+    \param [in,out] key Pointer to the ed448_key object to free
+
+    _Example_
+    \code
+    ed448_key key;
+    // initialize key and perform secure exchanges
+    ...
+    wc_ed448_free(&key);
+    \endcode
+
+    \sa wc_ed448_init
+*/
+WOLFSSL_API
+void wc_ed448_free(ed448_key* key);
+
+/*!
+    \ingroup ED448
+
+    \brief This function imports a public ed448_key pair from a buffer
+    containing the public key. This function will handle both compressed and
+    uncompressed keys.
+
+    \return 0 Returned on successfully importing the ed448_key.
+    \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is
+    less than the size of an Ed448 key.
+
+    \param [in] in Pointer to the buffer containing the public key.
+    \param [in] inLen Length of the buffer containing the public key.
+    \param [in,out] key Pointer to the ed448_key object in which to store the
+    public key.
+
+    _Example_
+    \code
+    int ret;
+    byte pub[] = { initialize Ed448 public key };
+
+    ed_448 key;
+    wc_ed448_init_key(&key);
+    ret = wc_ed448_import_public(pub, sizeof(pub), &key);
+    if (ret != 0) {
+        // error importing key
+    }
+    \endcode
+
+    \sa wc_ed448_import_private_key
+    \sa wc_ed448_export_public
+*/
+WOLFSSL_API
+int wc_ed448_import_public(const byte* in, word32 inLen, ed448_key* key);
+
+/*!
+    \ingroup ED448
+
+    \brief This function imports an Ed448 private key only from a
+    buffer.
+
+    \return 0 Returned on successfully importing the Ed448 private key.
+    \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if
+    privSz is less than ED448_KEY_SIZE.
+
+    \param [in] priv Pointer to the buffer containing the private key.
+    \param [in] privSz Length of the private key.
+    \param [in,out] key Pointer to the ed448_key object in which to store the
+    imported private key.
+
+    _Example_
+    \code
+    int ret;
+    byte priv[] = { initialize with 57 byte private key };
+
+    ed448_key key;
+    wc_ed448_init_key(&key);
+    ret = wc_ed448_import_private_only(priv, sizeof(priv), &key);
+    if (ret != 0) {
+        // error importing private key
+    }
+    \endcode
+
+    \sa wc_ed448_import_public
+    \sa wc_ed448_import_private_key
+    \sa wc_ed448_export_private_only
+*/
+WOLFSSL_API
+int wc_ed448_import_private_only(const byte* priv, word32 privSz,
+                                 ed448_key* key);
+
+/*!
+    \ingroup ED448
+
+    \brief This function imports a public/private Ed448 key pair from a
+    pair of buffers. This function will handle both compressed and
+    uncompressed keys.
+
+    \return 0 Returned on successfully importing the Ed448 key.
+    \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if
+    either privSz is less than ED448_KEY_SIZE or pubSz is less than
+    ED448_PUB_KEY_SIZE.
+
+    \param [in] priv Pointer to the buffer containing the private key.
+    \param [in] privSz Length of the private key.
+    \param [in] pub Pointer to the buffer containing the public key.
+    \param [in] pubSz Length of the public key.
+    \param [in,out] key Pointer to the ed448_key object in which to store the
+    imported private/public key pair.
+
+    _Example_
+    \code
+    int ret;
+    byte priv[] = { initialize with 57 byte private key };
+    byte pub[]  = { initialize with the corresponding public key };
+
+    ed448_key key;
+    wc_ed448_init_key(&key);
+    ret = wc_ed448_import_private_key(priv, sizeof(priv), pub, sizeof(pub),
+            &key);
+    if (ret != 0) {
+        // error importing key
+    }
+    \endcode
+
+    \sa wc_ed448_import_public
+    \sa wc_ed448_import_private_only
+    \sa wc_ed448_export_private
+*/
+WOLFSSL_API
+int wc_ed448_import_private_key(const byte* priv, word32 privSz,
+                               const byte* pub, word32 pubSz, ed448_key* key);
+
+/*!
+    \ingroup ED448
+
+    \brief This function exports the private key from an ed448_key
+    structure. It stores the public key in the buffer out, and sets the bytes
+    written to this buffer in outLen.
+
+    \return 0 Returned upon successfully exporting the public key.
+    \return BAD_FUNC_ARG Returned if any of the input values evaluate to NULL.
+    \return BUFFER_E Returned if the buffer provided is not large enough to
+    store the private key. Upon returning this error, the function sets the
+    size required in outLen.
+
+    \param [in] key Pointer to an ed448_key structure from which to export the
+    public key.
+    \param [out] out Pointer to the buffer in which to store the public key.
+    \param [in,out] outLen Pointer to a word32 object with the size available
+    in out. Set with the number of bytes written to out after successfully
+    exporting the public key.
+
+    _Example_
+    \code
+    int ret;
+    ed448_key key;
+    // initialize key, make key
+
+    char pub[57];
+    word32 pubSz = sizeof(pub);
+
+    ret = wc_ed448_export_public(&key, pub, &pubSz);
+    if (ret != 0) {
+        // error exporting public key
+    }
+    \endcode
+
+    \sa wc_ed448_import_public
+    \sa wc_ed448_export_private_only
+*/
+WOLFSSL_API
+int wc_ed448_export_public(ed448_key*, byte* out, word32* outLen);
+
+/*!
+    \ingroup ED448
+
+    \brief This function exports only the private key from an ed448_key
+    structure. It stores the private key in the buffer out, and sets
+    the bytes written to this buffer in outLen.
+
+    \return 0 Returned upon successfully exporting the private key.
+    \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL.
+    \return BUFFER_E Returned if the buffer provided is not large enough
+    to store the private key.
+
+    \param [in] key Pointer to an ed448_key structure from which to export
+    the private key.
+    \param [out] out Pointer to the buffer in which to store the private key.
+    \param [in,out] outLen Pointer to a word32 object with the size available in
+    out. Set with the number of bytes written to out after successfully
+    exporting the private key.
+
+    _Example_
+    \code
+    int ret;
+    ed448_key key;
+    // initialize key, make key
+
+    char priv[57]; // 57 bytes because only private key
+    word32 privSz = sizeof(priv);
+    ret = wc_ed448_export_private_only(&key, priv, &privSz);
+    if (ret != 0) {
+        // error exporting private key
+    }
+    \endcode
+
+    \sa wc_ed448_export_public
+    \sa wc_ed448_import_private_key
+*/
+WOLFSSL_API
+int wc_ed448_export_private_only(ed448_key* key, byte* out, word32* outLen);
+
+/*!
+    \ingroup ED448
+
+    \brief This function exports the key pair from an ed448_key
+    structure. It stores the key pair in the buffer out, and sets
+    the bytes written to this buffer in outLen.
+
+    \return 0 Returned upon successfully exporting the key pair.
+    \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL.
+    \return BUFFER_E Returned if the buffer provided is not large enough
+    to store the key pair.
+
+    \param [in] key Pointer to an ed448_key structure from which to export
+    the key pair.
+    \param [out] out Pointer to the buffer in which to store the key pair.
+    \param [in,out] outLen Pointer to a word32 object with the size available in
+    out. Set with the number of bytes written to out after successfully
+    exporting the key pair.
+
+    _Example_
+    \code
+    ed448_key key;
+    wc_ed448_init(&key);
+
+    WC_RNG rng;
+    wc_InitRng(&rng);
+
+    wc_ed448_make_key(&rng, 57, &key); // initialize 57 byte Ed448 key
+
+    byte out[114]; // out needs to be a sufficient buffer size
+    word32 outLen = sizeof(out);
+    int key_size = wc_ed448_export_private(&key, out, &outLen);
+    if (key_size == BUFFER_E) {
+        // Check size of out compared to outLen to see if function reset outLen
+    }
+    \endcode
+
+    \sa wc_ed448_import_private
+    \sa wc_ed448_export_private_only
+*/
+WOLFSSL_API
+int wc_ed448_export_private(ed448_key* key, byte* out, word32* outLen);
+
+/*!
+    \ingroup ED448
+
+    \brief This function exports the private and public key separately from an
+    ed448_key structure. It stores the private key in the buffer priv, and sets
+    the bytes written to this buffer in privSz. It stores the public key in the
+    buffer pub, and sets the bytes written to this buffer in pubSz.
+
+    \return 0 Returned upon successfully exporting the key pair.
+    \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL.
+    \return BUFFER_E Returned if the buffer provided is not large enough
+    to store the key pair.
+
+    \param [in] key Pointer to an ed448_key structure from which to export
+    the key pair.
+    \param [out] priv Pointer to the buffer in which to store the private key.
+    \param [in,out] privSz Pointer to a word32 object with the size available in
+    out. Set with the number of bytes written to out after successfully
+    exporting the private key.
+    \param [out] pub Pointer to the buffer in which to store the public key.
+    \param [in,out] pubSz Pointer to a word32 object with the size available in
+    out. Set with the number of bytes written to out after successfully
+    exporting the public key.
+
+    _Example_
+    \code
+    int ret;
+    ed448_key key;
+    // initialize key, make key
+
+    char pub[57];
+    word32 pubSz = sizeof(pub);
+    char priv[57];
+    word32 privSz = sizeof(priv);
+
+    ret = wc_ed448_export_key(&key, priv, &pubSz, pub, &pubSz);
+    if (ret != 0) {
+        // error exporting private and public key
+    }
+    \endcode
+
+    \sa wc_ed448_export_private
+    \sa wc_ed448_export_public
+*/
+WOLFSSL_API
+int wc_ed448_export_key(ed448_key* key,
+                          byte* priv, word32 *privSz,
+                          byte* pub, word32 *pubSz);
+
+/*!
+    \ingroup ED448
+
+    \brief This function checks the public key in ed448_key structure matches
+    the private key.
+
+    \return 0 Returned if the private and public key matched.
+    \return BAD_FUNC_ARGS Returned if the given key is NULL.
+
+    \param [in] key Pointer to an ed448_key structure holding a private and
+    public key.
+
+    _Example_
+    \code
+    int ret;
+    byte priv[] = { initialize with 57 byte private key };
+    byte pub[]  = { initialize with the corresponding public key };
+
+    ed448_key key;
+    wc_ed448_init_key(&key);
+    wc_ed448_import_private_key(priv, sizeof(priv), pub, sizeof(pub), &key);
+    ret = wc_ed448_check_key(&key);
+    if (ret != 0) {
+        // error checking key
+    }
+    \endcode
+
+    \sa wc_ed448_import_private_key
+*/
+WOLFSSL_API
+int wc_ed448_check_key(ed448_key* key);
+
+
+/*!
+    \ingroup ED448
+
+    \brief This function returns the size of an Ed448 private key - 57 bytes.
+
+    \return ED448_KEY_SIZE The size of a valid private key (57 bytes).
+    \return BAD_FUNC_ARGS Returned if the given key is NULL.
+
+    \param [in] key Pointer to an ed448_key structure for which to get the
+    key size.
+
+    _Example_
+    \code
+    int keySz;
+    ed448_key key;
+    // initialize key, make key
+    keySz = wc_ed448_size(&key);
+    if (keySz == 0) {
+        // error determining key size
+    }
+    \endcode
+
+    \sa wc_ed448_make_key
+*/
+WOLFSSL_API
+int wc_ed448_size(ed448_key* key);
+
+/*!
+    \ingroup ED448
+
+    \brief This function returns the private key size (secret + public) in
+    bytes.
+
+    \return ED448_PRV_KEY_SIZE The size of the private key (114 bytes).
+    \return BAD_FUNC_ARG Returns if key argument is NULL.
+
+    \param [in] key Pointer to an ed448_key structure for which to get the
+    key size.
+
+    _Example_
+    \code
+    ed448_key key;
+    wc_ed448_init(&key);
+
+    WC_RNG rng;
+    wc_InitRng(&rng);
+
+    wc_ed448_make_key(&rng, 57, &key); // initialize 57 byte Ed448 key
+    int key_size = wc_ed448_priv_size(&key);
+    \endcode
+
+    \sa wc_ed448_pub_size
+*/
+WOLFSSL_API
+int wc_ed448_priv_size(ed448_key* key);
+
+/*!
+    \ingroup ED448
+
+    \brief This function returns the compressed key size in bytes (public key).
+
+    \return ED448_PUB_KEY_SIZE The size of the compressed public key (57 bytes).
+    \return BAD_FUNC_ARG Returns if key argument is NULL.
+
+    \param [in] key Pointer to an ed448_key structure for which to get the
+    key size.
+
+    _Example_
+    \code
+    ed448_key key;
+    wc_ed448_init(&key);
+    WC_RNG rng;
+    wc_InitRng(&rng);
+
+    wc_ed448_make_key(&rng, 57, &key); // initialize 57 byte Ed448 key
+    int key_size = wc_ed448_pub_size(&key);
+    \endcode
+
+    \sa wc_ed448_priv_size
+*/
+WOLFSSL_API
+int wc_ed448_pub_size(ed448_key* key);
+
+/*!
+    \ingroup ED448
+
+    \brief This function returns the size of an Ed448 signature (114 in bytes).
+
+    \return ED448_SIG_SIZE The size of an Ed448 signature (114 bytes).
+    \return BAD_FUNC_ARG Returns if key argument is NULL.
+
+    \param [in] key Pointer to an ed448_key structure for which to get the
+    signature size.
+
+    _Example_
+    \code
+    int sigSz;
+    ed448_key key;
+    // initialize key, make key
+
+    sigSz = wc_ed448_sig_size(&key);
+    if (sigSz == 0) {
+        // error determining sig size
+    }
+    \endcode
+
+    \sa wc_ed448_sign_msg
+*/
+WOLFSSL_API
+int wc_ed448_sig_size(ed448_key* key);

wolfcrypt/src/ed25519.c

@@ -61,7 +61,7 @@ int wc_ed25519_make_public(ed25519_key* key, unsigned char* pubKey,
     ge_p3 A;
 #endif
 
-    if (key == NULL || pubKeySz != ED25519_PUB_KEY_SIZE)
+    if (key == NULL || pubKey == NULL || pubKeySz != ED25519_PUB_KEY_SIZE)
         ret = BAD_FUNC_ARG;
 
     if (ret == 0)

wolfcrypt/src/ed448.c

@@ -67,7 +67,7 @@ int wc_ed448_make_public(ed448_key* key, unsigned char* pubKey, word32 pubKeySz)
     byte  az[ED448_PRV_KEY_SIZE];
     ge448_p2 A;
 
-    if ((key == NULL) || (pubKeySz != ED448_PUB_KEY_SIZE)) {
+    if ((key == NULL) || (pubKey == NULL) || (pubKeySz != ED448_PUB_KEY_SIZE)) {
         ret = BAD_FUNC_ARG;
     }