From 6bc4bfd7f2a8c4fd34c4cc0e5460b64abbb50f4e Mon Sep 17 00:00:00 2001 From: Ethan Looney Date: Thu, 23 Jul 2020 13:25:18 -0700 Subject: [PATCH 1/2] Added doxygen comments to include all missing ABI functions and changed footer date from 2017 to 2020 --- doc/dox_comments/header_files/ecc.h | 68 ++++++++++ doc/dox_comments/header_files/random.h | 60 +++++++++ doc/dox_comments/header_files/ssl.h | 172 +++++++++++++++++++++++++ doc/formats/html/footer.html | 2 +- 4 files changed, 301 insertions(+), 1 deletion(-) diff --git a/doc/dox_comments/header_files/ecc.h b/doc/dox_comments/header_files/ecc.h index 1128af9e4..a843d9b2e 100644 --- a/doc/dox_comments/header_files/ecc.h +++ b/doc/dox_comments/header_files/ecc.h @@ -149,6 +149,28 @@ int wc_ecc_make_key_ex(WC_RNG* rng, int keysize, ecc_key* key, int curve_id); WOLFSSL_API int wc_ecc_check_key(ecc_key* key); +/*! + \ingroup ECC + + \brief This function frees an ecc_key key after it has been used. + + \return int integer returned indicating wolfSSL error or success status. + + \param key pointer to the ecc_key object to free + + _Example_ + \code + // initialize key and perform secure exchanges + ... + wc_ecc_key_free(&key); + \endcode + + \sa wc_ecc_key_new + \sa wc_ecc_init_ex +*/ +WOLFSSL_API +int wc_ecc_key_free(ecc_key* key); + /*! \ingroup ECC @@ -541,6 +563,52 @@ int wc_ecc_verify_hash_ex(mp_int *r, mp_int *s, const byte* hash, WOLFSSL_API int wc_ecc_init(ecc_key* key); +/*! + \ingroup ECC + + \brief This function initializes an ecc_key object for future + use with message verification or key negotiation. + + \return 0 Returned upon successfully initializing the ecc_key object + \return MEMORY_E Returned if there is an error allocating memory + + \param key pointer to the ecc_key object to initialize + + _Example_ + \code + ecc_key key; + wc_ecc_init_ex(&key, heap, devId); + \endcode + + \sa wc_ecc_make_key + \sa wc_ecc_free + \sa wc_ecc_init +*/ +WOLFSSL_API +int wc_ecc_init_ex(ecc_key* key, void* heap, int devId); + +/*! + \ingroup ECC + + \brief This function uses a user defined heap and allocates space for the + key structure. + + \return 0 Returned upon successfully initializing the ecc_key object + \return MEMORY_E Returned if there is an error allocating memory + + + _Example_ + \code + wc_ecc_key_new(&heap); + \endcode + + \sa wc_ecc_make_key + \sa wc_ecc_key_free + \sa wc_ecc_init +*/ +WOLFSSL_API +ecc_key* wc_ecc_key_new(void* heap); + /*! \ingroup ECC diff --git a/doc/dox_comments/header_files/random.h b/doc/dox_comments/header_files/random.h index 366dc8908..9bd52c015 100644 --- a/doc/dox_comments/header_files/random.h +++ b/doc/dox_comments/header_files/random.h @@ -137,6 +137,36 @@ WOLFSSL_API int wc_InitRng(WC_RNG*); */ WOLFSSL_API int wc_RNG_GenerateBlock(WC_RNG*, byte*, word32 sz); +/*! + \ingroup Random + + \brief Creates a new random number. + + + \return rng on success + \return NULL on error + + + \param rng random number generator initialized with wc_InitRng + + _Example_ + \code + RNG rng; + byte nonce[] = { initialize nonce }; + word32 nonceSz = sizeof(nonce); + + wc_rng_new(&nonce, nonceSz, &heap); + + + \endcode + + \sa wc_InitRng + \sa wc_rng_free + \sa wc_FreeRng + \sa wc_RNG_HealthTest +*/ +WOLFSSL_API WC_RNG* wc_rng_new(byte* nonce, word32 nonceSz, void* heap) + /*! \ingroup Random @@ -211,6 +241,36 @@ WOLFSSL_API int wc_RNG_GenerateByte(WC_RNG*, byte*); */ WOLFSSL_API int wc_FreeRng(WC_RNG*); +/*! + \ingroup Random + + \brief Should be called when RNG no longer needed in order to securely + free rng. + + + \param rng random number generator initialized with wc_InitRng + + _Example_ + \code + RNG rng; + byte nonce[] = { initialize nonce }; + word32 nonceSz = sizeof(nonce); + + rng = wc_rng_new(&nonce, nonceSz, &heap); + + // use rng + + wc_rng_free(&rng); + + \endcode + + \sa wc_InitRng + \sa wc_rng_new + \sa wc_FreeRng + \sa wc_RNG_HealthTest +*/ +WOLFSSL_API WC_RNG* wc_rng_free(WC_RNG* rng); + /*! \ingroup Random diff --git a/doc/dox_comments/header_files/ssl.h b/doc/dox_comments/header_files/ssl.h index eb25908f0..fd07ec3cd 100644 --- a/doc/dox_comments/header_files/ssl.h +++ b/doc/dox_comments/header_files/ssl.h @@ -2698,6 +2698,72 @@ WOLFSSL_API void wolfSSL_load_error_strings(void); */ WOLFSSL_API int wolfSSL_library_init(void); +/*! + \brief This function sets the Device Id. + + \return WOLFSSL_SUCCESS upon success. + \return BAD_FUNC_ARG if ssl is NULL. + + \param ssl pointer to a SSL object, created with wolfSSL_new(). + + _Example_ + \code + WOLFSSL* ssl; + int DevId = -2; + + wolfSSL_SetDevId(ssl, devId); + + \endcode + + \sa wolfSSL_CTX_SetDevId + \sa wolfSSL_CTX_GetDevId +*/ +WOLFSSL_API int wolfSSL_SetDevId(WOLFSSL* ssl, int devId) + +/*! + \brief This function sets the Device Id. + + \return WOLFSSL_SUCCESS upon success. + \return BAD_FUNC_ARG if ssl is NULL. + + \param ssl pointer to a SSL object, created with wolfSSL_CTX_new(). + + _Example_ + \code + WOLFSSL_CTX* ctx; + int DevId = -2; + + wolfSSL_CTX_SetDevId(ctx, devId); + + \endcode + + \sa wolfSSL_SetDevId + \sa wolfSSL_CTX_GetDevId +*/ +WOLFSSL_API int wolfSSL_CTX_SetDevId(WOLFSSL_CTX* ctx, int devId) + +/*! + \brief This function retrieves the Device Id. + + \return devId upon success. + \return INVALID_DEVID if both ssl and ctx are NULL. + + \param ssl pointer to a SSL object, created with wolfSSL_CTX_new(). + + _Example_ + \code + WOLFSSL_CTX* ctx; + + wolfSSL_CTX_GetDevId(ctx, ssl); + + \endcode + + \sa wolfSSL_SetDevId + \sa wolfSSL_CTX_SetDevId + +*/ +WOLFSSL_API int wolfSSL_CTX_GetDevId(WOLFSSL_CTX* ctx, WOLFSSL* ssl); + /*! \ingroup Setup @@ -4423,6 +4489,31 @@ WOLFSSL_API int wolfSSL_X509_NAME_get_text_by_NID( */ WOLFSSL_API int wolfSSL_X509_get_signature_type(WOLFSSL_X509*); +/*! + \brief This function frees an external WOLFSSL_X509 structure. + + + \param x509 a pointer to the WOLFSSL_X509 struct. + + _Example_ + \code + WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL, + DYNAMIC_TYPE_X509) ; + + wolfSSL_X509_free(x509); + + \endcode + + \sa wolfSSL_X509_get_signature + \sa wolfSSL_X509_version + \sa wolfSSL_X509_get_der + \sa wolfSSL_X509_get_serial_number + \sa wolfSSL_X509_notBefore + \sa wolfSSL_X509_notAfter + +*/ +WOLFSSL_API void wolfSSL_X509_free(WOLFSSL_X509* x509); + /*! \ingroup CertsKeys @@ -4538,6 +4629,66 @@ WOLFSSL_API WOLFSSL_STACK* wolfSSL_X509_STORE_CTX_get_chain( WOLFSSL_API int wolfSSL_X509_STORE_set_flags(WOLFSSL_X509_STORE* store, unsigned long flag); +/*! + \ingroup CertsKeys + + \brief This function returns the value stored in the sigOID + member of the WOLFSSL_X509 structure. + + \return NULL returned if the WOLFSSL_X509 structure is NULL. + \return byte is returned that contains the notBeforeData. + + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + _Example_ + \code + WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, + DYNAMIC_TYPE_X509); + ... + byte notBeforeData = wolfSSL_X509_notBefore(x509); + + + \endcode + + \sa wolfSSL_X509_get_signature + \sa wolfSSL_X509_version + \sa wolfSSL_X509_get_der + \sa wolfSSL_X509_get_serial_number + \sa wolfSSL_X509_notAfter + \sa wolfSSL_X509_free +*/ +WOLFSSL_API const byte* wolfSSL_X509_notBefore(WOLFSSL_X509* x509); + +/*! + \ingroup CertsKeys + + \brief This function returns the value stored in the sigOID + member of the WOLFSSL_X509 structure. + + \return NULL returned if the WOLFSSL_X509 structure is NULL. + \return byte is returned that contains the notAfterData. + + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + _Example_ + \code + WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, + DYNAMIC_TYPE_X509); + ... + byte notAfterData = wolfSSL_X509_notAfter(x509); + + + \endcode + + \sa wolfSSL_X509_get_signature + \sa wolfSSL_X509_version + \sa wolfSSL_X509_get_der + \sa wolfSSL_X509_get_serial_number + \sa wolfSSL_X509_notBefore + \sa wolfSSL_X509_free +*/ +WOLFSSL_API const byte* wolfSSL_X509_notAfter(WOLFSSL_X509* x509); + /*! \ingroup Setup @@ -7604,6 +7755,27 @@ WOLFSSL_API int wolfSSL_DTLS_SetCookieSecret(WOLFSSL*, const unsigned char*, unsigned int); +/*! + \brief This function retrieves the Device Id. + + \return rng upon success. + \return NULL if ssl is NULL. + + \param ssl pointer to a SSL object, created with wolfSSL_CTX_new(). + + _Example_ + \code + WOLFSSL* ssl; + + wolfSSL_GetRNG(ssl); + + \endcode + + \sa wolfSSL_CTX_new_rng + +*/ +WOLFSSL_API WC_RNG* wolfSSL_GetRNG(WOLFSSL* ssl); + /*! \ingroup Setup diff --git a/doc/formats/html/footer.html b/doc/formats/html/footer.html index 996406d4b..d4f5a624a 100644 --- a/doc/formats/html/footer.html +++ b/doc/formats/html/footer.html @@ -32,7 +32,7 @@
-

Copyright © 2017 wolfSSL Inc.
All rights reserved.

+

Copyright © 2020 wolfSSL Inc.
All rights reserved.

Help and Support

    From 7b357cff39911198807404de71b424f3739ca7b5 Mon Sep 17 00:00:00 2001 From: Ethan Looney Date: Fri, 24 Jul 2020 12:54:29 -0700 Subject: [PATCH 2/2] Changed param's, examples and brief's --- doc/dox_comments/header_files/ecc.h | 9 +++--- doc/dox_comments/header_files/random.h | 8 ++++-- doc/dox_comments/header_files/ssl.h | 40 ++++++++++++++------------ 3 files changed, 32 insertions(+), 25 deletions(-) diff --git a/doc/dox_comments/header_files/ecc.h b/doc/dox_comments/header_files/ecc.h index a843d9b2e..3b2e268da 100644 --- a/doc/dox_comments/header_files/ecc.h +++ b/doc/dox_comments/header_files/ecc.h @@ -154,13 +154,12 @@ int wc_ecc_check_key(ecc_key* key); \brief This function frees an ecc_key key after it has been used. - \return int integer returned indicating wolfSSL error or success status. - \param key pointer to the ecc_key object to free + \param key pointer to the ecc_key structure to free _Example_ \code - // initialize key and perform secure exchanges + // initialize key and perform ECC operations ... wc_ecc_key_free(&key); \endcode @@ -169,7 +168,7 @@ int wc_ecc_check_key(ecc_key* key); \sa wc_ecc_init_ex */ WOLFSSL_API -int wc_ecc_key_free(ecc_key* key); +void wc_ecc_key_free(ecc_key* key); /*! \ingroup ECC @@ -573,6 +572,8 @@ int wc_ecc_init(ecc_key* key); \return MEMORY_E Returned if there is an error allocating memory \param key pointer to the ecc_key object to initialize + \param devId ID to use with async hardware + \param heap pointer to a heap identifier _Example_ \code diff --git a/doc/dox_comments/header_files/random.h b/doc/dox_comments/header_files/random.h index 9bd52c015..8e5f0eb13 100644 --- a/doc/dox_comments/header_files/random.h +++ b/doc/dox_comments/header_files/random.h @@ -140,14 +140,16 @@ WOLFSSL_API int wc_RNG_GenerateBlock(WC_RNG*, byte*, word32 sz); /*! \ingroup Random - \brief Creates a new random number. + \brief Creates a new WC_RNG structure. - \return rng on success + \return WC_RNG structure on success \return NULL on error - \param rng random number generator initialized with wc_InitRng + \param heap pointer to a heap identifier + \param nonce pointer to the buffer containing the nonce + \param nonceSz length of the nonce _Example_ \code diff --git a/doc/dox_comments/header_files/ssl.h b/doc/dox_comments/header_files/ssl.h index fd07ec3cd..184e52fb1 100644 --- a/doc/dox_comments/header_files/ssl.h +++ b/doc/dox_comments/header_files/ssl.h @@ -2699,12 +2699,13 @@ WOLFSSL_API void wolfSSL_load_error_strings(void); WOLFSSL_API int wolfSSL_library_init(void); /*! - \brief This function sets the Device Id. + \brief This function sets the Device Id at the WOLFSSL session level. \return WOLFSSL_SUCCESS upon success. \return BAD_FUNC_ARG if ssl is NULL. \param ssl pointer to a SSL object, created with wolfSSL_new(). + \param devId ID to use with async hardware _Example_ \code @@ -2721,12 +2722,13 @@ WOLFSSL_API int wolfSSL_library_init(void); WOLFSSL_API int wolfSSL_SetDevId(WOLFSSL* ssl, int devId) /*! - \brief This function sets the Device Id. + \brief This function sets the Device Id at the WOLFSSL_CTX context level. \return WOLFSSL_SUCCESS upon success. \return BAD_FUNC_ARG if ssl is NULL. - \param ssl pointer to a SSL object, created with wolfSSL_CTX_new(). + \param ssl pointer to a SSL object, created with wolfSSL_new(). + \param devId ID to use with async hardware _Example_ \code @@ -2748,7 +2750,8 @@ WOLFSSL_API int wolfSSL_CTX_SetDevId(WOLFSSL_CTX* ctx, int devId) \return devId upon success. \return INVALID_DEVID if both ssl and ctx are NULL. - \param ssl pointer to a SSL object, created with wolfSSL_CTX_new(). + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). + \param ssl pointer to a SSL object, created with wolfSSL_new(). _Example_ \code @@ -4490,14 +4493,14 @@ WOLFSSL_API int wolfSSL_X509_NAME_get_text_by_NID( WOLFSSL_API int wolfSSL_X509_get_signature_type(WOLFSSL_X509*); /*! - \brief This function frees an external WOLFSSL_X509 structure. + \brief This function frees a WOLFSSL_X509 structure. \param x509 a pointer to the WOLFSSL_X509 struct. _Example_ \code - WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL, + WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALOC(sizeof(WOLFSSL_X509), NULL, DYNAMIC_TYPE_X509) ; wolfSSL_X509_free(x509); @@ -4632,20 +4635,21 @@ WOLFSSL_API int wolfSSL_X509_STORE_set_flags(WOLFSSL_X509_STORE* store, /*! \ingroup CertsKeys - \brief This function returns the value stored in the sigOID - member of the WOLFSSL_X509 structure. + \brief This function the certificate "not before" validity encoded as + a byte array. + \return NULL returned if the WOLFSSL_X509 structure is NULL. \return byte is returned that contains the notBeforeData. - \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param x509 pointer to a WOLFSSL_X509 structure. _Example_ \code - WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, + WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, DYNAMIC_TYPE_X509); ... - byte notBeforeData = wolfSSL_X509_notBefore(x509); + byte* notBeforeData = wolfSSL_X509_notBefore(x509); \endcode @@ -4662,20 +4666,20 @@ WOLFSSL_API const byte* wolfSSL_X509_notBefore(WOLFSSL_X509* x509); /*! \ingroup CertsKeys - \brief This function returns the value stored in the sigOID - member of the WOLFSSL_X509 structure. + \brief This function the certificate "not after" validity encoded as + a byte array. \return NULL returned if the WOLFSSL_X509 structure is NULL. \return byte is returned that contains the notAfterData. - \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + \param x509 pointer to a WOLFSSL_X509 structure. _Example_ \code - WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, + WOLFSSL_X509* x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, DYNAMIC_TYPE_X509); ... - byte notAfterData = wolfSSL_X509_notAfter(x509); + byte* notAfterData = wolfSSL_X509_notAfter(x509); \endcode @@ -7756,12 +7760,12 @@ WOLFSSL_API int wolfSSL_DTLS_SetCookieSecret(WOLFSSL*, unsigned int); /*! - \brief This function retrieves the Device Id. + \brief This function retrieves the random number. \return rng upon success. \return NULL if ssl is NULL. - \param ssl pointer to a SSL object, created with wolfSSL_CTX_new(). + \param ssl pointer to a SSL object, created with wolfSSL_new(). _Example_ \code