From 6bc4bfd7f2a8c4fd34c4cc0e5460b64abbb50f4e Mon Sep 17 00:00:00 2001 From: Ethan Looney Date: Thu, 23 Jul 2020 13:25:18 -0700 Subject: [PATCH] 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