wolfSSL/wolfssl
1
0
Fork 1
mirror of https://github.com/wolfSSL/wolfssl.git synced 2025-07-30 02:37:28 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4557 from LinuxJedi/doxygen-fixes

Browse Source 
Fix up some Doxygen issues for 1.9
This commit is contained in:
David Garske
2021-11-10 11:29:47 -08:00
committed by GitHub
parent 8e0fdc64be 231546dacc
commit b2ba6f94af
10 changed files with 70 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/dox_comments/header_files/asn_public.h
View File

@ -158,7 +158,7 @@ WOLFSSL_API int wc_MakeCertReq(Cert*, byte* derBuffer, word32 derSz,
word32 certSz;
certSz = wc_SignCert(myCert.bodySz, myCert.sigType,derCert,FOURK_BUF,
&key, NULL,
&rng);
&rng);
\endcode
\sa wc_InitCert

4
doc/dox_comments/header_files/des3.h
View File

@ -178,7 +178,7 @@ WOLFSSL_API int wc_Des_EcbEncrypt(Des* des, byte* out,
\param sz length of the plaintext to encrypt
_Example_
/code
\code
Des3 enc; // Des3 structure used for encryption
// initialize enc with wc_Des3_SetKey, use mode DES_ENCRYPTION
@ -188,7 +188,7 @@ WOLFSSL_API int wc_Des_EcbEncrypt(Des* des, byte* out,
if ( wc_Des3_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) {
// error encrypting message
}
/endcode
\endcode
\sa wc_Des3_SetKey
*/

12
doc/dox_comments/header_files/dh.h
View File

@ -240,15 +240,15 @@ WOLFSSL_API int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g
\return BUFFER_E Returned if there is inadequate space in p or g to
store the parsed parameters
\parma input pointer to a buffer containing a DER formatted
\param input pointer to a buffer containing a DER formatted
Diffie-Hellman certificate to parse
\parma inSz size of the input buffer
\parma p pointer to a buffer in which to store the parsed prime
\parma pInOutSz pointer to a word32 object containing the available
\param inSz size of the input buffer
\param p pointer to a buffer in which to store the parsed prime
\param pInOutSz pointer to a word32 object containing the available
size in the p buffer. Will be overwritten with the number of bytes
written to the buffer after completing the function call
\parma g pointer to a buffer in which to store the parsed base
\parma gInOutSz pointer to a word32 object containing the available size
\param g pointer to a buffer in which to store the parsed base
\param gInOutSz pointer to a word32 object containing the available size
in the g buffer. Will be overwritten with the number of bytes written to
the buffer after completing the function call

4
doc/dox_comments/header_files/ecc.h
View File

@ -505,7 +505,7 @@ int wc_ecc_verify_hash(const byte* sig, word32 siglen, const byte* hash,
\brief Verify an ECC signature. Result is written to stat.
1 is valid, 0 is invalid.
Note: Do not use the return value to test for valid. Only use stat.
Note: Do not use the return value to test for valid. Only use stat.
\return MP_OKAY If successful (even if the signature is not valid)
\return ECC_BAD_ARG_E Returns if arguments are null or if
@ -1107,7 +1107,7 @@ int wc_ecc_import_x963(const byte* in, word32 inLen, ecc_key* key);
through the HAVE_COMP_KEY option.
\return 0 Returned on successfully importing the ecc_key
NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at compile
NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at compile
time, but the key is stored in compressed format
\return ECC_BAD_ARG_E Returned if in or key evaluate to NULL, or the
inLen is even (according to the x9.63 standard, the key must be odd)

2
doc/dox_comments/header_files/evp.h
View File

@ -205,7 +205,7 @@ WOLFSSL_API int wolfSSL_EVP_EncryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx,
EVP_aes_128_ cbc(), e, key, iv, 1));
printf("cipher init ex success ret = %d\n", wolfSSL_EVP_DecryptInit_ex(ctx,
EVP_aes_128_c bc(), e, key, iv, 1));
// free resources
// free resources
\endcode
\sa wolfSSL_EVP_CIPHER_CTX_new

6
doc/dox_comments/header_files/iotsafe.h
View File

@ -225,8 +225,8 @@ WOLFSSL_API int wc_iotsafe_ecc_sign_hash(byte *in, word32 inlen, byte *out, word
\ingroup IoTSafe
\brief Verify an ECC signature against a pre-computed 256-bit HASH, using a public key previously stored, or pre-provisioned,
in the IoT-Safe applet. Result is written to res. 1 is valid, 0 is invalid.
Note: Do not use the return value to test for valid. Only use res.
Note: Do not use the return value to test for valid. Only use res.
\return 0 upon success (even if the signature is not valid)
\return < 0 in case of failure.
@ -235,7 +235,7 @@ Note: Do not use the return value to test for valid. Only use res.
\param hashlen The length of the hash (octets)
\param res Result of signature, 1==valid, 0==invalid
\param key_id The id of the slot where the public ECC key is stored in the IoT-Safe applet
\sa wc_iotsafe_ecc_sign_hash
\sa wc_iotsafe_ecc_gen_k

65
doc/dox_comments/header_files/rsa.h
View File

@ -422,10 +422,8 @@ WOLFSSL_API int wc_RsaPSS_Sign(const byte* in, word32 inLen, byte* out,
\ingroup RSA
\brief Decrypt input signature to verify that the message was signed by key.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
    is enabled.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
\return Success Length of text on no error.
\return MEMORY_E memory exception.
@ -476,11 +474,11 @@ WOLFSSL_API int wc_RsaPSS_Verify(byte* in, word32 inLen, byte* out,
/*!
\ingroup RSA
\brief Decrypt input signature to verify that the message was signed by RSA key.
\brief Decrypt input signature to verify that the message was signed by RSA
key.
The output uses the same byte array as the input.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
    is enabled.
is enabled.
\return >0 Length of text.
\return <0 An error occurred.
@ -538,11 +536,9 @@ WOLFSSL_API int wc_RsaPSS_VerifyInline(byte* in, word32 inLen, byte** out,
\brief Verify the message signed with RSA-PSS.
Salt length is equal to hash length.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
    is enabled.
\return the length of the PSS data on success and negative indicates failure.
\return the length of the PSS data on success and negative indicates failure.
\return MEMORY_E memory exception.
\param in The byte array to be decrypted.
@ -572,7 +568,7 @@ WOLFSSL_API int wc_RsaPSS_VerifyInline(byte* in, word32 inLen, byte** out,
digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
} else return -1;
if (ret == 0) {
ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
@ -609,11 +605,9 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheck(byte* in, word32 inLen,
\ingroup RSA
\brief Verify the message signed with RSA-PSS.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
    is enabled.
\return the length of the PSS data on success and negative indicates failure.
\return the length of the PSS data on success and negative indicates failure.
\return MEMORY_E memory exception.
\param in The byte array to be decrypted.
@ -625,8 +619,8 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheck(byte* in, word32 inLen,
\param hash Hash algorithm.
\param mgf Mask generation function.
\param saltLen Length of salt used. RSA_PSS_SALT_LEN_DEFAULT (-1) indicates salt
length is the same as the hash length. RSA_PSS_SALT_LEN_DISCOVER
indicates salt length is determined from the data.
length is the same as the hash length. RSA_PSS_SALT_LEN_DISCOVER
indicates salt length is determined from the data.
\param key Public RSA key.
@ -647,7 +641,7 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheck(byte* in, word32 inLen,
digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
} else return -1;
if (ret == 0) {
ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
@ -684,11 +678,10 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheck_ex(byte* in, word32 inLen,
\ingroup RSA
\brief Verify the message signed with RSA-PSS.
The input buffer is reused for the output buffer.
The input buffer is reused for the output buffer.
Salt length is equal to hash length.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
    is enabled.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
\return the length of the PSS data on success and negative indicates failure.
@ -718,7 +711,7 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheck_ex(byte* in, word32 inLen,
digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
} else return -1;
if (ret == 0) {
ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
@ -753,10 +746,8 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheckInline(byte* in, word32 inLen, byte** out,
\ingroup RSA
\brief Verify the message signed with RSA-PSS.
The input buffer is reused for the output buffer.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
    is enabled.
The input buffer is reused for the output buffer.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
\return the length of the PSS data on success and negative indicates failure.
@ -768,8 +759,8 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheckInline(byte* in, word32 inLen, byte** out,
\param hash The hash type to be in message
\param mgf Mask Generation Function Identifiers
\param saltLen Length of salt used. RSA_PSS_SALT_LEN_DEFAULT (-1) indicates salt
length is the same as the hash length. RSA_PSS_SALT_LEN_DISCOVER
indicates salt length is determined from the data.
length is the same as the hash length. RSA_PSS_SALT_LEN_DISCOVER
indicates salt length is determined from the data.
\param key The key to use for verification.
_Example_
@ -789,7 +780,7 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheckInline(byte* in, word32 inLen, byte** out,
digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
} else return -1;
if (ret == 0) {
ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
@ -826,20 +817,18 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheckInline_ex(byte* in, word32 inLen, byte** o
\brief Checks the PSS data to ensure that the signature matches.
Salt length is equal to hash length.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
    is enabled.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
\return BAD_PADDING_E when the PSS data is invalid, BAD_FUNC_ARG when
NULL is passed in to in or sig or inSz is not the same as the hash
algorithm length and 0 on success.
\return MEMORY_E memory exception.
\param in Hash of the data that is being verified.
\param inSz Length of hash.
\param sig Buffer holding PSS data.
\param sigSz Size of PSS data.
\param hashType Hash algorithm.
\param in Hash of the data that is being verified.
\param inSz Length of hash.
\param sig Buffer holding PSS data.
\param sigSz Size of PSS data.
\param hashType Hash algorithm.
_Example_
\code

2
doc/dox_comments/header_files/srp.h
View File

@ -97,7 +97,7 @@ WOLFSSL_API int wc_SrpSetUsername(Srp* srp, const byte* username, word32 size);
\return 0 Success
\return BAD_FUNC_ARG Returns if srp, N, g, or salt is null or if nSz < gSz.
\return SRP_CALL_ORDER_E Returns if wc_SrpSetParams is called before
wc_SrpSetUsername.
wc_SrpSetUsername.
\return <0 Error
\param srp the Srp structure.

33
doc/dox_comments/header_files/ssl.h
View File

@ -4389,7 +4389,7 @@ WOLFSSL_API WOLFSSL_X509_NAME* wolfSSL_X509_get_subject_name(WOLFSSL_X509*);
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
_Example_
/code
\code
WOLFSSL* ssl;
...
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
@ -5226,7 +5226,7 @@ WOLFSSL_API int wolfSSL_CTX_use_psk_identity_hint(WOLFSSL_CTX*, const char*);
\return SSL_FAILURE returned if the WOLFSSL or Arrays structures are NULL.
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
\para hint a constant character pointer that holds the hint to be saved
\param hint a constant character pointer that holds the hint to be saved
in memory.
_Example_
@ -12545,13 +12545,32 @@ WOLFSSL_API WOLFSSL_ASN1_TIME* wolfSSL_X509_get_notBefore(WOLFSSL_X509*);
/*!
\ingroup IO
\brief This function is called on the client side and initiates an SSL/TLS handshake with a server. When this function is called, the underlying communication channel has already been set up.
wolfSSL_connect() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_connect() will return when the underlying I/O could not satisfy the needs of wolfSSL_connect to continue the handshake. In this case, a call to wolfSSL_get_error() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to wolfSSL_connect() when the underlying I/O is ready and wolfSSL will pick up where it left off. When using a non-blocking socket, nothing needs to be done, but select() can be used to check for the required condition.
If the underlying I/O is blocking, wolfSSL_connect() will only return once the handshake has been finished or an error occurred.
wolfSSL takes a different approach to certificate verification than OpenSSL does. The default policy for the client is to verify the server, this means that if you don't load CAs to verify the server you'll get a connect error, unable to verify (-155). It you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new(); Though it's not recommended.
\brief This function is called on the client side and initiates an SSL/TLS
handshake with a server. When this function is called, the underlying
communication channel has already been set up.
wolfSSL_connect() works with both blocking and non-blocking I/O. When the
underlying I/O is non-blocking, wolfSSL_connect() will return when the
underlying I/O could not satisfy the needs of wolfSSL_connect to continue
the handshake. In this case, a call to wolfSSL_get_error() will yield
either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process
must then repeat the call to wolfSSL_connect() when the underlying I/O is
ready and wolfSSL will pick up where it left off. When using a non-blocking
socket, nothing needs to be done, but select() can be used to check for the
required condition.
If the underlying I/O is blocking, wolfSSL_connect() will only return once
the handshake has been finished or an error occurred.
wolfSSL takes a different approach to certificate verification than OpenSSL
does. The default policy for the client is to verify the server, this
means that if you don't load CAs to verify the server you'll get a connect
error, unable to verify (-155). It you want to mimic OpenSSL behavior of
having SSL_connect succeed even if verifying the server fails and reducing
security you can do this by calling:
SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new();
Though it's not recommended.
\return SSL_SUCCESS If successful.
\return SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error().
\return SSL_FATAL_ERROR will be returned if an error occurred. To get a
more detailed error code, call wolfSSL_get_error().
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().

2
doc/dox_comments/header_files/wc_encrypt.h
View File

@ -141,7 +141,7 @@ WOLFSSL_API int wc_Des_CbcEncryptWithKey(byte* out,
a Des structure.
\return <0 Returned on any error during encryption.
\parma out Final encrypted data
\param out Final encrypted data
\param in Data to be encrypted, must be padded to Des block size.
\param sz Size of input buffer.
\param key Pointer to the key to use for encryption.