diff --git a/doc/README_DOXYGEN b/doc/README_DOXYGEN index 871c6b79e..63e6b31cd 100644 --- a/doc/README_DOXYGEN +++ b/doc/README_DOXYGEN @@ -5,11 +5,11 @@ wolfSSL with Doxygen 1.8.13 cmake make git -latex-see below (With pdflatex included. However the pdflatex dependency can be removed by -setting USE_PDFLATEX to NO in the file "Doxyfile" located at +latex-see below (With pdflatex included. However the pdflatex dependency can be removed by +setting USE_PDFLATEX to NO in the file "Doxyfile" located at doc/formats/pdf/Doxyfile ) -The following texlive packages were installed when creating this +The following texlive packages were installed when creating this documentation on Linux Mint: sudo apt install texlive sudo apt install texlive-latex-extra @@ -24,7 +24,7 @@ additional dependencies will need to be met: If you are looking to just generate the html documentation and not interested in how to add your own just run one of the following commands from the main wolfssl directory: - + make dox (this option will make both html and pdf documentation) make dox-html (only html documentation) make dox-pdf (only pdf documentation) @@ -33,32 +33,32 @@ If it is the first time running one of the above commands the command will take some time to run. This is because the doxygen repository must be clones and then built along with the time taken to make the documentation. -Once documentation generation has completed to open the html use a browser to -open doc/html/index.html. To open the generated pdf looking for +Once documentation generation has completed to open the html use a browser to +open doc/html/index.html. To open the generated pdf looking for refman.pdf located and doc/refman.pdf. ---- Configure ---- Doxygen uses a file called "Doxyfile" to hold all its values for configuration. -If needed, to generate a fresh Doxfile run the command +If needed, to generate a fresh Doxfile run the command doxygen -g - + Once a Doxyfile is generate there are a few options to keep in mind. Below are some the the settings that are currently used: EXTRACT_ALL - - this option determines if all API are extracted or just API that is documented. - + - this option determines if all API are extracted or just API that is documented. + OPTIMIZE_OUTPUT_FOR_C - changes the look and naming schemes used in generated documentation. - + RECURSIVE - allows doxygen to search subdirectories in a library for documenting. - + GENERATE_LATEX - tells doxygen whether or not to generate LATEX documentation. The Latex @@ -67,17 +67,17 @@ Below are some the the settings that are currently used: ENABLE_PREPROCESSING - tells doxygen whether or not to ignore C/C++ preprocessors directives i.e #ifdef, #ifndef - + EXCLUDE - + - allows the user to specify files or directories to ignore when documenting. - + HTML_EXTRA_STYLESHEET - + -allows the user to specify their own css style sheet to use for the doxygen html. - + SHOW_USED_FILES and SHOW_FILES - + - when using groups it is important to keep these options set to yes otherwise functions with documentation that are not part of a group may fail to be included in the generated documentation. @@ -85,10 +85,10 @@ Below are some the the settings that are currently used: ---- Embedding Documentation ---- Doxygen API documentation should be placed in the doc/dox_comments/ -directory. The documentation should be stored in a file in this directory with the +directory. The documentation should be stored in a file in this directory with the same name of the file in which the API resides in the wolfssl repository. C code -header files (*.h) should be used when writing the API documentation. If API in a -file is being documented for the first time be sure to add the to the top of the +header files (*.h) should be used when writing the API documentation. If API in a +file is being documented for the first time be sure to add the to the top of the original file: /*! @@ -100,7 +100,7 @@ When specifying a specific file with the \file command be sure to include part o the file's path so that it is a unique name. This allows for linking to files even when multiple files share the same name. -To ensure that doxygen documents a specific API in to a desired module be sure +To ensure that doxygen documents a specific API in to a desired module be sure to include that module's name in the \ingroup. The current modules to choose from are as follows but new group can be made: @@ -139,7 +139,7 @@ are as follows but new group can be made: \ingroup IO \ingroup Debug -If one of the above modules/ groups does not fit a desired function then a new +If one of the above modules/ groups does not fit a desired function then a new group will need to be created. To do this include add a new group definition to the doxygen_groups.h file located at documentation/formats/pdf/doxygen_groups.h @@ -148,22 +148,22 @@ to the doxygen_groups.h file located at documentation/formats/pdf/doxygen_groups */ The general outline when documenting within the wolfssl library in doxygen should -look like as follows: +look like as follows: /*! \ingroup //if API should be in a separate module - + \brief - + \return // each return will need \return. - + \param // stands for parameter, each parameter will need \param. - + _Example_ \code // any example code here \endcode - + \sa // stands for see also. Each API reference here should begin with \sa \sa \sa @@ -174,5 +174,5 @@ When adding new documentation be sure to keep the sections, \ingroup, \brief, doxygen attempts to generate documentation the sections do not overlap each other and produce errors (this is especially important when the latex is being generated). Once finished creating new documentation it is highly recommended to generate new -html and pdf to ensure no errors were introduced that prevent documentation +html and pdf to ensure no errors were introduced that prevent documentation generation and that the documentation shows up correctly. diff --git a/doc/check_api.sh b/doc/check_api.sh index 4b6aa8b77..2d38390ab 100755 --- a/doc/check_api.sh +++ b/doc/check_api.sh @@ -3,7 +3,7 @@ ls ./dox_comments/header_files/ | while read h_file; do grep -P -h -z -o 'WOLFSSL_API(\n|\s|[^;])*;' ./dox_comments/header_files/$h_file | - tr '\n' ' ' | + tr '\n' ' ' | sed 's/\\n//g' | sed 's/ \+/ /g' | sed 's/\x00/\n/g' > dox_api.txt @@ -13,11 +13,11 @@ while read h_file; do echo "Checking: $h_file_path" grep -P -h -z -o 'WOLFSSL_API(\n|\s|[^;])*;' "$h_file_path" | sed 's/#.*/ /g' | - tr '\n' ' ' | + tr '\n' ' ' | sed 's/\\n//g' | sed 's/ \+/ /g' | sed 's/\x00/\n/g' > wolf_api.txt - + api_count="$(wc -l < dox_api.txt)" match_count="$(grep -Ff dox_api.txt wolf_api.txt | wc -l)" if [ "$api_count" != "$match_count" ]; then @@ -36,7 +36,7 @@ while read h_file; do fi done || exit 1 echo 'Next...\n' - + done || exit 1 rm dox_api.txt diff --git a/doc/dox_comments/header_files/aes.h b/doc/dox_comments/header_files/aes.h index 8c86fe47d..862f7a778 100644 --- a/doc/dox_comments/header_files/aes.h +++ b/doc/dox_comments/header_files/aes.h @@ -1,30 +1,30 @@ /*! \ingroup AES - \brief This function initializes an AES structure by setting the key and + \brief This function initializes an AES structure by setting the key and then setting the initialization vector. - + \return 0 On successfully setting key and initialization vector. \return BAD_FUNC_ARG Returned if key length is invalid. - + \param aes pointer to the AES structure to modify \param key 16, 24, or 32 byte secret key for encryption and decryption \param len length of the key passed in \param iv pointer to the initialization vector used to initialize the key - \param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or + \param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or AES_DECRYPTION to decrypt. - + _Example_ \code Aes enc; int ret = 0; byte key[] = { some 16, 24 or 32 byte key }; byte iv[] = { some 16 byte iv }; - if (ret = wc_AesSetKey(&enc, key, AES_BLOCK_SIZE, iv, + if (ret = wc_AesSetKey(&enc, key, AES_BLOCK_SIZE, iv, AES_ENCRYPTION) != 0) { // failed to set aes key } \endcode - + \sa wc_AesSetKeyDirect \sa wc_AesSetIV */ @@ -33,18 +33,18 @@ WOLFSSL_API int wc_AesSetKey(Aes* aes, const byte* key, word32 len, /*! \ingroup AES - \brief This function sets the initialization vector for a - particular AES object. The AES object should be initialized before + \brief This function sets the initialization vector for a + particular AES object. The AES object should be initialized before calling this function. - + \return 0 On successfully setting initialization vector. \return BAD_FUNC_ARG Returned if AES pointer is NULL. - - \param aes pointer to the AES structure on which to set the + + \param aes pointer to the AES structure on which to set the initialization vector - \param iv initialization vector used to initialize the AES structure. + \param iv initialization vector used to initialize the AES structure. If the value is NULL, the default action initializes the iv to 0. - + _Example_ \code Aes enc; @@ -54,7 +54,7 @@ WOLFSSL_API int wc_AesSetKey(Aes* aes, const byte* key, word32 len, // failed to set aes iv } \endcode - + \sa wc_AesSetKeyDirect \sa wc_AesSetKey */ @@ -62,27 +62,27 @@ WOLFSSL_API int wc_AesSetIV(Aes* aes, const byte* iv); /*! \ingroup AES - \brief Encrypts a plaintext message from the input buffer in, and places - the resulting cipher text in the output buffer out using cipher block - chaining with AES. This function requires that the AES object has been - initialized by calling AesSetKey before a message is able to be encrypted. - This function assumes that the input message is AES block length aligned. - PKCS#7 style padding should be added beforehand. This differs from the - OpenSSL AES-CBC methods which add the padding for you. To make the wolfSSL - function and equivalent OpenSSL functions interoperate, one should specify - the -nopad option in the OpenSSL command line function so that it behaves - like the wolfSSL AesCbcEncrypt method and does not add extra padding + \brief Encrypts a plaintext message from the input buffer in, and places + the resulting cipher text in the output buffer out using cipher block + chaining with AES. This function requires that the AES object has been + initialized by calling AesSetKey before a message is able to be encrypted. + This function assumes that the input message is AES block length aligned. + PKCS#7 style padding should be added beforehand. This differs from the + OpenSSL AES-CBC methods which add the padding for you. To make the wolfSSL + function and equivalent OpenSSL functions interoperate, one should specify + the -nopad option in the OpenSSL command line function so that it behaves + like the wolfSSL AesCbcEncrypt method and does not add extra padding during encryption. \return 0 On successfully encrypting message. \return BAD_ALIGN_E: Returned on block align error - + \param aes pointer to the AES object used to encrypt data - \param out pointer to the output buffer in which to store the ciphertext + \param out pointer to the output buffer in which to store the ciphertext of the encrypted message \param in pointer to the input buffer containing message to be encrypted \param sz size of input message - + _Example_ \code Aes enc; @@ -95,7 +95,7 @@ WOLFSSL_API int wc_AesSetIV(Aes* aes, const byte* iv); // block align error } \endcode - + \sa wc_AesSetKey \sa wc_AesSetIV \sa wc_AesCbcDecrypt @@ -104,29 +104,29 @@ WOLFSSL_API int wc_AesCbcEncrypt(Aes* aes, byte* out, const byte* in, word32 sz); /*! - \ingroup AES - \brief Decrypts a cipher from the input buffer in, and places the - resulting plain text in the output buffer out using cipher block chaining - with AES. This function requires that the AES structure has been - initialized by calling AesSetKey before a message is able to be decrypted. - This function assumes that the original message was AES block length - aligned. This differs from the OpenSSL AES-CBC methods which do not - require alignment as it adds PKCS#7 padding automatically. To make the - wolfSSL function and equivalent OpenSSL functions interoperate, one - should specify the -nopad option in the OpenSSL command line function - so that it behaves like the wolfSSL AesCbcEncrypt method and does not + \ingroup AES + \brief Decrypts a cipher from the input buffer in, and places the + resulting plain text in the output buffer out using cipher block chaining + with AES. This function requires that the AES structure has been + initialized by calling AesSetKey before a message is able to be decrypted. + This function assumes that the original message was AES block length + aligned. This differs from the OpenSSL AES-CBC methods which do not + require alignment as it adds PKCS#7 padding automatically. To make the + wolfSSL function and equivalent OpenSSL functions interoperate, one + should specify the -nopad option in the OpenSSL command line function + so that it behaves like the wolfSSL AesCbcEncrypt method and does not create errors during decryption. \return 0 On successfully decrypting message. \return BAD_ALIGN_E Returned on block align error. - + \param aes pointer to the AES object used to decrypt data. - \param out pointer to the output buffer in which to store the plain text + \param out pointer to the output buffer in which to store the plain text of the decrypted message. - \param in pointer to the input buffer containing cipher text to be + \param in pointer to the input buffer containing cipher text to be decrypted. \param sz size of input message. - + _Example_ \code Aes dec; @@ -139,7 +139,7 @@ WOLFSSL_API int wc_AesCbcEncrypt(Aes* aes, byte* out, // block align error } \endcode - + \sa wc_AesSetKey \sa wc_AesCbcEncrypt */ @@ -148,44 +148,44 @@ WOLFSSL_API int wc_AesCbcDecrypt(Aes* aes, byte* out, /*! \ingroup AES - \brief Encrypts/Decrypts a message from the input buffer in, and places - the resulting cipher text in the output buffer out using CTR mode with - AES. This function is only enabled if WOLFSSL_AES_COUNTER is enabled at - compile time. The AES structure should be initialized through AesSetKey - before calling this function. Note that this function is used for both - decryption and encryption. _NOTE:_ Regarding using same API for encryption - and decryption. User should differentiate between Aes structures + \brief Encrypts/Decrypts a message from the input buffer in, and places + the resulting cipher text in the output buffer out using CTR mode with + AES. This function is only enabled if WOLFSSL_AES_COUNTER is enabled at + compile time. The AES structure should be initialized through AesSetKey + before calling this function. Note that this function is used for both + decryption and encryption. _NOTE:_ Regarding using same API for encryption + and decryption. User should differentiate between Aes structures for encrypt/decrypt. - + \return int integer values corresponding to wolfSSL error or success status - + \param aes pointer to the AES object used to decrypt data - \param out pointer to the output buffer in which to store the cipher + \param out pointer to the output buffer in which to store the cipher text of the encrypted message \param in pointer to the input buffer containing plain text to be encrypted \param sz size of the input plain text - + _Example_ \code Aes enc; Aes dec; - // initialize enc and dec with AesSetKeyDirect, using direction + // initialize enc and dec with AesSetKeyDirect, using direction AES_ENCRYPTION - // since the underlying API only calls Encrypt and by default calling + // since the underlying API only calls Encrypt and by default calling encrypt on // a cipher results in a decryption of the cipher - - byte msg[AES_BLOCK_SIZE * n]; //n being a positive integer making msg + + byte msg[AES_BLOCK_SIZE * n]; //n being a positive integer making msg some multiple of 16 bytes // fill plain with message text byte cipher[AES_BLOCK_SIZE * n]; byte decrypted[AES_BLOCK_SIZE * n]; wc_AesCtrEncrypt(&enc, cipher, msg, sizeof(msg)); // encrypt plain - wc_AesCtrEncrypt(&dec, decrypted, cipher, sizeof(cipher)); + wc_AesCtrEncrypt(&dec, decrypted, cipher, sizeof(cipher)); // decrypt cipher text \endcode - + \sa wc_AesSetKey */ WOLFSSL_API int wc_AesCtrEncrypt(Aes* aes, byte* out, @@ -193,19 +193,19 @@ WOLFSSL_API int wc_AesCtrEncrypt(Aes* aes, byte* out, /*! \ingroup AES - \brief This function is a one-block encrypt of the input block, in, into - the output block, out. It uses the key and iv (initialization vector) - of the provided AES structure, which should be initialized with - wc_AesSetKey before calling this function. It is only enabled if the - configure option WOLFSSL_AES_DIRECT is enabled. __Warning:__ In nearly all - use cases ECB mode is considered to be less secure. Please avoid using ECB + \brief This function is a one-block encrypt of the input block, in, into + the output block, out. It uses the key and iv (initialization vector) + of the provided AES structure, which should be initialized with + wc_AesSetKey before calling this function. It is only enabled if the + configure option WOLFSSL_AES_DIRECT is enabled. __Warning:__ In nearly all + use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible - + \param aes pointer to the AES object used to encrypt data - \param out pointer to the output buffer in which to store the cipher + \param out pointer to the output buffer in which to store the cipher text of the encrypted message \param in pointer to the input buffer containing plain text to be encrypted - + _Example_ \code Aes enc; @@ -215,7 +215,7 @@ WOLFSSL_API int wc_AesCtrEncrypt(Aes* aes, byte* out, byte cipher[AES_BLOCK_SIZE]; wc_AesEncryptDirect(&enc, cipher, msg); \endcode - + \sa wc_AesDecryptDirect \sa wc_AesSetKeyDirect */ @@ -223,23 +223,23 @@ WOLFSSL_API void wc_AesEncryptDirect(Aes* aes, byte* out, const byte* in); /*! \ingroup AES - \brief This function is a one-block decrypt of the input block, in, into - the output block, out. It uses the key and iv (initialization vector) of - the provided AES structure, which should be initialized with wc_AesSetKey - before calling this function. It is only enabled if the configure option - WOLFSSL_AES_DIRECT is enabled, and there is support for direct AES - encryption on the system in question. __Warning:__ In nearly all use cases - ECB mode is considered to be less secure. Please avoid using ECB API’s + \brief This function is a one-block decrypt of the input block, in, into + the output block, out. It uses the key and iv (initialization vector) of + the provided AES structure, which should be initialized with wc_AesSetKey + before calling this function. It is only enabled if the configure option + WOLFSSL_AES_DIRECT is enabled, and there is support for direct AES + encryption on the system in question. __Warning:__ In nearly all use cases + ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible - + \return none - + \param aes pointer to the AES object used to encrypt data - \param out pointer to the output buffer in which to store the plain + \param out pointer to the output buffer in which to store the plain text of the decrypted cipher text - \param in pointer to the input buffer containing cipher text to be + \param in pointer to the input buffer containing cipher text to be decrypted - + _Example_ \code Aes dec; @@ -249,7 +249,7 @@ WOLFSSL_API void wc_AesEncryptDirect(Aes* aes, byte* out, const byte* in); byte msg[AES_BLOCK_SIZE]; wc_AesDecryptDirect(&dec, msg, cipher); \endcode - + \sa wc_AesEncryptDirect \sa wc_AesSetKeyDirect */ @@ -257,38 +257,38 @@ WOLFSSL_API void wc_AesDecryptDirect(Aes* aes, byte* out, const byte* in); /*! \ingroup AES - \brief This function is used to set the AES keys for CTR mode with AES. - It initializes an AES object with the given key, iv - (initialization vector), and encryption dir (direction). It is only - enabled if the configure option WOLFSSL_AES_DIRECT is enabled. - Currently wc_AesSetKeyDirect uses wc_AesSetKey internally. __Warning:__ In - nearly all use cases ECB mode is considered to be less secure. Please avoid + \brief This function is used to set the AES keys for CTR mode with AES. + It initializes an AES object with the given key, iv + (initialization vector), and encryption dir (direction). It is only + enabled if the configure option WOLFSSL_AES_DIRECT is enabled. + Currently wc_AesSetKeyDirect uses wc_AesSetKey internally. __Warning:__ In + nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible - + \return 0 On successfully setting the key. \return BAD_FUNC_ARG Returned if the given key is an invalid length. - + \param aes pointer to the AES object used to encrypt data \param key 16, 24, or 32 byte secret key for encryption and decryption \param len length of the key passed in \param iv initialization vector used to initialize the key - \param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or - AES_DECRYPTION to decrypt. (See enum in wolfssl/wolfcrypt/aes.h) - (NOTE: If using wc_AesSetKeyDirect with Aes Counter mode (Stream cipher) + \param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or + AES_DECRYPTION to decrypt. (See enum in wolfssl/wolfcrypt/aes.h) + (NOTE: If using wc_AesSetKeyDirect with Aes Counter mode (Stream cipher) only use AES_ENCRYPTION for both encrypting and decrypting) - + _Example_ \code Aes enc; int ret = 0; byte key[] = { some 16, 24, or 32 byte key }; byte iv[] = { some 16 byte iv }; - if (ret = wc_AesSetKeyDirect(&enc, key, sizeof(key), iv, + if (ret = wc_AesSetKeyDirect(&enc, key, sizeof(key), iv, AES_ENCRYPTION) != 0) { // failed to set aes key } \endcode - + \sa wc_AesEncryptDirect \sa wc_AesDecryptDirect \sa wc_AesSetKey @@ -298,18 +298,18 @@ WOLFSSL_API int wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len, /*! \ingroup AES - \brief This function is used to set the key for AES GCM - (Galois/Counter Mode). It initializes an AES object with the - given key. It is only enabled if the configure option + \brief This function is used to set the key for AES GCM + (Galois/Counter Mode). It initializes an AES object with the + given key. It is only enabled if the configure option HAVE_AESGCM is enabled at compile time. - + \return 0 On successfully setting the key. \return BAD_FUNC_ARG Returned if the given key is an invalid length. - + \param aes pointer to the AES object used to encrypt data \param key 16, 24, or 32 byte secret key for encryption and decryption \param len length of the key passed in - + _Example_ \code Aes enc; @@ -319,7 +319,7 @@ WOLFSSL_API int wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len, // failed to set aes key } \endcode - + \sa wc_AesGcmEncrypt \sa wc_AesGcmDecrypt */ @@ -327,33 +327,33 @@ WOLFSSL_API int wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len); /*! \ingroup AES - \brief This function encrypts the input message, held in the buffer in, - and stores the resulting cipher text in the output buffer out. It - requires a new iv (initialization vector) for each call to encrypt. - It also encodes the input authentication vector, authIn, into the + \brief This function encrypts the input message, held in the buffer in, + and stores the resulting cipher text in the output buffer out. It + requires a new iv (initialization vector) for each call to encrypt. + It also encodes the input authentication vector, authIn, into the authentication tag, authTag. - + \return 0 On successfully encrypting the input message - + \param aes - pointer to the AES object used to encrypt data \param out pointer to the output buffer in which to store the cipher text \param in pointer to the input buffer holding the message to encrypt \param sz length of the input message to encrypt \param iv pointer to the buffer containing the initialization vector \param ivSz length of the initialization vector - \param authTag pointer to the buffer in which to store the + \param authTag pointer to the buffer in which to store the authentication tag \param authTagSz length of the desired authentication tag - \param authIn pointer to the buffer containing the input + \param authIn pointer to the buffer containing the input authentication vector \param authInSz length of the input authentication vector - + _Example_ \code Aes enc; // initialize aes structure by calling wc_AesGcmSetKey - byte plain[AES_BLOCK_LENGTH * n]; //n being a positive integer + byte plain[AES_BLOCK_LENGTH * n]; //n being a positive integer making plain some multiple of 16 bytes // initialize plain with msg to encrypt byte cipher[sizeof(plain)]; @@ -364,7 +364,7 @@ WOLFSSL_API int wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len); wc_AesGcmEncrypt(&enc, cipher, plain, sizeof(cipher), iv, sizeof(iv), authTag, sizeof(authTag), authIn, sizeof(authIn)); \endcode - + \sa wc_AesGcmSetKey \sa wc_AesGcmDecrypt */ @@ -376,15 +376,15 @@ WOLFSSL_API int wc_AesGcmEncrypt(Aes* aes, byte* out, /*! \ingroup AES - \brief This function decrypts the input cipher text, held in the buffer - in, and stores the resulting message text in the output buffer out. - It also checks the input authentication vector, authIn, against the + \brief This function decrypts the input cipher text, held in the buffer + in, and stores the resulting message text in the output buffer out. + It also checks the input authentication vector, authIn, against the supplied authentication tag, authTag. - + \return 0 On successfully decrypting the input message - \return AES_GCM_AUTH_E If the authentication tag does not match the + \return AES_GCM_AUTH_E If the authentication tag does not match the supplied authentication code vector, authTag. - + \param aes pointer to the AES object used to encrypt data \param out pointer to the output buffer in which to store the message text \param in pointer to the input buffer holding the cipher text to decrypt @@ -393,16 +393,16 @@ WOLFSSL_API int wc_AesGcmEncrypt(Aes* aes, byte* out, \param ivSz length of the initialization vector \param authTag pointer to the buffer containing the authentication tag \param authTagSz length of the desired authentication tag - \param authIn pointer to the buffer containing the input + \param authIn pointer to the buffer containing the input authentication vector \param authInSz length of the input authentication vector - + _Example_ \code - Aes enc; //can use the same struct as was passed to wc_AesGcmEncrypt + Aes enc; //can use the same struct as was passed to wc_AesGcmEncrypt // initialize aes structure by calling wc_AesGcmSetKey if not already done - byte cipher[AES_BLOCK_LENGTH * n]; //n being a positive integer + byte cipher[AES_BLOCK_LENGTH * n]; //n being a positive integer making cipher some multiple of 16 bytes // initialize cipher with cipher text to decrypt byte output[sizeof(cipher)]; @@ -413,7 +413,7 @@ WOLFSSL_API int wc_AesGcmEncrypt(Aes* aes, byte* out, wc_AesGcmDecrypt(&enc, output, cipher, sizeof(cipher), iv, sizeof(iv), authTag, sizeof(authTag), authIn, sizeof(authIn)); \endcode - + \sa wc_AesGcmSetKey \sa wc_AesGcmEncrypt */ @@ -425,45 +425,45 @@ WOLFSSL_API int wc_AesGcmDecrypt(Aes* aes, byte* out, /*! \ingroup AES - \brief This function initializes and sets the key for a GMAC object + \brief This function initializes and sets the key for a GMAC object to be used for Galois Message Authentication. - + \return 0 On successfully setting the key \return BAD_FUNC_ARG Returned if key length is invalid. - + \param gmac pointer to the gmac object used for authentication \param key 16, 24, or 32 byte secret key for authentication \param len length of the key - + _Example_ \code Gmac gmac; key[] = { some 16, 24, or 32 byte length key }; wc_GmacSetKey(&gmac, key, sizeof(key)); \endcode - + \sa wc_GmacUpdate */ WOLFSSL_API int wc_GmacSetKey(Gmac* gmac, const byte* key, word32 len); /*! \ingroup AES - \brief This function generates the Gmac hash of the authIn input and - stores the result in the authTag buffer. After running wc_GmacUpdate, - one should compare the generated authTag to a known authentication tag + \brief This function generates the Gmac hash of the authIn input and + stores the result in the authTag buffer. After running wc_GmacUpdate, + one should compare the generated authTag to a known authentication tag to verify the authenticity of a message. - + \return 0 On successfully computing the Gmac hash. - + \param gmac pointer to the gmac object used for authentication \param iv initialization vector used for the hash \param ivSz size of the initialization vector used - \param authIn pointer to the buffer containing the authentication + \param authIn pointer to the buffer containing the authentication vector to verify \param authInSz size of the authentication vector \param authTag pointer to the output buffer in which to store the Gmac hash \param authTagSz the size of the output buffer used to store the Gmac hash - + _Example_ \code Gmac gmac; @@ -474,10 +474,10 @@ WOLFSSL_API int wc_GmacSetKey(Gmac* gmac, const byte* key, word32 len); authIn[] = { some 16 byte authentication input }; tag[AES_BLOCK_SIZE]; // will store authentication code - wc_GmacUpdate(&gmac, iv, sizeof(iv), authIn, sizeof(authIn), tag, + wc_GmacUpdate(&gmac, iv, sizeof(iv), authIn, sizeof(authIn), tag, sizeof(tag)); \endcode - + \sa wc_GmacSetKey */ WOLFSSL_API int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz, @@ -486,16 +486,16 @@ WOLFSSL_API int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz, /*! \ingroup AES - \brief This function sets the key for an AES object using CCM - (Counter with CBC-MAC). It takes a pointer to an AES structure and + \brief This function sets the key for an AES object using CCM + (Counter with CBC-MAC). It takes a pointer to an AES structure and initializes it with supplied key. - + \return none - + \param aes aes structure in which to store the supplied key \param key 16, 24, or 32 byte secret key for encryption and decryption \param keySz size of the supplied key - + _Example_ \code Aes enc; @@ -503,7 +503,7 @@ WOLFSSL_API int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz, wc_AesCcmSetKey(&aes, key, sizeof(key)); \endcode - + \sa wc_AesCcmEncrypt \sa wc_AesCcmDecrypt */ @@ -511,28 +511,28 @@ WOLFSSL_API int wc_AesCcmSetKey(Aes* aes, const byte* key, word32 keySz); /*! \ingroup AES - - \brief This function encrypts the input message, in, into the output - buffer, out, using CCM (Counter with CBC-MAC). It subsequently - calculates and stores the authorization tag, authTag, from the + + \brief This function encrypts the input message, in, into the output + buffer, out, using CCM (Counter with CBC-MAC). It subsequently + calculates and stores the authorization tag, authTag, from the authIn input. - + \return none - + \param aes pointer to the AES object used to encrypt data \param out pointer to the output buffer in which to store the cipher text \param in pointer to the input buffer holding the message to encrypt \param sz length of the input message to encrypt - \param nonce pointer to the buffer containing the nonce + \param nonce pointer to the buffer containing the nonce (number only used once) \param nonceSz length of the nonce - \param authTag pointer to the buffer in which to store the + \param authTag pointer to the buffer in which to store the authentication tag \param authTagSz length of the desired authentication tag - \param authIn pointer to the buffer containing the input + \param authIn pointer to the buffer containing the input authentication vector \param authInSz length of the input authentication vector - + _Example_ \code Aes enc; @@ -548,7 +548,7 @@ WOLFSSL_API int wc_AesCcmSetKey(Aes* aes, const byte* key, word32 keySz); wc_AesCcmEncrypt(&enc, cipher, plain, sizeof(plain), nonce, sizeof(nonce), tag, sizeof(tag), authIn, sizeof(authIn)); \endcode - + \sa wc_AesCcmSetKey \sa wc_AesCcmDecrypt */ @@ -560,31 +560,31 @@ WOLFSSL_API int wc_AesCcmEncrypt(Aes* aes, byte* out, /*! \ingroup AES - - \brief This function decrypts the input cipher text, in, into - the output buffer, out, using CCM (Counter with CBC-MAC). It - subsequently calculates the authorization tag, authTag, from the - authIn input. If the authorization tag is invalid, it sets the + + \brief This function decrypts the input cipher text, in, into + the output buffer, out, using CCM (Counter with CBC-MAC). It + subsequently calculates the authorization tag, authTag, from the + authIn input. If the authorization tag is invalid, it sets the output buffer to zero and returns the error: AES_CCM_AUTH_E. - + \return 0 On successfully decrypting the input message - \return AES_CCM_AUTH_E If the authentication tag does not match the + \return AES_CCM_AUTH_E If the authentication tag does not match the supplied authentication code vector, authTag. - + \param aes pointer to the AES object used to encrypt data \param out pointer to the output buffer in which to store the cipher text \param in pointer to the input buffer holding the message to encrypt \param sz length of the input cipher text to decrypt - \param nonce pointer to the buffer containing the nonce + \param nonce pointer to the buffer containing the nonce (number only used once) \param nonceSz length of the nonce - \param authTag pointer to the buffer in which to store the + \param authTag pointer to the buffer in which to store the authentication tag \param authTagSz length of the desired authentication tag - \param authIn pointer to the buffer containing the input + \param authIn pointer to the buffer containing the input authentication vector \param authInSz length of the input authentication vector - + _Example_ \code Aes dec; @@ -597,13 +597,13 @@ WOLFSSL_API int wc_AesCcmEncrypt(Aes* aes, byte* out, authIn[] = { some 16 byte authentication input }; tag[AES_BLOCK_SIZE] = { authentication tag received for verification }; - int return = wc_AesCcmDecrypt(&dec, plain, cipher, sizeof(cipher), + int return = wc_AesCcmDecrypt(&dec, plain, cipher, sizeof(cipher), nonce, sizeof(nonce),tag, sizeof(tag), authIn, sizeof(authIn)); if(return != 0) { // decrypt error, invalid authentication code } \endcode - + \sa wc_AesCcmSetKey \sa wc_AesCcmEncrypt */ @@ -616,14 +616,14 @@ WOLFSSL_API int wc_AesCcmDecrypt(Aes* aes, byte* out, /*! \ingroup AES - \brief This is to help with setting keys to correct encrypt or + \brief This is to help with setting keys to correct encrypt or decrypt type. It is up to user to call wc_AesXtsFree on aes key when done. \return 0 Success \param aes AES keys for encrypt/decrypt process \param key buffer holding aes key | tweak key - \param len length of key buffer in bytes. Should be twice that of + \param len length of key buffer in bytes. Should be twice that of key size. i.e. 32 for a 16 byte key. \param dir direction, either AES_ENCRYPTION or AES_DECRYPTION @@ -781,7 +781,7 @@ WOLFSSL_API int wc_AesXtsEncrypt(XtsAes* aes, byte* out, \param iSz size of i buffer, should always be AES_BLOCK_SIZE but having this input adds a sanity check on how the user calls the function. - + _Example_ \code XtsAes aes; diff --git a/doc/dox_comments/header_files/arc4.h b/doc/dox_comments/header_files/arc4.h index ae99da5ec..4e1e26130 100644 --- a/doc/dox_comments/header_files/arc4.h +++ b/doc/dox_comments/header_files/arc4.h @@ -1,20 +1,20 @@ /*! \ingroup ARC4 - \brief This function encrypts an input message from the buffer in, placing - the ciphertext in the output buffer out, or decrypts a ciphertext from the - buffer in, placing the plaintext in the output buffer out, using ARC4 - encryption. This function is used for both encryption and decryption. - Before this method may be called, one must first initialize the ARC4 + \brief This function encrypts an input message from the buffer in, placing + the ciphertext in the output buffer out, or decrypts a ciphertext from the + buffer in, placing the plaintext in the output buffer out, using ARC4 + encryption. This function is used for both encryption and decryption. + Before this method may be called, one must first initialize the ARC4 structure using wc_Arc4SetKey. - + \return none - + \param arc4 pointer to the ARC4 structure used to process the message - \param out pointer to the output buffer in which to store the + \param out pointer to the output buffer in which to store the processed message \param in pointer to the input buffer containing the message to process \param length length of the message to process - + _Example_ \code Arc4 enc; @@ -26,34 +26,34 @@ byte decrypted[sizeof(plain)]; // encrypt the plain into cipher wc_Arc4Process(&enc, cipher, plain, sizeof(plain)); - // decrypt the cipher - wc_Arc4Process(&enc, decrypted, cipher, sizeof(cipher)); + // decrypt the cipher + wc_Arc4Process(&enc, decrypted, cipher, sizeof(cipher)); \endcode - + \sa wc_Arc4SetKey */ WOLFSSL_API int wc_Arc4Process(Arc4*, byte*, const byte*, word32); /*! \ingroup ARC4 - - \brief This function sets the key for a ARC4 object, initializing it for - use as a cipher. It should be called before using it for encryption + + \brief This function sets the key for a ARC4 object, initializing it for + use as a cipher. It should be called before using it for encryption with wc_Arc4Process. - + \return none - + \param arc4 pointer to an arc4 structure to be used for encryption \param key key with which to initialize the arc4 structure \param length length of the key used to initialize the arc4 structure - + _Example_ \code Arc4 enc; byte key[] = { initialize with key to use for encryption }; wc_Arc4SetKey(&enc, key, sizeof(key)); \endcode - + \sa wc_Arc4Process */ WOLFSSL_API int wc_Arc4SetKey(Arc4*, const byte*, word32); diff --git a/doc/dox_comments/header_files/asn_public.h b/doc/dox_comments/header_files/asn_public.h index d876c79a9..47014dff1 100644 --- a/doc/dox_comments/header_files/asn_public.h +++ b/doc/dox_comments/header_files/asn_public.h @@ -1,21 +1,21 @@ /*! \ingroup ASN - - \brief This function initializes a default cert, with the default options: - version = 3 (0x2), serial = 0, sigType = SHA_WITH_RSA, issuer = blank, - daysValid = 500, selfSigned = 1 (true) use subject as issuer, + + \brief This function initializes a default cert, with the default options: + version = 3 (0x2), serial = 0, sigType = SHA_WITH_RSA, issuer = blank, + daysValid = 500, selfSigned = 1 (true) use subject as issuer, subject = blank - + \return none No returns. - + \param cert pointer to an uninitialized cert structure to initialize - + _Example_ \code Cert myCert; wc_InitCert(&myCert); \endcode - + \sa wc_MakeCert \sa wc_MakeCertReq */ @@ -23,35 +23,35 @@ WOLFSSL_API int wc_InitCert(Cert*); /*! \ingroup ASN - - \brief Used to make CA signed certs. Called after the subject information - has been entered. This function makes an x509 Certificate v3 RSA or ECC - from a cert input. It then writes this cert to derBuffer. It takes in - either an rsaKey or an eccKey to generate the certificate. The certificate + + \brief Used to make CA signed certs. Called after the subject information + has been entered. This function makes an x509 Certificate v3 RSA or ECC + from a cert input. It then writes this cert to derBuffer. It takes in + either an rsaKey or an eccKey to generate the certificate. The certificate must be initialized with wc_InitCert before this method is called. - - \return Success On successfully making an x509 certificate from the + + \return Success On successfully making an x509 certificate from the specified input cert, returns the size of the cert generated. - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return BUFFER_E Returned if the provided derBuffer is too small to + \return BUFFER_E Returned if the provided derBuffer is too small to store the generated certificate - \return Others Additional error messages may be returned if the cert + \return Others Additional error messages may be returned if the cert generation is not successful. - \param cert pointer to an initialized cert structure + \param cert pointer to an initialized cert structure \param derBuffer pointer to the buffer in which to hold the generated cert \param derSz size of the buffer in which to store the cert - \param rsaKey pointer to an RsaKey structure containing the rsa key used + \param rsaKey pointer to an RsaKey structure containing the rsa key used to generate the certificate - \param eccKey pointer to an EccKey structure containing the ecc key used + \param eccKey pointer to an EccKey structure containing the ecc key used to generate the certificate \param rng pointer to the random number generator used to make the cert - + _Example_ \code Cert myCert; - wc_InitCert(&myCert); + wc_InitCert(&myCert); WC_RNG rng; //initialize rng; RsaKey key; @@ -60,40 +60,40 @@ WOLFSSL_API int wc_InitCert(Cert*); word32 certSz; certSz = wc_MakeCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng); \endcode - + \sa wc_InitCert \sa wc_MakeCertReq */ WOLFSSL_API int wc_MakeCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*, ecc_key*, WC_RNG*); - + /*! \ingroup ASN - - \brief This function makes a certificate signing request using the input - certificate and writes the output to derBuffer. It takes in either an - rsaKey or an eccKey to generate the certificate request. wc_SignCert() - will need to be called after this function to sign the certificate request. - Please see the wolfCrypt test application (./wolfcrypt/test/test.c) for an + + \brief This function makes a certificate signing request using the input + certificate and writes the output to derBuffer. It takes in either an + rsaKey or an eccKey to generate the certificate request. wc_SignCert() + will need to be called after this function to sign the certificate request. + Please see the wolfCrypt test application (./wolfcrypt/test/test.c) for an example usage of this function. - - \return Success On successfully making an X.509 certificate request from - the specified input cert, returns the size of the certificate + + \return Success On successfully making an X.509 certificate request from + the specified input cert, returns the size of the certificate request generated. - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return BUFFER_E Returned if the provided derBuffer is too small to store + \return BUFFER_E Returned if the provided derBuffer is too small to store the generated certificate - \return Other Additional error messages may be returned if the certificate + \return Other Additional error messages may be returned if the certificate request generation is not successful. - - \param cert pointer to an initialized cert structure - \param derBuffer pointer to the buffer in which to hold the generated + + \param cert pointer to an initialized cert structure + \param derBuffer pointer to the buffer in which to hold the generated certificate request \param derSz size of the buffer in which to store the certificate request - \param rsaKey pointer to an RsaKey structure containing the rsa key used + \param rsaKey pointer to an RsaKey structure containing the rsa key used to generate the certificate request - \param eccKey pointer to an EccKey structure containing the ecc key used + \param eccKey pointer to an EccKey structure containing the ecc key used to generate the certificate request _Example_ @@ -107,44 +107,44 @@ WOLFSSL_API int wc_MakeCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*, word32 certSz; certSz = wc_MakeCertReq(&myCert, derCert, FOURK_BUF, NULL, &key); \endcode - + \sa wc_InitCert \sa wc_MakeCert */ WOLFSSL_API int wc_MakeCertReq(Cert*, byte* derBuffer, word32 derSz, RsaKey*, ecc_key*); - + /*! \ingroup ASN - - \brief This function signs buffer and adds the signature to the end of - buffer. It takes in a signature type. Must be called after wc_MakeCert() + + \brief This function signs buffer and adds the signature to the end of + buffer. It takes in a signature type. Must be called after wc_MakeCert() or wc_MakeCertReq() if creating a CA signed cert. - - \return Success On successfully signing the certificate, returns the new + + \return Success On successfully signing the certificate, returns the new size of the cert (including signature). - \return MEMORY_E Returned if there is an error allocating + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return BUFFER_E Returned if the provided buffer is too small to store + \return BUFFER_E Returned if the provided buffer is too small to store the generated certificate - \return Other Additional error messages may be returned if the cert + \return Other Additional error messages may be returned if the cert generation is not successful. - - \param requestSz the size of the certificate body we’re requesting + + \param requestSz the size of the certificate body we’re requesting to have signed - \param sType Type of signature to create. Valid options are: CTC_MD5wRSA, + \param sType Type of signature to create. Valid options are: CTC_MD5wRSA, CTC_SHAwRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, andCTC_SHA256wRSA - \param buffer pointer to the buffer containing the certificate to be + \param buffer pointer to the buffer containing the certificate to be signed. On success: will hold the newly signed certificate - \param buffSz the (total) size of the buffer in which to store the newly + \param buffSz the (total) size of the buffer in which to store the newly signed certificate - \param rsaKey pointer to an RsaKey structure containing the rsa key + \param rsaKey pointer to an RsaKey structure containing the rsa key to used to sign the certificate - \param eccKey pointer to an EccKey structure containing the ecc key + \param eccKey pointer to an EccKey structure containing the ecc key to used to sign the certificate - \param rng pointer to the random number generator used to sign + \param rng pointer to the random number generator used to sign the certificate - + _Example_ \code Cert myCert; @@ -156,40 +156,40 @@ WOLFSSL_API int wc_MakeCertReq(Cert*, byte* derBuffer, word32 derSz, // initialize rng word32 certSz; - certSz = wc_SignCert(myCert.bodySz, myCert.sigType,derCert,FOURK_BUF, - &key, NULL, + certSz = wc_SignCert(myCert.bodySz, myCert.sigType,derCert,FOURK_BUF, + &key, NULL, &rng); \endcode - + \sa wc_InitCert \sa wc_MakeCert */ WOLFSSL_API int wc_SignCert(int requestSz, int sigType, byte* derBuffer, word32 derSz, RsaKey*, ecc_key*, WC_RNG*); - + /*! \ingroup ASN - - \brief This function is a combination of the previous two functions, - wc_MakeCert and wc_SignCert for self signing (the previous functions may - be used for CA requests). It makes a certificate, and then signs it, + + \brief This function is a combination of the previous two functions, + wc_MakeCert and wc_SignCert for self signing (the previous functions may + be used for CA requests). It makes a certificate, and then signs it, generating a self-signed certificate. - - \return Success On successfully signing the certificate, returns the + + \return Success On successfully signing the certificate, returns the new size of the cert. - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return BUFFER_E Returned if the provided buffer is too small to store + \return BUFFER_E Returned if the provided buffer is too small to store the generated certificate - \return Other Additional error messages may be returned if the cert + \return Other Additional error messages may be returned if the cert generation is not successful. - + \param cert pointer to the cert to make and sign \param buffer pointer to the buffer in which to hold the signed certificate \param buffSz size of the buffer in which to store the signed certificate - \param key pointer to an RsaKey structure containing the rsa key to + \param key pointer to an RsaKey structure containing the rsa key to used to sign the certificate - \param rng pointer to the random number generator used to generate + \param rng pointer to the random number generator used to generate and sign the certificate _Example_ @@ -205,62 +205,62 @@ WOLFSSL_API int wc_SignCert(int requestSz, int sigType, byte* derBuffer, word32 certSz; certSz = wc_MakeSelfCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng); \endcode - + \sa wc_InitCert \sa wc_MakeCert \sa wc_SignCert */ WOLFSSL_API int wc_MakeSelfCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*, WC_RNG*); - + /*! \ingroup ASN - - \brief This function sets the issuer for a certificate to the issuer - in the provided pem issuerFile. It also changes the certificate’s - self-signed attribute to false. The issuer specified in issuerFile is - verified prior to setting the cert issuer. This method is used to set + + \brief This function sets the issuer for a certificate to the issuer + in the provided pem issuerFile. It also changes the certificate’s + self-signed attribute to false. The issuer specified in issuerFile is + verified prior to setting the cert issuer. This method is used to set fields prior to signing. - + \return 0 Returned on successfully setting the issuer for the certificate - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return ASN_PARSE_E Returned if there is an error parsing the + \return ASN_PARSE_E Returned if there is an error parsing the cert header file - \return ASN_OBJECT_ID_E Returned if there is an error parsing the + \return ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert - \return ASN_EXPECT_0_E Returned if there is a formatting error in + \return ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file - \return ASN_BEFORE_DATE_E Returned if the date is before the certificate + \return ASN_BEFORE_DATE_E Returned if the date is before the certificate start date - \return ASN_AFTER_DATE_E Returned if the date is after the certificate + \return ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date - \return ASN_BITSTR_E Returned if there is an error parsing a bit string + \return ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate - \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key + \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key from the certificate - \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key + \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate - \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown + \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id - \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not + \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate - \return BAD_FUNC_ARG Returned if there is an error processing the + \return BAD_FUNC_ARG Returned if there is an error processing the certificate extension - \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is + \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate - \return ASN_SIG_OID_E Returned if the signature encryption type is not + \return ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file - \return ASN_SIG_CONFIRM_E Returned if confirming the certification + \return ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails - \return ASN_NAME_INVALID_E Returned if the certificate’s name is not + \return ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints - \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify + \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity - + \param cert pointer to the cert for which to set the issuer \param issuerFile path of the file containing the pem formatted certificate - + _Example_ \code Cert myCert; @@ -269,7 +269,7 @@ WOLFSSL_API int wc_MakeSelfCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*, // error setting issuer } \endcode - + \sa wc_InitCert \sa wc_SetSubject \sa wc_SetIssuerBuffer @@ -278,49 +278,49 @@ WOLFSSL_API int wc_SetIssuer(Cert*, const char*); /*! \ingroup ASN - - \brief This function sets the subject for a certificate to the subject - in the provided pem subjectFile. This method is used to set fields prior + + \brief This function sets the subject for a certificate to the subject + in the provided pem subjectFile. This method is used to set fields prior to signing. - + \return 0 Returned on successfully setting the issuer for the certificate \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return ASN_PARSE_E Returned if there is an error parsing the cert + \return ASN_PARSE_E Returned if there is an error parsing the cert header file - \return ASN_OBJECT_ID_E Returned if there is an error parsing the + \return ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert - \return ASN_EXPECT_0_E Returned if there is a formatting error in the + \return ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file - \return ASN_BEFORE_DATE_E Returned if the date is before the certificate + \return ASN_BEFORE_DATE_E Returned if the date is before the certificate start date - \return ASN_AFTER_DATE_E Returned if the date is after the certificate + \return ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date - \return ASN_BITSTR_E Returned if there is an error parsing a bit string + \return ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate - \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key + \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key from the certificate - \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key + \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate - \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown + \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id - \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not + \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate - \return BAD_FUNC_ARG Returned if there is an error processing the + \return BAD_FUNC_ARG Returned if there is an error processing the certificate extension - \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is + \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate - \return ASN_SIG_OID_E Returned if the signature encryption type is not + \return ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file - \return ASN_SIG_CONFIRM_E Returned if confirming the certification + \return ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails - \return ASN_NAME_INVALID_E Returned if the certificate’s name is not + \return ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints - \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the + \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity - + \param cert pointer to the cert for which to set the issuer \param subjectFile path of the file containing the pem formatted certificate - + _Example_ \code Cert myCert; @@ -329,7 +329,7 @@ WOLFSSL_API int wc_SetIssuer(Cert*, const char*); // error setting subject } \endcode - + \sa wc_InitCert \sa wc_SetIssuer */ @@ -337,51 +337,51 @@ WOLFSSL_API int wc_SetSubject(Cert*, const char*); /*! \ingroup ASN - - \brief This function sets the alternate names for a certificate to the - alternate names in the provided pem file. This is useful in the case that - one wishes to secure multiple domains with the same certificate. This + + \brief This function sets the alternate names for a certificate to the + alternate names in the provided pem file. This is useful in the case that + one wishes to secure multiple domains with the same certificate. This method is used to set fields prior to signing. - + \return 0 Returned on successfully setting the alt names for the certificate - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return ASN_PARSE_E Returned if there is an error parsing the cert + \return ASN_PARSE_E Returned if there is an error parsing the cert header file - \return ASN_OBJECT_ID_E Returned if there is an error parsing the + \return ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert - \return ASN_EXPECT_0_E Returned if there is a formatting error in the + \return ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file - \return ASN_BEFORE_DATE_E Returned if the date is before the certificate + \return ASN_BEFORE_DATE_E Returned if the date is before the certificate start date - \return ASN_AFTER_DATE_E Returned if the date is after the certificate + \return ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date - \return ASN_BITSTR_E Returned if there is an error parsing a bit string + \return ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate - \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key + \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key from the certificate - \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key + \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate - \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown + \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id - \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not + \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate - \return BAD_FUNC_ARG Returned if there is an error processing the + \return BAD_FUNC_ARG Returned if there is an error processing the certificate extension - \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is + \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate - \return ASN_SIG_OID_E Returned if the signature encryption type is not + \return ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file - \return ASN_SIG_CONFIRM_E Returned if confirming the certification + \return ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails - \return ASN_NAME_INVALID_E Returned if the certificate’s name is not + \return ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints - \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the + \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity - + \param cert pointer to the cert for which to set the alt names \param file path of the file containing the pem formatted certificate - + _Example_ \code Cert myCert; @@ -390,7 +390,7 @@ WOLFSSL_API int wc_SetSubject(Cert*, const char*); // error setting alt names } \endcode - + \sa wc_InitCert \sa wc_SetIssuer */ @@ -398,53 +398,53 @@ WOLFSSL_API int wc_SetAltNames(Cert*, const char*); /*! \ingroup ASN - - \brief This function sets the issuer for a certificate from the issuer in - the provided der buffer. It also changes the certificate’s self-signed + + \brief This function sets the issuer for a certificate from the issuer in + the provided der buffer. It also changes the certificate’s self-signed attribute to false. This method is used to set fields prior to signing. - + \return 0 Returned on successfully setting the issuer for the certificate - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return ASN_PARSE_E Returned if there is an error parsing the cert + \return ASN_PARSE_E Returned if there is an error parsing the cert header file - \return ASN_OBJECT_ID_E Returned if there is an error parsing the + \return ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert - \return ASN_EXPECT_0_E Returned if there is a formatting error in the + \return ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file - \return ASN_BEFORE_DATE_E Returned if the date is before the certificate + \return ASN_BEFORE_DATE_E Returned if the date is before the certificate start date - \return ASN_AFTER_DATE_E Returned if the date is after the certificate + \return ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date - \return ASN_BITSTR_E Returned if there is an error parsing a bit string + \return ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate - \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU + \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key from the certificate - \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC + \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate - \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown + \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id - \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not + \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate - \return BAD_FUNC_ARG Returned if there is an error processing the + \return BAD_FUNC_ARG Returned if there is an error processing the certificate extension - \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is + \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate - \return ASN_SIG_OID_E Returned if the signature encryption type is not + \return ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file - \return ASN_SIG_CONFIRM_E Returned if confirming the certification + \return ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails - \return ASN_NAME_INVALID_E Returned if the certificate’s name is not + \return ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints - \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify + \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity - + \param cert pointer to the cert for which to set the issuer - \param der pointer to the buffer containing the der formatted certificate + \param der pointer to the buffer containing the der formatted certificate from which to grab the issuer - \param derSz size of the buffer containing the der formatted certificate + \param derSz size of the buffer containing the der formatted certificate from which to grab the issuer - + _Example_ \code Cert myCert; @@ -456,7 +456,7 @@ WOLFSSL_API int wc_SetAltNames(Cert*, const char*); // error setting issuer } \endcode - + \sa wc_InitCert \sa wc_SetIssuer */ @@ -464,52 +464,52 @@ WOLFSSL_API int wc_SetIssuerBuffer(Cert*, const byte*, int); /*! \ingroup ASN - - \brief This function sets the subject for a certificate from the subject in + + \brief This function sets the subject for a certificate from the subject in the provided der buffer. This method is used to set fields prior to signing. - + \return 0 Returned on successfully setting the subject for the certificate - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return ASN_PARSE_E Returned if there is an error parsing the cert + \return ASN_PARSE_E Returned if there is an error parsing the cert header file - \return ASN_OBJECT_ID_E Returned if there is an error parsing the + \return ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert - \return ASN_EXPECT_0_E Returned if there is a formatting error in the + \return ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file - \return ASN_BEFORE_DATE_E Returned if the date is before the certificate + \return ASN_BEFORE_DATE_E Returned if the date is before the certificate start date - \return ASN_AFTER_DATE_E Returned if the date is after the certificate + \return ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date - \return ASN_BITSTR_E Returned if there is an error parsing a bit string + \return ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate - \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key + \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key from the certificate - \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key + \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate - \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown + \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id - \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not + \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate - \return BAD_FUNC_ARG Returned if there is an error processing the + \return BAD_FUNC_ARG Returned if there is an error processing the certificate extension - \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is + \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate - \return ASN_SIG_OID_E Returned if the signature encryption type is not + \return ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file - \return ASN_SIG_CONFIRM_E Returned if confirming the certification + \return ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails - \return ASN_NAME_INVALID_E Returned if the certificate’s name is not + \return ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints - \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the + \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity - + \param cert pointer to the cert for which to set the subject - \param der pointer to the buffer containing the der formatted certificate + \param der pointer to the buffer containing the der formatted certificate from which to grab the subject - \param derSz size of the buffer containing the der formatted certificate + \param derSz size of the buffer containing the der formatted certificate from which to grab the subject - + _Example_ \code Cert myCert; @@ -521,7 +521,7 @@ WOLFSSL_API int wc_SetIssuerBuffer(Cert*, const byte*, int); // error setting subject } \endcode - + \sa wc_InitCert \sa wc_SetSubject */ @@ -529,55 +529,55 @@ WOLFSSL_API int wc_SetSubjectBuffer(Cert*, const byte*, int); /*! \ingroup ASN - - \brief This function sets the alternate names for a certificate from the - alternate names in the provided der buffer. This is useful in the case that - one wishes to secure multiple domains with the same certificate. This + + \brief This function sets the alternate names for a certificate from the + alternate names in the provided der buffer. This is useful in the case that + one wishes to secure multiple domains with the same certificate. This method is used to set fields prior to signing. - - \return 0 Returned on successfully setting the alternate names for the + + \return 0 Returned on successfully setting the alternate names for the certificate - \return MEMORY_E Returned if there is an error allocating memory with + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return ASN_PARSE_E Returned if there is an error parsing the cert + \return ASN_PARSE_E Returned if there is an error parsing the cert header file - \return ASN_OBJECT_ID_E Returned if there is an error parsing the + \return ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert - \return ASN_EXPECT_0_E Returned if there is a formatting error in the + \return ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file - \return ASN_BEFORE_DATE_E Returned if the date is before the + \return ASN_BEFORE_DATE_E Returned if the date is before the certificate start date - \return ASN_AFTER_DATE_E Returned if the date is after the certificate + \return ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date - \return ASN_BITSTR_E Returned if there is an error parsing a bit string + \return ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate - \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key + \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key from the certificate - \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key + \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate - \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown + \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id - \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not + \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate - \return BAD_FUNC_ARG Returned if there is an error processing the + \return BAD_FUNC_ARG Returned if there is an error processing the certificate extension - \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is + \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate - \return ASN_SIG_OID_E Returned if the signature encryption type is not the + \return ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file - \return ASN_SIG_CONFIRM_E Returned if confirming the certification + \return ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails - \return ASN_NAME_INVALID_E Returned if the certificate’s name is not + \return ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints - \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the + \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity - + \param cert pointer to the cert for which to set the alternate names - \param der pointer to the buffer containing the der formatted certificate + \param der pointer to the buffer containing the der formatted certificate from which to grab the alternate names - \param derSz size of the buffer containing the der formatted certificate + \param derSz size of the buffer containing the der formatted certificate from which to grab the alternate names - + _Example_ \code Cert myCert; @@ -589,7 +589,7 @@ WOLFSSL_API int wc_SetSubjectBuffer(Cert*, const byte*, int); // error setting subject } \endcode - + \sa wc_InitCert \sa wc_SetAltNames */ @@ -597,53 +597,53 @@ WOLFSSL_API int wc_SetAltNamesBuffer(Cert*, const byte*, int); /*! \ingroup ASN - - \brief This function sets the dates for a certificate from the date range - in the provided der buffer. This method is used to set fields prior + + \brief This function sets the dates for a certificate from the date range + in the provided der buffer. This method is used to set fields prior to signing. - + \return 0 Returned on successfully setting the dates for the certificate - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return ASN_PARSE_E Returned if there is an error parsing the cert + \return ASN_PARSE_E Returned if there is an error parsing the cert header file - \return ASN_OBJECT_ID_E Returned if there is an error parsing the + \return ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert - \return ASN_EXPECT_0_E Returned if there is a formatting error in the + \return ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file - \return ASN_BEFORE_DATE_E Returned if the date is before the certificate + \return ASN_BEFORE_DATE_E Returned if the date is before the certificate start date - \return ASN_AFTER_DATE_E Returned if the date is after the certificate + \return ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date - \return ASN_BITSTR_E Returned if there is an error parsing a bit string + \return ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate - \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key + \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key from the certificate - \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key + \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate - \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown + \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id - \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not + \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate - \return BAD_FUNC_ARG Returned if there is an error processing the + \return BAD_FUNC_ARG Returned if there is an error processing the certificate extension - \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is + \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate - \return ASN_SIG_OID_E Returned if the signature encryption type is not + \return ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file - \return ASN_SIG_CONFIRM_E Returned if confirming the certification + \return ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails - \return ASN_NAME_INVALID_E Returned if the certificate’s name is not + \return ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints - \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the + \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity - + \param cert pointer to the cert for which to set the dates - \param der pointer to the buffer containing the der formatted certificate + \param der pointer to the buffer containing the der formatted certificate from which to grab the date range - \param derSz size of the buffer containing the der formatted certificate + \param derSz size of the buffer containing the der formatted certificate from which to grab the date range - + _Example_ \code Cert myCert; @@ -655,26 +655,26 @@ WOLFSSL_API int wc_SetAltNamesBuffer(Cert*, const byte*, int); // error setting subject } \endcode - + \sa wc_InitCert */ WOLFSSL_API int wc_SetDatesBuffer(Cert*, const byte*, int); /*! \ingroup ASN - - \brief Set AKID from either an RSA or ECC public key. note: Only set one of + + \brief Set AKID from either an RSA or ECC public key. note: Only set one of rsakey or eckey, not both. - + \return 0 Success \return BAD_FUNC_ARG Either cert is null or both rsakey and eckey are null. \return MEMORY_E Error allocating memory. \return PUBLIC_KEY_E Error writing to the key. - + \param cert Pointer to the certificate to set the SKID. \param rsakey Pointer to the RsaKey struct to read from. - \param eckey Pointer to the ecc_key to read from. - + \param eckey Pointer to the ecc_key to read from. + _Example_ \code Cert myCert; @@ -687,7 +687,7 @@ WOLFSSL_API int wc_SetDatesBuffer(Cert*, const byte*, int); // Handle error } \endcode - + \sa wc_SetSubjectKeyId \sa wc_SetAuthKeyId \sa wc_SetAuthKeyIdFromCert @@ -697,14 +697,14 @@ WOLFSSL_API int wc_SetAuthKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey, /*! \ingroup ASN - + \brief Set AKID from from DER encoded certificate. - + \return 0 Success \return BAD_FUNC_ARG Error if any argument is null or derSz is less than 0. \return MEMORY_E Error if problem allocating memory. \return ASN_NO_SKID No subject key ID found. - + \param cert The Cert struct to write to. \param der The DER encoded certificate buffer. \param derSz Size of der in bytes. @@ -719,7 +719,7 @@ WOLFSSL_API int wc_SetAuthKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey, // Handle error } \endcode - + \sa wc_SetAuthKeyIdFromPublicKey \sa wc_SetAuthKeyId */ @@ -727,13 +727,13 @@ WOLFSSL_API int wc_SetAuthKeyIdFromCert(Cert *cert, const byte *der, int derSz); /*! \ingroup ASN - + \brief Set AKID from certificate file in PEM format. - + \return 0 Success \return BAD_FUNC_ARG Error if cert or file is null. \return MEMORY_E Error if problem allocating memory. - + \param cert Cert struct you want to set the AKID of. \param file Buffer containing PEM cert file. @@ -748,7 +748,7 @@ WOLFSSL_API int wc_SetAuthKeyIdFromCert(Cert *cert, const byte *der, int derSz); // Handle Error } \endcode - + \sa wc_SetAuthKeyIdFromPublicKey \sa wc_SetAuthKeyIdFromCert */ @@ -756,16 +756,16 @@ WOLFSSL_API int wc_SetAuthKeyId(Cert *cert, const char* file); /*! \ingroup ASN - + \brief Set SKID from RSA or ECC public key. - + \return 0 Success \return BAD_FUNC_ARG Returned if cert or rsakey and eckey is null. \return MEMORY_E Returned if there is an error allocating memory. \return PUBLIC_KEY_E Returned if there is an error getting the public key. - + \param cert Pointer to a Cert structure to be used. - \param rsakey Pointer to an RsaKey structure + \param rsakey Pointer to an RsaKey structure \param eckey Pointer to an ecc_key structure _Example_ @@ -780,27 +780,27 @@ WOLFSSL_API int wc_SetAuthKeyId(Cert *cert, const char* file); // Handle Error } \endcode - + \sa wc_SetSubjectKeyId \sa wc_SetSubjectKeyIdFromNtruPublicKey */ WOLFSSL_API int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey, ecc_key *eckey); - + /*! \ingroup ASN - - \brief Set SKID from public key file in PEM format. Both arguments + + \brief Set SKID from public key file in PEM format. Both arguments are required. - + \return 0 Success \return BAD_FUNC_ARG Returns if cert or file is null. \return MEMORY_E Returns if there is a problem allocating memory for key. \return PUBLIC_KEY_E Returns if there is an error decoding the public key. - + \param cert Cert structure to set the SKID of. \param file Contains the PEM encoded file. - + _Example_ \code const char* file_name = "path/to/file"; @@ -809,10 +809,10 @@ WOLFSSL_API int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey, if(wc_SetSubjectKeyId(&some_cert, file_name) != 0) { - // Handle Error + // Handle Error } \endcode - + \sa wc_SetSubjectKeyIdFromNtruPublicKey \sa wc_SetSubjectKeyIdFromPublicKey */ @@ -820,18 +820,18 @@ WOLFSSL_API int wc_SetSubjectKeyId(Cert *cert, const char* file); /*! \ingroup ASN - + \brief Set SKID from NTRU public key. - + \return 0 Success \return BAD_FUNC_ARG Returned if cert or ntruKey is null. \return MEMORY_E Returned if there is an error allocating memory. \return PUBLIC_KEY_E Returned if there is an error getting the public key. - + \param cert Pointer to a Cert structure to be used. \param ntruKey Pointer to the NTRU public key in a byte array. \param ntruKeySz Size of the NTRU byte array. - + _Example_ \code Cert some_cert; @@ -839,36 +839,36 @@ WOLFSSL_API int wc_SetSubjectKeyId(Cert *cert, const char* file); byte some_ntru_key[] = { // Load an NTRU key }; word32 ntru_size = sizeof(some_ntru_key); - if(wc_SetSubjectKeyIdFromNtruPublicKey(&some_cert, + if(wc_SetSubjectKeyIdFromNtruPublicKey(&some_cert, some_ntru_key, ntru_size) != 0) { // Handle error } \endcode - + \sa SetKeyIdFromPublicKey */ WOLFSSL_API int wc_SetSubjectKeyIdFromNtruPublicKey(Cert *cert, byte *ntruKey, word16 ntruKeySz); - + /*! \ingroup RSA - - \brief This function allows you to set the key usage using a comma - delimited string of tokens. Accepted tokens are: digitalSignature, - nonRepudiation, contentCommitment, keyCertSign, cRLSign, dataEncipherment, - keyAgreement, keyEncipherment, encipherOnly, decipherOnly. Example: - "digitalSignature,nonRepudiation" nonRepudiation and contentCommitment + + \brief This function allows you to set the key usage using a comma + delimited string of tokens. Accepted tokens are: digitalSignature, + nonRepudiation, contentCommitment, keyCertSign, cRLSign, dataEncipherment, + keyAgreement, keyEncipherment, encipherOnly, decipherOnly. Example: + "digitalSignature,nonRepudiation" nonRepudiation and contentCommitment are for the same usage. - + \return 0 Success \return BAD_FUNC_ARG Returned when either arg is null. \return MEMORY_E Returned when there is an error allocating memory. \return KEYUSAGE_E Returned if an unrecognized token is entered. - + \param cert Pointer to initialized Cert structure. \param value Comma delimited string of tokens to set usage. - + _Example_ \code Cert cert; @@ -879,7 +879,7 @@ WOLFSSL_API int wc_SetSubjectKeyIdFromNtruPublicKey(Cert *cert, byte *ntruKey, // Handle error } \endcode - + \sa wc_InitCert \sa wc_MakeRsaKey */ @@ -887,33 +887,33 @@ WOLFSSL_API int wc_SetKeyUsage(Cert *cert, const char *value); /*! \ingroup ASN - - \brief Used to make CA signed certs. Called after the subject information - has been entered. This function makes an NTRU Certificate from a cert - input. It then writes this cert to derBuffer. It takes in an ntruKey and - a rng to generate the certificate. The certificate must be initialized + + \brief Used to make CA signed certs. Called after the subject information + has been entered. This function makes an NTRU Certificate from a cert + input. It then writes this cert to derBuffer. It takes in an ntruKey and + a rng to generate the certificate. The certificate must be initialized with wc_InitCert before this method is called. - - \return Success On successfully making a NTRU certificate from the + + \return Success On successfully making a NTRU certificate from the specified input cert, returns the size of the cert generated. - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return BUFFER_E Returned if the provided derBuffer is too small to + \return BUFFER_E Returned if the provided derBuffer is too small to store the generated certificate - \return Other Additional error messages may be returned if the cert + \return Other Additional error messages may be returned if the cert generation is not successful. \param cert pointer to an initialized cert structure - \param derBuffer pointer to the buffer in which to store + \param derBuffer pointer to the buffer in which to store the generated certificate - \param derSz size of the buffer in which to store the generated - certificate - \param ntruKey pointer to the key to be used to generate the NTRU + \param derSz size of the buffer in which to store the generated + certificate + \param ntruKey pointer to the key to be used to generate the NTRU certificate \param keySz size of the key used to generate the NTRU certificate - \param rng pointer to the random number generator used to generate + \param rng pointer to the random number generator used to generate the NTRU certificate - + _Example_ \code Cert myCert; @@ -921,26 +921,26 @@ WOLFSSL_API int wc_SetKeyUsage(Cert *cert, const char *value); WC_RNG rng; //initialize rng; byte ntruPublicKey[NTRU_KEY_SIZE]; - //initialize ntruPublicKey; + //initialize ntruPublicKey; byte * derCert = malloc(FOURK_BUF); word32 certSz; - certSz = wc_MakeNtruCert(&myCert, derCert, FOURK_BUF, &ntruPublicKey, + certSz = wc_MakeNtruCert(&myCert, derCert, FOURK_BUF, &ntruPublicKey, NTRU_KEY_SIZE, &rng); \endcode - + \sa wc_InitCert \sa wc_MakeCert */ WOLFSSL_API int wc_MakeNtruCert(Cert*, byte* derBuffer, word32 derSz, const byte* ntruKey, word16 keySz, WC_RNG*); - + /*! \ingroup ASN - + \brief Loads a PEM key from a file and converts to a DER encoded buffer. - + \return 0 Success \return <0 Error \return SSL_BAD_FILE There is a problem with opening the file. @@ -961,33 +961,33 @@ WOLFSSL_API int wc_MakeNtruCert(Cert*, byte* derBuffer, word32 derSz, //Handle Error } \endcode - + \sa wc_PubKeyPemToDer */ WOLFSSL_API int wc_PemPubKeyToDer(const char* fileName, unsigned char* derBuf, int derSz); - + /*! \ingroup ASN - - \brief Convert a PEM encoded public key to DER. Returns the number of + + \brief Convert a PEM encoded public key to DER. Returns the number of bytes written to the buffer or a negative value for an error. \return >0 Success, number of bytes written. \return BAD_FUNC_ARG Returns if pem, buff, or buffSz are null \return <0 An error occurred in the function. - + \param pem PEM encoded key \param pemSz Size of pem \param buff Pointer to buffer for output. \param buffSz Size of buffer. - + _Example_ \code byte some_pem[] = { Initialize with PEM key } unsigned char out_buffer[1024]; // Ensure buffer is large enough to fit DER - if(wc_PubKeyPemToDer(some_pem, sizeof(some_pem), out_buffer, + if(wc_PubKeyPemToDer(some_pem, sizeof(some_pem), out_buffer, sizeof(out_buffer)) < 0) { // Handle error @@ -998,25 +998,25 @@ WOLFSSL_API int wc_PemPubKeyToDer(const char* fileName, */ WOLFSSL_API int wc_PubKeyPemToDer(const unsigned char*, int, unsigned char*, int); - + /*! \ingroup ASN - - \brief This function converts a pem certificate to a der certificate, + + \brief This function converts a pem certificate to a der certificate, and places the resulting certificate in the derBuf buffer provided. - + \return Success On success returns the size of the derBuf generated - \return BUFFER_E Returned if the size of derBuf is too small to hold + \return BUFFER_E Returned if the size of derBuf is too small to hold the certificate generated \return MEMORY_E Returned if the call to XMALLOC fails - - \param fileName path to the file containing a pem certificate to + + \param fileName path to the file containing a pem certificate to convert to a der certificate - \param derBuf pointer to a char buffer in which to store the + \param derBuf pointer to a char buffer in which to store the converted certificate - \param derSz size of the char buffer in which to store the + \param derSz size of the char buffer in which to store the converted certificate - + _Example_ \code char * file = “./certs/client-cert.pem”; @@ -1028,7 +1028,7 @@ WOLFSSL_API int wc_PubKeyPemToDer(const unsigned char*, int, //PemCertToDer error } \endcode - + \sa none */ WOLFSSL_API @@ -1036,32 +1036,32 @@ int wc_PemCertToDer(const char* fileName, unsigned char* derBuf, int derSz); /*! \ingroup ASN - - \brief This function converts a der formatted input certificate, contained - in the der buffer, into a pem formatted output certificate, contained in - the output buffer. It should be noted that this is not an in place - conversion, and a separate buffer must be utilized to store the pem + + \brief This function converts a der formatted input certificate, contained + in the der buffer, into a pem formatted output certificate, contained in + the output buffer. It should be noted that this is not an in place + conversion, and a separate buffer must be utilized to store the pem formatted output. - - \return Success On successfully making a pem certificate from the input + + \return Success On successfully making a pem certificate from the input der cert, returns the size of the pem cert generated. - \return BAD_FUNC_ARG Returned if there is an error parsing the der file + \return BAD_FUNC_ARG Returned if there is an error parsing the der file and storing it as a pem file - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC \return ASN_INPUT_E Returned in the case of a base 64 encoding error - \return BUFFER_E May be returned if the output buffer is too small to + \return BUFFER_E May be returned if the output buffer is too small to store the pem formatted certificate - + \param der pointer to the buffer of the certificate to convert - \param derSz size of the the certificate to convert - \param output pointer to the buffer in which to store the pem + \param derSz size of the the certificate to convert + \param output pointer to the buffer in which to store the pem formatted certificate - \param outSz size of the buffer in which to store the pem formatted + \param outSz size of the buffer in which to store the pem formatted certificate - \param type the type of certificate to generate. Valid types are: + \param type the type of certificate to generate. Valid types are: CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE. - + _Example_ \code byte* der; @@ -1071,41 +1071,41 @@ int wc_PemCertToDer(const char* fileName, unsigned char* derBuf, int derSz); word32 pemSz; pemSz = wc_DerToPem(der, derSz,pemFormatted,FOURK_BUF, CERT_TYPE); \endcode - + \sa wc_PemCertToDer */ WOLFSSL_API int wc_DerToPem(const byte* der, word32 derSz, byte* output, word32 outputSz, int type); - + /*! \ingroup ASN - - \brief This function converts a der formatted input certificate, - contained in the der buffer, into a pem formatted output certificate, - contained in the output buffer. It should be noted that this is not an - in place conversion, and a separate buffer must be utilized to store the + + \brief This function converts a der formatted input certificate, + contained in the der buffer, into a pem formatted output certificate, + contained in the output buffer. It should be noted that this is not an + in place conversion, and a separate buffer must be utilized to store the pem formatted output. Allows setting cipher info. - - \return Success On successfully making a pem certificate from the input + + \return Success On successfully making a pem certificate from the input der cert, returns the size of the pem cert generated. - \return BAD_FUNC_ARG Returned if there is an error parsing the der file + \return BAD_FUNC_ARG Returned if there is an error parsing the der file and storing it as a pem file - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC \return ASN_INPUT_E Returned in the case of a base 64 encoding error - \return BUFFER_E May be returned if the output buffer is too small to + \return BUFFER_E May be returned if the output buffer is too small to store the pem formatted certificate - + \param der pointer to the buffer of the certificate to convert - \param derSz size of the the certificate to convert - \param output pointer to the buffer in which to store the pem + \param derSz size of the the certificate to convert + \param output pointer to the buffer in which to store the pem formatted certificate - \param outSz size of the buffer in which to store the pem formatted + \param outSz size of the buffer in which to store the pem formatted certificate \param cipher_inf Additional cipher information. - \param type the type of certificate to generate. Valid types are: + \param type the type of certificate to generate. Valid types are: CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE. - + _Example_ \code byte* der; @@ -1116,7 +1116,7 @@ WOLFSSL_API int wc_DerToPem(const byte* der, word32 derSz, byte* output, byte* cipher_info[] { Additional cipher info. } pemSz = wc_DerToPemEx(der, derSz,pemFormatted,FOURK_BUF, ,CERT_TYPE); \endcode - + \sa wc_PemCertToDer */ WOLFSSL_API int wc_DerToPemEx(const byte* der, word32 derSz, byte* output, @@ -1126,24 +1126,24 @@ WOLFSSL_API int wc_DerToPemEx(const byte* der, word32 derSz, byte* output, \ingroup CertsKeys \brief Converts a key in PEM format to DER format. - - \return int the function returns the number of bytes written to + + \return int the function returns the number of bytes written to the buffer on successful execution. \return int negative int returned indicating an error. - + \param pem a pointer to the PEM encoded certificate. \param pemSz the size of the PEM buffer (pem) - \param buff a pointer to the copy of the buffer member of the + \param buff a pointer to the copy of the buffer member of the DerBuffer struct. \param buffSz size of the buffer space allocated in the DerBuffer struct. \param pass password passed into the function. - + _Example_ \code byte* loadBuf; long fileSz = 0; byte* bufSz; - static int LoadKeyFile(byte** keyBuf, word32* keyBufSz, + static int LoadKeyFile(byte** keyBuf, word32* keyBufSz, const char* keyFile, int typeKey, const char* pasword); … @@ -1154,90 +1154,90 @@ WOLFSSL_API int wc_DerToPemEx(const byte* der, word32 derSz, byte* output, // Bytes were written to the buffer. } \endcode - + \sa wc_PemToDer */ WOLFSSL_API int wc_KeyPemToDer(const unsigned char*, int, unsigned char*, int, const char*); - + /*! \ingroup CertsKeys - \brief This function converts a PEM formatted certificate to DER + \brief This function converts a PEM formatted certificate to DER format. Calls OpenSSL function PemToDer. - + \return buffer returns the bytes written to the buffer. - + \param pem pointer PEM formatted certificate. \param pemSz size of the certificate. \param buff buffer to be copied to DER format. \param buffSz size of the buffer. \param type Certificate file type found in asn_public.h enum CertType. - + _Example_ \code const unsigned char* pem; int pemSz; unsigned char buff[BUFSIZE]; int buffSz = sizeof(buff)/sizeof(char); - int type; + int type; ... if(wc_CertPemToDer(pem, pemSz, buff, buffSz, type) <= 0) { // There were bytes written to buffer } \endcode - + \sa wc_PemToDer */ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int, unsigned char*, int, int); - + /*! \ingroup ASN - - \brief This function reads in an ECC private key from the input buffer, - input, parses the private key, and uses it to generate an ecc_key object, + + \brief This function reads in an ECC private key from the input buffer, + input, parses the private key, and uses it to generate an ecc_key object, which it stores in key. - - \return 0 On successfully decoding the private key and storing the result + + \return 0 On successfully decoding the private key and storing the result in the ecc_key struct - \return ASN_PARSE_E: Returned if there is an error parsing the der file + \return ASN_PARSE_E: Returned if there is an error parsing the der file and storing it as a pem file - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return BUFFER_E Returned if the certificate to convert is large than + \return BUFFER_E Returned if the certificate to convert is large than the specified max certificate size - \return ASN_OBJECT_ID_E Returned if the certificate encoding has an + \return ASN_OBJECT_ID_E Returned if the certificate encoding has an invalid object id - \return ECC_CURVE_OID_E Returned if the ECC curve of the provided key is + \return ECC_CURVE_OID_E Returned if the ECC curve of the provided key is not supported \return ECC_BAD_ARG_E Returned if there is an error in the ECC key format - \return NOT_COMPILED_IN Returned if the private key is compressed, and no + \return NOT_COMPILED_IN Returned if the private key is compressed, and no compression key is provided - \return MP_MEM Returned if there is an error in the math library used - while parsing the private key - \return MP_VAL Returned if there is an error in the math library used - while parsing the private key - \return MP_RANGE Returned if there is an error in the math library used + \return MP_MEM Returned if there is an error in the math library used while parsing the private key - + \return MP_VAL Returned if there is an error in the math library used + while parsing the private key + \return MP_RANGE Returned if there is an error in the math library used + while parsing the private key + \param input pointer to the buffer containing the input private key - \param inOutIdx pointer to a word32 object containing the index in + \param inOutIdx pointer to a word32 object containing the index in the buffer at which to start - \param key pointer to an initialized ecc object, on which to store + \param key pointer to an initialized ecc object, on which to store the decoded private key \param inSz size of the input buffer containing the private key - + _Example_ \code int ret, idx=0; - ecc_key key; // to store key in + ecc_key key; // to store key in byte* tmp; // tmp buffer to read key from tmp = (byte*) malloc(FOURK_BUF); int inSz; - inSz = fread(tmp, 1, FOURK_BUF, privateKeyFile); + inSz = fread(tmp, 1, FOURK_BUF, privateKeyFile); // read key into tmp buffer wc_ecc_init(&key); // initialize key @@ -1246,38 +1246,38 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int, // error decoding ecc key } \endcode - + \sa wc_RSA_PrivateKeyDecode */ WOLFSSL_API int wc_EccPrivateKeyDecode(const byte*, word32*, ecc_key*, word32); - + /*! \ingroup ASN - + \brief This function writes a private ECC key to der format. - - \return Success On successfully writing the ECC key to der format, + + \return Success On successfully writing the ECC key to der format, returns the length written to the buffer \return BAD_FUNC_ARG Returned if key or output is null, or inLen equals zero - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return BUFFER_E Returned if the converted certificate is too large + \return BUFFER_E Returned if the converted certificate is too large to store in the output buffer - \return ASN_UNKNOWN_OID_E Returned if the ECC key used is of an + \return ASN_UNKNOWN_OID_E Returned if the ECC key used is of an unknown type - \return MP_MEM Returned if there is an error in the math library used - while parsing the private key - \return MP_VAL Returned if there is an error in the math library used - while parsing the private key - \return MP_RANGE Returned if there is an error in the math library used + \return MP_MEM Returned if there is an error in the math library used while parsing the private key - + \return MP_VAL Returned if there is an error in the math library used + while parsing the private key + \return MP_RANGE Returned if there is an error in the math library used + while parsing the private key + \param key pointer to the buffer containing the input ecc key \param output pointer to a buffer in which to store the der formatted key - \param inLen the length of the buffer in which to store the + \param inLen the length of the buffer in which to store the der formatted key - + _Example_ \code int derSz; @@ -1291,29 +1291,29 @@ WOLFSSL_API int wc_EccPrivateKeyDecode(const byte*, word32*, // error converting ecc key to der buffer } \endcode - + \sa wc_RsaKeyToDer */ WOLFSSL_API int wc_EccKeyToDer(ecc_key*, byte* output, word32 inLen); /*! \ingroup ASN - - \brief Decodes an ECC public key from an input buffer. It will parse an + + \brief Decodes an ECC public key from an input buffer. It will parse an ASN sequence to retrieve the ECC key. - + \return 0 Success \return BAD_FUNC_ARG Returns if any arguments are null. - \return ASN_PARSE_E Returns if there is an error parsing - \return ASN_ECC_KEY_E Returns if there is an error importing the key. + \return ASN_PARSE_E Returns if there is an error parsing + \return ASN_ECC_KEY_E Returns if there is an error importing the key. See wc_ecc_import_x963 for possible reasons. - + \param input Buffer containing DER encoded key to decode. - \param inOutIdx Index to start reading input buffer from. On output, + \param inOutIdx Index to start reading input buffer from. On output, index is set to last position parsed of input buffer. \param key Pointer to ecc_key struct to store the public key. \param inSz Size of the input buffer. - + _Example_ \code int ret; @@ -1325,31 +1325,31 @@ WOLFSSL_API int wc_EccKeyToDer(ecc_key*, byte* output, word32 inLen); // error decoding key } \endcode - + \sa wc_ecc_import_x963 */ WOLFSSL_API int wc_EccPublicKeyDecode(const byte*, word32*, ecc_key*, word32); - + /*! \ingroup ASN - - \brief This function converts the ECC public key to DER format. It - returns the size of buffer used. The public ECC key in DER format is stored - in output buffer. with_AlgCurve is a flag for when to include a header that + + \brief This function converts the ECC public key to DER format. It + returns the size of buffer used. The public ECC key in DER format is stored + in output buffer. with_AlgCurve is a flag for when to include a header that has the Algorithm and Curve information. - + \return >0 Success, size of buffer used \return BAD_FUNC_ARG Returned if output or key is null. \return LENGTH_ONLY_E Error in getting ECC public key size. \return BUFFER_E Returned when output buffer is too small. - + \param key Pointer to ECC key \param output Pointer to output buffer to write to. \param inLen Size of buffer. - \param with_AlgCurve a flag for when to include a header that has the + \param with_AlgCurve a flag for when to include a header that has the Algorithm and Curve information. - + _Example_ \code ecc_key key; @@ -1365,30 +1365,30 @@ WOLFSSL_API int wc_EccPublicKeyDecode(const byte*, word32*, // Error converting ECC public key to der } \endcode - + \sa wc_EccKeyToDer \sa wc_EccPrivateKeyDecode */ WOLFSSL_API int wc_EccPublicKeyToDer(ecc_key*, byte* output, word32 inLen, int with_AlgCurve); - + /*! \ingroup ASN - - \brief This function encodes a digital signature into the output buffer, + + \brief This function encodes a digital signature into the output buffer, and returns the size of the encoded signature created. - - \return Success On successfully writing the encoded signature to output, + + \return Success On successfully writing the encoded signature to output, returns the length written to the buffer - + \param out pointer to the buffer where the encoded signature will be written \param digest pointer to the digest to use to encode the signature \param digSz the length of the buffer containing the digest - \param hashOID OID identifying the hash type used to generate the - signature. Valid options, depending on build configurations, are: SHAh, - SHA256h, SHA384h, SHA512h, MD2h, MD5h, DESb, DES3b, CTC_MD5wRSA, - CTC_SHAwRSA, CTC_SHA256wRSA, CTC_SHA384wRSA, CTC_SHA512wRSA, CTC_SHAwECDSA, - CTC_SHA256wECDSA, CTC_SHA384wECDSA, and CTC_SHA512wECDSA. + \param hashOID OID identifying the hash type used to generate the + signature. Valid options, depending on build configurations, are: SHAh, + SHA256h, SHA384h, SHA512h, MD2h, MD5h, DESb, DES3b, CTC_MD5wRSA, + CTC_SHAwRSA, CTC_SHA256wRSA, CTC_SHA384wRSA, CTC_SHA512wRSA, CTC_SHAwECDSA, + CTC_SHA256wECDSA, CTC_SHA384wECDSA, and CTC_SHA512wECDSA. \endcode \code @@ -1407,22 +1407,22 @@ WOLFSSL_API int wc_EccPublicKeyToDer(ecc_key*, byte* output, */ WOLFSSL_API word32 wc_EncodeSignature(byte* out, const byte* digest, word32 digSz, int hashOID); - + /*! \ingroup ASN - - \brief This function returns the hash OID that corresponds to a hashing - type. For example, when given the type: SHA512, this function returns the + + \brief This function returns the hash OID that corresponds to a hashing + type. For example, when given the type: SHA512, this function returns the identifier corresponding to a SHA512 hash, SHA512h. - - \return Success On success, returns the OID corresponding to the + + \return Success On success, returns the OID corresponding to the appropriate hash to use with that encryption type. \return 0 Returned if an unrecognized hash type is passed in as argument. - - \param type the hash type for which to find the OID. Valid options, - depending on build configuration, include: MD2, MD5, SHA, SHA256, SHA512, + + \param type the hash type for which to find the OID. Valid options, + depending on build configuration, include: MD2, MD5, SHA, SHA256, SHA512, SHA384, and SHA512. - + _Example_ \code int hashOID; @@ -1432,7 +1432,7 @@ WOLFSSL_API word32 wc_EncodeSignature(byte* out, const byte* digest, // WOLFSSL_SHA512 not defined } \endcode - + \sa none */ WOLFSSL_API int wc_GetCTC_HashOID(int type); diff --git a/doc/dox_comments/header_files/blake2.h b/doc/dox_comments/header_files/blake2.h index 1a9d5a6ad..b5953e005 100644 --- a/doc/dox_comments/header_files/blake2.h +++ b/doc/dox_comments/header_files/blake2.h @@ -1,47 +1,47 @@ /*! \ingroup BLAKE2 - - \brief This function initializes a Blake2b structure for use with the + + \brief This function initializes a Blake2b structure for use with the Blake2 hash function. - - \return 0 Returned upon successfully initializing the Blake2b structure and + + \return 0 Returned upon successfully initializing the Blake2b structure and setting the digest size. \param b2b pointer to the Blake2b structure to initialize \param digestSz length of the blake 2 digest to implement - + _Example_ \code Blake2b b2b; // initialize Blake2b structure with 64 byte digest - wc_InitBlake2b(&b2b, 64); + wc_InitBlake2b(&b2b, 64); \endcode - + \sa wc_Blake2bUpdate */ WOLFSSL_API int wc_InitBlake2b(Blake2b*, word32); /*! \ingroup BLAKE2 - - \brief This function updates the Blake2b hash with the given input data. - This function should be called after wc_InitBlake2b, and repeated until + + \brief This function updates the Blake2b hash with the given input data. + This function should be called after wc_InitBlake2b, and repeated until one is ready for the final hash: wc_Blake2bFinal. - - \return 0 Returned upon successfully update the Blake2b structure with + + \return 0 Returned upon successfully update the Blake2b structure with the given data \return -1 Returned if there is a failure while compressing the input data - + \param b2b pointer to the Blake2b structure to update \param data pointer to a buffer containing the data to append \param sz length of the input data to append - + _Example_ \code int ret; Blake2b b2b; // initialize Blake2b structure with 64 byte digest - wc_InitBlake2b(&b2b, 64); + wc_InitBlake2b(&b2b, 64); byte plain[] = { // initialize input }; @@ -50,7 +50,7 @@ WOLFSSL_API int wc_InitBlake2b(Blake2b*, word32); // error updating blake2b } \endcode - + \sa wc_InitBlake2b \sa wc_Blake2bFinal */ @@ -58,29 +58,29 @@ WOLFSSL_API int wc_Blake2bUpdate(Blake2b*, const byte*, word32); /*! \ingroup BLAKE2 - - \brief This function computes the Blake2b hash of the previously supplied - input data. The output hash will be of length requestSz, or, if - requestSz==0, the digestSz of the b2b structure. This function should be - called after wc_InitBlake2b and wc_Blake2bUpdate has been processed for + + \brief This function computes the Blake2b hash of the previously supplied + input data. The output hash will be of length requestSz, or, if + requestSz==0, the digestSz of the b2b structure. This function should be + called after wc_InitBlake2b and wc_Blake2bUpdate has been processed for each piece of input data desired. - + \return 0 Returned upon successfully computing the Blake2b hash \return -1 Returned if there is a failure while parsing the Blake2b hash - + \param b2b pointer to the Blake2b structure to update - \param final pointer to a buffer in which to store the blake2b hash. + \param final pointer to a buffer in which to store the blake2b hash. Should be of length requestSz - \param requestSz length of the digest to compute. When this is zero, + \param requestSz length of the digest to compute. When this is zero, b2b->digestSz will be used instead - + _Example_ \code int ret; Blake2b b2b; byte hash[64]; // initialize Blake2b structure with 64 byte digest - wc_InitBlake2b(&b2b, 64); + wc_InitBlake2b(&b2b, 64); ... // call wc_Blake2bUpdate to add data to hash ret = wc_Blake2bFinal(&b2b, hash, 64); @@ -88,7 +88,7 @@ WOLFSSL_API int wc_Blake2bUpdate(Blake2b*, const byte*, word32); // error generating blake2b hash } \endcode - + \sa wc_InitBlake2b \sa wc_Blake2bUpdate */ diff --git a/doc/dox_comments/header_files/bn.h b/doc/dox_comments/header_files/bn.h index e3dcf1bde..811b9bc7e 100644 --- a/doc/dox_comments/header_files/bn.h +++ b/doc/dox_comments/header_files/bn.h @@ -1,17 +1,17 @@ /*! \ingroup openSSL - + \brief This function performs the following math “r = (a^p) % m”. - + \return SSL_SUCCESS On successfully performing math operation. \return SSL_FAILURE If an error case was encountered. - + \param r structure to hold result. \param a value to be raised by a power. \param p power to raise a by. \param m modulus to use. \param ctx currently not used with wolfSSL can be NULL. - + _Example_ \code WOLFSSL_BIGNUM r,a,p,m; @@ -20,7 +20,7 @@ ret = wolfSSL_BN_mod_exp(r, a, p, m, NULL); // check ret value \endcode - + \sa wolfSSL_BN_new \sa wolfSSL_BN_free */ diff --git a/doc/dox_comments/header_files/camellia.h b/doc/dox_comments/header_files/camellia.h index c6e4db722..c13d0f3ca 100644 --- a/doc/dox_comments/header_files/camellia.h +++ b/doc/dox_comments/header_files/camellia.h @@ -1,23 +1,23 @@ /*! \ingroup Camellia - - \brief This function sets the key and initialization vector for a + + \brief This function sets the key and initialization vector for a camellia object, initializing it for use as a cipher. - - \return 0 Returned upon successfully setting the key and initialization + + \return 0 Returned upon successfully setting the key and initialization vector - \return BAD_FUNC_ARG returned if there is an error processing one of + \return BAD_FUNC_ARG returned if there is an error processing one of the input arguments - \return MEMORY_E returned if there is an error allocating memory with + \return MEMORY_E returned if there is an error allocating memory with XMALLOC \param cam pointer to the camellia structure on which to set the key and iv - \param key pointer to the buffer containing the 16, 24, or 32 byte key + \param key pointer to the buffer containing the 16, 24, or 32 byte key to use for encryption and decryption \param len length of the key passed in - \param iv pointer to the buffer containing the 16 byte initialization + \param iv pointer to the buffer containing the 16 byte initialization vector for use with this camellia structure - + _Example_ \code Camellia cam; @@ -25,11 +25,11 @@ // initialize key byte iv[16]; // initialize iv - if( wc_CamelliaSetKey(&cam, key, sizeof(key), iv) != 0) { + if( wc_CamelliaSetKey(&cam, key, sizeof(key), iv) != 0) { // error initializing camellia structure } \endcode - + \sa wc_CamelliaEncryptDirect \sa wc_CamelliaDecryptDirect \sa wc_CamelliaCbcEncrypt @@ -40,56 +40,56 @@ WOLFSSL_API int wc_CamelliaSetKey(Camellia* cam, /*! \ingroup Camellia - + \brief This function sets the initialization vector for a camellia object. - - \return 0 Returned upon successfully setting the key and initialization + + \return 0 Returned upon successfully setting the key and initialization vector - \return BAD_FUNC_ARG returned if there is an error processing one of the + \return BAD_FUNC_ARG returned if there is an error processing one of the input arguments - + \param cam pointer to the camellia structure on which to set the iv - \param iv pointer to the buffer containing the 16 byte initialization + \param iv pointer to the buffer containing the 16 byte initialization vector for use with this camellia structure - + _Example_ \code Camellia cam; byte iv[16]; // initialize iv - if( wc_CamelliaSetIV(&cam, iv) != 0) { + if( wc_CamelliaSetIV(&cam, iv) != 0) { // error initializing camellia structure } \endcode - + \sa wc_CamelliaSetKey */ WOLFSSL_API int wc_CamelliaSetIV(Camellia* cam, const byte* iv); /*! \ingroup Camellia - - \brief This function does a one-block encrypt using the provided camellia - object. It parses the first 16 byte block from the buffer in and stores - the encrypted result in the buffer out. Before using this function, one - should initialize the camellia object using wc_CamelliaSetKey. - + + \brief This function does a one-block encrypt using the provided camellia + object. It parses the first 16 byte block from the buffer in and stores + the encrypted result in the buffer out. Before using this function, one + should initialize the camellia object using wc_CamelliaSetKey. + \return none No returns. - + \param cam pointer to the camellia structure to use for encryption \param out pointer to the buffer in which to store the encrypted block \param in pointer to the buffer containing the plaintext block to encrypt - + _Example_ \code Camellia cam; // initialize cam structure with key and iv byte plain[] = { // initialize with message to encrypt }; byte cipher[16]; - + wc_CamelliaEncryptDirect(&ca, cipher, plain); \endcode - + \sa wc_CamelliaDecryptDirect */ WOLFSSL_API int wc_CamelliaEncryptDirect(Camellia* cam, byte* out, @@ -97,19 +97,19 @@ WOLFSSL_API int wc_CamelliaEncryptDirect(Camellia* cam, byte* out, /*! \ingroup Camellia - - \brief This function does a one-block decrypt using the provided camellia - object. It parses the first 16 byte block from the buffer in, decrypts it, - and stores the result in the buffer out. Before using this function, one + + \brief This function does a one-block decrypt using the provided camellia + object. It parses the first 16 byte block from the buffer in, decrypts it, + and stores the result in the buffer out. Before using this function, one should initialize the camellia object using wc_CamelliaSetKey. - + \return none No returns. - + \param cam pointer to the camellia structure to use for encryption - \param out pointer to the buffer in which to store the decrypted + \param out pointer to the buffer in which to store the decrypted plaintext block \param in pointer to the buffer containing the ciphertext block to decrypt - + _Example_ \code Camellia cam; @@ -119,7 +119,7 @@ WOLFSSL_API int wc_CamelliaEncryptDirect(Camellia* cam, byte* out, wc_CamelliaDecryptDirect(&cam, decrypted, cipher); \endcode - + \sa wc_CamelliaEncryptDirect */ WOLFSSL_API int wc_CamelliaDecryptDirect(Camellia* cam, byte* out, @@ -127,42 +127,42 @@ WOLFSSL_API int wc_CamelliaDecryptDirect(Camellia* cam, byte* out, /*! \ingroup Camellia - - \brief This function encrypts the plaintext from the buffer in and - stores the output in the buffer out. It performs this encryption + + \brief This function encrypts the plaintext from the buffer in and + stores the output in the buffer out. It performs this encryption using Camellia with Cipher Block Chaining (CBC). - + \return none No returns. - + \param cam pointer to the camellia structure to use for encryption \param out pointer to the buffer in which to store the encrypted ciphertext \param in pointer to the buffer containing the plaintext to encrypt \param sz the size of the message to encrypt - + _Example_ \code Camellia cam; // initialize cam structure with key and iv byte plain[] = { // initialize with encrypted message to decrypt }; byte cipher[sizeof(plain)]; - + wc_CamelliaCbcEncrypt(&cam, cipher, plain, sizeof(plain)); \endcode - + \sa wc_CamelliaCbcDecrypt */ WOLFSSL_API int wc_CamelliaCbcEncrypt(Camellia* cam, byte* out, const byte* in, word32 sz); /*! - \ingroup Camellia - - \brief This function decrypts the ciphertext from the buffer in and - stores the output in the buffer out. It performs this decryption using + \ingroup Camellia + + \brief This function decrypts the ciphertext from the buffer in and + stores the output in the buffer out. It performs this decryption using Camellia with Cipher Block Chaining (CBC). - + \return none No returns. - + \param cam pointer to the camellia structure to use for encryption \param out pointer to the buffer in which to store the decrypted message \param in pointer to the buffer containing the encrypted ciphertext @@ -177,7 +177,7 @@ WOLFSSL_API int wc_CamelliaCbcEncrypt(Camellia* cam, wc_CamelliaCbcDecrypt(&cam, decrypted, cipher, sizeof(cipher)); \endcode - + \sa wc_CamelliaCbcEncrypt */ WOLFSSL_API int wc_CamelliaCbcDecrypt(Camellia* cam, diff --git a/doc/dox_comments/header_files/chacha.h b/doc/dox_comments/header_files/chacha.h index 7ed3af2ff..13aa81f60 100644 --- a/doc/dox_comments/header_files/chacha.h +++ b/doc/dox_comments/header_files/chacha.h @@ -1,19 +1,19 @@ /*! \ingroup ChaCha - - \brief This function sets the initialization vector (nonce) for a ChaCha - object, initializing it for use as a cipher. It should be called after the - key has been set, using wc_Chacha_SetKey. A difference nonce should be + + \brief This function sets the initialization vector (nonce) for a ChaCha + object, initializing it for use as a cipher. It should be called after the + key has been set, using wc_Chacha_SetKey. A difference nonce should be used for each round of encryption. - + \return 0 Returned upon successfully setting the initialization vector - \return BAD_FUNC_ARG returned if there is an error processing the ctx + \return BAD_FUNC_ARG returned if there is an error processing the ctx input argument - + \param ctx pointer to the ChaCha structure on which to set the iv - \param inIv pointer to a buffer containing the 12 byte initialization + \param inIv pointer to a buffer containing the 12 byte initialization vector with which to initialize the ChaCha structure - \param counter the value at which the block counter should start--usually + \param counter the value at which the block counter should start--usually zero. _Example_ @@ -21,12 +21,12 @@ ChaCha enc; // initialize enc with wc_Chacha_SetKey byte iv[12]; - // initialize iv - if( wc_Chacha_SetIV(&enc, iv, 0) != 0) { + // initialize iv + if( wc_Chacha_SetIV(&enc, iv, 0) != 0) { // error initializing ChaCha structure } \endcode - + \sa wc_Chacha_SetKey \sa wc_Chacha_Process */ @@ -34,18 +34,18 @@ WOLFSSL_API int wc_Chacha_SetIV(ChaCha* ctx, const byte* inIv, word32 counter); /*! \ingroup ChaCha - - \brief This function processes the text from the buffer input, encrypts + + \brief This function processes the text from the buffer input, encrypts or decrypts it, and stores the result in the buffer output. - + \return 0 Returned upon successfully encrypting or decrypting the input - \return BAD_FUNC_ARG returned if there is an error processing the ctx + \return BAD_FUNC_ARG returned if there is an error processing the ctx input argument - + \param ctx pointer to the ChaCha structure on which to set the iv - \param output pointer to a buffer in which to store the output ciphertext + \param output pointer to a buffer in which to store the output ciphertext or decrypted plaintext - \param input pointer to the buffer containing the input plaintext to + \param input pointer to the buffer containing the input plaintext to encrypt or the input ciphertext to decrypt \param msglen length of the message to encrypt or the ciphertext to decrypt @@ -56,11 +56,11 @@ WOLFSSL_API int wc_Chacha_SetIV(ChaCha* ctx, const byte* inIv, word32 counter); byte plain[] = { // initialize plaintext }; byte cipher[sizeof(plain)]; - if( wc_Chacha_Process(&enc, cipher, plain, sizeof(plain)) != 0) { + if( wc_Chacha_Process(&enc, cipher, plain, sizeof(plain)) != 0) { // error processing ChaCha cipher } \endcode - + \sa wc_Chacha_SetKey \sa wc_Chacha_Process */ @@ -69,30 +69,30 @@ WOLFSSL_API int wc_Chacha_Process(ChaCha* ctx, byte* cipher, const byte* plain, /*! \ingroup ChaCha - - \brief This function sets the key for a ChaCha object, initializing it for - use as a cipher. It should be called before setting the nonce with + + \brief This function sets the key for a ChaCha object, initializing it for + use as a cipher. It should be called before setting the nonce with wc_Chacha_SetIV, and before using it for encryption with wc_Chacha_Process. - + \return 0 Returned upon successfully setting the key - \return BAD_FUNC_ARG returned if there is an error processing the ctx + \return BAD_FUNC_ARG returned if there is an error processing the ctx input argument or if the key is not 16 or 32 bytes long - + \param ctx pointer to the ChaCha structure in which to set the key - \param key pointer to a buffer containing the 16 or 32 byte key with + \param key pointer to a buffer containing the 16 or 32 byte key with which to initialize the ChaCha structure \param keySz the length of the key passed in - + _Example_ \code ChaCha enc; byte key[] = { // initialize key }; - if( wc_Chacha_SetKey(&enc, key, sizeof(key)) != 0) { + if( wc_Chacha_SetKey(&enc, key, sizeof(key)) != 0) { // error initializing ChaCha structure } \endcode - + \sa wc_Chacha_SetIV \sa wc_Chacha_Process */ diff --git a/doc/dox_comments/header_files/chacha20_poly1305.h b/doc/dox_comments/header_files/chacha20_poly1305.h index 48ae90ff1..1189a4ec1 100644 --- a/doc/dox_comments/header_files/chacha20_poly1305.h +++ b/doc/dox_comments/header_files/chacha20_poly1305.h @@ -1,29 +1,29 @@ /*! \ingroup ChaCha20Poly1305 - - \brief This function encrypts an input message, inPlaintext, using the - ChaCha20 stream cipher, into the output buffer, outCiphertext. It - also performs Poly-1305 authentication (on the cipher text), and + + \brief This function encrypts an input message, inPlaintext, using the + ChaCha20 stream cipher, into the output buffer, outCiphertext. It + also performs Poly-1305 authentication (on the cipher text), and stores the generated authentication tag in the output buffer, outAuthTag. - + \return 0 Returned upon successfully encrypting the message - \return BAD_FUNC_ARG returned if there is an error during the encryption + \return BAD_FUNC_ARG returned if there is an error during the encryption process - - \param inKey pointer to a buffer containing the 32 byte key to use + + \param inKey pointer to a buffer containing the 32 byte key to use for encryption - \param inIv pointer to a buffer containing the 12 byte iv to use for + \param inIv pointer to a buffer containing the 12 byte iv to use for encryption - \param inAAD pointer to the buffer containing arbitrary length additional + \param inAAD pointer to the buffer containing arbitrary length additional authenticated data (AAD) \param inAADLen length of the input AAD - \param inPlaintext pointer to the buffer containing the plaintext to + \param inPlaintext pointer to the buffer containing the plaintext to encrypt \param inPlaintextLen the length of the plain text to encrypt \param outCiphertext pointer to the buffer in which to store the ciphertext - \param outAuthTag pointer to a 16 byte wide buffer in which to store the + \param outAuthTag pointer to a 16 byte wide buffer in which to store the authentication tag - + _Example_ \code byte key[] = { // initialize 32 byte key }; @@ -41,7 +41,7 @@ // error running encrypt } \endcode - + \sa wc_ChaCha20Poly1305_Decrypt \sa wc_ChaCha_* \sa wc_Poly1305* @@ -56,32 +56,32 @@ int wc_ChaCha20Poly1305_Encrypt( byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]); /*! - \ingroup ChaCha20Poly1305 - - \brief This function decrypts input ciphertext, inCiphertext, using the - ChaCha20 stream cipher, into the output buffer, outPlaintext. It also - performs Poly-1305 authentication, comparing the given inAuthTag to an - authentication generated with the inAAD (arbitrary length additional - authentication data). Note: If the generated authentication tag does + \ingroup ChaCha20Poly1305 + + \brief This function decrypts input ciphertext, inCiphertext, using the + ChaCha20 stream cipher, into the output buffer, outPlaintext. It also + performs Poly-1305 authentication, comparing the given inAuthTag to an + authentication generated with the inAAD (arbitrary length additional + authentication data). Note: If the generated authentication tag does not match the supplied authentication tag, the text is not decrypted. - + \return 0 Returned upon successfully decrypting the message - \return BAD_FUNC_ARG Returned if any of the function arguments do not + \return BAD_FUNC_ARG Returned if any of the function arguments do not match what is expected - \return MAC_CMP_FAILED_E Returned if the generated authentication tag + \return MAC_CMP_FAILED_E Returned if the generated authentication tag does not match the supplied inAuthTag. - - \param inKey pointer to a buffer containing the 32 byte key to use for + + \param inKey pointer to a buffer containing the 32 byte key to use for decryption - \param inIv pointer to a buffer containing the 12 byte iv to use for + \param inIv pointer to a buffer containing the 12 byte iv to use for decryption - \param inAAD pointer to the buffer containing arbitrary length additional + \param inAAD pointer to the buffer containing arbitrary length additional authenticated data (AAD) \param inAADLen length of the input AAD - \param inCiphertext pointer to the buffer containing the ciphertext to + \param inCiphertext pointer to the buffer containing the ciphertext to decrypt \param outCiphertextLen the length of the ciphertext to decrypt - \param inAuthTag pointer to the buffer containing the 16 byte digest + \param inAuthTag pointer to the buffer containing the 16 byte digest for authentication \param outPlaintext pointer to the buffer in which to store the plaintext @@ -105,7 +105,7 @@ int wc_ChaCha20Poly1305_Encrypt( // error with function arguments } \endcode - + \sa wc_ChaCha20Poly1305_Encrypt \sa wc_ChaCha_* \sa wc_Poly1305* diff --git a/doc/dox_comments/header_files/coding.h b/doc/dox_comments/header_files/coding.h index 455ad0c19..41c642a62 100644 --- a/doc/dox_comments/header_files/coding.h +++ b/doc/dox_comments/header_files/coding.h @@ -1,37 +1,37 @@ /*! \ingroup Base_Encoding - - \brief This function decodes the given Base64 encoded input, in, and - stores the result in the output buffer out. It also sets the size + + \brief This function decodes the given Base64 encoded input, in, and + stores the result in the output buffer out. It also sets the size written to the output buffer in the variable outLen. - + \return 0 Returned upon successfully decoding the Base64 encoded input - \return BAD_FUNC_ARG Returned if the output buffer is too small to + \return BAD_FUNC_ARG Returned if the output buffer is too small to store the decoded input - \return ASN_INPUT_E Returned if a character in the input buffer falls - outside of the Base64 range ([A-Za-z0-9+/=]) or if there is an invalid + \return ASN_INPUT_E Returned if a character in the input buffer falls + outside of the Base64 range ([A-Za-z0-9+/=]) or if there is an invalid line ending in the Base64 encoded input \param in pointer to the input buffer to decode \param inLen length of the input buffer to decode - \param out pointer to the output buffer in which to store the decoded + \param out pointer to the output buffer in which to store the decoded message - \param outLen pointer to the length of the output buffer. Updated with + \param outLen pointer to the length of the output buffer. Updated with the bytes written at the end of the function call _Example_ \code byte encoded[] = { // initialize text to decode }; - byte decoded[sizeof(encoded)]; + byte decoded[sizeof(encoded)]; // requires at least (sizeof(encoded) * 3 + 3) / 4 room int outLen = sizeof(decoded); - if( Base64_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) { + if( Base64_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) { // error decoding input buffer } \endcode - + \sa Base64_Encode \sa Base16_Decode */ @@ -40,38 +40,38 @@ WOLFSSL_API int Base64_Decode(const byte* in, word32 inLen, byte* out, /*! \ingroup Base_Encoding - - \brief This function encodes the given input, in, and stores the Base64 - encoded result in the output buffer out. It writes the data with the - traditional ‘\n’ line endings, instead of escaped %0A line endings. Upon - successfully completing, this function also sets outLen to the number + + \brief This function encodes the given input, in, and stores the Base64 + encoded result in the output buffer out. It writes the data with the + traditional ‘\n’ line endings, instead of escaped %0A line endings. Upon + successfully completing, this function also sets outLen to the number of bytes written to the output buffer. - + \return 0 Returned upon successfully decoding the Base64 encoded input - \return BAD_FUNC_ARG Returned if the output buffer is too small to + \return BAD_FUNC_ARG Returned if the output buffer is too small to store the encoded input - \return BUFFER_E Returned if the output buffer runs out of room + \return BUFFER_E Returned if the output buffer runs out of room while encoding \param in pointer to the input buffer to encode \param inLen length of the input buffer to encode - \param out pointer to the output buffer in which to store the + \param out pointer to the output buffer in which to store the encoded message - \param outLen pointer to the length of the output buffer in + \param outLen pointer to the length of the output buffer in which to store the encoded message _Example_ \code byte plain[] = { // initialize text to encode }; - byte encoded[MAX_BUFFER_SIZE]; + byte encoded[MAX_BUFFER_SIZE]; int outLen = sizeof(encoded); - if( Base64_Encode(plain, sizeof(plain), encoded, &outLen) != 0 ) { + if( Base64_Encode(plain, sizeof(plain), encoded, &outLen) != 0 ) { // error encoding input buffer } \endcode - + \sa Base64_EncodeEsc \sa Base64_Decode */ @@ -81,40 +81,40 @@ int Base64_Encode(const byte* in, word32 inLen, byte* out, /*! \ingroup Base_Encoding - - \brief This function encodes the given input, in, and stores the - Base64 encoded result in the output buffer out. It writes the data - with %0A escaped line endings instead of ‘\n’ line endings. - Upon successfully completing, this function also sets outLen + + \brief This function encodes the given input, in, and stores the + Base64 encoded result in the output buffer out. It writes the data + with %0A escaped line endings instead of ‘\n’ line endings. + Upon successfully completing, this function also sets outLen to the number of bytes written to the output buffer. - + \return 0 Returned upon successfully decoding the Base64 encoded input - \return BAD_FUNC_ARG Returned if the output buffer is too small + \return BAD_FUNC_ARG Returned if the output buffer is too small to store the encoded input - \return BUFFER_E Returned if the output buffer runs out of + \return BUFFER_E Returned if the output buffer runs out of room while encoding - \return ASN_INPUT_E Returned if there is an error processing + \return ASN_INPUT_E Returned if there is an error processing the decode on the input message \param in pointer to the input buffer to encode \param inLen length of the input buffer to encode - \param out pointer to the output buffer in which to store + \param out pointer to the output buffer in which to store the encoded message - \param outLen pointer to the length of the output buffer in + \param outLen pointer to the length of the output buffer in which to store the encoded message _Example_ \code byte plain[] = { // initialize text to encode }; - byte encoded[MAX_BUFFER_SIZE]; + byte encoded[MAX_BUFFER_SIZE]; int outLen = sizeof(encoded); - if( Base64_EncodeEsc(plain, sizeof(plain), encoded, &outLen) != 0 ) { + if( Base64_EncodeEsc(plain, sizeof(plain), encoded, &outLen) != 0 ) { // error encoding input buffer } \endcode - + \sa Base64_Encode \sa Base64_Decode */ @@ -123,37 +123,37 @@ int Base64_EncodeEsc(const byte* in, word32 inLen, byte* out, /*! \ingroup Base_Encoding - - \brief This function encodes the given input, in, and stores the - Base64 encoded result in the output buffer out. It writes the data - with no new lines. Upon successfully completing, this function + + \brief This function encodes the given input, in, and stores the + Base64 encoded result in the output buffer out. It writes the data + with no new lines. Upon successfully completing, this function also sets outLen to the number of bytes written to the output buffer - + \return 0 Returned upon successfully decoding the Base64 encoded input - \return BAD_FUNC_ARG Returned if the output buffer is too small + \return BAD_FUNC_ARG Returned if the output buffer is too small to store the encoded input - \return BUFFER_E Returned if the output buffer runs out of room + \return BUFFER_E Returned if the output buffer runs out of room while encoding - \return ASN_INPUT_E Returned if there is an error processing the + \return ASN_INPUT_E Returned if there is an error processing the decode on the input message \param in pointer to the input buffer to encode \param inLen length of the input buffer to encode - \param out pointer to the output buffer in which to store the + \param out pointer to the output buffer in which to store the encoded message - \param outLen pointer to the length of the output buffer in which to + \param outLen pointer to the length of the output buffer in which to store the encoded message _Example_ \code byte plain[] = { // initialize text to encode }; - byte encoded[MAX_BUFFER_SIZE]; + byte encoded[MAX_BUFFER_SIZE]; int outLen = sizeof(encoded); - if( Base64_Encode_NoNl(plain, sizeof(plain), encoded, &outLen) != 0 ) { + if( Base64_Encode_NoNl(plain, sizeof(plain), encoded, &outLen) != 0 ) { // error encoding input buffer } \endcode - + \sa Base64_Encode \sa Base64_Decode */ @@ -163,35 +163,35 @@ int Base64_Encode_NoNl(const byte* in, word32 inLen, byte* out, /*! \ingroup Base_Encoding - - \brief This function decodes the given Base16 encoded input, in, and - stores the result in the output buffer out. It also sets the size written + + \brief This function decodes the given Base16 encoded input, in, and + stores the result in the output buffer out. It also sets the size written to the output buffer in the variable outLen. - + \return 0 Returned upon successfully decoding the Base16 encoded input - \return BAD_FUNC_ARG Returned if the output buffer is too small to store + \return BAD_FUNC_ARG Returned if the output buffer is too small to store the decoded input or if the input length is not a multiple of two - \return ASN_INPUT_E Returned if a character in the input buffer falls + \return ASN_INPUT_E Returned if a character in the input buffer falls outside of the Base16 range ([0-9A-F]) \param in pointer to the input buffer to decode \param inLen length of the input buffer to decode - \param out pointer to the output buffer in which to store the decoded + \param out pointer to the output buffer in which to store the decoded message - \param outLen pointer to the length of the output buffer. Updated with the + \param outLen pointer to the length of the output buffer. Updated with the bytes written at the end of the function call _Example_ \code byte encoded[] = { // initialize text to decode }; - byte decoded[sizeof(encoded)]; + byte decoded[sizeof(encoded)]; int outLen = sizeof(decoded); - if( Base16_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) { + if( Base16_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) { // error decoding input buffer } \endcode - + \sa Base64_Encode \sa Base64_Decode \sa Base16_Encode @@ -201,13 +201,13 @@ int Base16_Decode(const byte* in, word32 inLen, byte* out, word32* outLen); /*! \ingroup Base_Encoding - + \brief Encode input to base16 output. - + \return 0 Success - \return BAD_FUNC_ARG Returns if in, out, or outLen is null or if outLen is + \return BAD_FUNC_ARG Returns if in, out, or outLen is null or if outLen is less than 2 times inLen plus 1. - + \param in Pointer to input buffer to be encoded. \param inLen Length of input buffer. \param out Pointer to output buffer. @@ -221,10 +221,10 @@ int Base16_Decode(const byte* in, word32 inLen, byte* out, word32* outLen); if(Base16_Encode(in, sizeof(in), out, &outSz) != 0) { - // Handle encode error + // Handle encode error } \endcode - + \sa Base64_Encode \sa Base64_Decode \sa Base16_Decode diff --git a/doc/dox_comments/header_files/compress.h b/doc/dox_comments/header_files/compress.h index 1075b3c5f..869aa3272 100644 --- a/doc/dox_comments/header_files/compress.h +++ b/doc/dox_comments/header_files/compress.h @@ -1,72 +1,72 @@ /*! \ingroup Compression - - \brief This function compresses the given input data using Huffman coding - and stores the output in out. Note that the output buffer should still be - larger than the input buffer because there exists a certain input for - which there will be no compression possible, which will still require a - lookup table. It is recommended that one allocate srcSz + 0.1% + 12 for + + \brief This function compresses the given input data using Huffman coding + and stores the output in out. Note that the output buffer should still be + larger than the input buffer because there exists a certain input for + which there will be no compression possible, which will still require a + lookup table. It is recommended that one allocate srcSz + 0.1% + 12 for the output buffer. - - \return On successfully compressing the input data, returns the number + + \return On successfully compressing the input data, returns the number of bytes stored in the output buffer - \return COMPRESS_INIT_E Returned if there is an error initializing the + \return COMPRESS_INIT_E Returned if there is an error initializing the stream for compression \return COMPRESS_E Returned if an error occurs during compression - \param out pointer to the output buffer in which to store the compressed + \param out pointer to the output buffer in which to store the compressed data - \param outSz size available in the output buffer for storage + \param outSz size available in the output buffer for storage \param in pointer to the buffer containing the message to compress \param inSz size of the input message to compress - \param flags flags to control how compression operates. Use 0 for normal + \param flags flags to control how compression operates. Use 0 for normal decompression - + _Example_ \code byte message[] = { // initialize text to compress }; - byte compressed[(sizeof(message) + sizeof(message) * .001 + 12 )]; + byte compressed[(sizeof(message) + sizeof(message) * .001 + 12 )]; // Recommends at least srcSz + .1% + 12 - if( wc_Compress(compressed, sizeof(compressed), message, sizeof(message), - 0) != 0){ + if( wc_Compress(compressed, sizeof(compressed), message, sizeof(message), + 0) != 0){ // error compressing data } \endcode - + \sa wc_DeCompress */ WOLFSSL_API int wc_Compress(byte*, word32, const byte*, word32, word32); /*! \ingroup Compression - - \brief This function decompresses the given compressed data using Huffman + + \brief This function decompresses the given compressed data using Huffman coding and stores the output in out. - - \return Succes On successfully decompressing the input data, returns the + + \return Succes On successfully decompressing the input data, returns the number of bytes stored in the output buffer - \return COMPRESS_INIT_E: Returned if there is an error initializing the + \return COMPRESS_INIT_E: Returned if there is an error initializing the stream for compression \return COMPRESS_E: Returned if an error occurs during compression - \param out pointer to the output buffer in which to store the decompressed + \param out pointer to the output buffer in which to store the decompressed data - \param outSz size available in the output buffer for storage + \param outSz size available in the output buffer for storage \param in pointer to the buffer containing the message to decompress \param inSz size of the input message to decompress - + _Example_ \code byte compressed[] = { // initialize compressed message }; - byte decompressed[MAX_MESSAGE_SIZE]; + byte decompressed[MAX_MESSAGE_SIZE]; - if( wc_DeCompress(decompressed, sizeof(decompressed), - compressed, sizeof(compressed)) != 0 ) { + if( wc_DeCompress(decompressed, sizeof(decompressed), + compressed, sizeof(compressed)) != 0 ) { // error decompressing data } \endcode - + \sa wc_Compress */ WOLFSSL_API int wc_DeCompress(byte*, word32, const byte*, word32); diff --git a/doc/dox_comments/header_files/curve25519.h b/doc/dox_comments/header_files/curve25519.h index 66280e2b7..dd9bf70b6 100644 --- a/doc/dox_comments/header_files/curve25519.h +++ b/doc/dox_comments/header_files/curve25519.h @@ -1,24 +1,24 @@ /*! \ingroup Curve25519 - - \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 + + \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. - - \return 0 Returned on successfully generating the key and and storing + + \return 0 Returned on successfully generating the key and and storing it in the given curve25519_key structure - \return ECC_BAD_ARG_E Returned if rng or key evaluate to NULL, or - the input keysize does not correspond to the keysize for a + \return ECC_BAD_ARG_E Returned if rng or key evaluate to NULL, or + the input keysize does not correspond to the keysize for a curve25519 key ( 32 bytes) - \return RNG_FAILURE_E Returned if the rng internal status is not + \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 - + \param 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 key pointer to the curve25519_key structure in which to + \param key pointer to the curve25519_key structure in which to store the generated key - + _Example_ \code curve25519_key key; @@ -26,11 +26,11 @@ WC_RNG rng; wc_InitRng(&rng); // initialize random number generator - if( wc_curve25519_make_key(&rng, 32, &key) != 0) { + if( wc_curve25519_make_key(&rng, 32, &key) != 0) { // making 25519 key } \endcode - + \sa wc_curve25519_init */ WOLFSSL_API @@ -38,25 +38,25 @@ int wc_curve25519_make_key(WC_RNG* rng, int keysize, curve25519_key* key); /*! \ingroup Curve25519 - - \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 + + \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 + \return BAD_FUNC_ARG Returned if any of the input parameters passed in are NULL - \return ECC_BAD_ARG_E Returned if the first bit of the public key is + \return ECC_BAD_ARG_E Returned if the first bit of the public key is set, to avoid implementation fingerprinting - - \param private_key pointer to the curve25519_key structure initialized + + \param private_key pointer to the curve25519_key structure initialized with the user’s private key - \param public_key pointer to the curve25519_key structure containing + \param public_key pointer to the curve25519_key structure containing the received public key - \param out pointer to a buffer in which to store the 32 byte computed + \param out pointer to a buffer in which to store the 32 byte computed secret key - \param outlen pointer in which to store the length written to the + \param outlen pointer in which to store the length written to the output buffer _Example_ @@ -66,12 +66,12 @@ int wc_curve25519_make_key(WC_RNG* rng, int keysize, curve25519_key* key); curve25519_key privKey, pubKey; // initialize both keys - if ( wc_curve25519_shared_secret(&privKey, &pubKey, sharedKey, + if ( wc_curve25519_shared_secret(&privKey, &pubKey, sharedKey, &keySz) != 0 ) { // error generating shared key } \endcode - + \sa wc_curve25519_init \sa wc_curve25519_make_key \sa wc_curve25519_shared_secret_ex @@ -83,27 +83,27 @@ int wc_curve25519_shared_secret(curve25519_key* private_key, /*! \ingroup Curve25519 - - \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 + + \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 + \return BAD_FUNC_ARG Returned if any of the input parameters passed in are NULL - \return ECC_BAD_ARG_E Returned if the first bit of the public key is set, + \return ECC_BAD_ARG_E Returned if the first bit of the public key is set, to avoid implementation fingerprinting - - \param private_key pointer to the curve25519_key structure initialized + + \param private_key pointer to the curve25519_key structure initialized with the user’s private key - \param public_key pointer to the curve25519_key structure containing + \param public_key pointer to the curve25519_key structure containing the received public key - \param out pointer to a buffer in which to store the 32 byte computed + \param out pointer to a buffer in which to store the 32 byte computed secret key - \param outlen pointer in which to store the length written to the output + \param outlen pointer in which to store the length written to the output buffer - \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which + \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use. _Example_ @@ -114,12 +114,12 @@ int wc_curve25519_shared_secret(curve25519_key* private_key, curve25519_key privKey, pubKey; // initialize both keys - if ( wc_curve25519_shared_secret_ex(&privKey, &pubKey, sharedKey, &keySz, + if ( wc_curve25519_shared_secret_ex(&privKey, &pubKey, sharedKey, &keySz, EC25519_BIG_ENDIAN) != 0 ) { // error generating shared key } \endcode - + \sa wc_curve25519_init \sa wc_curve25519_make_key \sa wc_curve25519_shared_secret @@ -131,12 +131,12 @@ int wc_curve25519_shared_secret_ex(curve25519_key* private_key, /*! \ingroup Curve25519 - - \brief This function initializes a curve25519 key. It should be called - before generating a key for the structure with wc_curve25519_init and + + \brief This function initializes a curve25519 key. It should be called + before generating a key for the structure with wc_curve25519_init and before using the key to encrypt data. - - \return 0 Returned on successfully initializing the curve25519_key + + \return 0 Returned on successfully initializing the curve25519_key structure \param key pointer to the curve25519_key structure to initialize @@ -147,7 +147,7 @@ int wc_curve25519_shared_secret_ex(curve25519_key* private_key, wc_curve25519_init(&key); // initialize key // make key and proceed to encryption \endcode - + \sa wc_curve25519_make_key */ WOLFSSL_API @@ -155,13 +155,13 @@ int wc_curve25519_init(curve25519_key* key); /*! \ingroup Curve25519 - + \brief This function frees a curve 25519 object. - + \return none No returns. - + \param key pointer to the key object to free - + _Example_ \code curve25519_key privKey; @@ -177,14 +177,14 @@ void wc_curve25519_free(curve25519_key* key); /*! \ingroup Curve25519 - + \brief This function imports a curve25519 private key only. (Big endian). - + \return 0 Success \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 wc_curve25519_size(key). - + \param priv Private key buffer \param privSz Size of private key buffer. \param key The curve25519_key structure to store the private key. @@ -200,7 +200,7 @@ void wc_curve25519_free(curve25519_key* key); // Some error was thrown } \endcode - + \sa wc_curve25519_import_private_ex \sa wc_curve25519_size */ @@ -210,18 +210,18 @@ int wc_curve25519_import_private(const byte* priv, word32 privSz, /*! \ingroup Curve25519 - + \brief curve25519 private key import only. (Big or Little endian). - + \return 0 Success \return 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 wc_curve25519_size(key). \param priv Buffer for private key. \param privSz Size of private key buffer. \param key The curve25519_key structure to store the private key. - \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to + \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use. _Example_ @@ -230,14 +230,14 @@ int wc_curve25519_import_private(const byte* priv, word32 privSz, curve25519_key key; wc_curve25519_init(&key); - if(wc_curve25519_import_private_ex(priv, sizeof(priv), &key, + if(wc_curve25519_import_private_ex(priv, sizeof(priv), &key, EC25519_BIG_ENDIAN) != 0) { // Some error was thrown } \endcode - + \sa wc_curve25519_import_private \sa wc_curbe25519_size */ @@ -247,15 +247,15 @@ int wc_curve25519_import_private_ex(const byte* priv, word32 privSz, /*! \ingroup Curve25519 - - \brief This function imports a public-private key pair into a + + \brief This function imports a public-private key pair into a 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 - are NULL, or the input key’s key size does not match the public + \return ECC_BAD_ARG_E Returned if any of the input parameters + are NULL, 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 privSz length of the private key to import \param pub pointer to a buffer containing the public key to import @@ -272,19 +272,19 @@ int wc_curve25519_import_private_ex(const byte* priv, word32 privSz, curve25519_key key; wc_curve25519_init(&key); - // initialize key + // initialize key - ret = wc_curve25519_import_private_raw(&priv, sizeof(priv), pub, + ret = wc_curve25519_import_private_raw(&priv, sizeof(priv), pub, sizeof(pub),&key); if (ret != 0) { // error importing keys } \endcode - + \sa wc_curve25519_init \sa wc_curve25519_make_key \sa wc_curve25519_import_public - \sa wc_curve25519_export_private_raw + \sa wc_curve25519_export_private_raw */ WOLFSSL_API int wc_curve25519_import_private_raw(const byte* priv, word32 privSz, @@ -292,19 +292,19 @@ int wc_curve25519_import_private_raw(const byte* priv, word32 privSz, /*! \ingroup Curve25519 - + \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 ECC_BAD_ARG_E Returned if any of the input parameters are NULL, 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 privSz length of the private key to import \param pub pointer to a buffer containing the public key to import \param pubSz length of the public key to import \param key pointer to the structure in which to store the imported keys - \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set + \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use. _Example_ @@ -316,9 +316,9 @@ int wc_curve25519_import_private_raw(const byte* priv, word32 privSz, curve25519_key key; wc_curve25519_init(&key); - // initialize key + // initialize key - ret = wc_curve25519_import_private_raw_ex(&priv, sizeof(priv), pub, + ret = wc_curve25519_import_private_raw_ex(&priv, sizeof(priv), pub, sizeof(pub),&key, EC25519_BIG_ENDIAN); if (ret != 0) { // error importing keys @@ -338,16 +338,16 @@ int wc_curve25519_import_private_raw_ex(const byte* priv, word32 privSz, /*! \ingroup Curve25519 - - \brief This function exports a private key from a curve25519_key structure - and stores it in the given out buffer. It also sets outLen to be the size + + \brief This function exports a private key from a curve25519_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 + + \return 0 Returned on successfully exporting the private key 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. - + \param 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 outLen will store the bytes written to the output buffer @@ -378,12 +378,12 @@ int wc_curve25519_export_private_raw(curve25519_key* key, byte* out, /*! \ingroup Curve25519 - - \brief This function exports a private key from a curve25519_key structure - and stores it in the given out buffer. It also sets outLen to be the size + + \brief This function exports a private key from a curve25519_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 + + \return 0 Returned on successfully exporting the private key 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. @@ -391,7 +391,7 @@ int wc_curve25519_export_private_raw(curve25519_key* key, byte* out, \param 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 outLen will store the bytes written to the output buffer - \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which + \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use. _Example_ @@ -402,7 +402,7 @@ int wc_curve25519_export_private_raw(curve25519_key* key, byte* out, int privSz; curve25519_key key; // initialize and make key - ret = wc_curve25519_export_private_raw_ex(&key, priv, &privSz, + ret = wc_curve25519_export_private_raw_ex(&key, priv, &privSz, EC25519_BIG_ENDIAN); if (ret != 0) { // error exporting key @@ -421,20 +421,20 @@ int wc_curve25519_export_private_raw_ex(curve25519_key* key, byte* out, /*! \ingroup Curve25519 - - \brief This function imports a public key from the given in buffer and + + \brief This function imports a public key from the given in buffer and stores it in the curve25519_key structure. - - \return 0 Returned on successfully importing the public key into the + + \return 0 Returned on successfully importing the public key into the curve25519_key structure - \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL, - or if the inLen + \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL, + or 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 pointer to the buffer containing the public key to import \param inLen length of the public key to import - \param key pointer to the curve25519_key structure in which to store + \param key pointer to the curve25519_key structure in which to store the key _Example_ @@ -452,7 +452,7 @@ parameter does not match the key size of the key structure. // error exporting key } \endcode - + \sa wc_curve25519_init \sa wc_curve25519_export_public \sa wc_curve25519_import_private_raw @@ -464,23 +464,23 @@ int wc_curve25519_import_public(const byte* in, word32 inLen, /*! \ingroup Curve25519 - - \brief This function imports a public key from the given in buffer and + + \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 + + \brief 0 Returned on successfully importing the public key into the curve25519_key structure - \brief ECC_BAD_ARG_E Returned if the inLen parameter does not match the + \brief ECC_BAD_ARG_E Returned if the inLen parameter does not match the key size of the key structure \brief 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 inLen length of the public key to import - \param key pointer to the curve25519_key structure in which to store + \param key pointer to the curve25519_key structure in which to store the key - \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which + \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use. - + _Example_ \code int ret; @@ -489,7 +489,7 @@ int wc_curve25519_import_public(const byte* in, word32 inLen, curve25519_key key; // initialize key - ret = wc_curve25519_import_public_ex(pub,sizeof(pub), &key, + ret = wc_curve25519_import_public_ex(pub,sizeof(pub), &key, EC25519_BIG_ENDIAN); if (ret != 0) { // error exporting key @@ -508,19 +508,19 @@ 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 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 + + \return 0 Returned on successfully exporting the public key from the curve25519_key structure \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL - - \param key pointer to the curve25519_key structure in from which to + + \param key pointer to the curve25519_key structure in from which to export the key \param out pointer to the buffer in which to store the public key \param outLen will store the bytes written to the output buffer - + _Example_ \code int ret; @@ -533,7 +533,7 @@ int wc_curve25519_import_public_ex(const byte* in, word32 inLen, // error exporting key } \endcode - + \sa wc_curve25519_init \sa wc_curve25519_export_private_raw \sa wc_curve25519_import_public @@ -543,21 +543,21 @@ int wc_curve25519_export_public(curve25519_key* key, byte* out, word32* outLen); /*! \ingroup Curve25519 - - \brief This function exports a public key from the given key structure and + + \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 + + \return 0 Returned on successfully exporting the public key from the curve25519_key structure \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL - \param key pointer to the curve25519_key structure in from which to + \param key pointer to the curve25519_key structure in from which to export the key \param out pointer to the buffer in which to store the public key \param outLen will store the bytes written to the output buffer - \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which + \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use. - + _Example_ \code int ret; @@ -572,7 +572,7 @@ int wc_curve25519_export_public(curve25519_key* key, byte* out, word32* outLen); // error exporting key } \endcode - + \sa wc_curve25519_init \sa wc_curve25519_export_private_raw \sa wc_curve25519_import_public @@ -583,19 +583,19 @@ int wc_curve25519_export_public_ex(curve25519_key* key, byte* out, /*! \ingroup Curve25519 - + \brief Export curve25519 key pair. Big endian only. - + \return 0 Success \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 Description \param priv Private key buffer. \param privSz Size of private key buffer. \param pub Public key buffer. \param pubSz Size of public key buffer. - + _Example_ \code int ret; @@ -612,7 +612,7 @@ int wc_curve25519_export_public_ex(curve25519_key* key, byte* out, // error exporting key } \endcode - + \sa wc_curve25519_export_key_raw_ex \sa wc_curve25519_export_private_raw \sa wc_curve25519_export_public_raw @@ -624,19 +624,19 @@ int wc_curve25519_export_key_raw(curve25519_key* key, /*! \ingroup Curve25519 - + \brief Export curve25519 key pair. 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 wc_curve25519_size() is not equal to key. - + \param key Description \param priv Private key buffer. \param privSz Size of private key buffer. \param pub Public key buffer. \param pubSz Size of public key buffer. - \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which + \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which form to use. _Example_ @@ -651,13 +651,13 @@ int wc_curve25519_export_key_raw(curve25519_key* key, curve25519_key key; // initialize and make key - ret = wc_curve25519_export_key_raw_ex(&key,priv, &privSz, pub, &pubSz, + ret = wc_curve25519_export_key_raw_ex(&key,priv, &privSz, pub, &pubSz, EC25519_BIG_ENDIAN); if (ret != 0) { // error exporting key } \endcode - + \sa wc_curve25519_export_key_raw \sa wc_curve25519_export_private_raw_ex \sa wc_curve25519_export_public_ex @@ -670,16 +670,16 @@ int wc_curve25519_export_key_raw_ex(curve25519_key* key, /*! \ingroup Curve25519 - + \brief This function returns the key size of the given key structure. - - \return Success Given a valid, initialized curve25519_key structure, - returns the size of the key. + + \return Success Given a valid, initialized curve25519_key structure, + 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 key pointer to the curve25519_key structure in for which to determine the key size - + _Example_ \code curve25519_key key; @@ -687,7 +687,7 @@ int wc_curve25519_export_key_raw_ex(curve25519_key* key, int keySz; keySz = wc_curve25519_size(&key); \endcode - + \sa wc_curve25519_init \sa wc_curve25519_make_key */ diff --git a/doc/dox_comments/header_files/des3.h b/doc/dox_comments/header_files/des3.h index 1fe70a715..3a788508c 100644 --- a/doc/dox_comments/header_files/des3.h +++ b/doc/dox_comments/header_files/des3.h @@ -1,23 +1,23 @@ /*! \ingroup 3DES - - \brief This function sets the key and initialization vector (iv) for the - Des structure given as argument. It also initializes and allocates space - for the buffers needed for encryption and decryption, if these have not - yet been initialized. Note: If no iv is provided (i.e. iv == NULL) + + \brief This function sets the key and initialization vector (iv) for the + Des structure given as argument. It also initializes and allocates space + for the buffers needed for encryption and decryption, if these have not + yet been initialized. Note: If no iv is provided (i.e. iv == NULL) the initialization vector defaults to an iv of 0. - - \return 0 On successfully setting the key and initialization vector for + + \return 0 On successfully setting the key and initialization vector for the Des structure - + \param des pointer to the Des structure to initialize - \param key pointer to the buffer containing the 8 byte key with which to + \param key pointer to the buffer containing the 8 byte key with which to initialize the Des structure - \param iv pointer to the buffer containing the 8 byte iv with which to + \param iv pointer to the buffer containing the 8 byte iv with which to initialize the Des structure. If this is not provided, the iv defaults to 0 - \param dir direction of encryption. Valid options are: DES_ENCRYPTION, + \param dir direction of encryption. Valid options are: DES_ENCRYPTION, and DES_DECRYPTION - + _Example_ \code Des enc; // Des structure used for encryption @@ -30,7 +30,7 @@ // error initializing des structure } \endcode - + \sa wc_Des_SetIV \sa wc_Des3_SetKey */ @@ -39,15 +39,15 @@ WOLFSSL_API int wc_Des_SetKey(Des* des, const byte* key, /*! \ingroup 3DES - - \brief This function sets the initialization vector (iv) for the Des - structure given as argument. When passed a NULL iv, it sets the + + \brief This function sets the initialization vector (iv) for the Des + structure given as argument. When passed a NULL iv, it sets the initialization vector to 0. - + \return none No returns. - + \param des pointer to the Des structure for which to set the iv - \param iv pointer to the buffer containing the 8 byte iv with which to + \param iv pointer to the buffer containing the 8 byte iv with which to initialize the Des structure. If this is not provided, the iv defaults to 0 _Example_ @@ -58,20 +58,20 @@ WOLFSSL_API int wc_Des_SetKey(Des* des, const byte* key, wc_Des_SetIV(&enc, iv); } \endcode - + \sa wc_Des_SetKey */ WOLFSSL_API void wc_Des_SetIV(Des* des, const byte* iv); /*! \ingroup 3DES - - \brief This function encrypts the input message, in, and stores the result - in the output buffer, out. It uses DES encryption with cipher block + + \brief This function encrypts the input message, in, and stores the result + in the output buffer, out. It uses DES encryption with cipher block chaining (CBC) mode. - + \return 0 Returned upon successfully encrypting the given input message - + \param des pointer to the Des structure to use for encryption \param out pointer to the buffer in which to store the encrypted ciphertext \param in pointer to the input buffer containing the message to encrypt @@ -85,11 +85,11 @@ WOLFSSL_API void wc_Des_SetIV(Des* des, const byte* iv); byte plain[] = { // initialize with message }; byte cipher[sizeof(plain)]; - if ( wc_Des_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) { + if ( wc_Des_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) { // error encrypting message } \endcode - + \sa wc_Des_SetKey \sa wc_Des_CbcDecrypt */ @@ -98,18 +98,18 @@ WOLFSSL_API int wc_Des_CbcEncrypt(Des* des, byte* out, /*! \ingroup 3DES - - \brief This function decrypts the input ciphertext, in, and stores the - resulting plaintext in the output buffer, out. It uses DES encryption + + \brief This function decrypts the input ciphertext, in, and stores the + resulting plaintext in the output buffer, out. It uses DES encryption with cipher block chaining (CBC) mode. - + \return 0 Returned upon successfully decrypting the given ciphertext - + \param des pointer to the Des structure to use for decryption \param out pointer to the buffer in which to store the decrypted plaintext \param in pointer to the input buffer containing the encrypted ciphertext \param sz length of the ciphertext to decrypt - + _Example_ \code Des dec; // Des structure used for decryption @@ -118,11 +118,11 @@ WOLFSSL_API int wc_Des_CbcEncrypt(Des* des, byte* out, byte cipher[] = { // initialize with ciphertext }; byte decoded[sizeof(cipher)]; - if ( wc_Des_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) { + if ( wc_Des_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) { // error decrypting message } \endcode - + \sa wc_Des_SetKey \sa wc_Des_CbcEncrypt */ @@ -131,13 +131,13 @@ WOLFSSL_API int wc_Des_CbcDecrypt(Des* des, byte* out, /*! \ingroup 3DES - - \brief This function encrypts the input message, in, and stores the result - in the output buffer, out. It uses Des encryption with Electronic + + \brief This function encrypts the input message, in, and stores the result + in the output buffer, out. It uses Des encryption with Electronic Codebook (ECB) mode. - + \return 0: Returned upon successfully encrypting the given plaintext. - + \param des pointer to the Des structure to use for encryption \param out pointer to the buffer in which to store the encrypted message \param in pointer to the input buffer containing the plaintext to encrypt @@ -151,11 +151,11 @@ WOLFSSL_API int wc_Des_CbcDecrypt(Des* des, byte* out, byte plain[] = { // initialize with message to encrypt }; byte cipher[sizeof(plain)]; - if ( wc_Des_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) { + if ( wc_Des_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) { // error encrypting message } \endcode - + \sa wc_Des_SetKe */ WOLFSSL_API int wc_Des_EcbEncrypt(Des* des, byte* out, @@ -163,15 +163,15 @@ WOLFSSL_API int wc_Des_EcbEncrypt(Des* des, byte* out, /*! \ingroup 3DES - - \brief This function encrypts the input message, in, and stores the - result in the output buffer, out. It uses Des3 encryption with - Electronic Codebook (ECB) mode. Warning: In nearly all use cases ECB - mode is considered to be less secure. Please avoid using ECB API’s + + \brief This function encrypts the input message, in, and stores the + result in the output buffer, out. It uses Des3 encryption with + Electronic Codebook (ECB) mode. Warning: In nearly all use cases ECB + mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible. - + \return 0 Returned upon successfully encrypting the given plaintext - + \param des3 pointer to the Des3 structure to use for encryption \param out pointer to the buffer in which to store the encrypted message \param in pointer to the input buffer containing the plaintext to encrypt @@ -185,11 +185,11 @@ WOLFSSL_API int wc_Des_EcbEncrypt(Des* des, byte* out, byte plain[] = { // initialize with message to encrypt }; byte cipher[sizeof(plain)]; - if ( wc_Des3_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) { + if ( wc_Des3_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) { // error encrypting message } /endcode - + \sa wc_Des3_SetKey */ WOLFSSL_API int wc_Des3_EcbEncrypt(Des3* des, byte* out, @@ -197,25 +197,25 @@ WOLFSSL_API int wc_Des3_EcbEncrypt(Des3* des, byte* out, /*! \ingroup 3DES - - \brief This function sets the key and initialization vector (iv) for - the Des3 structure given as argument. It also initializes and allocates - space for the buffers needed for encryption and decryption, if these - have not yet been initialized. Note: If no iv is provided (i.e. iv == + + \brief This function sets the key and initialization vector (iv) for + the Des3 structure given as argument. It also initializes and allocates + space for the buffers needed for encryption and decryption, if these + have not yet been initialized. Note: If no iv is provided (i.e. iv == NULL) the initialization vector defaults to an iv of 0. - - \return 0 On successfully setting the key and initialization vector + + \return 0 On successfully setting the key and initialization vector for the Des structure - + \param des3 pointer to the Des3 structure to initialize - \param key pointer to the buffer containing the 24 byte key with which + \param key pointer to the buffer containing the 24 byte key with which to initialize the Des3 structure - \param iv pointer to the buffer containing the 8 byte iv with which to - initialize the Des3 structure. If this is not provided, the iv defaults + \param iv pointer to the buffer containing the 8 byte iv with which to + initialize the Des3 structure. If this is not provided, the iv defaults to 0 - \param dir direction of encryption. Valid options are: DES_ENCRYPTION, + \param dir direction of encryption. Valid options are: DES_ENCRYPTION, and DES_DECRYPTION - + _Example_ \code Des3 enc; // Des3 structure used for encryption @@ -228,7 +228,7 @@ WOLFSSL_API int wc_Des3_EcbEncrypt(Des3* des, byte* out, // error initializing des structure } \endcode - + \sa wc_Des3_SetIV \sa wc_Des3_CbcEncrypt \sa wc_Des3_CbcDecrypt @@ -238,16 +238,16 @@ WOLFSSL_API int wc_Des3_SetKey(Des3* des, const byte* key, /*! \ingroup 3DES - - \brief This function sets the initialization vector (iv) for the Des3 - structure given as argument. When passed a NULL iv, it sets the + + \brief This function sets the initialization vector (iv) for the Des3 + structure given as argument. When passed a NULL iv, it sets the initialization vector to 0. - + \return none No returns. - + \param des pointer to the Des3 structure for which to set the iv - \param iv pointer to the buffer containing the 8 byte iv with which to - initialize the Des3 structure. If this is not provided, the iv + \param iv pointer to the buffer containing the 8 byte iv with which to + initialize the Des3 structure. If this is not provided, the iv defaults to 0 _Example_ @@ -260,25 +260,25 @@ WOLFSSL_API int wc_Des3_SetKey(Des3* des, const byte* key, wc_Des3_SetIV(&enc, iv); } \endcode - + \sa wc_Des3_SetKey */ WOLFSSL_API int wc_Des3_SetIV(Des3* des, const byte* iv); /*! \ingroup 3DES - - \brief This function encrypts the input message, in, and stores the - result in the output buffer, out. It uses Triple Des (3DES) encryption + + \brief This function encrypts the input message, in, and stores the + result in the output buffer, out. It uses Triple Des (3DES) encryption with cipher block chaining (CBC) mode. - + \return 0 Returned upon successfully encrypting the given input message - + \param des pointer to the Des3 structure to use for encryption \param out pointer to the buffer in which to store the encrypted ciphertext \param in pointer to the input buffer containing the message to encrypt \param sz length of the message to encrypt - + _Example_ \code Des3 enc; // Des3 structure used for encryption @@ -287,11 +287,11 @@ WOLFSSL_API int wc_Des3_SetIV(Des3* des, const byte* iv); byte plain[] = { // initialize with message }; byte cipher[sizeof(plain)]; - if ( wc_Des3_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) { + if ( wc_Des3_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) { // error encrypting message } \endcode - + \sa wc_Des3_SetKey \sa wc_Des3_CbcDecrypt */ @@ -300,18 +300,18 @@ WOLFSSL_API int wc_Des3_CbcEncrypt(Des3* des, byte* out, /*! \ingroup 3DES - - \brief This function decrypts the input ciphertext, in, and stores the - resulting plaintext in the output buffer, out. It uses Triple Des (3DES) + + \brief This function decrypts the input ciphertext, in, and stores the + resulting plaintext in the output buffer, out. It uses Triple Des (3DES) encryption with cipher block chaining (CBC) mode. - + \return 0 Returned upon successfully decrypting the given ciphertext - + \param des pointer to the Des3 structure to use for decryption \param out pointer to the buffer in which to store the decrypted plaintext \param in pointer to the input buffer containing the encrypted ciphertext \param sz length of the ciphertext to decrypt - + _Example_ \code Des3 dec; // Des structure used for decryption @@ -320,7 +320,7 @@ WOLFSSL_API int wc_Des3_CbcEncrypt(Des3* des, byte* out, byte cipher[] = { // initialize with ciphertext }; byte decoded[sizeof(cipher)]; - if ( wc_Des3_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) { + if ( wc_Des3_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) { // error decrypting message } \endcode diff --git a/doc/dox_comments/header_files/dh.h b/doc/dox_comments/header_files/dh.h index 8743c090c..d38d37af9 100644 --- a/doc/dox_comments/header_files/dh.h +++ b/doc/dox_comments/header_files/dh.h @@ -1,20 +1,20 @@ /*! \ingroup Diffie-Hellman - - \brief This function initializes a Diffie-Hellman key for use in + + \brief This function initializes a Diffie-Hellman key for use in negotiating a secure secret key with the Diffie-Hellman exchange protocol. - + \return none No returns. - - \param key pointer to the DhKey structure to initialize for use with + + \param key pointer to the DhKey structure to initialize for use with secure key exchanges - + _Example_ \code DhKey key; wc_InitDhKey(&key); // initialize DH key \endcode - + \sa wc_FreeDhKey \sa wc_DhGenerateKeyPair */ @@ -22,50 +22,50 @@ WOLFSSL_API int wc_InitDhKey(DhKey* key); /*! \ingroup Diffie-Hellman - - \brief This function frees a Diffie-Hellman key after it has been used to + + \brief This function frees a Diffie-Hellman key after it has been used to negotiate a secure secret key with the Diffie-Hellman exchange protocol. - + \return none No returns. - + \param key pointer to the DhKey structure to free - + _Example_ \code - DhKey key; + DhKey key; // initialize key, perform key exchange wc_FreeDhKey(&key); // free DH key to avoid memory leaks \endcode - + \sa wc_InitDhKey */ WOLFSSL_API void wc_FreeDhKey(DhKey* key); /*! \ingroup Diffie-Hellman - - \brief This function generates a public/private key pair based on the - Diffie-Hellman public parameters, storing the private key in priv and the - public key in pub. It takes an initialized Diffie-Hellman key and an + + \brief This function generates a public/private key pair based on the + Diffie-Hellman public parameters, storing the private key in priv and the + public key in pub. It takes an initialized Diffie-Hellman key and an initialized rng structure. - - \return BAD_FUNC_ARG Returned if there is an error parsing one of the + + \return BAD_FUNC_ARG Returned if there is an error parsing one of the inputs to this function - \return RNG_FAILURE_E Returned if there is an error generating a random - number using rng - \return MP_INIT_E May be returned if there is an error in the math library + \return RNG_FAILURE_E Returned if there is an error generating a random + number using rng + \return MP_INIT_E May be returned if there is an error in the math library while generating the public key - \return MP_READ_E May be returned if there is an error in the math library + \return MP_READ_E May be returned if there is an error in the math library while generating the public key - \return MP_EXPTMOD_E May be returned if there is an error in the math + \return MP_EXPTMOD_E May be returned if there is an error in the math library while generating the public key - \return MP_TO_E May be returned if there is an error in the math library + \return MP_TO_E May be returned if there is an error in the math library while generating the public key - - \param key pointer to the DhKey structure from which to generate + + \param key pointer to the DhKey structure from which to generate the key pair - \param rng pointer to an initialized random number generator (rng) with + \param rng pointer to an initialized random number generator (rng) with which to generate the keys \param priv pointer to a buffer in which to store the private key \param privSz will store the size of the private key written to priv @@ -86,7 +86,7 @@ WOLFSSL_API void wc_FreeDhKey(DhKey* key); wc_InitRng(&rng); // initialize rng ret = wc_DhGenerateKeyPair(&key, &rng, priv, &privSz, pub, &pubSz); \endcode - + \sa wc_InitDhKey \sa wc_DhSetKey \sa wc_DhKeyDecode @@ -96,32 +96,32 @@ WOLFSSL_API int wc_DhGenerateKeyPair(DhKey* key, WC_RNG* rng, byte* priv, /*! \ingroup Diffie-Hellman - - \brief This function generates an agreed upon secret key based on a local - private key and a received public key. If completed on both sides of an - exchange, this function generates an agreed upon secret key for symmetric - communication. On successfully generating a shared secret key, the size of + + \brief This function generates an agreed upon secret key based on a local + private key and a received public key. If completed on both sides of an + exchange, this function generates an agreed upon secret key for symmetric + communication. On successfully generating a shared secret key, the size of the secret key written will be stored in agreeSz. - + \return 0 Returned on successfully generating an agreed upon secret key - \return MP_INIT_E May be returned if there is an error while generating + \return MP_INIT_E May be returned if there is an error while generating the shared secret key - \return MP_READ_E May be returned if there is an error while generating + \return MP_READ_E May be returned if there is an error while generating the shared secret key - \return MP_EXPTMOD_E May be returned if there is an error while generating + \return MP_EXPTMOD_E May be returned if there is an error while generating the shared secret key - \return MP_TO_E May be returned if there is an error while generating the + \return MP_TO_E May be returned if there is an error while generating the shared secret key - + \param key pointer to the DhKey structure to use to compute the shared key \param agree pointer to the buffer in which to store the secret key - \param agreeSz will hold the size of the secret key after + \param agreeSz will hold the size of the secret key after successful generation \param priv pointer to the buffer containing the local secret key \param privSz size of the local secret key \param otherPub pointer to a buffer containing the received public key \param pubSz size of the received public key - + _Example_ \code DhKey key; @@ -133,13 +133,13 @@ WOLFSSL_API int wc_DhGenerateKeyPair(DhKey* key, WC_RNG* rng, byte* priv, // initialize key, set key prime and base // wc_DhGenerateKeyPair -- store private key in priv byte pub[] = { // initialized with the received public key }; - ret = wc_DhAgree(&key, agree, &agreeSz, priv, sizeof(priv), pub, + ret = wc_DhAgree(&key, agree, &agreeSz, priv, sizeof(priv), pub, sizeof(pub)); if ( ret != 0 ) { // error generating shared key } \endcode - + \sa wc_DhGenerateKeyPair */ WOLFSSL_API int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz, @@ -148,23 +148,23 @@ WOLFSSL_API int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz, /*! \ingroup Diffie-Hellman - - \brief This function decodes a Diffie-Hellman key from the given input - buffer containing the key in DER format. It stores the result in the + + \brief This function decodes a Diffie-Hellman key from the given input + buffer containing the key in DER format. It stores the result in the DhKey structure. - + \return 0 Returned on successfully decoding the input key - \return ASN_PARSE_E Returned if there is an error parsing the sequence + \return ASN_PARSE_E Returned if there is an error parsing the sequence of the input - \return ASN_DH_KEY_E Returned if there is an error reading the private + \return ASN_DH_KEY_E Returned if there is an error reading the private key parameters from the parsed input - \param input pointer to the buffer containing the DER formatted + \param input pointer to the buffer containing the DER formatted Diffie-Hellman key - \param inOutIdx pointer to an integer in which to store the index parsed + \param inOutIdx pointer to an integer in which to store the index parsed to while decoding the key \param key pointer to the DhKey structure to initialize with the input key - \param inSz length of the input buffer. Gives the max length that may + \param inSz length of the input buffer. Gives the max length that may be read _Example_ @@ -172,7 +172,7 @@ WOLFSSL_API int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz, DhKey key; word32 idx = 0; - byte keyBuff[1024]; + byte keyBuff[1024]; // initialize with DER formatted key wc_DhKeyInit(&key); ret = wc_DhKeyDecode(keyBuff, &idx, &key, sizeof(keyBuff)); @@ -181,7 +181,7 @@ WOLFSSL_API int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz, // error decoding key } \endcode - + \sa wc_DhSetKey */ WOLFSSL_API int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key, @@ -189,18 +189,18 @@ WOLFSSL_API int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key, /*! \ingroup Diffie-Hellman - - \brief This function sets the key for a DhKey structure using the input - private key parameters. Unlike wc_DhKeyDecode, this function does not - require that the input key be formatted in DER format, and instead simply + + \brief This function sets the key for a DhKey structure using the input + private key parameters. Unlike wc_DhKeyDecode, this function does not + require that the input key be formatted in DER format, and instead simply accepts the parsed input parameters p (prime) and g (base). - + \return 0 Returned on successfully setting the key - \return BAD_FUNC_ARG Returned if any of the input parameters + \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to NULL - \return MP_INIT_E Returned if there is an error initializing the key - parameters for storage - \return ASN_DH_KEY_E Returned if there is an error reading in the + \return MP_INIT_E Returned if there is an error initializing the key + parameters for storage + \return ASN_DH_KEY_E Returned if there is an error reading in the DH key parameters p and g \param key pointer to the DhKey structure on which to set the key @@ -208,7 +208,7 @@ WOLFSSL_API int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key, \param pSz length of the input prime \param g pointer to the buffer containing the base for use with the key \param gSz length of the input base - + _Example_ \code DhKey key; @@ -222,7 +222,7 @@ WOLFSSL_API int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key, // error setting key } \endcode - + \sa wc_DhKeyDecode */ WOLFSSL_API int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g, @@ -230,26 +230,26 @@ WOLFSSL_API int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g /*! \ingroup Diffie-Hellman - - \brief This function loads the Diffie-Hellman parameters, p (prime) + + \brief This function loads the Diffie-Hellman parameters, p (prime) and g (base) out of the given input buffer, DER formatted. - + \return 0 Returned on successfully extracting the DH parameters - \return ASN_PARSE_E Returned if an error occurs while parsing the DER + \return ASN_PARSE_E Returned if an error occurs while parsing the DER formatted DH certificate - \return BUFFER_E Returned if there is inadequate space in p or g to + \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 + \parma 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 - size in the p buffer. Will be overwritten with the number of bytes + \parma 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 - in the g buffer. Will be overwritten with the number of bytes written to + \parma 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 _Example_ @@ -265,7 +265,7 @@ WOLFSSL_API int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g // error parsing inputs } \endcode - + \sa wc_DhSetKey \sa wc_DhKeyDecode */ diff --git a/doc/dox_comments/header_files/dsa.h b/doc/dox_comments/header_files/dsa.h index 678f572d0..d5db20fc4 100644 --- a/doc/dox_comments/header_files/dsa.h +++ b/doc/dox_comments/header_files/dsa.h @@ -1,34 +1,34 @@ /*! \ingroup DSA - - \brief This function initializes a DsaKey object in order to use it for + + \brief This function initializes a DsaKey object in order to use it for authentication via the Digital Signature Algorithm (DSA). - + \return 0 Returned on success. \return BAD_FUNC_ARG Returned if a NULL key is passed in. - + \param key pointer to the DsaKey structure to initialize - + _Example_ \code DsaKey key; int ret; ret = wc_InitDsaKey(&key); // initialize DSA key \endcode - + \sa wc_FreeDsaKey */ WOLFSSL_API int wc_InitDsaKey(DsaKey* key); /*! \ingroup DSA - + \brief This function frees a DsaKey object after it has been used. - + \return none No returns. - + \param key pointer to the DsaKey structure to free - + _Example_ \code DsaKey key; @@ -36,48 +36,48 @@ WOLFSSL_API int wc_InitDsaKey(DsaKey* key); ... wc_FreeDsaKey(&key); // free DSA key \endcode - + \sa wc_FreeDsaKey */ WOLFSSL_API void wc_FreeDsaKey(DsaKey* key); /*! \ingroup DSA - - \brief This function signs the input digest and stores the result in the + + \brief This function signs the input digest and stores the result in the output buffer, out. - + \return 0 Returned on successfully signing the input digest - \return MP_INIT_E may be returned if there is an error in processing the + \return MP_INIT_E may be returned if there is an error in processing the DSA signature. - \return MP_READ_E may be returned if there is an error in processing the + \return MP_READ_E may be returned if there is an error in processing the DSA signature. - \return MP_CMP_E may be returned if there is an error in processing the + \return MP_CMP_E may be returned if there is an error in processing the DSA signature. - \return MP_INVMOD_E may be returned if there is an error in processing the + \return MP_INVMOD_E may be returned if there is an error in processing the DSA signature. - \return MP_EXPTMOD_E may be returned if there is an error in processing + \return MP_EXPTMOD_E may be returned if there is an error in processing the DSA signature. - \return MP_MOD_E may be returned if there is an error in processing the + \return MP_MOD_E may be returned if there is an error in processing the DSA signature. - \return MP_MUL_E may be returned if there is an error in processing the + \return MP_MUL_E may be returned if there is an error in processing the DSA signature. - \return MP_ADD_E may be returned if there is an error in processing the + \return MP_ADD_E may be returned if there is an error in processing the DSA signature. - \return MP_MULMOD_E may be returned if there is an error in processing + \return MP_MULMOD_E may be returned if there is an error in processing the DSA signature. - \return MP_TO_E may be returned if there is an error in processing the + \return MP_TO_E may be returned if there is an error in processing the DSA signature. - \return MP_MEM may be returned if there is an error in processing the + \return MP_MEM may be returned if there is an error in processing the DSA signature. - + \param digest pointer to the hash to sign \param out pointer to the buffer in which to store the signature - \param key pointer to the initialized DsaKey structure with which to + \param key pointer to the initialized DsaKey structure with which to generate the signature - \param rng pointer to an initialized RNG to use with the signature + \param rng pointer to an initialized RNG to use with the signature generation - + _Example_ \code DsaKey key; @@ -89,11 +89,11 @@ WOLFSSL_API void wc_FreeDsaKey(DsaKey* key); byte signature[40]; // signature will be 40 bytes (320 bits) ret = wc_DsaSign(hash, signature, &key, &rng); - if (ret != 0) { + if (ret != 0) { // error generating DSA signature } \endcode - + \sa wc_DsaVerify */ WOLFSSL_API int wc_DsaSign(const byte* digest, byte* out, @@ -101,45 +101,45 @@ WOLFSSL_API int wc_DsaSign(const byte* digest, byte* out, /*! \ingroup DSA - - \brief This function verifies the signature of a digest, given a private - key. It stores whether the key properly verifies in the answer parameter, - with 1 corresponding to a successful verification, and 0 corresponding to + + \brief This function verifies the signature of a digest, given a private + key. It stores whether the key properly verifies in the answer parameter, + with 1 corresponding to a successful verification, and 0 corresponding to failed verification. - - \return 0 Returned on successfully processing the verify request. Note: - this does not mean that the signature is verified, only that the function + + \return 0 Returned on successfully processing the verify request. Note: + this does not mean that the signature is verified, only that the function succeeded - \return MP_INIT_E may be returned if there is an error in processing the + \return MP_INIT_E may be returned if there is an error in processing the DSA signature. - \return MP_READ_E may be returned if there is an error in processing the + \return MP_READ_E may be returned if there is an error in processing the DSA signature. - \return MP_CMP_E may be returned if there is an error in processing the + \return MP_CMP_E may be returned if there is an error in processing the DSA signature. - \return MP_INVMOD_E may be returned if there is an error in processing + \return MP_INVMOD_E may be returned if there is an error in processing the DSA signature. - \return MP_EXPTMOD_E may be returned if there is an error in processing + \return MP_EXPTMOD_E may be returned if there is an error in processing the DSA signature. - \return MP_MOD_E may be returned if there is an error in processing the + \return MP_MOD_E may be returned if there is an error in processing the DSA signature. - \return MP_MUL_E may be returned if there is an error in processing the + \return MP_MUL_E may be returned if there is an error in processing the DSA signature. - \return MP_ADD_E may be returned if there is an error in processing the + \return MP_ADD_E may be returned if there is an error in processing the DSA signature. - \return MP_MULMOD_E may be returned if there is an error in processing + \return MP_MULMOD_E may be returned if there is an error in processing the DSA signature. - \return MP_TO_E may be returned if there is an error in processing the + \return MP_TO_E may be returned if there is an error in processing the DSA signature. - \return MP_MEM may be returned if there is an error in processing the + \return MP_MEM may be returned if there is an error in processing the DSA signature. - + \param digest pointer to the digest containing the subject of the signature \param sig pointer to the buffer containing the signature to verify - \param key pointer to the initialized DsaKey structure with which to + \param key pointer to the initialized DsaKey structure with which to verify the signature - \param answer pointer to an integer which will store whether the + \param answer pointer to an integer which will store whether the verification was successful - + _Example_ \code DsaKey key; @@ -150,13 +150,13 @@ WOLFSSL_API int wc_DsaSign(const byte* digest, byte* out, byte hash[] = { // initialize with hash digest }; byte signature[] = { // initialize with signature to verify }; ret = wc_DsaVerify(hash, signature, &key, &verified); - if (ret != 0) { + if (ret != 0) { // error processing verify request } else if (answer == 0) { // invalid signature } \endcode - + \sa wc_DsaSign */ WOLFSSL_API int wc_DsaVerify(const byte* digest, const byte* sig, @@ -164,21 +164,21 @@ WOLFSSL_API int wc_DsaVerify(const byte* digest, const byte* sig, /*! \ingroup DSA - - \brief This function decodes a DER formatted certificate buffer containing - a DSA public key, and stores the key in the given DsaKey structure. It + + \brief This function decodes a DER formatted certificate buffer containing + a DSA public key, and stores the key in the given DsaKey structure. It also sets the inOutIdx parameter according to the length of the input read. - - \return 0 Returned on successfully setting the public key for the DsaKey + + \return 0 Returned on successfully setting the public key for the DsaKey object - \return ASN_PARSE_E Returned if there is an error in the encoding while + \return ASN_PARSE_E Returned if there is an error in the encoding while reading the certificate buffer - \return ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly + \return ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly formatted - \param input pointer to the buffer containing the DER formatted DSA + \param input pointer to the buffer containing the DER formatted DSA public key - \param inOutIdx pointer to an integer in which to store the final index + \param inOutIdx pointer to an integer in which to store the final index of the certificate read \param key pointer to the DsaKey structure in which to store the public key \param inSz size of the input buffer @@ -191,11 +191,11 @@ WOLFSSL_API int wc_DsaVerify(const byte* digest, const byte* sig, wc_InitDsaKey(&key); byte derBuff[] = { // DSA public key}; ret = wc_DsaPublicKeyDecode(derBuff, &idx, &key, inSz); - if (ret != 0) { + if (ret != 0) { // error reading public key } \endcode - + \sa wc_InitDsaKey \sa wc_DsaPrivateKeyDecode */ @@ -204,23 +204,23 @@ WOLFSSL_API int wc_DsaPublicKeyDecode(const byte* input, word32* inOutIdx, /*! \ingroup DSA - - \brief This function decodes a DER formatted certificate buffer containing - a DSA private key, and stores the key in the given DsaKey structure. It + + \brief This function decodes a DER formatted certificate buffer containing + a DSA private key, and stores the key in the given DsaKey structure. It also sets the inOutIdx parameter according to the length of the input read. - - \return 0 Returned on successfully setting the private key for the DsaKey + + \return 0 Returned on successfully setting the private key for the DsaKey object - \return ASN_PARSE_E Returned if there is an error in the encoding while + \return ASN_PARSE_E Returned if there is an error in the encoding while reading the certificate buffer - \return ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly + \return ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly formatted - \param input pointer to the buffer containing the DER formatted DSA + \param input pointer to the buffer containing the DER formatted DSA private key - \param inOutIdx pointer to an integer in which to store the final index + \param inOutIdx pointer to an integer in which to store the final index of the certificate read - \param key pointer to the DsaKey structure in which to store the private + \param key pointer to the DsaKey structure in which to store the private key \param inSz size of the input buffer @@ -232,11 +232,11 @@ WOLFSSL_API int wc_DsaPublicKeyDecode(const byte* input, word32* inOutIdx, wc_InitDsaKey(&key); byte derBuff[] = { // DSA private key }; ret = wc_DsaPrivateKeyDecode(derBuff, &idx, &key, inSz); - if (ret != 0) { + if (ret != 0) { // error reading private key } \endcode - + \sa wc_InitDsaKey \sa wc_DsaPublicKeyDecode */ @@ -245,12 +245,12 @@ WOLFSSL_API int wc_DsaPrivateKeyDecode(const byte* input, word32* inOutIdx, /*! \ingroup DSA - - \brief Convert DsaKey key to DER format, write to output (inLen), + + \brief Convert DsaKey key to DER format, write to output (inLen), return bytes written. - + \return outLen Success, number of bytes written - \return BAD_FUNC_ARG key or output are null or key->type is not + \return BAD_FUNC_ARG key or output are null or key->type is not DSA_PRIVATE. \return MEMORY_E Error allocating memory. @@ -271,7 +271,7 @@ WOLFSSL_API int wc_DsaPrivateKeyDecode(const byte* input, word32* inOutIdx, wc_MakeDsaKey(&rng, &key); derSz = wc_DsaKeyToDer(&key, der, bufferSize); \endcode - + \sa wc_InitDsaKey \sa wc_FreeDsaKey \sa wc_MakeDsaKey @@ -280,11 +280,11 @@ WOLFSSL_API int wc_DsaKeyToDer(DsaKey* key, byte* output, word32 inLen); /*! \ingroup DSA - + \brief Create a DSA key. - + \return MP_OKAY Success - \return BAD_FUNC_ARG Either rng or dsa is null. + \return BAD_FUNC_ARG Either rng or dsa is null. \return MEMORY_E Couldn't allocate memory for buffer. \return MP_INIT_E Error initializing mp_int @@ -302,7 +302,7 @@ WOLFSSL_API int wc_DsaKeyToDer(DsaKey* key, byte* output, word32 inLen); // Error creating key } \endcode - + \sa wc_InitDsaKey \sa wc_FreeDsaKey \sa wc_DsaSign @@ -311,10 +311,10 @@ WOLFSSL_API int wc_MakeDsaKey(WC_RNG *rng, DsaKey *dsa); /*! \ingroup DSA - - \brief FIPS 186-4 defines valid for modulus_size values as + + \brief FIPS 186-4 defines valid for modulus_size values as (1024, 160) (2048, 256) (3072, 256) - + \return 0 Success \return BAD_FUNC_ARG rng or dsa is null or modulus_size is invalid. \return MEMORY_E Error attempting to allocate memory. @@ -334,7 +334,7 @@ WOLFSSL_API int wc_MakeDsaKey(WC_RNG *rng, DsaKey *dsa); // Handle error } \endcode - + \sa wc_MakeDsaKey \sa wc_DsaKeyToDer \sa wc_InitDsaKey diff --git a/doc/dox_comments/header_files/ecc.h b/doc/dox_comments/header_files/ecc.h index dc1bcd993..0dec2a3ac 100644 --- a/doc/dox_comments/header_files/ecc.h +++ b/doc/dox_comments/header_files/ecc.h @@ -1,38 +1,38 @@ /*! \ingroup ECC - + \brief This function generates a new ecc_key and stores it in key. - + \return 0 Returned on success. \return ECC_BAD_ARG_E Returned if rng or key evaluate to NULL - \return BAD_FUNC_ARG Returned if the specified key size is not in the + \return BAD_FUNC_ARG Returned if the specified key size is not in the correct range of supported keys - \return MEMORY_E Returned if there is an error allocating memory while + \return MEMORY_E Returned if there is an error allocating memory while computing the ecc key - \return MP_INIT_E may be returned if there is an error while computing + \return MP_INIT_E may be returned if there is an error while computing the ecc key - \return MP_READ_E may be returned if there is an error while computing + \return MP_READ_E may be returned if there is an error while computing the ecc key - \return MP_CMP_E may be returned if there is an error while computing the + \return MP_CMP_E may be returned if there is an error while computing the ecc key - \return MP_INVMOD_E may be returned if there is an error while computing + \return MP_INVMOD_E may be returned if there is an error while computing the ecc key - \return MP_EXPTMOD_E may be returned if there is an error while computing + \return MP_EXPTMOD_E may be returned if there is an error while computing the ecc key - \return MP_MOD_E may be returned if there is an error while computing the + \return MP_MOD_E may be returned if there is an error while computing the ecc key - \return MP_MUL_E may be returned if there is an error while computing the + \return MP_MUL_E may be returned if there is an error while computing the ecc key - \return MP_ADD_E may be returned if there is an error while computing the + \return MP_ADD_E may be returned if there is an error while computing the ecc key - \return MP_MULMOD_E may be returned if there is an error while computing + \return MP_MULMOD_E may be returned if there is an error while computing the ecc key - \return MP_TO_E may be returned if there is an error while computing the + \return MP_TO_E may be returned if there is an error while computing the ecc key - \return MP_MEM may be returned if there is an error while computing the + \return MP_MEM may be returned if there is an error while computing the ecc key - - \param rng pointer to an initialized RNG object with which to generate + + \param rng pointer to an initialized RNG object with which to generate the key \param keysize desired length for the ecc_key \param key pointer to the ecc_key for which to generate a key @@ -45,7 +45,7 @@ wc_InitRng(&rng); wc_ecc_make_key(&rng, 32, &key); // initialize 32 byte ecc key \endcode - + \sa wc_ecc_init \sa wc_ecc_shared_secret */ @@ -54,15 +54,15 @@ int wc_ecc_make_key(WC_RNG* rng, int keysize, ecc_key* key); /*! \ingroup ECC - + \brief Perform sanity checks on ecc key validity. - + \return MP_OKAY Success, key is OK. \return BAD_FUNC_ARG Returns if key is NULL. \return ECC_INF_E Returns if wc_ecc_point_is_at_infinity returns 1. - + \param key Pointer to key to check. - + _Example_ \code ecc_key key; @@ -82,7 +82,7 @@ int wc_ecc_make_key(WC_RNG* rng, int keysize, ecc_key* key); // key check failed } \endcode - + \sa wc_ecc_point_is_at_infinity */ WOLFSSL_API @@ -90,52 +90,52 @@ int wc_ecc_check_key(ecc_key* key); /*! \ingroup ECC - - \brief This function generates a new secret key using a local private key - and a received public key. It stores this shared secret key in the buffer - out and updates outlen to hold the number of bytes written to the output + + \brief This function generates a new secret key using a local private key + and a received public key. It stores this shared secret key in the buffer + out and updates outlen to hold the number of bytes written to the output buffer. - + \return 0 Returned upon successfully generating a shared secret key - \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to + \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to NULL - \return ECC_BAD_ARG_E Returned if the type of the private key given as - argument, private_key, is not ECC_PRIVATEKEY, or if the public and private + \return ECC_BAD_ARG_E Returned if the type of the private key given as + argument, private_key, is not ECC_PRIVATEKEY, or if the public and private key types (given by ecc->dp) are not equivalent \return MEMORY_E Returned if there is an error generating a new ecc point - \return BUFFER_E Returned if the generated shared secret key is too long + \return BUFFER_E Returned if the generated shared secret key is too long to store in the provided buffer - \return MP_INIT_E may be returned if there is an error while computing the + \return MP_INIT_E may be returned if there is an error while computing the shared key - \return MP_READ_E may be returned if there is an error while computing the + \return MP_READ_E may be returned if there is an error while computing the shared key - \return MP_CMP_E may be returned if there is an error while computing the + \return MP_CMP_E may be returned if there is an error while computing the shared key - \return MP_INVMOD_E may be returned if there is an error while computing + \return MP_INVMOD_E may be returned if there is an error while computing the shared key - \return MP_EXPTMOD_E may be returned if there is an error while computing + \return MP_EXPTMOD_E may be returned if there is an error while computing the shared key - \return MP_MOD_E may be returned if there is an error while computing the + \return MP_MOD_E may be returned if there is an error while computing the shared key - \return MP_MUL_E may be returned if there is an error while computing the + \return MP_MUL_E may be returned if there is an error while computing the shared key - \return MP_ADD_E may be returned if there is an error while computing the + \return MP_ADD_E may be returned if there is an error while computing the shared key - \return MP_MULMOD_E may be returned if there is an error while computing + \return MP_MULMOD_E may be returned if there is an error while computing the shared key - \return MP_TO_E may be returned if there is an error while computing the + \return MP_TO_E may be returned if there is an error while computing the shared key - \return MP_MEM may be returned if there is an error while computing the + \return MP_MEM may be returned if there is an error while computing the shared key - - \param private_key pointer to the ecc_key structure containing the local + + \param private_key pointer to the ecc_key structure containing the local private key - \param public_key pointer to the ecc_key structure containing the received + \param public_key pointer to the ecc_key structure containing the received public key - \param out pointer to an output buffer in which to store the generated + \param out pointer to an output buffer in which to store the generated shared secret key - \param outlen pointer to the word32 object containing the length of the - output buffer. Will be overwritten with the length written to the output + \param outlen pointer to the word32 object containing the length of the + output buffer. Will be overwritten with the length written to the output buffer upon successfully generating a shared secret key _Example_ @@ -150,13 +150,13 @@ int wc_ecc_check_key(ecc_key* key); wc_ecc_init(&priv); // initialize key wc_ecc_make_key(&rng, 32, &priv); // make public/private key pair // receive public key, and initialise into pub - ret = wc_ecc_shared_secret(&priv, &pub, secret, &secretSz); + ret = wc_ecc_shared_secret(&priv, &pub, secret, &secretSz); // generate secret key if ( ret != 0 ) { // error generating shared secret key } \endcode - + \sa wc_ecc_init \sa wc_ecc_make_key */ @@ -166,23 +166,23 @@ int wc_ecc_shared_secret(ecc_key* private_key, ecc_key* public_key, byte* out, /*! \ingroup ECC - + \brief Create an ECC shared secret between private key and public point. - + \return MP_OKAY Indicates success. \return BAD_FUNC_ARG Error returned when any arguments are null. - \return ECC_BAD_ARG_E Error returned if private_key->type is not + \return ECC_BAD_ARG_E Error returned if private_key->type is not ECC_PRIVATEKEY or private_key->idx fails to validate. \return BUFFER_E Error when outlen is too small. \return MEMORY_E Error to create a new point. \return MP_VAL possible when an initialization failure occurs. \return MP_MEM possible when an initialization failure occurs. - + \param private_key The private ECC key. \param point The point to use (public key). - \param out Output destination of the shared secret. Conforms to + \param out Output destination of the shared secret. Conforms to EC-DH from ANSI X9.63. - \param outlen Input the max size and output the resulting size of + \param outlen Input the max size and output the resulting size of the shared secret. _Example_ @@ -195,7 +195,7 @@ int wc_ecc_shared_secret(ecc_key* private_key, ecc_key* public_key, byte* out, point = wc_ecc_new_point(); - result = wc_ecc_shared_secret_ex(&key, point, + result = wc_ecc_shared_secret_ex(&key, point, &shared_secret, &secret_size); if (result != MP_OKAY) @@ -203,7 +203,7 @@ int wc_ecc_shared_secret(ecc_key* private_key, ecc_key* public_key, byte* out, // Handle error } \endcode - + \sa wc_ecc_verify_hash_ex */ WOLFSSL_API @@ -212,49 +212,49 @@ int wc_ecc_shared_secret_ex(ecc_key* private_key, ecc_point* point, /*! \ingroup ECC - - \brief This function signs a message digest using an ecc_key object to + + \brief This function signs a message digest using an ecc_key object to guarantee authenticity. - - \return 0 Returned upon successfully generating a signature for the + + \return 0 Returned upon successfully generating a signature for the message digest - \return BAD_FUNC_ARG Returned if 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 - \return ECC_BAD_ARG_E Returned if the input key is not a private key, or + \return ECC_BAD_ARG_E Returned if the input key is not a private key, or if the ECC OID is invalid - \return RNG_FAILURE_E Returned if the rng cannot successfully generate a + \return RNG_FAILURE_E Returned if the rng cannot successfully generate a satisfactory key - \return MP_INIT_E may be returned if there is an error while computing + \return MP_INIT_E may be returned if there is an error while computing the message signature - \return MP_READ_E may be returned if there is an error while computing + \return MP_READ_E may be returned if there is an error while computing the message signature - \return MP_CMP_E may be returned if there is an error while computing the + \return MP_CMP_E may be returned if there is an error while computing the message signature - \return MP_INVMOD_E may be returned if there is an error while computing + \return MP_INVMOD_E may be returned if there is an error while computing the message signature - \return MP_EXPTMOD_E may be returned if there is an error while computing + \return MP_EXPTMOD_E may be returned if there is an error while computing the message signature - \return MP_MOD_E may be returned if there is an error while computing the + \return MP_MOD_E may be returned if there is an error while computing the message signature - \return MP_MUL_E may be returned if there is an error while computing the + \return MP_MUL_E may be returned if there is an error while computing the message signature - \return MP_ADD_E may be returned if there is an error while computing the + \return MP_ADD_E may be returned if there is an error while computing the message signature - \return MP_MULMOD_E may be returned if there is an error while computing + \return MP_MULMOD_E may be returned if there is an error while computing the message signature - \return MP_TO_E may be returned if there is an error while computing the + \return MP_TO_E may be returned if there is an error while computing the message signature - \return MP_MEM may be returned if there is an error while computing the + \return MP_MEM may be returned if there is an error while computing the message signature \param in pointer to the buffer containing the message hash to sign \param inlen length of the message hash to sign \param out buffer in which to store the generated signature - \param outlen max length of the output buffer. Will store the bytes + \param outlen max length of the output buffer. Will store the bytes written to out upon successfully generating a message signature - \param key pointer to a private ECC key with which to generate the + \param key pointer to a private ECC key with which to generate the signature - + _Example_ \code ecc_key key; @@ -272,7 +272,7 @@ int wc_ecc_shared_secret_ex(ecc_key* private_key, ecc_point* point, // error generating message signature } \endcode - + \sa wc_ecc_verify_hash */ WOLFSSL_API @@ -281,39 +281,39 @@ int wc_ecc_sign_hash(const byte* in, word32 inlen, byte* out, word32 *outlen, /*! \ingroup ECC - + \brief Sign a message digest. - - \return MP_OKAY Returned upon successfully generating a signature for the + + \return MP_OKAY Returned upon successfully generating a signature for the message digest - \return ECC_BAD_ARG_E Returned if the input key is not a private key, or - if the ECC IDX is invalid, or if any of the input parameters evaluate to + \return ECC_BAD_ARG_E Returned if the input key is not a private key, or + if the ECC IDX is invalid, or if any of the input parameters evaluate to NULL, or if the output buffer is too small to store the generated signature - \return RNG_FAILURE_E Returned if the rng cannot successfully generate a + \return RNG_FAILURE_E Returned if the rng cannot successfully generate a satisfactory key - \return MP_INIT_E may be returned if there is an error while computing the + \return MP_INIT_E may be returned if there is an error while computing the message signature - \return MP_READ_E may be returned if there is an error while computing the + \return MP_READ_E may be returned if there is an error while computing the message signature - \return MP_CMP_E may be returned if there is an error while computing the + \return MP_CMP_E may be returned if there is an error while computing the message signature - \return MP_INVMOD_E may be returned if there is an error while computing + \return MP_INVMOD_E may be returned if there is an error while computing the message signature - \return MP_EXPTMOD_E may be returned if there is an error while computing + \return MP_EXPTMOD_E may be returned if there is an error while computing the message signature - \return MP_MOD_E may be returned if there is an error while computing the + \return MP_MOD_E may be returned if there is an error while computing the message signature - \return MP_MUL_E may be returned if there is an error while computing the + \return MP_MUL_E may be returned if there is an error while computing the message signature - \return MP_ADD_E may be returned if there is an error while computing the + \return MP_ADD_E may be returned if there is an error while computing the message signature - \return MP_MULMOD_E may be returned if there is an error while computing + \return MP_MULMOD_E may be returned if there is an error while computing the message signature - \return MP_TO_E may be returned if there is an error while computing the + \return MP_TO_E may be returned if there is an error while computing the message signature - \return MP_MEM may be returned if there is an error while computing the + \return MP_MEM may be returned if there is an error while computing the message signature - + \param in The message digest to sign. \param inlen The length of the digest. \param rng Pointer to WC_RNG struct. @@ -341,7 +341,7 @@ int wc_ecc_sign_hash(const byte* in, word32 inlen, byte* out, word32 *outlen, // error generating message signature } \endcode - + \sa wc_ecc_verify_hash_ex */ WOLFSSL_API @@ -350,45 +350,45 @@ int wc_ecc_sign_hash_ex(const byte* in, word32 inlen, WC_RNG* rng, /*! \ingroup ECC - - \brief This function verifies the ECC signature of a hash to ensure - authenticity. It returns the answer through stat, with 1 corresponding + + \brief This function verifies the ECC signature of a hash to ensure + authenticity. It returns the answer through stat, 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. + + \return 0 Returned upon successfully performing the signature + verification. Note: This does not mean that the signature is verified. The authenticity information is stored instead in stat \return BAD_FUNC_ARG Returned any of the input parameters evaluate to NULL \return MEMORY_E Returned if there is an error allocating memory - \return MP_INIT_E may be returned if there is an error while computing + \return MP_INIT_E may be returned if there is an error while computing the message signature - \return MP_READ_E may be returned if there is an error while computing + \return MP_READ_E may be returned if there is an error while computing the message signature - \return MP_CMP_E may be returned if there is an error while computing + \return MP_CMP_E may be returned if there is an error while computing the message signature - \return MP_INVMOD_E may be returned if there is an error while computing + \return MP_INVMOD_E may be returned if there is an error while computing the message signature - \return MP_EXPTMOD_E may be returned if there is an error while + \return MP_EXPTMOD_E may be returned if there is an error while computing the message signature - \return MP_MOD_E may be returned if there is an error while computing + \return MP_MOD_E may be returned if there is an error while computing the message signature - \return MP_MUL_E may be returned if there is an error while computing + \return MP_MUL_E may be returned if there is an error while computing the message signature - \return MP_ADD_E may be returned if there is an error while computing + \return MP_ADD_E may be returned if there is an error while computing the message signature - \return MP_MULMOD_E may be returned if there is an error while computing + \return MP_MULMOD_E may be returned if there is an error while computing the message signature - \return MP_TO_E may be returned if there is an error while computing the + \return MP_TO_E may be returned if there is an error while computing the message signature - \return MP_MEM may be returned if there is an error while computing the + \return MP_MEM may be returned if there is an error while computing the message signature \param sig pointer to the buffer containing the signature to verify \param siglen length of the signature to verify - \param hash pointer to the buffer containing the hash of the message + \param hash pointer to the buffer containing the hash of the message verified \param hashlen length of the hash of the message verified - \param stat pointer to the result of the verification. 1 indicates the + \param stat pointer to the result of the verification. 1 indicates the message was successfully verified \param key pointer to a public ECC key with which to verify the signature @@ -400,7 +400,7 @@ int wc_ecc_sign_hash_ex(const byte* in, word32 inlen, WC_RNG* rng, byte sig[1024] { initialize with received signature }; byte digest[] = { initialize with message hash }; // initialize key with received public key - ret = wc_ecc_verify_hash(sig, sizeof(sig), digest,sizeof(digest), + ret = wc_ecc_verify_hash(sig, sizeof(sig), digest,sizeof(digest), &verified, &key); if ( ret != 0 ) { // error performing verification @@ -408,7 +408,7 @@ int wc_ecc_sign_hash_ex(const byte* in, word32 inlen, WC_RNG* rng, // the signature is invalid } \endcode - + \sa wc_ecc_sign_hash \sa wc_ecc_verify_hash_ex */ @@ -418,13 +418,13 @@ int wc_ecc_verify_hash(const byte* sig, word32 siglen, const byte* hash, /*! \ingroup ECC - - \brief Verify an ECC signature. Result is written to stat. + + \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. \return MP_OKAY If successful (even if the signature is not valid) - \return ECC_BAD_ARG_E Returns if arguments are null or if + \return ECC_BAD_ARG_E Returns if arguments are null or if key-idx is invalid. \return MEMORY_E Error allocating ints or points. @@ -448,7 +448,7 @@ Note: Do not use the return value to test for valid. Only use stat. // Check stat } \endcode - + \sa wc_ecc_verify_hash */ WOLFSSL_API @@ -457,21 +457,21 @@ int wc_ecc_verify_hash_ex(mp_int *r, mp_int *s, const byte* hash, /*! \ingroup ECC - - \brief This function initializes an ecc_key object for future + + \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(&key); \endcode - + \sa wc_ecc_make_key \sa wc_ecc_free */ @@ -480,20 +480,20 @@ int wc_ecc_init(ecc_key* key); /*! \ingroup ECC - + \brief This function frees an ecc_key object 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_free(&key); \endcode - + \sa wc_ecc_init */ WOLFSSL_API @@ -501,15 +501,15 @@ int wc_ecc_free(ecc_key* key); /*! \ingroup ECC - - \brief This function frees the fixed-point cache, which can be used - with ecc to speed up computation times. To use this functionality, + + \brief This function frees the fixed-point cache, which can be used + with ecc to speed up computation times. To use this functionality, FP_ECC (fixed-point ecc), should be defined. - + \return none No returns. - + \param none No parameters. - + _Example_ \code ecc_key key; @@ -518,7 +518,7 @@ int wc_ecc_free(ecc_key* key); wc_ecc_fp_free(); \endcode - + \sa wc_ecc_free */ WOLFSSL_API @@ -526,14 +526,14 @@ void wc_ecc_fp_free(void); /*! \ingroup ECC - + \brief Checks if an ECC idx is valid. - + \return 1 Return if valid. \return 0 Return if not valid. - + \param n The idx number to check. - + _Example_ \code ecc_key key; @@ -552,7 +552,7 @@ void wc_ecc_fp_free(void); // idx is not valid } \endcode - + \sa none */ WOLFSSL_API @@ -560,14 +560,14 @@ int wc_ecc_is_valid_idx(int n); /*! \ingroup ECC - + \brief Allocate a new ECC point. - + \return p A newly allocated point. \return NULL Returns NULL on error. - + \param none No parameters. - + _Example_ \code ecc_point* point; @@ -578,7 +578,7 @@ int wc_ecc_is_valid_idx(int n); } // Do stuff with point \endcode - + \sa wc_ecc_del_point \sa wc_ecc_cmp_point \sa wc_ecc_copy_point @@ -588,13 +588,13 @@ ecc_point* wc_ecc_new_point(void); /*! \ingroup ECC - + \brief Free an ECC point from memory. - + \return none No returns. - + \param p The point to free. - + _Example_ \code ecc_point* point; @@ -606,7 +606,7 @@ ecc_point* wc_ecc_new_point(void); // Do stuff with point wc_ecc_del_point(point); \endcode - + \sa wc_ecc_new_point \sa wc_ecc_cmp_point \sa wc_ecc_copy_point @@ -616,16 +616,16 @@ void wc_ecc_del_point(ecc_point* p); /*! \ingroup ECC - + \brief Copy the value of one point to another one. - + \return ECC_BAD_ARG_E Error thrown when p or r is null. \return MP_OKAY Point copied successfully \return ret Error from internal functions. Can be... - + \param p The point to copy. \param r The created point. - + _Example_ \code ecc_point* point; @@ -639,7 +639,7 @@ void wc_ecc_del_point(ecc_point* p); // Handle error } \endcode - + \sa wc_ecc_new_point \sa wc_ecc_cmp_point \sa wc_ecc_del_point @@ -649,17 +649,17 @@ int wc_ecc_copy_point(ecc_point* p, ecc_point *r); /*! \ingroup ECC - + \brief Compare the value of a point with another one. - + \return BAD_FUNC_ARG One or both arguments are NULL. \return MP_EQ The points are equal. - \return ret Either MP_LT or MP_GT and signifies that the + \return ret Either MP_LT or MP_GT and signifies that the points are not equal. - + \param a First point to compare. \param b Second point to compare. - + _Example_ \code ecc_point* point; @@ -682,7 +682,7 @@ int wc_ecc_copy_point(ecc_point* p, ecc_point *r); // Points are not equal } \endcode - + \sa wc_ecc_new_point \sa wc_ecc_del_point \sa wc_ecc_copy_point @@ -692,16 +692,16 @@ int wc_ecc_cmp_point(ecc_point* a, ecc_point *b); /*! \ingroup ECC - - \brief Checks if a point is at infinity. Returns 1 if point is + + \brief Checks if a point is at infinity. Returns 1 if point is at infinity, 0 if not, < 0 on error \return 1 p is at infinity. \return 0 p is not at infinity. \return <0 Error. - + \param p The point to check. - + _Example_ \code ecc_point* point; @@ -722,7 +722,7 @@ int wc_ecc_cmp_point(ecc_point* a, ecc_point *b); // Point is at infinity } \endcode - + \sa wc_ecc_new_point \sa wc_ecc_del_point \sa wc_ecc_cmp_point @@ -733,20 +733,20 @@ int wc_ecc_point_is_at_infinity(ecc_point *p); /*! \ingroup ECC - + \brief Perform ECC Fixed Point multiplication. - + \return MP_OKAY Returns on successful operation. - \return MP_INIT_E Returned if there is an error initializing an integer + \return MP_INIT_E Returned if there is an error initializing an integer for use with the multiple precision integer (mp_int) library. - + \param k The multiplicand. \param G Base point to multiply. \param R Destination of product. \param modulus The modulus for the curve. - \param map If non-zero maps the point back to affine coordinates, + \param map If non-zero maps the point back to affine coordinates, otherwise it's left in jacobian-montgomery form. - + _Example_ \code ecc_point* base; @@ -759,7 +759,7 @@ int wc_ecc_point_is_at_infinity(ecc_point *p); mp_int modulus; int map; \endcode - + \sa none */ WOLFSSL_API @@ -768,49 +768,49 @@ int wc_ecc_mulmod(mp_int* k, ecc_point *G, ecc_point *R, /*! \ingroup ECC - - \brief This function exports the ECC key from the ecc_key structure, - storing the result in out. The key will be stored in ANSI X9.63 format. + + \brief This function exports the ECC key from the ecc_key structure, + storing the result in out. The key will be stored in ANSI X9.63 format. It stores the bytes written to the output buffer in outLen. - + \return 0 Returned on successfully exporting the ecc_key - \return LENGTH_ONLY_E Returned if the output buffer evaluates to NULL, - but the other two input parameters are valid. Indicates that the function + \return LENGTH_ONLY_E Returned if the output buffer evaluates to NULL, + but the other two input parameters are valid. Indicates that the function is only returning the length required to store the key - \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL, + \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL, or the key is unsupported (has an invalid index) - \return BUFFER_E Returned if the output buffer is too small to store the - ecc key. If the output buffer is too small, the size needed will be + \return BUFFER_E Returned if the output buffer is too small to store the + ecc key. If the output buffer is too small, the size needed will be returned in outLen - \return MEMORY_E Returned if there is an error allocating memory with + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return MP_INIT_E may be returned if there is an error processing the + \return MP_INIT_E may be returned if there is an error processing the ecc_key - \return MP_READ_E may be returned if there is an error processing the + \return MP_READ_E may be returned if there is an error processing the ecc_key - \return MP_CMP_E may be returned if there is an error processing the + \return MP_CMP_E may be returned if there is an error processing the ecc_key - \return MP_INVMOD_E may be returned if there is an error processing the + \return MP_INVMOD_E may be returned if there is an error processing the ecc_key - \return MP_EXPTMOD_E may be returned if there is an error processing the + \return MP_EXPTMOD_E may be returned if there is an error processing the ecc_key - \return MP_MOD_E may be returned if there is an error processing the + \return MP_MOD_E may be returned if there is an error processing the ecc_key - \return MP_MUL_E may be returned if there is an error processing the + \return MP_MUL_E may be returned if there is an error processing the ecc_key - \return MP_ADD_E may be returned if there is an error processing the + \return MP_ADD_E may be returned if there is an error processing the ecc_key - \return MP_MULMOD_E may be returned if there is an error processing the + \return MP_MULMOD_E may be returned if there is an error processing the ecc_key \return MP_TO_E may be returned if there is an error processing the ecc_key \return MP_MEM may be returned if there is an error processing the ecc_key - + \param key pointer to the ecc_key object to export - \param out pointer to the buffer in which to store the ANSI X9.63 + \param out pointer to the buffer in which to store the ANSI X9.63 formatted key - \param outLen size of the output buffer. On successfully storing the + \param outLen size of the output buffer. On successfully storing the key, will hold the bytes written to the output buffer - + _Example_ \code int ret; @@ -824,7 +824,7 @@ int wc_ecc_mulmod(mp_int* k, ecc_point *G, ecc_point *R, // error exporting key } \endcode - + \sa wc_ecc_export_x963_ex \sa wc_ecc_import_x963 */ @@ -833,56 +833,56 @@ int wc_ecc_export_x963(ecc_key*, byte* out, word32* outLen); /*! \ingroup ECC - - \brief This function exports the ECC key from the ecc_key structure, - storing the result in out. The key will be stored in ANSI X9.63 format. - It stores the bytes written to the output buffer in outLen. This function - allows the additional option of compressing the certificate through the - compressed parameter. When this parameter is true, the key will be stored + + \brief This function exports the ECC key from the ecc_key structure, + storing the result in out. The key will be stored in ANSI X9.63 format. + It stores the bytes written to the output buffer in outLen. This function + allows the additional option of compressing the certificate through the + compressed parameter. When this parameter is true, the key will be stored in ANSI X9.63 compressed format. - + \return 0 Returned on successfully exporting the ecc_key - \return NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at + \return NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at compile time, but the key was requested in compressed format - \return LENGTH_ONLY_E Returned if the output buffer evaluates to NULL, but - the other two input parameters are valid. Indicates that the function is + \return LENGTH_ONLY_E Returned if the output buffer evaluates to NULL, but + the other two input parameters are valid. Indicates that the function is only returning the length required to store the key - \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL, or + \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL, or the key is unsupported (has an invalid index) - \return BUFFER_E Returned if the output buffer is too small to store the - ecc key. If the output buffer is too small, the size needed will be + \return BUFFER_E Returned if the output buffer is too small to store the + ecc key. If the output buffer is too small, the size needed will be returned in outLen - \return MEMORY_E Returned if there is an error allocating memory with + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC - \return MP_INIT_E may be returned if there is an error processing the + \return MP_INIT_E may be returned if there is an error processing the ecc_key - \return MP_READ_E may be returned if there is an error processing the + \return MP_READ_E may be returned if there is an error processing the ecc_key - \return MP_CMP_E may be returned if there is an error processing the + \return MP_CMP_E may be returned if there is an error processing the ecc_key - \return MP_INVMOD_E may be returned if there is an error processing the + \return MP_INVMOD_E may be returned if there is an error processing the ecc_key - \return MP_EXPTMOD_E may be returned if there is an error processing + \return MP_EXPTMOD_E may be returned if there is an error processing the ecc_key - \return MP_MOD_E may be returned if there is an error processing the + \return MP_MOD_E may be returned if there is an error processing the ecc_key - \return MP_MUL_E may be returned if there is an error processing the + \return MP_MUL_E may be returned if there is an error processing the ecc_key - \return MP_ADD_E may be returned if there is an error processing the + \return MP_ADD_E may be returned if there is an error processing the ecc_key - \return MP_MULMOD_E may be returned if there is an error processing + \return MP_MULMOD_E may be returned if there is an error processing the ecc_key \return MP_TO_E may be returned if there is an error processing the ecc_key \return MP_MEM may be returned if there is an error processing the ecc_key \param key pointer to the ecc_key object to export - \param out pointer to the buffer in which to store the ANSI X9.63 + \param out pointer to the buffer in which to store the ANSI X9.63 formatted key - \param outLen size of the output buffer. On successfully storing the + \param outLen size of the output buffer. On successfully storing the key, will hold the bytes written to the output buffer - \param compressed indicator of whether to store the key in compressed + \param compressed indicator of whether to store the key in compressed format. 1==compressed, 0==uncompressed - + _Example_ \code int ret; @@ -904,47 +904,47 @@ int wc_ecc_export_x963_ex(ecc_key*, byte* out, word32* outLen, int compressed); /*! \ingroup ECC - - \brief This function imports a public ECC key from a buffer containing the - key stored in ANSI X9.63 format. This function will handle both compressed - and uncompressed keys, as long as compressed keys are enabled at compile + + \brief This function imports a public ECC key from a buffer containing the + key stored in ANSI X9.63 format. This function will handle both compressed + and uncompressed keys, as long as compressed keys are enabled at compile time through the HAVE_COMP_KEY option. - + \return 0 Returned on successfully importing the ecc_key - \return NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at + \return 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 + \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) \return MEMORY_E Returned if there is an error allocating memory - \return ASN_PARSE_E Returned if there is an error parsing the ECC key; + \return ASN_PARSE_E Returned if there is an error parsing the ECC key; may indicate that the ECC key is not stored in valid ANSI X9.63 format - \return IS_POINT_E Returned if the public key exported is not a point + \return IS_POINT_E Returned if the public key exported is not a point on the ECC curve - \return MP_INIT_E may be returned if there is an error processing the + \return MP_INIT_E may be returned if there is an error processing the ecc_key - \return MP_READ_E may be returned if there is an error processing the + \return MP_READ_E may be returned if there is an error processing the ecc_key - \return MP_CMP_E may be returned if there is an error processing the + \return MP_CMP_E may be returned if there is an error processing the ecc_key - \return MP_INVMOD_E may be returned if there is an error processing the + \return MP_INVMOD_E may be returned if there is an error processing the ecc_key - \return MP_EXPTMOD_E may be returned if there is an error processing the + \return MP_EXPTMOD_E may be returned if there is an error processing the ecc_key - \return MP_MOD_E may be returned if there is an error processing the + \return MP_MOD_E may be returned if there is an error processing the ecc_key - \return MP_MUL_E may be returned if there is an error processing the + \return MP_MUL_E may be returned if there is an error processing the ecc_key - \return MP_ADD_E may be returned if there is an error processing the + \return MP_ADD_E may be returned if there is an error processing the ecc_key - \return MP_MULMOD_E may be returned if there is an error processing the + \return MP_MULMOD_E may be returned if there is an error processing the ecc_key \return MP_TO_E may be returned if there is an error processing the ecc_key \return MP_MEM may be returned if there is an error processing the ecc_key - + \param in pointer to the buffer containing the ANSI x9.63 formatted ECC key \param inLen length of the input buffer \param key pointer to the ecc_key object in which to store the imported key - + _Example_ \code int ret; @@ -958,7 +958,7 @@ int wc_ecc_export_x963_ex(ecc_key*, byte* out, word32* outLen, int compressed); // error importing key } \endcode - + \sa wc_ecc_export_x963 \sa wc_ecc_import_private_key */ @@ -967,52 +967,52 @@ int wc_ecc_import_x963(const byte* in, word32 inLen, ecc_key* key); /*! \ingroup ECC - - \brief This function imports a public/private ECC key pair from a buffer - containing the raw private key, and a second buffer containing the ANSI - X9.63 formatted public key. This function will handle both compressed and - uncompressed keys, as long as compressed keys are enabled at compile time + + \brief This function imports a public/private ECC key pair from a buffer + containing the raw private key, and a second buffer containing the ANSI + X9.63 formatted public key. This function will handle both compressed and + uncompressed keys, as long as compressed keys are enabled at compile time 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 + \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) \return MEMORY_E Returned if there is an error allocating memory - \return ASN_PARSE_E Returned if there is an error parsing the ECC key; + \return ASN_PARSE_E Returned if there is an error parsing the ECC key; may indicate that the ECC key is not stored in valid ANSI X9.63 format - \return IS_POINT_E Returned if the public key exported is not a point + \return IS_POINT_E Returned if the public key exported is not a point on the ECC curve - \return MP_INIT_E may be returned if there is an error processing the + \return MP_INIT_E may be returned if there is an error processing the ecc_key - \return MP_READ_E may be returned if there is an error processing the + \return MP_READ_E may be returned if there is an error processing the ecc_key - \return MP_CMP_E may be returned if there is an error processing the + \return MP_CMP_E may be returned if there is an error processing the ecc_key - \return MP_INVMOD_E may be returned if there is an error processing + \return MP_INVMOD_E may be returned if there is an error processing the ecc_key - \return MP_EXPTMOD_E may be returned if there is an error processing + \return MP_EXPTMOD_E may be returned if there is an error processing the ecc_key - \return MP_MOD_E may be returned if there is an error processing the + \return MP_MOD_E may be returned if there is an error processing the ecc_key - \return MP_MUL_E may be returned if there is an error processing the + \return MP_MUL_E may be returned if there is an error processing the ecc_key - \return MP_ADD_E may be returned if there is an error processing the + \return MP_ADD_E may be returned if there is an error processing the ecc_key - \return MP_MULMOD_E may be returned if there is an error processing + \return MP_MULMOD_E may be returned if there is an error processing the ecc_key \return MP_TO_E may be returned if there is an error processing the ecc_key \return MP_MEM may be returned if there is an error processing the ecc_key - + \param priv pointer to the buffer containing the raw private key \param privSz size of the private key buffer - \param pub pointer to the buffer containing the ANSI x9.63 formatted ECC + \param pub pointer to the buffer containing the ANSI x9.63 formatted ECC public key \param pubSz length of the public key input buffer - \param key pointer to the ecc_key object in which to store the imported + \param key pointer to the ecc_key object in which to store the imported private/public key pair - + _Example_ \code int ret; @@ -1021,13 +1021,13 @@ NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at compile ecc_key key; wc_ecc_init_key(&key); - ret = wc_ecc_import_private_key(priv, sizeof(priv), pub, sizeof(pub), + ret = wc_ecc_import_private_key(priv, sizeof(priv), pub, sizeof(pub), &key); if ( ret != 0) { // error importing key } \endcode - + \sa wc_ecc_export_x963 \sa wc_ecc_import_private_key */ @@ -1037,44 +1037,44 @@ int wc_ecc_import_private_key(const byte* priv, word32 privSz, const byte* pub, /*! \ingroup ECC - - \brief This function converts the R and S portions of an ECC signature - into a DER-encoded ECDSA signature. This function also stores the length + + \brief This function converts the R and S portions of an ECC signature + into a DER-encoded ECDSA signature. This function also stores the length written to the output buffer, out, in outlen. - + \return 0 Returned on successfully converting the signature - \return ECC_BAD_ARG_E Returned if any of the input parameters evaluate - to NULL, or if the input buffer is not large enough to hold the + \return ECC_BAD_ARG_E Returned if any of the input parameters evaluate + to NULL, or if the input buffer is not large enough to hold the DER-encoded ECDSA signature - \return MP_INIT_E may be returned if there is an error processing + \return MP_INIT_E may be returned if there is an error processing the ecc_key - \return MP_READ_E may be returned if there is an error processing + \return MP_READ_E may be returned if there is an error processing the ecc_key - \return MP_CMP_E may be returned if there is an error processing + \return MP_CMP_E may be returned if there is an error processing the ecc_key - \return MP_INVMOD_E may be returned if there is an error processing + \return MP_INVMOD_E may be returned if there is an error processing the ecc_key - \return MP_EXPTMOD_E may be returned if there is an error processing + \return MP_EXPTMOD_E may be returned if there is an error processing the ecc_key - \return MP_MOD_E may be returned if there is an error processing the + \return MP_MOD_E may be returned if there is an error processing the ecc_key - \return MP_MUL_E may be returned if there is an error processing the + \return MP_MUL_E may be returned if there is an error processing the ecc_key - \return MP_ADD_E may be returned if there is an error processing the + \return MP_ADD_E may be returned if there is an error processing the ecc_key - \return MP_MULMOD_E may be returned if there is an error processing + \return MP_MULMOD_E may be returned if there is an error processing the ecc_key \return MP_TO_E may be returned if there is an error processing the ecc_key \return MP_MEM may be returned if there is an error processing the ecc_key - - \param r pointer to the buffer containing the R portion of the signature + + \param r pointer to the buffer containing the R portion of the signature as a string - \param s pointer to the buffer containing the S portion of the signature + \param s pointer to the buffer containing the S portion of the signature as a string - \param out pointer to the buffer in which to store the DER-encoded ECDSA + \param out pointer to the buffer in which to store the DER-encoded ECDSA signature - \param outlen length of the output buffer available. Will store the bytes - written to the buffer after successfully converting the signature to + \param outlen length of the output buffer available. Will store the bytes + written to the buffer after successfully converting the signature to ECDSA format _Example_ @@ -1085,7 +1085,7 @@ int wc_ecc_import_private_key(const byte* priv, word32 privSz, const byte* pub, char r[] = { initialize with R }; char s[] = { initialize with S }; - byte sig[wc_ecc_sig_size(key)]; + byte sig[wc_ecc_sig_size(key)]; // signature size will be 2 * ECC key size + ~10 bytes for ASN.1 overhead word32 sigSz = sizeof(sig); ret = wc_ecc_rs_to_sig(r, s, sig, &sigSz); @@ -1093,7 +1093,7 @@ int wc_ecc_import_private_key(const byte* priv, word32 privSz, const byte* pub, // error converting parameters to signature } \endcode - + \sa wc_ecc_sign_hash \sa wc_ecc_sig_size */ @@ -1102,47 +1102,47 @@ int wc_ecc_rs_to_sig(const char* r, const char* s, byte* out, word32* outlen); /*! \ingroup ECC - - \brief This function fills an ecc_key structure with the raw components + + \brief This function fills an ecc_key structure with the raw components of an ECC signature. - + \return 0 Returned upon successfully importing into the ecc_key structure \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL - \return MEMORY_E Returned if there is an error initializing space to + \return MEMORY_E Returned if there is an error initializing space to store the parameters of the ecc_key - \return ASN_PARSE_E Returned if the input curveName is not defined + \return ASN_PARSE_E Returned if the input curveName is not defined in ecc_sets - \return MP_INIT_E may be returned if there is an error processing the + \return MP_INIT_E may be returned if there is an error processing the input parameters - \return MP_READ_E may be returned if there is an error processing the + \return MP_READ_E may be returned if there is an error processing the input parameters - \return MP_CMP_E may be returned if there is an error processing the + \return MP_CMP_E may be returned if there is an error processing the input parameters - \return MP_INVMOD_E may be returned if there is an error processing the + \return MP_INVMOD_E may be returned if there is an error processing the input parameters - \return MP_EXPTMOD_E may be returned if there is an error processing the + \return MP_EXPTMOD_E may be returned if there is an error processing the input parameters - \return MP_MOD_E may be returned if there is an error processing the + \return MP_MOD_E may be returned if there is an error processing the input parameters - \return MP_MUL_E may be returned if there is an error processing the + \return MP_MUL_E may be returned if there is an error processing the input parameters - \return MP_ADD_E may be returned if there is an error processing the + \return MP_ADD_E may be returned if there is an error processing the input parameters - \return MP_MULMOD_E may be returned if there is an error processing + \return MP_MULMOD_E may be returned if there is an error processing the input parameters - \return MP_TO_E may be returned if there is an error processing the + \return MP_TO_E may be returned if there is an error processing the input parameters - \return MP_MEM may be returned if there is an error processing the + \return MP_MEM may be returned if there is an error processing the input parameters - + \param key pointer to an ecc_key structure to fill - \param qx pointer to a buffer containing the x component of the base + \param qx pointer to a buffer containing the x component of the base point as an ASCII hex string - \param qy pointer to a buffer containing the y component of the base + \param qy pointer to a buffer containing the y component of the base point as an ASCII hex string - \param d pointer to a buffer containing the private key as an ASCII + \param d pointer to a buffer containing the private key as an ASCII hex string - \param curveName pointer to a string containing the ECC curve name, + \param curveName pointer to a string containing the ECC curve name, as found in ecc_sets _Example_ @@ -1159,7 +1159,7 @@ int wc_ecc_rs_to_sig(const char* r, const char* s, byte* out, word32* outlen); // error initializing key with given inputs } \endcode - + \sa wc_ecc_import_private_key */ WOLFSSL_API @@ -1168,47 +1168,47 @@ int wc_ecc_import_raw(ecc_key* key, const char* qx, const char* qy, /*! \ingroup ECC - - \brief This function exports only the private key from an ecc_key - structure. It stores the private key in the buffer out, and sets + + \brief This function exports only the private key from an ecc_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 MEMORY_E Returned if there is an error initializing space + \return MEMORY_E Returned if there is an error initializing space to store the parameters of the ecc_key - \return ASN_PARSE_E Returned if the input curveName is not defined + \return ASN_PARSE_E Returned if the input curveName is not defined in ecc_sets - \return MP_INIT_E may be returned if there is an error processing + \return MP_INIT_E may be returned if there is an error processing the input parameters - \return MP_READ_E may be returned if there is an error processing the + \return MP_READ_E may be returned if there is an error processing the input parameters - \return MP_CMP_E may be returned if there is an error processing the + \return MP_CMP_E may be returned if there is an error processing the input parameters - \return MP_INVMOD_E may be returned if there is an error processing + \return MP_INVMOD_E may be returned if there is an error processing the input parameters - \return MP_EXPTMOD_E may be returned if there is an error processing + \return MP_EXPTMOD_E may be returned if there is an error processing the input parameters - \return MP_MOD_E may be returned if there is an error processing the + \return MP_MOD_E may be returned if there is an error processing the input parameters - \return MP_MUL_E may be returned if there is an error processing the + \return MP_MUL_E may be returned if there is an error processing the input parameters - \return MP_ADD_E may be returned if there is an error processing the + \return MP_ADD_E may be returned if there is an error processing the input parameters - \return MP_MULMOD_E may be returned if there is an error processing + \return MP_MULMOD_E may be returned if there is an error processing the input parameters - \return MP_TO_E may be returned if there is an error processing the + \return MP_TO_E may be returned if there is an error processing the input parameters - \return MP_MEM may be returned if there is an error processing the + \return MP_MEM may be returned if there is an error processing the input parameters - - \param key pointer to an ecc_key structure from which to export the + + \param key pointer to an ecc_key structure from which to export the private key \param out pointer to the buffer in which to store the private key - \param outLen pointer to a word32 object with the size available in - out. Set with the number of bytes written to out after successfully + \param 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; @@ -1222,7 +1222,7 @@ int wc_ecc_import_raw(ecc_key* key, const char* qx, const char* qy, // error exporting private key } \endcode - + \sa wc_ecc_import_private_key */ WOLFSSL_API @@ -1230,12 +1230,12 @@ int wc_ecc_export_private_only(ecc_key* key, byte* out, word32* outLen); /*! \ingroup ECC - + \brief Export point to der. - + \return 0 Returned on success. - \return ECC_BAD_ARG_E Returns if curve_idx is less than 0 or - invalid. Also returns when + \return ECC_BAD_ARG_E Returns if curve_idx is less than 0 or + invalid. Also returns when \return LENGTH_ONLY_E outLen is set but nothing else. \return BUFFER_E Returns if outLen is less than 1 + 2 * the curve size. \return MEMORY_E Returns if there is a problem allocating memory. @@ -1243,7 +1243,7 @@ int wc_ecc_export_private_only(ecc_key* key, byte* out, word32* outLen); \param curve_idx Index of the curve used from ecc_sets. \param point Point to export to der. \param out Destination for the output. - \param outLen Maxsize allowed for output, destination for + \param outLen Maxsize allowed for output, destination for final size of output _Example_ @@ -1254,7 +1254,7 @@ int wc_ecc_export_private_only(ecc_key* key, byte* out, word32* outLen); word32 outLen; wc_ecc_export_point_der(curve_idx, point, out, &outLen); \endcode - + \sa wc_ecc_import_point_der */ WOLFSSL_API @@ -1263,16 +1263,16 @@ int wc_ecc_export_point_der(const int curve_idx, ecc_point* point, /*! \ingroup ECC - + \brief Import point from der format. - - \return ECC_BAD_ARG_E Returns if any arguments are null or if + + \return ECC_BAD_ARG_E Returns if any arguments are null or if inLen is even. - \return MEMORY_E Returns if there is an error initializing - \return NOT_COMPILED_IN Returned if HAVE_COMP_KEY is not true + \return MEMORY_E Returns if there is an error initializing + \return NOT_COMPILED_IN Returned if HAVE_COMP_KEY is not true and in is a compressed cert \return MP_OKAY Successful operation. - + \param in der buffer to import point from. \param inLen Length of der buffer. \param curve_idx Index of curve. @@ -1286,7 +1286,7 @@ int wc_ecc_export_point_der(const int curve_idx, ecc_point* point, ecc_point* point; wc_ecc_import_point_der(in, inLen, curve_idx, point); \endcode - + \sa wc_ecc_export_point_der */ WOLFSSL_API @@ -1295,15 +1295,15 @@ int wc_ecc_import_point_der(byte* in, word32 inLen, const int curve_idx, /*! \ingroup ECC - - \brief This function returns the key size of an ecc_key + + \brief This function returns the key size of an ecc_key structure in octets. - + \return Given a valid key, returns the key size in octets \return 0 Returned if the given key is NULL - + \param key pointer to an ecc_key structure for which to get the key size - + _Example_ \code int keySz; @@ -1314,7 +1314,7 @@ int wc_ecc_import_point_der(byte* in, word32 inLen, const int curve_idx, // error determining key size } \endcode - + \sa wc_ecc_make_key */ WOLFSSL_API @@ -1322,16 +1322,16 @@ int wc_ecc_size(ecc_key* key); /*! \ingroup ECC - - \brief This function returns the worst case size for an ECC signature, + + \brief This function returns the worst case size for an ECC signature, given by: (keySz * 2) + SIG_HEADER_SZ + ECC_MAX_PAD_SZ. The actual signature size can be computed with wc_ecc_sign_hash. - - \return returns the maximum signature + + \return returns the maximum signature size, in octets - + \param key size - + _Example_ \code int sigSz = wc_ecc_sig_size_calc(32); @@ -1349,18 +1349,18 @@ int wc_ecc_sig_size_calc(int sz); /*! \ingroup ECC - - \brief This function returns the worst case size for an ECC signature, + + \brief This function returns the worst case size for an ECC signature, given by: (keySz * 2) + SIG_HEADER_SZ + ECC_MAX_PAD_SZ. The actual signature size can be computed with wc_ecc_sign_hash. - - \return Success Given a valid key, returns the maximum signature + + \return Success Given a valid key, returns the maximum signature size, in octets \return 0 Returned if the given key is NULL - - \param key pointer to an ecc_key structure for which to get the + + \param key pointer to an ecc_key structure for which to get the signature size - + _Example_ \code int sigSz; @@ -1383,18 +1383,18 @@ int wc_ecc_sig_size(ecc_key* key); /*! \ingroup ECC - \brief This function allocates and initializes space for a new ECC + \brief This function allocates and initializes space for a new ECC context object to allow secure message exchange with ECC. - - \return Success On successfully generating a new ecEncCtx object, + + \return Success On successfully generating a new ecEncCtx object, returns a pointer to that object - \return NULL Returned if the function fails to generate a new + \return NULL Returned if the function fails to generate a new ecEncCtx object - - \param flags indicate whether this is a server or client context + + \param flags indicate whether this is a server or client context Options are: REQ_RESP_CLIENT, and REQ_RESP_SERVER \param rng pointer to a RNG object with which to generate a salt - + _Example_ \code ecEncCtx* ctx; @@ -1405,7 +1405,7 @@ int wc_ecc_sig_size(ecc_key* key); // error generating new ecEncCtx object } \endcode - + \sa wc_ecc_encrypt \sa wc_ecc_decrypt */ @@ -1414,14 +1414,14 @@ ecEncCtx* wc_ecc_ctx_new(int flags, WC_RNG* rng); /*! \ingroup ECC - - \brief This function frees the ecEncCtx object used for encrypting + + \brief This function frees the ecEncCtx object used for encrypting and decrypting messages. - + \return none Returns. - + \param ctx pointer to the ecEncCtx object to free - + _Example_ \code ecEncCtx* ctx; @@ -1440,18 +1440,18 @@ void wc_ecc_ctx_free(ecEncCtx*); /*! \ingroup ECC - - \brief This function resets an ecEncCtx structure to avoid having + + \brief This function resets an ecEncCtx structure to avoid having to free and allocate a new context object. - + \return 0 Returned if the ecEncCtx structure is successfully reset \return BAD_FUNC_ARG Returned if either rng or ctx is NULL - \return RNG_FAILURE_E Returned if there is an error generating a + \return RNG_FAILURE_E Returned if there is an error generating a new salt for the ECC object \param ctx pointer to the ecEncCtx object to reset \param rng pointer to an RNG object with which to generate a new salt - + _Example_ \code ecEncCtx* ctx; @@ -1463,7 +1463,7 @@ void wc_ecc_ctx_free(ecEncCtx*); wc_ecc_ctx_reset(&ctx, &rng); // do more secure communication \endcode - + \sa wc_ecc_ctx_new */ WOLFSSL_API @@ -1471,19 +1471,19 @@ int wc_ecc_ctx_reset(ecEncCtx*, WC_RNG*); /* reset for use again w/o alloc/free /*! \ingroup ECC - - \brief This function returns the salt of an ecEncCtx object. This - function should only be called when the ecEncCtx's state is + + \brief This function returns the salt of an ecEncCtx object. This + function should only be called when the ecEncCtx's state is ecSRV_INIT or ecCLI_INIT. - + \return Success On success, returns the ecEncCtx salt - \return NULL Returned if the ecEncCtx object is NULL, or the ecEncCtx's - state is not ecSRV_INIT or ecCLI_INIT. In the latter two cases, this - function also sets the ecEncCtx's state to ecSRV_BAD_STATE or + \return NULL Returned if the ecEncCtx object is NULL, or the ecEncCtx's + state is not ecSRV_INIT or ecCLI_INIT. In the latter two cases, this + function also sets the ecEncCtx's state to ecSRV_BAD_STATE or ecCLI_BAD_STATE, respectively - + \param ctx pointer to the ecEncCtx object from which to get the salt - + _Example_ \code ecEncCtx* ctx; @@ -1496,7 +1496,7 @@ int wc_ecc_ctx_reset(ecEncCtx*, WC_RNG*); /* reset for use again w/o alloc/free // error getting salt } \endcode - + \sa wc_ecc_ctx_new \sa wc_ecc_ctx_set_peer_salt */ @@ -1505,21 +1505,21 @@ const byte* wc_ecc_ctx_get_own_salt(ecEncCtx*); /*! \ingroup ECC - - \brief This function sets the peer salt of an ecEncCtx object. - - \return 0 Returned upon successfully setting the peer salt for the + + \brief This function sets the peer salt of an ecEncCtx object. + + \return 0 Returned upon successfully setting the peer salt for the ecEncCtx object. - \return BAD_FUNC_ARG Returned if the given ecEncCtx object is NULL + \return BAD_FUNC_ARG Returned if the given ecEncCtx object is NULL or has an invalid protocol, or if the given salt is NULL - \return BAD_ENC_STATE_E Returned if the ecEncCtx's state is - ecSRV_SALT_GET or ecCLI_SALT_GET. In the latter two cases, this - function also sets the ecEncCtx's state to ecSRV_BAD_STATE or + \return BAD_ENC_STATE_E Returned if the ecEncCtx's state is + ecSRV_SALT_GET or ecCLI_SALT_GET. In the latter two cases, this + function also sets the ecEncCtx's state to ecSRV_BAD_STATE or ecCLI_BAD_STATE, respectively \param ctx pointer to the ecEncCtx for which to set the salt \param salt pointer to the peer's salt - + _Example_ \code ecEncCtx* cliCtx, srvCtx; @@ -1535,7 +1535,7 @@ const byte* wc_ecc_ctx_get_own_salt(ecEncCtx*); srvSalt = wc_ecc_ctx_get_own_salt(&srvCtx); ret = wc_ecc_ctx_set_peer_salt(&cliCtx, srvSalt); \endcode - + \sa wc_ecc_ctx_get_own_salt */ WOLFSSL_API @@ -1543,20 +1543,20 @@ int wc_ecc_ctx_set_peer_salt(ecEncCtx*, const byte* salt); /*! \ingroup ECC - - \brief This function can optionally be called before or after - wc_ecc_ctx_set_peer_salt. It sets optional information for + + \brief This function can optionally be called before or after + wc_ecc_ctx_set_peer_salt. It sets optional information for an ecEncCtx object. - \return 0 Returned upon successfully setting the information + \return 0 Returned upon successfully setting the information for the ecEncCtx object. - \return BAD_FUNC_ARG Returned if the given ecEncCtx object is + \return BAD_FUNC_ARG Returned if the given ecEncCtx object is NULL, the input info is NULL or it's size is invalid - + \param ctx pointer to the ecEncCtx for which to set the info \param info pointer to a buffer containing the info to set \param sz size of the info buffer - + _Example_ \code ecEncCtx* ctx; @@ -1566,7 +1566,7 @@ int wc_ecc_ctx_set_peer_salt(ecEncCtx*, const byte* salt); // error setting info } \endcode - + \sa wc_ecc_ctx_new */ WOLFSSL_API @@ -1574,38 +1574,38 @@ int wc_ecc_ctx_set_info(ecEncCtx*, const byte* info, int sz); /*! \ingroup ECC - - \brief This function encrypts the given input message from msg - to out. This function takes an optional ctx object as parameter. - When supplied, encryption proceeds based on the ecEncCtx's - encAlgo, kdfAlgo, and macAlgo. If ctx is not supplied, processing - completes with the default algorithms, ecAES_128_CBC, - ecHKDF_SHA256 and ecHMAC_SHA256. This function requires that + + \brief This function encrypts the given input message from msg + to out. This function takes an optional ctx object as parameter. + When supplied, encryption proceeds based on the ecEncCtx's + encAlgo, kdfAlgo, and macAlgo. If ctx is not supplied, processing + completes with the default algorithms, ecAES_128_CBC, + ecHKDF_SHA256 and ecHMAC_SHA256. This function requires that the messages are padded according to the encryption type specified by ctx. - + \return 0 Returned upon successfully encrypting the input message - \return BAD_FUNC_ARG Returned if privKey, pubKey, msg, msgSz, out, - or outSz are NULL, or the ctx object specifies an unsupported + \return BAD_FUNC_ARG Returned if privKey, pubKey, msg, msgSz, out, + or outSz are NULL, or the ctx object specifies an unsupported encryption type - \return BAD_ENC_STATE_E Returned if the ctx object given is in a + \return BAD_ENC_STATE_E Returned if the ctx object given is in a state that is not appropriate for encryption - \return BUFFER_E Returned if the supplied output buffer is too + \return BUFFER_E Returned if the supplied output buffer is too small to store the encrypted ciphertext - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory for the shared secret key - \param privKey pointer to the ecc_key object containing the + \param privKey pointer to the ecc_key object containing the private key to use for encryption - \param pubKey pointer to the ecc_key object containing the public + \param pubKey pointer to the ecc_key object containing the public key of the peer with whom one wishes to communicate \param msg pointer to the buffer holding the message to encrypt \param msgSz size of the buffer to encrypt - \param out pointer to the buffer in which to store the encrypted - ciphertext - \param outSz pointer to a word32 object containing the available - size in the out buffer. Upon successfully encrypting the message, + \param out pointer to the buffer in which to store the encrypted + ciphertext + \param outSz pointer to a word32 object containing the available + size in the out buffer. Upon successfully encrypting the message, holds the number of bytes written to the output buffer - \param ctx Optional: pointer to an ecEncCtx object specifying different + \param ctx Optional: pointer to an ecEncCtx object specifying different encryption algorithms to use _Example_ @@ -1622,11 +1622,11 @@ int wc_ecc_ctx_set_info(ecEncCtx*, const byte* info, int sz); // initialize cliCtx and servCtx // exchange salts ret = wc_ecc_encrypt(&cli, &serv, msg, sizeof(msg), out, &outSz, cliCtx); - if(ret != 0) { - // error encrypting message + if(ret != 0) { + // error encrypting message } \endcode - + \sa wc_ecc_decrypt */ WOLFSSL_API @@ -1635,42 +1635,42 @@ int wc_ecc_encrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg, /*! \ingroup ECC - - \brief This function decrypts the ciphertext from msg to out. This - function takes an optional ctx object as parameter. When supplied, - encryption proceeds based on the ecEncCtx's encAlgo, kdfAlgo, and - macAlgo. If ctx is not supplied, processing completes with the - default algorithms, ecAES_128_CBC, ecHKDF_SHA256 and ecHMAC_SHA256. - This function requires that the messages are padded according to + + \brief This function decrypts the ciphertext from msg to out. This + function takes an optional ctx object as parameter. When supplied, + encryption proceeds based on the ecEncCtx's encAlgo, kdfAlgo, and + macAlgo. If ctx is not supplied, processing completes with the + default algorithms, ecAES_128_CBC, ecHKDF_SHA256 and ecHMAC_SHA256. + This function requires that the messages are padded according to the encryption type specified by ctx. - + \return 0 Returned upon successfully decrypting the input message - \return BAD_FUNC_ARG Returned if privKey, pubKey, msg, msgSz, out, - or outSz are NULL, or the ctx object specifies an unsupported + \return BAD_FUNC_ARG Returned if privKey, pubKey, msg, msgSz, out, + or outSz are NULL, or the ctx object specifies an unsupported encryption type - \return BAD_ENC_STATE_E Returned if the ctx object given is in + \return BAD_ENC_STATE_E Returned if the ctx object given is in a state that is not appropriate for decryption - \return BUFFER_E Returned if the supplied output buffer is too + \return BUFFER_E Returned if the supplied output buffer is too small to store the decrypted plaintext - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory for the shared secret key - - \param privKey pointer to the ecc_key object containing the private + + \param privKey pointer to the ecc_key object containing the private key to use for decryption - \param pubKey pointer to the ecc_key object containing the public + \param pubKey pointer to the ecc_key object containing the public key of the peer with whom one wishes to communicate \param msg pointer to the buffer holding the ciphertext to decrypt \param msgSz size of the buffer to decrypt \param out pointer to the buffer in which to store the decrypted plaintext - \param outSz pointer to a word32 object containing the available - size in the out buffer. Upon successfully decrypting the + \param outSz pointer to a word32 object containing the available + size in the out buffer. Upon successfully decrypting the ciphertext, holds the number of bytes written to the output buffer - \param ctx Optional: pointer to an ecEncCtx object specifying + \param ctx Optional: pointer to an ecEncCtx object specifying different decryption algorithms to use - + _Example_ \code - byte cipher[] = { initialize with + byte cipher[] = { initialize with ciphertext to decrypt. Ensure padded to block size }; byte plain[sizeof(cipher)]; word32 plainSz = sizeof(plain); @@ -1681,14 +1681,14 @@ int wc_ecc_encrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg, ecEncCtx* cliCtx, servCtx; // initialize cliCtx and servCtx // exchange salts - ret = wc_ecc_decrypt(&cli, &serv, cipher, sizeof(cipher), + ret = wc_ecc_decrypt(&cli, &serv, cipher, sizeof(cipher), plain, &plainSz, cliCtx); - if(ret != 0) { - // error decrypting message + if(ret != 0) { + // error decrypting message } \endcode - + \sa Wc_ecc_encrypt */ WOLFSSL_API diff --git a/doc/dox_comments/header_files/ed25519.h b/doc/dox_comments/header_files/ed25519.h index c2fa273fd..c5e09a9dc 100644 --- a/doc/dox_comments/header_files/ed25519.h +++ b/doc/dox_comments/header_files/ed25519.h @@ -1,15 +1,15 @@ /*! \ingroup ED25519 - + \brief This function generates a new ed25519_key and stores it in key. - + \retrun 0 Returned upon successfully making an ed25519_key - \retrun BAD_FUNC_ARG Returned if rng or key evaluate to NULL, or if the + \retrun 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) - \retrun MEMORY_E Returned if there is an error allocating memory + \retrun MEMORY_E Returned if there is an error allocating memory during function execution - \param rng pointer to an initialized RNG object with which to + \param rng pointer to an initialized RNG object with which to generate the key \param keysize length of key to generate. Should always be 32 for ed25519 \param key pointer to the ed25519_key for which to generate a key @@ -22,7 +22,7 @@ wc_InitRng(&rng); wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key \endcode - + \sa wc_ed25519_init */ WOLFSSL_API @@ -30,25 +30,25 @@ 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 digest using an ed25519_key object to guarantee authenticity. - - \return 0 Returned upon successfully generating a signature for the + + \return 0 Returned upon successfully generating a signature for the message digest - \return BAD_FUNC_ARG Returned any of the input parameters evaluate to + \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 + \return MEMORY_E Returned if there is an error allocating memory during function execution - + \param in pointer to the buffer containing the message to sign \param inlen length of the message to sign \param out buffer in which to store the generated signature - \param outlen max length of the output buffer. Will store the bytes + \param outlen max length of the output buffer. Will store the bytes written to out upon successfully generating a message signature - \param key pointer to a private ed25519_key with which to generate the + \param key pointer to a private ed25519_key with which to generate the signature - + _Example_ \code ed25519_key key; @@ -67,7 +67,7 @@ int wc_ed25519_make_key(WC_RNG* rng, int keysize, ed25519_key* key); // error generating message signature } \endcode - + \sa wc_ed25519_verify_msg */ WOLFSSL_API @@ -76,26 +76,26 @@ 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 - authenticity. It returns the answer through stat, with 1 corresponding to + + \brief This function verifies the ed25519 signature of a message to ensure + authenticity. It returns the answer through stat, 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. + + \return 0 Returned upon successfully performing the signature + verification. Note: This does not mean that the signature is verified. The authenticity information is stored instead in stat - \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to + \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 1 Returned if verification completes, but the signature generated + \return 1 Returned if verification completes, but the signature generated does not match the signature provided - + \param sig pointer to the buffer containing the signature to verify \param siglen length of the signature to verify \param msg pointer to the buffer containing the message to verify \param msglen length of the message to verify - \param stat pointer to the result of the verification. 1 indicates the + \param stat pointer to the result of the verification. 1 indicates the message was successfully verified - \param key pointer to a public ed25519 key with which to verify the + \param key pointer to a public ed25519 key with which to verify the signature _Example_ @@ -106,7 +106,7 @@ int wc_ed25519_sign_msg(const byte* in, word32 inlen, byte* out, byte sig[] { // initialize with received signature }; 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, &key); if ( return < 0 ) { @@ -115,7 +115,7 @@ int wc_ed25519_sign_msg(const byte* in, word32 inlen, byte* out, // the signature is invalid } \endcode - + \sa wc_ed25519_sign_msg */ WOLFSSL_API @@ -124,21 +124,21 @@ int wc_ed25519_verify_msg(const byte* sig, word32 siglen, const byte* msg, /*! \ingroup ED25519 - - \brief This function initializes an ed25519_key object for future use + + \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 BAD_FUNC_ARG Returned if key is NULL - + \param key pointer to the ed25519_key object to initialize - + _Example_ \code ed25519_key key; wc_ed25519_init(&key); \endcode - + \sa wc_ed25519_make_key \sa wc_ed25519_free */ @@ -147,13 +147,13 @@ int wc_ed25519_init(ed25519_key* key); /*! \ingroup ED25519 - + \brief This function frees an ed25519 object after it has been used. - + \return none No returns. - + \param key pointer to the ed25519_key object to free - + _Example_ \code ed25519_key key; @@ -161,7 +161,7 @@ int wc_ed25519_init(ed25519_key* key); ... wc_ed25519_free(&key); \endcode - + \sa wc_ed25519_init */ WOLFSSL_API @@ -169,20 +169,20 @@ void wc_ed25519_free(ed25519_key* key); /*! \ingroup ED25519 - - \brief This function imports a public ed25519_key pair from a buffer - containing the public key. This function will handle both compressed and + + \brief This function imports a public ed25519_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 ed25519_key - \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is + \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is less than the size of an ed25519 key - + \param in pointer to the buffer containing the public key \param inLen length of the buffer containing the public key - \param key pointer to the ed25519_key object in which to store the + \param key pointer to the ed25519_key object in which to store the public key - + _Example_ \code int ret; @@ -195,7 +195,7 @@ void wc_ed25519_free(ed25519_key* key); // error importing key } \endcode - + \sa wc_ed25519_import_private_key \sa wc_ed25519_export_public */ @@ -204,20 +204,20 @@ 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 - pair of buffers. This function will handle both compressed and + + \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 + \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 - + \param priv pointer to the buffer containing the private key \param privSz size of the private key \param pub pointer to the buffer containing the public key \param pubSz length of the public key - \param key pointer to the ed25519_key object in which to store the + \param key pointer to the ed25519_key object in which to store the imported private/public key pair _Example_ @@ -228,13 +228,13 @@ int wc_ed25519_import_public(const byte* in, word32 inLen, ed25519_key* 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), pub, sizeof(pub), &key); if ( ret != 0) { // error importing key } \endcode - + \sa wc_ed25519_import_public_key \sa wc_ed25519_export_private_only */ @@ -244,22 +244,22 @@ int wc_ed25519_import_private_key(const byte* priv, word32 privSz, /*! \ingroup ED25519 - - \brief This function exports the private key from an ed25519_key - structure. It stores the public key in the buffer out, and sets the bytes + + \brief This function exports the private key from an ed25519_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 + \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 key pointer to an ed25519_key structure from which to export the + + \param key pointer to an ed25519_key structure from which to export the public key \param 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. - Set with the number of bytes written to out after successfully exporting + \param 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_ @@ -276,7 +276,7 @@ int wc_ed25519_import_private_key(const byte* priv, word32 privSz, // error exporting public key } \endcode - + \sa wc_ed25519_import_public_key \sa wc_ed25519_export_private_only */ @@ -285,23 +285,23 @@ int wc_ed25519_export_public(ed25519_key*, byte* out, word32* outLen); /*! \ingroup ED25519 - - \brief This function exports only the private key from an ed25519_key - structure. It stores the private key in the buffer out, and sets + + \brief This function exports only the private key from an ed25519_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 + \return BUFFER_E Returned if the buffer provided is not large enough to store the private key - - \param key pointer to an ed25519_key structure from which to export + + \param key pointer to an ed25519_key structure from which to export the private key \param out pointer to the buffer in which to store the private key - \param outLen pointer to a word32 object with the size available in - out. Set with the number of bytes written to out after successfully + \param 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; @@ -315,7 +315,7 @@ int wc_ed25519_export_public(ed25519_key*, byte* out, word32* outLen); // error exporting private key } \endcode - + \sa wc_ed25519_export_public \sa wc_ed25519_import_private_key */ @@ -324,7 +324,7 @@ int wc_ed25519_export_private_only(ed25519_key* key, byte* out, word32* outLen); /*! \ingroup ED25519 - + \brief Export the private key, including public part. \return 0 Success @@ -333,9 +333,9 @@ int wc_ed25519_export_private_only(ed25519_key* key, byte* out, word32* outLen); \param key ed25519_key struct to export from. \param out Destination for private key. - \param outLen Max length of output, set to the length of the exported + \param outLen Max length of output, set to the length of the exported private key. - + _Example_ \code ed25519_key key; @@ -354,7 +354,7 @@ int wc_ed25519_export_private_only(ed25519_key* key, byte* out, word32* outLen); // Check size of out compared to outLen to see if function reset outLen } \endcode - + \sa none */ WOLFSSL_API @@ -362,14 +362,14 @@ int wc_ed25519_export_private(ed25519_key* key, byte* out, word32* outLen); /*! \ingroup ED25519 - + \brief Export full private key and public key. - + \return 0 Success \return BAD_FUNC_ARG: Returns if any argument is null. - \return BUFFER_E: Returns if outLen is less than ED25519_PRV_KEY_SIZE + \return BUFFER_E: Returns if outLen is less than ED25519_PRV_KEY_SIZE or ED25519_PUB_KEY_SIZE - + \param key The ed25519_key structure to export to. \param priv Byte array to store private key. \param privSz Size of priv buffer. @@ -392,7 +392,7 @@ int wc_ed25519_export_private(ed25519_key* key, byte* out, word32* outLen); // error exporting public key } \endcode - + \sa wc_ed25519_export_private \sa wc_ed25519_export_public */ @@ -403,16 +403,16 @@ 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 returns the key size of an ed25519_key structure, or 32 bytes. - + \return Success Given a valid key, returns ED25519_KEY_SIZE (32 bytes) \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 key pointer to an ed25519_key structure for which to get the key size - + _Example_ \code int keySz; @@ -423,7 +423,7 @@ int wc_ed25519_export_key(ed25519_key* key, // error determining key size } \endcode - + \sa wc_ed25519_make_key */ WOLFSSL_API @@ -431,14 +431,14 @@ int wc_ed25519_size(ed25519_key* key); /*! \ingroup ED25519 - + \brief 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. - + \param key The ed25119_key struct - + _Example_ \code ed25519_key key; @@ -450,7 +450,7 @@ int wc_ed25519_size(ed25519_key* 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 */ WOLFSSL_API @@ -458,14 +458,14 @@ int wc_ed25519_priv_size(ed25519_key* key); /*! \ingroup ED25519 - + \brief Returns the compressed key size in bytes (public key). - + \return BAD_FUNC_ARG returns if key is null. \return ED25519_PUB_KEY_SIZE Size of key. - + \param key Pointer to the ed25519_key struct. - + _Example_ \code ed25519_key key; @@ -476,7 +476,7 @@ int wc_ed25519_priv_size(ed25519_key* key); wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key int key_size = wc_ed25519_pub_size(&key); \endcode - + \sa wc_ed25519_priv_size */ WOLFSSL_API @@ -484,15 +484,15 @@ int wc_ed25519_pub_size(ed25519_key* key); /*! \ingroup ED25519 - + \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 0 Returned if the given key is NULL - - \param key pointer to an ed25519_key structure for which to get the + + \param key pointer to an ed25519_key structure for which to get the signature size - + _Example_ \code int sigSz; @@ -504,7 +504,7 @@ int wc_ed25519_pub_size(ed25519_key* key); // error determining sig size } \endcode - + \sa wc_ed25519_sign_msg */ WOLFSSL_API diff --git a/doc/dox_comments/header_files/error-crypt.h b/doc/dox_comments/header_files/error-crypt.h index a97153d09..139c57e3c 100644 --- a/doc/dox_comments/header_files/error-crypt.h +++ b/doc/dox_comments/header_files/error-crypt.h @@ -1,15 +1,15 @@ /*! \ingroup Error - - \brief This function stores the error string for a particular error code + + \brief This function stores the error string for a particular error code in the given buffer. - + \return none No returns. - + \param error error code for which to get the string - \param buffer buffer in which to store the error string. Buffer should be + \param buffer buffer in which to store the error string. Buffer should be at least WOLFSSL_MAX_ERROR_SZ (80 bytes) long - + _Example_ \code char errorMsg[WOLFSSL_MAX_ERROR_SZ]; @@ -19,21 +19,21 @@ wc_ErrorString(err, errorMsg); } \endcode - + \sa wc_GetErrorString */ WOLFSSL_API void wc_ErrorString(int err, char* buff); /*! \ingroup Error - + \brief This function returns the error string for a particular error code. - - \return string Returns the error string for an error code as a + + \return string Returns the error string for an error code as a string literal. - + \param error error code for which to get the string - + _Example_ \code char * errorMsg; @@ -43,7 +43,7 @@ WOLFSSL_API void wc_ErrorString(int err, char* buff); errorMsg = wc_GetErrorString(err); } \endcode - + \sa wc_ErrorString */ WOLFSSL_API const char* wc_GetErrorString(int error); diff --git a/doc/dox_comments/header_files/evp.h b/doc/dox_comments/header_files/evp.h index cad033f57..840ef50be 100644 --- a/doc/dox_comments/header_files/evp.h +++ b/doc/dox_comments/header_files/evp.h @@ -1,64 +1,64 @@ /*! \ingroup openSSL - - \brief Getter functions for the respective WOLFSSL_EVP_CIPHER pointers. - wolfSSL_EVP_init() must be called once in the program first to populate - these cipher strings. WOLFSSL_DES_ECB macro must be defined for + + \brief Getter functions for the respective WOLFSSL_EVP_CIPHER pointers. + wolfSSL_EVP_init() must be called once in the program first to populate + these cipher strings. WOLFSSL_DES_ECB macro must be defined for wolfSSL_EVP_des_ede3_ecb(). - + \return pointer Returns a WOLFSSL_EVP_CIPHER pointer for DES EDE3 operations. - + \param none No parameters. - + _Example_ \code - printf("block size des ede3 cbc = %d\n", + printf("block size des ede3 cbc = %d\n", wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_cbc())); - printf("block size des ede3 ecb = %d\n", + printf("block size des ede3 ecb = %d\n", wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_ecb())); \endcode - + \sa wolfSSL_EVP_CIPHER_CTX_init */ WOLFSSL_API const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_ede3_ecb(void); /*! \ingroup openSSL - - \brief Getter functions for the respective WOLFSSL_EVP_CIPHER pointers. - wolfSSL_EVP_init() must be called once in the program first to populate - these cipher strings. WOLFSSL_DES_ECB macro must be defined for + + \brief Getter functions for the respective WOLFSSL_EVP_CIPHER pointers. + wolfSSL_EVP_init() must be called once in the program first to populate + these cipher strings. WOLFSSL_DES_ECB macro must be defined for wolfSSL_EVP_des_ecb(). - + \return pointer Returns a WOLFSSL_EVP_CIPHER pointer for DES operations. - + \param none No parameters. - + _Example_ \code WOLFSSL_EVP_CIPHER* cipher; cipher = wolfSSL_EVP_des_cbc(); … \endcode - + \sa wolfSSL_EVP_CIPHER_CTX_init */ WOLFSSL_API const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_cbc(void); /*! \ingroup openSSL - - \brief Function for initializing WOLFSSL_EVP_MD_CTX. This function is a - wrapper for wolfSSL_EVP_DigestInit() because wolfSSL does not + + \brief Function for initializing WOLFSSL_EVP_MD_CTX. This function is a + wrapper for wolfSSL_EVP_DigestInit() because wolfSSL does not use WOLFSSL_ENGINE. - + \return SSL_SUCCESS If successfully set. \return SSL_FAILURE If not successful. - + \param ctx structure to initialize. \param type type of hash to do, for example SHA. \param impl engine to use. N/A for wolfSSL, can be NULL. - + _Example_ \code WOLFSSL_EVP_MD_CTX* md = NULL; @@ -68,11 +68,11 @@ WOLFSSL_API const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_cbc(void); printf("error setting md\n"); return -1; } - printf("cipher md init ret = %d\n", wolfSSL_EVP_DigestInit_ex(md, - wolfSSL_EVP_sha1(), e)); + printf("cipher md init ret = %d\n", wolfSSL_EVP_DigestInit_ex(md, + wolfSSL_EVP_sha1(), e)); //free resources \endcode - + \sa wolfSSL_EVP_MD_CTX_new \sa wolfCrypt_Init \sa wolfSSL_EVP_MD_CTX_free @@ -83,21 +83,21 @@ WOLFSSL_API int wolfSSL_EVP_DigestInit_ex(WOLFSSL_EVP_MD_CTX* ctx, /*! \ingroup openSSL - - \brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a - wrapper for wolfSSL_CipherInit() because wolfSSL does not + + \brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a + wrapper for wolfSSL_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE. - + \return SSL_SUCCESS If successfully set. \return SSL_FAILURE If not successful. - + \param ctx structure to initialize. \param type type of encryption/decryption to do, for example AES. \param impl engine to use. N/A for wolfSSL, can be NULL. \param key key to set . \param iv iv if needed by algorithm. \param enc encryption (1) or decryption (0) flag. - + _Example_ \code WOLFSSL_EVP_CIPHER_CTX* ctx = NULL; @@ -110,14 +110,14 @@ WOLFSSL_API int wolfSSL_EVP_DigestInit_ex(WOLFSSL_EVP_MD_CTX* ctx, printf("issue creating ctx\n"); return -1; } - - printf("cipher init ex error ret = %d\n", wolfSSL_EVP_CipherInit_ex(NULL, + + printf("cipher init ex error ret = %d\n", wolfSSL_EVP_CipherInit_ex(NULL, EVP_aes_128_ cbc(), e, key, iv, 1)); - printf("cipher init ex success ret = %d\n", wolfSSL_EVP_CipherInit_ex(ctx, + printf("cipher init ex success ret = %d\n", wolfSSL_EVP_CipherInit_ex(ctx, EVP_aes_128_c bc(), e, key, iv, 1)); // free resources \endcode - + \sa wolfSSL_EVP_CIPHER_CTX_new \sa wolfCrypt_Init \sa wolfSSL_EVP_CIPHER_CTX_free @@ -131,20 +131,20 @@ WOLFSSL_API int wolfSSL_EVP_CipherInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, /*! \ingroup openSSL - - \brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a - wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use + + \brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a + wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE. Sets encrypt flag to be encrypt. - + \return SSL_SUCCESS If successfully set. \return SSL_FAILURE If not successful. - + \param ctx structure to initialize. \param type type of encryption to do, for example AES. \param impl engine to use. N/A for wolfSSL, can be NULL. \param key key to use. \param iv iv to use. - + _Example_ \code WOLFSSL_EVP_CIPHER_CTX* ctx = NULL; @@ -154,7 +154,7 @@ WOLFSSL_API int wolfSSL_EVP_CipherInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, printf("error setting ctx\n"); return -1; } - printf("cipher ctx init ret = %d\n", wolfSSL_EVP_EncryptInit_ex(ctx, + printf("cipher ctx init ret = %d\n", wolfSSL_EVP_EncryptInit_ex(ctx, wolfSSL_EVP_aes_128_cbc(), e, key, iv)); //free resources \endcode @@ -171,21 +171,21 @@ WOLFSSL_API int wolfSSL_EVP_EncryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, /*! \ingroup openSSL - - \brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a - wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use + + \brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a + wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE. Sets encrypt flag to be decrypt. - + \return SSL_SUCCESS If successfully set. \return SSL_FAILURE If not successful. - + \param ctx structure to initialize. \param type type of encryption/decryption to do, for example AES. \param impl engine to use. N/A for wolfSSL, can be NULL. \param key key to set . \param iv iv if needed by algorithm. \param enc encryption (1) or decryption (0) flag. - + _Example_ \code WOLFSSL_EVP_CIPHER_CTX* ctx = NULL; @@ -201,13 +201,13 @@ WOLFSSL_API int wolfSSL_EVP_EncryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, return -1; } - printf("cipher init ex error ret = %d\n", wolfSSL_EVP_DecryptInit_ex(NULL, + printf("cipher init ex error ret = %d\n", wolfSSL_EVP_DecryptInit_ex(NULL, EVP_aes_128_ cbc(), e, key, iv, 1)); - printf("cipher init ex success ret = %d\n", wolfSSL_EVP_DecryptInit_ex(ctx, + printf("cipher init ex success ret = %d\n", wolfSSL_EVP_DecryptInit_ex(ctx, EVP_aes_128_c bc(), e, key, iv, 1)); // free resources \endcode - + \sa wolfSSL_EVP_CIPHER_CTX_new \sa wolfCrypt_Init \sa wolfSSL_EVP_CIPHER_CTX_free @@ -220,11 +220,11 @@ WOLFSSL_API int wolfSSL_EVP_DecryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, /*! \ingroup openSSL - - \brief Function for encrypting/decrypting data. In buffer is added to be - encrypted or decrypted and out buffer holds the results. outl will be the + + \brief Function for encrypting/decrypting data. In buffer is added to be + encrypted or decrypted and out buffer holds the results. outl will be the length of encrypted/decrypted information. - + \return SSL_SUCCESS If successfull. \return SSL_FAILURE If not successful. @@ -233,7 +233,7 @@ WOLFSSL_API int wolfSSL_EVP_DecryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, \param outl adjusted to be size of output. \param in buffer to perform operation on. \param inl length of input buffer. - + _Example_ \code WOLFSSL_EVP_CIPHER_CTX* ctx = NULL; @@ -249,7 +249,7 @@ WOLFSSL_API int wolfSSL_EVP_DecryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, // buffer out holds outl bytes of data // free resources \endcode - + \sa wolfSSL_EVP_CIPHER_CTX_new \sa wolfCrypt_Init \sa wolfSSL_EVP_CIPHER_CTX_free @@ -260,21 +260,21 @@ WOLFSSL_API int wolfSSL_EVP_CipherUpdate(WOLFSSL_EVP_CIPHER_CTX *ctx, /*! \ingroup openSSL - - \brief This function performs the final cipher operations adding in - padding. If WOLFSSL_EVP_CIPH_NO_PADDING flag is set in - WOLFSSL_EVP_CIPHER_CTX structure then 1 is returned and no - encryption/decryption is done. If padding flag is seti padding is added and - encrypted when ctx is set to encrypt, padding values are checked when set + + \brief This function performs the final cipher operations adding in + padding. If WOLFSSL_EVP_CIPH_NO_PADDING flag is set in + WOLFSSL_EVP_CIPHER_CTX structure then 1 is returned and no + encryption/decryption is done. If padding flag is seti padding is added and + encrypted when ctx is set to encrypt, padding values are checked when set to decrypt. - + \return 1 Returned on success. \return 0 If encountering a failure. - + \param ctx structure to decrypt/encrypt with. \param out buffer for final decrypt/encrypt. \param out1 size of out buffer when data has been added by function. - + _Example_ \code WOLFSSL_EVP_CIPHER_CTX* ctx; @@ -283,7 +283,7 @@ WOLFSSL_API int wolfSSL_EVP_CipherUpdate(WOLFSSL_EVP_CIPHER_CTX *ctx, // create ctx wolfSSL_EVP_CipherFinal(ctx, out, &out1); \endcode - + \sa wolfSSL_EVP_CIPHER_CTX_new */ WOLFSSL_API int wolfSSL_EVP_CipherFinal(WOLFSSL_EVP_CIPHER_CTX *ctx, @@ -291,15 +291,15 @@ WOLFSSL_API int wolfSSL_EVP_CipherFinal(WOLFSSL_EVP_CIPHER_CTX *ctx, /*! \ingroup openSSL - + \brief Setter function for WOLFSSL_EVP_CIPHER_CTX structure key length. - + \return SSL_SUCCESS If successfully set. \return SSL_FAILURE If failed to set key length. - + \param ctx structure to set key length. \param keylen key length. - + _Example_ \code WOLFSSL_EVP_CIPHER_CTX* ctx; @@ -307,7 +307,7 @@ WOLFSSL_API int wolfSSL_EVP_CipherFinal(WOLFSSL_EVP_CIPHER_CTX *ctx, // create ctx wolfSSL_EVP_CIPHER_CTX_set_key_length(ctx, keylen); \endcode - + \sa wolfSSL_EVP_CIPHER_flags */ WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_set_key_length(WOLFSSL_EVP_CIPHER_CTX* ctx, @@ -315,53 +315,53 @@ WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_set_key_length(WOLFSSL_EVP_CIPHER_CTX* c /*! \ingroup openSSL - + \brief This is a getter function for the ctx block size. - + \return size Returns ctx->block_size. - + \param ctx the cipher ctx to get block size of. - + _Example_ \code const WOLFSSL_CVP_CIPHER_CTX* ctx; //set up ctx printf(“block size = %d\n”, wolfSSL_EVP_CIPHER_CTX_block_size(ctx)); \endcode - + \sa wolfSSL_EVP_CIPHER_block_size */ WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_block_size(const WOLFSSL_EVP_CIPHER_CTX *ctx); /*! \ingroup openSSL - + \brief This is a getter function for the block size of cipher. - + \return size returns the block size. - + \param cipher cipher to get block size of. - + _Example_ \code - printf(“block size = %d\n”, + printf(“block size = %d\n”, wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_aes_256_ecb())); \endcode - + \sa wolfSSL_EVP_aes_256_ctr */ WOLFSSL_API int wolfSSL_EVP_CIPHER_block_size(const WOLFSSL_EVP_CIPHER *cipher); /*! \ingroup openSSL - + \brief Setter function for WOLFSSL_EVP_CIPHER_CTX structure. - + \return none No returns. - + \param ctx structure to set flag. \param flag flag to set in structure. - + _Example_ \code WOLFSSL_EVP_CIPHER_CTX* ctx; @@ -369,29 +369,29 @@ WOLFSSL_API int wolfSSL_EVP_CIPHER_block_size(const WOLFSSL_EVP_CIPHER *cipher); // create ctx wolfSSL_EVP_CIPHER_CTX_set_flags(ctx, flag); \endcode - + \sa wolfSSL_EVP_CIPHER_flags */ WOLFSSL_API void wolfSSL_EVP_CIPHER_CTX_set_flags(WOLFSSL_EVP_CIPHER_CTX *ctx, int flags); /*! \ingroup openSSL - + \brief Setter function for WOLFSSL_EVP_CIPHER_CTX structure to use padding. - + \return SSL_SUCCESS If successfully set. \return BAD_FUNC_ARG If null argument passed in. - + \param ctx structure to set padding flag. \param padding 0 for not setting padding, 1 for setting padding. - + _Example_ \code WOLFSSL_EVP_CIPHER_CTX* ctx; // create ctx wolfSSL_EVP_CIPHER_CTX_set_padding(ctx, 1); \endcode - + \sa wolfSSL_EVP_CIPHER_flags */ WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_set_padding(WOLFSSL_EVP_CIPHER_CTX *c, int pad); diff --git a/doc/dox_comments/header_files/hash.h b/doc/dox_comments/header_files/hash.h index 043dfdf48..8f6c24282 100644 --- a/doc/dox_comments/header_files/hash.h +++ b/doc/dox_comments/header_files/hash.h @@ -1,15 +1,15 @@ /*! \ingroup wolfCrypt - + \brief This function will return the OID for the wc_HashType provided. - + \return OID returns value greater than 0 \return HASH_TYPE_E hash type not supported. \return BAD_FUNC_ARG one of the provided arguments is incorrect. - - \param hash_type A hash type from the “enum wc_HashType” such + + \param hash_type A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”. - + _Example_ \code enum wc_HashType hash_type = WC_HASH_TYPE_SHA256; @@ -18,7 +18,7 @@ // Success } \endcode - + \sa wc_HashGetDigestSize \sa wc_Hash */ @@ -26,19 +26,19 @@ WOLFSSL_API int wc_HashGetOID(enum wc_HashType hash_type); /*! \ingroup wolfCrypt - - \brief This function returns the size of the digest (output) for a - hash_type. The returns size is used to make sure the output buffer + + \brief This function returns the size of the digest (output) for a + hash_type. The returns size is used to make sure the output buffer provided to wc_Hash is large enough. - - \return Success A positive return value indicates the digest size + + \return Success A positive return value indicates the digest size for the hash. - \return Error Returns HASH_TYPE_E if hash_type is not supported. + \return Error Returns HASH_TYPE_E if hash_type is not supported. \return Failure Returns BAD_FUNC_ARG if an invalid hash_type was used. - - \param hash_type A hash type from the “enum wc_HashType” such as + + \param hash_type A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”. - + _Example_ \code int hash_len = wc_HashGetDigestSize(hash_type); @@ -47,26 +47,26 @@ WOLFSSL_API int wc_HashGetOID(enum wc_HashType hash_type); return BAD_FUNC_ARG; } \endcode - + \sa wc_Hash */ WOLFSSL_API int wc_HashGetDigestSize(enum wc_HashType hash_type); /*! \ingroup wolfCrypt - - \brief This function performs a hash on the provided data buffer + + \brief This function performs a hash on the provided data buffer and returns it in the hash buffer provided. - + \return 0 Success, else error (such as BAD_FUNC_ARG or BUFFER_E). - - \param hash_type A hash type from the “enum wc_HashType” + + \param hash_type A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”. \param data Pointer to buffer containing the data to hash. \param data_len Length of the data buffer. \param hash Pointer to buffer used to output the final hash to. \param hash_len Length of the hash buffer. - + _Example_ \code enum wc_HashType hash_type = WC_HASH_TYPE_SHA256; @@ -78,7 +78,7 @@ WOLFSSL_API int wc_HashGetDigestSize(enum wc_HashType hash_type); } } \endcode - + \sa wc_HashGetDigestSize */ WOLFSSL_API int wc_Hash(enum wc_HashType hash_type, @@ -87,14 +87,14 @@ WOLFSSL_API int wc_Hash(enum wc_HashType hash_type, /*! \ingroup MD5 - - \brief Convenience function, handles all the hashing and places the + + \brief Convenience function, handles all the hashing and places the result into hash. - + \return 0 Returned upon successfully hashing the data. - \return Memory_E memory error, unable to allocate memory. This is only + \return Memory_E memory error, unable to allocate memory. This is only possible with the small stack option enabled. - + \param data the data to hash \param len the length of data \param hash Byte array to hold hash value. @@ -105,13 +105,13 @@ WOLFSSL_API int wc_Hash(enum wc_HashType hash_type, word32 data_len; byte* hash; int ret; - ... + ... ret = wc_Md5Hash(data, data_len, hash); if (ret != 0) { // Md5 Hash Failure Case. } \endcode - + \sa wc_Md5Hash \sa wc_Md5Final \sa wc_InitMd5 @@ -120,23 +120,23 @@ WOLFSSL_API int wc_Md5Hash(const byte* data, word32 len, byte* hash); /*! \ingroup SHA - - \brief Convenience function, handles all the hashing and places the + + \brief Convenience function, handles all the hashing and places the result into hash. - + \return 0 Returned upon successfully …. - \return Memory_E memory error, unable to allocate memory. This is only + \return Memory_E memory error, unable to allocate memory. This is only possible with the small stack option enabled. - + \param data the data to hash \param len the length of data \param hash Byte array to hold hash value. - + _Example_ \code none \endcode - + \sa wc_ShaHash \sa wc_ShaFinal \sa wc_InitSha @@ -145,23 +145,23 @@ WOLFSSL_API int wc_ShaHash(const byte*, word32, byte*); /*! \ingroup SHA - - \brief Convenience function, handles all the hashing and places the + + \brief Convenience function, handles all the hashing and places the result into hash. - + \return 0 Returned upon successfully … - \return Memory_E memory error, unable to allocate memory. This is only + \return Memory_E memory error, unable to allocate memory. This is only possible with the small stack option enabled. - + \param data the data to hash \param len the length of data \param hash Byte array to hold hash value. - + _Example_ \code none \endcode - + \sa wc_Sha256Hash \sa wc_Sha256Final \sa wc_InitSha256 @@ -170,22 +170,22 @@ WOLFSSL_API int wc_Sha256Hash(const byte*, word32, byte*); /*! \ingroup SHA - - \brief Convenience function, handles all the hashing and places the + + \brief Convenience function, handles all the hashing and places the result into hash. - + \return 0 Success \return <0 Error - + \param data the data to hash \param len the length of data \param hash Byte array to hold hash value. - + _Example_ \code none \endcode - + \sa wc_InitSha224 \sa wc_Sha224Update \sa wc_Sha224Final @@ -194,14 +194,14 @@ WOLFSSL_API int wc_Sha224Hash(const byte*, word32, byte*); /*! \ingroup SHA - - \brief Convenience function, handles all the hashing and places the + + \brief Convenience function, handles all the hashing and places the result into hash. - + \return 0 Returned upon successfully hashing the inputted data - \return Memory_E memory error, unable to allocate memory. This is only + \return Memory_E memory error, unable to allocate memory. This is only possible with the small stack option enabled. - + \param data the data to hash \param len the length of data \param hash Byte array to hold hash value. @@ -210,7 +210,7 @@ WOLFSSL_API int wc_Sha224Hash(const byte*, word32, byte*); \code none \endcode - + \sa wc_Sha512Hash \sa wc_Sha512Final \sa wc_InitSha512 @@ -219,18 +219,18 @@ WOLFSSL_API int wc_Sha512Hash(const byte*, word32, byte*); /*! \ingroup SHA - - \brief Convenience function, handles all the hashing and places the + + \brief Convenience function, handles all the hashing and places the result into hash. - + \return 0 Returned upon successfully hashing the data - \return Memory_E memory error, unable to allocate memory. This is only + \return Memory_E memory error, unable to allocate memory. This is only possible with the small stack option enabled. \param data the data to hash \param len the length of data \param hash Byte array to hold hash value. - + _Example_ \code none diff --git a/doc/dox_comments/header_files/hc128.h b/doc/dox_comments/header_files/hc128.h index 3f0b06bc0..2e24cdba8 100644 --- a/doc/dox_comments/header_files/hc128.h +++ b/doc/dox_comments/header_files/hc128.h @@ -1,24 +1,24 @@ /*! \ingroup HC128 - - \brief This function encrypts or decrypts a message of any size from the - input buffer input, and stores the resulting plaintext/ciphertext in + + \brief This function encrypts or decrypts a message of any size from the + input buffer input, and stores the resulting plaintext/ciphertext in the output buffer output. - + \return 0 Returned upon successfully encrypting/decrypting the given input - \return MEMORY_E Returned if the input and output buffers are not aligned + \return MEMORY_E Returned if the input and output buffers are not aligned along a 4-byte boundary, and there is an error allocating memory - \return BAD_ALIGN_E Returned if the input or output buffers are not + \return BAD_ALIGN_E Returned if the input or output buffers are not aligned along a 4-byte boundary, and NO_WOLFSSL_ALLOC_ALIGN is defined - - \param ctx pointer to a HC-128 context object with an initialized key + + \param ctx pointer to a HC-128 context object with an initialized key to use for encryption or decryption \param output buffer in which to store the processed input - \param input buffer containing the plaintext to encrypt or the + \param input buffer containing the plaintext to encrypt or the ciphertext to decrypt - \param msglen length of the plaintext to encrypt or the ciphertext + \param msglen length of the plaintext to encrypt or the ciphertext to decrypt - + _Example_ \code HC128 enc; @@ -33,26 +33,26 @@ // error encrypting msg } \endcode - + \sa wc_Hc128_SetKey */ WOLFSSL_API int wc_Hc128_Process(HC128*, byte*, const byte*, word32); /*! \ingroup HC128 - - \brief This function initializes an HC128 context object by + + \brief This function initializes an HC128 context object by setting its key and iv. - - \return 0 Returned upon successfully setting the key and iv + + \return 0 Returned upon successfully setting the key and iv for the HC128 context object - + \param ctx pointer to an HC-128 context object to initialize - \param key pointer to the buffer containing the 16 byte key to + \param key pointer to the buffer containing the 16 byte key to use with encryption/decryption - \param iv pointer to the buffer containing the 16 byte iv (nonce) + \param iv pointer to the buffer containing the 16 byte iv (nonce) with which to initialize the HC128 object - + _Example_ \code HC128 enc; @@ -60,7 +60,7 @@ WOLFSSL_API int wc_Hc128_Process(HC128*, byte*, const byte*, word32); byte iv[] = { // initialize with iv }; wc_Hc128_SetKey(&enc, key, iv); \endcode - + \sa wc_Hc128_Process */ WOLFSSL_API int wc_Hc128_SetKey(HC128*, const byte* key, const byte* iv); diff --git a/doc/dox_comments/header_files/hmac.h b/doc/dox_comments/header_files/hmac.h index aaf1b3aec..fbc80ec00 100644 --- a/doc/dox_comments/header_files/hmac.h +++ b/doc/dox_comments/header_files/hmac.h @@ -1,25 +1,25 @@ /*! \ingroup HMAC - - \brief This function initializes an Hmac object, setting its + + \brief This function initializes an Hmac object, setting its encryption type, key and HMAC length. - + \return 0 Returned on successfully initializing the Hmac object - \return BAD_FUNC_ARG Returned if the input type is invalid. Valid options + \return BAD_FUNC_ARG Returned if the input type is invalid. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID - \return MEMORY_E Returned if there is an error allocating memory for the + \return MEMORY_E Returned if there is an error allocating memory for the structure to use for hashing - \return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation - and the key length specified is shorter than the minimum acceptable + \return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation + and the key length specified is shorter than the minimum acceptable FIPS standard - + \param hmac pointer to the Hmac object to initialize - \param type type specifying which encryption method the Hmac object + \param type type specifying which encryption method the Hmac object should use. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID - \param key pointer to a buffer containing the key with which to + \param key pointer to a buffer containing the key with which to initialize the Hmac object \param length length of the key - + _Example_ \code Hmac hmac; @@ -28,7 +28,7 @@ // error initializing Hmac object } \endcode - + \sa wc_HmacUpdate \sa wc_HmacFinal */ @@ -36,21 +36,21 @@ WOLFSSL_API int wc_HmacSetKey(Hmac*, int type, const byte* key, word32 keySz); /*! \ingroup HMAC - - \brief This function updates the message to authenticate using HMAC. - It should be called after the Hmac object has been initialized with - wc_HmacSetKey. This function may be called multiple times to update - the message to hash. After calling wc_HmacUpdate as desired, one should - call wc_HmacFinal to obtain the final authenticated message tag. - + + \brief This function updates the message to authenticate using HMAC. + It should be called after the Hmac object has been initialized with + wc_HmacSetKey. This function may be called multiple times to update + the message to hash. After calling wc_HmacUpdate as desired, one should + call wc_HmacFinal to obtain the final authenticated message tag. + \return 0 Returned on successfully updating the message to authenticate - \return MEMORY_E Returned if there is an error allocating memory for + \return MEMORY_E Returned if there is an error allocating memory for use with a hashing algorithm - + \param hmac pointer to the Hmac object for which to update the message \param msg pointer to the buffer containing the message to append \param length length of the message to append - + _Example_ \code Hmac hmac; @@ -64,7 +64,7 @@ WOLFSSL_API int wc_HmacSetKey(Hmac*, int type, const byte* key, word32 keySz); // error updating with second message } \endcode - + \sa wc_HmacSetKey \sa wc_HmacFinal */ @@ -72,18 +72,18 @@ WOLFSSL_API int wc_HmacUpdate(Hmac*, const byte*, word32); /*! \ingroup HMAC - + \brief This function computes the final hash of an Hmac object's message. - + \return 0 Returned on successfully computing the final hash - \return MEMORY_E Returned if there is an error allocating memory for + \return MEMORY_E Returned if there is an error allocating memory for use with a hashing algorithm - - \param hmac pointer to the Hmac object for which to calculate the + + \param hmac pointer to the Hmac object for which to calculate the final hash - \param hash pointer to the buffer in which to store the final hash. + \param hash pointer to the buffer in which to store the final hash. Should have room available as required by the hashing algorithm chosen - + _Example_ \code Hmac hmac; @@ -95,7 +95,7 @@ WOLFSSL_API int wc_HmacUpdate(Hmac*, const byte*, word32); // error computing hash } \endcode - + \sa wc_HmacSetKey \sa wc_HmacUpdate */ @@ -103,54 +103,54 @@ WOLFSSL_API int wc_HmacFinal(Hmac*, byte*); /*! \ingroup HMAC - - \brief This function returns the largest HMAC digest size available + + \brief This function returns the largest HMAC digest size available based on the configured cipher suites. - - \return Success Returns the largest HMAC digest size available based + + \return Success Returns the largest HMAC digest size available based on the configured cipher suites - + \param none No parameters. - + _Example_ \code int maxDigestSz = wolfSSL_GetHmacMaxSize(); \endcode - + \sa none */ WOLFSSL_API int wolfSSL_GetHmacMaxSize(void); /*! \ingroup HMAC - - \brief This function provides access to a HMAC Key Derivation Function - (HKDF). It utilizes HMAC to convert inKey, with an optional salt and - optional info into a derived key, which it stores in out. The hash type + + \brief This function provides access to a HMAC Key Derivation Function + (HKDF). It utilizes HMAC to convert inKey, with an optional salt and + optional info into a derived key, which it stores in out. The hash type defaults to MD5 if 0 or NULL is given. - + \return 0 Returned upon successfully generating a key with the given inputs - \return BAD_FUNC_ARG Returned if an invalid hash type is given as + \return BAD_FUNC_ARG Returned if an invalid hash type is given as argument. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID \return MEMORY_E Returned if there is an error allocating memory - \return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation - and the key length specified is shorter than the minimum acceptable FIPS + \return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation + and the key length specified is shorter than the minimum acceptable FIPS standard - - \param type hash type to use for the HKDF. Valid types are: MD5, SHA, + + \param type hash type to use for the HKDF. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID \param inKey pointer to the buffer containing the key to use for KDF \param inKeySz length of the input key - \param salt pointer to a buffer containing an optional salt. Use NULL + \param salt pointer to a buffer containing an optional salt. Use NULL instead if not using a salt \param saltSz length of the salt. Use 0 if not using a salt - \param info pointer to a buffer containing optional additional info. + \param info pointer to a buffer containing optional additional info. Use NULL if not appending extra info \param infoSz length of additional info. Use 0 if not using additional info \param out pointer to the buffer in which to store the derived key - \param outSz space available in the output buffer to store the + \param outSz space available in the output buffer to store the generated key - + _Example_ \code byte key[] = { // initialize with key }; @@ -163,7 +163,7 @@ WOLFSSL_API int wolfSSL_GetHmacMaxSize(void); // error generating derived key } \endcode - + \sa wc_HmacSetKey */ WOLFSSL_API int wc_HKDF(int type, const byte* inKey, word32 inKeySz, diff --git a/doc/dox_comments/header_files/idea.h b/doc/dox_comments/header_files/idea.h index c583cc6ff..47eb750b7 100644 --- a/doc/dox_comments/header_files/idea.h +++ b/doc/dox_comments/header_files/idea.h @@ -1,12 +1,12 @@ /*! \ingroup IDEA - + \brief Generate the 52, 16-bit key sub-blocks from the 128 key. - + \return 0 Success - \return BAD_FUNC_ARG Returns if idea or key is null, keySz is not equal to + \return BAD_FUNC_ARG Returns if idea or key is null, keySz is not equal to IDEA_KEY_SIZE, or dir is not IDEA_ENCRYPTION or IDEA_DECRYPTION. - + \param idea Pointer to Idea structure. \param key Pointer to key in memory. \param keySz Size of key. @@ -23,7 +23,7 @@ // There was an error } \endcode - + \sa wc_IdeaSetIV */ WOLFSSL_API int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz, @@ -31,7 +31,7 @@ WOLFSSL_API int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz, /*! \ingroup IDEA - + \brief Sets the IV in an Idea key structure. \return 0 Success @@ -39,7 +39,7 @@ WOLFSSL_API int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz, \param idea Pointer to idea key structure. \param iv The IV value to set, can be null. - + _Example_ \code Idea idea; @@ -52,19 +52,19 @@ WOLFSSL_API int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz, // Some error occured } \endcode - + \sa wc_IdeaSetKey */ WOLFSSL_API int wc_IdeaSetIV(Idea *idea, const byte* iv); /*! \ingroup IDEA - + \brief Encryption or decryption for a block (64 bits). - + \return 0 upon success. \return <0 an error occured - + \param idea Pointer to idea key structure. \param out Pointer to destination. \param in Pointer to input data to encrypt or decrypt. @@ -82,7 +82,7 @@ WOLFSSL_API int wc_IdeaSetIV(Idea *idea, const byte* iv); // There was an error } \endcode - + \sa wc_IdeaSetKey \sa wc_IdeaSetIV \sa wc_IdeaCbcEncrypt @@ -92,9 +92,9 @@ WOLFSSL_API int wc_IdeaCipher(Idea *idea, byte* out, const byte* in); /*! \ingroup IDEA - + \brief Encrypt data using IDEA CBC mode. - + \return 0 Success \return BAD_FUNC_ARG Returns if any arguments are null. @@ -102,7 +102,7 @@ WOLFSSL_API int wc_IdeaCipher(Idea *idea, byte* out, const byte* in); \param out Pointer to destination for encryption. \param in Pointer to input for encryption. \param len length of input. - + _Example_ \code Idea idea; @@ -118,7 +118,7 @@ WOLFSSL_API int wc_IdeaCipher(Idea *idea, byte* out, const byte* in); // Some error occured } \endcode - + \sa wc_IdeaCbcDecrypt \sa wc_IdeaCipher \sa wc_IdeaSetKey @@ -128,17 +128,17 @@ WOLFSSL_API int wc_IdeaCbcEncrypt(Idea *idea, byte* out, /*! \ingroup IDEA - + \brief Decrypt data using IDEA CBC mode. \return 0 Success \return BAD_FUNC_ARG Returns if any arguments are null. - + \param idea Pointer to Idea key structure. \param out Pointer to destination for encryption. \param in Pointer to input for encryption. \param len length of input. - + _Example_ \code Idea idea; @@ -154,7 +154,7 @@ WOLFSSL_API int wc_IdeaCbcEncrypt(Idea *idea, byte* out, // Some error occured } \endcode - + \sa wc_IdeaCbcEncrypt \sa wc_IdeaCipher \sa wc_IdeaSetKey diff --git a/doc/dox_comments/header_files/logging.h b/doc/dox_comments/header_files/logging.h index ae5bfea11..8520a3687 100644 --- a/doc/dox_comments/header_files/logging.h +++ b/doc/dox_comments/header_files/logging.h @@ -1,18 +1,18 @@ /*! \ingroup Logging - - \brief This function registers a logging callback that will be used to - handle the wolfSSL log message. By default, if the system supports it - fprintf() to stderr is used but by using this function anything + + \brief This function registers a logging callback that will be used to + handle the wolfSSL log message. By default, if the system supports it + fprintf() to stderr is used but by using this function anything can be done by the user. - + \return Success If successful this function will return 0. - \return BAD_FUNC_ARG is the error that will be returned if a function + \return BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided. - - \param log_function function to register as a logging callback. + + \param log_function function to register as a logging callback. Function signature must follow the above prototype. - + _Example_ \code int ret = 0; @@ -28,7 +28,7 @@ // custom logging function } \endcode - + \sa wolfSSL_Debugging_ON \sa wolfSSL_Debugging_OFF */ @@ -37,21 +37,21 @@ WOLFSSL_API int wolfSSL_SetLoggingCb(wolfSSL_Logging_cb log_function); /*! \ingroup Debug - \brief If logging has been enabled at build time this function turns on - logging at runtime. To enable logging at build time use --enable-debug + \brief If logging has been enabled at build time this function turns on + logging at runtime. To enable logging at build time use --enable-debug or define DEBUG_WOLFSSL. - + \return 0 upon success. - \return NOT_COMPILED_IN is the error that will be returned if logging + \return NOT_COMPILED_IN is the error that will be returned if logging isn’t enabled for this build. - + \param none No parameters. - + _Example_ \code wolfSSL_Debugging_ON(); \endcode - + \sa wolfSSL_Debugging_OFF \sa wolfSSL_SetLoggingCb */ @@ -60,18 +60,18 @@ WOLFSSL_API int wolfSSL_Debugging_ON(void); /*! \ingroup Debug - \brief This function turns off runtime logging messages. If they’re + \brief This function turns off runtime logging messages. If they’re already off, no action is taken. - + \return none No returns. - + \param none No parameters. - + _Example_ \code wolfSSL_Debugging_OFF(); \endcode - + \sa wolfSSL_Debugging_ON \sa wolfSSL_SetLoggingCb */ diff --git a/doc/dox_comments/header_files/md2.h b/doc/dox_comments/header_files/md2.h index e09d8ca27..62e9a259c 100644 --- a/doc/dox_comments/header_files/md2.h +++ b/doc/dox_comments/header_files/md2.h @@ -1,13 +1,13 @@ /*! \ingroup MD2 - - \brief This function initializes md2. This is automatically + + \brief This function initializes md2. This is automatically called by wc_Md2Hash. - + \return 0 Returned upon successfully initializing - + \param md2 pointer to the md2 structure to use for encryption - + _Example_ \code md2 md2[1]; @@ -19,7 +19,7 @@ wc_Md2Final(md2, hash); } \endcode - + \sa wc_Md2Hash \sa wc_Md2Update \sa wc_Md2Final @@ -28,12 +28,12 @@ WOLFSSL_API void wc_InitMd2(Md2*); /*! \ingroup MD2 - - \brief Can be called to continually hash the provided byte + + \brief Can be called to continually hash the provided byte array of length len. - + \return 0 Returned upon successfully adding the data to the digest. - + \param md2 pointer to the md2 structure to use for encryption \param data the data to be hashed \param len length of data to be hashed @@ -52,7 +52,7 @@ WOLFSSL_API void wc_InitMd2(Md2*); wc_Md2Final(md2, hash); } \endcode - + \sa wc_Md2Hash \sa wc_Md2Final \sa wc_InitMd2 @@ -61,9 +61,9 @@ WOLFSSL_API void wc_Md2Update(Md2*, const byte*, word32); /*! \ingroup MD2 - + \brief Finalizes hashing of data. Result is placed into hash. - + \return 0 Returned upon successfully finalizing. \param md2 pointer to the md2 structure to use for encryption @@ -83,7 +83,7 @@ WOLFSSL_API void wc_Md2Update(Md2*, const byte*, word32); wc_Md2Final(md2, hash); } \endcode - + \sa wc_Md2Hash \sa wc_Md2Final \sa wc_InitMd2 @@ -92,14 +92,14 @@ WOLFSSL_API void wc_Md2Final(Md2*, byte*); /*! \ingroup MD2 - - \brief Convenience function, handles all the hashing and places + + \brief Convenience function, handles all the hashing and places the result into hash. - + \return 0 Returned upon successfully hashing the data. - \return Memory_E memory error, unable to allocate memory. This is only + \return Memory_E memory error, unable to allocate memory. This is only possible with the small stack option enabled. - + \param data the data to hash \param len the length of data \param hash Byte array to hold hash value. @@ -108,7 +108,7 @@ WOLFSSL_API void wc_Md2Final(Md2*, byte*); \code none \endcode - + \sa wc_Md2Hash \sa wc_Md2Final \sa wc_InitMd2 diff --git a/doc/dox_comments/header_files/md4.h b/doc/dox_comments/header_files/md4.h index 3696bdd19..252a1a778 100644 --- a/doc/dox_comments/header_files/md4.h +++ b/doc/dox_comments/header_files/md4.h @@ -1,13 +1,13 @@ /*! \ingroup MD4 - - \brief This function initializes md4. This is automatically + + \brief This function initializes md4. This is automatically called by wc_Md4Hash. - + \return 0 Returned upon successfully initializing - + \param md4 pointer to the md4 structure to use for encryption - + _Example_ \code md4 md4[1]; @@ -19,7 +19,7 @@ wc_Md4Final(md4, hash); } \endcode - + \sa wc_Md4Hash \sa wc_Md4Update \sa wc_Md4Final @@ -28,16 +28,16 @@ WOLFSSL_API void wc_InitMd4(Md4*); /*! \ingroup MD4 - - \brief Can be called to continually hash the provided byte array + + \brief Can be called to continually hash the provided byte array of length len. - + \return 0 Returned upon successfully adding the data to the digest. - + \param md4 pointer to the md4 structure to use for encryption \param data the data to be hashed \param len length of data to be hashed - + _Example_ \code md4 md4[1]; @@ -61,11 +61,11 @@ WOLFSSL_API void wc_Md4Update(Md4*, const byte*, word32); /*! \ingroup MD4 - + \brief Finalizes hashing of data. Result is placed into hash. - + \return 0 Returned upon successfully finalizing. - + \param md4 pointer to the md4 structure to use for encryption \param hash Byte array to hold hash value. diff --git a/doc/dox_comments/header_files/md5.h b/doc/dox_comments/header_files/md5.h index 40bb71366..427c7c9b0 100644 --- a/doc/dox_comments/header_files/md5.h +++ b/doc/dox_comments/header_files/md5.h @@ -1,15 +1,15 @@ /*! \ingroup MD5 - - \brief This function initializes md5. This is automatically + + \brief This function initializes md5. This is automatically called by wc_Md5Hash. - + \return 0 Returned upon successfully initializing. - \return BAD_FUNC_ARG Returned if the Md5 structure is passed + \return BAD_FUNC_ARG Returned if the Md5 structure is passed as a NULL value. - + \param md5 pointer to the md5 structure to use for encryption - + _Example_ \code Md5 md5; @@ -28,7 +28,7 @@ } } \endcode - + \sa wc_Md5Hash \sa wc_Md5Update \sa wc_Md5Final @@ -37,19 +37,19 @@ WOLFSSL_API int wc_InitMd5(wc_Md5*); /*! \ingroup MD5 - - \brief Can be called to continually hash the provided byte array of + + \brief Can be called to continually hash the provided byte array of length len. - + \return 0 Returned upon successfully adding the data to the digest. - \return BAD_FUNC_ARG Returned if the Md5 structure is NULL or if - data is NULL and len is greater than zero. The function should + \return BAD_FUNC_ARG Returned if the Md5 structure is NULL or if + data is NULL and len is greater than zero. The function should not return an error if the data parameter is NULL and len is zero. \param md5 pointer to the md5 structure to use for encryption \param data the data to be hashed \param len length of data to be hashed - + _Example_ \code Md5 md5; @@ -70,7 +70,7 @@ WOLFSSL_API int wc_InitMd5(wc_Md5*); } } \endcode - + \sa wc_Md5Hash \sa wc_Md5Final \sa wc_InitMd5 @@ -79,18 +79,18 @@ WOLFSSL_API int wc_Md5Update(wc_Md5*, const byte*, word32); /*! \ingroup MD5 - - \brief Finalizes hashing of data. Result is placed into hash. Md5 - Struct is reset. Note: This function will also return the result + + \brief Finalizes hashing of data. Result is placed into hash. Md5 + Struct is reset. Note: This function will also return the result of calling IntelQaSymMd5() in the case that HAVE_INTEL_QA is defined. - + \return 0 Returned upon successfully finalizing. - \return BAD_FUNC_ARG Returned if the Md5 structure or hash pointer + \return BAD_FUNC_ARG Returned if the Md5 structure or hash pointer is passed in NULL. - + \param md5 pointer to the md5 structure to use for encryption \param hash Byte array to hold hash value. - + _Example_ \code md5 md5[1]; @@ -111,7 +111,7 @@ WOLFSSL_API int wc_Md5Update(wc_Md5*, const byte*, word32); } } \endcode - + \sa wc_Md5Hash \sa wc_InitMd5 \sa wc_Md5GetHash @@ -120,12 +120,12 @@ WOLFSSL_API int wc_Md5Final(wc_Md5*, byte*); /*! \ingroup MD5 - - \brief Resets the Md5 structure. Note: this is only supported if + + \brief Resets the Md5 structure. Note: this is only supported if you have WOLFSSL_TI_HASH defined. \return none No returns. - + \param md5 Pointer to the Md5 structure to be reset. _Example_ @@ -143,7 +143,7 @@ WOLFSSL_API int wc_Md5Final(wc_Md5*, byte*); wc_Md5Free(&md5); } \endcode - + \sa wc_InitMd5 \sa wc_Md5Update \sa wc_Md5Final @@ -152,15 +152,15 @@ WOLFSSL_API void wc_Md5Free(wc_Md5*); /*! \ingroup MD5 - - \brief Gets hash data. Result is placed into hash. Md5 struct + + \brief Gets hash data. Result is placed into hash. Md5 struct is not reset. - + \return none No returns - + \param md5 pointer to the md5 structure to use for encryption. \param hash Byte array to hold hash value. - + _Example_ \code md5 md5[1]; @@ -172,7 +172,7 @@ WOLFSSL_API void wc_Md5Free(wc_Md5*); wc_Md5GetHash(md5, hash); } \endcode - + \sa wc_Md5Hash \sa wc_Md5Final \sa wc_InitMd5 diff --git a/doc/dox_comments/header_files/memory.h b/doc/dox_comments/header_files/memory.h index 5833cb2d5..f94872516 100644 --- a/doc/dox_comments/header_files/memory.h +++ b/doc/dox_comments/header_files/memory.h @@ -1,23 +1,23 @@ /*! \ingroup Memory - - \brief This function calls the custom malloc function, if one has been - defined, or simply calls the default C malloc function if no custom - function exists. It is not called directly by wolfSSL, but instead - generally called by using XMALLOC, which may be replaced by + + \brief This function calls the custom malloc function, if one has been + defined, or simply calls the default C malloc function if no custom + function exists. It is not called directly by wolfSSL, but instead + generally called by using XMALLOC, which may be replaced by wolfSSL_Malloc during preprocessing. - - \return Success On successfully allocating the desired memory, + + \return Success On successfully allocating the desired memory, returns a void* to that location \return NULL Returned when there is a failure to allocate memory - + \param size size, in bytes, of the memory to allocate - + _Example_ \code int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10); \endcode - + \sa wolfSSL_Free \sa wolfSSL_Realloc \sa XMALLOC @@ -28,17 +28,17 @@ WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type, const char* /*! \ingroup Memory - - \brief This function calls a custom free function, if one has been - defined, or simply calls the default C free function if no custom - function exists. It is not called directly by wolfSSL, but instead - generally called by using XFREE, which may be replaced by wolfSSL_Free + + \brief This function calls a custom free function, if one has been + defined, or simply calls the default C free function if no custom + function exists. It is not called directly by wolfSSL, but instead + generally called by using XFREE, which may be replaced by wolfSSL_Free during preprocessing. - + \return none No returns. - + \param ptr pointer to the memory to free - + _Example_ \code int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10); @@ -59,17 +59,17 @@ WOLFSSL_API void wolfSSL_Free(void *ptr, void* heap, int type, const char* func /*! \ingroup Memory - - \brief This function calls a custom realloc function, if one has been - defined, or simply calls the default C realloc function if no custom - function exists. It is not called directly by wolfSSL, but instead - generally called by using XREALLOC, which may be replaced by + + \brief This function calls a custom realloc function, if one has been + defined, or simply calls the default C realloc function if no custom + function exists. It is not called directly by wolfSSL, but instead + generally called by using XREALLOC, which may be replaced by wolfSSL_Realloc during preprocessing. - - \return Success On successfully reallocating the desired memory, + + \return Success On successfully reallocating the desired memory, returns a void* to that location \return NULL Returned when there is a failure to reallocate memory - + \param ptr pointer to the memory to the memory to reallocate \param size desired size after reallocation @@ -78,7 +78,7 @@ WOLFSSL_API void wolfSSL_Free(void *ptr, void* heap, int type, const char* func int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10); int* twentyInts = (int*)realloc(tenInts, sizeof(tenInts)*2); \endcode - + \sa wolfSSL_Malloc \sa wolfSSL_Free \sa XMALLOC @@ -89,20 +89,20 @@ WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type, /*! \ingroup Memory - - \brief This function is similar to malloc(), but calls the memory - allocation function which wolfSSL has been configured to use. By default, - wolfSSL uses malloc(). This can be changed using the wolfSSL memory + + \brief This function is similar to malloc(), but calls the memory + allocation function which wolfSSL has been configured to use. By default, + wolfSSL uses malloc(). This can be changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators(). - - \return pointer If successful, this function returns a pointer to + + \return pointer If successful, this function returns a pointer to allocated memory. \return error If there is an error, NULL will be returned. - \return other Specific return values may be dependent on the underlying + \return other Specific return values may be dependent on the underlying memory allocation function being used (if not using the default malloc()). - + \param size number of bytes to allocate. - + _Example_ \code char* buffer; @@ -111,7 +111,7 @@ WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type, // failed to allocate memory } \endcode - + \sa wolfSSL_Free \sa wolfSSL_Realloc \sa wolfSSL_SetAllocators @@ -120,23 +120,23 @@ WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type); /*! \ingroup Memory - - \brief This function is similar to realloc(), but calls the memory - re-allocation function which wolfSSL has been configured to use. - By default, wolfSSL uses realloc(). This can be changed using the + + \brief This function is similar to realloc(), but calls the memory + re-allocation function which wolfSSL has been configured to use. + By default, wolfSSL uses realloc(). This can be changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators(). - - \return pointer If successful, this function returns a pointer to - re-allocated memory. This may be the same pointer as ptr, or a + + \return pointer If successful, this function returns a pointer to + re-allocated memory. This may be the same pointer as ptr, or a new pointer location. \return Null If there is an error, NULL will be returned. - \return other Specific return values may be dependent on the - underlying memory re-allocation function being used + \return other Specific return values may be dependent on the + underlying memory re-allocation function being used (if not using the default realloc()). - + \param ptr pointer to the previously-allocated memory, to be reallocated. \param size number of bytes to allocate. - + _Example_ \code char* buffer; @@ -146,7 +146,7 @@ WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type); // failed to re-allocate memory } \endcode - + \sa wolfSSL_Free \sa wolfSSL_Malloc \sa wolfSSL_SetAllocators @@ -155,23 +155,23 @@ WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type); /*! \ingroup Memory - - \brief This function is similar to free(), but calls the memory free - function which wolfSSL has been configured to use. By default, wolfSSL - uses free(). This can be changed using the wolfSSL memory abstraction + + \brief This function is similar to free(), but calls the memory free + function which wolfSSL has been configured to use. By default, wolfSSL + uses free(). This can be changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators(). - + \return none No returns. - + \param ptr pointer to the memory to be freed. - + _Example_ \code char* buffer; ... wolfSSL_Free(buffer); \endcode - + \sa wolfSSL_Alloc \sa wolfSSL_Realloc \sa wolfSSL_SetAllocators @@ -180,23 +180,23 @@ WOLFSSL_API void wolfSSL_Free(void *ptr, const char* func, unsigned int line); /*! \ingroup Memory - - \brief This function registers the allocation functions used by wolfSSL. - By default, if the system supports it, malloc/free and realloc are used. - Using this function allows the user at runtime to install their own + + \brief This function registers the allocation functions used by wolfSSL. + By default, if the system supports it, malloc/free and realloc are used. + Using this function allows the user at runtime to install their own memory handlers. - + \return Success If successful this function will return 0. - \return BAD_FUNC_ARG is the error that will be returned if a + \return BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided. - - \param malloc_function memory allocation function for wolfSSL to use. + + \param malloc_function memory allocation function for wolfSSL to use. Function signature must match wolfSSL_Malloc_cb prototype, above. - \param free_function memory free function for wolfSSL to use. Function + \param free_function memory free function for wolfSSL to use. Function signature must match wolfSSL_Free_cb prototype, above. - \param realloc_function memory re-allocation function for wolfSSL to use. + \param realloc_function memory re-allocation function for wolfSSL to use. Function signature must match wolfSSL_Realloc_cb prototype, above. - + _Example_ \code int ret = 0; @@ -226,7 +226,7 @@ WOLFSSL_API void wolfSSL_Free(void *ptr, const char* func, unsigned int line); // custom realloc function } \endcode - + \sa none */ WOLFSSL_API int wolfSSL_SetAllocators(wolfSSL_Malloc_cb, @@ -235,21 +235,21 @@ WOLFSSL_API int wolfSSL_SetAllocators(wolfSSL_Malloc_cb, /*! \ingroup Memory - - \brief This function is available when static memory feature is used - (--enable-staticmemory). It gives the optimum buffer size for memory - “buckets”. This allows for a way to compute buffer size so that no - extra unused memory is left at the end after it has been partitioned. - The returned value, if positive, is the computed buffer size to use. - - \return Success On successfully completing buffer size calculations a + + \brief This function is available when static memory feature is used + (--enable-staticmemory). It gives the optimum buffer size for memory + “buckets”. This allows for a way to compute buffer size so that no + extra unused memory is left at the end after it has been partitioned. + The returned value, if positive, is the computed buffer size to use. + + \return Success On successfully completing buffer size calculations a positive value is returned. This returned value is for optimum buffer size. \return Failure All negative values are considered to be error cases. - + \param buffer pointer to buffer \param size size of buffer \param type desired type of memory ie WOLFMEM_GENERAL or WOLFMEM_IO_POOL - + _Example_ \code byte buffer[1000]; @@ -257,11 +257,11 @@ WOLFSSL_API int wolfSSL_SetAllocators(wolfSSL_Malloc_cb, int optimum; optimum = wolfSSL_StaticBufferSz(buffer, size, WOLFMEM_GENERAL); if (optimum < 0) { //handle error case } - printf(“The optimum buffer size to make use of all memory is %d\n”, + printf(“The optimum buffer size to make use of all memory is %d\n”, optimum); ... \endcode - + \sa wolfSSL_Malloc \sa wolfSSL_Free */ @@ -269,31 +269,31 @@ WOLFSSL_API int wolfSSL_StaticBufferSz(byte* buffer, word32 sz, int flag); /*! \ingroup Memory - - \brief This function is available when static memory feature is used - (--enable-staticmemory). It gives the size of padding needed for each - partition of memory. This padding size will be the size needed to - contain a memory management structure along with any extra for + + \brief This function is available when static memory feature is used + (--enable-staticmemory). It gives the size of padding needed for each + partition of memory. This padding size will be the size needed to + contain a memory management structure along with any extra for memory alignment. - - \return On successfully memory padding calculation the return value will + + \return On successfully memory padding calculation the return value will be a positive value - \return All negative values are considered error cases. - + \return All negative values are considered error cases. + \param none No parameters. - + _Example_ \code int padding; padding = wolfSSL_MemoryPaddingSz(); if (padding < 0) { //handle error case } - printf(“The padding size needed for each \”bucket\” of memory is %d\n”, + printf(“The padding size needed for each \”bucket\” of memory is %d\n”, padding); - // calculation of buffer for IO POOL size is number of buckets + // calculation of buffer for IO POOL size is number of buckets // times (padding + WOLFMEM_IO_SZ) ... \endcode - + \sa wolfSSL_Malloc \sa wolfSSL_Free */ diff --git a/doc/dox_comments/header_files/pem.h b/doc/dox_comments/header_files/pem.h index 0b4519b51..44201adfe 100644 --- a/doc/dox_comments/header_files/pem.h +++ b/doc/dox_comments/header_files/pem.h @@ -1,12 +1,12 @@ /*! \ingroup openSSL - - \brief This function writes a key into a WOLFSSL_BIO structure + + \brief This function writes a key into a WOLFSSL_BIO structure in PEM format. - + \return SSL_SUCCESS upon success. \return SSL_FAILURE upon failure. - + \param bio WOLFSSL_BIO structure to get PEM buffer from. \param key key to convert to PEM format. \param cipher EVP cipher structure. @@ -14,7 +14,7 @@ \param len length of password. \param cb password callback. \param arg optional argument. - + _Example_ \code WOLFSSL_BIO* bio; @@ -24,7 +24,7 @@ ret = wolfSSL_PEM_write_bio_PrivateKey(bio, key, NULL, NULL, 0, NULL, NULL); //check ret value \endcode - + \sa wolfSSL_PEM_read_bio_X509_AUX */ WOLFSSL_API diff --git a/doc/dox_comments/header_files/pkcs7.h b/doc/dox_comments/header_files/pkcs7.h index 436506cc3..2ad33cd43 100644 --- a/doc/dox_comments/header_files/pkcs7.h +++ b/doc/dox_comments/header_files/pkcs7.h @@ -1,51 +1,51 @@ /*! \ingroup PKCS7 - - \brief This function initializes a PKCS7 structure with a DER-formatted - certificate. To initialize an empty PKCS7 structure, one can pass in a NULL - cert and 0 for certSz. - + + \brief This function initializes a PKCS7 structure with a DER-formatted + certificate. To initialize an empty PKCS7 structure, one can pass in a NULL + cert and 0 for certSz. + \return 0 Returned on successfully initializing the PKCS7 structure - \return MEMORY_E Returned if there is an error allocating memory + \return MEMORY_E Returned if there is an error allocating memory with XMALLOC \return ASN_PARSE_E Returned if there is an error parsing the cert header - \return ASN_OBJECT_ID_E Returned if there is an error parsing the + \return ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert - \return ASN_EXPECT_0_E Returned if there is a formatting error in the + \return ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file - \return ASN_BEFORE_DATE_E Returned if the date is before the certificate + \return ASN_BEFORE_DATE_E Returned if the date is before the certificate start date - \return ASN_AFTER_DATE_E Returned if the date is after the certificate + \return ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date - \return ASN_BITSTR_E Returned if there is an error parsing a bit string + \return ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate - \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU + \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU key from the certificate - \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC + \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate - \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown + \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id - \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not + \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate - \return BAD_FUNC_ARG Returned if there is an error processing the + \return BAD_FUNC_ARG Returned if there is an error processing the certificate extension - \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is + \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate - \return ASN_SIG_OID_E Returned if the signature encryption type is not + \return ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file - \return ASN_SIG_CONFIRM_E Returned if confirming the certification + \return ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails - \return ASN_NAME_INVALID_E Returned if the certificate’s name is not + \return ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints - \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify + \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity - \param pkcs7 pointer to the PKCS7 structure in which to + \param pkcs7 pointer to the PKCS7 structure in which to store the decoded cert - \param cert pointer to a buffer containing a DER formatted ASN.1 + \param cert pointer to a buffer containing a DER formatted ASN.1 certificate with which to initialize the PKCS7 structure \param certSz size of the certificate buffer - + _Example_ \code PKCS7 pkcs7; @@ -54,20 +54,20 @@ // error parsing certificate into pkcs7 format } \endcode - + \sa wc_PKCS7_Free */ WOLFSSL_API int wc_PKCS7_InitWithCert(PKCS7* pkcs7, byte* cert, word32 certSz); /*! \ingroup PKCS7 - + \brief This function releases any memory allocated by a PKCS7 initializer. - + \return none No returns. - + \param pkcs7 pointer to the PKCS7 structure to free - + _Example_ \code PKCS7 pkcs7; @@ -75,28 +75,28 @@ WOLFSSL_API int wc_PKCS7_InitWithCert(PKCS7* pkcs7, byte* cert, word32 certSz); wc_PKCS7_Free(pkcs7); \endcode - + \sa wc_PKCS7_InitWithCert */ WOLFSSL_API void wc_PKCS7_Free(PKCS7* pkcs7); /*! \ingroup PKCS7 - - \brief This function builds the PKCS7 data content type, encoding the + + \brief This function builds the PKCS7 data content type, encoding the PKCS7 structure into a buffer containing a parsable PKCS7 data packet. - - \return Success On successfully encoding the PKCS7 data into the buffer, - returns the index parsed up to in the PKCS7 structure. This index also + + \return Success On successfully encoding the PKCS7 data into the buffer, + returns the index parsed up to in the PKCS7 structure. This index also corresponds to the bytes written to the output buffer. - \return BUFFER_E Returned if the given buffer is not large enough to hold + \return BUFFER_E Returned if the given buffer is not large enough to hold the encoded certificate - + \param pkcs7 pointer to the PKCS7 structure to encode - \param output pointer to the buffer in which to store the encoded + \param output pointer to the buffer in which to store the encoded certificate \param outputSz size available in the output buffer - + _Example_ \code PKCS7 pkcs7; @@ -118,7 +118,7 @@ WOLFSSL_API void wc_PKCS7_Free(PKCS7* pkcs7); // error encoding into output buffer } \endcode - + \sa wc_PKCS7_InitWithCert */ WOLFSSL_API int wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output, @@ -126,46 +126,46 @@ WOLFSSL_API int wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output, /*! \ingroup PKCS7 - - \brief This function builds the PKCS7 signed data content type, encoding - the PKCS7 structure into a buffer containing a parsable PKCS7 + + \brief This function builds the PKCS7 signed data content type, encoding + the PKCS7 structure into a buffer containing a parsable PKCS7 signed data packet. - - \return Success On successfully encoding the PKCS7 data into the buffer, - returns the index parsed up to in the PKCS7 structure. This index also + + \return Success On successfully encoding the PKCS7 data into the buffer, + returns the index parsed up to in the PKCS7 structure. This index also corresponds to the bytes written to the output buffer. - \return BAD_FUNC_ARG Returned if the PKCS7 structure is missing one or + \return BAD_FUNC_ARG Returned if the PKCS7 structure is missing one or more required elements to generate a signed data packet \return MEMORY_E Returned if there is an error allocating memory \return PUBLIC_KEY_E Returned if there is an error parsing the public key - \return RSA_BUFFER_E Returned if buffer error, output too small or input + \return RSA_BUFFER_E Returned if buffer error, output too small or input too large - \return BUFFER_E Returned if the given buffer is not large enough to hold + \return BUFFER_E Returned if the given buffer is not large enough to hold the encoded certificate - \return MP_INIT_E may be returned if there is an error generating + \return MP_INIT_E may be returned if there is an error generating the signature - \return MP_READ_E may be returned if there is an error generating + \return MP_READ_E may be returned if there is an error generating the signature - \return MP_CMP_E may be returned if there is an error generating + \return MP_CMP_E may be returned if there is an error generating the signature - \return MP_INVMOD_E may be returned if there is an error generating + \return MP_INVMOD_E may be returned if there is an error generating the signature - \return MP_EXPTMOD_E may be returned if there is an error generating + \return MP_EXPTMOD_E may be returned if there is an error generating the signature - \return MP_MOD_E may be returned if there is an error generating + \return MP_MOD_E may be returned if there is an error generating the signature - \return MP_MUL_E may be returned if there is an error generating + \return MP_MUL_E may be returned if there is an error generating the signature - \return MP_ADD_E may be returned if there is an error generating + \return MP_ADD_E may be returned if there is an error generating the signature - \return MP_MULMOD_E may be returned if there is an error generating + \return MP_MULMOD_E may be returned if there is an error generating the signature - \return MP_TO_E may be returned if there is an error generating + \return MP_TO_E may be returned if there is an error generating the signature \return MP_MEM may be returned if there is an error generating the signature - + \param pkcs7 pointer to the PKCS7 structure to encode - \param output pointer to the buffer in which to store the + \param output pointer to the buffer in which to store the encoded certificate \param outputSz size available in the output buffer @@ -190,7 +190,7 @@ WOLFSSL_API int wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output, // error encoding into output buffer } \endcode - + \sa wc_PKCS7_InitWithCert \sa wc_PKCS7_VerifySignedData */ @@ -199,53 +199,53 @@ WOLFSSL_API int wc_PKCS7_EncodeSignedData(PKCS7* pkcs7, /*! \ingroup PKCS7 - - \brief This function takes in a transmitted PKCS7 signed data message, - extracts the certificate list and certificate revocation list, and then - verifies the signature. It stores the extracted content in the given + + \brief This function takes in a transmitted PKCS7 signed data message, + extracts the certificate list and certificate revocation list, and then + verifies the signature. It stores the extracted content in the given PKCS7 structure. - - \return 0 Returned on successfully extracting the information + + \return 0 Returned on successfully extracting the information from the message \return BAD_FUNC_ARG Returned if one of the input parameters is invalid - \return ASN_PARSE_E Returned if there is an error parsing from the + \return ASN_PARSE_E Returned if there is an error parsing from the given pkiMsg \return PKCS7_OID_E Returned if the given pkiMsg is not a signed data type \return ASN_VERSION_E Returned if the PKCS7 signer info is not version 1 \return MEMORY_E Returned if there is an error allocating memory \return PUBLIC_KEY_E Returned if there is an error parsing the public key - \return RSA_BUFFER_E Returned if buffer error, output too small or + \return RSA_BUFFER_E Returned if buffer error, output too small or input too large - \return BUFFER_E Returned if the given buffer is not large enough to + \return BUFFER_E Returned if the given buffer is not large enough to hold the encoded certificate - \return MP_INIT_E may be returned if there is an error generating + \return MP_INIT_E may be returned if there is an error generating the signature - \return MP_READ_E may be returned if there is an error generating + \return MP_READ_E may be returned if there is an error generating the signature - \return MP_CMP_E may be returned if there is an error generating + \return MP_CMP_E may be returned if there is an error generating the signature - \return MP_INVMOD_E may be returned if there is an error generating + \return MP_INVMOD_E may be returned if there is an error generating the signature - \return MP_EXPTMOD_E may be returned if there is an error generating + \return MP_EXPTMOD_E may be returned if there is an error generating the signature - \return MP_MOD_E may be returned if there is an error generating + \return MP_MOD_E may be returned if there is an error generating the signature - \return MP_MUL_E may be returned if there is an error generating + \return MP_MUL_E may be returned if there is an error generating the signature - \return MP_ADD_E may be returned if there is an error generating + \return MP_ADD_E may be returned if there is an error generating the signature - \return MP_MULMOD_E may be returned if there is an error generating + \return MP_MULMOD_E may be returned if there is an error generating the signature - \return MP_TO_E may be returned if there is an error generating + \return MP_TO_E may be returned if there is an error generating the signature \return MP_MEM may be returned if there is an error generating the signature - - \param pkcs7 pointer to the PKCS7 structure in which to store the parsed + + \param pkcs7 pointer to the PKCS7 structure in which to store the parsed certificates - \param pkiMsg pointer to the buffer containing the signed message to verify + \param pkiMsg pointer to the buffer containing the signed message to verify and decode \param pkiMsgSz size of the signed message - + _Example_ \code PKCS7 pkcs7; @@ -267,7 +267,7 @@ WOLFSSL_API int wc_PKCS7_EncodeSignedData(PKCS7* pkcs7, // error encoding into output buffer } \endcode - + \sa wc_PKCS7_InitWithCert \sa wc_PKCS7_EncodeSignedData */ @@ -276,30 +276,30 @@ WOLFSSL_API int wc_PKCS7_VerifySignedData(PKCS7* pkcs7, /*! \ingroup PKCS7 - - \brief This function builds the PKCS7 enveloped data content type, encoding - the PKCS7 structure into a buffer containing a parsable PKCS7 enveloped + + \brief This function builds the PKCS7 enveloped data content type, encoding + the PKCS7 structure into a buffer containing a parsable PKCS7 enveloped data packet. - - \return Success Returned on successfully encoding the message in enveloped + + \return Success Returned on successfully encoding the message in enveloped data format, returns the size written to the output buffer - \return BAD_FUNC_ARG: Returned if one of the input parameters is invalid, + \return BAD_FUNC_ARG: Returned if one of the input parameters is invalid, or if the PKCS7 structure is missing required elements - \return ALGO_ID_E Returned if the PKCS7 structure is using an unsupported - algorithm type. Currently, only DESb and DES3b are supported - \return BUFFER_E Returned if the given output buffer is too small to store + \return ALGO_ID_E Returned if the PKCS7 structure is using an unsupported + algorithm type. Currently, only DESb and DES3b are supported + \return BUFFER_E Returned if the given output buffer is too small to store the output data \return MEMORY_E Returned if there is an error allocating memory - \return RNG_FAILURE_E Returned if there is an error initializing the random + \return RNG_FAILURE_E Returned if there is an error initializing the random number generator for encryption - \return DRBG_FAILED Returned if there is an error generating numbers with + \return DRBG_FAILED Returned if there is an error generating numbers with the random number generator used for encryption - + \param pkcs7 pointer to the PKCS7 structure to encode - \param output pointer to the buffer in which to store the encoded + \param output pointer to the buffer in which to store the encoded certificate \param outputSz size available in the output buffer - + _Example_ \code PKCS7 pkcs7; @@ -321,7 +321,7 @@ WOLFSSL_API int wc_PKCS7_VerifySignedData(PKCS7* pkcs7, // error encoding into output buffer } \endcode - + \sa wc_PKCS7_InitWithCert \sa wc_PKCS7_DecodeEnvelopedData */ @@ -330,51 +330,51 @@ WOLFSSL_API int wc_PKCS7_EncodeEnvelopedData(PKCS7* pkcs7, /*! \ingroup PKCS7 - - \brief This function unwraps and decrypts a PKCS7 enveloped data content - type, decoding the message into output. It uses the private key of the + + \brief This function unwraps and decrypts a PKCS7 enveloped data content + type, decoding the message into output. It uses the private key of the PKCS7 object passed in to decrypt the message. - - \return On successfully extracting the information from the message, + + \return On successfully extracting the information from the message, returns the bytes written to output \return BAD_FUNC_ARG Returned if one of the input parameters is invalid - \return ASN_PARSE_E Returned if there is an error parsing from the + \return ASN_PARSE_E Returned if there is an error parsing from the given pkiMsg - \return PKCS7_OID_E Returned if the given pkiMsg is not an enveloped + \return PKCS7_OID_E Returned if the given pkiMsg is not an enveloped data type \return ASN_VERSION_E Returned if the PKCS7 signer info is not version 0 \return MEMORY_E Returned if there is an error allocating memory - \return ALGO_ID_E Returned if the PKCS7 structure is using an unsupported - algorithm type. Currently, only DESb and DES3b are supported for + \return ALGO_ID_E Returned if the PKCS7 structure is using an unsupported + algorithm type. Currently, only DESb and DES3b are supported for encryption, with RSAk for signature generation - \return PKCS7_RECIP_E Returned if there is no recipient found in the + \return PKCS7_RECIP_E Returned if there is no recipient found in the enveloped data that matches the recipient provided - \return RSA_BUFFER_E Returned if there is an error during RSA signature + \return RSA_BUFFER_E Returned if there is an error during RSA signature verification due to buffer error, output too small or input too large. - \return MP_INIT_E may be returned if there is an error during signature + \return MP_INIT_E may be returned if there is an error during signature verification - \return MP_READ_E may be returned if there is an error during signature + \return MP_READ_E may be returned if there is an error during signature verification - \return MP_CMP_E may be returned if there is an error during signature + \return MP_CMP_E may be returned if there is an error during signature verification - \return MP_INVMOD_E may be returned if there is an error during signature + \return MP_INVMOD_E may be returned if there is an error during signature verification - \return MP_EXPTMOD_E may be returned if there is an error during signature + \return MP_EXPTMOD_E may be returned if there is an error during signature verification - \return MP_MOD_E may be returned if there is an error during signature + \return MP_MOD_E may be returned if there is an error during signature verification - \return MP_MUL_E may be returned if there is an error during signature + \return MP_MUL_E may be returned if there is an error during signature verification - \return MP_ADD_E may be returned if there is an error during signature + \return MP_ADD_E may be returned if there is an error during signature verification - \return MP_MULMOD_E may be returned if there is an error during signature + \return MP_MULMOD_E may be returned if there is an error during signature verification - \return MP_TO_E may be returned if there is an error during signature + \return MP_TO_E may be returned if there is an error during signature verification - \return MP_MEM may be returned if there is an error during signature + \return MP_MEM may be returned if there is an error during signature verification - - \param pkcs7 pointer to the PKCS7 structure containing the private key with + + \param pkcs7 pointer to the PKCS7 structure containing the private key with which to decode the enveloped data package \param pkiMsg pointer to the buffer containing the enveloped data package \param pkiMsgSz size of the enveloped data package @@ -393,13 +393,13 @@ WOLFSSL_API int wc_PKCS7_EncodeEnvelopedData(PKCS7* pkcs7, pkcs7.privateKey = key; pkcs7.privateKeySz = keySz; - decodedSz = wc_PKCS7_DecodeEnvelopedData(&pkcs7, received, + decodedSz = wc_PKCS7_DecodeEnvelopedData(&pkcs7, received, sizeof(received),decoded, sizeof(decoded)); if ( decodedSz != 0 ) { // error decoding message } \endcode - + \sa wc_PKCS7_InitWithCert \sa wc_PKCS7_EncodeEnvelopedData */ diff --git a/doc/dox_comments/header_files/poly1305.h b/doc/dox_comments/header_files/poly1305.h index 1d0fc579e..155c655fa 100644 --- a/doc/dox_comments/header_files/poly1305.h +++ b/doc/dox_comments/header_files/poly1305.h @@ -1,15 +1,15 @@ /*! \ingroup Poly1305 - - \brief This function sets the key for a Poly1305 context structure, - initializing it for hashing. Note: A new key should be set after + + \brief This function sets the key for a Poly1305 context structure, + initializing it for hashing. Note: A new key should be set after generating a message hash with wc_Poly1305Final to ensure security. - - \return 0 Returned on successfully setting the key and initializing + + \return 0 Returned on successfully setting the key and initializing the Poly1305 structure - \return BAD_FUNC_ARG Returned if the given key is not 32 bytes long, + \return BAD_FUNC_ARG Returned if the given key is not 32 bytes long, or the Poly1305 context is NULL - + \param ctx pointer to a Poly1305 structure to initialize \param key pointer to the buffer containing the key to use for hashing \param keySz size of the key in the buffer. Should be 32 bytes @@ -20,7 +20,7 @@ byte key[] = { initialize with 32 byte key to use for hashing }; wc_Poly1305SetKey(&enc, key, sizeof(key)); \endcode - + \sa wc_Poly1305Update \sa wc_Poly1305Final */ @@ -29,16 +29,16 @@ WOLFSSL_API int wc_Poly1305SetKey(Poly1305* poly1305, const byte* key, /*! \ingroup Poly1305 - - \brief This function updates the message to hash with the + + \brief This function updates the message to hash with the Poly1305 structure. - + \return 0 Returned on successfully updating the message to hash \return BAD_FUNC_ARG Returned if the Poly1305 structure is NULL - \param ctx pointer to a Poly1305 structure for which to update + \param ctx pointer to a Poly1305 structure for which to update the message to hash - \param m pointer to the buffer containing the message which should + \param m pointer to the buffer containing the message which should be added to the hash \param bytes size of the message to hash @@ -54,7 +54,7 @@ WOLFSSL_API int wc_Poly1305SetKey(Poly1305* poly1305, const byte* key, // error updating message to hash } \endcode - + \sa wc_Poly1305SetKey \sa wc_Poly1305Final */ @@ -62,18 +62,18 @@ WOLFSSL_API int wc_Poly1305Update(Poly1305* poly1305, const byte*, word32); /*! \ingroup Poly1305 - - \brief This function calculates the hash of the input messages - and stores the result in mac. After this is called, the key + + \brief This function calculates the hash of the input messages + and stores the result in mac. After this is called, the key should be reset. - + \return 0 Returned on successfully computing the final MAC \return BAD_FUNC_ARG Returned if the Poly1305 structure is NULL - + \param ctx pointer to a Poly1305 structure with which to generate the MAC - \param mac pointer to the buffer in which to store the MAC. + \param mac pointer to the buffer in which to store the MAC. Should be POLY1305_DIGEST_SIZE (16 bytes) wide - + _Example_ \code Poly1305 enc; @@ -89,7 +89,7 @@ WOLFSSL_API int wc_Poly1305Update(Poly1305* poly1305, const byte*, word32); // error computing final MAC } \endcode - + \sa wc_Poly1305SetKey \sa wc_Poly1305Update */ @@ -97,40 +97,40 @@ WOLFSSL_API int wc_Poly1305Final(Poly1305* poly1305, byte* tag); /*! \ingroup Poly1305 - - \brief Takes in an initialized Poly1305 struct that has a key + + \brief Takes in an initialized Poly1305 struct that has a key loaded and creates a MAC (tag) using recent TLS AEAD padding scheme. - + \return 0 Success - \return BAD_FUNC_ARG Returned if ctx, input, or tag is null or if - additional is null and addSz is greater than 0 or if tagSz is less + \return BAD_FUNC_ARG Returned if ctx, input, or tag is null or if + additional is null and addSz is greater than 0 or if tagSz is less than WC_POLY1305_MAC_SZ. - + \param ctx Initialized Poly1305 struct to use \param additional Additional data to use \param addSz Size of additional buffer \param input Input buffer to create tag from \param sz Size of input buffer \param tag Buffer to hold created tag - \param tagSz Size of input tag buffer (must be at least + \param tagSz Size of input tag buffer (must be at least WC_POLY1305_MAC_SZ(16)) - + _Example_ \code Poly1305 ctx; byte key[] = { }; // initialize with 32 byte key to use for hashing - byte additional[] = { }; // initialize with additional data + byte additional[] = { }; // initialize with additional data byte msg[] = { }; // initialize with message byte tag[16]; wc_Poly1305SetKey(&ctx, key, sizeof(key)); - if(wc_Poly1305_MAC(&ctx, additional, sizeof(additional), (byte*)msg, + if(wc_Poly1305_MAC(&ctx, additional, sizeof(additional), (byte*)msg, sizeof(msg), tag, sizeof(tag)) != 0) { // Handle the error } \endcode - + \sa wc_Poly1305SetKey \sa wc_Poly1305Update \sa wcPoly1305Final diff --git a/doc/dox_comments/header_files/pwdbased.h b/doc/dox_comments/header_files/pwdbased.h index fa672194d..b0cef5ef9 100644 --- a/doc/dox_comments/header_files/pwdbased.h +++ b/doc/dox_comments/header_files/pwdbased.h @@ -1,45 +1,45 @@ /*! \ingroup Password - - \brief This function implements the Password Based Key Derivation - Function 1 (PBKDF1), converting an input password with a concatenated salt - into a more secure key, which it stores in output. It allows the user to + + \brief This function implements the Password Based Key Derivation + Function 1 (PBKDF1), converting an input password with a concatenated salt + into a more secure key, which it stores in output. It allows the user to select between SHA and MD5 as hash functions. - + \return 0 Returned on successfully deriving a key from the input password - \return BAD_FUNC_ARG Returned if there is an invalid hash type given - (valid type are: MD5 and SHA), iterations is less than 1, or the key + \return BAD_FUNC_ARG Returned if there is an invalid hash type given + (valid type are: MD5 and SHA), iterations is less than 1, or the key length (kLen) requested is greater than the hash length of the provided hash - \return MEMORY_E Returned if there is an error allocating memory for a + \return MEMORY_E Returned if there is an error allocating memory for a SHA or MD5 object - - \param output pointer to the buffer in which to store the generated key. + + \param output pointer to the buffer in which to store the generated key. Should be at least kLen long - \param passwd pointer to the buffer containing the password to use for + \param passwd pointer to the buffer containing the password to use for the key derivation \param pLen length of the password to use for key derivation - \param salt pointer to the buffer containing the salt to use for + \param salt pointer to the buffer containing the salt to use for key derivation \param sLen length of the salt \param iterations number of times to process the hash - \param kLen desired length of the derived key. Should not be longer + \param kLen desired length of the derived key. Should not be longer than the digest size of the hash chosen \param hashType the hashing algorithm to use. Valid choices are MD5 and SHA - + _Example_ \code int ret; byte key[MD5_DIGEST_SIZE]; - byte pass[] = { }; // initialize with password + byte pass[] = { }; // initialize with password byte salt[] = { }; // initialize with salt - ret = wc_PBKDF1(key, pass, sizeof(pass), salt, sizeof(salt), 1000, + ret = wc_PBKDF1(key, pass, sizeof(pass), salt, sizeof(salt), 1000, sizeof(key), MD5); if ( ret != 0 ) { // error deriving key from password } \endcode - + \sa wc_PBKDF2 \sa wc_PKCS12_PBKDF */ @@ -49,32 +49,32 @@ WOLFSSL_API int wc_PBKDF1(byte* output, const byte* passwd, int pLen, /*! \ingroup Password - - \brief This function implements the Password Based Key Derivation - Function 2 (PBKDF2), converting an input password with a concatenated - salt into a more secure key, which it stores in output. It allows the user - to select any of the supported HMAC hash functions, including: MD5, SHA, + + \brief This function implements the Password Based Key Derivation + Function 2 (PBKDF2), converting an input password with a concatenated + salt into a more secure key, which it stores in output. It allows the user + to select any of the supported HMAC hash functions, including: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B - + \return 0 Returned on successfully deriving a key from the input password - \return BAD_FUNC_ARG Returned if there is an invalid hash type given or + \return BAD_FUNC_ARG Returned if there is an invalid hash type given or iterations is less than 1 - \return MEMORY_E Returned if there is an allocating memory for + \return MEMORY_E Returned if there is an allocating memory for the HMAC object - \param output pointer to the buffer in which to store the generated key. + \param output pointer to the buffer in which to store the generated key. Should be kLen long - \param passwd pointer to the buffer containing the password to use for + \param passwd pointer to the buffer containing the password to use for the key derivation \param pLen length of the password to use for key derivation - \param salt pointer to the buffer containing the salt to use for + \param salt pointer to the buffer containing the salt to use for key derivation \param sLen length of the salt \param iterations number of times to process the hash \param kLen desired length of the derived key - \param hashType the hashing algorithm to use. Valid choices are: MD5, + \param hashType the hashing algorithm to use. Valid choices are: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B - + _Example_ \code int ret; @@ -82,13 +82,13 @@ WOLFSSL_API int wc_PBKDF1(byte* output, const byte* passwd, int pLen, byte pass[] = { }; // initialize with password byte salt[] = { }; // initialize with salt - ret = wc_PBKDF2(key, pass, sizeof(pass), salt, sizeof(salt), 2048, sizeof(key), + ret = wc_PBKDF2(key, pass, sizeof(pass), salt, sizeof(salt), 2048, sizeof(key), SHA512); if ( ret != 0 ) { // error deriving key from password } \endcode - + \sa wc_PBKDF1 \sa wc_PKCS12_PBKDF */ @@ -98,66 +98,66 @@ WOLFSSL_API int wc_PBKDF2(byte* output, const byte* passwd, int pLen, /*! \ingroup Password - - \brief This function implements the Password Based Key Derivation Function - (PBKDF) described in RFC 7292 Appendix B. This function converts an input - password with a concatenated salt into a more secure key, which it stores - in output. It allows the user to select any of the supported HMAC hash + + \brief This function implements the Password Based Key Derivation Function + (PBKDF) described in RFC 7292 Appendix B. This function converts an input + password with a concatenated salt into a more secure key, which it stores + in output. It allows the user to select any of the supported HMAC hash functions, including: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B. - + \return 0 Returned on successfully deriving a key from the input password - \return BAD_FUNC_ARG Returned if there is an invalid hash type given, - iterations is less than 1, or the key length (kLen) requested is greater + \return BAD_FUNC_ARG Returned if there is an invalid hash type given, + iterations is less than 1, or the key length (kLen) requested is greater than the hash length of the provided hash \return MEMORY_E Returned if there is an allocating memory \return MP_INIT_E may be returned if there is an error during key generation \return MP_READ_E may be returned if there is an error during key generation \return MP_CMP_E may be returned if there is an error during key generation - \return MP_INVMOD_E may be returned if there is an error during + \return MP_INVMOD_E may be returned if there is an error during key generation - \return MP_EXPTMOD_E may be returned if there is an error during + \return MP_EXPTMOD_E may be returned if there is an error during key generation \return MP_MOD_E may be returned if there is an error during key generation \return MP_MUL_E may be returned if there is an error during key generation \return MP_ADD_E may be returned if there is an error during key generation - \return MP_MULMOD_E may be returned if there is an error during + \return MP_MULMOD_E may be returned if there is an error during key generation \return MP_TO_E may be returned if there is an error during key generation \return MP_MEM may be returned if there is an error during key generation - - \param output pointer to the buffer in which to store the generated key. + + \param output pointer to the buffer in which to store the generated key. Should be kLen long - \param passwd pointer to the buffer containing the password to use for + \param passwd pointer to the buffer containing the password to use for the key derivation \param pLen length of the password to use for key derivation - \param salt pointer to the buffer containing the salt to use + \param salt pointer to the buffer containing the salt to use for key derivation \param sLen length of the salt \param iterations number of times to process the hash \param kLen desired length of the derived key - \param hashType the hashing algorithm to use. Valid choices are: MD5, + \param hashType the hashing algorithm to use. Valid choices are: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B - \param id this is a byte indetifier indicating the purpose of key - generation. It is used to diversify the key output, and should be - assigned as follows: ID=1: pseudorandom bits are to be used as key - material for performing encryption or decryption. ID=2: pseudorandom - bits are to be used an IV (Initial Value) for encryption or decryption. + \param id this is a byte indetifier indicating the purpose of key + generation. It is used to diversify the key output, and should be + assigned as follows: ID=1: pseudorandom bits are to be used as key + material for performing encryption or decryption. ID=2: pseudorandom + bits are to be used an IV (Initial Value) for encryption or decryption. ID=3: pseudorandom bits are to be used as an integrity key for MACing. - + _Example_ \code int ret; byte key[64]; - byte pass[] = { }; // initialize with password + byte pass[] = { }; // initialize with password byte salt[] = { }; // initialize with salt - ret = wc_PKCS512_PBKDF(key, pass, sizeof(pass), salt, sizeof(salt), 2048, + ret = wc_PKCS512_PBKDF(key, pass, sizeof(pass), salt, sizeof(salt), 2048, sizeof(key), SHA512, 1); if ( ret != 0 ) { // error deriving key from password } \endcode - + \sa wc_PBKDF1 \sa wc_PBKDF2 */ diff --git a/doc/dox_comments/header_files/rabbit.h b/doc/dox_comments/header_files/rabbit.h index 6e3daf9cb..eaba93c5e 100644 --- a/doc/dox_comments/header_files/rabbit.h +++ b/doc/dox_comments/header_files/rabbit.h @@ -1,23 +1,23 @@ /*! \ingroup Rabbit - - \brief This function encrypts or decrypts a message of any size, storing - the result in output. It requires that the Rabbit ctx structure be + + \brief This function encrypts or decrypts a message of any size, storing + the result in output. It requires that the Rabbit ctx structure be initialized with a key and an iv before encryption. \return 0 Returned on successfully encrypting/decrypting input - \return BAD_ALIGN_E Returned if the input message is not 4-byte aligned - but is required to be by XSTREAM_ALIGN, but NO_WOLFSSL_ALLOC_ALIGN is + \return BAD_ALIGN_E Returned if the input message is not 4-byte aligned + but is required to be by XSTREAM_ALIGN, but NO_WOLFSSL_ALLOC_ALIGN is defined - \return MEMORY_E Returned if there is an error allocating memory to + \return MEMORY_E Returned if there is an error allocating memory to align the message, if NO_WOLFSSL_ALLOC_ALIGN is not defined - + \param ctx pointer to the Rabbit structure to use for encryption/decryption - \param output pointer to the buffer in which to store the processed + \param output pointer to the buffer in which to store the processed message. Should be at least msglen long \param input pointer to the buffer containing the message to process \param msglen the length of the message to process - + _Example_ \code int ret; @@ -32,25 +32,25 @@ wc_RabbitProcess(enc, ciphertext, message, sizeof(message)); \endcode - + \sa wc_RabbitSetKey */ WOLFSSL_API int wc_RabbitProcess(Rabbit*, byte*, const byte*, word32); /*! \ingroup Rabbit - - \brief This function initializes a Rabbit context for use with + + \brief This function initializes a Rabbit context for use with encryption or decryption by setting its iv and key. - + \return 0 Returned on successfully setting the key and iv - + \param ctx pointer to the Rabbit structure to initialize - \param key pointer to the buffer containing the 16 byte key to + \param key pointer to the buffer containing the 16 byte key to use for encryption/decryption - \param iv pointer to the buffer containing the 8 byte iv with + \param iv pointer to the buffer containing the 8 byte iv with which to initialize the Rabbit structure - + _Example_ \code int ret; @@ -60,7 +60,7 @@ WOLFSSL_API int wc_RabbitProcess(Rabbit*, byte*, const byte*, word32); wc_RabbitSetKey(&enc, key, iv) \endcode - + \sa wc_RabbitProcess */ WOLFSSL_API int wc_RabbitSetKey(Rabbit*, const byte* key, const byte* iv); diff --git a/doc/dox_comments/header_files/random.h b/doc/dox_comments/header_files/random.h index fa60855cb..93ddb8416 100644 --- a/doc/dox_comments/header_files/random.h +++ b/doc/dox_comments/header_files/random.h @@ -1,16 +1,16 @@ /*! \ingroup Random - + \brief Init global Whitewood netRandom context - + \return 0 Success \return BAD_FUNC_ARG Either configFile is null or timeout is negative. \return RNG_FAILURE_E There was a failure initializing the rng. - + \param configFile Path to configuration file \param hmac_cb Optional to create HMAC callback. \param timeout A timeout duration. - + _Example_ \code char* config = "path/to/config/example.conf"; @@ -21,21 +21,21 @@ // Some error occured } \endcode - + \sa wc_FreeNetRandom */ WOLFSSL_API int wc_InitNetRandom(const char*, wnr_hmac_key, int); /*! \ingroup Random - + \brief Free global Whitewood netRandom context. - + \return 0 Success \return BAD_MUTEX_E Error locking mutex on wnr_mutex - + \param none No returns. - + _Example_ \code int ret = wc_FreeNetRandom(); @@ -44,40 +44,40 @@ WOLFSSL_API int wc_InitNetRandom(const char*, wnr_hmac_key, int); // Handle the error } \endcode - + \sa wc_InitNetRandom */ WOLFSSL_API int wc_FreeNetRandom(void); /*! \ingroup Random - - \brief Gets the seed (from OS) and key cipher for rng. rng->drbg - (deterministic random bit generator) allocated (should be deallocated + + \brief Gets the seed (from OS) and key cipher for rng. rng->drbg + (deterministic random bit generator) allocated (should be deallocated with wc_FreeRng). This is a blocking operation. - + \return 0 on success. \return MEMORY_E XMALLOC failed \return WINCRYPT_E wc_GenerateSeed: failed to acquire context \return CRYPTGEN_E wc_GenerateSeed: failed to get random - \return BAD_FUNC_ARG wc_RNG_GenerateBlock input is null or sz exceeds + \return BAD_FUNC_ARG wc_RNG_GenerateBlock input is null or sz exceeds MAX_REQUEST_LEN - \return DRBG_CONT_FIPS_E wc_RNG_GenerateBlock: Hash_gen returned + \return DRBG_CONT_FIPS_E wc_RNG_GenerateBlock: Hash_gen returned DRBG_CONT_FAILURE - \return RNG_FAILURE_E wc_RNG_GenerateBlock: Default error. rng’s + \return RNG_FAILURE_E wc_RNG_GenerateBlock: Default error. rng’s status originally not ok, or set to DRBG_FAILED - - \param rng random number generator to be initialized for use + + \param rng random number generator to be initialized for use with a seed and key cipher - + _Example_ \code RNG rng; int ret; - + #ifdef HAVE_CAVIUM ret = wc_InitRngCavium(&rng, CAVIUM_DEV_ID); - if (ret != 0){ + if (ret != 0){ printf(“RNG Nitrox init for device: %d failed”, CAVIUM_DEV_ID); return -1; } @@ -88,7 +88,7 @@ WOLFSSL_API int wc_FreeNetRandom(void); return -1; } \endcode - + \sa wc_InitRngCavium \sa wc_RNG_GenerateBlock \sa wc_RNG_GenerateByte @@ -99,20 +99,20 @@ WOLFSSL_API int wc_InitRng(WC_RNG*); /*! \ingroup Random - - \brief Copies a sz bytes of pseudorandom data to output. Will + + \brief Copies a sz bytes of pseudorandom data to output. Will reseed rng if needed (blocking). - + \return 0 on success \return BAD_FUNC_ARG an input is null or sz exceeds MAX_REQUEST_LEN \return DRBG_CONT_FIPS_E Hash_gen returned DRBG_CONT_FAILURE - \return RNG_FAILURE_E Default error. rng’s status originally not + \return RNG_FAILURE_E Default error. rng’s status originally not ok, or set to DRBG_FAILED - + \param rng random number generator initialized with wc_InitRng \param output buffer to which the block is copied \param sz size of output in bytes - + _Example_ \code RNG rng; @@ -123,13 +123,13 @@ WOLFSSL_API int wc_InitRng(WC_RNG*); if (ret != 0) { return -1; //init of rng failed! } - + ret = wc_RNG_GenerateBlock(&rng, block, sz); if (ret != 0) { return -1; //generating block failed! } \endcode - + \sa wc_InitRngCavium, wc_InitRng \sa wc_RNG_GenerateByte \sa wc_FreeRng @@ -139,19 +139,19 @@ WOLFSSL_API int wc_RNG_GenerateBlock(WC_RNG*, byte*, word32 sz); /*! \ingroup Random - - \brief Calls wc_RNG_GenerateBlock to copy a byte of pseudorandom + + \brief Calls wc_RNG_GenerateBlock to copy a byte of pseudorandom data to b. Will reseed rng if needed. - + \return 0 on success \return BAD_FUNC_ARG an input is null or sz exceeds MAX_REQUEST_LEN \return DRBG_CONT_FIPS_E Hash_gen returned DRBG_CONT_FAILURE - \return RNG_FAILURE_E Default error. rng’s status originally not + \return RNG_FAILURE_E Default error. rng’s status originally not ok, or set to DRBG_FAILED - + \param rng: random number generator initialized with wc_InitRng \param b one byte buffer to which the block is copied - + _Example_ \code RNG rng; @@ -168,7 +168,7 @@ WOLFSSL_API int wc_RNG_GenerateBlock(WC_RNG*, byte*, word32 sz); return -1; //generating block failed! } \endcode - + \sa wc_InitRngCavium \sa wc_InitRng \sa wc_RNG_GenerateBlock @@ -179,16 +179,16 @@ WOLFSSL_API int wc_RNG_GenerateByte(WC_RNG*, byte*); /*! \ingroup Random - - \brief Should be called when RNG no longer needed in order to securely + + \brief Should be called when RNG no longer needed in order to securely free drgb. Zeros and XFREEs rng-drbg. - + \return 0 on success \return BAD_FUNC_ARG rng or rng->drgb null \return RNG_FAILURE_E Failed to deallocated drbg - + \param rng random number generator initialized with wc_InitRng - + _Example_ \code RNG rng; @@ -198,38 +198,38 @@ WOLFSSL_API int wc_RNG_GenerateByte(WC_RNG*, byte*); } int ret = wc_FreeRng(&rng); - if (ret != 0) { + if (ret != 0) { return -1; //free of rng failed! } \endcode - + \sa wc_InitRngCavium \sa wc_InitRng \sa wc_RNG_GenerateBlock - \sa wc_RNG_GenerateByte, + \sa wc_RNG_GenerateByte, \sa wc_RNG_HealthTest */ WOLFSSL_API int wc_FreeRng(WC_RNG*); /*! \ingroup Random - + \brief Creates and tests functionality of drbg. - + \return 0 on success - \return BAD_FUNC_ARG entropyA and output must not be null. If reseed + \return BAD_FUNC_ARG entropyA and output must not be null. If reseed set entropyB must not be null \return -1 test failed - + \param int reseed: if set, will test reseed functionality \param entropyA: entropy to instantiate drgb with \param entropyASz: size of entropyA in bytes \param entropyB: If reseed set, drbg will be reseeded with entropyB \param entropyBSz: size of entropyB in bytes - \param output: initialized to random data seeded with entropyB if + \param output: initialized to random data seeded with entropyB if seedrandom is set, and entropyA otherwise \param outputSz: length of output in bytes - + _Example_ \code byte output[SHA256_DIGEST_SIZE * 4]; @@ -249,11 +249,11 @@ WOLFSSL_API int wc_FreeRng(WC_RNG*); ret = wc_RNG_HealthTest(1, test2EntropyA, sizeof(test2EntropyA), test2EntropyB, sizeof(test2EntropyB), output, sizeof(output)); - + if (XMEMCMP(test2Output, output, sizeof(output)) != 0) return -1; //compare to testvector failed \endcode - + \sa wc_InitRngCavium \sa wc_InitRng \sa wc_RNG_GenerateBlock diff --git a/doc/dox_comments/header_files/ripemd.h b/doc/dox_comments/header_files/ripemd.h index 342ab527c..045cfa90e 100644 --- a/doc/dox_comments/header_files/ripemd.h +++ b/doc/dox_comments/header_files/ripemd.h @@ -1,15 +1,15 @@ /*! \ingroup RIPEMD - - \brief This function initializes a ripemd structure by initializing + + \brief This function initializes a ripemd structure by initializing ripemd’s digest, buffer, loLen and hiLen. - - \return 0 returned on successful execution of the function. The RipeMd + + \return 0 returned on successful execution of the function. The RipeMd structure is initialized. \return BAD_FUNC_ARG returned if the RipeMd structure is NULL. - + \param ripemd pointer to the ripemd structure to initialize - + _Example_ \code RipeMd md; @@ -19,7 +19,7 @@ // Failure case. } \endcode - + \sa wc_RipeMdUpdate \sa wc_RipeMdFinal */ @@ -27,18 +27,18 @@ WOLFSSL_API int wc_InitRipeMd(RipeMd*); /*! \ingroup RIPEMD - - \brief This function generates the RipeMd digest of the data input and - stores the result in the ripemd->digest buffer. After running - wc_RipeMdUpdate, one should compare the generated ripemd->digest to a + + \brief This function generates the RipeMd digest of the data input and + stores the result in the ripemd->digest buffer. After running + wc_RipeMdUpdate, one should compare the generated ripemd->digest to a known authentication tag to verify the authenticity of a message. - + \return 0 Returned on successful execution of the function. - \return BAD_FUNC_ARG Returned if the RipeMd structure is NULL or if data - is NULL and len is not zero. This function should execute if data is NULL + \return BAD_FUNC_ARG Returned if the RipeMd structure is NULL or if data + is NULL and len is not zero. This function should execute if data is NULL and len is 0. - - \param ripemd: pointer to the ripemd structure to be initialized with + + \param ripemd: pointer to the ripemd structure to be initialized with wc_InitRipeMd \param data data to be hashed \param len sizeof data in bytes @@ -55,37 +55,37 @@ WOLFSSL_API int wc_InitRipeMd(RipeMd*); if (ret != 0) { // Failure case … \endcode - + \sa wc_InitRipeMd \sa wc_RipeMdFinal */ WOLFSSL_API int wc_RipeMdUpdate(RipeMd*, const byte*, word32); /*! - \ingroup RIPEMD - - \brief This function copies the computed digest into hash. If there is a - partial unhashed block, this method will pad the block with 0s, and - include that block’s round in the digest before copying to hash. State + \ingroup RIPEMD + + \brief This function copies the computed digest into hash. If there is a + partial unhashed block, this method will pad the block with 0s, and + include that block’s round in the digest before copying to hash. State of ripemd is reset. - - \return 0 Returned on successful execution of the function. The state of + + \return 0 Returned on successful execution of the function. The state of the RipeMd structure has been reset. - \return BAD_FUNC_ARG Returned if the RipeMd structure or hash parameters + \return BAD_FUNC_ARG Returned if the RipeMd structure or hash parameters are NULL. - - \param ripemd pointer to the ripemd structure to be initialized with - wc_InitRipeMd, and containing hashes from wc_RipeMdUpdate. State will + + \param ripemd pointer to the ripemd structure to be initialized with + wc_InitRipeMd, and containing hashes from wc_RipeMdUpdate. State will be reset \param hash buffer to copy digest to. Should be RIPEMD_DIGEST_SIZE bytes - + _Example_ \code RipeMd md; int ret; byte digest[RIPEMD_DIGEST_SIZE]; const byte* data; // The data to be hashed - ... + ... ret = wc_InitRipeMd(&md); if (ret == 0) { ret = wc_RipeMdUpdate(&md, plain, sizeof(plain)); @@ -97,7 +97,7 @@ WOLFSSL_API int wc_RipeMdUpdate(RipeMd*, const byte*, word32); // RipeMd Final Failure Case. }... \endcode - + \sa none */ WOLFSSL_API int wc_RipeMdFinal(RipeMd*, byte*); diff --git a/doc/dox_comments/header_files/rsa.h b/doc/dox_comments/header_files/rsa.h index 92d686a64..878dea9be 100644 --- a/doc/dox_comments/header_files/rsa.h +++ b/doc/dox_comments/header_files/rsa.h @@ -1,19 +1,19 @@ /*! \ingroup RSA - - \brief This function initializes a provided RsaKey struct. It also takes - in a heap identifier, for use with user defined memory overrides + + \brief This function initializes a provided RsaKey struct. It also takes + in a heap identifier, for use with user defined memory overrides (see XMALLOC, XFREE, XREALLOC). - - \return 0 Returned upon successfully initializing the RSA structure for + + \return 0 Returned upon successfully initializing the RSA structure for use with encryption and decryption \return BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL - + \param key pointer to the RsaKey structure to initialize - \param heap pointer to a heap identifier, for use with memory overrides, - allowing custom handling of memory allocation. This heap will be the + \param heap pointer to a heap identifier, for use with memory overrides, + allowing custom handling of memory allocation. This heap will be the default used when allocating memory for use with this RSA object - + _Example_ \code RsaKey enc; @@ -23,7 +23,7 @@ // error initializing RSA key } \endcode - + \sa wc_RsaInitCavium \sa wc_FreeRsaKey */ @@ -31,13 +31,13 @@ WOLFSSL_API int wc_InitRsaKey(RsaKey* key, void* heap); /*! \ingroup RSA - + \brief This function frees a provided RsaKey struct using mp_clear. - + \return 0 Returned upon successfully freeing the key - + \param key pointer to the RsaKey structure to free - + _Example_ \code RsaKey enc; @@ -46,61 +46,61 @@ WOLFSSL_API int wc_InitRsaKey(RsaKey* key, void* heap); wc_FreeRsaKey(&enc); \endcode - + \sa wc_InitRsaKey */ WOLFSSL_API int wc_FreeRsaKey(RsaKey* key); /*! \ingroup RSA - - \brief This function encrypts a message from in and stores the result - in out. It requires an initialized public key and a random number - generator. As a side effect, this function will return the bytes written + + \brief This function encrypts a message from in and stores the result + in out. It requires an initialized public key and a random number + generator. As a side effect, this function will return the bytes written to out in outLen. - - \return Success Upon successfully encrypting the input message, returns + + \return Success Upon successfully encrypting the input message, returns the number bytes written to out - \return -1 Returned if there is an error during RSA encryption and + \return -1 Returned if there is an error during RSA encryption and hardware acceleration via Cavium is enabled \return BAD_FUNC_ARG Returned if any of the input parameters are invalid - \return RSA_BUFFER_E Returned if the output buffer is too small to store + \return RSA_BUFFER_E Returned if the output buffer is too small to store the ciphertext - \return RNG_FAILURE_E Returned if there is an error generating a random + \return RNG_FAILURE_E Returned if there is an error generating a random block using the provided RNG structure - \return MP_INIT_E May be returned if there is an error in the math + \return MP_INIT_E May be returned if there is an error in the math library used while encrypting the message - \return MP_READ_E May be returned if there is an error in the math + \return MP_READ_E May be returned if there is an error in the math library used while encrypting the message - \return MP_CMP_E May be returned if there is an error in the math + \return MP_CMP_E May be returned if there is an error in the math library used while encrypting the message - \return MP_INVMOD_E May be returned if there is an error in the math + \return MP_INVMOD_E May be returned if there is an error in the math library used while encrypting the message - \return MP_EXPTMOD_E May be returned if there is an error in the math + \return MP_EXPTMOD_E May be returned if there is an error in the math library used while encrypting the message - \return MP_MOD_E May be returned if there is an error in the math + \return MP_MOD_E May be returned if there is an error in the math library used while encrypting the message - \return MP_MUL_E May be returned if there is an error in the math + \return MP_MUL_E May be returned if there is an error in the math library used while encrypting the message - \return MP_ADD_E May be returned if there is an error in the math + \return MP_ADD_E May be returned if there is an error in the math library used while encrypting the message - \return MP_MULMOD_E May be returned if there is an error in the math + \return MP_MULMOD_E May be returned if there is an error in the math library used while encrypting the message - \return MP_TO_E May be returned if there is an error in the math + \return MP_TO_E May be returned if there is an error in the math library used while encrypting the message - \return MP_MEM May be returned if there is an error in the math + \return MP_MEM May be returned if there is an error in the math library used while encrypting the message - \return MP_ZERO_E May be returned if there is an error in the math + \return MP_ZERO_E May be returned if there is an error in the math library used while encrypting the message - + \param in pointer to a buffer containing the input message to encrypt \param inLen the length of the message to encrypt \param out pointer to the buffer in which to store the output ciphertext \param outLen the length of the output buffer - \param key pointer to the RsaKey structure containing the public + \param key pointer to the RsaKey structure containing the public key to use for encryption \param rng The RNG structure with which to generate random block padding - + _Example_ \code RsaKey pub; @@ -108,9 +108,9 @@ WOLFSSL_API int wc_FreeRsaKey(RsaKey* key); byte n[] = { // initialize with received n component of public key }; byte e[] = { // initialize with received e component of public key }; byte msg[] = { // initialize with plaintext of message to encrypt }; - byte cipher[256]; // 256 bytes is large enough to store 2048 bit RSA + byte cipher[256]; // 256 bytes is large enough to store 2048 bit RSA ciphertext - + wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub); // initialize with received public key parameters @@ -119,7 +119,7 @@ WOLFSSL_API int wc_FreeRsaKey(RsaKey* key); // error encrypting message } \endcode - + \sa wc_RsaPrivateDecrypt */ WOLFSSL_API int wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out, @@ -127,23 +127,23 @@ WOLFSSL_API int wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out, /*! \ingroup RSA - - \brief This functions is utilized by the wc_RsaPrivateDecrypt function + + \brief This functions is utilized by the wc_RsaPrivateDecrypt function for decrypting. - + \return Success Length of decrypted data. \return RSA_PAD_E RsaUnPad error, bad formatting - + \param in The byte array to be decrypted. \param inLen The length of in. \param out The byte array for the decrypted data to be stored. \param key The key to use for decryption. - + _Example_ \code none \endcode - + \sa wc_RsaPrivateDecrypt */ WOLFSSL_API int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out, @@ -151,9 +151,9 @@ WOLFSSL_API int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out, /*! \ingroup RSA - + \brief This functions provides private RSA decryption. - + \return Success length of decrypted data. \return MEMORY_E -125, out of memory error \return BAD_FUNC_ARG -173, Bad function argument provided @@ -163,7 +163,7 @@ WOLFSSL_API int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out, \param out The byte array for the decrypted data to be stored. \param outLen The length of out. \param key The key to use for decryption. - + _Example_ \code ret = wc_RsaPublicEncrypt(in, inLen, out, sizeof(out), &key, &rng); @@ -185,19 +185,19 @@ WOLFSSL_API int wc_RsaPrivateDecrypt(const byte* in, word32 inLen, byte* out, /*! \ingroup RSA - + \brief Signs the provided array with the private key. - - \return RSA_BUFFER_E: -131, RSA buffer error, output too small or + + \return RSA_BUFFER_E: -131, RSA buffer error, output too small or input too large - + \param in The byte array to be encrypted. \param inLen The length of in. \param out The byte array for the encrypted data to be stored. \param outLen The length of out. \param key The key to use for encryption. \param RNG The RNG struct to use for random number purposes. - + _Example_ \code ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng); @@ -210,7 +210,7 @@ WOLFSSL_API int wc_RsaPrivateDecrypt(const byte* in, word32 inLen, byte* out, return -1; } \endcode - + \sa wc_RsaPad */ WOLFSSL_API int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out, @@ -218,18 +218,18 @@ WOLFSSL_API int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out, /*! \ingroup RSA - - \brief Used to verify that the message was signed by RSA key. The output + + \brief Used to verify that the message was signed by RSA key. The output uses the same byte array as the input. - + \return >0 Length of text. \return <0 An error occurred. - + \param in Byte array to be decrypted. \param inLen Length of the buffer input. \param out Pointer to a pointer for decrypted information. \param key RsaKey to use. - + _Example_ \code RsaKey key; @@ -247,7 +247,7 @@ WOLFSSL_API int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out, // handle error } \endcode - + \sa wc_RsaSSL_Verify \sa wc_RsaSSL_Sign */ @@ -256,9 +256,9 @@ WOLFSSL_API int wc_RsaSSL_VerifyInline(byte* in, word32 inLen, byte** out, /*! \ingroup RSA - + \brief Used to verify that the message was signed by key. - + \return Success Length of text on no error. \return MEMORY_E memory exception. @@ -280,7 +280,7 @@ WOLFSSL_API int wc_RsaSSL_VerifyInline(byte* in, word32 inLen, byte** out, return -1; } \endcode - + \sa wc_RsaSSL_Sign */ WOLFSSL_API int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out, @@ -288,18 +288,18 @@ WOLFSSL_API int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out, /*! \ingroup RSA - + \brief Returns the encryption size for the provided key structure. - + \return Success Encryption size for the provided key structure. - + \param key The key to use for verification. - + _Example_ \code int sz = wc_RsaEncryptSize(&key); \endcode - + \sa wc_InitRsaKey \sa wc_InitRsaKey_ex \sa wc_MakeRsaKey @@ -309,28 +309,28 @@ WOLFSSL_API int wc_RsaEncryptSize(RsaKey* key); /*! \ingroup RSA - - \brief This function parses a DER-formatted RSA private key, extracts the - private key and stores it in the given RsaKey structure. It also sets the + + \brief This function parses a DER-formatted RSA private key, extracts the + private key and stores it in the given RsaKey structure. It also sets the distance parsed in idx. - \return 0 Returned upon successfully parsing the private key from the DER + \return 0 Returned upon successfully parsing the private key from the DER encoded input - \return ASN_PARSE_E Returned if there is an error parsing the private key - from the input buffer. This may happen if the input private key is not + \return ASN_PARSE_E Returned if there is an error parsing the private key + from the input buffer. This may happen if the input private key is not properly formatted according to ASN.1 standards - \return ASN_RSA_KEY_E Returned if there is an error reading the private + \return ASN_RSA_KEY_E Returned if there is an error reading the private key elements of the RSA key input - \param input pointer to the buffer containing the DER formatted private + \param input pointer to the buffer containing the DER formatted private key to decode - \param inOutIdx pointer to the index in the buffer at which the key begins - (usually 0). As a side effect of this function, inOutIdx will store the + \param inOutIdx pointer to the index in the buffer at which the key begins + (usually 0). As a side effect of this function, inOutIdx will store the distance parsed through the input buffer - \param key pointer to the RsaKey structure in which to store the decoded + \param key pointer to the RsaKey structure in which to store the decoded private key \param inSz size of the input buffer - + _Example_ \code RsaKey enc; @@ -341,10 +341,10 @@ WOLFSSL_API int wc_RsaEncryptSize(RsaKey* key); wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory ret = wc_RsaPrivateKeyDecode(der, &idx, &enc, sizeof(der)); if( ret != 0 ) { - // error parsing private key + // error parsing private key } \endcode - + \sa wc_RsaPublicKeyDecode \sa wc_MakeRsaKey */ @@ -353,31 +353,31 @@ WOLFSSL_API int wc_RsaPrivateKeyDecode(const byte* input, word32* inOutIdx, /*! \ingroup RSA - - \brief This function parses a DER-formatted RSA public key, extracts the - public key and stores it in the given RsaKey structure. It also sets the + + \brief This function parses a DER-formatted RSA public key, extracts the + public key and stores it in the given RsaKey structure. It also sets the distance parsed in idx. - - \return 0 Returned upon successfully parsing the public key from the DER + + \return 0 Returned upon successfully parsing the public key from the DER encoded input - \return ASN_PARSE_E Returned if there is an error parsing the public key - from the input buffer. This may happen if the input public key is not + \return ASN_PARSE_E Returned if there is an error parsing the public key + from the input buffer. This may happen if the input public key is not properly formatted according to ASN.1 standards - \return ASN_OBJECT_ID_E Returned if the ASN.1 Object ID does not match + \return ASN_OBJECT_ID_E Returned if the ASN.1 Object ID does not match that of a RSA public key - \return ASN_EXPECT_0_E Returned if the input key is not correctly + \return ASN_EXPECT_0_E Returned if the input key is not correctly formatted according to ASN.1 standards - \return ASN_BITSTR_E Returned if the input key is not correctly formatted - according to ASN.1 standards - \return ASN_RSA_KEY_E Returned if there is an error reading the public key + \return ASN_BITSTR_E Returned if the input key is not correctly formatted + according to ASN.1 standards + \return ASN_RSA_KEY_E Returned if there is an error reading the public key elements of the RSA key input - \param input pointer to the buffer containing the input DER-encoded RSA + \param input pointer to the buffer containing the input DER-encoded RSA public key to decode - \param inOutIdx pointer to the index in the buffer at which the key - begins (usually 0). As a side effect of this function, inOutIdx will + \param inOutIdx pointer to the index in the buffer at which the key + begins (usually 0). As a side effect of this function, inOutIdx will store the distance parsed through the input buffer - \param key pointer to the RsaKey structure in which to store the decoded + \param key pointer to the RsaKey structure in which to store the decoded public key \param inSz size of the input buffer @@ -391,10 +391,10 @@ WOLFSSL_API int wc_RsaPrivateKeyDecode(const byte* input, word32* inOutIdx, wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory ret = wc_RsaPublicKeyDecode(der, &idx, &pub, sizeof(der)); if( ret != 0 ) { - // error parsing public key + // error parsing public key } \endcode - + \sa wc_RsaPublicKeyDecodeRaw */ WOLFSSL_API int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx, @@ -402,28 +402,28 @@ WOLFSSL_API int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx, /*! \ingroup RSA - - \brief This function decodes the raw elements of an RSA public key, taking - in the public modulus (n) and exponent (e). It stores these raw elements - in the provided RsaKey structure, allowing one to use them in the + + \brief This function decodes the raw elements of an RSA public key, taking + in the public modulus (n) and exponent (e). It stores these raw elements + in the provided RsaKey structure, allowing one to use them in the encryption/decryption process. - - \return 0 Returned upon successfully decoding the raw elements of the + + \return 0 Returned upon successfully decoding the raw elements of the public key into the RsaKey structure - \return BAD_FUNC_ARG Returned if any of the input arguments evaluates to + \return BAD_FUNC_ARG Returned if any of the input arguments evaluates to NULL - \return MP_INIT_E Returned if there is an error initializing an integer + \return MP_INIT_E Returned if there is an error initializing an integer for use with the multiple precision integer (mp_int) library - \return ASN_GETINT_E Returned if there is an error reading one of the + \return ASN_GETINT_E Returned if there is an error reading one of the provided RSA key elements, n or e - \param n pointer to a buffer containing the raw modulus parameter of the + \param n pointer to a buffer containing the raw modulus parameter of the public RSA key \param nSz size of the buffer containing n - \param e pointer to a buffer containing the raw exponent parameter of + \param e pointer to a buffer containing the raw exponent parameter of the public RSA key \param eSz size of the buffer containing e - \param key pointer to the RsaKey struct to initialize with the provided + \param key pointer to the RsaKey struct to initialize with the provided public key elements _Example_ @@ -439,7 +439,7 @@ WOLFSSL_API int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx, // error parsing public key elements } \endcode - + \sa wc_RsaPublicKeyDecode */ WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz, @@ -447,19 +447,19 @@ WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz, /*! \ingroup RSA - - \brief This function converts an RsaKey key to DER format. The result is + + \brief This function converts an RsaKey key to DER format. The result is written to output and it returns the number of bytes written. - + \return 0 Success - \return BAD_FUNC_ARG Returned if key or output is null, or if key->type + \return BAD_FUNC_ARG Returned if key or output is null, or if key->type is not RSA_PRIVATE, or if inLen isn't large enough for output buffer. \return MEMORY_E Returned if there is an error allocating memory. - + \param key Initialized RsaKey structure. \param output Pointer to output buffer. \param inLen Size of output buffer. - + _Example_ \code byte* der; @@ -468,7 +468,7 @@ WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz, RsaKey key; WC_WC_RNG rng; long e = 65537; // standard value to use for exponent - ret = wc_MakeRsaKey(&key, 2048, e, &rng); // generate 2048 bit long + ret = wc_MakeRsaKey(&key, 2048, e, &rng); // generate 2048 bit long private key wc_InitRsaKey(&key, NULL); wc_InitRng(&rng); @@ -477,7 +477,7 @@ WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz, // Handle the error thrown } \endcode - + \sa wc_RsaKeyToPublicDer \sa wc_InitRsaKey \sa wc_MakeRsaKey @@ -487,14 +487,14 @@ WOLFSSL_API int wc_RsaKeyToDer(RsaKey*, byte* output, word32 inLen); /*! \ingroup RSA - - \brief This function performs RSA encrypt while allowing the choice of + + \brief This function performs RSA encrypt while allowing the choice of which padding to use. - - \return size On successfully encryption the size of the encrypted buffer + + \return size On successfully encryption the size of the encrypted buffer is returned \return RSA_BUFFER_E RSA buffer error, output too small or input too large - + \param in pointer to the buffer for encryption \param inLen length of the buffer to encrypt \param out encrypted msg created @@ -516,13 +516,13 @@ WOLFSSL_API int wc_RsaKeyToDer(RsaKey*, byte* output, word32 inLen); int ret; … - ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng, + ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0); if (ret < 0) { //handle error } \endcode - + \sa wc_RsaPublicEncrypt \sa wc_RsaPrivateDecrypt_ex */ @@ -532,17 +532,17 @@ WOLFSSL_API int wc_RsaPublicEncrypt_ex(const byte* in, word32 inLen, byte* out, /*! \ingroup RSA - - \brief This function uses RSA to decrypt a message and gives the + + \brief This function uses RSA to decrypt a message and gives the option of what padding type. - - \return size On successful decryption, the size of the decrypted message + + \return size On successful decryption, the size of the decrypted message is returned. - \return MEMORY_E Returned if not enough memory on system to malloc a + \return MEMORY_E Returned if not enough memory on system to malloc a needed array. - \return BAD_FUNC_ARG Returned if a bad argument was passed into the + \return BAD_FUNC_ARG Returned if a bad argument was passed into the function. - + \param in pointer to the buffer for decryption \param inLen length of the buffer to decrypt \param out decrypted msg created @@ -563,20 +563,20 @@ WOLFSSL_API int wc_RsaPublicEncrypt_ex(const byte* in, word32 inLen, byte* out, byte plain[256]; int ret; … - ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, + ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0); if (ret < 0) { //handle error } … - ret = wc_RsaPrivateDecrypt_ex(out, ret, plain, sizeof(plain), &key, + ret = wc_RsaPrivateDecrypt_ex(out, ret, plain, sizeof(plain), &key, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0); - + if (ret < 0) { //handle error } \endcode - + \sa none */ WOLFSSL_API int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen, @@ -585,20 +585,20 @@ WOLFSSL_API int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen, /*! \ingroup RSA - - \brief This function uses RSA to decrypt a message inline and gives the - option of what padding type. The in buffer will contain the decrypted - message after being called and the out byte pointer will point to the + + \brief This function uses RSA to decrypt a message inline and gives the + option of what padding type. The in buffer will contain the decrypted + message after being called and the out byte pointer will point to the location in the “in” buffer where the plain text is. - - \return size On successful decryption, the size of the decrypted message + + \return size On successful decryption, the size of the decrypted message is returned. - \return MEMORY_E: Returned if not enough memory on system to malloc a + \return MEMORY_E: Returned if not enough memory on system to malloc a needed array. \return RSA_PAD_E: Returned if an error in the padding was encountered. - \return BAD_PADDING_E: Returned if an error happened during parsing past + \return BAD_PADDING_E: Returned if an error happened during parsing past padding. - \return BAD_FUNC_ARG: Returned if a bad argument was passed into the + \return BAD_FUNC_ARG: Returned if a bad argument was passed into the function. \param in pointer to the buffer for decryption @@ -620,21 +620,21 @@ WOLFSSL_API int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen, byte* plain; int ret; … - ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, + ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0); if (ret < 0) { //handle error } … - ret = wc_RsaPrivateDecryptInline_ex(out, ret, &plain, &key, + ret = wc_RsaPrivateDecryptInline_ex(out, ret, &plain, &key, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0); if (ret < 0) { //handle error } \endcode - + \sa none */ WOLFSSL_API int wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen, @@ -643,23 +643,23 @@ WOLFSSL_API int wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen, /*! \ingroup RSA - - \brief Flattens the RsaKey structure into individual elements (e, n) + + \brief Flattens the RsaKey structure into individual elements (e, n) used for the RSA algorithm. - + \return 0 Returned if the function executed normally, without error. - \return BAD_FUNC_ARG: Returned if any of the parameters are passed in + \return BAD_FUNC_ARG: Returned if any of the parameters are passed in with a null value. - \return RSA_BUFFER_E: Returned if the e or n buffers passed in are not + \return RSA_BUFFER_E: Returned if the e or n buffers passed in are not the correct size. \return MP_MEM: Returned if an internal function has memory errors. \return MP_VAL: Returned if an internal function argument is not valid. - + \param key The key to use for verification. - \param e a buffer for the value of e. e is a large positive integer in + \param e a buffer for the value of e. e is a large positive integer in the RSA modular arithmetic operation. \param eSz the size of the e buffer. - \param n a buffer for the value of n. n is a large positive integer in + \param n a buffer for the value of n. n is a large positive integer in the RSA modular arithmetic operation. \param nSz the size of the n buffer. @@ -677,7 +677,7 @@ WOLFSSL_API int wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen, // Failure case. } \endcode - + \sa wc_InitRsaKey \sa wc_InitRsaKey_ex \sa wc_MakeRsaKey @@ -688,10 +688,10 @@ WOLFSSL_API int wc_RsaFlattenPublicKey(RsaKey*, byte*, word32*, byte*, /*! \ingroup RSA - - \brief Convert Rsa Public key to DER format. Writes to output, and + + \brief Convert Rsa Public key to DER format. Writes to output, and returns count of bytes written. - + \return >0 Success, number of bytes written. \return BAD_FUNC_ARG Returned if key or output is null. \return MEMORY_E Returned when an error allocating memory occurs. @@ -700,7 +700,7 @@ WOLFSSL_API int wc_RsaFlattenPublicKey(RsaKey*, byte*, word32*, byte*, \param key The RSA key structure to convert. \param output Output buffer to hold DER. \param inLen Length of buffer. - + _Example_ \code RsaKey key; @@ -715,7 +715,7 @@ WOLFSSL_API int wc_RsaFlattenPublicKey(RsaKey*, byte*, word32*, byte*, // Handle Error } \endcode - + \sa wc_RsaKeyToPublicDer \sa wc_RsaInitKey */ @@ -723,53 +723,53 @@ WOLFSSL_API int wc_RsaKeyToPublicDer(RsaKey*, byte* output, word32 inLen); /*! \ingroup RSA - - \brief This function generates a RSA private key of length size (in bits) - and given exponent (e). It then stores this key in the provided RsaKey - structure, so that it may be used for encryption/decryption. A secure - number to use for e is 65537. size is required to be greater than - RSA_MIN_SIZE and less than RSA_MAX_SIZE. For this function to be - available, the option WOLFSSL_KEY_GEN must be enabled at compile time. + + \brief This function generates a RSA private key of length size (in bits) + and given exponent (e). It then stores this key in the provided RsaKey + structure, so that it may be used for encryption/decryption. A secure + number to use for e is 65537. size is required to be greater than + RSA_MIN_SIZE and less than RSA_MAX_SIZE. For this function to be + available, the option WOLFSSL_KEY_GEN must be enabled at compile time. This can be accomplished with --enable-keygen if using ./configure. \return 0 Returned upon successfully generating a RSA private key - \return BAD_FUNC_ARG Returned if any of the input arguments are NULL, - the size parameter falls outside of the necessary bounds, or e is + \return BAD_FUNC_ARG Returned if any of the input arguments are NULL, + the size parameter falls outside of the necessary bounds, or e is incorrectly chosen - \return RNG_FAILURE_E Returned if there is an error generating a random + \return RNG_FAILURE_E Returned if there is an error generating a random block using the provided RNG structure \return MP_INIT_E - \return MP_READ_E May be May be returned if there is an error in the math - library used while generating the RSA key returned if there is an error + \return MP_READ_E May be May be returned if there is an error in the math + library used while generating the RSA key returned if there is an error in the math library used while generating the RSA key - \return MP_CMP_E May be returned if there is an error in the math library + \return MP_CMP_E May be returned if there is an error in the math library used while generating the RSA key - \return MP_INVMOD_E May be returned if there is an error in the math + \return MP_INVMOD_E May be returned if there is an error in the math library used while generating the RSA key - \return MP_EXPTMOD_E May be returned if there is an error in the math + \return MP_EXPTMOD_E May be returned if there is an error in the math library used while generating the RSA key - \return MP_MOD_E May be returned if there is an error in the math + \return MP_MOD_E May be returned if there is an error in the math library used while generating the RSA key - \return MP_MUL_E May be returned if there is an error in the math + \return MP_MUL_E May be returned if there is an error in the math library used while generating the RSA key - \return MP_ADD_E May be returned if there is an error in the math + \return MP_ADD_E May be returned if there is an error in the math library used while generating the RSA key - \return MP_MULMOD_E May be returned if there is an error in the math + \return MP_MULMOD_E May be returned if there is an error in the math library used while generating the RSA key - \return MP_TO_E May be returned if there is an error in the math + \return MP_TO_E May be returned if there is an error in the math library used while generating the RSA key - \return MP_MEM May be returned if there is an error in the math + \return MP_MEM May be returned if there is an error in the math library used while generating the RSA key - \return MP_ZERO_E May be returned if there is an error in the math + \return MP_ZERO_E May be returned if there is an error in the math library used while generating the RSA key - - \param key pointer to the RsaKey structure in which to store the + + \param key pointer to the RsaKey structure in which to store the generated private key - \param size desired keylenth, in bits. Required to be greater than + \param size desired keylenth, in bits. Required to be greater than RSA_MIN_SIZE and less than RSA_MAX_SIZE - \param e exponent parameter to use for generating the key. A secure + \param e exponent parameter to use for generating the key. A secure choice is 65537 - \param rng pointer to an RNG structure to use for random number generation + \param rng pointer to an RNG structure to use for random number generation while making the ke _Example_ @@ -782,12 +782,12 @@ WOLFSSL_API int wc_RsaKeyToPublicDer(RsaKey*, byte* output, word32 inLen); wc_InitRsaKey(&priv, NULL); // not using heap hint. No custom memory wc_InitRng(&rng); // generate 2048 bit long private key - ret = wc_MakeRsaKey(&priv, 2048, e, &rng); + ret = wc_MakeRsaKey(&priv, 2048, e, &rng); if( ret != 0 ) { // error generating private key } \endcode - + \sa none */ WOLFSSL_API int wc_MakeRsaKey(RsaKey* key, int size, long e, WC_RNG* rng); diff --git a/doc/dox_comments/header_files/sha.h b/doc/dox_comments/header_files/sha.h index 57373c1c3..3b5ac12a1 100644 --- a/doc/dox_comments/header_files/sha.h +++ b/doc/dox_comments/header_files/sha.h @@ -1,13 +1,13 @@ /*! \ingroup SHA - - \brief This function initializes SHA. This is automatically called + + \brief This function initializes SHA. This is automatically called by wc_ShaHash. - + \return 0 Returned upon successfully initializing - + \param sha pointer to the sha structure to use for encryption - + _Example_ \code Sha sha[1]; @@ -19,7 +19,7 @@ wc_ShaFinal(sha, hash); } \endcode - + \sa wc_ShaHash \sa wc_ShaUpdate \sa wc_ShaFinal @@ -28,16 +28,16 @@ WOLFSSL_API int wc_InitSha(wc_Sha*); /*! \ingroup SHA - - \brief Can be called to continually hash the provided byte array of + + \brief Can be called to continually hash the provided byte array of length len. - + \return 0 Returned upon successfully adding the data to the digest. - + \param sha pointer to the sha structure to use for encryption \param data the data to be hashed \param len length of data to be hashed - + _Example_ \code Sha sha[1]; @@ -52,7 +52,7 @@ WOLFSSL_API int wc_InitSha(wc_Sha*); wc_ShaFinal(sha, hash); } \endcode - + \sa wc_ShaHash \sa wc_ShaFinal \sa wc_InitSha @@ -61,15 +61,15 @@ WOLFSSL_API int wc_ShaUpdate(wc_Sha*, const byte*, word32); /*! \ingroup SHA - - \brief Finalizes hashing of data. Result is placed into hash. + + \brief Finalizes hashing of data. Result is placed into hash. Resets state of sha struct. - + \return 0 Returned upon successfully finalizing. - + \param sha pointer to the sha structure to use for encryption \param hash Byte array to hold hash value. - + _Example_ \code Sha sha[1]; @@ -84,7 +84,7 @@ WOLFSSL_API int wc_ShaUpdate(wc_Sha*, const byte*, word32); wc_ShaFinal(sha, hash); } \endcode - + \sa wc_ShaHash \sa wc_InitSha \sa wc_ShaGetHash @@ -93,14 +93,14 @@ WOLFSSL_API int wc_ShaFinal(wc_Sha*, byte*); /*! \ingroup SHA - + \brief Used to clean up memory used by an initialized Sha struct. Note: this is only supported if you have WOLFSSL_TI_HASH defined. - + \return No returns. - + \param sha Pointer to the Sha struct to free. - + _Example_ \code Sha sha; @@ -108,7 +108,7 @@ WOLFSSL_API int wc_ShaFinal(wc_Sha*, byte*); // Use sha wc_ShaFree(&sha); \endcode - + \sa wc_InitSha \sa wc_ShaUpdate \sa wc_ShaFinal @@ -117,15 +117,15 @@ WOLFSSL_API void wc_ShaFree(wc_Sha*); /*! \ingroup SHA - - \brief Gets hash data. Result is placed into hash. Does not reset state + + \brief Gets hash data. Result is placed into hash. Does not reset state of sha struct. - + \return 0 Returned upon successfully finalizing. - + \param sha pointer to the sha structure to use for encryption \param hash Byte array to hold hash value. - + _Example_ \code Sha sha[1]; @@ -137,7 +137,7 @@ WOLFSSL_API void wc_ShaFree(wc_Sha*); wc_ShaGetHash(sha, hash); } \endcode - + \sa wc_ShaHash \sa wc_ShaFinal \sa wc_InitSha diff --git a/doc/dox_comments/header_files/sha256.h b/doc/dox_comments/header_files/sha256.h index 045539f1a..8c667ca9b 100644 --- a/doc/dox_comments/header_files/sha256.h +++ b/doc/dox_comments/header_files/sha256.h @@ -1,13 +1,13 @@ /*! \ingroup SHA - - \brief This function initializes SHA256. This is automatically + + \brief This function initializes SHA256. This is automatically called by wc_Sha256Hash. - + \return 0 Returned upon successfully initializing - + \param sha256 pointer to the sha256 structure to use for encryption - + _Example_ \code Sha256 sha256[1]; @@ -19,7 +19,7 @@ wc_Sha256Final(sha256, hash); } \endcode - + \sa wc_Sha256Hash \sa wc_Sha256Update \sa wc_Sha256Final @@ -28,16 +28,16 @@ WOLFSSL_API int wc_InitSha256(wc_Sha256*); /*! \ingroup SHA - - \brief Can be called to continually hash the provided byte + + \brief Can be called to continually hash the provided byte array of length len. - + \return 0 Returned upon successfully adding the data to the digest. - + \param sha256 pointer to the sha256 structure to use for encryption \param data the data to be hashed \param len length of data to be hashed - + _Example_ \code Sha256 sha256[1]; @@ -52,7 +52,7 @@ WOLFSSL_API int wc_InitSha256(wc_Sha256*); wc_Sha256Final(sha256, hash); } \endcode - + \sa wc_Sha256Hash \sa wc_Sha256Final \sa wc_InitSha256 @@ -61,15 +61,15 @@ WOLFSSL_API int wc_Sha256Update(wc_Sha256*, const byte*, word32); /*! \ingroup SHA - - \brief Finalizes hashing of data. Result is placed into hash. + + \brief Finalizes hashing of data. Result is placed into hash. Resets state of sha256 struct. - + \return 0 Returned upon successfully finalizing. - + \param sha256 pointer to the sha256 structure to use for encryption \param hash Byte array to hold hash value. - + _Example_ \code Sha256 sha256[1]; @@ -84,7 +84,7 @@ WOLFSSL_API int wc_Sha256Update(wc_Sha256*, const byte*, word32); wc_Sha256Final(sha256, hash); } \endcode - + \sa wc_Sha256Hash \sa wc_Sha256GetHash \sa wc_InitSha256 @@ -93,12 +93,12 @@ WOLFSSL_API int wc_Sha256Final(wc_Sha256*, byte*); /*! \ingroup SHA - - \brief Resets the Sha256 structure. Note: this is only supported + + \brief Resets the Sha256 structure. Note: this is only supported if you have WOLFSSL_TI_HASH defined. - + \return none No returns. - + \param sha256 Pointer to the sha256 structure to be freed. _Example_ @@ -116,7 +116,7 @@ WOLFSSL_API int wc_Sha256Final(wc_Sha256*, byte*); wc_Sha256Free(&sha256); } \endcode - + \sa wc_InitSha256 \sa wc_Sha256Update \sa wc_Sha256Final @@ -125,15 +125,15 @@ WOLFSSL_API void wc_Sha256Free(wc_Sha256*); /*! \ingroup SHA - - \brief Gets hash data. Result is placed into hash. Does not + + \brief Gets hash data. Result is placed into hash. Does not reset state of sha256 struct. - + \return 0 Returned upon successfully finalizing. - + \param sha256 pointer to the sha256 structure to use for encryption \param hash Byte array to hold hash value. - + _Example_ \code Sha256 sha256[1]; @@ -145,7 +145,7 @@ WOLFSSL_API void wc_Sha256Free(wc_Sha256*); wc_Sha256GetHash(sha256, hash); } \endcode - + \sa wc_Sha256Hash \sa wc_Sha256Final \sa wc_InitSha256 @@ -154,14 +154,14 @@ WOLFSSL_API int wc_Sha256GetHash(wc_Sha256*, byte*); /*! \ingroup SHA - + \brief Used to initialize a Sha224 struct. - + \return 0 Success \return 1 Error returned because sha224 is null. - + \param sha224 Pointer to a Sha224 struct to initialize. - + _Example_ \code Sha224 sha224; @@ -170,7 +170,7 @@ WOLFSSL_API int wc_Sha256GetHash(wc_Sha256*, byte*); // Handle error } \endcode - + \sa wc_Sha224Hash \sa wc_Sha224Update \sa wc_Sha224Final @@ -179,10 +179,10 @@ WOLFSSL_API int wc_InitSha224(wc_Sha224*); /*! \ingroup SHA - - \brief Can be called to continually hash the provided byte array + + \brief Can be called to continually hash the provided byte array of length len. - + \return 0 Success \return 1 Error returned if function fails. \return BAD_FUNC_ARG Error returned if sha224 or data is null. @@ -205,7 +205,7 @@ WOLFSSL_API int wc_InitSha224(wc_Sha224*); wc_Sha224Final(&sha224, hash); } \endcode - + \sa wc_InitSha224 \sa wc_Sha224Final \sa wc_Sha224Hash @@ -214,16 +214,16 @@ WOLFSSL_API int wc_Sha224Update(wc_Sha224*, const byte*, word32); /*! \ingroup SHA - - \brief Finalizes hashing of data. Result is placed into hash. + + \brief Finalizes hashing of data. Result is placed into hash. Resets state of sha224 struct. - + \return 0 Success \return <0 Error - + \param sha224 pointer to the sha224 structure to use for encryption \param hash Byte array to hold hash value. - + _Example_ \code Sha224 sha224; @@ -238,7 +238,7 @@ WOLFSSL_API int wc_Sha224Update(wc_Sha224*, const byte*, word32); wc_Sha224Final(&sha224, hash); } \endcode - + \sa wc_InitSha224 \sa wc_Sha224Hash \sa wc_Sha224Update diff --git a/doc/dox_comments/header_files/sha512.h b/doc/dox_comments/header_files/sha512.h index 210a95eb3..408e222b5 100644 --- a/doc/dox_comments/header_files/sha512.h +++ b/doc/dox_comments/header_files/sha512.h @@ -1,13 +1,13 @@ /*! \ingroup SHA - - \brief This function initializes SHA512. This is automatically called + + \brief This function initializes SHA512. This is automatically called by wc_Sha512Hash. - + \return 0 Returned upon successfully initializing - + \param sha512 pointer to the sha512 structure to use for encryption - + _Example_ \code Sha512 sha512[1]; @@ -19,7 +19,7 @@ wc_Sha512Final(sha512, hash); } \endcode - + \sa wc_Sha512Hash \sa wc_Sha512Update \sa wc_Sha512Final @@ -28,16 +28,16 @@ WOLFSSL_API int wc_InitSha512(wc_Sha512*); /*! \ingroup SHA - - \brief Can be called to continually hash the provided byte array + + \brief Can be called to continually hash the provided byte array of length len. - + \return 0 Returned upon successfully adding the data to the digest. - + \param sha512 pointer to the sha512 structure to use for encryption \param data the data to be hashed \param len length of data to be hashed - + _Example_ \code Sha512 sha512[1]; @@ -51,8 +51,8 @@ WOLFSSL_API int wc_InitSha512(wc_Sha512*); wc_Sha512Update(sha512, data, len); wc_Sha512Final(sha512, hash); } - \endcode - + \endcode + \sa wc_Sha512Hash \sa wc_Sha512Final \sa wc_InitSha512 @@ -61,14 +61,14 @@ WOLFSSL_API int wc_Sha512Update(wc_Sha512*, const byte*, word32); /*! \ingroup SHA - + \brief Finalizes hashing of data. Result is placed into hash. - + \return 0 Returned upon successfully finalizing the hash. - + \param sha512 pointer to the sha512 structure to use for encryption \param hash Byte array to hold hash value. - + _Example_ \code Sha512 sha512[1]; @@ -83,7 +83,7 @@ WOLFSSL_API int wc_Sha512Update(wc_Sha512*, const byte*, word32); wc_Sha512Final(sha512, hash); } \endcode - + \sa wc_Sha512Hash \sa wc_Sha512Final \sa wc_InitSha512 @@ -92,14 +92,14 @@ WOLFSSL_API int wc_Sha512Final(wc_Sha512*, byte*); /*! \ingroup SHA - - \brief This function initializes SHA384. This is automatically called + + \brief This function initializes SHA384. This is automatically called by wc_Sha384Hash. - + \return 0 Returned upon successfully initializing - + \param sha384 pointer to the sha384 structure to use for encryption - + _Example_ \code Sha384 sha384[1]; @@ -111,7 +111,7 @@ WOLFSSL_API int wc_Sha512Final(wc_Sha512*, byte*); wc_Sha384Final(sha384, hash); } \endcode - + \sa wc_Sha384Hash \sa wc_Sha384Update \sa wc_Sha384Final @@ -120,12 +120,12 @@ WOLFSSL_API int wc_InitSha384(wc_Sha384*); /*! \ingroup SHA - - \brief Can be called to continually hash the provided byte array + + \brief Can be called to continually hash the provided byte array of length len. - + \return 0 Returned upon successfully adding the data to the digest. - + \param sha384 pointer to the sha384 structure to use for encryption \param data the data to be hashed \param len length of data to be hashed @@ -144,7 +144,7 @@ WOLFSSL_API int wc_InitSha384(wc_Sha384*); wc_Sha384Final(sha384, hash); } \endcode - + \sa wc_Sha384Hash \sa wc_Sha384Final \sa wc_InitSha384 @@ -153,14 +153,14 @@ WOLFSSL_API int wc_Sha384Update(wc_Sha384*, const byte*, word32); /*! \ingroup SHA - + \brief Finalizes hashing of data. Result is placed into hash. - + \return 0 Returned upon successfully finalizing. - + \param sha384 pointer to the sha384 structure to use for encryption \param hash Byte array to hold hash value. - + _Example_ \code Sha384 sha384[1]; @@ -175,7 +175,7 @@ WOLFSSL_API int wc_Sha384Update(wc_Sha384*, const byte*, word32); wc_Sha384Final(sha384, hash); } \endcode - + \sa wc_Sha384Hash \sa wc_Sha384Final \sa wc_InitSha384 diff --git a/doc/dox_comments/header_files/signature.h b/doc/dox_comments/header_files/signature.h index 6661d13f7..f6bb32d9b 100644 --- a/doc/dox_comments/header_files/signature.h +++ b/doc/dox_comments/header_files/signature.h @@ -1,17 +1,17 @@ /*! \ingroup Signature - + \brief This function returns the maximum size of the resulting signature. - - \return Returns SIG_TYPE_E if sig_type is not supported. Returns - BAD_FUNC_ARG if sig_type was invalid. A positive return value indicates + + \return Returns SIG_TYPE_E if sig_type is not supported. Returns + BAD_FUNC_ARG if sig_type was invalid. A positive return value indicates the maximum size of a signature. - - \param sig_type A signature type enum value such as + + \param sig_type A signature type enum value such as WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA. \param key Pointer to a key structure such as ecc_key or RsaKey. \param key_len Size of the key structure. - + _Example_ \code // Get signature length @@ -24,7 +24,7 @@ // Success } \endcode - + \sa wc_HashGetDigestSize \sa wc_SignatureGenerate \sa wc_SignatureVerify @@ -34,18 +34,18 @@ WOLFSSL_API int wc_SignatureGetSize(enum wc_SignatureType sig_type, /*! \ingroup Signature - - \brief This function validates a signature by hashing the data and + + \brief This function validates a signature by hashing the data and using the resulting hash and key to verify the signature. - + \return 0 Success \return SIG_TYPE_E -231, signature type not enabled/ available \return BAD_FUNC_ARG -173, bad function argument provided \return BUFFER_E -132, output buffer too small or input too large. - - \param hash_type A hash type from the “enum wc_HashType” such as + + \param hash_type A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”. - \param sig_type A signature type enum value such as + \param sig_type A signature type enum value such as WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA. \param data Pointer to buffer containing the data to hash. \param data_len Length of the data buffer. @@ -53,7 +53,7 @@ WOLFSSL_API int wc_SignatureGetSize(enum wc_SignatureType sig_type, \param sig_len Length of the signature output buffer. \param key Pointer to a key structure such as ecc_key or RsaKey. \param key_len Size of the key structure. - + _Example_ \code int ret; @@ -68,11 +68,11 @@ WOLFSSL_API int wc_SignatureGetSize(enum wc_SignatureType sig_type, fileBuf, fileLen, sigBuf, sigLen, &eccKey, sizeof(eccKey)); - printf("Signature Verification: %s + printf("Signature Verification: %s (%d)\n", (ret == 0) ? "Pass" : "Fail", ret); wc_ecc_free(&eccKey); \endcode - + \sa wc_SignatureGetSize \sa wc_SignatureGenerate */ @@ -84,18 +84,18 @@ WOLFSSL_API int wc_SignatureVerify( /*! \ingroup Signature - - \brief This function generates a signature from the data using a + + \brief This function generates a signature from the data using a key. It first creates a hash of the data then signs the hash using the key. \return 0 Success \return SIG_TYPE_E -231, signature type not enabled/ available \return BAD_FUNC_ARG -173, bad function argument provided \return BUFFER_E -132, output buffer too small or input too large. - - \param hash_type A hash type from the “enum wc_HashType” + + \param hash_type A hash type from the “enum wc_HashType” such as “WC_HASH_TYPE_SHA256”. - \param sig_type A signature type enum value such as + \param sig_type A signature type enum value such as WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA. \param data Pointer to buffer containing the data to hash. \param data_len Length of the data buffer. @@ -104,13 +104,13 @@ WOLFSSL_API int wc_SignatureVerify( \param key Pointer to a key structure such as ecc_key or RsaKey. \param key_len Size of the key structure. \param rng Pointer to an initialized RNG structure. - + _Example_ \code int ret; WC_RNG rng; ecc_key eccKey; - + wc_InitRng(&rng); wc_ecc_init(&eccKey); @@ -128,14 +128,14 @@ WOLFSSL_API int wc_SignatureVerify( sigBuf, &sigLen, &eccKey, sizeof(eccKey), &rng); - printf("Signature Generation: %s + printf("Signature Generation: %s (%d)\n", (ret == 0) ? "Pass" : "Fail", ret); free(sigBuf); wc_ecc_free(&eccKey); wc_FreeRng(&rng); \endcode - + \sa wc_SignatureGetSize \sa wc_SignatureVerify */ diff --git a/doc/dox_comments/header_files/srp.h b/doc/dox_comments/header_files/srp.h index 004e106a7..da560c413 100644 --- a/doc/dox_comments/header_files/srp.h +++ b/doc/dox_comments/header_files/srp.h @@ -1,19 +1,19 @@ /*! \ingroup SRP - + \brief Initializes the Srp struct for usage. - + \return 0 on success. - \return BAD_FUNC_ARG Returns when there's an issue with the arguments such + \return BAD_FUNC_ARG Returns when there's an issue with the arguments such as srp being null or SrpSide not being SRP_CLIENT_SIDE or SRP_SERVER_SIDE. - \return NOT_COMPILED_IN Returns when a type is passed as an argument but + \return NOT_COMPILED_IN Returns when a type is passed as an argument but hasn't been configured in the wolfCrypt build. \return <0 on error. - + \param srp the Srp structure to be initialized. \param type the hash type to be used. \param side the side of the communication. - + _Example_ \code Srp srp; @@ -26,7 +26,7 @@ wc_SrpTerm(&srp); } \endcode - + \sa wc_SrpTerm \sa wc_SrpSetUsername */ @@ -34,13 +34,13 @@ WOLFSSL_API int wc_SrpInit(Srp* srp, SrpType type, SrpSide side); /*! \ingroup SRP - + \brief Releases the Srp struct resources after usage. - + \return none No returns. - + \param srp Pointer to the Srp structure to be terminated. - + _Example_ \code Srp srp; @@ -48,26 +48,26 @@ WOLFSSL_API int wc_SrpInit(Srp* srp, SrpType type, SrpSide side); // Use srp wc_SrpTerm(&srp) \endcode - + \sa wc_SrpInit */ WOLFSSL_API void wc_SrpTerm(Srp* srp); /*! \ingroup SRP - + \brief Sets the username. This function MUST be called after wc_SrpInit. - + \return 0 Username set successfully. \return BAD_FUNC_ARG: Return if srp or username is null. - \return MEMORY_E: Returns if there is an issue allocating memory + \return MEMORY_E: Returns if there is an issue allocating memory for srp->user \return < 0: Error. \param srp the Srp structure. \param username the buffer containing the username. \param size the username size in bytes - + _Example_ \code Srp srp; @@ -81,7 +81,7 @@ WOLFSSL_API void wc_SrpTerm(Srp* srp); } wc_SrpTerm(&srp); \endcode - + \sa wc_SrpInit \sa wc_SrpSetParams \sa wc_SrpTerm @@ -90,16 +90,16 @@ WOLFSSL_API int wc_SrpSetUsername(Srp* srp, const byte* username, word32 size); /*! \ingroup SRP - - \brief Sets the srp parameters based on the username.. Must be called + + \brief Sets the srp parameters based on the username.. Must be called after wc_SrpSetUsername. - + \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 + \return SRP_CALL_ORDER_E Returns if wc_SrpSetParams is called before wc_SrpSetUsername. \return <0 Error - + \param srp the Srp structure. \param N the Modulus. N = 2q+1, [q, N] are primes. \param nSz the N size in bytes. @@ -121,14 +121,14 @@ wc_SrpSetUsername. wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE); wc_SrpSetUsername(&srp, username, usernameSize); - if(wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, + if(wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt)) != 0) { // Error setting params } wc_SrpTerm(&srp); \endcode - + \sa wc_SrpInit \sa wc_SrpSetUsername \sa wc_SrpTerm @@ -139,16 +139,16 @@ WOLFSSL_API int wc_SrpSetParams(Srp* srp, const byte* N, word32 nSz, /*! \ingroup SRP - - \brief Sets the password. Setting the password does not persists the - clear password data in the srp structure. The client calculates - x = H(salt + H(user:pswd)) and stores it in the auth field. This function + + \brief Sets the password. Setting the password does not persists the + clear password data in the srp structure. The client calculates + x = H(salt + H(user:pswd)) and stores it in the auth field. This function MUST be called after wc_SrpSetParams and is CLIENT SIDE ONLY. - + \return 0 Success - \return BAD_FUNC_ARG Returns if srp or password is null or if srp->side + \return BAD_FUNC_ARG Returns if srp or password is null or if srp->side is not set to SRP_CLIENT_SIDE. - \return SRP_CALL_ORDER_E Returns when wc_SrpSetPassword is called out + \return SRP_CALL_ORDER_E Returns when wc_SrpSetPassword is called out of order. \return <0 Error @@ -179,7 +179,7 @@ WOLFSSL_API int wc_SrpSetParams(Srp* srp, const byte* N, word32 nSz, wc_SrpTerm(&srp); \endcode - + \sa wc_SrpInit \sa wc_SrpSetUsername \sa wc_SrpSetParams @@ -188,12 +188,12 @@ WOLFSSL_API int wc_SrpSetPassword(Srp* srp, const byte* password, word32 size); /*! \ingroup SRP - - \brief Sets the verifier. This function MUST be called after + + \brief Sets the verifier. This function MUST be called after wc_SrpSetParams and is SERVER SIDE ONLY. - + \return 0 Success - \return BAD_FUNC_ARG Returned if srp or verifier is null or + \return BAD_FUNC_ARG Returned if srp or verifier is null or srp->side is not SRP_SERVER_SIDE. \return <0 Error @@ -222,7 +222,7 @@ WOLFSSL_API int wc_SrpSetPassword(Srp* srp, const byte* password, word32 size); wc_SrpTerm(&srp); \endcode - + \sa wc_SrpInit \sa wc_SrpSetParams \sa wc_SrpGetVerifier @@ -231,23 +231,23 @@ WOLFSSL_API int wc_SrpSetVerifier(Srp* srp, const byte* verifier, word32 size); /*! \ingroup SRP - - \brief Gets the verifier. The client calculates the verifier + + \brief Gets the verifier. The client calculates the verifier with v = g ^ x % N. - This function MAY be called after wc_SrpSetPassword and + This function MAY be called after wc_SrpSetPassword and is CLIENT SIDE ONLY. - + \return 0 Success - \return BAD_FUNC_ARG Returned if srp, verifier or size is null + \return BAD_FUNC_ARG Returned if srp, verifier or size is null or if srp->side is not SRP_CLIENT_SIDE. - \return SRP_CALL_ORDER_E Returned if wc_SrpGetVerifier is called + \return SRP_CALL_ORDER_E Returned if wc_SrpGetVerifier is called out of order. \return <0 Error - + \param srp The Srp structure. \param verifier The buffer to write the verifier. \param size Buffer size in bytes. Updated with the verifier size. - + _Example_ \code Srp srp; @@ -274,7 +274,7 @@ WOLFSSL_API int wc_SrpSetVerifier(Srp* srp, const byte* verifier, word32 size); } wc_SrpTerm(&srp); \endcode - + \sa wc_SrpSetVerifier \sa wc_SrpSetPassword */ @@ -282,22 +282,22 @@ WOLFSSL_API int wc_SrpGetVerifier(Srp* srp, byte* verifier, word32* size); /*! \ingroup SRP - - \brief Sets the private ephemeral value. The private ephemeral value + + \brief Sets the private ephemeral value. The private ephemeral value is known as: a at the client side. a = random() b at the server side. b = random() - This function is handy for unit test cases or if the developer wants + This function is handy for unit test cases or if the developer wants to use an external - random source to set the ephemeral value. This function MAY be called + random source to set the ephemeral value. This function MAY be called before wc_SrpGetPublic. - + \return 0 Success \return BAD_FUNC_ARG Returned if srp, private, or size is null. - \return SRP_CALL_ORDER_E Returned if wc_SrpSetPrivate is called out + \return SRP_CALL_ORDER_E Returned if wc_SrpSetPrivate is called out of order. \return <0 Error - + \param srp the Srp structure. \param priv the ephemeral value. \param size the private size in bytes. @@ -325,31 +325,31 @@ WOLFSSL_API int wc_SrpGetVerifier(Srp* srp, byte* verifier, word32* size); wc_SrpTerm(&srp); \endcode - + \sa wc_SrpGetPublic */ WOLFSSL_API int wc_SrpSetPrivate(Srp* srp, const byte* priv, word32 size); /*! \ingroup SRP - - \brief Gets the public ephemeral value. The public ephemeral value + + \brief Gets the public ephemeral value. The public ephemeral value is known as: A at the client side. A = g ^ a % N B at the server side. B = (k * v + (g ˆ b % N)) % N This function MUST be called after wc_SrpSetPassword or wc_SrpSetVerifier. The function wc_SrpSetPrivate may be called before wc_SrpGetPublic. - + \return 0 Success \return BAD_FUNC_ARG Returned if srp, pub, or size is null. - \return SRP_CALL_ORDER_E Returned if wc_SrpGetPublic is called out + \return SRP_CALL_ORDER_E Returned if wc_SrpGetPublic is called out of order. \return BUFFER_E Returned if size < srp.N. \return <0 Error \param srp the Srp structure. \param pub the buffer to write the public ephemeral value. - \param size the the buffer size in bytes. Will be updated with + \param size the the buffer size in bytes. Will be updated with the ephemeral value size. _Example_ @@ -378,7 +378,7 @@ WOLFSSL_API int wc_SrpSetPrivate(Srp* srp, const byte* priv, word32 size); wc_SrpTerm(&srp); \endcode - + \sa wc_SrpSetPrivate \sa wc_SrpSetPassword \sa wc_SrpSetVerifier @@ -387,17 +387,17 @@ WOLFSSL_API int wc_SrpGetPublic(Srp* srp, byte* pub, word32* size); /*! \ingroup SRP - - \brief Computes the session key. The key can be accessed at + + \brief Computes the session key. The key can be accessed at srp->key after success. - + \return 0 Success - \return BAD_FUNC_ARG Returned if srp, clientPubKey, or serverPubKey + \return BAD_FUNC_ARG Returned if srp, clientPubKey, or serverPubKey or if clientPubKeySz or serverPubKeySz is 0. - \return SRP_CALL_ORDER_E Returned if wc_SrpComputeKey is called out + \return SRP_CALL_ORDER_E Returned if wc_SrpComputeKey is called out of order. \return <0 Error - + \param srp the Srp structure. \param clientPubKey the client's public ephemeral value. \param clientPubKeySz the client's public ephemeral value size. @@ -431,7 +431,7 @@ WOLFSSL_API int wc_SrpGetPublic(Srp* srp, byte* pub, word32* size); serverPubKey, serverPubKeySize) wc_SrpTerm(&server); \endcode - + \sa wc_SrpGetPublic */ WOLFSSL_API int wc_SrpComputeKey(Srp* srp, @@ -440,9 +440,9 @@ WOLFSSL_API int wc_SrpComputeKey(Srp* srp, /*! \ingroup SRP - + \brief Gets the proof. This function MUST be called after wc_SrpComputeKey. - + \return 0 Success \return BAD_FUNC_ARG Returns if srp, proof, or size is null. \return BUFFER_E Returns if size is less than the hash size of srp->type. @@ -465,24 +465,24 @@ WOLFSSL_API int wc_SrpComputeKey(Srp* srp, // Error getting proof } \endcode - + \sa wc_SrpComputeKey */ WOLFSSL_API int wc_SrpGetProof(Srp* srp, byte* proof, word32* size); /*! \ingroup SRP - - \brief Verifies the peers proof. This function MUST be called before + + \brief Verifies the peers proof. This function MUST be called before wc_SrpGetSessionKey. - + \return 0 Success \return <0 Error - + \param srp the Srp structure. \param proof the peers proof. \param size the proof size in bytes. - + _Example_ \code Srp cli; @@ -499,7 +499,7 @@ WOLFSSL_API int wc_SrpGetProof(Srp* srp, byte* proof, word32* size); // Error verifying proof } \endcode - + \sa wc_SrpGetSessionKey \sa wc_SrpGetProof \sa wc_SrpTerm diff --git a/doc/dox_comments/header_files/ssl.h b/doc/dox_comments/header_files/ssl.h index 6d457b537..30e285069 100644 --- a/doc/dox_comments/header_files/ssl.h +++ b/doc/dox_comments/header_files/ssl.h @@ -1,11 +1,11 @@ /*! \brief This function initializes the DTLS v1.2 client method. - - \return pointer This function returns a pointer to a new + + \return pointer This function returns a pointer to a new WOLFSSL_METHOD structure. - + \param none No parameters. - + _Example_ \code wolfSSL_Init(); @@ -14,7 +14,7 @@ WOLFSSL* ssl = wolfSSL_new(ctx); … \endcode - + \sa wolfSSL_Init \sa wolfSSL_CTX_new */ @@ -23,23 +23,23 @@ WOLFSSL_API WOLFSSL_METHOD *wolfDTLSv1_2_client_method_ex(void* heap); /*! \ingroup Setup - \brief This function returns a WOLFSSL_METHOD similar to - wolfSSLv23_client_method except that it is not determined + \brief This function returns a WOLFSSL_METHOD similar to + wolfSSLv23_client_method except that it is not determined which side yet (server/client). - - \return WOLFSSL_METHOD* On successful creations returns a WOLFSSL_METHOD + + \return WOLFSSL_METHOD* On successful creations returns a WOLFSSL_METHOD pointer \return NULL Null if memory allocation error or failure to create method - + \param none No parameters. - + _Example_ \code WOLFSSL* ctx; ctx = wolfSSL_CTX_new(wolfSSLv23_method()); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -47,25 +47,25 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv23_method(void); /*! \ingroup Setup - - \brief The wolfSSLv3_server_method() function is used to indicate - that the application is a server and will only support the SSL 3.0 - protocol. This function allocates memory for and initializes a new - wolfSSL_METHOD structure to be used when creating the SSL/TLS context + + \brief The wolfSSLv3_server_method() function is used to indicate + that the application is a server and will only support the SSL 3.0 + protocol. This function allocates memory for and initializes a new + wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). - \return * If successful, the call will return a pointer to the newly + \return * If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return FAIL If memory allocation fails when calling XMALLOC, the - failure value of the underlying malloc() implementation will be returned + \return FAIL If memory allocation fails when calling XMALLOC, the + failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters. - + _Example_ \code #include - + WOLFSSL_METHOD* method; WOLFSSL_CTX* ctx; @@ -77,7 +77,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv23_method(void); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfTLSv1_server_method \sa wolfTLSv1_1_server_method \sa wolfTLSv1_2_server_method @@ -88,27 +88,27 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv23_method(void); */ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv3_server_method(void); -/*! +/*! \ingroup Setup - \brief The wolfSSLv3_client_method() function is used to indicate - that the application is a client and will only support the SSL 3.0 - protocol. This function allocates memory for and initializes a - new wolfSSL_METHOD structure to be used when creating the SSL/TLS + \brief The wolfSSLv3_client_method() function is used to indicate + that the application is a client and will only support the SSL 3.0 + protocol. This function allocates memory for and initializes a + new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). - - \return * If successful, the call will return a pointer to the newly + + \return * If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return FAIL If memory allocation fails when calling XMALLOC, the - failure value of the underlying malloc() implementation will be + \return FAIL If memory allocation fails when calling XMALLOC, the + failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters. - + _Example_ \code #include - + WOLFSSL_METHOD* method; WOLFSSL_CTX* ctx; @@ -120,7 +120,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv3_server_method(void); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfTLSv1_client_method \sa wolfTLSv1_1_client_method \sa wolfTLSv1_2_client_method @@ -133,24 +133,24 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv3_client_method(void); /*! \ingroup Setup - \brief The wolfTLSv1_server_method() function is used to indicate that the - application is a server and will only support the TLS 1.0 protocol. This - function allocates memory for and initializes a new wolfSSL_METHOD - structure to be used when creating the SSL/TLS context with + \brief The wolfTLSv1_server_method() function is used to indicate that the + application is a server and will only support the TLS 1.0 protocol. This + function allocates memory for and initializes a new wolfSSL_METHOD + structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). - - \return * If successful, the call will return a pointer to the newly + + \return * If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return FAIL If memory allocation fails when calling XMALLOC, the failure - value of the underlying malloc() implementation will be returned + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters. - + _Example_ \code #include - + WOLFSSL_METHOD* method; WOLFSSL_CTX* ctx; @@ -162,7 +162,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv3_client_method(void); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfSSLv3_server_method \sa wolfTLSv1_1_server_method \sa wolfTLSv1_2_server_method @@ -175,24 +175,24 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_server_method(void); /*! \ingroup Setup - \brief The wolfTLSv1_client_method() function is used to indicate - that the application is a client and will only support the TLS 1.0 - protocol. This function allocates memory for and initializes a new - wolfSSL_METHOD structure to be used when creating the SSL/TLS context + \brief The wolfTLSv1_client_method() function is used to indicate + that the application is a client and will only support the TLS 1.0 + protocol. This function allocates memory for and initializes a new + wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). - - \return * If successful, the call will return a pointer to the newly + + \return * If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return FAIL If memory allocation fails when calling XMALLOC, - the failure value of the underlying malloc() implementation + \return FAIL If memory allocation fails when calling XMALLOC, + the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters. - + _Example_ \code #include - + WOLFSSL_METHOD* method; WOLFSSL_CTX* ctx; @@ -204,7 +204,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_server_method(void); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfSSLv3_client_method \sa wolfTLSv1_1_client_method \sa wolfTLSv1_2_client_method @@ -217,24 +217,24 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_client_method(void); /*! \ingroup Setup - \brief The wolfTLSv1_1_server_method() function is used to indicate - that the application is a server and will only support the TLS 1.1 - protocol. This function allocates memory for and initializes a new - wolfSSL_METHOD structure to be used when creating the SSL/TLS + \brief The wolfTLSv1_1_server_method() function is used to indicate + that the application is a server and will only support the TLS 1.1 + protocol. This function allocates memory for and initializes a new + wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). - - \return * If successful, the call will return a pointer to the newly + + \return * If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return FAIL If memory allocation fails when calling XMALLOC, the failure - value of the underlying malloc() implementation will be returned + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters. - + _Example_ \code #include - + WOLFSSL_METHOD* method; WOLFSSL_CTX* ctx; @@ -246,7 +246,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_client_method(void); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfSSLv3_server_method \sa wolfTLSv1_server_method \sa wolfTLSv1_2_server_method @@ -258,25 +258,25 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_1_server_method(void); /*! \ingroup Setup - - \brief The wolfTLSv1_1_client_method() function is used to indicate - that the application is a client and will only support the TLS 1.0 - protocol. This function allocates memory for and initializes a - new wolfSSL_METHOD structure to be used when creating the SSL/TLS + + \brief The wolfTLSv1_1_client_method() function is used to indicate + that the application is a client and will only support the TLS 1.0 + protocol. This function allocates memory for and initializes a + new wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). - - \return * If successful, the call will return a pointer to the + + \return * If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return FAIL If memory allocation fails when calling XMALLOC, the failure - value of the underlying malloc() implementation will be returned + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters. - + _Example_ \code #include - + WOLFSSL_METHOD* method; WOLFSSL_CTX* ctx; @@ -288,7 +288,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_1_server_method(void); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfSSLv3_client_method \sa wolfTLSv1_client_method \sa wolfTLSv1_2_client_method @@ -301,24 +301,24 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_1_client_method(void); /*! \ingroup Setup - \brief The wolfTLSv1_2_server_method() function is used to indicate - that the application is a server and will only support the TLS 1.2 - protocol. This function allocates memory for and initializes a new - wolfSSL_METHOD structure to be used when creating the SSL/TLS context + \brief The wolfTLSv1_2_server_method() function is used to indicate + that the application is a server and will only support the TLS 1.2 + protocol. This function allocates memory for and initializes a new + wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). - \return * If successful, the call will return a pointer to the newly + \return * If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return FAIL If memory allocation fails when calling XMALLOC, the failure - value of the underlying malloc() implementation will be returned + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters. - + _Example_ \code #include - + WOLFSSL_METHOD* method; WOLFSSL_CTX* ctx; @@ -330,7 +330,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_1_client_method(void); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfSSLv3_server_method \sa wolfTLSv1_server_method \sa wolfTLSv1_1_server_method @@ -343,24 +343,24 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_2_server_method(void); /*! \ingroup Setup - \brief The wolfTLSv1_2_client_method() function is used to indicate - that the application is a client and will only support the TLS 1.2 - protocol. This function allocates memory for and initializes a new - wolfSSL_METHOD structure to be used when creating the SSL/TLS context + \brief The wolfTLSv1_2_client_method() function is used to indicate + that the application is a client and will only support the TLS 1.2 + protocol. This function allocates memory for and initializes a new + wolfSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). - - \return * If successful, the call will return a pointer to the newly + + \return * If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return FAIL If memory allocation fails when calling XMALLOC, the failure - value of the underlying malloc() implementation will be returned + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters. - + _Example_ \code #include - + WOLFSSL_METHOD* method; WOLFSSL_CTX* ctx; @@ -372,7 +372,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_2_server_method(void); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfSSLv3_client_method \sa wolfTLSv1_client_method \sa wolfTLSv1_1_client_method @@ -385,24 +385,24 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_2_client_method(void); /*! \ingroup Setup - \brief The wolfDTLSv1_client_method() function is used to indicate that - the application is a client and will only support the DTLS 1.0 protocol. - This function allocates memory for and initializes a new - wolfSSL_METHOD structure to be used when creating the SSL/TLS context - with wolfSSL_CTX_new(). This function is only available when wolfSSL has - been compiled with DTLS support (--enable-dtls, + \brief The wolfDTLSv1_client_method() function is used to indicate that + the application is a client and will only support the DTLS 1.0 protocol. + This function allocates memory for and initializes a new + wolfSSL_METHOD structure to be used when creating the SSL/TLS context + with wolfSSL_CTX_new(). This function is only available when wolfSSL has + been compiled with DTLS support (--enable-dtls, or by defining wolfSSL_DTLS). - - \return * If successful, the call will return a pointer to the newly + + \return * If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return FAIL If memory allocation fails when calling XMALLOC, the failure - value of the underlying malloc() implementation will be returned + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters. - + _Example_ - \code + \code WOLFSSL_METHOD* method; WOLFSSL_CTX* ctx; @@ -414,7 +414,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfTLSv1_2_client_method(void); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfSSLv3_client_method \sa wolfTLSv1_client_method \sa wolfTLSv1_1_client_method @@ -427,24 +427,24 @@ WOLFSSL_API WOLFSSL_METHOD *wolfDTLSv1_client_method(void); /*! \ingroup Setup - \brief The wolfDTLSv1_server_method() function is used to indicate - that the application is a server and will only support the DTLS 1.0 - protocol. This function allocates memory for and initializes a - new wolfSSL_METHOD structure to be used when creating the SSL/TLS - context with wolfSSL_CTX_new(). This function is only available - when wolfSSL has been compiled with DTLS support (--enable-dtls, + \brief The wolfDTLSv1_server_method() function is used to indicate + that the application is a server and will only support the DTLS 1.0 + protocol. This function allocates memory for and initializes a + new wolfSSL_METHOD structure to be used when creating the SSL/TLS + context with wolfSSL_CTX_new(). This function is only available + when wolfSSL has been compiled with DTLS support (--enable-dtls, or by defining wolfSSL_DTLS). - - \return * If successful, the call will return a pointer to the newly + + \return * If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return FAIL If memory allocation fails when calling XMALLOC, the failure - value of the underlying malloc() implementation will be returned + \return FAIL If memory allocation fails when calling XMALLOC, the failure + value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters. - + _Example_ - \code + \code WOLFSSL_METHOD* method; WOLFSSL_CTX* ctx; @@ -456,7 +456,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfDTLSv1_client_method(void); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfSSLv3_server_method \sa wolfTLSv1_server_method \sa wolfTLSv1_1_server_method @@ -467,13 +467,13 @@ WOLFSSL_API WOLFSSL_METHOD *wolfDTLSv1_client_method(void); WOLFSSL_API WOLFSSL_METHOD *wolfDTLSv1_server_method(void); /*! - \brief This function creates and initializes a WOLFSSL_METHOD for the + \brief This function creates and initializes a WOLFSSL_METHOD for the server side. - + \return This function returns a WOLFSSL_METHOD pointer. - + \param none No parameters. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfDTLSv1_2_server_method()); @@ -488,19 +488,19 @@ WOLFSSL_API WOLFSSL_METHOD *wolfDTLSv1_2_server_method(void); /*! \ingroup Setup - \brief Since there is some differences between the first release and - newer versions of chacha-poly AEAD construction we have added an option - to communicate with servers/clients using the older version. By default + \brief Since there is some differences between the first release and + newer versions of chacha-poly AEAD construction we have added an option + to communicate with servers/clients using the older version. By default wolfSSL uses the new version. - + \return 0 upon success - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param value whether or not to use the older version of setting up the - information for poly1305. Passing a flag value of 1 indicates yes use the - old poly AEAD, to switch back to using the new version pass a flag value + \param value whether or not to use the older version of setting up the + information for poly1305. Passing a flag value of 1 indicates yes use the + old poly AEAD, to switch back to using the new version pass a flag value of 0. - + _Example_ \code int ret = 0; @@ -512,26 +512,26 @@ WOLFSSL_API WOLFSSL_METHOD *wolfDTLSv1_2_server_method(void); // failed to set poly1305 AEAD version } \endcode - + \sa none */ WOLFSSL_API int wolfSSL_use_old_poly(WOLFSSL*, int); /*! - \brief The wolfSSL_dtls_import() function is used to parse in a serialized - session state. This allows for picking up the connection after the + \brief The wolfSSL_dtls_import() function is used to parse in a serialized + session state. This allows for picking up the connection after the handshake has been completed. - - \return Success If successful, the amount of the buffer read will be + + \return Success If successful, the amount of the buffer read will be returned. \return Failure All unsuccessful return values will be less than 0. - \return VERSION_ERROR If a version mismatch is found ie DTLS v1 and ctx + \return VERSION_ERROR If a version mismatch is found ie DTLS v1 and ctx was set up for DTLS v1.2 then VERSION_ERROR is returned. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param buf serialized session to import. \param sz size of serialized session buffer. - + _Example_ \code WOLFSSL* ssl; @@ -550,7 +550,7 @@ WOLFSSL_API int wolfSSL_use_old_poly(WOLFSSL*, int); ret = wolfSSL_write(ssl) and wolfSSL_read(ssl); ... \endcode - + \sa wolfSSL_new \sa wolfSSL_CTX_new \sa wolfSSL_CTX_dtls_set_export @@ -559,23 +559,23 @@ WOLFSSL_API int wolfSSL_dtls_import(WOLFSSL* ssl, unsigned char* buf, unsigned int sz); /*! - \brief The wolfSSL_CTX_dtls_set_export() function is used to set - the callback function for exporting a session. It is allowed to - pass in NULL as the parameter func to clear the export function - previously stored. Used on the server side and is called immediately + \brief The wolfSSL_CTX_dtls_set_export() function is used to set + the callback function for exporting a session. It is allowed to + pass in NULL as the parameter func to clear the export function + previously stored. Used on the server side and is called immediately after handshake is completed. - + \return SSL_SUCCESS upon success. \return BAD_FUNC_ARG If null or not expected arguments are passed in - - \param ctx a pointer to a WOLFSSL_CTX structure, created + + \param ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new(). \param func wc_dtls_export function to use when exporting a session. - + _Example_ \code int send_session(WOLFSSL* ssl, byte* buf, word32 sz, void* userCtx); - // body of send session (wc_dtls_export) that passses + // body of send session (wc_dtls_export) that passses // buf (serialized session) to destination WOLFSSL_CTX* ctx; int ret; @@ -588,7 +588,7 @@ WOLFSSL_API int wolfSSL_dtls_import(WOLFSSL* ssl, unsigned char* buf, ret = wolfSSL_accept(ssl); ... \endcode - + \sa wolfSSL_new \sa wolfSSL_CTX_new \sa wolfSSL_dtls_set_export @@ -598,21 +598,21 @@ WOLFSSL_API int wolfSSL_CTX_dtls_set_export(WOLFSSL_CTX* ctx, wc_dtls_export func); /*! - \brief The wolfSSL_dtls_set_export() function is used to set the callback - function for exporting a session. It is allowed to pass in NULL as the - parameter func to clear the export function previously stored. Used on + \brief The wolfSSL_dtls_set_export() function is used to set the callback + function for exporting a session. It is allowed to pass in NULL as the + parameter func to clear the export function previously stored. Used on the server side and is called immediately after handshake is completed. - + \return SSL_SUCCESS upon success. \return BAD_FUNC_ARG If null or not expected arguments are passed in - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param func wc_dtls_export function to use when exporting a session. - + _Example_ \code int send_session(WOLFSSL* ssl, byte* buf, word32 sz, void* userCtx); - // body of send session (wc_dtls_export) that passses + // body of send session (wc_dtls_export) that passses // buf (serialized session) to destination WOLFSSL* ssl; int ret; @@ -625,7 +625,7 @@ WOLFSSL_API int wolfSSL_CTX_dtls_set_export(WOLFSSL_CTX* ctx, ret = wolfSSL_accept(ssl); ... \endcode - + \sa wolfSSL_new \sa wolfSSL_CTX_new \sa wolfSSL_CTX_dtls_set_export @@ -633,21 +633,21 @@ WOLFSSL_API int wolfSSL_CTX_dtls_set_export(WOLFSSL_CTX* ctx, WOLFSSL_API int wolfSSL_dtls_set_export(WOLFSSL* ssl, wc_dtls_export func); /*! - \brief The wolfSSL_dtls_export() function is used to serialize a - WOLFSSL session into the provided buffer. Allows for less memory - overhead than using a function callback for sending a session and - choice over when the session is serialized. If buffer is NULL when - passed to function then sz will be set to the size of buffer needed + \brief The wolfSSL_dtls_export() function is used to serialize a + WOLFSSL session into the provided buffer. Allows for less memory + overhead than using a function callback for sending a session and + choice over when the session is serialized. If buffer is NULL when + passed to function then sz will be set to the size of buffer needed for serializing the WOLFSSL session. - - \return Success If successful, the amount of the buffer used will + + \return Success If successful, the amount of the buffer used will be returned. \return Failure All unsuccessful return values will be less than 0. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param buf buffer to hold serialized session. \param sz size of buffer. - + _Example_ \code WOLFSSL* ssl; @@ -661,7 +661,7 @@ WOLFSSL_API int wolfSSL_dtls_set_export(WOLFSSL* ssl, wc_dtls_export func); } ... \endcode - + \sa wolfSSL_new \sa wolfSSL_CTX_new \sa wolfSSL_CTX_dtls_set_export @@ -671,33 +671,33 @@ WOLFSSL_API int wolfSSL_dtls_export(WOLFSSL* ssl, unsigned char* buf, unsigned int* sz); /*! - \brief This function is used to set aside static memory for a CTX. Memory - set aside is then used for the CTX’s lifetime and for any SSL objects - created from the CTX. By passing in a NULL ctx pointer and a - wolfSSL_method_func function the creation of the CTX itself will also - use static memory. wolfSSL_method_func has the function signature of - WOLFSSL_METHOD* (*wolfSSL_method_func)(void* heap);. Passing in 0 for max - makes it behave as if not set and no max concurrent use restrictions is - in place. The flag value passed in determines how the memory is used and - behavior while operating. Available flags are the following: 0 - default - general memory, WOLFMEM_IO_POOL - used for input/output buffer when - sending receiving messages and overrides general memory, so all memory - in buffer passed in is used for IO, WOLFMEM_IO_FIXED - same as - WOLFMEM_IO_POOL but each SSL now keeps two buffers to themselves for - their lifetime, WOLFMEM_TRACK_STATS - each SSL keeps track of memory + \brief This function is used to set aside static memory for a CTX. Memory + set aside is then used for the CTX’s lifetime and for any SSL objects + created from the CTX. By passing in a NULL ctx pointer and a + wolfSSL_method_func function the creation of the CTX itself will also + use static memory. wolfSSL_method_func has the function signature of + WOLFSSL_METHOD* (*wolfSSL_method_func)(void* heap);. Passing in 0 for max + makes it behave as if not set and no max concurrent use restrictions is + in place. The flag value passed in determines how the memory is used and + behavior while operating. Available flags are the following: 0 - default + general memory, WOLFMEM_IO_POOL - used for input/output buffer when + sending receiving messages and overrides general memory, so all memory + in buffer passed in is used for IO, WOLFMEM_IO_FIXED - same as + WOLFMEM_IO_POOL but each SSL now keeps two buffers to themselves for + their lifetime, WOLFMEM_TRACK_STATS - each SSL keeps track of memory stats while running. - + \return SSL_SUCCESS upon success. \return SSL_FAILURE upon failure. - + \param ctx address of pointer to a WOLFSSL_CTX structure. - \param method function to create protocol. (should be NULL if ctx is not + \param method function to create protocol. (should be NULL if ctx is not also NULL) \param buf memory to use for all operations. \param sz size of memory buffer being passed in. \param flag type of memory. \param max max concurrent operations. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -711,20 +711,20 @@ WOLFSSL_API int wolfSSL_dtls_export(WOLFSSL* ssl, unsigned char* buf, ... // create ctx also using static memory, start with general memory to use ctx = NULL: - ret = wolfSSL_CTX_load_static_memory(&ctx, wolfSSLv23_server_method_ex, + ret = wolfSSL_CTX_load_static_memory(&ctx, wolfSSLv23_server_method_ex, memory, memorySz, 0, MAX_CONCURRENT_HANDSHAKES); if (ret != SSL_SUCCESS) { // handle error case } // load in memory for use with IO - ret = wolfSSL_CTX_load_static_memory(&ctx, NULL, IO, IOSz, flag, + ret = wolfSSL_CTX_load_static_memory(&ctx, NULL, IO, IOSz, flag, MAX_CONCURRENT_IO); if (ret != SSL_SUCCESS) { // handle error case } ... \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_is_static_memory \sa wolfSSL_is_static_memory @@ -735,16 +735,16 @@ WOLFSSL_API int wolfSSL_CTX_load_static_memory(WOLFSSL_CTX** ctx, int flag, int max); /*! - \brief This function does not change any of the connections behavior + \brief This function does not change any of the connections behavior and is used only for gathering information about the static memory usage. - + \return 1 is returned if using static memory for the CTX is true. \return 0 is returned if not using static memory. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). \param mem_stats structure to hold information about static memory usage. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -762,7 +762,7 @@ WOLFSSL_API int wolfSSL_CTX_load_static_memory(WOLFSSL_CTX** ctx, } … \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_load_static_memory \sa wolfSSL_is_static_memory @@ -771,15 +771,15 @@ WOLFSSL_API int wolfSSL_CTX_is_static_memory(WOLFSSL_CTX* ctx, WOLFSSL_MEM_STATS* mem_stats); /*! - \brief wolfSSL_is_static_memory is used to gather information about - a SSL’s static memory usage. The return value indicates if static - memory is being used and WOLFSSL_MEM_CONN_STATS will be filled out - if and only if the flag WOLFMEM_TRACK_STATS was passed to the parent + \brief wolfSSL_is_static_memory is used to gather information about + a SSL’s static memory usage. The return value indicates if static + memory is being used and WOLFSSL_MEM_CONN_STATS will be filled out + if and only if the flag WOLFMEM_TRACK_STATS was passed to the parent CTX when loading in static memory. - + \return 1 is returned if using static memory for the CTX is true. \return 0 is returned if not using static memory. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param mem_stats structure to contain static memory usage. @@ -796,7 +796,7 @@ WOLFSSL_API int wolfSSL_CTX_is_static_memory(WOLFSSL_CTX* ctx, } ... \endcode - + \sa wolfSSL_new \sa wolfSSL_CTX_is_static_memory */ @@ -806,26 +806,26 @@ WOLFSSL_API int wolfSSL_is_static_memory(WOLFSSL* ssl, /*! \ingroup CertsKeys - \brief This function loads a certificate file into the SSL context - (WOLFSSL_CTX). The file is provided by the file argument. The - format argument specifies the format type of the file, either - SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples + \brief This function loads a certificate file into the SSL context + (WOLFSSL_CTX). The file is provided by the file argument. The + format argument specifies the format type of the file, either + SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage. - + \return SSL_SUCCESS upon success. - \return SSL_FAILURE If the function call fails, possible causes might - include the file is in the wrong format, or the wrong format has been - given using the “format” argument, file doesn’t exist, can’t be read, - or is corrupted, an out of memory condition occurs, Base16 decoding + \return SSL_FAILURE If the function call fails, possible causes might + include the file is in the wrong format, or the wrong format has been + given using the “format” argument, file doesn’t exist, can’t be read, + or is corrupted, an out of memory condition occurs, Base16 decoding fails on the file. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new() - \param file a pointer to the name of the file containing the certificate + \param file a pointer to the name of the file containing the certificate to be loaded into the wolfSSL SSL context. - \param format - format of the certificates pointed to by file. Possible + \param format - format of the certificates pointed to by file. Possible options are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + _Example_ \code int ret = 0; @@ -838,7 +838,7 @@ WOLFSSL_API int wolfSSL_is_static_memory(WOLFSSL* ssl, } ... \endcode - + \sa wolfSSL_CTX_use_certificate_buffer \sa wolfSSL_use_certificate_file \sa wolfSSL_use_certificate_buffer @@ -848,20 +848,20 @@ WOLFSSL_API int wolfSSL_CTX_use_certificate_file(WOLFSSL_CTX*, const char*, int) /*! \ingroup CertsKeys - \brief This function loads a private key file into the SSL context - (WOLFSSL_CTX). The file is provided by the file argument. The format - argument specifies the format type of the file - SSL_FILETYPE_ASN1or + \brief This function loads a private key file into the SSL context + (WOLFSSL_CTX). The file is provided by the file argument. The format + argument specifies the format type of the file - SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM. Please see the examples for proper usage. - + \return SSL_SUCCESS upon success. - \return SSL_FAILURE The file is in the wrong format, or the wrong format - has been given using the “format” argument. The file doesn’t exist, can’t - be read, or is corrupted. An out of memory condition occurs. Base16 - decoding fails on the file. The key file is encrypted but no password + \return SSL_FAILURE The file is in the wrong format, or the wrong format + has been given using the “format” argument. The file doesn’t exist, can’t + be read, or is corrupted. An out of memory condition occurs. Base16 + decoding fails on the file. The key file is encrypted but no password is provided. - + \param none No parameters. - + _Example_ \code int ret = 0; @@ -874,7 +874,7 @@ WOLFSSL_API int wolfSSL_CTX_use_certificate_file(WOLFSSL_CTX*, const char*, int) } ... \endcode - + \sa wolfSSL_CTX_use_PrivateKey_buffer \sa wolfSSL_use_PrivateKey_file \sa wolfSSL_use_PrivateKey_buffer @@ -884,40 +884,40 @@ WOLFSSL_API int wolfSSL_CTX_use_PrivateKey_file(WOLFSSL_CTX*, const char*, int); /*! \ingroup CertsKeys - \brief This function loads PEM-formatted CA certificate files into the SSL - context (WOLFSSL_CTX). These certificates will be treated as trusted root - certificates and used to verify certs received from peers during the SSL - handshake. The root certificate file, provided by the file argument, may - be a single certificate or a file containing multiple certificates. - If multiple CA certs are included in the same file, wolfSSL will load them - in the same order they are presented in the file. The path argument is - a pointer to the name of a directory that contains certificates of - trusted root CAs. If the value of file is not NULL, path may be specified - as NULL if not needed. If path is specified and NO_WOLFSSL_DIR was not - defined when building the library, wolfSSL will load all CA certificates - located in the given directory. This function will attempt to load all - files in the directory and locate any files with the PEM header + \brief This function loads PEM-formatted CA certificate files into the SSL + context (WOLFSSL_CTX). These certificates will be treated as trusted root + certificates and used to verify certs received from peers during the SSL + handshake. The root certificate file, provided by the file argument, may + be a single certificate or a file containing multiple certificates. + If multiple CA certs are included in the same file, wolfSSL will load them + in the same order they are presented in the file. The path argument is + a pointer to the name of a directory that contains certificates of + trusted root CAs. If the value of file is not NULL, path may be specified + as NULL if not needed. If path is specified and NO_WOLFSSL_DIR was not + defined when building the library, wolfSSL will load all CA certificates + located in the given directory. This function will attempt to load all + files in the directory and locate any files with the PEM header “-----BEGIN CERTIFICATE-----”. Please see the examples for proper usage. - + \return SSL_SUCCESS up success. - \return SSL_FAILURE will be returned if ctx is NULL, or if both file and + \return SSL_FAILURE will be returned if ctx is NULL, or if both file and path are NULL. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - \return BUFFER_E will be returned if a chain buffer is bigger than the + \return BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer. - \return BAD_PATH_ERROR will be returned if opendir() fails when trying + \return BAD_PATH_ERROR will be returned if opendir() fails when trying to open path. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). - \param file pointer to name of the file containing PEM-formatted CA + \param file pointer to name of the file containing PEM-formatted CA certificates. - \param path pointer to the name of a directory to load PEM-formatted + \param path pointer to the name of a directory to load PEM-formatted certificates from. - + _Example_ \code int ret = 0; @@ -929,7 +929,7 @@ WOLFSSL_API int wolfSSL_CTX_use_PrivateKey_file(WOLFSSL_CTX*, const char*, int); } ... \endcode - + \sa wolfSSL_CTX_load_verify_buffer \sa wolfSSL_CTX_use_certificate_file \sa wolfSSL_CTX_use_PrivateKey_file @@ -945,41 +945,41 @@ WOLFSSL_API int wolfSSL_CTX_load_verify_locations(WOLFSSL_CTX*, const char*, /*! \ingroup Setup - \brief This function loads a certificate to use for verifying a peer - when performing a TLS/SSL handshake. The peer certificate sent during the - handshake is compared by using the SKID when available and the signature. - If these two things do not match then any loaded CAs are used. Feature is - enabled by defining the macro WOLFSSL_TRUST_PEER_CERT. Please see the + \brief This function loads a certificate to use for verifying a peer + when performing a TLS/SSL handshake. The peer certificate sent during the + handshake is compared by using the SKID when available and the signature. + If these two things do not match then any loaded CAs are used. Feature is + enabled by defining the macro WOLFSSL_TRUST_PEER_CERT. Please see the examples for proper usage. \return SSL_SUCCES upon success. - \return SSL_FAILURE will be returned if ctx is NULL, or if both file and + \return SSL_FAILURE will be returned if ctx is NULL, or if both file and type are invalid. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param file pointer to name of the file containing certificates - \param type type of certificate being loaded ie SSL_FILETYPE_ASN1 + \param type type of certificate being loaded ie SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + _Example_ \code int ret = 0; WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); ... - ret = wolfSSL_CTX_trust_peer_cert(ctx, “./peer-cert.pem”, + ret = wolfSSL_CTX_trust_peer_cert(ctx, “./peer-cert.pem”, SSL_FILETYPE_PEM); if (ret != SSL_SUCCESS) { // error loading trusted peer cert } ... \endcode - + \sa wolfSSL_CTX_load_verify_buffer \sa wolfSSL_CTX_use_certificate_file \sa wolfSSL_CTX_use_PrivateKey_file @@ -996,24 +996,24 @@ WOLFSSL_API int wolfSSL_CTX_trust_peer_cert(WOLFSSL_CTX*, const char*, int); /*! \ingroup CertsKeys - \brief This function loads a chain of certificates into the SSL - context (WOLFSSL_CTX). The file containing the certificate chain - is provided by the file argument, and must contain PEM-formatted - certificates. This function will process up to MAX_CHAIN_DEPTH + \brief This function loads a chain of certificates into the SSL + context (WOLFSSL_CTX). The file containing the certificate chain + is provided by the file argument, and must contain PEM-formatted + certificates. This function will process up to MAX_CHAIN_DEPTH (default = 9, defined in internal.h) certificates, plus the subject cert. - + \return SSL_SUCCESS upon success - \return SSL_FAILURE If the function call fails, possible causes might - include the file is in the wrong format, or the wrong format has been - given using the “format” argument, file doesn’t exist, can’t be read, + \return SSL_FAILURE If the function call fails, possible causes might + include the file is in the wrong format, or the wrong format has been + given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new() - \param file a pointer to the name of the file containing the chain of - certificates to be loaded into the wolfSSL SSL context. Certificates + \param file a pointer to the name of the file containing the chain of + certificates to be loaded into the wolfSSL SSL context. Certificates must be in PEM format. - + _Example_ \code int ret = 0; @@ -1025,7 +1025,7 @@ WOLFSSL_API int wolfSSL_CTX_trust_peer_cert(WOLFSSL_CTX*, const char*, int); } ... \endcode - + \sa wolfSSL_CTX_use_certificate_file \sa wolfSSL_CTX_use_certificate_buffer \sa wolfSSL_use_certificate_file @@ -1036,27 +1036,27 @@ WOLFSSL_API int wolfSSL_CTX_use_certificate_chain_file(WOLFSSL_CTX *, /*! \ingroup openSSL - - \brief This function loads the private RSA key used in the SSL connection - into the SSL context (WOLFSSL_CTX). This function is only available when - wolfSSL has been compiled with the OpenSSL compatibility layer enabled - (--enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the - more-typically used wolfSSL_CTX_use_PrivateKey_file() function. The file - argument contains a pointer to the RSA private key file, in the format + + \brief This function loads the private RSA key used in the SSL connection + into the SSL context (WOLFSSL_CTX). This function is only available when + wolfSSL has been compiled with the OpenSSL compatibility layer enabled + (--enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the + more-typically used wolfSSL_CTX_use_PrivateKey_file() function. The file + argument contains a pointer to the RSA private key file, in the format specified by format. - + \return SSL_SUCCESS upon success. - \return SSL_FAILURE If the function call fails, possible causes might - include: The input key file is in the wrong format, or the wrong format - has been given using the “format” argument, file doesn’t exist, can’t + \return SSL_FAILURE If the function call fails, possible causes might + include: The input key file is in the wrong format, or the wrong format + has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new() - \param file a pointer to the name of the file containing the RSA private - key to be loaded into the wolfSSL SSL context, with format as specified + \param file a pointer to the name of the file containing the RSA private + key to be loaded into the wolfSSL SSL context, with format as specified by format. - \param format the encoding type of the RSA private key specified by file. + \param format the encoding type of the RSA private key specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1. _Example_ @@ -1071,7 +1071,7 @@ WOLFSSL_API int wolfSSL_CTX_use_certificate_chain_file(WOLFSSL_CTX *, } ... \endcode - + \sa wolfSSL_CTX_use_PrivateKey_buffer \sa wolfSSL_CTX_use_PrivateKey_file \sa wolfSSL_use_RSAPrivateKey_file @@ -1085,13 +1085,13 @@ WOLFSSL_API int wolfSSL_CTX_use_RSAPrivateKey_file(WOLFSSL_CTX*, const char*, in \brief This function returns the maximum chain depth allowed, which is 9 by default, for a valid session i.e. there is a non-null session object (ssl). - - \return MAX_CHAIN_DEPTH returned if the WOLFSSL_CTX structure is not + + \return MAX_CHAIN_DEPTH returned if the WOLFSSL_CTX structure is not NULL. By default the value is 9. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -1105,7 +1105,7 @@ WOLFSSL_API int wolfSSL_CTX_use_RSAPrivateKey_file(WOLFSSL_CTX*, const char*, in // The verified depth is smaller or equal to the expected value } \endcode - + \sa wolfSSL_CTX_get_verify_depth */ WOLFSSL_API long wolfSSL_get_verify_depth(WOLFSSL* ssl); @@ -1113,16 +1113,16 @@ WOLFSSL_API long wolfSSL_get_verify_depth(WOLFSSL* ssl); /*! \ingroup Setup - \brief This function gets the certificate chaining depth using the + \brief This function gets the certificate chaining depth using the CTX structure. - - \return MAX_CHAIN_DEPTH returned if the CTX struct is not NULL. The + + \return MAX_CHAIN_DEPTH returned if the CTX struct is not NULL. The constant representation of the max certificate chain peer depth. \return BAD_FUNC_ARG returned if the CTX structure is NULL. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - + _Example_ \code WOLFSSL_METHOD method; // protocol method @@ -1136,7 +1136,7 @@ WOLFSSL_API long wolfSSL_get_verify_depth(WOLFSSL* ssl); // Handle an unexpected depth } \endcode - + \sa wolfSSL_CTX_use_certificate_chain_file \sa wolfSSL_get_verify_depth */ @@ -1144,25 +1144,25 @@ WOLFSSL_API long wolfSSL_CTX_get_verify_depth(WOLFSSL_CTX* ctx); /*! \ingroup openSSL - - \brief This function loads a certificate file into the SSL session - (WOLFSSL structure). The certificate file is provided by the file - argument. The format argument specifies the format type of the file - + + \brief This function loads a certificate file into the SSL session + (WOLFSSL structure). The certificate file is provided by the file + argument. The format argument specifies the format type of the file - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + \return SSL_SUCCESS upon success - \return SSL_FAILURE If the function call fails, possible causes might - include: The file is in the wrong format, or the wrong format has been - given using the “format” argument, file doesn’t exist, can’t be read, - or is corrupted, an out of memory condition occurs, Base16 decoding + \return SSL_FAILURE If the function call fails, possible causes might + include: The file is in the wrong format, or the wrong format has been + given using the “format” argument, file doesn’t exist, can’t be read, + or is corrupted, an out of memory condition occurs, Base16 decoding fails on the file - + \param ssl a pointer to a WOLFSSL structure, created with wolfSSL_new(). \param file a pointer to the name of the file containing the certificate to be loaded into the wolfSSL SSL session, with format as specified by format. - \param format the encoding type of the certificate specified by file. + \param format the encoding type of the certificate specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1. - + _Example_ \code int ret = 0; @@ -1184,23 +1184,23 @@ WOLFSSL_API int wolfSSL_use_certificate_file(WOLFSSL*, const char*, int); /*! \ingroup openSSL - - \brief This function loads a private key file into the SSL session - (WOLFSSL structure). The key file is provided by the file argument. - The format argument specifies the format type of the file - + + \brief This function loads a private key file into the SSL session + (WOLFSSL structure). The key file is provided by the file argument. + The format argument specifies the format type of the file - SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + \return SSL_SUCCESS upon success. - \return SSL_FAILURE If the function call fails, possible causes might - include: The file is in the wrong format, or the wrong format has been - given using the “format” argument, The file doesn’t exist, can’t be read, - or is corrupted, An out of memory condition occurs, Base16 decoding + \return SSL_FAILURE If the function call fails, possible causes might + include: The file is in the wrong format, or the wrong format has been + given using the “format” argument, The file doesn’t exist, can’t be read, + or is corrupted, An out of memory condition occurs, Base16 decoding fails on the file, The key file is encrypted but no password is provided - + \param ssl a pointer to a WOLFSSL structure, created with wolfSSL_new(). - \param file a pointer to the name of the file containing the key file to + \param file a pointer to the name of the file containing the key file to be loaded into the wolfSSL SSL session, with format as specified by format. - \param format the encoding type of the key specified by file. Possible + \param format the encoding type of the key specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1. _Example_ @@ -1215,7 +1215,7 @@ WOLFSSL_API int wolfSSL_use_certificate_file(WOLFSSL*, const char*, int); } ... \endcode - + \sa wolfSSL_CTX_use_PrivateKey_buffer \sa wolfSSL_CTX_use_PrivateKey_file \sa wolfSSL_use_PrivateKey_buffer @@ -1224,23 +1224,23 @@ WOLFSSL_API int wolfSSL_use_PrivateKey_file(WOLFSSL*, const char*, int); /*! \ingroup openSSL - - \brief This function loads a chain of certificates into the SSL - session (WOLFSSL structure). The file containing the certificate - chain is provided by the file argument, and must contain PEM-formatted - certificates. This function will process up to MAX_CHAIN_DEPTH - (default = 9, defined in internal.h) certificates, plus the + + \brief This function loads a chain of certificates into the SSL + session (WOLFSSL structure). The file containing the certificate + chain is provided by the file argument, and must contain PEM-formatted + certificates. This function will process up to MAX_CHAIN_DEPTH + (default = 9, defined in internal.h) certificates, plus the subject certificate. - + \return SSL_SUCCESS upon success. - \return SSL_FAILURE If the function call fails, possible causes - might include: The file is in the wrong format, or the wrong format - has been given using the “format” argument, file doesn’t exist, + \return SSL_FAILURE If the function call fails, possible causes + might include: The file is in the wrong format, or the wrong format + has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new() - \param file a pointer to the name of the file containing the chain - of certificates to be loaded into the wolfSSL SSL session. + \param file a pointer to the name of the file containing the chain + of certificates to be loaded into the wolfSSL SSL session. Certificates must be in PEM format. _Example_ @@ -1254,7 +1254,7 @@ WOLFSSL_API int wolfSSL_use_PrivateKey_file(WOLFSSL*, const char*, int); } ... \endcode - + \sa wolfSSL_CTX_use_certificate_chain_file \sa wolfSSL_CTX_use_certificate_chain_buffer \sa wolfSSL_use_certificate_chain_buffer @@ -1263,29 +1263,29 @@ WOLFSSL_API int wolfSSL_use_certificate_chain_file(WOLFSSL*, const char *file); /*! \ingroup openSSL - - \brief This function loads the private RSA key used in the SSL - connection into the SSL session (WOLFSSL structure). This - function is only available when wolfSSL has been compiled with - the OpenSSL compatibility layer enabled (--enable-opensslExtra, - #define OPENSSL_EXTRA), and is identical to the more-typically - used wolfSSL_use_PrivateKey_file() function. The file argument - contains a pointer to the RSA private key file, in the format + + \brief This function loads the private RSA key used in the SSL + connection into the SSL session (WOLFSSL structure). This + function is only available when wolfSSL has been compiled with + the OpenSSL compatibility layer enabled (--enable-opensslExtra, + #define OPENSSL_EXTRA), and is identical to the more-typically + used wolfSSL_use_PrivateKey_file() function. The file argument + contains a pointer to the RSA private key file, in the format specified by format. - + \return SSL_SUCCESS upon success - \return SSL_FAILURE If the function call fails, possible causes might - include: The input key file is in the wrong format, or the wrong format - has been given using the “format” argument, file doesn’t exist, can’t + \return SSL_FAILURE If the function call fails, possible causes might + include: The input key file is in the wrong format, or the wrong format + has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new() - \param file a pointer to the name of the file containing the RSA private - key to be loaded into the wolfSSL SSL session, with format as specified + \param file a pointer to the name of the file containing the RSA private + key to be loaded into the wolfSSL SSL session, with format as specified by format. - \parm format the encoding type of the RSA private key specified by file. + \parm format the encoding type of the RSA private key specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1. - + _Example_ \code int ret = 0; @@ -1298,7 +1298,7 @@ WOLFSSL_API int wolfSSL_use_certificate_chain_file(WOLFSSL*, const char *file); } ... \endcode - + \sa wolfSSL_CTX_use_RSAPrivateKey_file \sa wolfSSL_CTX_use_PrivateKey_buffer \sa wolfSSL_CTX_use_PrivateKey_file @@ -1310,32 +1310,32 @@ WOLFSSL_API int wolfSSL_use_RSAPrivateKey_file(WOLFSSL*, const char*, int); /*! \ingroup CertsKeys - \brief This function is similar to wolfSSL_CTX_load_verify_locations, - but allows the loading of DER-formatted CA files into the SSL context - (WOLFSSL_CTX). It may still be used to load PEM-formatted CA files as - well. These certificates will be treated as trusted root certificates - and used to verify certs received from peers during the SSL handshake. - The root certificate file, provided by the file argument, may be a single - certificate or a file containing multiple certificates. If multiple CA - certs are included in the same file, wolfSSL will load them in the same - order they are presented in the file. The format argument specifies the - format which the certificates are in either, SSL_FILETYPE_PEM or - SSL_FILETYPE_ASN1 (DER). Unlike wolfSSL_CTX_load_verify_locations, - this function does not allow the loading of CA certificates from a given - directory path. Note that this function is only available when the wolfSSL + \brief This function is similar to wolfSSL_CTX_load_verify_locations, + but allows the loading of DER-formatted CA files into the SSL context + (WOLFSSL_CTX). It may still be used to load PEM-formatted CA files as + well. These certificates will be treated as trusted root certificates + and used to verify certs received from peers during the SSL handshake. + The root certificate file, provided by the file argument, may be a single + certificate or a file containing multiple certificates. If multiple CA + certs are included in the same file, wolfSSL will load them in the same + order they are presented in the file. The format argument specifies the + format which the certificates are in either, SSL_FILETYPE_PEM or + SSL_FILETYPE_ASN1 (DER). Unlike wolfSSL_CTX_load_verify_locations, + this function does not allow the loading of CA certificates from a given + directory path. Note that this function is only available when the wolfSSL library was compiled with WOLFSSL_DER_LOAD defined. \return SSL_SUCCESS upon success. \return SSL_FAILURE upon failure. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new() - \param file a pointer to the name of the file containing the CA - certificates to be loaded into the wolfSSL SSL context, with format + \param file a pointer to the name of the file containing the CA + certificates to be loaded into the wolfSSL SSL context, with format as specified by format. - \param format the encoding type of the certificates specified by file. + \param format the encoding type of the certificates specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1. - + _Example_ \code int ret = 0; @@ -1348,7 +1348,7 @@ WOLFSSL_API int wolfSSL_use_RSAPrivateKey_file(WOLFSSL*, const char*, int); } ... \endcode - + \sa wolfSSL_CTX_load_verify_locations \sa wolfSSL_CTX_load_verify_buffer */ @@ -1358,27 +1358,27 @@ WOLFSSL_API int wolfSSL_CTX_der_load_verify_locations(WOLFSSL_CTX*, /*! \ingroup CertsKeys - \brief This function loads an NTRU private key file into the WOLFSSL - Context. It behaves like the normal version, only differing in its - ability to accept an NTRU raw key file. This function is needed since - the format of the file is different than the normal key file (buffer) + \brief This function loads an NTRU private key file into the WOLFSSL + Context. It behaves like the normal version, only differing in its + ability to accept an NTRU raw key file. This function is needed since + the format of the file is different than the normal key file (buffer) functions. Please see the examples for proper usage. - + \return SSL_SUCCES upon success. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - \return BUFFER_E will be returned if a chain buffer is bigger than the + \return BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer. - \return NO_PASSWORD will be returned if the key file is encrypted but + \return NO_PASSWORD will be returned if the key file is encrypted but no password is provided. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new() - \param file a pointer to the name of the file containing the NTRU + \param file a pointer to the name of the file containing the NTRU private key to be loaded into the wolfSSL SSL context. - + _Example_ \code int ret = 0; @@ -1390,7 +1390,7 @@ WOLFSSL_API int wolfSSL_CTX_der_load_verify_locations(WOLFSSL_CTX*, } ... \endcode - + \sa wolfSSL_CTX_load_verify_buffer \sa wolfSSL_CTX_use_certificate_buffer \sa wolfSSL_CTX_use_PrivateKey_buffer @@ -1404,17 +1404,17 @@ WOLFSSL_API int wolfSSL_CTX_use_NTRUPrivateKey_file(WOLFSSL_CTX*, const char*); /*! \ingroup Setup - \brief This function creates a new SSL context, taking a desired + \brief This function creates a new SSL context, taking a desired SSL/TLS protocol method for input. - - \return pointer If successful the call will return a pointer to the + + \return pointer If successful the call will return a pointer to the newly-created WOLFSSL_CTX. \return NULL upon failure. - - \param method pointer to the desired WOLFSSL_METHOD to use for the SSL - context. This is created using one of the wolfSSLvXX_XXXX_method() + + \param method pointer to the desired WOLFSSL_METHOD to use for the SSL + context. This is created using one of the wolfSSLvXX_XXXX_method() functions to specify SSL/TLS/DTLS protocol level. - + _Example_ \code WOLFSSL_CTX* ctx = 0; @@ -1430,7 +1430,7 @@ WOLFSSL_API int wolfSSL_CTX_use_NTRUPrivateKey_file(WOLFSSL_CTX*, const char*); // context creation failed } \endcode - + \sa wolfSSL_new */ WOLFSSL_API WOLFSSL_CTX* wolfSSL_CTX_new(WOLFSSL_METHOD*); @@ -1438,19 +1438,19 @@ WOLFSSL_API WOLFSSL_CTX* wolfSSL_CTX_new(WOLFSSL_METHOD*); /*! \ingroup Setup - \brief This function creates a new SSL session, taking an already + \brief This function creates a new SSL session, taking an already created SSL context as input. - - \return * If successful the call will return a pointer to the + + \return * If successful the call will return a pointer to the newly-created wolfSSL structure. \return NULL Upon failure. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). - + _Example_ \code #include - + WOLFSSL* ssl = NULL; WOLFSSL_CTX* ctx = 0; @@ -1464,7 +1464,7 @@ WOLFSSL_API WOLFSSL_CTX* wolfSSL_CTX_new(WOLFSSL_METHOD*); // SSL object creation failed } \endcode - + \sa wolfSSL_CTX_new */ WOLFSSL_API WOLFSSL* wolfSSL_new(WOLFSSL_CTX*); @@ -1472,16 +1472,16 @@ WOLFSSL_API WOLFSSL* wolfSSL_new(WOLFSSL_CTX*); /*! \ingroup Setup - \brief This function assigns a file descriptor (fd) as the - input/output facility for the SSL connection. Typically this will be + \brief This function assigns a file descriptor (fd) as the + input/output facility for the SSL connection. Typically this will be a socket file descriptor. - + \return SSL_SUCCESS upon success. \return Bad_FUNC_ARG upon failure. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param fd file descriptor to use with SSL/TLS connection. - + _Example_ \code int sockfd; @@ -1493,7 +1493,7 @@ WOLFSSL_API WOLFSSL* wolfSSL_new(WOLFSSL_CTX*); // failed to set SSL file descriptor } \endcode - + \sa wolfSSL_CTX_SetIOSend \sa wolfSSL_CTX_SetIORecv \sa wolfSSL_SetIOReadCtx @@ -1508,14 +1508,14 @@ WOLFSSL_API int wolfSSL_set_fd (WOLFSSL*, int); \return string Success \return 0 Priority is either out of bounds or not valid. - + \param priority Integer representing the priority level of a cipher. - + _Example_ \code printf("The cipher at 1 is %s", wolfSSL_get_cipher_list(1)); \endcode - + \sa wolfSSL_CIPHER_get_name \sa wolfSSL_get_current_cipher */ @@ -1525,16 +1525,16 @@ WOLFSSL_API char* wolfSSL_get_cipher_list(int priority); \ingroup IO \brief This function gets the ciphers enabled in wolfSSL. - + \return SSL_SUCCESS returned if the function executed without error. - \return BAD_FUNC_ARG returned if the buf parameter was NULL or if the + \return BAD_FUNC_ARG returned if the buf parameter was NULL or if the len argument was less than or equal to zero. - \return BUFFER_E returned if the buffer is not large enough and + \return BUFFER_E returned if the buffer is not large enough and will overflow. - + \param buf a char pointer representing the buffer. \param len the length of the buffer. - + _Example_ \code static void ShowCiphers(void){ @@ -1546,7 +1546,7 @@ WOLFSSL_API char* wolfSSL_get_cipher_list(int priority); } } \endcode - + \sa GetCipherNames \sa wolfSSL_get_cipher_list \sa ShowCiphers @@ -1556,15 +1556,15 @@ WOLFSSL_API int wolfSSL_get_ciphers(char*, int); /*! \ingroup IO - \brief This function gets the cipher name in the format DHE-RSA by + \brief This function gets the cipher name in the format DHE-RSA by passing through argument to wolfSSL_get_cipher_name_internal. - - \return string This function returns the string representation of the + + \return string This function returns the string representation of the cipher suite that was matched. \return NULL error or cipher not found. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -1579,7 +1579,7 @@ WOLFSSL_API int wolfSSL_get_ciphers(char*, int); printf(“%s\n”, cipherS); } \endcode - + \sa wolfSSL_CIPHER_get_name \sa wolfSSL_get_current_cipher \sa wolfSSL_get_cipher_name_internal @@ -1589,15 +1589,15 @@ WOLFSSL_API const char* wolfSSL_get_cipher_name(WOLFSSL* ssl); /*! \ingroup IO - \brief This function returns the file descriptor (fd) used as the - input/output facility for the SSL connection. Typically this + \brief This function returns the file descriptor (fd) used as the + input/output facility for the SSL connection. Typically this will be a socket file descriptor. - - \return fd If successful the call will return the SSL session file + + \return fd If successful the call will return the SSL session file descriptor. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - + _Example_ \code int sockfd; @@ -1606,7 +1606,7 @@ WOLFSSL_API const char* wolfSSL_get_cipher_name(WOLFSSL* ssl); sockfd = wolfSSL_get_fd(ssl); ... \endcode - + \sa wolfSSL_set_fd */ WOLFSSL_API int wolfSSL_get_fd(const WOLFSSL*); @@ -1616,24 +1616,24 @@ WOLFSSL_API int wolfSSL_get_fd(const WOLFSSL*); \brief This function informs the WOLFSSL object that the underlying I/O is non-blocking. After an application creates a WOLFSSL object, - if it will be used with a non-blocking socket, call + if it will be used with a non-blocking socket, call wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know - that receiving EWOULDBLOCK means that the recvfrom call would + that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out. - + \return none No return. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - \param nonblock value used to set non-blocking flag on WOLFSSL object. + \param nonblock value used to set non-blocking flag on WOLFSSL object. Use 1 to specify non-blocking, otherwise 0. - + _Example_ \code WOLFSSL* ssl = 0; ... wolfSSL_set_using_nonblock(ssl, 1); \endcode - + \sa wolfSSL_get_using_nonblock \sa wolfSSL_dtls_got_timeout \sa wolfSSL_dtls_get_current_timeout @@ -1643,19 +1643,19 @@ WOLFSSL_API void wolfSSL_set_using_nonblock(WOLFSSL*, int); /*! \ingroup IO - \brief This function allows the application to determine if wolfSSL is - using non-blocking I/O. If wolfSSL is using non-blocking I/O, this - function will return 1, otherwise 0. After an application creates a - WOLFSSL object, if it will be used with a non-blocking socket, call - wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know - that receiving EWOULDBLOCK means that the recvfrom call would block + \brief This function allows the application to determine if wolfSSL is + using non-blocking I/O. If wolfSSL is using non-blocking I/O, this + function will return 1, otherwise 0. After an application creates a + WOLFSSL object, if it will be used with a non-blocking socket, call + wolfSSL_set_using_nonblock() on it. This lets the WOLFSSL object know + that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out. - + \return 0 underlying I/O is blocking. \return 1 underlying I/O is non-blocking. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - + _Example_ \code int ret = 0; @@ -1667,7 +1667,7 @@ WOLFSSL_API void wolfSSL_set_using_nonblock(WOLFSSL*, int); } ... \endcode - + \sa wolfSSL_set_session */ WOLFSSL_API int wolfSSL_get_using_nonblock(WOLFSSL*); @@ -1675,32 +1675,32 @@ WOLFSSL_API int wolfSSL_get_using_nonblock(WOLFSSL*); /*! \ingroup IO - \brief This function writes sz bytes from the buffer, data, to the SSL - connection, ssl. If necessary, wolfSSL_write() will negotiate an SSL/TLS - session if the handshake has not already been performed yet by - wolfSSL_connect() or wolfSSL_accept(). wolfSSL_write() works with both - blocking and non-blocking I/O. When the underlying I/O is non-blocking, - wolfSSL_write() will return when the underlying I/O could not satisfy the - needs of wolfSSL_write() to continue. 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_write() when the underlying I/O is ready. If the underlying I/O - is blocking, wolfSSL_write() will only return once the buffer data of + \brief This function writes sz bytes from the buffer, data, to the SSL + connection, ssl. If necessary, wolfSSL_write() will negotiate an SSL/TLS + session if the handshake has not already been performed yet by + wolfSSL_connect() or wolfSSL_accept(). wolfSSL_write() works with both + blocking and non-blocking I/O. When the underlying I/O is non-blocking, + wolfSSL_write() will return when the underlying I/O could not satisfy the + needs of wolfSSL_write() to continue. 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_write() when the underlying I/O is ready. If the underlying I/O + is blocking, wolfSSL_write() will only return once the buffer data of size sz has been completely written or an error occurred. - + \return >0 the number of bytes written upon success. - \return 0 will be returned upon failure. Call wolfSSL_get_error() for + \return 0 will be returned upon failure. Call wolfSSL_get_error() for the specific error code. - \return SSL_FATAL_ERROR will be returned upon failure when either an error - occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or - SSL_ERROR_WANT_WRITE error was received and and the application needs to - call wolfSSL_write() again. Use wolfSSL_get_error() to get a specific + \return SSL_FATAL_ERROR will be returned upon failure when either an error + occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or + SSL_ERROR_WANT_WRITE error was received and and the application needs to + call wolfSSL_write() again. Use wolfSSL_get_error() to get a specific error code. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param data data buffer which will be sent to peer. \param sz size, in bytes, of data to send to the peer (data). - + _Example_ \code WOLFSSL* ssl = 0; @@ -1715,7 +1715,7 @@ WOLFSSL_API int wolfSSL_get_using_nonblock(WOLFSSL*); // wolfSSL_write() failed, call wolfSSL_get_error() } \endcode - + \sa wolfSSL_send \sa wolfSSL_read \sa wolfSSL_recv @@ -1725,39 +1725,39 @@ WOLFSSL_API int wolfSSL_write(WOLFSSL*, const void*, int); /*! \ingroup IO - \brief This function reads sz bytes from the SSL session (ssl) - internal read buffer into the buffer data. The bytes read are removed - from the internal receive buffer. If necessary wolfSSL_read() will - negotiate an SSL/TLS session if the handshake has not already been - performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS - protocol uses SSL records which have a maximum size of 16kB (the max - record size can be controlled by the MAX_RECORD_SIZE define in - /wolfssl/internal.h). As such, wolfSSL needs to read an - entire SSL record internally before it is able to process and decrypt the - record. Because of this, a call to wolfSSL_read() will only be able to - return the maximum buffer size which has been decrypted at the time of - calling. There may be additional not-yet-decrypted data waiting in the - internal wolfSSL receive buffer which will be retrieved and decrypted with - the next call to wolfSSL_read(). If sz is larger than the number of bytes - in the internal read buffer, SSL_read() will return the bytes available in - the internal read buffer. If no bytes are buffered in the internal read - buffer yet, a call to wolfSSL_read() will trigger processing of the next + \brief This function reads sz bytes from the SSL session (ssl) + internal read buffer into the buffer data. The bytes read are removed + from the internal receive buffer. If necessary wolfSSL_read() will + negotiate an SSL/TLS session if the handshake has not already been + performed yet by wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS + protocol uses SSL records which have a maximum size of 16kB (the max + record size can be controlled by the MAX_RECORD_SIZE define in + /wolfssl/internal.h). As such, wolfSSL needs to read an + entire SSL record internally before it is able to process and decrypt the + record. Because of this, a call to wolfSSL_read() will only be able to + return the maximum buffer size which has been decrypted at the time of + calling. There may be additional not-yet-decrypted data waiting in the + internal wolfSSL receive buffer which will be retrieved and decrypted with + the next call to wolfSSL_read(). If sz is larger than the number of bytes + in the internal read buffer, SSL_read() will return the bytes available in + the internal read buffer. If no bytes are buffered in the internal read + buffer yet, a call to wolfSSL_read() will trigger processing of the next record. - + \return >0 the number of bytes read upon success. - \return 0 will be returned upon failure. This may be caused by a either a - clean (close notify alert) shutdown or just that the peer closed the + \return 0 will be returned upon failure. This may be caused by a either a + clean (close notify alert) shutdown or just that the peer closed the connection. Call wolfSSL_get_error() for the specific error code. - \return SSL_FATAL_ERROR will be returned upon failure when either an error - occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or - SSL_ERROR_WANT_WRITE error was received and and the application needs to - call wolfSSL_read() again. Use wolfSSL_get_error() to get a specific + \return SSL_FATAL_ERROR will be returned upon failure when either an error + occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or + SSL_ERROR_WANT_WRITE error was received and and the application needs to + call wolfSSL_read() again. Use wolfSSL_get_error() to get a specific error code. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param data buffer where wolfSSL_read() will place data read. \param sz number of bytes to read into data. - + _Example_ \code WOLFSSL* ssl = 0; @@ -1769,10 +1769,10 @@ WOLFSSL_API int wolfSSL_write(WOLFSSL*, const void*, int); // “input” number of bytes returned into buffer “reply” } - See wolfSSL examples (client, server, echoclient, echoserver) for more + See wolfSSL examples (client, server, echoclient, echoserver) for more complete examples of wolfSSL_read(). \endcode - + \sa wolfSSL_recv \sa wolfSSL_write \sa wolfSSL_peek @@ -1783,53 +1783,53 @@ WOLFSSL_API int wolfSSL_read(WOLFSSL*, void*, int); /*! \ingroup IO - \brief This function copies sz bytes from the SSL session (ssl) internal - read buffer into the buffer data. This function is identical to - wolfSSL_read() except that the data in the internal SSL session - receive buffer is not removed or modified. If necessary, like - wolfSSL_read(), wolfSSL_peek() will negotiate an SSL/TLS session if - the handshake has not already been performed yet by wolfSSL_connect() - or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a - maximum size of 16kB (the max record size can be controlled by the - MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, - wolfSSL needs to read an entire SSL record internally before it is able - to process and decrypt the record. Because of this, a call to - wolfSSL_peek() will only be able to return the maximum buffer size which - has been decrypted at the time of calling. There may be additional - not-yet-decrypted data waiting in the internal wolfSSL receive buffer - which will be retrieved and decrypted with the next call to - wolfSSL_peek() / wolfSSL_read(). If sz is larger than the number of bytes - in the internal read buffer, SSL_peek() will return the bytes available - in the internal read buffer. If no bytes are buffered in the internal - read buffer yet, a call to wolfSSL_peek() will trigger processing of the + \brief This function copies sz bytes from the SSL session (ssl) internal + read buffer into the buffer data. This function is identical to + wolfSSL_read() except that the data in the internal SSL session + receive buffer is not removed or modified. If necessary, like + wolfSSL_read(), wolfSSL_peek() will negotiate an SSL/TLS session if + the handshake has not already been performed yet by wolfSSL_connect() + or wolfSSL_accept(). The SSL/TLS protocol uses SSL records which have a + maximum size of 16kB (the max record size can be controlled by the + MAX_RECORD_SIZE define in /wolfssl/internal.h). As such, + wolfSSL needs to read an entire SSL record internally before it is able + to process and decrypt the record. Because of this, a call to + wolfSSL_peek() will only be able to return the maximum buffer size which + has been decrypted at the time of calling. There may be additional + not-yet-decrypted data waiting in the internal wolfSSL receive buffer + which will be retrieved and decrypted with the next call to + wolfSSL_peek() / wolfSSL_read(). If sz is larger than the number of bytes + in the internal read buffer, SSL_peek() will return the bytes available + in the internal read buffer. If no bytes are buffered in the internal + read buffer yet, a call to wolfSSL_peek() will trigger processing of the next record. - + \return >0 the number of bytes read upon success. - \return 0 will be returned upon failure. This may be caused by a either - a clean (close notify alert) shutdown or just that the peer closed the + \return 0 will be returned upon failure. This may be caused by a either + a clean (close notify alert) shutdown or just that the peer closed the connection. Call wolfSSL_get_error() for the specific error code. - \return SSL_FATAL_ERROR will be returned upon failure when either an - error occurred or, when using non-blocking sockets, the - SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and - the application needs to call wolfSSL_peek() again. Use + \return SSL_FATAL_ERROR will be returned upon failure when either an + error occurred or, when using non-blocking sockets, the + SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and and + the application needs to call wolfSSL_peek() again. Use wolfSSL_get_error() to get a specific error code. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param data buffer where wolfSSL_peek() will place data read. \param sz number of bytes to read into data. - + _Example_ \code WOLFSSL* ssl = 0; char reply[1024]; ... - + input = wolfSSL_peek(ssl, reply, sizeof(reply)); if (input > 0) { // “input” number of bytes returned into buffer “reply” } \endcode - + \sa wolfSSL_read */ WOLFSSL_API int wolfSSL_peek(WOLFSSL*, void*, int); @@ -1837,27 +1837,27 @@ WOLFSSL_API int wolfSSL_peek(WOLFSSL*, void*, int); /*! \ingroup IO - \brief This function is called on the server side and waits for an SSL - client to initiate the SSL/TLS handshake. When this function is called, - the underlying communication channel has already been set up. - wolfSSL_accept() works with both blocking and non-blocking I/O. - When the underlying I/O is non-blocking, wolfSSL_accept() will return - when the underlying I/O could not satisfy the needs of wolfSSL_accept - 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_accept when - data is available to read 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_accept() will only return once the handshake has + \brief This function is called on the server side and waits for an SSL + client to initiate the SSL/TLS handshake. When this function is called, + the underlying communication channel has already been set up. + wolfSSL_accept() works with both blocking and non-blocking I/O. + When the underlying I/O is non-blocking, wolfSSL_accept() will return + when the underlying I/O could not satisfy the needs of wolfSSL_accept + 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_accept when + data is available to read 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_accept() will only return once the handshake has been finished or an error occurred. - + \return SSL_SUCCESS upon success. - \return SSL_FATAL_ERROR will be returned if an error occurred. To get a + \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(). - + _Example_ \code int ret = 0; @@ -1872,41 +1872,41 @@ WOLFSSL_API int wolfSSL_peek(WOLFSSL*, void*, int); printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); } \endcode - + \sa wolfSSL_get_error \sa wolfSSL_connect */ WOLFSSL_API int wolfSSL_accept(WOLFSSL*); /*! - \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 + \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 upon success. - \return SSL_FATAL_ERROR will be returned if an error occurred. To get a + \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(). - + _Example_ \code int ret = 0; @@ -1921,7 +1921,7 @@ WOLFSSL_API int wolfSSL_accept(WOLFSSL*); printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); } \endcode - + \sa wolfSSL_get_error \sa wolfSSL_accept */ @@ -1930,21 +1930,21 @@ WOLFSSL_API int wolfSSL_connect_TLSv13(WOLFSSL*); /*! \ingroup Setup - \brief This function frees an allocated WOLFSSL_CTX object. This - function decrements the CTX reference count and only frees the context + \brief This function frees an allocated WOLFSSL_CTX object. This + function decrements the CTX reference count and only frees the context when the reference count has reached 0. - + \return none No return. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). - + _Example_ \code WOLFSSL_CTX* ctx = 0; ... wolfSSL_CTX_free(ctx); \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_new \sa wolfSSL_free @@ -1957,9 +1957,9 @@ WOLFSSL_API void wolfSSL_CTX_free(WOLFSSL_CTX*); \brief This function frees an allocated wolfSSL object. \return none No return. - + \param ssl pointer to the SSL object, created with wolfSSL_new(). - + _Example_ \code #include @@ -1968,7 +1968,7 @@ WOLFSSL_API void wolfSSL_CTX_free(WOLFSSL_CTX*); ... wolfSSL_free(ssl); \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_new \sa wolfSSL_CTX_free @@ -1978,35 +1978,35 @@ WOLFSSL_API void wolfSSL_free(WOLFSSL*); /*! \ingroup TLS - \brief This function shuts down an active SSL/TLS connection using - the SSL session, ssl. This function will try to send a “close notify” - alert to the peer. The calling application can choose to wait for the - peer to send its “close notify” alert in response or just go ahead - and shut down the underlying connection after directly calling - wolfSSL_shutdown (to save resources). Either option is allowed by - the TLS specification. If the underlying connection will be used - again in the future, the complete two-directional shutdown procedure - must be performed to keep synchronization intact between the peers. - wolfSSL_shutdown() works with both blocking and non-blocking I/O. - When the underlying I/O is non-blocking, wolfSSL_shutdown() will - return an error if the underlying I/O could not satisfy the needs of - wolfSSL_shutdown() to continue. 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 + \brief This function shuts down an active SSL/TLS connection using + the SSL session, ssl. This function will try to send a “close notify” + alert to the peer. The calling application can choose to wait for the + peer to send its “close notify” alert in response or just go ahead + and shut down the underlying connection after directly calling + wolfSSL_shutdown (to save resources). Either option is allowed by + the TLS specification. If the underlying connection will be used + again in the future, the complete two-directional shutdown procedure + must be performed to keep synchronization intact between the peers. + wolfSSL_shutdown() works with both blocking and non-blocking I/O. + When the underlying I/O is non-blocking, wolfSSL_shutdown() will + return an error if the underlying I/O could not satisfy the needs of + wolfSSL_shutdown() to continue. 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_shutdown() when the underlying I/O is ready. \return SSL_SUCCESS will be returned upon success. - \return SSL_SHUTDOWN_NOT_DONE will be returned when shutdown has not + \return SSL_SHUTDOWN_NOT_DONE will be returned when shutdown has not finished, and the function should be called again. - \return SSL_FATAL_ERROR will be returned upon failure. Call + \return SSL_FATAL_ERROR will be returned upon failure. Call wolfSSL_get_error() for a more specific error code. - + \param ssl pointer to the SSL session created with wolfSSL_new(). - + _Example_ \code #include - + int ret = 0; WOLFSSL* ssl = 0; ... @@ -2015,7 +2015,7 @@ WOLFSSL_API void wolfSSL_free(WOLFSSL*); // failed to shut down SSL connection } \endcode - + \sa wolfSSL_free \sa wolfSSL_CTX_free */ @@ -2024,34 +2024,34 @@ WOLFSSL_API int wolfSSL_shutdown(WOLFSSL*); /*! \ingroup IO - \brief This function writes sz bytes from the buffer, data, to the SSL - connection, ssl, using the specified flags for the underlying write - operation. If necessary wolfSSL_send() will negotiate an SSL/TLS session - if the handshake has not already been performed yet by wolfSSL_connect() - or wolfSSL_accept(). wolfSSL_send() works with both blocking and - non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_send() - will return when the underlying I/O could not satisfy the needs of - wolfSSL_send to continue. 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_send() when - the underlying I/O is ready. If the underlying I/O is blocking, - wolfSSL_send() will only return once the buffer data of size sz has + \brief This function writes sz bytes from the buffer, data, to the SSL + connection, ssl, using the specified flags for the underlying write + operation. If necessary wolfSSL_send() will negotiate an SSL/TLS session + if the handshake has not already been performed yet by wolfSSL_connect() + or wolfSSL_accept(). wolfSSL_send() works with both blocking and + non-blocking I/O. When the underlying I/O is non-blocking, wolfSSL_send() + will return when the underlying I/O could not satisfy the needs of + wolfSSL_send to continue. 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_send() when + the underlying I/O is ready. If the underlying I/O is blocking, + wolfSSL_send() will only return once the buffer data of size sz has been completely written or an error occurred. \return >0 the number of bytes written upon success. - \return 0 will be returned upon failure. Call wolfSSL_get_error() for + \return 0 will be returned upon failure. Call wolfSSL_get_error() for the specific error code. - \return SSL_FATAL_ERROR will be returned upon failure when either an error - occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or - SSL_ERROR_WANT_WRITE error was received and and the application needs to - call wolfSSL_send() again. Use wolfSSL_get_error() to get a specific + \return SSL_FATAL_ERROR will be returned upon failure when either an error + occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or + SSL_ERROR_WANT_WRITE error was received and and the application needs to + call wolfSSL_send() again. Use wolfSSL_get_error() to get a specific error code. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param data data buffer to send to peer. \param sz size, in bytes, of data to be sent to peer. \param flags the send flags to use for the underlying send operation. - + _Example_ \code WOLFSSL* ssl = 0; @@ -2065,7 +2065,7 @@ WOLFSSL_API int wolfSSL_shutdown(WOLFSSL*); // wolfSSL_send() failed } \endcode - + \sa wolfSSL_write \sa wolfSSL_read \sa wolfSSL_recv @@ -2075,43 +2075,43 @@ WOLFSSL_API int wolfSSL_send(WOLFSSL*, const void*, int sz, int flags); /*! \ingroup IO - \brief This function reads sz bytes from the SSL session (ssl) internal - read buffer into the buffer data using the specified flags for the - underlying recv operation. The bytes read are removed from the internal - receive buffer. This function is identical to wolfSSL_read() except - that it allows the application to set the recv flags for the underlying - read operation. If necessary wolfSSL_recv() will negotiate an SSL/TLS - session if the handshake has not already been performed yet by - wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses - SSL records which have a maximum size of 16kB (the max record size - can be controlled by the MAX_RECORD_SIZE define in - /wolfssl/internal.h). As such, wolfSSL needs to read an - entire SSL record internally before it is able to process and decrypt - the record. Because of this, a call to wolfSSL_recv() will only be - able to return the maximum buffer size which has been decrypted at - the time of calling. There may be additional not-yet-decrypted data - waiting in the internal wolfSSL receive buffer which will be - retrieved and decrypted with the next call to wolfSSL_recv(). If sz - is larger than the number of bytes in the internal read buffer, - SSL_recv() will return the bytes available in the internal read buffer. - If no bytes are buffered in the internal read buffer yet, a call to + \brief This function reads sz bytes from the SSL session (ssl) internal + read buffer into the buffer data using the specified flags for the + underlying recv operation. The bytes read are removed from the internal + receive buffer. This function is identical to wolfSSL_read() except + that it allows the application to set the recv flags for the underlying + read operation. If necessary wolfSSL_recv() will negotiate an SSL/TLS + session if the handshake has not already been performed yet by + wolfSSL_connect() or wolfSSL_accept(). The SSL/TLS protocol uses + SSL records which have a maximum size of 16kB (the max record size + can be controlled by the MAX_RECORD_SIZE define in + /wolfssl/internal.h). As such, wolfSSL needs to read an + entire SSL record internally before it is able to process and decrypt + the record. Because of this, a call to wolfSSL_recv() will only be + able to return the maximum buffer size which has been decrypted at + the time of calling. There may be additional not-yet-decrypted data + waiting in the internal wolfSSL receive buffer which will be + retrieved and decrypted with the next call to wolfSSL_recv(). If sz + is larger than the number of bytes in the internal read buffer, + SSL_recv() will return the bytes available in the internal read buffer. + If no bytes are buffered in the internal read buffer yet, a call to wolfSSL_recv() will trigger processing of the next record. - + \return >0 the number of bytes read upon success. - \return 0 will be returned upon failure. This may be caused by a either - a clean (close notify alert) shutdown or just that the peer closed the + \return 0 will be returned upon failure. This may be caused by a either + a clean (close notify alert) shutdown or just that the peer closed the connection. Call wolfSSL_get_error() for the specific error code. - \return SSL_FATAL_ERROR will be returned upon failure when either an error - occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or - SSL_ERROR_WANT_WRITE error was received and and the application needs to - call wolfSSL_recv() again. Use wolfSSL_get_error() to get a specific + \return SSL_FATAL_ERROR will be returned upon failure when either an error + occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or + SSL_ERROR_WANT_WRITE error was received and and the application needs to + call wolfSSL_recv() again. Use wolfSSL_get_error() to get a specific error code. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param data buffer where wolfSSL_recv() will place data read. \param sz number of bytes to read into data. \param flags the recv flags to use for the underlying recv operation. - + _Example_ \code WOLFSSL* ssl = 0; @@ -2124,7 +2124,7 @@ WOLFSSL_API int wolfSSL_send(WOLFSSL*, const void*, int sz, int flags); // “input” number of bytes returned into buffer “reply” } \endcode - + \sa wolfSSL_read \sa wolfSSL_write \sa wolfSSL_peek @@ -2135,23 +2135,23 @@ WOLFSSL_API int wolfSSL_recv(WOLFSSL*, void*, int sz, int flags); /*! \ingroup Debug - \brief This function returns a unique error code describing why the - previous API function call (wolfSSL_connect, wolfSSL_accept, wolfSSL_read, - wolfSSL_write, etc.) resulted in an error return code (SSL_FAILURE). - The return value of the previous function is passed to wolfSSL_get_error - through ret. After wolfSSL_get_error is called and returns the unique - error code, wolfSSL_ERR_error_string() may be called to get a - human-readable error string. See wolfSSL_ERR_error_string() for more + \brief This function returns a unique error code describing why the + previous API function call (wolfSSL_connect, wolfSSL_accept, wolfSSL_read, + wolfSSL_write, etc.) resulted in an error return code (SSL_FAILURE). + The return value of the previous function is passed to wolfSSL_get_error + through ret. After wolfSSL_get_error is called and returns the unique + error code, wolfSSL_ERR_error_string() may be called to get a + human-readable error string. See wolfSSL_ERR_error_string() for more information. - \return code On successful completion, this function will return the + \return code On successful completion, this function will return the unique error code describing why the previous API function failed. \return SSL_ERROR_NONE will be returned if ret > 0. - + \param ssl pointer to the SSL object, created with wolfSSL_new(). - \param ret return value of the previous function that resulted in an error + \param ret return value of the previous function that resulted in an error return code. - + _Example_ \code int err = 0; @@ -2162,7 +2162,7 @@ WOLFSSL_API int wolfSSL_recv(WOLFSSL*, void*, int sz, int flags); wolfSSL_ERR_error_string(err, buffer); printf(“err = %d, %s\n”, err, buffer); \endcode - + \sa wolfSSL_ERR_error_string \sa wolfSSL_ERR_error_string_n \sa wolfSSL_ERR_print_errors_fp @@ -2174,15 +2174,15 @@ WOLFSSL_API int wolfSSL_get_error(WOLFSSL*, int); \ingroup IO \brief This function gets the alert history. - - \return SSL_SUCCESS returned when the function completed successfully. - Either there was alert history or there wasn’t, either way, the + + \return SSL_SUCCESS returned when the function completed successfully. + Either there was alert history or there wasn’t, either way, the return value is SSL_SUCCESS. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param h a pointer to a WOLFSSL_ALERT_HISTORY structure that will hold the + \param h a pointer to a WOLFSSL_ALERT_HISTORY structure that will hold the WOLFSSL struct’s alert_history member’s value. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method); @@ -2192,7 +2192,7 @@ WOLFSSL_API int wolfSSL_get_error(WOLFSSL*, int); wolfSSL_get_alert_history(ssl, h); // h now has a copy of the ssl->alert_history contents \endcode - + \sa wolfSSL_get_error */ WOLFSSL_API int wolfSSL_get_alert_history(WOLFSSL*, WOLFSSL_ALERT_HISTORY *); @@ -2200,22 +2200,22 @@ WOLFSSL_API int wolfSSL_get_alert_history(WOLFSSL*, WOLFSSL_ALERT_HISTORY *); /*! \ingroup Setup - \brief This function sets the session to be used when the SSL object, - ssl, is used to establish a SSL/TLS connection. For session resumption, - before calling wolfSSL_shutdown() with your session object, an application - should save the session ID from the object with a call to - wolfSSL_get_session(), which returns a pointer to the session. - Later, the application should create a new WOLFSSL object and assign - the saved session with wolfSSL_set_session(). At this point, the - application may call wolfSSL_connect() and wolfSSL will try to resume + \brief This function sets the session to be used when the SSL object, + ssl, is used to establish a SSL/TLS connection. For session resumption, + before calling wolfSSL_shutdown() with your session object, an application + should save the session ID from the object with a call to + wolfSSL_get_session(), which returns a pointer to the session. + Later, the application should create a new WOLFSSL object and assign + the saved session with wolfSSL_set_session(). At this point, the + application may call wolfSSL_connect() and wolfSSL will try to resume the session. The wolfSSL server code allows session resumption by default. - + \return SSL_SUCCESS will be returned upon successfully setting the session. - \return SSL_FAILURE will be returned on failure. This could be caused + \return SSL_FAILURE will be returned on failure. This could be caused by the session cache being disabled, or if the session has timed out. - + \param ssl pointer to the SSL object, created with wolfSSL_new(). - \param session pointer to the WOLFSSL_SESSION used to set the session + \param session pointer to the WOLFSSL_SESSION used to set the session for ssl. _Example_ @@ -2231,7 +2231,7 @@ WOLFSSL_API int wolfSSL_get_alert_history(WOLFSSL*, WOLFSSL_ALERT_HISTORY *); } ... \endcode - + \sa wolfSSL_get_session */ WOLFSSL_API int wolfSSL_set_session(WOLFSSL*, WOLFSSL_SESSION*); @@ -2239,26 +2239,26 @@ WOLFSSL_API int wolfSSL_set_session(WOLFSSL*, WOLFSSL_SESSION*); /*! \ingroup IO - \brief This function returns a pointer to the current session - (WOLFSSL_SESSION) used in ssl. The WOLFSSL_SESSION pointed to - contains all the necessary information required to perform a session - resumption and reestablish the connection without a new handshake. For - session resumption, before calling wolfSSL_shutdown() with your session - object, an application should save the session ID from the object with a - call to wolfSSL_get_session(), which returns a pointer to the session. - Later, the application should create a new WOLFSSL object and assign the - saved session with wolfSSL_set_session(). At this point, the application - may call wolfSSL_connect() and wolfSSL will try to resume the session. + \brief This function returns a pointer to the current session + (WOLFSSL_SESSION) used in ssl. The WOLFSSL_SESSION pointed to + contains all the necessary information required to perform a session + resumption and reestablish the connection without a new handshake. For + session resumption, before calling wolfSSL_shutdown() with your session + object, an application should save the session ID from the object with a + call to wolfSSL_get_session(), which returns a pointer to the session. + Later, the application should create a new WOLFSSL object and assign the + saved session with wolfSSL_set_session(). At this point, the application + may call wolfSSL_connect() and wolfSSL will try to resume the session. The wolfSSL server code allows session resumption by default. - - \return pointer If successful the call will return a pointer to the the + + \return pointer If successful the call will return a pointer to the the current SSL session object. - \return NULL will be returned if ssl is NULL, the SSL session cache is - disabled, wolfSSL doesn’t have the Session ID available, or mutex + \return NULL will be returned if ssl is NULL, the SSL session cache is + disabled, wolfSSL doesn’t have the Session ID available, or mutex functions fail. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl = 0; @@ -2270,7 +2270,7 @@ WOLFSSL_API int wolfSSL_set_session(WOLFSSL*, WOLFSSL_SESSION*); } ... \endcode - + \sa wolfSSL_set_session */ WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL*); @@ -2278,26 +2278,26 @@ WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL*); /*! \ingroup IO - \brief This function flushes session from the session cache which - have expired. The time, tm, is used for the time comparison. Note - that wolfSSL currently uses a static table for sessions, so no flushing - is needed. As such, this function is currently just a stub. This - function provides OpenSSL compatibility (SSL_flush_sessions) when + \brief This function flushes session from the session cache which + have expired. The time, tm, is used for the time comparison. Note + that wolfSSL currently uses a static table for sessions, so no flushing + is needed. As such, this function is currently just a stub. This + function provides OpenSSL compatibility (SSL_flush_sessions) when wolfSSL is compiled with the OpenSSL compatibility layer. - + \return none No returns. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). \param tm time used in session expiration comparison. - + _Example_ \code WOLFSSL_CTX* ssl; ... wolfSSL_flush_sessions(ctx, time(0)); \endcode - + \sa wolfSSL_get_session \sa wolfSSL_set_session */ @@ -2306,20 +2306,20 @@ WOLFSSL_API void wolfSSL_flush_sessions(WOLFSSL_CTX*, long); /*! \ingroup TLS - \brief This function associates the client session with the server id. + \brief This function associates the client session with the server id. If the newSession flag is on, an existing session won’t be reused. - + \return SSL_SUCCESS returned if the finction executed without error. - \return BAD_FUNC_ARG returned if the WOLFSSL struct or id parameter + \return BAD_FUNC_ARG returned if the WOLFSSL struct or id parameter is NULL or if len is not greater than zero. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param id a constant byte pointer that will be copied to the + \param id a constant byte pointer that will be copied to the serverID member of the WOLFSSL_SESSION structure. \param len an int type representing the length of the session id parameter. - \param newSession an int type representing the flag to denote whether + \param newSession an int type representing the flag to denote whether to reuse a session or not. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol ); @@ -2334,7 +2334,7 @@ WOLFSSL_API void wolfSSL_flush_sessions(WOLFSSL_CTX*, long); // The Id was successfully set } \endcode - + \sa GetSessionClient */ WOLFSSL_API int wolfSSL_SetServerID(WOLFSSL*, const unsigned char*, @@ -2344,12 +2344,12 @@ WOLFSSL_API int wolfSSL_SetServerID(WOLFSSL*, const unsigned char*, \ingroup IO \brief This function gets the session index of the WOLFSSL structure. - - \return int The function returns an int type representing the + + \return int The function returns an int type representing the sessionIndex within the WOLFSSL struct. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX_new( protocol method ); @@ -2361,7 +2361,7 @@ WOLFSSL_API int wolfSSL_SetServerID(WOLFSSL*, const unsigned char*, // You have an out of bounds index number and something is not right. } \endcode - + \sa wolfSSL_GetSessionAtIndex */ WOLFSSL_API int wolfSSL_GetSessionIndex(WOLFSSL* ssl); @@ -2369,18 +2369,18 @@ WOLFSSL_API int wolfSSL_GetSessionIndex(WOLFSSL* ssl); /*! \ingroup IO - \brief This function gets the session at specified index of the session - cache and copies it into memory. The WOLFSSL_SESSION structure holds + \brief This function gets the session at specified index of the session + cache and copies it into memory. The WOLFSSL_SESSION structure holds the session information. - - \return SSL_SUCCESS returned if the function executed successfully and + + \return SSL_SUCCESS returned if the function executed successfully and no errors were thrown. \return BAD_MUTEX_E returned if there was an unlock or lock mutex error. \return SSL_FAILURE returned if the function did not execute successfully. - + \param idx an int type representing the session index. \param session a pointer to the WOLFSSL_SESSION structure. - + _Example_ \code int idx; // The index to locate the session. @@ -2390,7 +2390,7 @@ WOLFSSL_API int wolfSSL_GetSessionIndex(WOLFSSL* ssl); // Failure case. } \endcode - + \sa UnLockMutex \sa LockMutex \sa wolfSSL_GetSessionIndex @@ -2401,12 +2401,12 @@ WOLFSSL_API int wolfSSL_GetSessionAtIndex(int index, WOLFSSL_SESSION* session); \ingroup IO \brief Returns the peer certificate chain from the WOLFSSL_SESSION struct. - - \return pointer A pointer to a WOLFSSL_X509_CHAIN structure that + + \return pointer A pointer to a WOLFSSL_X509_CHAIN structure that contains the peer certification chain. - + \param session a pointer to a WOLFSSL_SESSION structure. - + _Example_ \code WOLFSSL_SESSION* session; @@ -2417,7 +2417,7 @@ WOLFSSL_API int wolfSSL_GetSessionAtIndex(int index, WOLFSSL_SESSION* session); // There was no chain. Failure case. } \endcode - + \sa get_locked_session_stats \sa wolfSSL_GetSessionAtIndex \sa wolfSSL_GetSessionIndex @@ -2429,38 +2429,38 @@ WOLFSSL_API /*! \ingroup Setup - \brief This function sets the verification method for remote peers and - also allows a verify callback to be registered with the SSL context. - The verify callback will be called only when a verification failure has - occurred. If no verify callback is desired, the NULL pointer can be used - for verify_callback. The verification mode of peer certificates is a - logically OR’d list of flags. The possible flag values include: - SSL_VERIFY_NONE Client mode: the client will not verify the certificate - received from the server and the handshake will continue as normal. - Server mode: the server will not send a certificate request to the client. - As such, client verification will not be enabled. SSL_VERIFY_PEER Client - mode: the client will verify the certificate received from the server - during the handshake. This is turned on by default in wolfSSL, therefore, - using this option has no effect. Server mode: the server will send a - certificate request to the client and verify the client certificate - received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when - used on the client side. Server mode: the verification will fail on the - server side if the client fails to send a certificate when requested to - do so (when using SSL_VERIFY_PEER on the SSL server). - SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client - side. Server mode: the verification is the same as - SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection. - If a PSK connection is being made then the connection will go through + \brief This function sets the verification method for remote peers and + also allows a verify callback to be registered with the SSL context. + The verify callback will be called only when a verification failure has + occurred. If no verify callback is desired, the NULL pointer can be used + for verify_callback. The verification mode of peer certificates is a + logically OR’d list of flags. The possible flag values include: + SSL_VERIFY_NONE Client mode: the client will not verify the certificate + received from the server and the handshake will continue as normal. + Server mode: the server will not send a certificate request to the client. + As such, client verification will not be enabled. SSL_VERIFY_PEER Client + mode: the client will verify the certificate received from the server + during the handshake. This is turned on by default in wolfSSL, therefore, + using this option has no effect. Server mode: the server will send a + certificate request to the client and verify the client certificate + received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when + used on the client side. Server mode: the verification will fail on the + server side if the client fails to send a certificate when requested to + do so (when using SSL_VERIFY_PEER on the SSL server). + SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client + side. Server mode: the verification is the same as + SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection. + If a PSK connection is being made then the connection will go through without a peer cert. \return none No return. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param mode session timeout value in seconds - \param verify_callback callback to be called when verification fails. - If no callback is desired, the NULL pointer can be used for + \param verify_callback callback to be called when verification fails. + If no callback is desired, the NULL pointer can be used for verify_callback. - + _Example_ \code WOLFSSL_CTX* ctx = 0; @@ -2468,7 +2468,7 @@ WOLFSSL_API wolfSSL_CTX_set_verify(ctx, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, 0); \endcode - + \sa wolfSSL_set_verify */ WOLFSSL_API void wolfSSL_CTX_set_verify(WOLFSSL_CTX*, int, @@ -2477,45 +2477,45 @@ WOLFSSL_API void wolfSSL_CTX_set_verify(WOLFSSL_CTX*, int, /*! \ingroup Setup - \brief This function sets the verification method for remote peers and - also allows a verify callback to be registered with the SSL session. - The verify callback will be called only when a verification failure has - occurred. If no verify callback is desired, the NULL pointer can be used - for verify_callback. The verification mode of peer certificates is a - logically OR’d list of flags. The possible flag values include: - SSL_VERIFY_NONE Client mode: the client will not verify the certificate - received from the server and the handshake will continue as normal. Server - mode: the server will not send a certificate request to the client. - As such, client verification will not be enabled. SSL_VERIFY_PEER Client - mode: the client will verify the certificate received from the server - during the handshake. This is turned on by default in wolfSSL, therefore, - using this option has no effect. Server mode: the server will send a - certificate request to the client and verify the client certificate - received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when - used on the client side. Server mode: the verification will fail on the - server side if the client fails to send a certificate when requested to do - so (when using SSL_VERIFY_PEER on the SSL server). - SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client - side. Server mode: the verification is the same as - SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection. - If a PSK connection is being made then the connection will go through + \brief This function sets the verification method for remote peers and + also allows a verify callback to be registered with the SSL session. + The verify callback will be called only when a verification failure has + occurred. If no verify callback is desired, the NULL pointer can be used + for verify_callback. The verification mode of peer certificates is a + logically OR’d list of flags. The possible flag values include: + SSL_VERIFY_NONE Client mode: the client will not verify the certificate + received from the server and the handshake will continue as normal. Server + mode: the server will not send a certificate request to the client. + As such, client verification will not be enabled. SSL_VERIFY_PEER Client + mode: the client will verify the certificate received from the server + during the handshake. This is turned on by default in wolfSSL, therefore, + using this option has no effect. Server mode: the server will send a + certificate request to the client and verify the client certificate + received. SSL_VERIFY_FAIL_IF_NO_PEER_CERT Client mode: no effect when + used on the client side. Server mode: the verification will fail on the + server side if the client fails to send a certificate when requested to do + so (when using SSL_VERIFY_PEER on the SSL server). + SSL_VERIFY_FAIL_EXCEPT_PSK Client mode: no effect when used on the client + side. Server mode: the verification is the same as + SSL_VERIFY_FAIL_IF_NO_PEER_CERT except in the case of a PSK connection. + If a PSK connection is being made then the connection will go through without a peer cert. \return none No return. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param mode session timeout value in seconds. - \param verify_callback callback to be called when verification fails. - If no callback is desired, the NULL pointer can + \param verify_callback callback to be called when verification fails. + If no callback is desired, the NULL pointer can be used for verify_callback. - + _Example_ \code WOLFSSL* ssl = 0; ... wolfSSL_set_verify(ssl, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, 0); \endcode - + \sa wolfSSL_CTX_set_verify */ WOLFSSL_API void wolfSSL_set_verify(WOLFSSL*, int, VerifyCallback verify_callback); @@ -2524,13 +2524,13 @@ WOLFSSL_API void wolfSSL_set_verify(WOLFSSL*, int, VerifyCallback verify_callbac \ingroup CertsKeys \brief This function stores user CTX object information for verify callback. - + \return none No return. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param ctx a void pointer that is set to WOLFSSL structure’s verifyCbCtx + \param ctx a void pointer that is set to WOLFSSL structure’s verifyCbCtx member’s value. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -2543,7 +2543,7 @@ WOLFSSL_API void wolfSSL_set_verify(WOLFSSL*, int, VerifyCallback verify_callbac // Error case, the SSL is not initialized properly. } \endcode - + \sa wolfSSL_CTX_save_cert_cache \sa wolfSSL_CTX_restore_cert_cache \sa wolfSSL_CTX_set_verify @@ -2553,13 +2553,13 @@ WOLFSSL_API void wolfSSL_SetCertCbCtx(WOLFSSL*, void*); /*! \ingroup IO - \brief This function returns the number of bytes which are buffered and + \brief This function returns the number of bytes which are buffered and available in the SSL object to be read by wolfSSL_read(). - + \return int This function returns the number of bytes pending. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - + _Example_ \code int pending = 0; @@ -2569,7 +2569,7 @@ WOLFSSL_API void wolfSSL_SetCertCbCtx(WOLFSSL*, void*); pending = wolfSSL_pending(ssl); printf(“There are %d bytes buffered and available for reading”, pending); \endcode - + \sa wolfSSL_recv \sa wolfSSL_read \sa wolfSSL_peek @@ -2579,18 +2579,18 @@ WOLFSSL_API int wolfSSL_pending(WOLFSSL*); /*! \ingroup Debug - \brief This function is for OpenSSL compatibility (SSL_load_error_string) + \brief This function is for OpenSSL compatibility (SSL_load_error_string) only and takes no action. - + \return none No returns. - + \param none No parameters. - + _Example_ \code wolfSSL_load_error_strings(); \endcode - + \sa wolfSSL_get_error \sa wolfSSL_ERR_error_string \sa wolfSSL_ERR_error_string_n @@ -2602,17 +2602,17 @@ WOLFSSL_API void wolfSSL_load_error_strings(void); /*! \ingroup TLS - \brief This function is called internally in wolfSSL_CTX_new(). This - function is a wrapper around wolfSSL_Init() and exists for OpenSSL - compatibility (SSL_library_init) when wolfSSL has been compiled with - OpenSSL compatibility layer. wolfSSL_Init() is the more typically-used + \brief This function is called internally in wolfSSL_CTX_new(). This + function is a wrapper around wolfSSL_Init() and exists for OpenSSL + compatibility (SSL_library_init) when wolfSSL has been compiled with + OpenSSL compatibility layer. wolfSSL_Init() is the more typically-used wolfSSL initialization function. - + \return SSL_SUCCESS If successful the call will return. \return SSL_FATAL_ERROR is returned upon failure. - + \param none No parameters. - + _Example_ \code int ret = 0; @@ -2622,7 +2622,7 @@ WOLFSSL_API void wolfSSL_load_error_strings(void); } ... \endcode - + \sa wolfSSL_Init \sa wolfSSL_Cleanup */ @@ -2631,15 +2631,15 @@ WOLFSSL_API int wolfSSL_library_init(void); /*! \ingroup Setup - \brief This function enables or disables SSL session caching. - Behavior depends on the value used for mode. The following values - for mode are available: SSL_SESS_CACHE_OFF- disable session caching. - Session caching is turned on by default. SSL_SESS_CACHE_NO_AUTO_CLEAR - - Disable auto-flushing of the session cache. Auto-flushing is turned on + \brief This function enables or disables SSL session caching. + Behavior depends on the value used for mode. The following values + for mode are available: SSL_SESS_CACHE_OFF- disable session caching. + Session caching is turned on by default. SSL_SESS_CACHE_NO_AUTO_CLEAR - + Disable auto-flushing of the session cache. Auto-flushing is turned on by default. - + \return SSL_SUCCESS will be returned upon success. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param mode modifier used to change behavior of the session cache. @@ -2652,7 +2652,7 @@ WOLFSSL_API int wolfSSL_library_init(void); // failed to turn SSL session caching off } \endcode - + \sa wolfSSL_flush_sessions \sa wolfSSL_get_session \sa wolfSSL_set_session @@ -2662,32 +2662,32 @@ WOLFSSL_API int wolfSSL_library_init(void); WOLFSSL_API long wolfSSL_CTX_set_session_cache_mode(WOLFSSL_CTX*, long); /*! - \brief This function sets the session secret callback function. The - SessionSecretCb type has the signature: int (*SessionSecretCb)(WOLFSSL* ssl, - void* secret, int* secretSz, void* ctx). The sessionSecretCb member of + \brief This function sets the session secret callback function. The + SessionSecretCb type has the signature: int (*SessionSecretCb)(WOLFSSL* ssl, + void* secret, int* secretSz, void* ctx). The sessionSecretCb member of the WOLFSSL struct is set to the parameter cb. - - \return SSL_SUCCESS returned if the execution of the function did not + + \return SSL_SUCCESS returned if the execution of the function did not return an error. \return SSL_FATAL_ERROR returned if the WOLFSSL structure is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param cb a SessionSecretCb type that is a function pointer with the above + \param cb a SessionSecretCb type that is a function pointer with the above signature. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); WOLFSSL* ssl = wolfSSL_new(ctx); // Signature of SessionSecretCb - int SessionSecretCB (WOLFSSL* ssl, void* secret, int* secretSz, + int SessionSecretCB (WOLFSSL* ssl, void* secret, int* secretSz, void* ctx) = SessionSecretCb; … int wolfSSL_set_session_secret_cb(ssl, SessionSecretCB, (void*)ssl->ctx){ // Function body. } \endcode - + \sa SessionSecretCb */ WOLFSSL_API int wolfSSL_set_session_secret_cb(WOLFSSL*, SessionSecretCb, void*); @@ -2695,18 +2695,18 @@ WOLFSSL_API int wolfSSL_set_session_secret_cb(WOLFSSL*, SessionSecretCb, void*) /*! \ingroup IO - \brief This function persists the session cache to file. It doesn’t use + \brief This function persists the session cache to file. It doesn’t use memsave because of additional memory use. - - \return SSL_SUCCESS returned if the function executed without error. + + \return SSL_SUCCESS returned if the function executed without error. The session cache has been written to a file. - \return SSL_BAD_FILE returned if fname cannot be opened or is otherwise + \return SSL_BAD_FILE returned if fname cannot be opened or is otherwise corrupt. \return FWRITE_ERROR returned if XFWRITE failed to write to the file. \return BAD_MUTEX_E returned if there was a mutex lock failure. - + \param name is a constant char pointer that points to a file for writing. - + _Example_ \code const char* fname; @@ -2715,7 +2715,7 @@ WOLFSSL_API int wolfSSL_set_session_secret_cb(WOLFSSL*, SessionSecretCb, void*) // Fail to write to file. } \endcode - + \sa XFWRITE \sa wolfSSL_restore_session_cache \sa wolfSSL_memrestore_session_cache @@ -2725,19 +2725,19 @@ WOLFSSL_API int wolfSSL_save_session_cache(const char*); /*! \ingroup IO - \brief This function restores the persistent session cache from file. It + \brief This function restores the persistent session cache from file. It does not use memstore because of additional memory use. - + \return SSL_SUCCESS returned if the function executed without error. - \return SSL_BAD_FILE returned if the file passed into the function was + \return SSL_BAD_FILE returned if the file passed into the function was corrupted and could not be opened by XFOPEN. \return FREAD_ERROR returned if the file had a read error from XFREAD. - \return CACHE_MATCH_ERROR returned if the session cache header match + \return CACHE_MATCH_ERROR returned if the session cache header match failed. \return BAD_MUTEX_E returned if there was a mutex lock failure. - + \param fname a constant char pointer file input that will be read. - + _Example_ \code const char *fname; @@ -2746,7 +2746,7 @@ WOLFSSL_API int wolfSSL_save_session_cache(const char*); // Failure case. The function did not return SSL_SUCCESS. } \endcode - + \sa XFREAD \sa XFOPEN */ @@ -2756,16 +2756,16 @@ WOLFSSL_API int wolfSSL_restore_session_cache(const char*); \ingroup IO \brief This function persists session cache to memory. - - \return SSL_SUCCESS returned if the function executed without error. + + \return SSL_SUCCESS returned if the function executed without error. The session cache has been successfully persisted to memory. \return BAD_MUTEX_E returned if there was a mutex lock error. \return BUFFER_E returned if the buffer size was too small. - - \param mem a void pointer representing the destination for the memory + + \param mem a void pointer representing the destination for the memory copy, XMEMCPY(). \param sz an int type representing the size of mem. - + _Example_ \code void* mem; @@ -2775,7 +2775,7 @@ WOLFSSL_API int wolfSSL_restore_session_cache(const char*); // Failure case, you did not persist the session cache to memory } \endcode - + \sa XMEMCPY \sa wolfSSL_get_session_cache_memsize */ @@ -2785,27 +2785,27 @@ WOLFSSL_API int wolfSSL_memsave_session_cache(void*, int); \ingroup IO \brief This function restores the persistent session cache from memory. - + \return SSL_SUCCESS returned if the function executed without an error. \return BUFFER_E returned if the memory buffer is too small. \return BAD_MUTEX_E returned if the session cache mutex lock failed. - \return CACHE_MATCH_ERROR returned if the session cache header match + \return CACHE_MATCH_ERROR returned if the session cache header match failed. - - \param mem a constant void pointer containing the source of the + + \param mem a constant void pointer containing the source of the restoration. \param sz an integer representing the size of the memory buffer. - + _Example_ \code - const void* memoryFile; + const void* memoryFile; int szMf; ... if(wolfSSL_memrestore_session_cache(memoryFile, szMf) != SSL_SUCCESS){ // Failure case. SSL_SUCCESS was not returned. } \endcode - + \sa wolfSSL_save_session_cache */ WOLFSSL_API int wolfSSL_memrestore_session_cache(const void*, int); @@ -2813,14 +2813,14 @@ WOLFSSL_API int wolfSSL_memrestore_session_cache(const void*, int); /*! \ingroup IO - \brief This function returns how large the session cache save buffer + \brief This function returns how large the session cache save buffer should be. - - \return int This function returns an integer that represents the size of + + \return int This function returns an integer that represents the size of the session cache save buffer. - + \param none No parameters. - + _Example_ \code int sz = // Minimum size for error checking; @@ -2829,7 +2829,7 @@ WOLFSSL_API int wolfSSL_memrestore_session_cache(const void*, int); // Memory buffer is too small } \endcode - + \sa wolfSSL_memrestore_session_cache */ WOLFSSL_API int wolfSSL_get_session_cache_memsize(void); @@ -2838,18 +2838,18 @@ WOLFSSL_API int wolfSSL_get_session_cache_memsize(void); \ingroup CertsKeys \brief This function writes the cert cache from memory to file. - + \return SSL_SUCCESS if CM_SaveCertCache exits normally. \return BAD_FUNC_ARG is returned if either of the arguments are NULL. \return SSL_BAD_FILE if the cert cache save file could not be opened. \return BAD_MUTEX_E if the lock mutex failed. \return MEMORY_E the allocation of memory failed. \return FWRITE_ERROR Certificate cache file write failed. - - \param ctx a pointer to a WOLFSSL_CTX structure, holding the + + \param ctx a pointer to a WOLFSSL_CTX structure, holding the certificate information. \param fname the cert cache buffer. - + _Example_ \code WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol def ); @@ -2859,7 +2859,7 @@ WOLFSSL_API int wolfSSL_get_session_cache_memsize(void); // file was written. } \endcode - + \sa CM_SaveCertCache \sa DoMemSaveCertCache */ @@ -2869,19 +2869,19 @@ WOLFSSL_API int wolfSSL_CTX_save_cert_cache(WOLFSSL_CTX*, const char*); \ingroup CertsKeys \brief This function persistes certificate cache from a file. - - \return SSL_SUCCESS returned if the function, CM_RestoreCertCache, + + \return SSL_SUCCESS returned if the function, CM_RestoreCertCache, executes normally. - \return SSL_BAD_FILE returned if XFOPEN returns XBADFILE. The file is + \return SSL_BAD_FILE returned if XFOPEN returns XBADFILE. The file is corrupted. - \return MEMORY_E returned if the allocated memory for the temp buffer + \return MEMORY_E returned if the allocated memory for the temp buffer fails. \return BAD_FUNC_ARG returned if fname or ctx have a NULL value. - - \param ctx a pointer to a WOLFSSL_CTX structure, holding the certificate + + \param ctx a pointer to a WOLFSSL_CTX structure, holding the certificate information. \param fname the cert cache buffer. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -2892,7 +2892,7 @@ WOLFSSL_API int wolfSSL_CTX_save_cert_cache(WOLFSSL_CTX*, const char*); // check to see if the execution was successful } \endcode - + \sa CM_RestoreCertCache \sa XFOPEN */ @@ -2902,21 +2902,21 @@ WOLFSSL_API int wolfSSL_CTX_restore_cert_cache(WOLFSSL_CTX*, const char*); \ingroup CertsKeys \brief This function persists the certificate cache to memory. - - \return SSL_SUCCESS returned on successful execution of the function. + + \return SSL_SUCCESS returned on successful execution of the function. No errors were thrown. - \return BAD_MUTEX_E mutex error where the WOLFSSL_CERT_MANAGER member + \return BAD_MUTEX_E mutex error where the WOLFSSL_CERT_MANAGER member caLock was not 0 (zero). - \return BAD_FUNC_ARG returned if ctx, mem, or used is NULL or if sz + \return BAD_FUNC_ARG returned if ctx, mem, or used is NULL or if sz is less than or equal to 0 (zero). \return BUFFER_E output buffer mem was too small. - - \param ctx a pointer to a WOLFSSL_CTX structure, created + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). \param mem a void pointer to the destination (output buffer). \param sz the size of the output buffer. \param used a pointer to size of the cert cache header. - + _Example_ \code WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol ); @@ -2928,7 +2928,7 @@ WOLFSSL_API int wolfSSL_CTX_restore_cert_cache(WOLFSSL_CTX*, const char*); // The function returned with an error } \endcode - + \sa DoMemSaveCertCache \sa GetCertCacheMemSize \sa CM_MemRestoreCertCache @@ -2940,22 +2940,22 @@ WOLFSSL_API int wolfSSL_CTX_memsave_cert_cache(WOLFSSL_CTX*, void*, int, int*); \ingroup Setup \brief This function restores the certificate cache from memory. - - \return SSL_SUCCESS returned if the function and subroutines + + \return SSL_SUCCESS returned if the function and subroutines executed without an error. - \return BAD_FUNC_ARG returned if the ctx or mem parameters are + \return BAD_FUNC_ARG returned if the ctx or mem parameters are NULL or if the sz parameter is less than or equal to zero. \return BUFFER_E returned if the cert cache memory buffer is too small. - \return CACHE_MATCH_ERROR returned if there was a cert cache + \return CACHE_MATCH_ERROR returned if there was a cert cache header mismatch. \return BAD_MUTEX_E returned if the lock mutex on failed. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - \param mem a void pointer with a value that will be restored to + \param mem a void pointer with a value that will be restored to the certificate cache. \param sz an int type that represents the size of the mem parameter. - + _Example_ \code WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method ); @@ -2963,11 +2963,11 @@ WOLFSSL_API int wolfSSL_CTX_memsave_cert_cache(WOLFSSL_CTX*, void*, int, int*); void* mem; int sz = (*int) sizeof(mem); … - if(wolfSSL_CTX_memrestore_cert_cache(ssl->ctx, mem, sz)){ + if(wolfSSL_CTX_memrestore_cert_cache(ssl->ctx, mem, sz)){ // The success case } \endcode - + \sa CM_MemRestoreCertCache */ WOLFSSL_API int wolfSSL_CTX_memrestore_cert_cache(WOLFSSL_CTX*, const void*, int); @@ -2976,15 +2976,15 @@ WOLFSSL_API int wolfSSL_CTX_memrestore_cert_cache(WOLFSSL_CTX*, const void*, in \ingroup CertsKeys \brief Returns the size the certificate cache save buffer needs to be. - - \return int integer value returned representing the memory size + + \return int integer value returned representing the memory size upon success. \return BAD_FUNC_ARG is returned if the WOLFSSL_CTX struct is NULL. \return BAD_MUTEX_E - returned if there was a mutex lock error. - - \param ctx a pointer to a wolfSSL_CTX structure, created using + + \param ctx a pointer to a wolfSSL_CTX structure, created using wolfSSL_CTX_new(). - + _Example_ \code WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(protocol); @@ -2995,7 +2995,7 @@ WOLFSSL_API int wolfSSL_CTX_memrestore_cert_cache(WOLFSSL_CTX*, const void*, in // Successfully retrieved the memory size. } \endcode - + \sa CM_GetCertCacheMemSize */ WOLFSSL_API int wolfSSL_CTX_get_cert_cache_memsize(WOLFSSL_CTX*); @@ -3003,26 +3003,26 @@ WOLFSSL_API int wolfSSL_CTX_get_cert_cache_memsize(WOLFSSL_CTX*); /*! \ingroup Setup - \brief This function sets cipher suite list for a given WOLFSSL_CTX. - This cipher suite list becomes the default list for any new SSL sessions - (WOLFSSL) created using this context. The ciphers in the list should be - sorted in order of preference from highest to lowest. Each call to - wolfSSL_CTX_set_cipher_list() resets the cipher suite list for the - specific SSL context to the provided list each time the function is - called. The cipher suite list, list, is a null-terminated text string, - and a colon-delimited list. For example, one value for list may be - "DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256" Valid cipher - values are the full name values from the cipher_names[] array in - src/internal.c (for a definite list of valid cipher values check + \brief This function sets cipher suite list for a given WOLFSSL_CTX. + This cipher suite list becomes the default list for any new SSL sessions + (WOLFSSL) created using this context. The ciphers in the list should be + sorted in order of preference from highest to lowest. Each call to + wolfSSL_CTX_set_cipher_list() resets the cipher suite list for the + specific SSL context to the provided list each time the function is + called. The cipher suite list, list, is a null-terminated text string, + and a colon-delimited list. For example, one value for list may be + "DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256" Valid cipher + values are the full name values from the cipher_names[] array in + src/internal.c (for a definite list of valid cipher values check src/internal.c) - + \return SSL_SUCCESS will be returned upon successful function completion. \return SSL_FAILURE will be returned on failure. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). - \param list null-terminated text string and a colon-delimited list of + \param list null-terminated text string and a colon-delimited list of cipher suites to use with the specified SSL context. - + _Example_ \code WOLFSSL_CTX* ctx = 0; @@ -3033,7 +3033,7 @@ WOLFSSL_API int wolfSSL_CTX_get_cert_cache_memsize(WOLFSSL_CTX*); // failed to set cipher suite list } \endcode - + \sa wolfSSL_set_cipher_list \sa wolfSSL_CTX_new */ @@ -3042,25 +3042,25 @@ WOLFSSL_API int wolfSSL_CTX_set_cipher_list(WOLFSSL_CTX*, const char*); /*! \ingroup Setup - \brief This function sets cipher suite list for a given WOLFSSL object - (SSL session). The ciphers in the list should be sorted in order of - preference from highest to lowest. Each call to wolfSSL_set_cipher_list() - resets the cipher suite list for the specific SSL session to the provided - list each time the function is called. The cipher suite list, list, is a - null-terminated text string, and a colon-delimited list. For example, one - value for list may be - "DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256". - Valid cipher values are the full name values from the cipher_names[] - array in src/internal.c (for a definite list of valid cipher values + \brief This function sets cipher suite list for a given WOLFSSL object + (SSL session). The ciphers in the list should be sorted in order of + preference from highest to lowest. Each call to wolfSSL_set_cipher_list() + resets the cipher suite list for the specific SSL session to the provided + list each time the function is called. The cipher suite list, list, is a + null-terminated text string, and a colon-delimited list. For example, one + value for list may be + "DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256". + Valid cipher values are the full name values from the cipher_names[] + array in src/internal.c (for a definite list of valid cipher values check src/internal.c) - + \return SSL_SUCCESS will be returned upon successful function completion. \return SSL_FAILURE will be returned on failure. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - \param list null-terminated text string and a colon-delimited list of + \param list null-terminated text string and a colon-delimited list of cipher suites to use with the specified SSL session. - + _Example_ \code int ret = 0; @@ -3072,7 +3072,7 @@ WOLFSSL_API int wolfSSL_CTX_set_cipher_list(WOLFSSL_CTX*, const char*); // failed to set cipher suite list } \endcode - + \sa wolfSSL_CTX_set_cipher_list \sa wolfSSL_new */ @@ -3081,44 +3081,44 @@ WOLFSSL_API int wolfSSL_set_cipher_list(WOLFSSL*, const char*); /*! \brief This function informs the WOLFSSL DTLS object that the underlying UDP I/O is non-blocking. After an application creates a WOLFSSL object, - if it will be used with a non-blocking UDP socket, call + if it will be used with a non-blocking UDP socket, call wolfSSL_dtls_set_using_nonblock() on it. This lets the WOLFSSL object know - that receiving EWOULDBLOCK means that the recvfrom call would + that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out. - + \return none No return. - + \param ssl pointer to the DTLS session, created with wolfSSL_new(). - \param nonblock value used to set non-blocking flag on WOLFSSL object. + \param nonblock value used to set non-blocking flag on WOLFSSL object. Use 1 to specify non-blocking, otherwise 0. - + _Example_ \code WOLFSSL* ssl = 0; ... wolfSSL_dtls_set_using_nonblock(ssl, 1); \endcode - + \sa wolfSSL_dtls_get_using_nonblock \sa wolfSSL_dtls_got_timeout \sa wolfSSL_dtls_get_current_timeout */ WOLFSSL_API void wolfSSL_dtls_set_using_nonblock(WOLFSSL*, int); /*! - \brief This function allows the application to determine if wolfSSL is - using non-blocking I/O with UDP. If wolfSSL is using non-blocking I/O, this - function will return 1, otherwise 0. After an application creates a - WOLFSSL object, if it will be used with a non-blocking UDP socket, call - wolfSSL_dtls_set_using_nonblock() on it. This lets the WOLFSSL object know - that receiving EWOULDBLOCK means that the recvfrom call would block - rather than that it timed out. This function is only meaningful to DTLS + \brief This function allows the application to determine if wolfSSL is + using non-blocking I/O with UDP. If wolfSSL is using non-blocking I/O, this + function will return 1, otherwise 0. After an application creates a + WOLFSSL object, if it will be used with a non-blocking UDP socket, call + wolfSSL_dtls_set_using_nonblock() on it. This lets the WOLFSSL object know + that receiving EWOULDBLOCK means that the recvfrom call would block + rather than that it timed out. This function is only meaningful to DTLS sessions. - + \return 0 underlying I/O is blocking. \return 1 underlying I/O is non-blocking. - + \param ssl pointer to the DTLS session, created with wolfSSL_new(). - + _Example_ \code int ret = 0; @@ -3130,24 +3130,24 @@ WOLFSSL_API void wolfSSL_dtls_set_using_nonblock(WOLFSSL*, int); } ... \endcode - + \sa wolfSSL_dtls_set_using_nonblock \sa wolfSSL_dtls_got_timeout \sa wolfSSL_dtls_set_using_nonblock */ WOLFSSL_API int wolfSSL_dtls_get_using_nonblock(WOLFSSL*); /*! - \brief This function returns the current timeout value in seconds for - the WOLFSSL object. When using non-blocking sockets, something in the user - code needs to decide when to check for available recv data and how long - it has been waiting. The value returned by this function indicates how + \brief This function returns the current timeout value in seconds for + the WOLFSSL object. When using non-blocking sockets, something in the user + code needs to decide when to check for available recv data and how long + it has been waiting. The value returned by this function indicates how long the application should wait. - + \return seconds The current DTLS timeout value in seconds \return NOT_COMPILED_IN if wolfSSL was not built with DTLS support. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code int timeout = 0; @@ -3156,7 +3156,7 @@ WOLFSSL_API int wolfSSL_dtls_get_using_nonblock(WOLFSSL*); timeout = wolfSSL_get_dtls_current_timeout(ssl); printf(“DTLS timeout (sec) = %d\n”, timeout); \endcode - + \sa wolfSSL_dtls \sa wolfSSL_dtls_get_peer \sa wolfSSL_dtls_got_timeout @@ -3168,17 +3168,17 @@ WOLFSSL_API int wolfSSL_dtls_get_current_timeout(WOLFSSL* ssl); \ingroup Setup \brief This function sets the dtls timeout. - - \return SSL_SUCCESS returned if the function executes without an error. + + \return SSL_SUCCESS returned if the function executes without an error. The dtls_timeout_init and the dtls_timeout members of SSL have been set. - \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if - the timeout is not greater than 0. It will also return if the timeout + \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if + the timeout is not greater than 0. It will also return if the timeout argument exceeds the maximum value allowed. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param timeout an int type that will be set to the dtls_timeout_init + \param timeout an int type that will be set to the dtls_timeout_init member of the WOLFSSL structure. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -3191,7 +3191,7 @@ WOLFSSL_API int wolfSSL_dtls_get_current_timeout(WOLFSSL* ssl); // Failed to set DTLS timeout. } \endcode - + \sa wolfSSL_dtls_set_timeout_max \sa wolfSSL_dtls_got_timeout */ @@ -3199,15 +3199,15 @@ WOLFSSL_API int wolfSSL_dtls_set_timeout_init(WOLFSSL* ssl, int); /*! \brief This function sets the maximum dtls timeout. - + \return SSL_SUCCESS returned if the function executed without an error. - \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if - the timeout argument is not greater than zero or is less than the + \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if + the timeout argument is not greater than zero or is less than the dtls_timeout_init member of the WOLFSSL structure. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param timeout an int type representing the dtls maximum timeout. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -3219,34 +3219,34 @@ WOLFSSL_API int wolfSSL_dtls_set_timeout_init(WOLFSSL* ssl, int); // Failed to set the max timeout } \endcode - + \sa wolfSSL_dtls_set_timeout_init \sa wolfSSL_dtls_got_timeout */ WOLFSSL_API int wolfSSL_dtls_set_timeout_max(WOLFSSL* ssl, int); /*! - \brief When using non-blocking sockets with DTLS, this function should - be called on the WOLFSSL object when the controlling code thinks the - transmission has timed out. It performs the actions needed to retry - the last transmit, including adjusting the timeout value. If it + \brief When using non-blocking sockets with DTLS, this function should + be called on the WOLFSSL object when the controlling code thinks the + transmission has timed out. It performs the actions needed to retry + the last transmit, including adjusting the timeout value. If it has been too long, this will return a failure. - + \return SSL_SUCCESS will be returned upon success - \return SSL_FATAL_ERROR will be returned if there have been too many + \return SSL_FATAL_ERROR will be returned if there have been too many retransmissions/timeouts without getting a response from the peer. - \return NOT_COMPILED_IN will be returned if wolfSSL was not compiled with + \return NOT_COMPILED_IN will be returned if wolfSSL was not compiled with DTLS support. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code See the following files for usage examples: /examples/client/client.c /examples/server/server.c \endcode - + \sa wolfSSL_dtls_get_current_timeout \sa wolfSSL_dtls_get_peer \sa wolfSSL_dtls_set_peer @@ -3255,15 +3255,15 @@ WOLFSSL_API int wolfSSL_dtls_set_timeout_max(WOLFSSL* ssl, int); WOLFSSL_API int wolfSSL_dtls_got_timeout(WOLFSSL* ssl); /*! - \brief This function is used to determine if the SSL session has been + \brief This function is used to determine if the SSL session has been configured to use DTLS. - - \return 1 If the SSL session (ssl) has been configured to use DTLS, this - function will return 1. + + \return 1 If the SSL session (ssl) has been configured to use DTLS, this + function will return 1. \return 0 otherwise. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code int ret = 0; @@ -3283,18 +3283,18 @@ WOLFSSL_API int wolfSSL_dtls_got_timeout(WOLFSSL* ssl); WOLFSSL_API int wolfSSL_dtls(WOLFSSL* ssl); /*! - \brief This function sets the DTLS peer, peer (sockaddr_in) with size of + \brief This function sets the DTLS peer, peer (sockaddr_in) with size of peerSz. - + \return SSL_SUCCESS will be returned upon success. \return SSL_FAILURE will be returned upon failure. - \return SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled + \return SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled with DTLS support. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param peer pointer to peer’s sockaddr_in structure. \param peerSz size of the sockaddr_in structure pointed to by peer. - + _Example_ \code int ret = 0; @@ -3306,7 +3306,7 @@ WOLFSSL_API int wolfSSL_dtls(WOLFSSL* ssl); // failed to set DTLS peer } \endcode - + \sa wolfSSL_dtls_get_current_timeout \sa wolfSSL_dtls_get_peer \sa wolfSSL_dtls_got_timeout @@ -3315,23 +3315,23 @@ WOLFSSL_API int wolfSSL_dtls(WOLFSSL* ssl); WOLFSSL_API int wolfSSL_dtls_set_peer(WOLFSSL*, void*, unsigned int); /*! - \brief This function gets the sockaddr_in (of size peerSz) of the current - DTLS peer. The function will compare peerSz to the actual DTLS peer size - stored in the SSL session. If the peer will fit into peer, the peer’s + \brief This function gets the sockaddr_in (of size peerSz) of the current + DTLS peer. The function will compare peerSz to the actual DTLS peer size + stored in the SSL session. If the peer will fit into peer, the peer’s sockaddr_in will be copied into peer, with peerSz set to the size of peer. - + \return SSL_SUCCESS will be returned upon success. \return SSL_FAILURE will be returned upon failure. - \return SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled + \return SSL_NOT_IMPLEMENTED will be returned if wolfSSL was not compiled with DTLS support. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param peer pointer to memory location to store peer’s sockaddr_in + \param peer pointer to memory location to store peer’s sockaddr_in structure. - \param peerSz input/output size. As input, the size of the allocated memory - pointed to by peer. As output, the size of the actual sockaddr_in structure + \param peerSz input/output size. As input, the size of the allocated memory + pointed to by peer. As output, the size of the actual sockaddr_in structure pointed to by peer. - + _Example_ \code int ret = 0; @@ -3343,7 +3343,7 @@ WOLFSSL_API int wolfSSL_dtls_set_peer(WOLFSSL*, void*, unsigned int); // failed to get DTLS peer } \endcode - + \sa wolfSSL_dtls_get_current_timeout \sa wolfSSL_dtls_got_timeout \sa wolfSSL_dtls_set_peer @@ -3354,22 +3354,22 @@ WOLFSSL_API int wolfSSL_dtls_get_peer(WOLFSSL*, void*, unsigned int*); /*! \ingroup Debug - \brief This function converts an error code returned by - wolfSSL_get_error() into a more human-readable error string. - errNumber is the error code returned by wolfSSL_get_error() and data - is the storage buffer which the error string will be placed in. - The maximum length of data is 80 characters by default, as defined by + \brief This function converts an error code returned by + wolfSSL_get_error() into a more human-readable error string. + errNumber is the error code returned by wolfSSL_get_error() and data + is the storage buffer which the error string will be placed in. + The maximum length of data is 80 characters by default, as defined by MAX_ERROR_SZ is wolfssl/wolfcrypt/error.h. - - \return success On successful completion, this function returns the same + + \return success On successful completion, this function returns the same string as is returned in data. - \return failure Upon failure, this function returns a string with the + \return failure Upon failure, this function returns a string with the appropriate failure reason, msg. - + \param errNumber error code returned by wolfSSL_get_error(). - \param data output buffer containing human-readable error string matching + \param data output buffer containing human-readable error string matching errNumber. - + _Example_ \code int err = 0; @@ -3380,7 +3380,7 @@ WOLFSSL_API int wolfSSL_dtls_get_peer(WOLFSSL*, void*, unsigned int*); wolfSSL_ERR_error_string(err, buffer); printf(“err = %d, %s\n”, err, buffer); \endcode - + \sa wolfSSL_get_error \sa wolfSSL_ERR_error_string_n \sa wolfSSL_ERR_print_errors_fp @@ -3391,18 +3391,18 @@ WOLFSSL_API char* wolfSSL_ERR_error_string(unsigned long,char*); /*! \ingroup Debug - \brief This function is a version of wolfSSL_ERR_error_string() where - len specifies the maximum number of characters that may be written to buf. - Like wolfSSL_ERR_error_string(), this function converts an error code - returned from wolfSSL_get_error() into a more human-readable error string. + \brief This function is a version of wolfSSL_ERR_error_string() where + len specifies the maximum number of characters that may be written to buf. + Like wolfSSL_ERR_error_string(), this function converts an error code + returned from wolfSSL_get_error() into a more human-readable error string. The human-readable string is placed in buf. - + \return none No returns. - + \param e error code returned by wolfSSL_get_error(). \param buff output buffer containing human-readable error string matching e. \param len maximum length in characters which may be written to buf. - + _Example_ \code int err = 0; @@ -3413,7 +3413,7 @@ WOLFSSL_API char* wolfSSL_ERR_error_string(unsigned long,char*); wolfSSL_ERR_error_string_n(err, buffer, 80); printf(“err = %d, %s\n”, err, buffer); \endcode - + \sa wolfSSL_get_error \sa wolfSSL_ERR_error_string \sa wolfSSL_ERR_print_errors_fp @@ -3425,20 +3425,20 @@ WOLFSSL_API void wolfSSL_ERR_error_string_n(unsigned long e, char* buf, /*! \ingroup TLS - \brief This function checks the shutdown conditions in closeNotify or - connReset or sentNotify members of the Options structure. The Options + \brief This function checks the shutdown conditions in closeNotify or + connReset or sentNotify members of the Options structure. The Options structure is within the WOLFSSL structure. - + \return 1 SSL_SENT_SHUTDOWN is returned. \return 2 SS_RECEIVED_SHUTDOWN is returned. - - \param ssl a constant pointer to a WOLFSSL structure, created using + + \param ssl a constant pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code #include - + WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method ); WOLFSSL* ssl = WOLFSSL_new(ctx); … @@ -3453,7 +3453,7 @@ WOLFSSL_API void wolfSSL_ERR_error_string_n(unsigned long e, char* buf, Fatal error. } \endcode - + \sa wolfSSL_SESSION_free */ WOLFSSL_API int wolfSSL_get_shutdown(const WOLFSSL*); @@ -3461,15 +3461,15 @@ WOLFSSL_API int wolfSSL_get_shutdown(const WOLFSSL*); /*! \ingroup IO - \brief This function returns the resuming member of the options struct. The - flag indicates whether or not to reuse a session. If not, a new session must + \brief This function returns the resuming member of the options struct. The + flag indicates whether or not to reuse a session. If not, a new session must be established. - - \return This function returns an int type held in the Options structure + + \return This function returns an int type held in the Options structure representing the flag for session reuse. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -3478,7 +3478,7 @@ WOLFSSL_API int wolfSSL_get_shutdown(const WOLFSSL*); // No session reuse allowed. } \endcode - + \sa wolfSSL_SESSION_free \sa wolfSSL_GetSessionIndex \sa wolfSSL_memsave_session_cache @@ -3489,18 +3489,18 @@ WOLFSSL_API int wolfSSL_session_reused(WOLFSSL*); \ingroup TLS \brief This function checks to see if the connection is established. - - \return 0 returned if the connection is not established, i.e. the WOLFSSL + + \return 0 returned if the connection is not established, i.e. the WOLFSSL struct is NULL or the handshake is not done. - \return 1 returned if the connection is not established i.e. the WOLFSSL + \return 1 returned if the connection is not established i.e. the WOLFSSL struct is null or the handshake is not done. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _EXAMPLE_ \code #include - + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); WOLFSSL* ssl = wolfSSL_new(ctx); ... @@ -3508,7 +3508,7 @@ WOLFSSL_API int wolfSSL_session_reused(WOLFSSL*); Handshake is done and connection is established } \endcode - + \sa wolfSSL_set_accept_state \sa wolfSSL_get_keys \sa wolfSSL_set_shutdown @@ -3519,7 +3519,7 @@ WOLFSSL_API int wolfSSL_is_init_finished(WOLFSSL*); \ingroup IO \brief Returns the SSL version being used as a string. - + \return "SSLv3" Using SSLv3 \return "TLSv1" Using TLSv1 \return "TLSv1.1" Using TLSv1.1 @@ -3527,11 +3527,11 @@ WOLFSSL_API int wolfSSL_is_init_finished(WOLFSSL*); \return "TLSv1.3" Using TLSv1.3 \return "DTLS": Using DTLS \return "DTLSv1.2" Using DTLSv1.2 - \return "unknown" There was a problem determining which version of TLS + \return "unknown" There was a problem determining which version of TLS being used. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code wolfSSL_Init(); @@ -3542,7 +3542,7 @@ WOLFSSL_API int wolfSSL_is_init_finished(WOLFSSL*); ssl = wolfSSL_new(ctx); printf(wolfSSL_get_version("Using version: %s", ssl)); \endcode - + \sa wolfSSL_lib_version */ WOLFSSL_API const char* wolfSSL_get_version(WOLFSSL*); @@ -3551,13 +3551,13 @@ WOLFSSL_API const char* wolfSSL_get_version(WOLFSSL*); \ingroup IO \brief Returns the current cipher suit an ssl session is using. - - \return ssl->options.cipherSuite An integer representing the current + + \return ssl->options.cipherSuite An integer representing the current cipher suite. \return 0 The ssl session provided is null. - + \param ssl The SSL session to check. - + _Example_ \code wolfSSL_Init(); @@ -3566,13 +3566,13 @@ WOLFSSL_API const char* wolfSSL_get_version(WOLFSSL*); WOLFSSL_METHOD method = // Some wolfSSL method ctx = wolfSSL_CTX_new(method); ssl = wolfSSL_new(ctx); - + if(wolfSSL_get_current_cipher_suite(ssl) == 0) { // Error getting cipher suite } \endcode - + \sa wolfSSL_CIPHER_get_name \sa wolfSSL_get_current_cipher \sa wolfSSL_get_cipher_list @@ -3582,15 +3582,15 @@ WOLFSSL_API int wolfSSL_get_current_cipher_suite(WOLFSSL* ssl); /*! \ingroup IO - \brief This function returns a pointer to the current cipher in the + \brief This function returns a pointer to the current cipher in the ssl session. - - \return The function returns the address of the cipher member of the + + \return The function returns the address of the cipher member of the WOLFSSL struct. This is a pointer to the WOLFSSL_CIPHER structure. \return NULL returned if the WOLFSSL structure is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -3604,7 +3604,7 @@ WOLFSSL_API int wolfSSL_get_current_cipher_suite(WOLFSSL* ssl); // The cipher was returned to cipherCurr } \endcode - + \sa wolfSSL_get_cipher \sa wolfSSL_get_cipher_name_internal \sa wolfSSL_get_cipher_name @@ -3613,16 +3613,16 @@ WOLFSSL_API WOLFSSL_CIPHER* wolfSSL_get_current_cipher(WOLFSSL*); /*! \ingroup IO - - \brief This function matches the cipher suite in the SSL object with + + \brief This function matches the cipher suite in the SSL object with the available suites and returns the string representation. - - \return string This function returns the string representation of the + + \return string This function returns the string representation of the matched cipher suite. \return none It will return “None” if there are no suites matched. - + \param cipher a constant pointer to a WOLFSSL_CIPHER structure. - + _Example_ \code // gets cipher name in the format DHE_RSA ... @@ -3637,7 +3637,7 @@ WOLFSSL_API WOLFSSL_CIPHER* wolfSSL_get_current_cipher(WOLFSSL*); // sanity check on returned cipher } \endcode - + \sa wolfSSL_get_cipher \sa wolfSSL_get_current_cipher \sa wolfSSL_get_cipher_name_internal @@ -3648,14 +3648,14 @@ WOLFSSL_API const char* wolfSSL_CIPHER_get_name(const WOLFSSL_CIPHER* cipher); /*! \ingroup IO - \brief This function matches the cipher suite in the SSL object with + \brief This function matches the cipher suite in the SSL object with the available suites. - - \return This function returns the string value of the suite matched. It + + \return This function returns the string value of the suite matched. It will return “None” if there are no suites matched. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code #ifdef WOLFSSL_DTLS @@ -3668,7 +3668,7 @@ WOLFSSL_API const char* wolfSSL_CIPHER_get_name(const WOLFSSL_CIPHER* cipher); … #endif // WOLFSSL_DTLS \endcode - + \sa wolfSSL_CIPHER_get_name \sa wolfSSL_get_current_cipher */ @@ -3678,12 +3678,12 @@ WOLFSSL_API const char* wolfSSL_get_cipher(WOLFSSL*); \ingroup Setup \brief This function returns the WOLFSSL_SESSION from the WOLFSSL structure. - + \return WOLFSSL_SESSION On success return session pointer. \return NULL on failure returns NULL. - + \param ssl WOLFSSL structure to get session from. - + _Example_ \code WOLFSSL* ssl; @@ -3692,7 +3692,7 @@ WOLFSSL_API const char* wolfSSL_get_cipher(WOLFSSL*); ses = wolfSSL_get1_session(ssl); // check ses information \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -3701,28 +3701,28 @@ WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get1_session(WOLFSSL* ssl); /*! \ingroup Setup - \brief The wolfSSLv23_client_method() function is used to indicate that - the application is a client and will support the highest protocol - version supported by the server between SSL 3.0 - TLS 1.2. This function - allocates memory for and initializes a new WOLFSSL_METHOD structure - to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). - Both wolfSSL clients and servers have robust version downgrade capability. - If a specific protocol version method is used on either side, then only - that version will be negotiated or an error will be returned. For - example, a client that uses TLSv1 and tries to connect to a SSLv3 only - server will fail, likewise connecting to a TLSv1.1 will fail as well. - To resolve this issue, a client that uses the wolfSSLv23_client_method() - function will use the highest protocol version supported by the server and - downgrade to SSLv3 if needed. In this case, the client will be able to + \brief The wolfSSLv23_client_method() function is used to indicate that + the application is a client and will support the highest protocol + version supported by the server between SSL 3.0 - TLS 1.2. This function + allocates memory for and initializes a new WOLFSSL_METHOD structure + to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). + Both wolfSSL clients and servers have robust version downgrade capability. + If a specific protocol version method is used on either side, then only + that version will be negotiated or an error will be returned. For + example, a client that uses TLSv1 and tries to connect to a SSLv3 only + server will fail, likewise connecting to a TLSv1.1 will fail as well. + To resolve this issue, a client that uses the wolfSSLv23_client_method() + function will use the highest protocol version supported by the server and + downgrade to SSLv3 if needed. In this case, the client will be able to connect to a server running SSLv3 - TLSv1.2. \return pointer upon success a pointer to a WOLFSSL_METHOD. - \return Failure If memory allocation fails when calling XMALLOC, - the failure value of the underlying malloc() implementation will be + \return Failure If memory allocation fails when calling XMALLOC, + the failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters - + _Example_ \code WOLFSSL_METHOD* method; @@ -3735,7 +3735,7 @@ WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get1_session(WOLFSSL* ssl); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfSSLv3_client_method \sa wolfTLSv1_client_method \sa wolfTLSv1_1_client_method @@ -3748,15 +3748,15 @@ WOLFSSL_API WOLFSSL_METHOD* wolfSSLv23_client_method(void); /*! \ingroup IO - \brief This is used to set a byte pointer to the start of the + \brief This is used to set a byte pointer to the start of the internal memory buffer. - + \return size On success the size of the buffer is returned \return SSL_FATAL_ERROR If an error case was encountered. - + \param bio WOLFSSL_BIO structure to get memory buffer of. \param p byte pointer to set to memory buffer. - + _Example_ \code WOLFSSL_BIO* bio; @@ -3766,7 +3766,7 @@ WOLFSSL_API WOLFSSL_METHOD* wolfSSLv23_client_method(void); ret = wolfSSL_BIO_get_mem_data(bio, &p); // check ret value \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_s_mem \sa wolfSSL_BIO_set_fp @@ -3778,13 +3778,13 @@ WOLFSSL_API int wolfSSL_BIO_get_mem_data(WOLFSSL_BIO* bio,void* p); \ingroup IO \brief Sets the file descriptor for bio to use. - + \return SSL_SUCCESS(1) upon success. - + \param bio WOLFSSL_BIO structure to set fd. \param fd file descriptor to use. \param closeF flag for behavior when closing fd. - + _Example_ \code WOLFSSL_BIO* bio; @@ -3792,7 +3792,7 @@ WOLFSSL_API int wolfSSL_BIO_get_mem_data(WOLFSSL_BIO* bio,void* p); // setup bio wolfSSL_BIO_set_fd(bio, fd, BIO_NOCLOSE); \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_free */ @@ -3802,18 +3802,18 @@ WOLFSSL_API long wolfSSL_BIO_set_fd(WOLFSSL_BIO* b, int fd, int flag); \ingroup IO \brief This is used to get a BIO_SOCKET type WOLFSSL_BIO_METHOD. - - \return WOLFSSL_BIO_METHOD pointer to a WOLFSSL_BIO_METHOD structure + + \return WOLFSSL_BIO_METHOD pointer to a WOLFSSL_BIO_METHOD structure that is a socket type - + \param none No parameters. - + _Example_ \code WOLFSSL_BIO* bio; bio = wolfSSL_BIO_new(wolfSSL_BIO_s_socket); \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_s_mem */ @@ -3822,17 +3822,17 @@ WOLFSSL_API WOLFSSL_BIO_METHOD *wolfSSL_BIO_s_socket(void); /*! \ingroup IO - \brief This is used to set the size of write buffer for a - WOLFSSL_BIO. If write buffer has been previously set this - function will free it when resetting the size. It is similar to + \brief This is used to set the size of write buffer for a + WOLFSSL_BIO. If write buffer has been previously set this + function will free it when resetting the size. It is similar to wolfSSL_BIO_reset in that it resets read and write indexes to 0. - + \return SSL_SUCCESS On successfully setting the write buffer. \return SSL_FAILURE If an error case was encountered. - + \param bio WOLFSSL_BIO structure to set fd. \param size size of buffer to allocate. - + _Example_ \code WOLFSSL_BIO* bio; @@ -3841,7 +3841,7 @@ WOLFSSL_API WOLFSSL_BIO_METHOD *wolfSSL_BIO_s_socket(void); ret = wolfSSL_BIO_set_write_buf_size(bio, 15000); // check return value \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_s_mem \sa wolfSSL_BIO_free @@ -3851,20 +3851,20 @@ WOLFSSL_API int wolfSSL_BIO_set_write_buf_size(WOLFSSL_BIO *b, long size); /*! \ingroup IO - \brief This is used to pair two bios together. A pair of bios acts - similar to a two way pipe writing to one can be read by the other - and vice versa. It is expected that both bios be in the same thread, - this function is not thread safe. Freeing one of the two bios removes - both from being paired. If a write buffer size was not previously - set for either of the bios it is set to a default size of 17000 + \brief This is used to pair two bios together. A pair of bios acts + similar to a two way pipe writing to one can be read by the other + and vice versa. It is expected that both bios be in the same thread, + this function is not thread safe. Freeing one of the two bios removes + both from being paired. If a write buffer size was not previously + set for either of the bios it is set to a default size of 17000 (WOLFSSL_BIO_SIZE) before being paired. - + \return SSL_SUCCESS On successfully pairing the two bios. \return SSL_FAILURE If an error case was encountered. - + \param b1 WOLFSSL_BIO structure to set pair. \param b2 second WOLFSSL_BIO structure to complete pair. - + _Example_ \code WOLFSSL_BIO* bio; @@ -3875,7 +3875,7 @@ WOLFSSL_API int wolfSSL_BIO_set_write_buf_size(WOLFSSL_BIO *b, long size); ret = wolfSSL_BIO_make_bio_pair(bio, bio2); // check ret value \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_s_mem \sa wolfSSL_BIO_free @@ -3886,12 +3886,12 @@ WOLFSSL_API int wolfSSL_BIO_make_bio_pair(WOLFSSL_BIO *b1, WOLFSSL_BIO *b2); \ingroup IO \brief This is used to set the read request flag back to 0. - + \return SSL_SUCCESS On successfully setting value. \return SSL_FAILURE If an error case was encountered. - + \param bio WOLFSSL_BIO structure to set read request flag. - + _Example_ \code WOLFSSL_BIO* bio; @@ -3900,7 +3900,7 @@ WOLFSSL_API int wolfSSL_BIO_make_bio_pair(WOLFSSL_BIO *b1, WOLFSSL_BIO *b2); ret = wolfSSL_BIO_ctrl_reset_read_request(bio); // check ret value \endcode - + \sa wolfSSL_BIO_new, wolfSSL_BIO_s_mem \sa wolfSSL_BIO_new, wolfSSL_BIO_free */ @@ -3909,16 +3909,16 @@ WOLFSSL_API int wolfSSL_BIO_ctrl_reset_read_request(WOLFSSL_BIO *b); /*! \ingroup IO - \brief This is used to get a buffer pointer for reading from. Unlike - wolfSSL_BIO_nread the internal read index is not advanced by the number - returned from the function call. Reading past the value returned can + \brief This is used to get a buffer pointer for reading from. Unlike + wolfSSL_BIO_nread the internal read index is not advanced by the number + returned from the function call. Reading past the value returned can result in reading out of array bounds. - + \return >=0 on success return the number of bytes to read - + \param bio WOLFSSL_BIO structure to read from. \param buf pointer to set at beginning of read array. - + _Example_ \code WOLFSSL_BIO* bio; @@ -3929,7 +3929,7 @@ WOLFSSL_API int wolfSSL_BIO_ctrl_reset_read_request(WOLFSSL_BIO *b); // handle negative ret check // read ret bytes from bufPt \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_nwrite0 */ @@ -3938,20 +3938,20 @@ WOLFSSL_API int wolfSSL_BIO_nread0(WOLFSSL_BIO *bio, char **buf); /*! \ingroup IO - \brief This is used to get a buffer pointer for reading from. The internal - read index is advanced by the number returned from the function call with - buf being pointed to the beginning of the buffer to read from. In the - case that less bytes are in the read buffer than the value requested with - num the lesser value is returned. Reading past the value returned can + \brief This is used to get a buffer pointer for reading from. The internal + read index is advanced by the number returned from the function call with + buf being pointed to the beginning of the buffer to read from. In the + case that less bytes are in the read buffer than the value requested with + num the lesser value is returned. Reading past the value returned can result in reading out of array bounds. - + \return >=0 on success return the number of bytes to read \return WOLFSSL_BIO_ERROR(-1) on error case with nothing to read return -1 - + \param bio WOLFSSL_BIO structure to read from. \param buf pointer to set at beginning of read array. \param num number of bytes to try and read. - + _Example_ \code WOLFSSL_BIO* bio; @@ -3963,7 +3963,7 @@ WOLFSSL_API int wolfSSL_BIO_nread0(WOLFSSL_BIO *bio, char **buf); // handle negative ret check // read ret bytes from bufPt \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_nwrite */ @@ -3972,16 +3972,16 @@ WOLFSSL_API int wolfSSL_BIO_nread(WOLFSSL_BIO *bio, char **buf, int num); /*! \ingroup IO - \brief Gets a pointer to the buffer for writing as many bytes as returned by - the function. Writing more bytes to the pointer returned then the value + \brief Gets a pointer to the buffer for writing as many bytes as returned by + the function. Writing more bytes to the pointer returned then the value returned can result in writing out of bounds. - - \return int Returns the number of bytes that can be written to the buffer + + \return int Returns the number of bytes that can be written to the buffer pointer returned. \return WOLFSSL_BIO_UNSET(-2) in the case that is not part of a bio pair - \return WOLFSSL_BIO_ERROR(-1) in the case that there is no more room to + \return WOLFSSL_BIO_ERROR(-1) in the case that there is no more room to write to - + \param bio WOLFSSL_BIO structure to write to. \param buf pointer to buffer to write to. \param num number of bytes desired to be written. @@ -3996,7 +3996,7 @@ WOLFSSL_API int wolfSSL_BIO_nread(WOLFSSL_BIO *bio, char **buf, int num); // handle negative ret check // write ret bytes to bufPt \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_free \sa wolfSSL_BIO_nread @@ -4006,14 +4006,14 @@ WOLFSSL_API int wolfSSL_BIO_nwrite(WOLFSSL_BIO *bio, char **buf, int num); /*! \ingroup IO - \brief Resets bio to an initial state. As an example for type BIO_BIO + \brief Resets bio to an initial state. As an example for type BIO_BIO this resets the read and write index. - + \return 0 On successfully resetting the bio. \return WOLFSSL_BIO_ERROR(-1) Returned on bad input or unsuccessful reset. - + \param bio WOLFSSL_BIO structure to reset. - + _Example_ \code WOLFSSL_BIO* bio; @@ -4021,7 +4021,7 @@ WOLFSSL_API int wolfSSL_BIO_nwrite(WOLFSSL_BIO *bio, char **buf, int num); wolfSSL_BIO_reset(bio); //use pt \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_free */ @@ -4030,15 +4030,15 @@ WOLFSSL_API int wolfSSL_BIO_reset(WOLFSSL_BIO *bio); /*! \ingroup IO - \brief This function adjusts the file pointer to the offset given. This + \brief This function adjusts the file pointer to the offset given. This is the offset from the head of the file. - + \return 0 On successfully seeking. \return -1 If an error case was encountered. - + \param bio WOLFSSL_BIO structure to set. \param ofs offset into file. - + _Example_ \code WOLFSSL_BIO* bio; @@ -4050,7 +4050,7 @@ WOLFSSL_API int wolfSSL_BIO_reset(WOLFSSL_BIO *bio); ret = wolfSSL_BIO_seek(bio, 3); // check ret value \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_s_mem \sa wolfSSL_BIO_set_fp @@ -4061,15 +4061,15 @@ WOLFSSL_API int wolfSSL_BIO_seek(WOLFSSL_BIO *bio, int ofs); /*! \ingroup IO - \brief This is used to set and write to a file. WIll overwrite any data + \brief This is used to set and write to a file. WIll overwrite any data currently in the file and is set to close the file when the bio is freed. - + \return SSL_SUCCESS On successfully opening and setting file. \return SSL_FAILURE If an error case was encountered. - + \param bio WOLFSSL_BIO structure to set file. \param name name of file to write to. - + _Example_ \code WOLFSSL_BIO* bio; @@ -4078,7 +4078,7 @@ WOLFSSL_API int wolfSSL_BIO_seek(WOLFSSL_BIO *bio, int ofs); ret = wolfSSL_BIO_write_filename(bio, “test.txt”); // check ret value \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_s_file \sa wolfSSL_BIO_set_fp @@ -4089,14 +4089,14 @@ WOLFSSL_API int wolfSSL_BIO_write_filename(WOLFSSL_BIO *bio, char *name); /*! \ingroup IO - \brief This is used to set the end of file value. Common value is -1 so + \brief This is used to set the end of file value. Common value is -1 so as not to get confused with expected positive values. - + \return 0 returned on completion - + \param bio WOLFSSL_BIO structure to set end of file value. \param v value to set in bio. - + _Example_ \code WOLFSSL_BIO* bio; @@ -4105,9 +4105,9 @@ WOLFSSL_API int wolfSSL_BIO_write_filename(WOLFSSL_BIO *bio, char *name); ret = wolfSSL_BIO_set_mem_eof_return(bio, -1); // check ret value \endcode - - \sa wolfSSL_BIO_new - \sa wolfSSL_BIO_s_mem + + \sa wolfSSL_BIO_new + \sa wolfSSL_BIO_s_mem \sa wolfSSL_BIO_set_fp \sa wolfSSL_BIO_free */ @@ -4117,16 +4117,16 @@ WOLFSSL_API long wolfSSL_BIO_set_mem_eof_return(WOLFSSL_BIO *bio, int v); \ingroup IO \brief This is a getter function for WOLFSSL_BIO memory pointer. - - \return SSL_SUCCESS On successfully getting the pointer SSL_SUCCESS is + + \return SSL_SUCCESS On successfully getting the pointer SSL_SUCCESS is returned (currently value of 1). - \return SSL_FAILURE Returned if NULL arguments are passed in (currently + \return SSL_FAILURE Returned if NULL arguments are passed in (currently value of 0). - + \param bio pointer to the WOLFSSL_BIO structure for getting memory pointer. - \param ptr structure that is currently a char*. Is set to point to + \param ptr structure that is currently a char*. Is set to point to bio’s memory. - + _Example_ \code WOLFSSL_BIO* bio; @@ -4135,7 +4135,7 @@ WOLFSSL_API long wolfSSL_BIO_set_mem_eof_return(WOLFSSL_BIO *bio, int v); wolfSSL_BIO_get_mem_ptr(bio, &pt); //use pt \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_s_mem */ @@ -4145,15 +4145,15 @@ WOLFSSL_API long wolfSSL_BIO_get_mem_ptr(WOLFSSL_BIO *bio, WOLFSSL_BUF_MEM **m); \ingroup CertsKeys \brief This function copies the name of the x509 into a buffer. - - \return A char pointer to the buffer with the WOLFSSL_X509_NAME structures + + \return A char pointer to the buffer with the WOLFSSL_X509_NAME structures name member’s data is returned if the function executed normally. - + \param name a pointer to a WOLFSSL_X509 structure. - \param in a buffer to hold the name copied from the + \param in a buffer to hold the name copied from the WOLFSSL_X509_NAME structure. \param sz the maximum size of the buffer. - + _Example_ \code WOLFSSL_X509 x509; @@ -4165,7 +4165,7 @@ WOLFSSL_API long wolfSSL_BIO_get_mem_ptr(WOLFSSL_BIO *bio, WOLFSSL_BUF_MEM **m); // There’s nothing in the buffer. } \endcode - + \sa wolfSSL_X509_get_subject_name \sa wolfSSL_X509_get_issuer_name \sa wolfSSL_X509_get_isCA @@ -4178,13 +4178,13 @@ WOLFSSL_API char* wolfSSL_X509_NAME_oneline(WOLFSSL_X509_NAME*, char*, int \ingroup CertsKeys \brief This function returns the name of the certificate issuer. - - \return point a pointer to the WOLFSSL_X509 struct’s issuer member is + + \return point a pointer to the WOLFSSL_X509 struct’s issuer member is returned. \return NULL if the cert passed in is NULL. - + \param cert a pointer to a WOLFSSL_X509 structure. - + _Example_ \code WOLFSSL_X509* x509; @@ -4198,7 +4198,7 @@ WOLFSSL_API char* wolfSSL_X509_NAME_oneline(WOLFSSL_X509_NAME*, char*, int // issuer hods the name of the certificate issuer. } \endcode - + \sa wolfSSL_X509_get_subject_name \sa wolfSSL_X509_get_isCA \sa wolfSSL_get_peer_certificate @@ -4209,15 +4209,15 @@ WOLFSSL_API WOLFSSL_X509_NAME* wolfSSL_X509_get_issuer_name(WOLFSSL_X509*); /*! \ingroup CertsKeys - \brief This function returns the subject member of the WOLFSSL_X509 + \brief This function returns the subject member of the WOLFSSL_X509 structure. - - \return pointer a pointer to the WOLFSSL_X509_NAME structure. The pointer - may be NULL if the WOLFSSL_X509 struct is NULL or if the subject member of + + \return pointer a pointer to the WOLFSSL_X509_NAME structure. The pointer + may be NULL if the WOLFSSL_X509 struct is NULL or if the subject member of the structure is NULL. - + \param cert a pointer to a WOLFSSL_X509 structure. - + _Example_ \code WOLFSSL_X509* cert; @@ -4225,10 +4225,10 @@ WOLFSSL_API WOLFSSL_X509_NAME* wolfSSL_X509_get_issuer_name(WOLFSSL_X509*); … name = wolfSSL_X509_get_subject_name(cert); if(name == NULL){ - // Deal with the NULL cacse + // Deal with the NULL cacse } \endcode - + \sa wolfSSL_X509_get_issuer_name \sa wolfSSL_X509_get_isCA \sa wolfSSL_get_peer_certificate @@ -4238,15 +4238,15 @@ WOLFSSL_API WOLFSSL_X509_NAME* wolfSSL_X509_get_subject_name(WOLFSSL_X509*); /*! \ingroup CertsKeys - \brief Checks the isCa member of the WOLFSSL_X509 structure and returns + \brief Checks the isCa member of the WOLFSSL_X509 structure and returns the value. - - \return isCA returns the value in the isCA member of the WOLFSSL_X509 + + \return isCA returns the value in the isCA member of the WOLFSSL_X509 structure is returned. \return 0 returned if there is not a valid x509 structure passed in. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ /code WOLFSSL* ssl; @@ -4260,7 +4260,7 @@ WOLFSSL_API WOLFSSL_X509_NAME* wolfSSL_X509_get_subject_name(WOLFSSL_X509*); // Failure case } \endcode - + \sa wolfSSL_X509_get_issuer_name \sa wolfSSL_X509_get_isCA */ @@ -4270,14 +4270,14 @@ WOLFSSL_API int wolfSSL_X509_get_isCA(WOLFSSL_X509*); \ingroup CertsKeys \brief This function gets the text related to the passed in NID value. - + \return int returns the size of the text buffer. - + \param name WOLFSSL_X509_NAME to search for text. \param nid NID to search for. \param buf buffer to hold text when found. \param len length of buffer. - + _Example_ \code WOLFSSL_X509_NAME* name; @@ -4285,12 +4285,12 @@ WOLFSSL_API int wolfSSL_X509_get_isCA(WOLFSSL_X509*); int bufferSz; int ret; // get WOLFSSL_X509_NAME - ret = wolfSSL_X509_NAME_get_text_by_NID(name, NID_commonName, + ret = wolfSSL_X509_NAME_get_text_by_NID(name, NID_commonName, buffer, bufferSz); //check ret value \endcode - + \sa none */ WOLFSSL_API int wolfSSL_X509_NAME_get_text_by_NID( @@ -4299,15 +4299,15 @@ WOLFSSL_API int wolfSSL_X509_NAME_get_text_by_NID( /*! \ingroup CertsKeys - \brief This function returns the value stored in the sigOID + \brief This function returns the value stored in the sigOID member of the WOLFSSL_X509 structure. - + \return 0 returned if the WOLFSSL_X509 structure is NULL. - \return int an integer value is returned which was retrieved from + \return int an integer value is returned which was retrieved from the x509 object. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, @@ -4319,7 +4319,7 @@ WOLFSSL_API int wolfSSL_X509_NAME_get_text_by_NID( // Deal with an unexpected value } \endcode - + \sa wolfSSL_X509_get_signature \sa wolfSSL_X509_version \sa wolfSSL_X509_get_der @@ -4334,17 +4334,17 @@ WOLFSSL_API int wolfSSL_X509_get_signature_type(WOLFSSL_X509*); \ingroup CertsKeys \brief Gets the X509 signature and stores it in the buffer. - - \return SSL_SUCCESS returned if the function successfully executes. + + \return SSL_SUCCESS returned if the function successfully executes. The signature is loaded into the buffer. - \return SSL_FATAL_ERRROR returns if the x509 struct or the bufSz member - is NULL. There is also a check for the length member of the sig structure + \return SSL_FATAL_ERRROR returns if the x509 struct or the bufSz member + is NULL. There is also a check for the length member of the sig structure (sig is a member of x509). - + \param x509 pointer to a WOLFSSL_X509 structure. \param buf a char pointer to the buffer. \param bufSz an integer pointer to the size of the buffer. - + _Example_ \code WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL, @@ -4358,7 +4358,7 @@ WOLFSSL_API int wolfSSL_X509_get_signature_type(WOLFSSL_X509*); // The buffer was written to correctly. } \endcode - + \sa wolfSSL_X509_get_serial_number \sa wolfSSL_X509_get_signature_type \sa wolfSSL_X509_get_device_type @@ -4369,13 +4369,13 @@ WOLFSSL_API int wolfSSL_X509_get_signature(WOLFSSL_X509*, unsigned char*, int*); \ingroup CertsKeys \brief This function adds a certificate to the WOLFSSL_X509_STRE structure. - + \return SSL_SUCCESS If certificate is added successfully. \return SSL_FATAL_ERROR: If certificate is not added successfully. - + \param str certificate store to add the certificate to. \param x509 certificate to add. - + _Example_ \code WOLFSSL_X509_STORE* str; @@ -4384,7 +4384,7 @@ WOLFSSL_API int wolfSSL_X509_get_signature(WOLFSSL_X509*, unsigned char*, int*); ret = wolfSSL_X509_STORE_add_cert(str, x509); //check ret value \endcode - + \sa wolfSSL_X509_free */ WOLFSSL_API int wolfSSL_X509_STORE_add_cert( @@ -4393,15 +4393,15 @@ WOLFSSL_API int wolfSSL_X509_STORE_add_cert( /*! \ingroup CertsKeys - \brief This function is a getter function for chain variable + \brief This function is a getter function for chain variable in WOLFSSL_X509_STORE_CTX structure. Currently chain is not populated. - - \return pointer if successful returns WOLFSSL_STACK + + \return pointer if successful returns WOLFSSL_STACK (same as STACK_OF(WOLFSSL_X509)) pointer \return Null upon failure - + \param ctx certificate store ctx to get parse chain from. - + _Example_ \code WOLFSSL_STACK* sk; @@ -4409,7 +4409,7 @@ WOLFSSL_API int wolfSSL_X509_STORE_add_cert( sk = wolfSSL_X509_STORE_CTX_get_chain(ctx); //check sk for NULL and then use it. sk needs freed after done. \endcode - + \sa wolfSSL_sk_X509_free */ WOLFSSL_API WOLFSSL_STACK* wolfSSL_X509_STORE_CTX_get_chain( @@ -4418,16 +4418,16 @@ WOLFSSL_API WOLFSSL_STACK* wolfSSL_X509_STORE_CTX_get_chain( /*! \ingroup CertsKeys - \brief This function takes in a flag to change the behavior of the - WOLFSSL_X509_STORE structure passed in. An example of a flag used + \brief This function takes in a flag to change the behavior of the + WOLFSSL_X509_STORE structure passed in. An example of a flag used is WOLFSSL_CRL_CHECK. - + \return SSL_SUCCESS If no errors were encountered when setting the flag. \return <0 a negative vlaue will be returned upon failure. - + \param str certificate store to set flag in. \param flag flag for behavior. - + _Example_ \code WOLFSSL_X509_STORE* str; @@ -4438,7 +4438,7 @@ WOLFSSL_API WOLFSSL_STACK* wolfSSL_X509_STORE_CTX_get_chain( //check ret value and handle error case } \endcode - + \sa wolfSSL_X509_STORE_new \sa wolfSSL_X509_STORE_free */ @@ -4448,19 +4448,19 @@ WOLFSSL_API int wolfSSL_X509_STORE_set_flags(WOLFSSL_X509_STORE* store, /*! \ingroup Setup - \brief This function is used to copy a WOLFSSL_ASN1_INTEGER + \brief This function is used to copy a WOLFSSL_ASN1_INTEGER value to a WOLFSSL_BIGNUM structure. - - \return pointer On successfully copying the WOLFSSL_ASN1_INTEGER + + \return pointer On successfully copying the WOLFSSL_ASN1_INTEGER value a WOLFSSL_BIGNUM pointer is returned. \return Null upon failure. - + \param ai WOLFSSL_ASN1_INTEGER structure to copy from. - \param bn if wanting to copy into an already existing - WOLFSSL_BIGNUM struct then pass in a pointer to it. - Optionally this can be NULL and a new WOLFSSL_BIGNUM + \param bn if wanting to copy into an already existing + WOLFSSL_BIGNUM struct then pass in a pointer to it. + Optionally this can be NULL and a new WOLFSSL_BIGNUM structure will be created. - + _Example_ \code WOLFSSL_ASN1_INTEGER* ai; @@ -4472,7 +4472,7 @@ WOLFSSL_API int wolfSSL_X509_STORE_set_flags(WOLFSSL_X509_STORE* store, // wolfSSL_ASN1_INTEGER_to_BN(ai, bn); // check bn is or return value is not NULL \endcode - + \sa none */ WOLFSSL_API WOLFSSL_BIGNUM *wolfSSL_ASN1_INTEGER_to_BN(const WOLFSSL_ASN1_INTEGER *ai, @@ -4481,15 +4481,15 @@ WOLFSSL_API WOLFSSL_BIGNUM *wolfSSL_ASN1_INTEGER_to_BN(const WOLFSSL_ASN1_INTEGE /*! \ingroup Setup - \brief This function adds the certificate to the internal chain + \brief This function adds the certificate to the internal chain being built in the WOLFSSL_CTX structure. - + \return SSL_SUCCESS after successfully adding the certificate. \return SSL_FAILURE if failing to add the certificate to the chain. - + \param ctx WOLFSSL_CTX structure to add certificate to. \param x509 certificate to add to the chain. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -4499,7 +4499,7 @@ WOLFSSL_API WOLFSSL_BIGNUM *wolfSSL_ASN1_INTEGER_to_BN(const WOLFSSL_ASN1_INTEGE ret = wolfSSL_CTX_add_extra_chain_cert(ctx, x509); // check ret value \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_free */ @@ -4508,14 +4508,14 @@ WOLFSSL_API long wolfSSL_CTX_add_extra_chain_cert(WOLFSSL_CTX*, WOLFSSL_X509*); /*! \ingroup Setup - \brief This function returns the get read ahead flag from a + \brief This function returns the get read ahead flag from a WOLFSSL_CTX structure. - + \return flag On success returns the read ahead flag. \return SSL_FAILURE If ctx is NULL then SSL_FAILURE is returned. - + \param ctx WOLFSSL_CTX structure to get read ahead flag from. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -4524,7 +4524,7 @@ WOLFSSL_API long wolfSSL_CTX_add_extra_chain_cert(WOLFSSL_CTX*, WOLFSSL_X509*); flag = wolfSSL_CTX_get_read_ahead(ctx); //check flag \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_free \sa wolfSSL_CTX_set_read_ahead @@ -4535,12 +4535,12 @@ WOLFSSL_API int wolfSSL_CTX_get_read_ahead(WOLFSSL_CTX*); \ingroup Setup \brief This function sets the read ahead flag in the WOLFSSL_CTX structure. - + \return SSL_SUCCESS If ctx read ahead flag set. \return SSL_FAILURE If ctx is NULL then SSL_FAILURE is returned. - + \param ctx WOLFSSL_CTX structure to set read ahead flag. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -4550,7 +4550,7 @@ WOLFSSL_API int wolfSSL_CTX_get_read_ahead(WOLFSSL_CTX*); ret = wolfSSL_CTX_set_read_ahead(ctx, flag); // check return value \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_free \sa wolfSSL_CTX_get_read_ahead @@ -4561,13 +4561,13 @@ WOLFSSL_API int wolfSSL_CTX_set_read_ahead(WOLFSSL_CTX*, int v); \ingroup Setup \brief This function sets the options argument to use with OCSP. - + \return SSL_FAILURE If ctx or it’s cert manager is NULL. \return SSL_SUCCESS If successfully set. - + \param ctx WOLFSSL_CTX structure to set user argument. \param arg user argument. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -4578,7 +4578,7 @@ WOLFSSL_API int wolfSSL_CTX_set_read_ahead(WOLFSSL_CTX*, int v); //check ret value \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_free */ @@ -4587,15 +4587,15 @@ WOLFSSL_API long wolfSSL_CTX_set_tlsext_status_arg(WOLFSSL_CTX*, void* arg); /*! \ingroup Setup - \brief This function sets the optional argument to be passed to + \brief This function sets the optional argument to be passed to the PRF callback. - + \return SSL_FAILURE If ctx is NULL. \return SSL_SUCCESS If successfully set. - + \param ctx WOLFSSL_CTX structure to set user argument. \param arg user argument. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -4605,7 +4605,7 @@ WOLFSSL_API long wolfSSL_CTX_set_tlsext_status_arg(WOLFSSL_CTX*, void* arg); ret = wolfSSL_CTX_set_tlsext_opaques_prf_input_callback_arg(ctx, data); //check ret value \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_free */ @@ -4615,13 +4615,13 @@ WOLFSSL_API long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg( /*! \ingroup Setup - \brief This function sets the options mask in the ssl. - Some valid options are, SSL_OP_ALL, SSL_OP_COOKIE_EXCHANGE, - SSL_OP_NO_SSLv2, SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, + \brief This function sets the options mask in the ssl. + Some valid options are, SSL_OP_ALL, SSL_OP_COOKIE_EXCHANGE, + SSL_OP_NO_SSLv2, SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_COMPRESSION. - + \return val Returns the updated options mask value stored in ssl. - + \param s WOLFSSL structure to set options mask. \param op This function sets the options mask in the ssl. Some valid options are: @@ -4633,7 +4633,7 @@ WOLFSSL_API long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg( SSL_OP_NO_TLSv1_1 SSL_OP_NO_TLSv1_2 SSL_OP_NO_COMPRESSION - + _Example_ \code WOLFSSL* ssl; @@ -4653,11 +4653,11 @@ WOLFSSL_API long wolfSSL_set_options(WOLFSSL *s, long op); \ingroup Setup \brief This function returns the current options mask. - + \return val Returns the mask value stored in ssl. - + \param ssl WOLFSSL structure to get options mask from. - + _Example_ \code WOLFSSL* ssl; @@ -4665,7 +4665,7 @@ WOLFSSL_API long wolfSSL_set_options(WOLFSSL *s, long op); mask = wolfSSL_get_options(ssl); // check mask \endcode - + \sa wolfSSL_new \sa wolfSSL_free \sa wolfSSL_set_options @@ -4676,13 +4676,13 @@ WOLFSSL_API long wolfSSL_get_options(const WOLFSSL *s); \ingroup Setup \brief This is used to set the debug argument passed around. - + \return SSL_SUCCESS On successful setting argument. \return SSL_FAILURE If an NULL ssl passed in. - + \param ssl WOLFSSL structure to set argument in. \param arg argument to use. - + _Example_ \code WOLFSSL* ssl; @@ -4692,7 +4692,7 @@ WOLFSSL_API long wolfSSL_get_options(const WOLFSSL *s); ret = wolfSSL_set_tlsext_debug_arg(ssl, args); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -4700,19 +4700,19 @@ WOLFSSL_API long wolfSSL_set_tlsext_debug_arg(WOLFSSL *s, void *arg); /*! \ingroup openSSL - - \brief This function is called when the client application request - that a server send back an OCSP status response (also known as - OCSP stapling).Currently, the only supported type is + + \brief This function is called when the client application request + that a server send back an OCSP status response (also known as + OCSP stapling).Currently, the only supported type is TLSEXT_STATUSTYPE_ocsp. - + \return 1 upon success. \return 0 upon error. - + \param s pointer to WolfSSL struct which is created by SSL_new() function - \param type ssl extension type which TLSEXT_STATUSTYPE_ocsp is + \param type ssl extension type which TLSEXT_STATUSTYPE_ocsp is only supported. - + _Example_ \code WOLFSSL *ssl; @@ -4724,7 +4724,7 @@ WOLFSSL_API long wolfSSL_set_tlsext_debug_arg(WOLFSSL *s, void *arg); wolfSSL_free(ssl); wolfSSL_CTX_free(ctx); \endcode - + \sa wolfSSL_new \sa wolfSSL_CTX_new \sa wolfSSL_free @@ -4735,14 +4735,14 @@ WOLFSSL_API long wolfSSL_set_tlsext_status_type(WOLFSSL *s, int type); /*! \ingroup Setup - \brief This is used to get the results after trying to verify the peer's + \brief This is used to get the results after trying to verify the peer's certificate. - + \return X509_V_OK On successful verification. \return SSL_FAILURE If an NULL ssl passed in. - + \param ssl WOLFSSL structure to get verification results from. - + _Example_ \code WOLFSSL* ssl; @@ -4751,7 +4751,7 @@ WOLFSSL_API long wolfSSL_set_tlsext_status_type(WOLFSSL *s, int type); ret = wolfSSL_get_verify_result(ssl); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -4760,17 +4760,17 @@ WOLFSSL_API long wolfSSL_get_verify_result(const WOLFSSL *ssl); /*! \ingroup Debug - \brief This function converts an error code returned by - wolfSSL_get_error() into a more human-readable error string - and prints that string to the output file - fp. err is the - error code returned by wolfSSL_get_error() and fp is the + \brief This function converts an error code returned by + wolfSSL_get_error() into a more human-readable error string + and prints that string to the output file - fp. err is the + error code returned by wolfSSL_get_error() and fp is the file which the error string will be placed in. - + \return none No returns. - + \param fp output file for human-readable error string to be written to. \param err error code returned by wolfSSL_get_error(). - + _Example_ \code int err = 0; @@ -4780,7 +4780,7 @@ WOLFSSL_API long wolfSSL_get_verify_result(const WOLFSSL *ssl); err = wolfSSL_get_error(ssl, 0); wolfSSL_ERR_print_errors_fp(fp, err); \endcode - + \sa wolfSSL_get_error \sa wolfSSL_ERR_error_string \sa wolfSSL_ERR_error_string_n @@ -4789,16 +4789,16 @@ WOLFSSL_API long wolfSSL_get_verify_result(const WOLFSSL *ssl); WOLFSSL_API void wolfSSL_ERR_print_errors_fp(FILE*, int err); /*! - \brief The function sets the client_psk_cb member of the + \brief The function sets the client_psk_cb member of the WOLFSSL_CTX structure. - + \return none No returns. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - \param cb wc_psk_client_callback is a function pointer that will be + \param cb wc_psk_client_callback is a function pointer that will be stored in the WOLFSSL_CTX structure. - + _Example_ \code WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol def ); @@ -4809,7 +4809,7 @@ WOLFSSL_API void wolfSSL_ERR_print_errors_fp(FILE*, int err); … wolfSSL_CTX_set_psk_client_callback(ctx, my_psk_client_cb); \endcode - + \sa wolfSSL_set_psk_client_callback \sa wolfSSL_set_psk_server_callback \sa wolfSSL_CTX_set_psk_server_callback @@ -4820,12 +4820,12 @@ WOLFSSL_API void wolfSSL_CTX_set_psk_client_callback(WOLFSSL_CTX*, /*! \brief Sets the PSK client side callback. - + \return none No returns. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param cb a function pointer to type wc_psk_client_callback. - + _Example_ \code WOLFSSL* ssl; @@ -4841,7 +4841,7 @@ WOLFSSL_API void wolfSSL_CTX_set_psk_client_callback(WOLFSSL_CTX*, // could not set callback } \endcode - + \sa wolfSSL_CTX_set_psk_client_callback \sa wolfSSL_CTX_set_psk_server_callback \sa wolfSSL_set_psk_server_callback @@ -4853,13 +4853,13 @@ WOLFSSL_API void wolfSSL_set_psk_client_callback(WOLFSSL*, \ingroup CertsKeys \brief This function returns the psk identity hint. - - \return pointer a const char pointer to the value that was stored in + + \return pointer a const char pointer to the value that was stored in the arrays member of the WOLFSSL structure is returned. \return NULL returned if the WOLFSSL or Arrays structures are NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -4873,7 +4873,7 @@ WOLFSSL_API void wolfSSL_set_psk_client_callback(WOLFSSL*, // Hint wasn’t successfully retrieved } \endcode - + \sa wolfSSL_get_psk_identity */ WOLFSSL_API const char* wolfSSL_get_psk_identity_hint(const WOLFSSL*); @@ -4881,16 +4881,16 @@ WOLFSSL_API const char* wolfSSL_get_psk_identity_hint(const WOLFSSL*); /*! \ingroup CertsKeys - \brief The function returns a constant pointer to the client_identity + \brief The function returns a constant pointer to the client_identity member of the Arrays structure. - - \return string the string value of the client_identity member of the + + \return string the string value of the client_identity member of the Arrays structure. - \return NULL if the WOLFSSL structure is NULL or if the Arrays member of + \return NULL if the WOLFSSL structure is NULL or if the Arrays member of the WOLFSSL structure is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -4903,7 +4903,7 @@ WOLFSSL_API const char* wolfSSL_get_psk_identity_hint(const WOLFSSL*); // There is not a value in pskID } \endcode - + \sa wolfSSL_get_psk_identity_hint \sa wolfSSL_use_psk_identity_hint */ @@ -4912,16 +4912,16 @@ WOLFSSL_API const char* wolfSSL_get_psk_identity(const WOLFSSL*); /*! \ingroup CertsKeys - \brief This function stores the hint argument in the server_hint + \brief This function stores the hint argument in the server_hint member of the WOLFSSL_CTX structure. - + \return SSL_SUCCESS returned for successful execution of the function. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - \param hint a constant char pointer that will be copied to the + \param hint a constant char pointer that will be copied to the WOLFSSL_CTX structure. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -4936,7 +4936,7 @@ WOLFSSL_API const char* wolfSSL_get_psk_identity(const WOLFSSL*); // Failure case. } \endcode - + \sa wolfSSL_use_psk_identity_hint */ WOLFSSL_API int wolfSSL_CTX_use_psk_identity_hint(WOLFSSL_CTX*, const char*); @@ -4944,17 +4944,17 @@ WOLFSSL_API int wolfSSL_CTX_use_psk_identity_hint(WOLFSSL_CTX*, const char*); /*! \ingroup CertsKeys - \brief This function stores the hint argument in the server_hint member + \brief This function stores the hint argument in the server_hint member of the Arrays structure within the WOLFSSL structure. - - \return SSL_SUCCESS returned if the hint was successfully stored in the + + \return SSL_SUCCESS returned if the hint was successfully stored in the WOLFSSL structure. \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 + \para hint a constant character pointer that holds the hint to be saved in memory. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -4964,21 +4964,21 @@ WOLFSSL_API int wolfSSL_CTX_use_psk_identity_hint(WOLFSSL_CTX*, const char*); // Handle failure case. } \endcode - + \sa wolfSSL_CTX_use_psk_identity_hint */ WOLFSSL_API int wolfSSL_use_psk_identity_hint(WOLFSSL*, const char*); /*! - \brief This function sets the psk callback for the server side in + \brief This function sets the psk callback for the server side in the WOLFSSL_CTX structure. - + \return none No returns. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param cb a function pointer for the callback and will be stored in + \param cb a function pointer for the callback and will be stored in the WOLFSSL_CTX structure. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -4996,7 +4996,7 @@ WOLFSSL_API int wolfSSL_use_psk_identity_hint(WOLFSSL*, const char*); // The CTX object was not properly initialized. } \endcode - + \sa wc_psk_server_callback \sa wolfSSL_set_psk_client_callback \sa wolfSSL_set_psk_server_callback @@ -5006,15 +5006,15 @@ WOLFSSL_API void wolfSSL_CTX_set_psk_server_callback(WOLFSSL_CTX*, wc_psk_server_callback); /*! - \brief Sets the psk callback for the server side by setting the + \brief Sets the psk callback for the server side by setting the WOLFSSL structure options members. - + \return none No returns. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param cb a function pointer for the callback and will be stored in + \param cb a function pointer for the callback and will be stored in the WOLFSSL structure. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -5029,7 +5029,7 @@ WOLFSSL_API void wolfSSL_CTX_set_psk_server_callback(WOLFSSL_CTX*, wolfSSL_set_psk_server_callback(ssl, cb); } \endcode - + \sa wolfSSL_set_psk_client_callback \sa wolfSSL_CTX_set_psk_server_callback \sa wolfSSL_CTX_set_psk_client_callback @@ -5041,18 +5041,18 @@ WOLFSSL_API void wolfSSL_set_psk_server_callback(WOLFSSL*, wc_psk_server_callback); /*! - \ingroup Setup + \ingroup Setup - \brief This function enables the havAnon member of the CTX structure if + \brief This function enables the havAnon member of the CTX structure if HAVE_ANON is defined during compilation. - - \return SSL_SUCCESS returned if the function executed successfully and the + + \return SSL_SUCCESS returned if the function executed successfully and the haveAnnon member of the CTX is set to 1. \return SSL_FAILURE returned if the CTX structure was NULL. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -5064,10 +5064,10 @@ WOLFSSL_API void wolfSSL_set_psk_server_callback(WOLFSSL*, if(wolfSSL_CTX_set_cipher_list(ctx, “ADH_AES128_SHA”) != SSL_SUCCESS){ // failure case } - } + } #endif \endcode - + \sa none */ WOLFSSL_API int wolfSSL_CTX_allow_anon_cipher(WOLFSSL_CTX*); @@ -5075,20 +5075,20 @@ WOLFSSL_API int wolfSSL_CTX_allow_anon_cipher(WOLFSSL_CTX*); /*! \ingroup Setup - \brief The wolfSSLv23_server_method() function is used to indicate - that the application is a server and will support clients connecting - with protocol version from SSL 3.0 - TLS 1.2. This function allocates - memory for and initializes a new WOLFSSL_METHOD structure to be used when + \brief The wolfSSLv23_server_method() function is used to indicate + that the application is a server and will support clients connecting + with protocol version from SSL 3.0 - TLS 1.2. This function allocates + memory for and initializes a new WOLFSSL_METHOD structure to be used when creating the SSL/TLS context with wolfSSL_CTX_new(). - - \return pointer If successful, the call will return a pointer to the newly + + \return pointer If successful, the call will return a pointer to the newly created WOLFSSL_METHOD structure. - \return Failure If memory allocation fails when calling XMALLOC, the - failure value of the underlying malloc() implementation will be returned + \return Failure If memory allocation fails when calling XMALLOC, the + failure value of the underlying malloc() implementation will be returned (typically NULL with errno will be set to ENOMEM). - + \param none No parameters - + _Example_ \code WOLFSSL_METHOD* method; @@ -5102,7 +5102,7 @@ WOLFSSL_API int wolfSSL_CTX_allow_anon_cipher(WOLFSSL_CTX*); ctx = wolfSSL_CTX_new(method); ... \endcode - + \sa wolfSSLv3_server_method \sa wolfTLSv1_server_method \sa wolfTLSv1_1_server_method @@ -5116,12 +5116,12 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv23_server_method(void); \ingroup Setup \brief This is used to get the internal error state of the WOLFSSL structure. - + \return wolfssl_error returns ssl error state, usualy a negative \return BAD_FUNC_ARG if ssl is NULL. - + \return ssl WOLFSSL structure to get state from. - + _Example_ \code WOLFSSL* ssl; @@ -5130,7 +5130,7 @@ WOLFSSL_API WOLFSSL_METHOD *wolfSSLv23_server_method(void); ret = wolfSSL_state(ssl); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -5140,13 +5140,13 @@ WOLFSSL_API int wolfSSL_state(WOLFSSL* ssl); \ingroup CertsKeys \brief This function gets the peer’s certificate. - - \return pointer a pointer to the peerCert member of the WOLFSSL_X509 + + \return pointer a pointer to the peerCert member of the WOLFSSL_X509 structure if it exists. \return 0 returned if the peer certificate issuer size is not defined. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -5158,7 +5158,7 @@ WOLFSSL_API int wolfSSL_state(WOLFSSL* ssl); // You have a pointer peerCert to the peer certification } \endcode - + \sa wolfSSL_X509_get_issuer_name \sa wolfSSL_X509_get_subject_name \sa wolfSSL_X509_get_isCA @@ -5168,16 +5168,16 @@ WOLFSSL_API WOLFSSL_X509* wolfSSL_get_peer_certificate(WOLFSSL* ssl); /*! \ingroup Debug - \brief This function is similar to calling wolfSSL_get_error() and - getting SSL_ERROR_WANT_READ in return. If the underlying error state + \brief This function is similar to calling wolfSSL_get_error() and + getting SSL_ERROR_WANT_READ in return. If the underlying error state is SSL_ERROR_WANT_READ, this function will return 1, otherwise, 0. - - \return 1 wolfSSL_get_error() would return SSL_ERROR_WANT_READ, the + + \return 1 wolfSSL_get_error() would return SSL_ERROR_WANT_READ, the underlying I/O has data available for reading. \return 0 There is no SSL_ERROR_WANT_READ error state. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - + _Example_ \code int ret; @@ -5189,7 +5189,7 @@ WOLFSSL_API WOLFSSL_X509* wolfSSL_get_peer_certificate(WOLFSSL* ssl); // underlying I/O has data available for reading (SSL_ERROR_WANT_READ) } \endcode - + \sa wolfSSL_want_write \sa wolfSSL_get_error */ @@ -5198,17 +5198,17 @@ WOLFSSL_API int wolfSSL_want_read(WOLFSSL*); /*! \ingroup Debug - \brief This function is similar to calling wolfSSL_get_error() and getting - SSL_ERROR_WANT_WRITE in return. If the underlying error state is + \brief This function is similar to calling wolfSSL_get_error() and getting + SSL_ERROR_WANT_WRITE in return. If the underlying error state is SSL_ERROR_WANT_WRITE, this function will return 1, otherwise, 0. - - \return 1 wolfSSL_get_error() would return SSL_ERROR_WANT_WRITE, the - underlying I/O needs data to be written in order for progress to be + + \return 1 wolfSSL_get_error() would return SSL_ERROR_WANT_WRITE, the + underlying I/O needs data to be written in order for progress to be made in the underlying SSL connection. \return 0 There is no SSL_ERROR_WANT_WRITE error state. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - + _Example_ \code int ret; @@ -5219,7 +5219,7 @@ WOLFSSL_API int wolfSSL_want_read(WOLFSSL*); // underlying I/O needs data to be written (SSL_ERROR_WANT_WRITE) } \endcode - + \sa wolfSSL_want_read \sa wolfSSL_get_error */ @@ -5228,18 +5228,18 @@ WOLFSSL_API int wolfSSL_want_write(WOLFSSL*); /*! \ingroup Setup - \brief wolfSSL by default checks the peer certificate for a valid date - range and a verified signature. Calling this function before - wolfSSL_connect() or wolfSSL_accept() will add a domain name check to - the list of checks to perform. dn holds the domain name to check + \brief wolfSSL by default checks the peer certificate for a valid date + range and a verified signature. Calling this function before + wolfSSL_connect() or wolfSSL_accept() will add a domain name check to + the list of checks to perform. dn holds the domain name to check against the peer certificate when it’s received. - + \return SSL_SUCCESS upon success. \return SSL_FAILURE will be returned if a memory error was encountered. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param dn domain name to check against the peer certificate when received. - + _Example_ \code int ret = 0; @@ -5252,7 +5252,7 @@ WOLFSSL_API int wolfSSL_want_write(WOLFSSL*); // failed to enable domain name check } \endcode - + \sa none */ WOLFSSL_API int wolfSSL_check_domain_name(WOLFSSL* ssl, const char* dn); @@ -5260,13 +5260,13 @@ WOLFSSL_API int wolfSSL_check_domain_name(WOLFSSL* ssl, const char* dn); /*! \ingroup TLS - \brief Initializes the wolfSSL library for use. Must be called once per + \brief Initializes the wolfSSL library for use. Must be called once per application and before any other call to the library. - + \return SSL_SUCCESS If successful the call will return. \return BAD_MUTEX_E is an error that may be returned. \return WC_INIT_E wolfCrypt initialization error returned. - + _Example_ \code int ret = 0; @@ -5276,25 +5276,25 @@ WOLFSSL_API int wolfSSL_check_domain_name(WOLFSSL* ssl, const char* dn); } \endcode - + \sa wolfSSL_Cleanup */ WOLFSSL_API int wolfSSL_Init(void); /*! \ingroup TLS - - \brief Un-initializes the wolfSSL library from further use. Doesn’t have + + \brief Un-initializes the wolfSSL library from further use. Doesn’t have to be called, though it will free any resources used by the library. - + \return SSL_SUCCESS return no errors. \return BAD_MUTEX_E a mutex error return.] - + _Example_ \code wolfSSL_Cleanup(); \endcode - + \sa wolfSSL_Init */ WOLFSSL_API int wolfSSL_Cleanup(void); @@ -5303,12 +5303,12 @@ WOLFSSL_API int wolfSSL_Cleanup(void); \ingroup IO \brief This function returns the current library version. - - \return LIBWOLFSSL_VERSION_STRING a const char pointer defining the + + \return LIBWOLFSSL_VERSION_STRING a const char pointer defining the version. - + \param none No parameters. - + _Example_ \code char version[MAXSIZE]; @@ -5318,7 +5318,7 @@ WOLFSSL_API int wolfSSL_Cleanup(void); // Handle the mismatch case } \endcode - + \sa word32_wolfSSL_lib_version_hex */ WOLFSSL_API const char* wolfSSL_lib_version(void); @@ -5326,14 +5326,14 @@ WOLFSSL_API const char* wolfSSL_lib_version(void); /*! \ingroup IO - \brief This function returns the current library version in hexadecimal + \brief This function returns the current library version in hexadecimal notation. - + \return LILBWOLFSSL_VERSION_HEX returns the hexidecimal version defined in wolfssl/version.h. - + \param none No parameters. - + _Example_ \code word32 libV; @@ -5345,7 +5345,7 @@ WOLFSSL_API const char* wolfSSL_lib_version(void); // The expected result for libV } \endcode - + \sa wolfSSL_lib_version */ WOLFSSL_API unsigned int wolfSSL_lib_version_hex(void); @@ -5353,17 +5353,17 @@ WOLFSSL_API unsigned int wolfSSL_lib_version_hex(void); /*! \ingroup IO - \brief Performs the actual connect or accept based on the side of the SSL - method. If called from the client side then an wolfSSL_connect() is done + \brief Performs the actual connect or accept based on the side of the SSL + method. If called from the client side then an wolfSSL_connect() is done while a wolfSSL_accept() is performed if called from the server side. - - \return SSL_SUCCESS will be returned if successful. (Note, older versions + + \return SSL_SUCCESS will be returned if successful. (Note, older versions will return 0.) - \return SSL_FATAL_ERROR will be returned if the underlying call resulted + \return SSL_FATAL_ERROR will be returned if the underlying call resulted in an error. Use wolfSSL_get_error() to get a specific error code. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - + _Example_ \code int ret = SSL_FATAL_ERROR; @@ -5377,7 +5377,7 @@ WOLFSSL_API unsigned int wolfSSL_lib_version_hex(void); } ... \endcode - + \sa SSL_connect \sa SSL_accept */ @@ -5386,21 +5386,21 @@ WOLFSSL_API int wolfSSL_negotiate(WOLFSSL* ssl); /*! \ingroup Setup - \brief Turns on the ability to use compression for the SSL connection. - Both sides must have compression turned on otherwise compression will not be - used. The zlib library performs the actual data compression. To compile - into the library use --with-libz for the configure system and define - HAVE_LIBZ otherwise. Keep in mind that while compressing data before - sending decreases the actual size of the messages being sent and received, - the amount of data saved by compression usually takes longer in time to + \brief Turns on the ability to use compression for the SSL connection. + Both sides must have compression turned on otherwise compression will not be + used. The zlib library performs the actual data compression. To compile + into the library use --with-libz for the configure system and define + HAVE_LIBZ otherwise. Keep in mind that while compressing data before + sending decreases the actual size of the messages being sent and received, + the amount of data saved by compression usually takes longer in time to analyze than it does to send it raw on all but the slowest of networks. \return SSL_SUCCESS upon success. - \return NOT_COMPILED_IN will be returned if compression support wasn’t + \return NOT_COMPILED_IN will be returned if compression support wasn’t built into the library. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - + _Example_ \code int ret = 0; @@ -5411,7 +5411,7 @@ WOLFSSL_API int wolfSSL_negotiate(WOLFSSL* ssl); // successfully enabled compression for SSL session } \endcode - + \sa none */ WOLFSSL_API int wolfSSL_set_compression(WOLFSSL* ssl); @@ -5420,13 +5420,13 @@ WOLFSSL_API int wolfSSL_set_compression(WOLFSSL* ssl); \ingroup Setup \brief This function sets the SSL session timeout value in seconds. - + \return SSL_SUCCESS will be returned upon successfully setting the session. \return BAD_FUNC_ARG will be returned if ssl is NULL. - + \param ssl pointer to the SSL object, created with wolfSSL_new(). \param to value, in seconds, used to set the SSL session timeout. - + _Example_ \code int ret = 0; @@ -5439,7 +5439,7 @@ WOLFSSL_API int wolfSSL_set_compression(WOLFSSL* ssl); } ... \endcode - + \sa wolfSSL_get_session \sa wolfSSL_set_session */ @@ -5448,15 +5448,15 @@ WOLFSSL_API int wolfSSL_set_timeout(WOLFSSL*, unsigned int); /*! \ingroup Setup - \brief This function sets the timeout value for SSL sessions, in seconds, + \brief This function sets the timeout value for SSL sessions, in seconds, for the specified SSL context. - + \return SSL_SUCCESS will be returned upon success. \return BAD_FUNC_ARG will be returned when the input context (ctx) is null. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param to session timeout value in seconds. - + _Example_ \code WOLFSSL_CTX* ctx = 0; @@ -5466,7 +5466,7 @@ WOLFSSL_API int wolfSSL_set_timeout(WOLFSSL*, unsigned int); // failed to set session timeout value } \endcode - + \sa wolfSSL_flush_sessions \sa wolfSSL_get_session \sa wolfSSL_set_session @@ -5477,21 +5477,21 @@ WOLFSSL_API int wolfSSL_CTX_set_timeout(WOLFSSL_CTX*, unsigned int); /*! \ingroup openSSL - + \brief Retrieves the peer’s certificate chain. - - \return chain If successful the call will return the peer’s + + \return chain If successful the call will return the peer’s certificate chain. - \return 0 will be returned if an invalid WOLFSSL pointer is passed to the + \return 0 will be returned if an invalid WOLFSSL pointer is passed to the function. - + \param ssl pointer to a valid WOLFSSL structure. - + _Example_ \code none \endcode - + \sa wolfSSL_get_chain_count \sa wolfSSL_get_chain_length \sa wolfSSL_get_chain_cert @@ -5501,42 +5501,42 @@ WOLFSSL_API WOLFSSL_X509_CHAIN* wolfSSL_get_peer_chain(WOLFSSL* ssl); /*! \ingroup openSSL - + \brief Retrieve's the peers certificate chain count. - - \return Success If successful the call will return the peer’s certificate + + \return Success If successful the call will return the peer’s certificate chain count. - \return 0 will be returned if an invalid chain pointer is passed to + \return 0 will be returned if an invalid chain pointer is passed to the function. - + \param chain pointer to a valid WOLFSSL_X509_CHAIN structure. - + _Example_ \code none \endcode - + \sa wolfSSL_get_peer_chain \sa wolfSSL_get_chain_length \sa wolfSSL_get_chain_cert \sa wolfSSL_get_chain_cert_pem -*/ +*/ WOLFSSL_API int wolfSSL_get_chain_count(WOLFSSL_X509_CHAIN* chain); /*! \ingroup openSSL - - \brief Retrieves the peer’s ASN1.DER certificate length in bytes + + \brief Retrieves the peer’s ASN1.DER certificate length in bytes at index (idx). - - \return Success If successful the call will return the peer’s + + \return Success If successful the call will return the peer’s certificate length in bytes by index. - \return 0 will be returned if an invalid chain pointer is passed + \return 0 will be returned if an invalid chain pointer is passed to the function. - + \param chain pointer to a valid WOLFSSL_X509_CHAIN structure. \param idx index to start of chain. - + _Example_ \code none @@ -5551,22 +5551,22 @@ WOLFSSL_API int wolfSSL_get_chain_length(WOLFSSL_X509_CHAIN*, int idx); /*! \ingroup openSSL - + \brief Retrieves the peer’s ASN1.DER certificate at index (idx). - - \return Success If successful the call will return the peer’s + + \return Success If successful the call will return the peer’s certificate by index. - \return 0 will be returned if an invalid chain pointer is passed + \return 0 will be returned if an invalid chain pointer is passed to the function. \param chain pointer to a valid WOLFSSL_X509_CHAIN structure. \param idx index to start of chain. - + _Example_ \code none \endcode - + \sa wolfSSL_get_peer_chain \sa wolfSSL_get_chain_count \sa wolfSSL_get_chain_length @@ -5577,15 +5577,15 @@ WOLFSSL_API unsigned char* wolfSSL_get_chain_cert(WOLFSSL_X509_CHAIN*, int idx); /*! \ingroup CertsKeys - \brief This function gets the peer’s wolfSSL_X509_certificate at + \brief This function gets the peer’s wolfSSL_X509_certificate at index (idx) from the chain of certificates. - + \return pointer returns a pointer to a WOLFSSL_X509 structure. - - \param chain a pointer to the WOLFSSL_X509_CHAIN used for no dynamic + + \param chain a pointer to the WOLFSSL_X509_CHAIN used for no dynamic memory SESSION_CACHE. \param idx the index of the WOLFSSL_X509 certificate. - + _Example_ \code WOLFSSL_X509_CHAIN* chain = &session->chain; @@ -5597,10 +5597,10 @@ WOLFSSL_API unsigned char* wolfSSL_get_chain_cert(WOLFSSL_X509_CHAIN*, int idx); if(ptr != NULL){ //ptr contains the cert at the index specified } else { - // ptr is NULL + // ptr is NULL } \endcode - + \sa InitDecodedCert \sa ParseCertRelative \sa CopyDecodedToX509 @@ -5609,22 +5609,22 @@ WOLFSSL_API WOLFSSL_X509* wolfSSL_get_chain_X509(WOLFSSL_X509_CHAIN*, int idx); /*! \ingroup openSSL - + \brief Retrieves the peer’s PEM certificate at index (idx). - - \return Success If successful the call will return the peer’s + + \return Success If successful the call will return the peer’s certificate by index. - \return 0 will be returned if an invalid chain pointer is passed to + \return 0 will be returned if an invalid chain pointer is passed to the function. \param chain pointer to a valid WOLFSSL_X509_CHAIN structure. \param idx indexto start of chain. - + _Example_ \code none \endcode - + \sa wolfSSL_get_peer_chain \sa wolfSSL_get_chain_count \sa wolfSSL_get_chain_length @@ -5637,41 +5637,41 @@ WOLFSSL_API int wolfSSL_get_chain_cert_pem(WOLFSSL_X509_CHAIN*, int idx, \ingroup openSSL \brief Retrieves the session’s ID. The session ID is always 32 bytes long. - + \return id The session ID. - + \param session pointer to a valid wolfssl session. - + _Example_ \code none \endcode - + \sa SSL_get_session */ WOLFSSL_API const unsigned char* wolfSSL_get_sessionID(const WOLFSSL_SESSION* s); /*! \ingroup openSSL - - \brief Retrieves the peer’s certificate serial number. The serial - number buffer (in) should be at least 32 bytes long and be provided - as the *inOutSz argument as input. After calling the function *inOutSz + + \brief Retrieves the peer’s certificate serial number. The serial + number buffer (in) should be at least 32 bytes long and be provided + as the *inOutSz argument as input. After calling the function *inOutSz will hold the actual length in bytes written to the in buffer. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG will be returned if a bad function argument + \return BAD_FUNC_ARG will be returned if a bad function argument was encountered. - + \param in The serial number buffer and should be at least 32 bytes long - \param inOutSz will hold the actual length in bytes written to the + \param inOutSz will hold the actual length in bytes written to the in buffer. - + _Example_ \code none \endcode - + \sa SSL_get_peer_certificate */ WOLFSSL_API int wolfSSL_X509_get_serial_number(WOLFSSL_X509*,unsigned char*,int*); @@ -5680,14 +5680,14 @@ WOLFSSL_API int wolfSSL_X509_get_serial_number(WOLFSSL_X509*,unsigned char*,int \ingroup CertsKeys \brief Returns the common name of the subject from the certificate. - + \return NULL returned if the x509 structure is null - \return string a string representation of the subject's common + \return string a string representation of the subject's common name is returned upon success - - \param x509 a pointer to a WOLFSSL_X509 structure containing + + \param x509 a pointer to a WOLFSSL_X509 structure containing certificate information. - + _Example_ \code WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, @@ -5700,7 +5700,7 @@ WOLFSSL_API int wolfSSL_X509_get_serial_number(WOLFSSL_X509*,unsigned char*,int // x509Cn contains the common name } \endcode - + \sa wolfSSL_X509_Name_get_entry \sa wolfSSL_X509_get_next_altname \sa wolfSSL_X509_get_issuer_name @@ -5712,17 +5712,17 @@ WOLFSSL_API char* wolfSSL_X509_get_subjectCN(WOLFSSL_X509*); /*! \ingroup CertsKeys - \brief This function gets the DER encoded certificate in the + \brief This function gets the DER encoded certificate in the WOLFSSL_X509 struct. - - \return buffer This function returns the DerBuffer structure’s + + \return buffer This function returns the DerBuffer structure’s buffer member, which is of type byte. \return NULL returned if the x509 or outSz parameter is NULL. - - \param x509 a pointer to a WOLFSSL_X509 structure containing + + \param x509 a pointer to a WOLFSSL_X509 structure containing certificate information. \param outSz length of the derBuffer member of the WOLFSSL_X509 struct. - + _Example_ \code WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, @@ -5734,7 +5734,7 @@ WOLFSSL_API char* wolfSSL_X509_get_subjectCN(WOLFSSL_X509*); // Failure case one of the parameters was NULL } \endcode - + \sa wolfSSL_X509_version \sa wolfSSL_X509_Name_get_entry \sa wolfSSL_X509_get_next_altname @@ -5746,15 +5746,15 @@ WOLFSSL_API const unsigned char* wolfSSL_X509_get_der(WOLFSSL_X509*, int*); /*! \ingroup CertsKeys - \brief This function checks to see if x509 is NULL and if it’s not, + \brief This function checks to see if x509 is NULL and if it’s not, it returns the notAfter member of the x509 struct. - - \return pointer returns a constant byte pointer to the notAfter + + \return pointer returns a constant byte pointer to the notAfter member of the x509 struct. \return NULL returned if the x509 object is NULL. - + \param x509 a pointer to the WOLFSSL_X509 struct. - + _Example_ \code WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL, @@ -5765,8 +5765,8 @@ WOLFSSL_API const unsigned char* wolfSSL_X509_get_der(WOLFSSL_X509*, int*); // Failure case, the x509 object is null. } \endcode - - \sa none + + \sa none */ WOLFSSL_API const unsigned char* wolfSSL_X509_notAfter(WOLFSSL_X509*); @@ -5774,12 +5774,12 @@ WOLFSSL_API const unsigned char* wolfSSL_X509_notAfter(WOLFSSL_X509*); \ingroup CertsKeys \brief This function retrieves the version of the X509 certificate. - + \return 0 returned if the x509 structure is NULL. \return version the version stored in the x509 structure will be returned. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_X509* x509; @@ -5790,7 +5790,7 @@ WOLFSSL_API const unsigned char* wolfSSL_X509_notAfter(WOLFSSL_X509*); // The function returned 0, failure case. } \endcode - + \sa wolfSSL_X509_get_subject_name \sa wolfSSL_X509_get_issuer_name \sa wolfSSL_X509_get_isCA @@ -5801,19 +5801,19 @@ WOLFSSL_API int wolfSSL_X509_version(WOLFSSL_X509*); /*! \ingroup CertsKeys - \brief If NO_STDIO_FILESYSTEM is defined this function will allocate + \brief If NO_STDIO_FILESYSTEM is defined this function will allocate heap memory, initialize a WOLFSSL_X509 structure and return a pointer to it. - - \return *WOLFSSL_X509 WOLFSSL_X509 structure pointer is returned if + + \return *WOLFSSL_X509 WOLFSSL_X509 structure pointer is returned if the function executes successfully. \return NULL if the call to XFTELL macro returns a negative value. - + \param x509 a pointer to a WOLFSSL_X509 pointer. \param file a defined type that is a pointer to a FILE. - + _Example_ \code - WOLFSSL_X509* x509a = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, + WOLFSSL_X509* x509a = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, DYNAMIC_TYPE_X509); WOLFSSL_X509** x509 = x509a; XFILE file; (mapped to struct fs_file*) @@ -5823,7 +5823,7 @@ WOLFSSL_API int wolfSSL_X509_version(WOLFSSL_X509*); // The function returned NULL } \endcode - + \sa wolfSSL_X509_d2i \sa XFTELL \sa XREWIND @@ -5836,24 +5836,24 @@ WOLFSSL_API WOLFSSL_X509* \ingroup CertsKeys \brief The function loads the x509 certificate into memory. - - \return pointer a successful execution returns pointer to a + + \return pointer a successful execution returns pointer to a WOLFSSL_X509 structure. \return NULL returned if the certificate was not able to be written. - + \param fname the certificate file to be loaded. \param format the format of the certificate. - + _Example_ \code #define cliCert “certs/client-cert.pem” … X509* x509; … - x509 = wolfSSL_X509_load_certificate_file(cliCert, SSL_FILETYPE_PEM); + x509 = wolfSSL_X509_load_certificate_file(cliCert, SSL_FILETYPE_PEM); AssertNotNull(x509); \endcode - + \sa InitDecodedCert \sa PemToDer \sa wolfSSL_get_certificate @@ -5865,20 +5865,20 @@ WOLFSSL_API WOLFSSL_X509* /*! \ingroup CertsKeys - \brief This function copies the device type from the x509 structure + \brief This function copies the device type from the x509 structure to the buffer. - - \return pointer returns a byte pointer holding the device type from + + \return pointer returns a byte pointer holding the device type from the x509 structure. \return NULL returned if the buffer size is NULL. - - \param x509 pointer to a WOLFSSL_X509 structure, created with + + \param x509 pointer to a WOLFSSL_X509 structure, created with WOLFSSL_X509_new(). - \param in a pointer to a byte type that will hold the device type + \param in a pointer to a byte type that will hold the device type (the buffer). - \param inOutSz the minimum of either the parameter inOutSz or the + \param inOutSz the minimum of either the parameter inOutSz or the deviceTypeSz member of the x509 structure. - + _Example_ \code WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALOC(sizeof(WOLFSSL_X509), NULL, @@ -5892,7 +5892,7 @@ WOLFSSL_API WOLFSSL_X509* // Failure case, NULL was returned. } \endcode - + \sa wolfSSL_X509_get_hw_type \sa wolfSSL_X509_get_hw_serial_number \sa wolfSSL_X509_d2i @@ -5903,18 +5903,18 @@ WOLFSSL_API unsigned char* /*! \ingroup CertsKeys - \brief The function copies the hwType member of the WOLFSSL_X509 + \brief The function copies the hwType member of the WOLFSSL_X509 structure to the buffer. - - \return byte The function returns a byte type of the data previously held + + \return byte The function returns a byte type of the data previously held in the hwType member of the WOLFSSL_X509 structure. \return NULL returned if inOutSz is NULL. - - \param x509 a pointer to a WOLFSSL_X509 structure containing certificate + + \param x509 a pointer to a WOLFSSL_X509 structure containing certificate information. \param in pointer to type byte that represents the buffer. \param inOutSz pointer to type int that represents the size of the buffer. - + _Example_ \code WOLFSSL_X509* x509; // X509 certificate @@ -5927,7 +5927,7 @@ WOLFSSL_API unsigned char* // Failure case function returned NULL. } \endcode - + \sa wolfSSL_X509_get_hw_serial_number \sa wolfSSL_X509_get_device_type */ @@ -5938,21 +5938,21 @@ WOLFSSL_API unsigned char* \ingroup CertsKeys \brief This function returns the hwSerialNum member of the x509 object. - - \return pointer the function returns a byte pointer to the in buffer that - will contain the serial number loaded from the x509 object. - - \param x509 pointer to a WOLFSSL_X509 structure containing certificate + + \return pointer the function returns a byte pointer to the in buffer that + will contain the serial number loaded from the x509 object. + + \param x509 pointer to a WOLFSSL_X509 structure containing certificate information. \param in a pointer to the buffer that will be copied to. \param inOutSz a pointer to the size of the buffer. - + _Example_ \code char* serial; byte* in; int* inOutSz; - WOLFSSL_X509 x509; + WOLFSSL_X509 x509; ... serial = wolfSSL_X509_get_hw_serial_number(x509, in, inOutSz); @@ -5960,7 +5960,7 @@ WOLFSSL_API unsigned char* // Failure case } \endcode - + \sa wolfSSL_X509_get_subject_name \sa wolfSSL_X509_get_issuer_name \sa wolfSSL_X509_get_isCA @@ -5973,29 +5973,29 @@ WOLFSSL_API unsigned char* /*! \ingroup IO - \brief This function is called on the client side and initiates an - SSL/TLS handshake with a server only long enough to get the peer’s - certificate chain. When this function is called, the underlying - communication channel has already been set up. wolfSSL_connect_cert() - works with both blocking and non-blocking I/O. When the underlying I/O - is non-blocking, wolfSSL_connect_cert() will return when the underlying - I/O could not satisfy the needs of wolfSSL_connect_cert() 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_cert() 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_cert() will only return once the peer’s certificate chain + \brief This function is called on the client side and initiates an + SSL/TLS handshake with a server only long enough to get the peer’s + certificate chain. When this function is called, the underlying + communication channel has already been set up. wolfSSL_connect_cert() + works with both blocking and non-blocking I/O. When the underlying I/O + is non-blocking, wolfSSL_connect_cert() will return when the underlying + I/O could not satisfy the needs of wolfSSL_connect_cert() 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_cert() 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_cert() will only return once the peer’s certificate chain has been received. - + \return SSL_SUCCESS upon success. \return SSL_FAILURE will be returned if the SSL session parameter is NULL. - \return SSL_FATAL_ERROR will be returned if an error occurred. To get a more + \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(). - + _Example_ \code int ret = 0; @@ -6009,7 +6009,7 @@ WOLFSSL_API unsigned char* printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); } \endcode - + \sa wolfSSL_get_error \sa wolfSSL_connect \sa wolfSSL_accept @@ -6018,21 +6018,21 @@ WOLFSSL_API int wolfSSL_connect_cert(WOLFSSL* ssl); /*! \ingroup openSSL - - \brief wolfSSL_d2i_PKCS12_bio (d2i_PKCS12_bio) copies in the PKCS12 - information from WOLFSSL_BIO to the structure WC_PKCS12. The information - is divided up in the structure as a list of Content Infos along with a - structure to hold optional MAC information. After the information has been - divided into chunks (but not decrypted) in the structure WC_PKCS12, it can + + \brief wolfSSL_d2i_PKCS12_bio (d2i_PKCS12_bio) copies in the PKCS12 + information from WOLFSSL_BIO to the structure WC_PKCS12. The information + is divided up in the structure as a list of Content Infos along with a + structure to hold optional MAC information. After the information has been + divided into chunks (but not decrypted) in the structure WC_PKCS12, it can then be parsed and decrypted by calling. - - \return WC_PKCS12 pointer to a WC_PKCS12 structure. + + \return WC_PKCS12 pointer to a WC_PKCS12 structure. \return Failure If function failed it will return NULL. \param bio WOLFSSL_BIO structure to read PKCS12 buffer from. - \param pkcs12 WC_PKCS12 structure pointer for new PKCS12 structure created. + \param pkcs12 WC_PKCS12 structure pointer for new PKCS12 structure created. Can be NULL - + _Example_ \code WC_PKCS12* pkcs; @@ -6046,7 +6046,7 @@ WOLFSSL_API int wolfSSL_connect_cert(WOLFSSL* ssl); wc_PKCS12_free(pkcs) //use cert, pkey, and optionally certs stack \endcode - + \sa wolfSSL_PKCS12_parse \sa wc_PKCS12_free */ @@ -6055,37 +6055,37 @@ WOLFSSL_API WC_PKCS12* wolfSSL_d2i_PKCS12_bio(WOLFSSL_BIO* bio, /*! \ingroup openSSL - - \brief PKCS12 can be enabled with adding –enable-opensslextra to the - configure command. It can use triple DES and RC4 for decryption so would - recommend also enabling these features when enabling opensslextra - (--enable-des3 –enable-arc4). wolfSSL does not currently support RC2 so - decryption with RC2 is currently not available. This may be noticeable - with default encryption schemes used by OpenSSL command line to create - .p12 files. wolfSSL_PKCS12_parse (PKCS12_parse). The first thing this - function does is check the MAC is correct if present. If the MAC fails - then the function returns and does not try to decrypt any of the stored - Content Infos. This function then parses through each Content Info - looking for a bag type, if the bag type is known it is decrypted as - needed and either stored in the list of certificates being built or as - a key found. After parsing through all bags the key found is then - compared with the certificate list until a matching pair is found. - This matching pair is then returned as the key and certificate, - optionally the certificate list found is returned as a STACK_OF - certificates. At the moment a CRL, Secret or SafeContents bag will be - skipped over and not parsed. It can be seen if these or other “Unknown” - bags are skipped over by viewing the debug print out. Additional attributes + + \brief PKCS12 can be enabled with adding –enable-opensslextra to the + configure command. It can use triple DES and RC4 for decryption so would + recommend also enabling these features when enabling opensslextra + (--enable-des3 –enable-arc4). wolfSSL does not currently support RC2 so + decryption with RC2 is currently not available. This may be noticeable + with default encryption schemes used by OpenSSL command line to create + .p12 files. wolfSSL_PKCS12_parse (PKCS12_parse). The first thing this + function does is check the MAC is correct if present. If the MAC fails + then the function returns and does not try to decrypt any of the stored + Content Infos. This function then parses through each Content Info + looking for a bag type, if the bag type is known it is decrypted as + needed and either stored in the list of certificates being built or as + a key found. After parsing through all bags the key found is then + compared with the certificate list until a matching pair is found. + This matching pair is then returned as the key and certificate, + optionally the certificate list found is returned as a STACK_OF + certificates. At the moment a CRL, Secret or SafeContents bag will be + skipped over and not parsed. It can be seen if these or other “Unknown” + bags are skipped over by viewing the debug print out. Additional attributes such as friendly name are skipped over when parsing a PKCS12 file. \return SSL_SUCCESS On successfully parsing PKCS12. \return SSL_FAILURE If an error case was encountered. - + \param pkcs12 WC_PKCS12 structure to parse. \param paswd password for decrypting PKCS12. \param pkey structure to hold private key decoded from PKCS12. \param cert structure to hold certificate decoded from PKCS12. \param stack optional stack of extra certificates. - + _Example_ \code WC_PKCS12* pkcs; @@ -6099,7 +6099,7 @@ WOLFSSL_API WC_PKCS12* wolfSSL_d2i_PKCS12_bio(WOLFSSL_BIO* bio, wc_PKCS12_free(pkcs) //use cert, pkey, and optionally certs stack \endcode - + \sa wolfSSL_d2i_PKCS12_bio \sa wc_PKCS12_free */ @@ -6109,21 +6109,21 @@ WOLFSSL_API int wolfSSL_PKCS12_parse(WC_PKCS12* pkcs12, const char* psw, /*! \ingroup CertsKeys - \brief Server Diffie-Hellman Ephemeral parameters setting. This function - sets up the group parameters to be used if the server negotiates a cipher + \brief Server Diffie-Hellman Ephemeral parameters setting. This function + sets up the group parameters to be used if the server negotiates a cipher suite that uses DHE. - + \return SSL_SUCCESS upon success. \return MEMORY_ERROR will be returned if a memory error was encountered. - \return SIDE_ERROR will be returned if this function is called on an SSL + \return SIDE_ERROR will be returned if this function is called on an SSL client instead of an SSL server. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param p Diffie-Hellman prime number parameter. \param pSz size of p. \param g Diffie-Hellman “generator” parameter. \param gSz size of g. - + _Example_ \code WOLFSSL* ssl; @@ -6132,7 +6132,7 @@ WOLFSSL_API int wolfSSL_PKCS12_parse(WC_PKCS12* pkcs12, const char* psw, ... wolfSSL_SetTmpDH(ssl, p, sizeof(p), g, sizeof(g)); \endcode - + \sa SSL_accept */ WOLFSSL_API int wolfSSL_SetTmpDH(WOLFSSL*, const unsigned char* p, int pSz, @@ -6141,33 +6141,33 @@ WOLFSSL_API int wolfSSL_SetTmpDH(WOLFSSL*, const unsigned char* p, int pSz, /*! \ingroup CertsKeys - \brief The function calls the wolfSSL_SetTMpDH_buffer_wrapper, + \brief The function calls the wolfSSL_SetTMpDH_buffer_wrapper, which is a wrapper for Diffie-Hellman parameters. - + \return SSL_SUCCESS on successful execution. - \return SSL_BAD_FILETYPE if the file type is not PEM and is not - ASN.1. It will also be returned if the wc_DhParamsLoad does not + \return SSL_BAD_FILETYPE if the file type is not PEM and is not + ASN.1. It will also be returned if the wc_DhParamsLoad does not return normally. - \return SSL_NO_PEM_HEADER returns from PemToDer if there is not + \return SSL_NO_PEM_HEADER returns from PemToDer if there is not a PEM header. \return SSL_BAD_FILE returned if there is a file error in PemToDer. \return SSL_FATAL_ERROR returned from PemToDer if there was a copy error. \return MEMORY_E - if there was a memory allocation error. - \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if + \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if there was otherwise a NULL argument passed to a subroutine. - \return DH_KEY_SIZE_E is returned if their is a key size error in + \return DH_KEY_SIZE_E is returned if their is a key size error in wolfSSL_SetTmpDH() or in wolfSSL_CTX_SetTmpDH(). - \return SIDE_ERROR returned if it is not the server side + \return SIDE_ERROR returned if it is not the server side in wolfSSL_SetTmpDH. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param buf allocated buffer passed in from wolfSSL_SetTMpDH_file_wrapper. - \param sz a long int that holds the size of the file + \param sz a long int that holds the size of the file (fname within wolfSSL_SetTmpDH_file_wrapper). - \param format an integer type passed through from - wolfSSL_SetTmpDH_file_wrapper() that is a representation of the certificate + \param format an integer type passed through from + wolfSSL_SetTmpDH_file_wrapper() that is a representation of the certificate format. - + _Example_ \code Static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl, @@ -6178,7 +6178,7 @@ WOLFSSL_API int wolfSSL_SetTmpDH(WOLFSSL*, const unsigned char* p, int pSz, if(ssl) ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format); \endcode - + \sa wolfSSL_SetTmpDH_buffer_wrapper \sa wc_DhParamsLoad \sa wolfSSL_SetTmpDH @@ -6192,32 +6192,32 @@ WOLFSSL_API int wolfSSL_SetTmpDH_buffer(WOLFSSL*, const unsigned char* b, long /*! \ingroup CertsKeys - \brief This function calls wolfSSL_SetTmpDH_file_wrapper to set server + \brief This function calls wolfSSL_SetTmpDH_file_wrapper to set server Diffie-Hellman parameters. - - \return SSL_SUCCESS returned on successful completion of this function + + \return SSL_SUCCESS returned on successful completion of this function and its subroutines. - \return MEMORY_E returned if a memory allocation failed in this function + \return MEMORY_E returned if a memory allocation failed in this function or a subroutine. - \return SIDE_ERROR if the side member of the Options structure found + \return SIDE_ERROR if the side member of the Options structure found in the WOLFSSL struct is not the server side. \return SSL_BAD_FILETYPE returns if the certificate fails a set of checks. - \return BAD_FUNC_ARG returns if an argument value is NULL that is not + \return BAD_FUNC_ARG returns if an argument value is NULL that is not permitted such as, the WOLFSSL structure. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param fname a constant char pointer holding the certificate. \param format an integer type that holds the format of the certification. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); const char* dhParam; … - AssertIntNE(SSL_SUCCESS, + AssertIntNE(SSL_SUCCESS, wolfSSL_SetTmpDH_file(ssl, dhParam, SSL_FILETYPE_PEM)); \endcode - + \sa wolfSSL_CTX_SetTmpDH_file \sa wolfSSL_SetTmpDH_file_wrapper \sa wolfSSL_SetTmpDH_buffer @@ -6232,26 +6232,26 @@ WOLFSSL_API int wolfSSL_SetTmpDH_file(WOLFSSL*, const char* f, int format); \ingroup CertsKeys \brief Sets the parameters for the server CTX Diffie-Hellman. - - \return SSL_SUCCESS returned if the function and all subroutines + + \return SSL_SUCCESS returned if the function and all subroutines return without error. \return BAD_FUNC_ARG returned if the CTX, p or g parameters are NULL. - \return DH_KEY_SIZE_E returned if the minDhKeySz member of the + \return DH_KEY_SIZE_E returned if the minDhKeySz member of the WOLFSSL_CTX struct is not the correct size. - \return MEMORY_E returned if the allocation of memory failed in this + \return MEMORY_E returned if the allocation of memory failed in this function or a subroutine. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - \param p a constant unsigned char pointer loaded into the buffer + \param p a constant unsigned char pointer loaded into the buffer member of the serverDH_P struct. - \param pSz an int type representing the size of p, initialized + \param pSz an int type representing the size of p, initialized to MAX_DH_SIZE. - \param g a constant unsigned char pointer loaded into the buffer + \param g a constant unsigned char pointer loaded into the buffer member of the serverDH_G struct. - \param gSz an int type representing the size of g, initialized ot + \param gSz an int type representing the size of g, initialized ot MAX_DH_SIZE. - + _Exmaple_ \code WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol ); @@ -6266,7 +6266,7 @@ WOLFSSL_API int wolfSSL_SetTmpDH_file(WOLFSSL*, const char* f, int format); // Failure case } \endcode - + \sa wolfSSL_SetTmpDH \sa wc_DhParamsLoad */ @@ -6277,28 +6277,28 @@ WOLFSSL_API int wolfSSL_CTX_SetTmpDH(WOLFSSL_CTX*, const unsigned char* p, \ingroup CertsKeys \brief A wrapper function that calls wolfSSL_SetTmpDH_buffer_wrapper - + \return 0 returned for a successful execution. \return BAD_FUNC_ARG returned if the ctx or buf parameters are NULL. \return MEMORY_E if there is a memory allocation error. \return SSL_BAD_FILETYPE returned if format is not correct. - - \param ctx a pointer to a WOLFSSL structure, created using + + \param ctx a pointer to a WOLFSSL structure, created using wolfSSL_CTX_new(). - \param buf a pointer to a constant unsigned char type that is - allocated as the buffer and passed through to + \param buf a pointer to a constant unsigned char type that is + allocated as the buffer and passed through to wolfSSL_SetTmpDH_buffer_wrapper. - \param sz a long integer type that is derived from the fname parameter + \param sz a long integer type that is derived from the fname parameter in wolfSSL_SetTmpDH_file_wrapper(). - \param format an integer type passed through from + \param format an integer type passed through from wolfSSL_SetTmpDH_file_wrapper(). - + _Example_ \code static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl, Const char* fname, int format); #ifdef WOLFSSL_SMALL_STACK - byte staticBuffer[1]; // force heap usage + byte staticBuffer[1]; // force heap usage #else byte* staticBuffer; long sz = 0; @@ -6309,7 +6309,7 @@ WOLFSSL_API int wolfSSL_CTX_SetTmpDH(WOLFSSL_CTX*, const unsigned char* p, ret = wolfSSL_CTX_SetTmpDH_buffer(ctx, myBuffer, sz, format); } \endcode - + \sa wolfSSL_SetTmpDH_buffer_wrapper \sa wolfSSL_SetTMpDH_buffer \sa wolfSSL_SetTmpDH_file_wrapper @@ -6321,35 +6321,35 @@ WOLFSSL_API int wolfSSL_CTX_SetTmpDH_buffer(WOLFSSL_CTX*, const unsigned char* /*! \ingroup CertsKeys - \brief The function calls wolfSSL_SetTmpDH_file_wrapper to set the server + \brief The function calls wolfSSL_SetTmpDH_file_wrapper to set the server Diffie-Hellman parameters. - - \return SSL_SUCCESS returned if the wolfSSL_SetTmpDH_file_wrapper or any + + \return SSL_SUCCESS returned if the wolfSSL_SetTmpDH_file_wrapper or any of its subroutines return successfully. - \return MEMORY_E returned if an allocation of dynamic memory fails in a + \return MEMORY_E returned if an allocation of dynamic memory fails in a subroutine. - \return BAD_FUNC_ARG returned if the ctx or fname parameters are NULL or - if + \return BAD_FUNC_ARG returned if the ctx or fname parameters are NULL or + if a subroutine is passed a NULL argument. - \return SSL_BAD_FILE returned if the certificate file is unable to open or + \return SSL_BAD_FILE returned if the certificate file is unable to open or if the a set of checks on the file fail from wolfSSL_SetTmpDH_file_wrapper. - \return SSL_BAD_FILETYPE returned if teh format is not PEM or ASN.1 from + \return SSL_BAD_FILETYPE returned if teh format is not PEM or ASN.1 from wolfSSL_SetTmpDH_buffer_wrapper(). - \return DH_KEY_SIZE_E returned from wolfSSL_SetTmpDH() if the ctx + \return DH_KEY_SIZE_E returned from wolfSSL_SetTmpDH() if the ctx minDhKeySz member exceeds maximum size allowed for DH. - \return SIDE_ERROR returned in wolfSSL_SetTmpDH() if the side is not the + \return SIDE_ERROR returned in wolfSSL_SetTmpDH() if the side is not the server end. \return SSL_NO_PEM_HEADER returned from PemToDer if there is no PEM header. - \return SSL_FATAL_ERROR returned from PemToDer if there is a memory copy + \return SSL_FATAL_ERROR returned from PemToDer if there is a memory copy failure. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). \param fname a constant character pointer to a certificate file. - \param format an integer type passed through from - wolfSSL_SetTmpDH_file_wrapper() that is a representation of + \param format an integer type passed through from + wolfSSL_SetTmpDH_file_wrapper() that is a representation of the certificate format. - + _Example_ \code #define dhParam “certs/dh2048.pem” @@ -6358,10 +6358,10 @@ WOLFSSL_API int wolfSSL_CTX_SetTmpDH_buffer(WOLFSSL_CTX*, const unsigned char* … AssertNotNull(ctx = wolfSSL_CTX_new(wolfSSLv23_client_method())) … - AssertIntNE(SSL_SUCCESS, wolfSSL_CTX_SetTmpDH_file(NULL, dhParam, + AssertIntNE(SSL_SUCCESS, wolfSSL_CTX_SetTmpDH_file(NULL, dhParam, SSL_FILETYPE_PEM)); \endcode - + \sa wolfSSL_SetTmpDH_buffer_wrapper \sa wolfSSL_SetTmpDH \sa wolfSSL_CTX_SetTmpDH @@ -6377,24 +6377,24 @@ WOLFSSL_API int wolfSSL_CTX_SetTmpDH_file(WOLFSSL_CTX*, const char* f, /*! \ingroup CertsKeys - \brief This function sets the minimum size of the Diffie Hellman key size + \brief This function sets the minimum size of the Diffie Hellman key size by accessing the minDhKeySz member in the WOLFSSL_CTX structure. - + \return SSL_SUCCESS returned if the function completes successfully. - \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if + \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if the keySz is greater than 16,000 or not divisible by 8. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param keySz a word16 type used to set the minimum DH key size. The + \param keySz a word16 type used to set the minimum DH key size. The WOLFSSL_CTX struct holds this information in the minDhKeySz member. - + _Example_ \code public static int CTX_SetMinDhKey_Sz(IntPtr ctx, short minDhKey){ … return wolfSSL_CTX_SetMinDhKey_Sz(local_ctx, minDhKey); \endcode - + \sa wolfSSL_SetMinDhKey_Sz \sa CTX_SetMinDhKey_Sz \sa wolfSSL_GetDhKey_Sz @@ -6405,16 +6405,16 @@ WOLFSSL_API int wolfSSL_CTX_SetMinDhKey_Sz(WOLFSSL_CTX*, unsigned short); /*! \ingroup CertsKeys - \brief Sets the minimum size for a Diffie-Hellman key in the WOLFSSL + \brief Sets the minimum size for a Diffie-Hellman key in the WOLFSSL structure in bytes. - + \return SSL_SUCCESS the minimum size was successfully set. - \return BAD_FUNC_ARG the WOLFSSL structure was NULL or the keySz parameter + \return BAD_FUNC_ARG the WOLFSSL structure was NULL or the keySz parameter was greater than the allowable size or not divisible by 8. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param keySz a word16 type representing the bit size of the minimum DH key. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -6424,7 +6424,7 @@ WOLFSSL_API int wolfSSL_CTX_SetMinDhKey_Sz(WOLFSSL_CTX*, unsigned short); // Failed to set. } \endcode - + \sa wolfSSL_GetDhKey_Sz */ WOLFSSL_API int wolfSSL_SetMinDhKey_Sz(WOLFSSL*, unsigned short); @@ -6432,15 +6432,15 @@ WOLFSSL_API int wolfSSL_SetMinDhKey_Sz(WOLFSSL*, unsigned short); /*! \ingroup CertsKeys - \brief Returns the value of dhKeySz that is a member of the options + \brief Returns the value of dhKeySz that is a member of the options structure. This value represents the Diffie-Hellman key size in bytes. - - \return dhKeySz returns the value held in ssl->options.dhKeySz which is an + + \return dhKeySz returns the value held in ssl->options.dhKeySz which is an integer value. \return BAD_FUNC_ARG returns if the WOLFSSL struct is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -6455,7 +6455,7 @@ WOLFSSL_API int wolfSSL_SetMinDhKey_Sz(WOLFSSL*, unsigned short); // dhKeySz holds the size of the key. } \endcode - + \sa wolfSSL_SetMinDhKey_sz \sa wolfSSL_CTX_SetMinDhKey_Sz \sa wolfSSL_CTX_SetTmpDH @@ -6467,18 +6467,18 @@ WOLFSSL_API int wolfSSL_GetDhKey_Sz(WOLFSSL*); /*! \ingroup CertsKeys - \brief Sets the minimum RSA key size in both the WOLFSSL_CTX structure + \brief Sets the minimum RSA key size in both the WOLFSSL_CTX structure and the WOLFSSL_CERT_MANAGER structure. - + \return SSL_SUCCESS returned on successful execution of the function. - \return BAD_FUNC_ARG returned if the ctx structure is NULL or the keySz + \return BAD_FUNC_ARG returned if the ctx structure is NULL or the keySz is less than zero or not divisible by 8. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - \param keySz a short integer type stored in minRsaKeySz in the ctx + \param keySz a short integer type stored in minRsaKeySz in the ctx structure and the cm structure converted to bytes. - + _Example_ \code WOLFSSL_CTX* ctx = SSL_CTX_new(method); @@ -6490,7 +6490,7 @@ WOLFSSL_API int wolfSSL_GetDhKey_Sz(WOLFSSL*); if(wolfSSL_CTX_SetMinRsaKey_Sz(ctx, minRsaKeyBits) != SSL_SUCCESS){ … \endcode - + \sa wolfSSL_SetMinRsaKey_Sz */ WOLFSSL_API int wolfSSL_CTX_SetMinRsaKey_Sz(WOLFSSL_CTX*, short); @@ -6498,16 +6498,16 @@ WOLFSSL_API int wolfSSL_CTX_SetMinRsaKey_Sz(WOLFSSL_CTX*, short); /*! \ingroup CertsKeys - \brief Sets the minimum allowable key size in bytes for RSA located in the + \brief Sets the minimum allowable key size in bytes for RSA located in the WOLFSSL structure. - + \return SSL_SUCCESS the minimum was set successfully. - \return BAD_FUNC_ARG returned if the ssl structure is NULL or if the ksySz + \return BAD_FUNC_ARG returned if the ssl structure is NULL or if the ksySz is less than zero or not divisible by 8. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param keySz a short integer value representing the the minimum key in bits. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -6519,7 +6519,7 @@ WOLFSSL_API int wolfSSL_CTX_SetMinRsaKey_Sz(WOLFSSL_CTX*, short); Failed to set. } \endcode - + \sa wolfSSL_CTX_SetMinRsaKey_Sz */ WOLFSSL_API int wolfSSL_SetMinRsaKey_Sz(WOLFSSL*, short); @@ -6527,19 +6527,19 @@ WOLFSSL_API int wolfSSL_SetMinRsaKey_Sz(WOLFSSL*, short); /*! \ingroup CertsKeys - \brief Sets the minimum size in bytes for the ECC key in the WOLF_CTX + \brief Sets the minimum size in bytes for the ECC key in the WOLF_CTX structure and the WOLFSSL_CERT_MANAGER structure. - - \return SSL_SUCCESS returned for a successful execution and the minEccKeySz + + \return SSL_SUCCESS returned for a successful execution and the minEccKeySz member is set. - \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if + \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or if the keySz is negative or not divisible by 8. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - \param keySz a short integer type that represents the minimum ECC key + \param keySz a short integer type that represents the minimum ECC key size in bits. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -6549,7 +6549,7 @@ WOLFSSL_API int wolfSSL_SetMinRsaKey_Sz(WOLFSSL*, short); // Failed to set min key size } \endcode - + \sa wolfSSL_SetMinEccKey_Sz */ WOLFSSL_API int wolfSSL_CTX_SetMinEccKey_Sz(WOLFSSL_CTX*, short); @@ -6557,19 +6557,19 @@ WOLFSSL_API int wolfSSL_CTX_SetMinEccKey_Sz(WOLFSSL_CTX*, short); /*! \ingroup CertsKeys - \brief Sets the value of the minEccKeySz member of the options structure. - The options struct is a member of the WOLFSSL structure and is + \brief Sets the value of the minEccKeySz member of the options structure. + The options struct is a member of the WOLFSSL structure and is accessed through the ssl parameter. - - \return SSL_SUCCESS if the function successfully set the minEccKeySz + + \return SSL_SUCCESS if the function successfully set the minEccKeySz member of the options structure. - \return BAD_FUNC_ARG if the WOLFSSL_CTX structure is NULL or if the + \return BAD_FUNC_ARG if the WOLFSSL_CTX structure is NULL or if the key size (keySz) is less than 0 (zero) or not divisible by 8. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param keySz value used to set the minimum ECC key size. Sets + \param keySz value used to set the minimum ECC key size. Sets value in the options structure. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); // New session @@ -6579,7 +6579,7 @@ WOLFSSL_API int wolfSSL_CTX_SetMinEccKey_Sz(WOLFSSL_CTX*, short); // Failure case. } \endcode - + \sa wolfSSL_CTX_SetMinEccKey_Sz \sa wolfSSL_CTX_SetMinRsaKey_Sz \sa wolfSSL_SetMinRsaKey_Sz @@ -6589,20 +6589,20 @@ WOLFSSL_API int wolfSSL_SetMinEccKey_Sz(WOLFSSL*, short); /*! \ingroup CertsKeys - \brief This function is used by EAP_TLS and EAP-TTLS to derive + \brief This function is used by EAP_TLS and EAP-TTLS to derive keying material from the master secret. - - \return BUFFER_E returned if the actual size of the buffer exceeds + + \return BUFFER_E returned if the actual size of the buffer exceeds the maximum size allowable. \return MEMORY_E returned if there is an error with memory allocation. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param msk a void pointer variable that will hold the result + \param msk a void pointer variable that will hold the result of the p_hash function. - \param len an unsigned integer that represents the length of + \param len an unsigned integer that represents the length of the msk variable. \param label a constant char pointer that is copied from in PRF(). - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx);; @@ -6612,7 +6612,7 @@ WOLFSSL_API int wolfSSL_SetMinEccKey_Sz(WOLFSSL*, short); … return wolfSSL_make_eap_keys(ssl, msk, len, label); \endcode - + \sa PRF \sa doPRF \sa p_hash @@ -6625,24 +6625,24 @@ WOLFSSL_API int wolfSSL_make_eap_keys(WOLFSSL*, void* key, unsigned int len, /*! \ingroup IO - \brief Simulates writev semantics but doesn’t actually do block at a time - because of SSL_write() behavior and because front adds may be small. + \brief Simulates writev semantics but doesn’t actually do block at a time + because of SSL_write() behavior and because front adds may be small. Makes porting into software that uses writev easier. - + \return >0 the number of bytes written upon success. - \return 0 will be returned upon failure. Call wolfSSL_get_error() for + \return 0 will be returned upon failure. Call wolfSSL_get_error() for the specific error code. \return MEMORY_ERROR will be returned if a memory error was encountered. - \return SSL_FATAL_ERROR will be returned upon failure when either an error - occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or - SSL_ERROR_WANT_WRITE error was received and and the application needs to - call wolfSSL_write() again. Use wolfSSL_get_error() to get a specific + \return SSL_FATAL_ERROR will be returned upon failure when either an error + occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or + SSL_ERROR_WANT_WRITE error was received and and the application needs to + call wolfSSL_write() again. Use wolfSSL_get_error() to get a specific error code. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param iov array of I/O vectors to write \param iovcnt number of vectors in iov array. - + _Example_ \code WOLFSSL* ssl = 0; @@ -6660,7 +6660,7 @@ WOLFSSL_API int wolfSSL_make_eap_keys(WOLFSSL*, void* key, unsigned int len, ret = wolfSSL_writev(ssl, iov, iovcnt); // wrote “ret” bytes, or error if <= 0. \endcode - + \sa wolfSSL_write */ WOLFSSL_API int wolfSSL_writev(WOLFSSL* ssl, const struct iovec* iov, @@ -6669,28 +6669,28 @@ WOLFSSL_API int wolfSSL_writev(WOLFSSL* ssl, const struct iovec* iov, /*! \ingroup Setup - \brief This function unloads the CA signer list and frees + \brief This function unloads the CA signer list and frees the whole signer table. - + \return SSL_SUCCESS returned on successful execution of the function. - \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or there + \return BAD_FUNC_ARG returned if the WOLFSSL_CTX struct is NULL or there are otherwise unpermitted argument values passed in a subroutine. - \return BAD_MUTEX_E returned if there was a mutex error. The LockMutex() + \return BAD_MUTEX_E returned if there was a mutex error. The LockMutex() did not return 0. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - + _Example_ \code - WOLFSSL_METHOD method = wolfTLSv1_2_client_method(); + WOLFSSL_METHOD method = wolfTLSv1_2_client_method(); WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method); … if(!wolfSSL_CTX_UnloadCAs(ctx)){ // The function did not unload CAs } \endcode - + \sa wolfSSL_CertManagerUnloadCAs \sa LockMutex \sa FreeSignerTable @@ -6701,18 +6701,18 @@ WOLFSSL_API int wolfSSL_CTX_UnloadCAs(WOLFSSL_CTX*); /*! \ingroup Setup - \brief This function is used to unload all previously loaded trusted peer - certificates. Feature is enabled by defining the macro + \brief This function is used to unload all previously loaded trusted peer + certificates. Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT. - + \return SSL_SUCCESS upon success. \return BAD_FUNC_ARG will be returned if ctx is NULL. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). - + _Example_ \code int ret = 0; @@ -6724,7 +6724,7 @@ WOLFSSL_API int wolfSSL_CTX_UnloadCAs(WOLFSSL_CTX*); } ... \endcode - + \sa wolfSSL_CTX_trust_peer_buffer \sa wolfSSL_CTX_trust_peer_cert */ @@ -6733,43 +6733,43 @@ WOLFSSL_API int wolfSSL_CTX_Unload_trust_peers(WOLFSSL_CTX*); /*! \ingroup Setup - \brief This function loads a certificate to use for verifying a peer - when performing a TLS/SSL handshake. The peer certificate sent during - the handshake is compared by using the SKID when available and the - signature. If these two things do not match then any loaded CAs are used. - Is the same functionality as wolfSSL_CTX_trust_peer_cert except is from - a buffer instead of a file. Feature is enabled by defining the macro + \brief This function loads a certificate to use for verifying a peer + when performing a TLS/SSL handshake. The peer certificate sent during + the handshake is compared by using the SKID when available and the + signature. If these two things do not match then any loaded CAs are used. + Is the same functionality as wolfSSL_CTX_trust_peer_cert except is from + a buffer instead of a file. Feature is enabled by defining the macro WOLFSSL_TRUST_PEER_CERT Please see the examples for proper usage. - + \return SSL_SUCCESS upon success - \return SSL_FAILURE will be returned if ctx is NULL, or if both file and + \return SSL_FAILURE will be returned if ctx is NULL, or if both file and type are invalid. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param buffer pointer to the buffer containing certificates. \param sz length of the buffer input. - \param type type of certificate being loaded i.e. SSL_FILETYPE_ASN1 or + \param type type of certificate being loaded i.e. SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + _Example_ \code int ret = 0; WOLFSSL_CTX* ctx; ... - ret = wolfSSL_CTX_trust_peer_buffer(ctx, bufferPtr, bufferSz, + ret = wolfSSL_CTX_trust_peer_buffer(ctx, bufferPtr, bufferSz, SSL_FILETYPE_PEM); if (ret != SSL_SUCCESS) { // error loading trusted peer cert } ... \endcode - + \sa wolfSSL_CTX_load_verify_buffer \sa wolfSSL_CTX_use_certificate_file \sa wolfSSL_CTX_use_PrivateKey_file @@ -6787,29 +6787,29 @@ WOLFSSL_API int wolfSSL_CTX_trust_peer_buffer(WOLFSSL_CTX*, /*! \ingroup CertsKeys - \brief This function loads a CA certificate buffer into the WOLFSSL - Context. It behaves like the non-buffered version, only differing in - its ability to be called with a buffer as input instead of a file. - The buffer is provided by the in argument of size sz. format specifies - the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - More than one CA certificate may be loaded per buffer as long as the + \brief This function loads a CA certificate buffer into the WOLFSSL + Context. It behaves like the non-buffered version, only differing in + its ability to be called with a buffer as input instead of a file. + The buffer is provided by the in argument of size sz. format specifies + the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. + More than one CA certificate may be loaded per buffer as long as the format is in PEM. Please see the examples for proper usage. - + \return SSL_SUCCESS upon success \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - \return BUFFER_E will be returned if a chain buffer is bigger than + \return BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param in pointer to the CA certificate buffer. \param sz size of the input CA certificate buffer, in. - \param format format of the buffer certificate, either SSL_FILETYPE_ASN1 + \param format format of the buffer certificate, either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + _Example_ \code int ret = 0; @@ -6817,14 +6817,14 @@ WOLFSSL_API int wolfSSL_CTX_trust_peer_buffer(WOLFSSL_CTX*, WOLFSSL_CTX* ctx; byte certBuff[...]; ... - + ret = wolfSSL_CTX_load_verify_buffer(ctx, certBuff, sz, SSL_FILETYPE_PEM); if (ret != SSL_SUCCESS) { // error loading CA certs from buffer } ... - \endcode - + \endcode + \sa wolfSSL_CTX_load_verify_locations \sa wolfSSL_CTX_use_certificate_buffer \sa wolfSSL_CTX_use_PrivateKey_buffer @@ -6840,26 +6840,26 @@ WOLFSSL_API int wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX*, /*! \ingroup CertsKeys - \brief This function loads a certificate buffer into the WOLFSSL Context. - It behaves like the non-buffered version, only differing in its ability - to be called with a buffer as input instead of a file. The buffer is - provided by the in argument of size sz. format specifies the format - type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please + \brief This function loads a certificate buffer into the WOLFSSL Context. + It behaves like the non-buffered version, only differing in its ability + to be called with a buffer as input instead of a file. The buffer is + provided by the in argument of size sz. format specifies the format + type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage. - + \return SSL_SUCCESS upon success \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param in the input buffer containing the certificate to be loaded. \param sz the size of the input buffer. - \param format the format of the certificate located in the input + \param format the format of the certificate located in the input buffer (in). Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + _Example_ \code int ret = 0; @@ -6873,7 +6873,7 @@ WOLFSSL_API int wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX*, } ... \endcode - + \sa wolfSSL_CTX_load_verify_buffer \sa wolfSSL_CTX_use_PrivateKey_buffer \sa wolfSSL_CTX_use_NTRUPrivateKey_file @@ -6888,28 +6888,28 @@ WOLFSSL_API int wolfSSL_CTX_use_certificate_buffer(WOLFSSL_CTX*, /*! \ingroup CertsKeys - \brief This function loads a private key buffer into the SSL Context. - It behaves like the non-buffered version, only differing in its ability - to be called with a buffer as input instead of a file. The buffer is - provided by the in argument of size sz. format specifies the format type - of the buffer; SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM. Please see the + \brief This function loads a private key buffer into the SSL Context. + It behaves like the non-buffered version, only differing in its ability + to be called with a buffer as input instead of a file. The buffer is + provided by the in argument of size sz. format specifies the format type + of the buffer; SSL_FILETYPE_ASN1or SSL_FILETYPE_PEM. Please see the examples for proper usage. - + \return SSL_SUCCESS upon success \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - \return NO_PASSWORD will be returned if the key file is encrypted but no + \return NO_PASSWORD will be returned if the key file is encrypted but no password is provided. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param in the input buffer containing the private key to be loaded. \param sz the size of the input buffer. - \param format the format of the private key located in the input + \param format the format of the private key located in the input buffer (in). Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + _Example_ \code int ret = 0; @@ -6923,7 +6923,7 @@ WOLFSSL_API int wolfSSL_CTX_use_certificate_buffer(WOLFSSL_CTX*, } ... \endcode - + \sa wolfSSL_CTX_load_verify_buffer \sa wolfSSL_CTX_use_certificate_buffer \sa wolfSSL_CTX_use_NTRUPrivateKey_file @@ -6938,27 +6938,27 @@ WOLFSSL_API int wolfSSL_CTX_use_PrivateKey_buffer(WOLFSSL_CTX*, /*! \ingroup CertsKeys - \brief This function loads a certificate chain buffer into the WOLFSSL - Context. It behaves like the non-buffered version, only differing in - its ability to be called with a buffer as input instead of a file. - The buffer is provided by the in argument of size sz. The buffer must - be in PEM format and start with the subject’s certificate, ending with + \brief This function loads a certificate chain buffer into the WOLFSSL + Context. It behaves like the non-buffered version, only differing in + its ability to be called with a buffer as input instead of a file. + The buffer is provided by the in argument of size sz. The buffer must + be in PEM format and start with the subject’s certificate, ending with the root certificate. Please see the examples for proper usage. - + \return SSL_SUCCESS upon success \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - \return BUFFER_E will be returned if a chain buffer is bigger than + \return BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). - \param in the input buffer containing the PEM-formatted certificate + \param in the input buffer containing the PEM-formatted certificate chain to be loaded. \param sz the size of the input buffer. - + _Example_ \code int ret = 0; @@ -6972,7 +6972,7 @@ WOLFSSL_API int wolfSSL_CTX_use_PrivateKey_buffer(WOLFSSL_CTX*, } ... \endcode - + \sa wolfSSL_CTX_load_verify_buffer \sa wolfSSL_CTX_use_certificate_buffer \sa wolfSSL_CTX_use_PrivateKey_buffer @@ -6987,26 +6987,26 @@ WOLFSSL_API int wolfSSL_CTX_use_certificate_chain_buffer(WOLFSSL_CTX*, /*! \ingroup CertsKeys - \brief This function loads a certificate buffer into the WOLFSSL object. - It behaves like the non-buffered version, only differing in its ability - to be called with a buffer as input instead of a file. The buffer - is provided by the in argument of size sz. format specifies the format - type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. + \brief This function loads a certificate buffer into the WOLFSSL object. + It behaves like the non-buffered version, only differing in its ability + to be called with a buffer as input instead of a file. The buffer + is provided by the in argument of size sz. format specifies the format + type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage. - + \return SSL_SUCCESS upon success. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param in buffer containing certificate to load. \param sz size of the certificate located in buffer. - \param format format of the certificate to be loaded. + \param format format of the certificate to be loaded. Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + _Example_ \code int buffSz; @@ -7020,7 +7020,7 @@ WOLFSSL_API int wolfSSL_CTX_use_certificate_chain_buffer(WOLFSSL_CTX*, // failed to load certificate from buffer } \endcode - + \sa wolfSSL_CTX_load_verify_buffer \sa wolfSSL_CTX_use_certificate_buffer \sa wolfSSL_CTX_use_PrivateKey_buffer @@ -7035,28 +7035,28 @@ WOLFSSL_API int wolfSSL_use_certificate_buffer(WOLFSSL*, const unsigned char*, /*! \ingroup CertsKeys - \brief This function loads a private key buffer into the WOLFSSL object. - It behaves like the non-buffered version, only differing in its ability - to be called with a buffer as input instead of a file. The buffer is - provided by the in argument of size sz. format specifies the format - type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please + \brief This function loads a private key buffer into the WOLFSSL object. + It behaves like the non-buffered version, only differing in its ability + to be called with a buffer as input instead of a file. The buffer is + provided by the in argument of size sz. format specifies the format + type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the examples for proper usage. - + \return SSL_SUCCESS upon success. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - \return NO_PASSWORD will be returned if the key file is encrypted but no + \return NO_PASSWORD will be returned if the key file is encrypted but no password is provided. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param in buffer containing private key to load. \param sz size of the private key located in buffer. - \param format format of the private key to be loaded. Possible values are + \param format format of the private key to be loaded. Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + _Example_ \code int buffSz; @@ -7069,7 +7069,7 @@ WOLFSSL_API int wolfSSL_use_certificate_buffer(WOLFSSL*, const unsigned char*, // failed to load private key from buffer } \endcode - + \sa wolfSSL_use_PrivateKey \sa wolfSSL_CTX_load_verify_buffer \sa wolfSSL_CTX_use_certificate_buffer @@ -7085,26 +7085,26 @@ WOLFSSL_API int wolfSSL_use_PrivateKey_buffer(WOLFSSL*, const unsigned char*, /*! \ingroup CertsKeys - \brief This function loads a certificate chain buffer into the WOLFSSL - object. It behaves like the non-buffered version, only differing in its - ability to be called with a buffer as input instead of a file. The buffer - is provided by the in argument of size sz. The buffer must be in PEM format - and start with the subject’s certificate, ending with the root certificate. + \brief This function loads a certificate chain buffer into the WOLFSSL + object. It behaves like the non-buffered version, only differing in its + ability to be called with a buffer as input instead of a file. The buffer + is provided by the in argument of size sz. The buffer must be in PEM format + and start with the subject’s certificate, ending with the root certificate. Please see the examples for proper usage. - + \return SSL_SUCCES upon success. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - \return BUFFER_E will be returned if a chain buffer is bigger than + \return BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param in buffer containing certificate to load. \param sz size of the certificate located in buffer. - + _Example_ \code int buffSz; @@ -7117,7 +7117,7 @@ WOLFSSL_API int wolfSSL_use_PrivateKey_buffer(WOLFSSL*, const unsigned char*, // failed to load certificate chain from buffer } \endcode - + \sa wolfSSL_CTX_load_verify_buffer \sa wolfSSL_CTX_use_certificate_buffer \sa wolfSSL_CTX_use_PrivateKey_buffer @@ -7133,12 +7133,12 @@ WOLFSSL_API int wolfSSL_use_certificate_chain_buffer(WOLFSSL*, \ingroup CertsKeys \brief This function unloads any certificates or keys that SSL owns. - + \return SSL_SUCCESS - returned if the function executed successfully. \return BAD_FUNC_ARG - returned if the WOLFSSL object is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -7148,7 +7148,7 @@ WOLFSSL_API int wolfSSL_use_certificate_chain_buffer(WOLFSSL*, // Failure case. } \endcode - + \sa wolfSSL_CTX_UnloadCAs */ WOLFSSL_API int wolfSSL_UnloadCertsKeys(WOLFSSL*); @@ -7157,12 +7157,12 @@ WOLFSSL_API int wolfSSL_UnloadCertsKeys(WOLFSSL*); \ingroup Setup \brief This function turns on grouping of handshake messages where possible. - + \return SSL_SUCCESS will be returned upon success. \return BAD_FUNC_ARG will be returned if the input context is null. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). - + _Example_ \code WOLFSSL_CTX* ctx = 0; @@ -7172,7 +7172,7 @@ WOLFSSL_API int wolfSSL_UnloadCertsKeys(WOLFSSL*); // failed to set handshake message grouping } \endcode - + \sa wolfSSL_set_group_messages \sa wolfSSL_CTX_new */ @@ -7182,12 +7182,12 @@ WOLFSSL_API int wolfSSL_CTX_set_group_messages(WOLFSSL_CTX*); \ingroup Setup \brief This function turns on grouping of handshake messages where possible. - + \return SSL_SUCCESS will be returned upon success. \return BAD_FUNC_ARG will be returned if the input context is null. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl = 0; @@ -7197,7 +7197,7 @@ WOLFSSL_API int wolfSSL_CTX_set_group_messages(WOLFSSL_CTX*); // failed to set handshake message grouping } \endcode - + \sa wolfSSL_CTX_set_group_messages \sa wolfSSL_new */ @@ -7205,48 +7205,48 @@ WOLFSSL_API int wolfSSL_set_group_messages(WOLFSSL*); /*! \brief This function sets the fuzzer callback. - + \return none No returns. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param cbf a CallbackFuzzer type that is a function pointer of the form: - int (*CallbackFuzzer)(WOLFSSL* ssl, const unsigned char* buf, int sz, int + \param cbf a CallbackFuzzer type that is a function pointer of the form: + int (*CallbackFuzzer)(WOLFSSL* ssl, const unsigned char* buf, int sz, int type, void* fuzzCtx); - \param fCtx a void pointer type that will be set to the fuzzerCtx member of + \param fCtx a void pointer type that will be set to the fuzzerCtx member of the WOLFSSL structure. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); WOLFSSL* ssl = wolfSSL_new(ctx); void* fCtx; - int callbackFuzzerCB(WOLFSSL* ssl, const unsigned char* buf, int sz, + int callbackFuzzerCB(WOLFSSL* ssl, const unsigned char* buf, int sz, int type, void* fuzzCtx){ // function definition } … wolfSSL_SetFuzzerCb(ssl, callbackFuzzerCB, fCtx); \endcode - + \sa CallbackFuzzer */ WOLFSSL_API void wolfSSL_SetFuzzerCb(WOLFSSL* ssl, CallbackFuzzer cbf, void* fCtx); /*! \brief This function sets a new dtls cookie secret. - + \return 0 returned if the function executed without an error. - \return BAD_FUNC_ARG returned if there was an argument passed + \return BAD_FUNC_ARG returned if there was an argument passed to the function with an unacceptable value. \return COOKIE_SECRET_SZ returned if the secret size is 0. - \return MEMORY_ERROR returned if there was a problem allocating + \return MEMORY_ERROR returned if there was a problem allocating memory for a new cookie secret. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param secret a constant byte pointer representing the secret buffer. \param secretSz the size of the buffer. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -7260,7 +7260,7 @@ WOLFSSL_API void wolfSSL_SetFuzzerCb(WOLFSSL* ssl, CallbackFuzzer cbf, void* fCt // Success! Cookie secret is set. } \endcode - + \sa ForceZero \sa wc_RNG_GenerateBlock \sa XMEMCPY @@ -7272,21 +7272,21 @@ WOLFSSL_API int wolfSSL_DTLS_SetCookieSecret(WOLFSSL*, /*! \ingroup Setup - \brief This function sets the minimum downgrade version allowed. - Applicable only when the connection allows downgrade using + \brief This function sets the minimum downgrade version allowed. + Applicable only when the connection allows downgrade using (wolfSSLv23_client_method or wolfSSLv23_server_method). - - \return SSL_SUCCESS returned if the function returned without + + \return SSL_SUCCESS returned if the function returned without error and the minimum version is set. - \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure was + \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure was NULL or if the minimum version is not supported. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - \param version an integer representation of the version to be set as the - minimum: WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or + \param version an integer representation of the version to be set as the + minimum: WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or WOLFSSL_TLSV1_2 = 3. - + _Example_ \code WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method ); @@ -7297,7 +7297,7 @@ WOLFSSL_API int wolfSSL_DTLS_SetCookieSecret(WOLFSSL*, // Failed to set min version } \endcode - + \sa SetMinVersionHelper */ WOLFSSL_API int wolfSSL_CTX_SetMinVersion(WOLFSSL_CTX* ctx, int version); @@ -7305,94 +7305,94 @@ WOLFSSL_API int wolfSSL_CTX_SetMinVersion(WOLFSSL_CTX* ctx, int version); /*! \ingroup TLS - \brief This function sets the minimum downgrade version allowed. - Applicable only when the connection allows downgrade using + \brief This function sets the minimum downgrade version allowed. + Applicable only when the connection allows downgrade using (wolfSSLv23_client_method or wolfSSLv23_server_method). - - \return SSL_SUCCESS returned if this function and its subroutine executes + + \return SSL_SUCCESS returned if this function and its subroutine executes without error. - \return BAD_FUNC_ARG returned if the SSL object is NULL. In + \return BAD_FUNC_ARG returned if the SSL object is NULL. In the subroutine this error is thrown if there is not a good version match. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param version an integer representation of the version to be set as the - minimum: WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or + \param version an integer representation of the version to be set as the + minimum: WOLFSSL_SSLV3 = 0, WOLFSSL_TLSV1 = 1, WOLFSSL_TLSV1_1 = 2 or WOLFSSL_TLSV1_2 = 3. - + _Example_ \code WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(protocol method); WOLFSSL* ssl = WOLFSSL_new(ctx); - int version; macro representation + int version; macro representation … if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){ Failed to set min version } \endcode - + \sa SetMinVersionHelper */ WOLFSSL_API int wolfSSL_SetMinVersion(WOLFSSL* ssl, int version); /*! - \brief This function returns the size of the WOLFSSL object and will be - dependent on build options and settings. If SHOW_SIZES has been defined - when building wolfSSL, this function will also print the sizes of individual + \brief This function returns the size of the WOLFSSL object and will be + dependent on build options and settings. If SHOW_SIZES has been defined + when building wolfSSL, this function will also print the sizes of individual objects within the WOLFSSL object (Suites, Ciphers, etc.) to stdout. - + \return size This function returns the size of the WOLFSSL object. - + \param none No parameters. - + _Example_ \code int size = 0; size = wolfSSL_GetObjectSize(); printf(“sizeof(WOLFSSL) = %d\n”, size); \endcode - + \sa wolfSSL_new */ WOLFSSL_API int wolfSSL_GetObjectSize(void); /* object size based on build */ /*! - \brief Returns the record layer size of the plaintext input. This is helpful - when an application wants to know how many bytes will be sent across the - Transport layer, given a specified plaintext input size. This function + \brief Returns the record layer size of the plaintext input. This is helpful + when an application wants to know how many bytes will be sent across the + Transport layer, given a specified plaintext input size. This function must be called after the SSL/TLS handshake has been completed. - + \return size Upon success, the requested size will be returned - \return INPUT_SIZE_E will be returned if the input size is greater than the + \return INPUT_SIZE_E will be returned if the input size is greater than the maximum TLS fragment size (see wolfSSL_GetMaxOutputSize()) - \return BAD_FUNC_ARG will be returned upon invalid function argument, or if + \return BAD_FUNC_ARG will be returned upon invalid function argument, or if the SSL/TLS handshake has not been completed yet - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). \param inSz size of plaintext data. - + _Example_ \code none \endcode - + \sa wolfSSL_GetMaxOutputSize */ WOLFSSL_API int wolfSSL_GetOutputSize(WOLFSSL*, int); /*! - \brief Returns the maximum record layer size for plaintext data. This - will correspond to either the maximum SSL/TLS record size as specified - by the protocol standard, the maximum TLS fragment size as set by the - TLS Max Fragment Length extension. This function is helpful when the - application has called wolfSSL_GetOutputSize() and received a INPUT_SIZE_E - error. This function must be called after the SSL/TLS handshake has been + \brief Returns the maximum record layer size for plaintext data. This + will correspond to either the maximum SSL/TLS record size as specified + by the protocol standard, the maximum TLS fragment size as set by the + TLS Max Fragment Length extension. This function is helpful when the + application has called wolfSSL_GetOutputSize() and received a INPUT_SIZE_E + error. This function must be called after the SSL/TLS handshake has been completed. - + \return size Upon success, the maximum output size will be returned - \return BAD_FUNC_ARG will be returned upon invalid function argument, + \return BAD_FUNC_ARG will be returned upon invalid function argument, or if the SSL/TLS handshake has not been completed yet. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none @@ -7405,20 +7405,20 @@ WOLFSSL_API int wolfSSL_GetMaxOutputSize(WOLFSSL*); /*! \ingroup Setup - \brief This function sets the SSL/TLS protocol version for the specified - SSL session (WOLFSSL object) using the version as specified by version. - This will override the protocol setting for the SSL session (ssl) - - originally defined and set by the SSL context (wolfSSL_CTX_new()) + \brief This function sets the SSL/TLS protocol version for the specified + SSL session (WOLFSSL object) using the version as specified by version. + This will override the protocol setting for the SSL session (ssl) - + originally defined and set by the SSL context (wolfSSL_CTX_new()) method type. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG will be returned if the input SSL object is + \return BAD_FUNC_ARG will be returned if the input SSL object is NULL or an incorrect protocol version is given for version. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param version SSL/TLS protocol version. Possible values include + \param version SSL/TLS protocol version. Possible values include WOLFSSL_SSLV3, WOLFSSL_TLSV1, WOLFSSL_TLSV1_1, WOLFSSL_TLSV1_2. - + _Example_ \code int ret = 0; @@ -7430,98 +7430,98 @@ WOLFSSL_API int wolfSSL_GetMaxOutputSize(WOLFSSL*); // failed to set SSL session protocol version } \endcode - + \sa wolfSSL_CTX_new */ WOLFSSL_API int wolfSSL_SetVersion(WOLFSSL* ssl, int version); /*! - \brief Allows caller to set the Atomic User Record Processing - Mac/Encrypt Callback. The callback should return 0 for success - or < 0 for an error. The ssl and ctx pointers are available - for the user’s convenience. macOut is the output buffer where - the result of the mac should be stored. macIn is the mac input - buffer and macInSz notes the size of the buffer. macContent - and macVerify are needed for wolfSSL_SetTlsHmacInner() and be - passed along as is. encOut is the output buffer where the result - on the encryption should be stored. encIn is the input buffer to - encrypt while encSz is the size of the input. An example callback + \brief Allows caller to set the Atomic User Record Processing + Mac/Encrypt Callback. The callback should return 0 for success + or < 0 for an error. The ssl and ctx pointers are available + for the user’s convenience. macOut is the output buffer where + the result of the mac should be stored. macIn is the mac input + buffer and macInSz notes the size of the buffer. macContent + and macVerify are needed for wolfSSL_SetTlsHmacInner() and be + passed along as is. encOut is the output buffer where the result + on the encryption should be stored. encIn is the input buffer to + encrypt while encSz is the size of the input. An example callback can be found wolfssl/test.h myMacEncryptCb(). - + \return none No return. - + \param No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_SetMacEncryptCtx \sa wolfSSL_GetMacEncryptCtx */ WOLFSSL_API void wolfSSL_CTX_SetMacEncryptCb(WOLFSSL_CTX*, CallbackMacEncrypt); /*! - \brief Allows caller to set the Atomic User Record Processing Mac/Encrypt + \brief Allows caller to set the Atomic User Record Processing Mac/Encrypt Callback Context to ctx. - + \return none No return. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetMacEncryptCb \sa wolfSSL_GetMacEncryptCtx */ WOLFSSL_API void wolfSSL_SetMacEncryptCtx(WOLFSSL* ssl, void *ctx); /*! - \brief Allows caller to retrieve the Atomic User Record Processing - Mac/Encrypt Callback Context previously stored with + \brief Allows caller to retrieve the Atomic User Record Processing + Mac/Encrypt Callback Context previously stored with wolfSSL_SetMacEncryptCtx(). - - \return pointer If successful the call will return a valid pointer + + \return pointer If successful the call will return a valid pointer to the context. \return NULL will be returned for a blank context. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetMacEncryptCb \sa wolfSSL_SetMacEncryptCtx */ WOLFSSL_API void* wolfSSL_GetMacEncryptCtx(WOLFSSL* ssl); /*! - \brief Allows caller to set the Atomic User Record Processing - Decrypt/Verify Callback. The callback should return 0 for success - or < 0 for an error. The ssl and ctx pointers are available for - the user’s convenience. decOut is the output buffer where the result - of the decryption should be stored. decIn is the encrypted input - buffer and decInSz notes the size of the buffer. content and verify - are needed for wolfSSL_SetTlsHmacInner() and be passed along as is. - padSz is an output variable that should be set with the total value - of the padding. That is, the mac size plus any padding and pad bytes. + \brief Allows caller to set the Atomic User Record Processing + Decrypt/Verify Callback. The callback should return 0 for success + or < 0 for an error. The ssl and ctx pointers are available for + the user’s convenience. decOut is the output buffer where the result + of the decryption should be stored. decIn is the encrypted input + buffer and decInSz notes the size of the buffer. content and verify + are needed for wolfSSL_SetTlsHmacInner() and be passed along as is. + padSz is an output variable that should be set with the total value + of the padding. That is, the mac size plus any padding and pad bytes. An example callback can be found wolfssl/test.h myDecryptVerifyCb(). - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_SetMacEncryptCtx \sa wolfSSL_GetMacEncryptCtx */ @@ -7529,99 +7529,99 @@ WOLFSSL_API void wolfSSL_CTX_SetDecryptVerifyCb(WOLFSSL_CTX*, CallbackDecryptVerify); /*! - \brief Allows caller to set the Atomic User Record Processing + \brief Allows caller to set the Atomic User Record Processing Decrypt/Verify Callback Context to ctx. - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetDecryptVerifyCb \sa wolfSSL_GetDecryptVerifyCtx */ WOLFSSL_API void wolfSSL_SetDecryptVerifyCtx(WOLFSSL* ssl, void *ctx); /*! - \brief Allows caller to retrieve the Atomic User Record Processing - Decrypt/Verify Callback Context previously stored with + \brief Allows caller to retrieve the Atomic User Record Processing + Decrypt/Verify Callback Context previously stored with wolfSSL_SetDecryptVerifyCtx(). - - \return pointer If successful the call will return a valid pointer to the + + \return pointer If successful the call will return a valid pointer to the context. \return NULL will be returned for a blank context. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetDecryptVerifyCb \sa wolfSSL_SetDecryptVerifyCtx */ WOLFSSL_API void* wolfSSL_GetDecryptVerifyCtx(WOLFSSL* ssl); /*! - \brief Allows retrieval of the Hmac/Mac secret from the handshake process. - The verify parameter specifies whether this is for verification of a + \brief Allows retrieval of the Hmac/Mac secret from the handshake process. + The verify parameter specifies whether this is for verification of a peer message. - - \return pointer If successful the call will return a valid pointer to the + + \return pointer If successful the call will return a valid pointer to the secret. The size of the secret can be obtained from wolfSSL_GetHmacSize(). \return NULL will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). \param verify specifies whether this is for verification of a peer message. - + _Example_ \code none \endcode - + \sa wolfSSL_GetHmacSize */ WOLFSSL_API const unsigned char* wolfSSL_GetMacSecret(WOLFSSL*, int); /*! \brief Allows retrieval of the client write key from the handshake process. - - \return pointer If successful the call will return a valid pointer to the + + \return pointer If successful the call will return a valid pointer to the key. The size of the key can be obtained from wolfSSL_GetKeySize(). \return NULL will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetKeySize \sa wolfSSL_GetClientWriteIV */ WOLFSSL_API const unsigned char* wolfSSL_GetClientWriteKey(WOLFSSL*); /*! - \brief Allows retrieval of the client write IV (initialization vector) + \brief Allows retrieval of the client write IV (initialization vector) from the handshake process. - - \return pointer If successful the call will return a valid pointer to the + + \return pointer If successful the call will return a valid pointer to the IV. The size of the IV can be obtained from wolfSSL_GetCipherBlockSize(). \return NULL will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetCipherBlockSize() \sa wolfSSL_GetClientWriteKey() */ @@ -7629,33 +7629,33 @@ WOLFSSL_API const unsigned char* wolfSSL_GetClientWriteIV(WOLFSSL*); /*! \brief Allows retrieval of the server write key from the handshake process. - - \return pointer If successful the call will return a valid pointer to the + + \return pointer If successful the call will return a valid pointer to the key. The size of the key can be obtained from wolfSSL_GetKeySize(). \return NULL will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetKeySize \sa wolfSSL_GetServerWriteIV */ WOLFSSL_API const unsigned char* wolfSSL_GetServerWriteKey(WOLFSSL*); /*! - \brief Allows retrieval of the server write IV (initialization vector) + \brief Allows retrieval of the server write IV (initialization vector) from the handshake process. - - \return pointer If successful the call will return a valid pointer to the + + \return pointer If successful the call will return a valid pointer to the IV. The size of the IV can be obtained from wolfSSL_GetCipherBlockSize(). \return NULL will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + \sa wolfSSL_GetCipherBlockSize \sa wolfSSL_GetClientWriteKey */ @@ -7663,17 +7663,17 @@ WOLFSSL_API const unsigned char* wolfSSL_GetServerWriteIV(WOLFSSL*); /*! \brief Allows retrieval of the key size from the handshake process. - + \return size If successful the call will return the key size in bytes. \return BAD_FUNC_ARG will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetClientWriteKey \sa wolfSSL_GetServerWriteKey */ @@ -7682,14 +7682,14 @@ WOLFSSL_API int wolfSSL_GetKeySize(WOLFSSL*); /*! \ingroup CertsKeys - \brief Returns the iv_size member of the specs structure + \brief Returns the iv_size member of the specs structure held in the WOLFSSL struct. - + \return iv_size returns the value held in ssl->specs.iv_size. \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -7702,7 +7702,7 @@ WOLFSSL_API int wolfSSL_GetKeySize(WOLFSSL*); // ivSize holds the specs.iv_size value. } \endcode - + \sa wolfSSL_GetKeySize \sa wolfSSL_GetClientWriteIV \sa wolfSSL_GetServerWriteIV @@ -7711,184 +7711,184 @@ WOLFSSL_API int wolfSSL_GetIVSize(WOLFSSL*); /*! \brief Allows retrieval of the side of this WOLFSSL connection. - - \return success If successful the call will return either - WOLFSSL_SERVER_END or WOLFSSL_CLIENT_END depending on the + + \return success If successful the call will return either + WOLFSSL_SERVER_END or WOLFSSL_CLIENT_END depending on the side of WOLFSSL object. \return BAD_FUNC_ARG will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetClientWriteKey \sa wolfSSL_GetServerWriteKey */ WOLFSSL_API int wolfSSL_GetSide(WOLFSSL*); /*! - \brief Allows caller to determine if the negotiated protocol version + \brief Allows caller to determine if the negotiated protocol version is at least TLS version 1.1 or greater. - - \return true/false If successful the call will return 1 for true or + + \return true/false If successful the call will return 1 for true or 0 for false. \return BAD_FUNC_ARG will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetSide */ WOLFSSL_API int wolfSSL_IsTLSv1_1(WOLFSSL*); /*! - \brief Allows caller to determine the negotiated bulk cipher algorithm + \brief Allows caller to determine the negotiated bulk cipher algorithm from the handshake. - - \return If successful the call will return one of the following: - wolfssl_cipher_null, wolfssl_des, wolfssl_triple_des, wolfssl_aes, - wolfssl_aes_gcm, wolfssl_aes_ccm, wolfssl_camellia, wolfssl_hc128, + + \return If successful the call will return one of the following: + wolfssl_cipher_null, wolfssl_des, wolfssl_triple_des, wolfssl_aes, + wolfssl_aes_gcm, wolfssl_aes_ccm, wolfssl_camellia, wolfssl_hc128, wolfssl_rabbit. \return BAD_FUNC_ARG will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). _Example_ \code none \endcode - + \sa wolfSSL_GetCipherBlockSize \sa wolfSSL_GetKeySize */ WOLFSSL_API int wolfSSL_GetBulkCipher(WOLFSSL*); /*! - \brief Allows caller to determine the negotiated cipher block size from + \brief Allows caller to determine the negotiated cipher block size from the handshake. - - \return size If successful the call will return the size in bytes of the + + \return size If successful the call will return the size in bytes of the cipher block size. \return BAD_FUNC_ARG will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetBulkCipher \sa wolfSSL_GetKeySize */ WOLFSSL_API int wolfSSL_GetCipherBlockSize(WOLFSSL*); /*! - \brief Allows caller to determine the negotiated aead mac size from the + \brief Allows caller to determine the negotiated aead mac size from the handshake. For cipher type WOLFSSL_AEAD_TYPE. - - \return size If successful the call will return the size in bytes of the + + \return size If successful the call will return the size in bytes of the aead mac size. \return BAD_FUNC_ARG will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetBulkCipher \sa wolfSSL_GetKeySize */ WOLFSSL_API int wolfSSL_GetAeadMacSize(WOLFSSL*); /*! - \brief Allows caller to determine the negotiated (h)mac size from the + \brief Allows caller to determine the negotiated (h)mac size from the handshake. For cipher types except WOLFSSL_AEAD_TYPE. - - \return size If successful the call will return the size in bytes of + + \return size If successful the call will return the size in bytes of the (h)mac size. \return BAD_FUNC_ARG will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetBulkCipher \sa wolfSSL_GetHmacType */ WOLFSSL_API int wolfSSL_GetHmacSize(WOLFSSL*); /*! - \brief Allows caller to determine the negotiated (h)mac type from the + \brief Allows caller to determine the negotiated (h)mac type from the handshake. For cipher types except WOLFSSL_AEAD_TYPE. - - \return If successful the call will return one of the following: + + \return If successful the call will return one of the following: MD5, SHA, SHA256, SHA384. \return BAD_FUNC_ARG may be returned for an error state. \return SSL_FATAL_ERROR may also be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetBulkCipher \sa wolfSSL_GetHmacSize */ WOLFSSL_API int wolfSSL_GetHmacType(WOLFSSL*); /*! - \brief Allows caller to determine the negotiated cipher type + \brief Allows caller to determine the negotiated cipher type from the handshake. - - \return If successful the call will return one of the following: + + \return If successful the call will return one of the following: WOLFSSL_BLOCK_TYPE, WOLFSSL_STREAM_TYPE, WOLFSSL_AEAD_TYPE. \return BAD_FUNC_ARG will be returned for an error state. - + \param ssl a pointer to a WOLFSSL object, created using wolfSSL_new(). - + _Example_ \code none \endcode - + \sa wolfSSL_GetBulkCipher \sa wolfSSL_GetHmacType */ WOLFSSL_API int wolfSSL_GetCipherType(WOLFSSL*); /*! - \brief Allows caller to set the Hmac Inner vector for message - sending/receiving. The result is written to inner which should - be at least wolfSSL_GetHmacSize() bytes. The size of the message - is specified by sz, content is the type of message, and verify - specifies whether this is a verification of a peer message. Valid + \brief Allows caller to set the Hmac Inner vector for message + sending/receiving. The result is written to inner which should + be at least wolfSSL_GetHmacSize() bytes. The size of the message + is specified by sz, content is the type of message, and verify + specifies whether this is a verification of a peer message. Valid for cipher types excluding WOLFSSL_AEAD_TYPE. - + \return 1 upon success. \return BAD_FUNC_ARG will be returned for an error state. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_GetBulkCipher \sa wolfSSL_GetHmacType */ @@ -7896,395 +7896,395 @@ WOLFSSL_API int wolfSSL_SetTlsHmacInner(WOLFSSL*, unsigned char unsigned int, int, int); /*! - \brief Allows caller to set the Public Key Callback for ECC Signing. - The callback should return 0 for success or < 0 for an error. - The ssl and ctx pointers are available for the user’s convenience. - in is the input buffer to sign while inSz denotes the length of the input. - out is the output buffer where the result of the signature should be stored. - outSz is an input/output variable that specifies the size of the output - buffer upon invocation and the actual size of the signature should be stored - there before returning. keyDer is the ECC Private key in ASN1 format and - keySz is the length of the key in bytes. An example callback can be found + \brief Allows caller to set the Public Key Callback for ECC Signing. + The callback should return 0 for success or < 0 for an error. + The ssl and ctx pointers are available for the user’s convenience. + in is the input buffer to sign while inSz denotes the length of the input. + out is the output buffer where the result of the signature should be stored. + outSz is an input/output variable that specifies the size of the output + buffer upon invocation and the actual size of the signature should be stored + there before returning. keyDer is the ECC Private key in ASN1 format and + keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myEccSign(). - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_SetEccSignCtx \sa wolfSSL_GetEccSignCtx */ WOLFSSL_API void wolfSSL_CTX_SetEccSignCb(WOLFSSL_CTX*, CallbackEccSign); /*! - \brief Allows caller to set the Public Key Ecc Signing Callback + \brief Allows caller to set the Public Key Ecc Signing Callback Context to ctx. - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetEccSignCb \sa wolfSSL_GetEccSignCtx */ WOLFSSL_API void wolfSSL_SetEccSignCtx(WOLFSSL* ssl, void *ctx); /*! - \brief Allows caller to retrieve the Public Key Ecc Signing Callback + \brief Allows caller to retrieve the Public Key Ecc Signing Callback Context previously stored with wolfSSL_SetEccSignCtx(). - - \return pointer If successful the call will return a valid pointer + + \return pointer If successful the call will return a valid pointer to the context. \return NULL will be returned for a blank context. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetEccSignCb \sa wolfSSL_SetEccSignCtx */ WOLFSSL_API void* wolfSSL_GetEccSignCtx(WOLFSSL* ssl); /*! - \brief Allows caller to set the Public Key Callback for ECC Verification. - The callback should return 0 for success or < 0 for an error. - The ssl and ctx pointers are available for the user’s convenience. - sig is the signature to verify and sigSz denotes the length of the - signature. hash is an input buffer containing the digest of the message - and hashSz denotes the length in bytes of the hash. result is an output - variable where the result of the verification should be stored, 1 for - success and 0 for failure. keyDer is the ECC Private key in ASN1 - format and keySz is the length of the key in bytes. An example + \brief Allows caller to set the Public Key Callback for ECC Verification. + The callback should return 0 for success or < 0 for an error. + The ssl and ctx pointers are available for the user’s convenience. + sig is the signature to verify and sigSz denotes the length of the + signature. hash is an input buffer containing the digest of the message + and hashSz denotes the length in bytes of the hash. result is an output + variable where the result of the verification should be stored, 1 for + success and 0 for failure. keyDer is the ECC Private key in ASN1 + format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myEccVerify(). - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_SetEccVerifyCtx \sa wolfSSL_GetEccVerifyCtx */ WOLFSSL_API void wolfSSL_CTX_SetEccVerifyCb(WOLFSSL_CTX*, CallbackEccVerify); /*! - \brief Allows caller to set the Public Key Ecc Verification Callback + \brief Allows caller to set the Public Key Ecc Verification Callback Context to ctx. - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetEccVerifyCb \sa wolfSSL_GetEccVerifyCtx */ WOLFSSL_API void wolfSSL_SetEccVerifyCtx(WOLFSSL* ssl, void *ctx); /*! - \brief Allows caller to retrieve the Public Key Ecc Verification Callback + \brief Allows caller to retrieve the Public Key Ecc Verification Callback Context previously stored with wolfSSL_SetEccVerifyCtx(). - - \return pointer If successful the call will return a valid pointer to the + + \return pointer If successful the call will return a valid pointer to the context. \return NULL will be returned for a blank context. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetEccVerifyCb \sa wolfSSL_SetEccVerifyCtx */ WOLFSSL_API void* wolfSSL_GetEccVerifyCtx(WOLFSSL* ssl); /*! - \brief Allows caller to set the Public Key Callback for RSA Signing. - The callback should return 0 for success or < 0 for an error. - The ssl and ctx pointers are available for the user’s convenience. - in is the input buffer to sign while inSz denotes the length of the input. - out is the output buffer where the result of the signature should be stored. - outSz is an input/output variable that specifies the size of the output - buffer upon invocation and the actual size of the signature should be - stored there before returning. keyDer is the RSA Private key in ASN1 format - and keySz is the length of the key in bytes. An example callback can be + \brief Allows caller to set the Public Key Callback for RSA Signing. + The callback should return 0 for success or < 0 for an error. + The ssl and ctx pointers are available for the user’s convenience. + in is the input buffer to sign while inSz denotes the length of the input. + out is the output buffer where the result of the signature should be stored. + outSz is an input/output variable that specifies the size of the output + buffer upon invocation and the actual size of the signature should be + stored there before returning. keyDer is the RSA Private key in ASN1 format + and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaSign(). - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_SetRsaSignCtx \sa wolfSSL_GetRsaSignCtx */ WOLFSSL_API void wolfSSL_CTX_SetRsaSignCb(WOLFSSL_CTX*, CallbackRsaSign); /*! - \brief Allows caller to set the Public Key RSA Signing Callback Context + \brief Allows caller to set the Public Key RSA Signing Callback Context to ctx. - + \return none No Returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetRsaSignCb \sa wolfSSL_GetRsaSignCtx */ WOLFSSL_API void wolfSSL_SetRsaSignCtx(WOLFSSL* ssl, void *ctx); /*! - \brief Allows caller to retrieve the Public Key RSA Signing Callback + \brief Allows caller to retrieve the Public Key RSA Signing Callback Context previously stored with wolfSSL_SetRsaSignCtx(). - - \return pointer If successful the call will return a valid pointer to the + + \return pointer If successful the call will return a valid pointer to the context. \return NULL will be returned for a blank context. - + \param none No parameters. \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetRsaSignCb \sa wolfSSL_SetRsaSignCtx */ WOLFSSL_API void* wolfSSL_GetRsaSignCtx(WOLFSSL* ssl); /*! - \brief Allows caller to set the Public Key Callback for RSA Verification. - The callback should return the number of plaintext bytes for success or - < 0 for an error. The ssl and ctx pointers are available for the user’s - convenience. sig is the signature to verify and sigSz denotes the length - of the signature. out should be set to the beginning of the verification - buffer after the decryption process and any padding. keyDer is the RSA - Public key in ASN1 format and keySz is the length of the key in bytes. + \brief Allows caller to set the Public Key Callback for RSA Verification. + The callback should return the number of plaintext bytes for success or + < 0 for an error. The ssl and ctx pointers are available for the user’s + convenience. sig is the signature to verify and sigSz denotes the length + of the signature. out should be set to the beginning of the verification + buffer after the decryption process and any padding. keyDer is the RSA + Public key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaVerify(). - + \return none No returns. - + \param none No parameters. - + \sa wolfSSL_SetRsaVerifyCtx \sa wolfSSL_GetRsaVerifyCtx */ WOLFSSL_API void wolfSSL_CTX_SetRsaVerifyCb(WOLFSSL_CTX*, CallbackRsaVerify); /*! - \brief Allows caller to set the Public Key RSA Verification Callback + \brief Allows caller to set the Public Key RSA Verification Callback Context to ctx. - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetRsaVerifyCb \sa wolfSSL_GetRsaVerifyCtx */ WOLFSSL_API void wolfSSL_SetRsaVerifyCtx(WOLFSSL* ssl, void *ctx); /*! - \brief Allows caller to retrieve the Public Key RSA Verification Callback + \brief Allows caller to retrieve the Public Key RSA Verification Callback Context previously stored with wolfSSL_SetRsaVerifyCtx(). - - \return pointer If successful the call will return a valid pointer to + + \return pointer If successful the call will return a valid pointer to the context. \return NULL will be returned for a blank context. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetRsaVerifyCb \sa wolfSSL_SetRsaVerifyCtx */ WOLFSSL_API void* wolfSSL_GetRsaVerifyCtx(WOLFSSL* ssl); /*! - \brief Allows caller to set the Public Key Callback for RSA Public - Encrypt. The callback should return 0 for success or < 0 for an error. - The ssl and ctx pointers are available for the user’s convenience. - in is the input buffer to encrypt while inSz denotes the length of - the input. out is the output buffer where the result of the encryption - should be stored. outSz is an input/output variable that specifies - the size of the output buffer upon invocation and the actual size of - the encryption should be stored there before returning. keyDer is the - RSA Public key in ASN1 format and keySz is the length of the key in + \brief Allows caller to set the Public Key Callback for RSA Public + Encrypt. The callback should return 0 for success or < 0 for an error. + The ssl and ctx pointers are available for the user’s convenience. + in is the input buffer to encrypt while inSz denotes the length of + the input. out is the output buffer where the result of the encryption + should be stored. outSz is an input/output variable that specifies + the size of the output buffer upon invocation and the actual size of + the encryption should be stored there before returning. keyDer is the + RSA Public key in ASN1 format and keySz is the length of the key in bytes. An example callback can be found wolfssl/test.h myRsaEnc(). - + \return none No returns. - + \param none No parameters. - + _Examples_ \code none \endcode - + \sa wolfSSL_SetRsaEncCtx \sa wolfSSL_GetRsaEncCtx */ WOLFSSL_API void wolfSSL_CTX_SetRsaEncCb(WOLFSSL_CTX*, CallbackRsaEnc); /*! - \brief Allows caller to set the Public Key RSA Public Encrypt + \brief Allows caller to set the Public Key RSA Public Encrypt Callback Context to ctx. - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetRsaEncCb \sa wolfSSL_GetRsaEncCtx */ WOLFSSL_API void wolfSSL_SetRsaEncCtx(WOLFSSL* ssl, void *ctx); /*! - \brief Allows caller to retrieve the Public Key RSA Public Encrypt + \brief Allows caller to retrieve the Public Key RSA Public Encrypt Callback Context previously stored with wolfSSL_SetRsaEncCtx(). - - \return pointer If successful the call will return a valid pointer + + \return pointer If successful the call will return a valid pointer to the context. \return NULL will be returned for a blank context. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetRsaEncCb \sa wolfSSL_SetRsaEncCtx */ WOLFSSL_API void* wolfSSL_GetRsaEncCtx(WOLFSSL* ssl); /*! - \brief Allows caller to set the Public Key Callback for RSA Private - Decrypt. The callback should return the number of plaintext bytes - for success or < 0 for an error. The ssl and ctx pointers are available - for the user’s convenience. in is the input buffer to decrypt and inSz - denotes the length of the input. out should be set to the beginning - of the decryption buffer after the decryption process and any padding. - keyDer is the RSA Private key in ASN1 format and keySz is the length - of the key in bytes. An example callback can be found + \brief Allows caller to set the Public Key Callback for RSA Private + Decrypt. The callback should return the number of plaintext bytes + for success or < 0 for an error. The ssl and ctx pointers are available + for the user’s convenience. in is the input buffer to decrypt and inSz + denotes the length of the input. out should be set to the beginning + of the decryption buffer after the decryption process and any padding. + keyDer is the RSA Private key in ASN1 format and keySz is the length + of the key in bytes. An example callback can be found wolfssl/test.h myRsaDec(). - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_SetRsaDecCtx \sa wolfSSL_GetRsaDecCtx */ WOLFSSL_API void wolfSSL_CTX_SetRsaDecCb(WOLFSSL_CTX*, CallbackRsaDec); /*! - \brief Allows caller to set the Public Key RSA Private Decrypt + \brief Allows caller to set the Public Key RSA Private Decrypt Callback Context to ctx. - + \return none No returns. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetRsaDecCb \sa wolfSSL_GetRsaDecCtx */ WOLFSSL_API void wolfSSL_SetRsaDecCtx(WOLFSSL* ssl, void *ctx); /*! - \brief Allows caller to retrieve the Public Key RSA Private Decrypt + \brief Allows caller to retrieve the Public Key RSA Private Decrypt Callback Context previously stored with wolfSSL_SetRsaDecCtx(). - - \return pointer If successful the call will return a valid pointer + + \return pointer If successful the call will return a valid pointer to the context. \return NULL will be returned for a blank context. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_SetRsaDecCb \sa wolfSSL_SetRsaDecCtx */ WOLFSSL_API void* wolfSSL_GetRsaDecCtx(WOLFSSL* ssl); /*! - \brief This function registers a callback with the SSL context - (WOLFSSL_CTX) to be called when a new CA certificate is loaded - into wolfSSL. The callback is given a buffer with the DER-encoded + \brief This function registers a callback with the SSL context + (WOLFSSL_CTX) to be called when a new CA certificate is loaded + into wolfSSL. The callback is given a buffer with the DER-encoded certificate. - + \return none No return. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). - \param callback function to be registered as the CA callback for the - wolfSSL context, ctx. The signature of this function must follow that + \param callback function to be registered as the CA callback for the + wolfSSL context, ctx. The signature of this function must follow that as shown above in the Synopsis section. - + _Example_ \code WOLFSSL_CTX* ctx = 0; @@ -8295,112 +8295,112 @@ WOLFSSL_API void* wolfSSL_GetRsaDecCtx(WOLFSSL* ssl); // Register the custom CA callback with the SSL context wolfSSL_CTX_SetCACb(ctx, MyCACallback); - int MyCACallback(unsigned char* der, int sz, int type) + int MyCACallback(unsigned char* der, int sz, int type) { // custom CA callback function, DER-encoded cert - // located in “der” of size “sz” with type “type” + // located in “der” of size “sz” with type “type” } \endcode - + \sa wolfSSL_CTX_load_verify_locations */ WOLFSSL_API void wolfSSL_CTX_SetCACb(WOLFSSL_CTX*, CallbackCACache); /*! \ingroup CertManager - \brief Allocates and initializes a new Certificate Manager context. - This context may be used independent of SSL needs. It may be used to + \brief Allocates and initializes a new Certificate Manager context. + This context may be used independent of SSL needs. It may be used to load certificates, verify certificates, and check the revocation status. - - \return WOLFSSL_CERT_MANAGER If successful the call will return a valid + + \return WOLFSSL_CERT_MANAGER If successful the call will return a valid WOLFSSL_CERT_MANAGER pointer. \return NULL will be returned for an error state. - + \param none No parameters. - + \sa wolfSSL_CertManagerFree */ WOLFSSL_API WOLFSSL_CERT_MANAGER* wolfSSL_CertManagerNew_ex(void* heap); /*! \ingroup CertManager - \brief Allocates and initializes a new Certificate Manager context. - This context may be used independent of SSL needs. It may be used to + \brief Allocates and initializes a new Certificate Manager context. + This context may be used independent of SSL needs. It may be used to load certificates, verify certificates, and check the revocation status. - - \return WOLFSSL_CERT_MANAGER If successful the call will return a + + \return WOLFSSL_CERT_MANAGER If successful the call will return a valid WOLFSSL_CERT_MANAGER pointer. \return NULL will be returned for an error state. - + \param none No parameters. - + _Example_ \code #import - + WOLFSSL_CERT_MANAGER* cm; cm = wolfSSL_CertManagerNew(); if (cm == NULL) { // error creating new cert manager } \endcode - + \sa wolfSSL_CertManagerFree */ WOLFSSL_API WOLFSSL_CERT_MANAGER* wolfSSL_CertManagerNew(void); /*! \ingroup CertManager - \brief Frees all resources associated with the Certificate Manager + \brief Frees all resources associated with the Certificate Manager context. Call this when you no longer need to use the Certificate Manager. - + \return none - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). - + _Example_ \code #include - + WOLFSSL_CERT_MANAGER* cm; ... wolfSSL_CertManagerFree(cm); \endcode - + \sa wolfSSL_CertManagerNew */ WOLFSSL_API void wolfSSL_CertManagerFree(WOLFSSL_CERT_MANAGER*); /*! \ingroup CertManager - \brief Specifies the locations for CA certificate loading into the - manager context. The PEM certificate CAfile may contain several - trusted CA certificates. If CApath is not NULL it specifies a + \brief Specifies the locations for CA certificate loading into the + manager context. The PEM certificate CAfile may contain several + trusted CA certificates. If CApath is not NULL it specifies a directory containing CA certificates in PEM format. - + \return SSL_SUCCESS If successful the call will return. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - \return BAD_FUNC_ARG is the error that will be returned if a + \return BAD_FUNC_ARG is the error that will be returned if a pointer is not provided. \return SSL_FATAL_ERROR - will be returned upon failure. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). - \param file pointer to the name of the file containing CA + \param file pointer to the name of the file containing CA certificates to load. \param path pointer to the name of a directory path containing CA c - ertificates to load. The NULL pointer may be used if no + ertificates to load. The NULL pointer may be used if no certificate directory is desired. - + _Example_ \code #include - + int ret = 0; WOLFSSL_CERT_MANAGER* cm; ... @@ -8409,7 +8409,7 @@ WOLFSSL_API void wolfSSL_CertManagerFree(WOLFSSL_CERT_MANAGER*); // error loading CA certs into cert manager } \endcode - + \sa wolfSSL_CertManagerVerify */ WOLFSSL_API int wolfSSL_CertManagerLoadCA(WOLFSSL_CERT_MANAGER*, const char* f, @@ -8417,20 +8417,20 @@ WOLFSSL_API int wolfSSL_CertManagerLoadCA(WOLFSSL_CERT_MANAGER*, const char* f, /*! \ingroup CertManager - \brief Loads the CA Buffer by calling wolfSSL_CTX_load_verify_buffer and - returning that result using a temporary cm so as not to lose the information + \brief Loads the CA Buffer by calling wolfSSL_CTX_load_verify_buffer and + returning that result using a temporary cm so as not to lose the information in the cm passed into the function. - - \return SSL_FATAL_ERROR is returned if the WOLFSSL_CERT_MANAGER struct is + + \return SSL_FATAL_ERROR is returned if the WOLFSSL_CERT_MANAGER struct is NULL or if wolfSSL_CTX_new() returns NULL. \return SSL_SUCCESS is returned for a successful execution. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). \param in buffer for cert information. \param sz length of the buffer. \param format certificate format, either PEM or DER. - + _Example_ \code WOLFSSL_CERT_MANAGER* cm = (WOLFSSL_CERT_MANAGER*)vp; @@ -8443,7 +8443,7 @@ WOLFSSL_API int wolfSSL_CertManagerLoadCA(WOLFSSL_CERT_MANAGER*, const char* f, Error returned. Failure case code block. } \endcode - + \sa wolfSSL_CTX_load_verify_buffer \sa ProcessChainBuffer \sa ProcessBuffer @@ -8455,18 +8455,18 @@ WOLFSSL_API int wolfSSL_CertManagerLoadCABuffer(WOLFSSL_CERT_MANAGER*, /*! \ingroup CertManager \brief This function unloads the CA signer list. - - \return SSL_SUCCESS returned on successful execution of the function. + + \return SSL_SUCCESS returned on successful execution of the function. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL. \return BAD_MUTEX_E returned if there was a mutex error. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). - + _Example_ \code #include - + WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method); WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew(); ... @@ -8474,7 +8474,7 @@ WOLFSSL_API int wolfSSL_CertManagerLoadCABuffer(WOLFSSL_CERT_MANAGER*, Failure case. } \endcode - + \sa FreeSignerTable \sa UnlockMutex */ @@ -8482,21 +8482,21 @@ WOLFSSL_API int wolfSSL_CertManagerUnloadCAs(WOLFSSL_CERT_MANAGER* cm); /*! \ingroup CertManager - \brief The function will free the Trusted Peer linked list and unlocks + \brief The function will free the Trusted Peer linked list and unlocks the trusted peer list. - + \return SSL_SUCCESS if the function completed normally. \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER is NULL. - \return BAD_MUTEX_E mutex error if tpLock, a member of the + \return BAD_MUTEX_E mutex error if tpLock, a member of the WOLFSSL_CERT_MANAGER struct, is 0 (nill). - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). - + _Example_ \code #include - + WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(Protocol define); WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew(); ... @@ -8504,57 +8504,57 @@ WOLFSSL_API int wolfSSL_CertManagerUnloadCAs(WOLFSSL_CERT_MANAGER* cm); The function did not execute successfully. } \endcode - + \sa UnLockMutex */ WOLFSSL_API int wolfSSL_CertManagerUnload_trust_peers(WOLFSSL_CERT_MANAGER* cm); /*! \ingroup CertManager - \brief Specifies the certificate to verify with the Certificate Manager + \brief Specifies the certificate to verify with the Certificate Manager context. The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1. - + \return SSL_SUCCESS If successfull. - \return ASN_SIG_CONFIRM_E will be returned if the signature could not be + \return ASN_SIG_CONFIRM_E will be returned if the signature could not be verified. - \return ASN_SIG_OID_E will be returned if the signature type is not + \return ASN_SIG_OID_E will be returned if the signature type is not supported. - \return CRL_CERT_REVOKED is an error that is returned if this certificate + \return CRL_CERT_REVOKED is an error that is returned if this certificate has been revoked. - \return CRL_MISSING is an error that is returned if a current issuer CRL is + \return CRL_MISSING is an error that is returned if a current issuer CRL is not available. - \return ASN_BEFORE_DATE_E will be returned if the current date is before the + \return ASN_BEFORE_DATE_E will be returned if the current date is before the before date. - \return ASN_AFTER_DATE_E will be returned if the current date is after the + \return ASN_AFTER_DATE_E will be returned if the current date is after the after date. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - \return BAD_FUNC_ARG is the error that will be returned if a pointer is + \return BAD_FUNC_ARG is the error that will be returned if a pointer is not provided. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). - \param fname pointer to the name of the file containing the certificates + \param fname pointer to the name of the file containing the certificates to verify. - \param format format of the certificate to verify - either + \param format format of the certificate to verify - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + _Example_ \code int ret = 0; WOLFSSL_CERT_MANAGER* cm; ... - - ret = wolfSSL_CertManagerVerify(cm, “path/to/cert-file.pem”, + + ret = wolfSSL_CertManagerVerify(cm, “path/to/cert-file.pem”, SSL_FILETYPE_PEM); if (ret != SSL_SUCCESS) { error verifying certificate } \endcode - + \sa wolfSSL_CertManagerLoadCA \sa wolfSSL_CertManagerVerifyBuffer */ @@ -8563,41 +8563,41 @@ WOLFSSL_API int wolfSSL_CertManagerVerify(WOLFSSL_CERT_MANAGER*, const char* f, /*! \ingroup CertManager - \brief Specifies the certificate buffer to verify with the Certificate + \brief Specifies the certificate buffer to verify with the Certificate Manager context. The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1. - + \return SSL_SUCCESS If successful. - \return ASN_SIG_CONFIRM_E will be returned if the signature could not + \return ASN_SIG_CONFIRM_E will be returned if the signature could not be verified. - \return ASN_SIG_OID_E will be returned if the signature type is not + \return ASN_SIG_OID_E will be returned if the signature type is not supported. - \return CRL_CERT_REVOKED is an error that is returned if this certificate + \return CRL_CERT_REVOKED is an error that is returned if this certificate has been revoked. - \return CRL_MISSING is an error that is returned if a current issuer CRL + \return CRL_MISSING is an error that is returned if a current issuer CRL is not available. - \return ASN_BEFORE_DATE_E will be returned if the current date is before + \return ASN_BEFORE_DATE_E will be returned if the current date is before the before date. - \return ASN_AFTER_DATE_E will be returned if the current date is after + \return ASN_AFTER_DATE_E will be returned if the current date is after the after date. \return SSL_BAD_FILETYPE will be returned if the file is the wrong format. - \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t + \return SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted. \return MEMORY_E will be returned if an out of memory condition occurs. \return ASN_INPUT_E will be returned if Base16 decoding fails on the file. - \return BAD_FUNC_ARG is the error that will be returned if a pointer + \return BAD_FUNC_ARG is the error that will be returned if a pointer is not provided. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). \param buff buffer containing the certificates to verify. \param sz size of the buffer, buf. - \param format format of the certificate to verify, located in buf - either + \param format format of the certificate to verify, located in buf - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. - + _Example_ \code #include - + int ret = 0; int sz = 0; WOLFSSL_CERT_MANAGER* cm; @@ -8610,7 +8610,7 @@ WOLFSSL_API int wolfSSL_CertManagerVerify(WOLFSSL_CERT_MANAGER*, const char* f, } \endcode - + \sa wolfSSL_CertManagerLoadCA \sa wolfSSL_CertManagerVerify */ @@ -8618,18 +8618,18 @@ WOLFSSL_API int wolfSSL_CertManagerVerifyBuffer(WOLFSSL_CERT_MANAGER* cm, const unsigned char* buff, long sz, int format); /*! - \brief Check CRL if the option is enabled and compares the cert to the + \brief Check CRL if the option is enabled and compares the cert to the CRL list. - - \return SSL_SUCCESS returns if the function returned as expected. If + + \return SSL_SUCCESS returns if the function returned as expected. If the crlEnabled member of the WOLFSSL_CERT_MANAGER struct is turned on. \return MEMORY_E returns if the allocated memory failed. \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER is NULL. - + \param cm a pointer to a WOLFSSL_CERT_MANAGER struct. \param der pointer to a DER formatted certificate. \param sz size of the certificate. - + _Example_ \code WOLFSSL_CERT_MANAGER* cm; @@ -8640,7 +8640,7 @@ WOLFSSL_API int wolfSSL_CertManagerVerifyBuffer(WOLFSSL_CERT_MANAGER* cm, // Error returned. Deal with failure case. } \endcode - + \sa CheckCertCRL \sa ParseCertRelative \sa wolfSSL_CertManagerSetCRL_CB @@ -8651,29 +8651,29 @@ WOLFSSL_API int wolfSSL_CertManagerCheckCRL(WOLFSSL_CERT_MANAGER*, /*! \ingroup CertManager - \brief Turns on Certificate Revocation List checking when verifying - certificates with the Certificate Manager. By default, CRL checking - is off. options include WOLFSSL_CRL_CHECKALL which performs CRL - checking on each certificate in the chain versus the Leaf certificate + \brief Turns on Certificate Revocation List checking when verifying + certificates with the Certificate Manager. By default, CRL checking + is off. options include WOLFSSL_CRL_CHECKALL which performs CRL + checking on each certificate in the chain versus the Leaf certificate only which is the default. - + \return SSL_SUCCESS If successful the call will return. - \return NOT_COMPILED_IN will be returned if wolfSSL was not built with + \return NOT_COMPILED_IN will be returned if wolfSSL was not built with CRL enabled. \return MEMORY_E will be returned if an out of memory condition occurs. - \return BAD_FUNC_ARG is the error that will be returned if a pointer + \return BAD_FUNC_ARG is the error that will be returned if a pointer is not provided. - \return SSL_FAILURE will be returned if the CRL context cannot be + \return SSL_FAILURE will be returned if the CRL context cannot be initialized properly. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). \param options options to use when enabling the Certification Manager, cm. - + _Example_ \code #include - + int ret = 0; WOLFSSL_CERT_MANAGER* cm; ... @@ -8685,7 +8685,7 @@ WOLFSSL_API int wolfSSL_CertManagerCheckCRL(WOLFSSL_CERT_MANAGER*, ... \endcode - + \sa wolfSSL_CertManagerDisableCRL */ WOLFSSL_API int wolfSSL_CertManagerEnableCRL(WOLFSSL_CERT_MANAGER*, @@ -8693,23 +8693,23 @@ WOLFSSL_API int wolfSSL_CertManagerEnableCRL(WOLFSSL_CERT_MANAGER*, /*! \ingroup CertManager - \brief Turns off Certificate Revocation List checking when verifying - certificates with the Certificate Manager. By default, CRL checking is - off. You can use this function to temporarily or permanently disable CRL - checking with this Certificate Manager context that previously had CRL + \brief Turns off Certificate Revocation List checking when verifying + certificates with the Certificate Manager. By default, CRL checking is + off. You can use this function to temporarily or permanently disable CRL + checking with this Certificate Manager context that previously had CRL checking enabled. - + \return SSL_SUCCESS If successful the call will return. - \return BAD_FUNC_ARG is the error that will be returned if a function + \return BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). - + _Example_ \code #include - + int ret = 0; WOLFSSL_CERT_MANAGER* cm; ... @@ -8719,40 +8719,40 @@ WOLFSSL_API int wolfSSL_CertManagerEnableCRL(WOLFSSL_CERT_MANAGER*, } ... \endcode - + \sa wolfSSL_CertManagerEnableCRL */ WOLFSSL_API int wolfSSL_CertManagerDisableCRL(WOLFSSL_CERT_MANAGER*); /*! \ingroup CertManager - \brief Error checks and passes through to LoadCRL() in order to load the + \brief Error checks and passes through to LoadCRL() in order to load the cert into the CRL for revocation checking. - - \return SSL_SUCCESS if there is no error in wolfSSL_CertManagerLoadCRL and + + \return SSL_SUCCESS if there is no error in wolfSSL_CertManagerLoadCRL and if LoadCRL returns successfully. \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER struct is NULL. - \return SSL_FATAL_ERROR if wolfSSL_CertManagerEnableCRL returns anything + \return SSL_FATAL_ERROR if wolfSSL_CertManagerEnableCRL returns anything other than SSL_SUCCESS. \return BAD_PATH_ERROR if the path is NULL. \return MEMORY_E if LoadCRL fails to allocate heap memory. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). \param path a constant char pointer holding the CRL path. \param type type of certificate to be loaded. \param monitor requests monitoring in LoadCRL(). - + _Example_ \code #include - - int wolfSSL_LoadCRL(WOLFSSL* ssl, const char* path, int type, + + int wolfSSL_LoadCRL(WOLFSSL* ssl, const char* path, int type, int monitor); … wolfSSL_CertManagerLoadCRL(ssl->ctx->cm, path, type, monitor); \endcode - + \sa wolfSSL_CertManagerEnableCRL \sa wolfSSL_LoadCRL */ @@ -8762,23 +8762,23 @@ WOLFSSL_API int wolfSSL_CertManagerLoadCRL(WOLFSSL_CERT_MANAGER*, /*! \ingroup CertManager \brief The function loads the CRL file by calling BufferLoadCRL. - + \return SSL_SUCCESS returned if the function completed without errors. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL. - \return SSL_FATAL_ERROR returned if there is an error associated + \return SSL_FATAL_ERROR returned if there is an error associated with the WOLFSSL_CERT_MANAGER. - + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure. \param buff a constant byte type and is the buffer. \param sz a long int representing the size of the buffer. \param type a long integer that holds the certificate type. - + _Example_ \code #include - + WOLFSSL_CERT_MANAGER* cm; - const unsigned char* buff; + const unsigned char* buff; long sz; size of buffer int type; cert type ... @@ -8789,7 +8789,7 @@ WOLFSSL_API int wolfSSL_CertManagerLoadCRL(WOLFSSL_CERT_MANAGER*, Failure case. } \endcode - + \sa BufferLoadCRL \sa wolfSSL_CertManagerEnableCRL */ @@ -8798,24 +8798,24 @@ WOLFSSL_API int wolfSSL_CertManagerLoadCRLBuffer(WOLFSSL_CERT_MANAGER*, /*! \ingroup CertManager - \brief This function sets the CRL Certificate Manager callback. If - HAVE_CRL is defined and a matching CRL record is not found then the - cbMissingCRL is called (set via wolfSSL_CertManagerSetCRL_Cb). This + \brief This function sets the CRL Certificate Manager callback. If + HAVE_CRL is defined and a matching CRL record is not found then the + cbMissingCRL is called (set via wolfSSL_CertManagerSetCRL_Cb). This allows you to externally retrieve the CRL and load it. - - \return SSL_SUCCESS returned upon successful execution of the function and + + \return SSL_SUCCESS returned upon successful execution of the function and subroutines. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL. - - \param cm the WOLFSSL_CERT_MANAGER structure holding the information for + + \param cm the WOLFSSL_CERT_MANAGER structure holding the information for the certificate. - \param cb a function pointer to (*CbMissingCRL) that is set to the + \param cb a function pointer to (*CbMissingCRL) that is set to the cbMissingCRL member of the WOLFSSL_CERT_MANAGER. - + _Example_ \code #include - + WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method); WOLFSSL* ssl = wolfSSL_new(ctx); … @@ -8829,7 +8829,7 @@ WOLFSSL_API int wolfSSL_CertManagerLoadCRLBuffer(WOLFSSL_CERT_MANAGER*, return wolfSSL_CertManagerSetCRL_Cb(ssl->ctx->cm, cb); } \endcode - + \sa CbMissingCRL \sa wolfSSL_SetCRL_Cb */ @@ -8838,25 +8838,25 @@ WOLFSSL_API int wolfSSL_CertManagerSetCRL_Cb(WOLFSSL_CERT_MANAGER*, /*! \ingroup CertManager - \brief The function enables the WOLFSSL_CERT_MANAGER’s member, ocspEnabled + \brief The function enables the WOLFSSL_CERT_MANAGER’s member, ocspEnabled to signify that the OCSP check option is enabled. - - \return SSL_SUCCESS returned on successful execution of the function. The + + \return SSL_SUCCESS returned on successful execution of the function. The ocspEnabled member of the WOLFSSL_CERT_MANAGER is enabled. - \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is + \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is NULL or if an argument value that is not allowed is passed to a subroutine. - \return MEMORY_E returned if there is an error allocating memory within + \return MEMORY_E returned if there is an error allocating memory within this function or a subroutine. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). \param der a byte pointer to the certificate. \param sz an int type representing the size of the DER cert. - + _Example_ \code #import - + WOLFSSL* ssl = wolfSSL_new(ctx); byte* der; int sz; size of der @@ -8865,7 +8865,7 @@ WOLFSSL_API int wolfSSL_CertManagerSetCRL_Cb(WOLFSSL_CERT_MANAGER*, Failure case. } \endcode - + \sa ParseCertRelative \sa CheckCertOCSP */ @@ -8874,34 +8874,34 @@ WOLFSSL_API int wolfSSL_CertManagerCheckOCSP(WOLFSSL_CERT_MANAGER*, /*! \ingroup CertManager - \brief Turns on OCSP if it’s turned off and if compiled with the + \brief Turns on OCSP if it’s turned off and if compiled with the set option available. - + \return SSL_SUCCESS returned if the function call is successful. \return BAD_FUNC_ARG if cm struct is NULL. \return MEMORY_E if WOLFSSL_OCSP struct value is NULL. - \return SSL_FAILURE initialization of WOLFSSL_OCSP struct fails + \return SSL_FAILURE initialization of WOLFSSL_OCSP struct fails to initialize. \return NOT_COMPILED_IN build not compiled with correct feature enabled. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using wolfSSL_CertManagerNew(). \param options used to set values in WOLFSSL_CERT_MANAGER struct. - + _Example_ \code #include - + WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method); WOLFSSL* ssl = wolfSSL_new(ctx); WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew(); - int options; + int options; … if(wolfSSL_CertManagerEnableOCSP(ssl->ctx->cm, options) != SSL_SUCCESS){ Failure case. } \endcode - + \sa wolfSSL_CertManagerNew */ WOLFSSL_API int wolfSSL_CertManagerEnableOCSP(WOLFSSL_CERT_MANAGER*, @@ -8910,17 +8910,17 @@ WOLFSSL_API int wolfSSL_CertManagerEnableOCSP(WOLFSSL_CERT_MANAGER*, /*! \ingroup CertManager \brief Disables OCSP certificate revocation. - - \return SSL_SUCCESS wolfSSL_CertMangerDisableCRL successfully disabled the + + \return SSL_SUCCESS wolfSSL_CertMangerDisableCRL successfully disabled the crlEnabled member of the WOLFSSL_CERT_MANAGER structure. \return BAD_FUNC_ARG the WOLFSSL structure was NULL. - + \param ssl - a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code #include - + WOLFSSL_CTX* ctx = wolfSSL_CTX_new(method); WOLFSSL* ssl = wolfSSL_new(ctx); ... @@ -8928,23 +8928,23 @@ WOLFSSL_API int wolfSSL_CertManagerEnableOCSP(WOLFSSL_CERT_MANAGER*, Fail case. } \endcode - + \sa wolfSSL_DisableCRL */ WOLFSSL_API int wolfSSL_CertManagerDisableOCSP(WOLFSSL_CERT_MANAGER*); /*! \ingroup CertManager - \brief The function copies the url to the ocspOverrideURL member of the + \brief The function copies the url to the ocspOverrideURL member of the WOLFSSL_CERT_MANAGER structure. - + \return SSL_SUCCESS the function was able to execute as expected. \return BAD_FUNC_ARG the WOLFSSL_CERT_MANAGER struct is NULL. - \return MEMEORY_E Memory was not able to be allocated for the + \return MEMEORY_E Memory was not able to be allocated for the ocspOverrideURL member of the certificate manager. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code #include @@ -8957,7 +8957,7 @@ WOLFSSL_API int wolfSSL_CertManagerDisableOCSP(WOLFSSL_CERT_MANAGER*); Failure case. } \endcode - + \sa ocspOverrideURL \sa wolfSSL_SetOCSP_OverrideURL */ @@ -8967,27 +8967,27 @@ WOLFSSL_API int wolfSSL_CertManagerSetOCSPOverrideURL(WOLFSSL_CERT_MANAGER*, /*! \ingroup CertManager \brief The function sets the OCSP callback in the WOLFSSL_CERT_MANAGER. - - \return SSL_SUCCESS returned on successful execution. The arguments are + + \return SSL_SUCCESS returned on successful execution. The arguments are saved in the WOLFSSL_CERT_MANAGER structure. \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER is NULL. - + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure. \param ioCb a function pointer of type CbOCSPIO. \param respFreeCb - a function pointer of type CbOCSPRespFree. - \param ioCbCtx - a void pointer variable to the I/O callback user + \param ioCbCtx - a void pointer variable to the I/O callback user registered context. - + _Example_ \code #include - - wolfSSL_SetOCSP_Cb(WOLFSSL* ssl, CbOCSPIO ioCb, + + wolfSSL_SetOCSP_Cb(WOLFSSL* ssl, CbOCSPIO ioCb, CbOCSPRespFree respFreeCb, void* ioCbCtx){ … return wolfSSL_CertManagerSetOCSP_Cb(ssl->ctx->cm, ioCb, respFreeCb, ioCbCtx); \endcode - + \sa wolfSSL_CertManagerSetOCSPOverrideURL \sa wolfSSL_CertManagerCheckOCSP \sa wolfSSL_CertManagerEnableOCSPStapling @@ -9000,30 +9000,30 @@ WOLFSSL_API int wolfSSL_CertManagerSetOCSP_Cb(WOLFSSL_CERT_MANAGER*, /*! \ingroup CertManager - \brief This function turns on OCSP stapling if it is not turned on as well + \brief This function turns on OCSP stapling if it is not turned on as well as set the options. - - \return SSL_SUCCESS returned if there were no errors and the function + + \return SSL_SUCCESS returned if there were no errors and the function executed successfully. - \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is - NULL or otherwise if there was a unpermitted argument value passed to + \return BAD_FUNC_ARG returned if the WOLFSSL_CERT_MANAGER structure is + NULL or otherwise if there was a unpermitted argument value passed to a subroutine. \return MEMORY_E returned if there was an issue allocating memory. - \return SSL_FAILURE returned if the initialization of the OCSP + \return SSL_FAILURE returned if the initialization of the OCSP structure failed. - \return NOT_COMPILED_IN returned if wolfSSL was not compiled with + \return NOT_COMPILED_IN returned if wolfSSL was not compiled with HAVE_CERTIFICATE_STATUS_REQUEST option. - - \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, a member of the + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, a member of the WOLFSSL_CTX structure. - + _Example_ \code int wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX* ctx){ … return wolfSSL_CertManagerEnableOCSPStapling(ctx->cm); \endcode - + \sa wolfSSL_CTX_EnableOCSPStapling */ WOLFSSL_API int wolfSSL_CertManagerEnableOCSPStapling( @@ -9031,28 +9031,28 @@ WOLFSSL_API int wolfSSL_CertManagerEnableOCSPStapling( /*! \brief Enables CRL certificate revocation. - - \return SSL_SUCCESS the function and subroutines returned with no errors. + + \return SSL_SUCCESS the function and subroutines returned with no errors. \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL. \return MEMORY_E returned if the allocation of memory failed. - \return SSL_FAILURE returned if the InitCRL function does not return + \return SSL_FAILURE returned if the InitCRL function does not return successfully. \return NOT_COMPILED_IN HAVE_CRL was not enabled during the compiling. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param options an integer that is used to determine the setting of + \param options an integer that is used to determine the setting of crlCheckAll member of the WOLFSSL_CERT_MANAGER structure. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); … if (wolfSSL_EnableCRL(ssl, WOLFSSL_CRL_CHECKALL) != SSL_SUCCESS){ - // Failure case. SSL_SUCCESS was not returned by this function or + // Failure case. SSL_SUCCESS was not returned by this function or a subroutine } \endcode - + \sa wolfSSL_CertManagerEnableCRL \sa InitCRL */ @@ -9060,13 +9060,13 @@ WOLFSSL_API int wolfSSL_EnableCRL(WOLFSSL* ssl, int options); /*! \brief Disables CRL certificate revocation. - - \return SSL_SUCCESS wolfSSL_CertMangerDisableCRL successfully disabled + + \return SSL_SUCCESS wolfSSL_CertMangerDisableCRL successfully disabled the crlEnabled member of the WOLFSSL_CERT_MANAGER structure. \return BAD_FUNC_ARG the WOLFSSL structure was NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -9076,30 +9076,30 @@ WOLFSSL_API int wolfSSL_EnableCRL(WOLFSSL* ssl, int options); // Failure case } \endcode - + \sa wolfSSL_CertManagerDisableCRL \sa wolfSSL_CertManagerDisableOCSP */ WOLFSSL_API int wolfSSL_DisableCRL(WOLFSSL* ssl); /*! - \brief A wrapper function that ends up calling LoadCRL to load the + \brief A wrapper function that ends up calling LoadCRL to load the certificate for revocation checking. - - \return WOLFSSL_SUCCESS returned if the function and all of the + + \return WOLFSSL_SUCCESS returned if the function and all of the subroutines executed without error. - \return SSL_FATAL_ERROR returned if one of the subroutines does not + \return SSL_FATAL_ERROR returned if one of the subroutines does not return successfully. - \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER or the WOLFSSL + \return BAD_FUNC_ARG if the WOLFSSL_CERT_MANAGER or the WOLFSSL structure are NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param path a constant character pointer that holds the path to the + \param path a constant character pointer that holds the path to the crl file. \param type an integer representing the type of certificate. - \param monitor an integer variable used to verify the monitor path if + \param monitor an integer variable used to verify the monitor path if requested. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -9109,7 +9109,7 @@ WOLFSSL_API int wolfSSL_DisableCRL(WOLFSSL* ssl); // Failure case. Did not return SSL_SUCCESS. } \endcode - + \sa wolfSSL_CertManagerLoadCRL \sa wolfSSL_CertManagerEnableCRL \sa LoadCRL @@ -9118,15 +9118,15 @@ WOLFSSL_API int wolfSSL_LoadCRL(WOLFSSL*, const char*, int, int); /*! \brief Sets the CRL callback in the WOLFSSL_CERT_MANAGER structure. - - \return SSL_SUCCESS returned if the function or subroutine executes + + \return SSL_SUCCESS returned if the function or subroutine executes without error. The cbMissingCRL member of the WOLFSSL_CERT_MANAGER is set. - \return BAD_FUNC_ARG returned if the WOLFSSL or WOLFSSL_CERT_MANAGER + \return BAD_FUNC_ARG returned if the WOLFSSL or WOLFSSL_CERT_MANAGER structure is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param cb a function pointer to CbMissingCRL. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -9142,7 +9142,7 @@ WOLFSSL_API int wolfSSL_LoadCRL(WOLFSSL*, const char*, int, int); // The callback was not set properly } \endcode - + \sa CbMissingCRL \sa wolfSSL_CertManagerSetCRL_Cb */ @@ -9150,20 +9150,20 @@ WOLFSSL_API int wolfSSL_SetCRL_Cb(WOLFSSL*, CbMissingCRL); /*! \brief This function enables OCSP certificate verification. - - \return SSL_SUCCESS returned if the function and subroutines executes + + \return SSL_SUCCESS returned if the function and subroutines executes without errors. - \return BAD_FUNC_ARG returned if an argument in this function or any + \return BAD_FUNC_ARG returned if an argument in this function or any subroutine receives an invalid argument value. - \return MEMORY_E returned if there was an error allocating memory for + \return MEMORY_E returned if there was an error allocating memory for a structure or other variable. - \return NOT_COMPILED_IN returned if wolfSSL was not compiled with the + \return NOT_COMPILED_IN returned if wolfSSL was not compiled with the HAVE_OCSP option. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param options an integer type passed to wolfSSL_CertMangerENableOCSP() + \param options an integer type passed to wolfSSL_CertMangerENableOCSP() used for settings check. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -9175,21 +9175,21 @@ WOLFSSL_API int wolfSSL_SetCRL_Cb(WOLFSSL*, CbMissingCRL); // OCSP is not enabled } \endcode - + \sa wolfSSL_CertManagerEnableOCSP */ WOLFSSL_API int wolfSSL_EnableOCSP(WOLFSSL*, int options); /*! \brief Disables the OCSP certificate revocation option. - - \return SSL_SUCCESS returned if the function and its subroutine return with - no errors. The ocspEnabled member of the WOLFSSL_CERT_MANAGER structure was + + \return SSL_SUCCESS returned if the function and its subroutine return with + no errors. The ocspEnabled member of the WOLFSSL_CERT_MANAGER structure was successfully set. \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -9198,25 +9198,25 @@ WOLFSSL_API int wolfSSL_EnableOCSP(WOLFSSL*, int options); // Returned with an error. Failure case in this block. } \endcode - + \sa wolfSSL_CertManagerDisableOCSP */ WOLFSSL_API int wolfSSL_DisableOCSP(WOLFSSL*); /*! - \brief This function sets the ocspOverrideURL member in the + \brief This function sets the ocspOverrideURL member in the WOLFSSL_CERT_MANAGER structure. - + \return SSL_SUCCESS returned on successful execution of the function. - \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if a + \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL or if a unpermitted argument was passed to a subroutine. - \return MEMORY_E returned if there was an error allocating memory in the + \return MEMORY_E returned if there was an error allocating memory in the subroutine. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param url a constant char pointer to the url that will be stored in the + \param url a constant char pointer to the url that will be stored in the ocspOverrideURL member of the WOLFSSL_CERT_MANAGER structure. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -9227,32 +9227,32 @@ WOLFSSL_API int wolfSSL_DisableOCSP(WOLFSSL*); // The override url is set to the new value } \endcode - + \sa wolfSSL_CertManagerSetOCSPOverrideURL */ WOLFSSL_API int wolfSSL_SetOCSP_OverrideURL(WOLFSSL*, const char*); /*! - \brief This function sets the OCSP callback in the + \brief This function sets the OCSP callback in the WOLFSSL_CERT_MANAGER structure. - - \return SSL_SUCCESS returned if the function executes without error. + + \return SSL_SUCCESS returned if the function executes without error. The ocspIOCb, ocspRespFreeCb, and ocspIOCtx memebers of the CM are set. - \return BAD_FUNC_ARG returned if the WOLFSSL or WOLFSSL_CERT_MANAGER + \return BAD_FUNC_ARG returned if the WOLFSSL or WOLFSSL_CERT_MANAGER structures are NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ioCb a function pointer to type CbOCSPIO. - \param respFreeCb a function pointer to type CbOCSPRespFree which is the + \param respFreeCb a function pointer to type CbOCSPRespFree which is the call to free the response memory. - \param ioCbCtx a void pointer that will be held in the ocspIOCtx member + \param ioCbCtx a void pointer that will be held in the ocspIOCtx member of the CM. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); … - int OCSPIO_CB(void* , const char*, int , unsigned char* , int, + int OCSPIO_CB(void* , const char*, int , unsigned char* , int, unsigned char**){ // must have this signature // Function Body } @@ -9261,15 +9261,15 @@ WOLFSSL_API int wolfSSL_SetOCSP_OverrideURL(WOLFSSL*, const char*); // function body } … - void* ioCbCtx; + void* ioCbCtx; CbOCSPRespFree CB_OCSPRespFree; - if(wolfSSL_SetOCSP_Cb(ssl, OCSPIO_CB( pass args ), CB_OCSPRespFree, + if(wolfSSL_SetOCSP_Cb(ssl, OCSPIO_CB( pass args ), CB_OCSPRespFree, ioCbCtx) != SSL_SUCCESS){ // Callback not set } \endcode - + \sa wolfSSL_CertManagerSetOCSP_Cb \sa CbOCSPIO \sa CbOCSPRespFree @@ -9278,19 +9278,19 @@ WOLFSSL_API int wolfSSL_SetOCSP_Cb(WOLFSSL*, CbOCSPIO, CbOCSPRespFree, void*); /*! \brief Enables CRL certificate verification through the CTX. - - \return SSL_SUCCESS returned if this function and it’s subroutines - execute without errors. - \return BAD_FUNC_ARG returned if the CTX struct is NULL or there + + \return SSL_SUCCESS returned if this function and it’s subroutines + execute without errors. + \return BAD_FUNC_ARG returned if the CTX struct is NULL or there was otherwise an invalid argument passed in a subroutine. - \return MEMORY_E returned if there was an error allocating + \return MEMORY_E returned if there was an error allocating memory during execution of the function. - \return SSL_FAILURE returned if the crl member of the + \return SSL_FAILURE returned if the crl member of the WOLFSSL_CERT_MANAGER fails to initialize correctly. \return NOT_COMPILED_IN wolfSSL was not compiled with the HAVE_CRL option. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -9300,7 +9300,7 @@ WOLFSSL_API int wolfSSL_SetOCSP_Cb(WOLFSSL*, CbOCSPIO, CbOCSPRespFree, void*); // The function failed } \endcode - + \sa wolfSSL_CertManagerEnableCRL \sa InitCRL \sa wolfSSL_CTX_DisableCRL @@ -9309,15 +9309,15 @@ WOLFSSL_API int wolfSSL_CTX_EnableCRL(WOLFSSL_CTX* ctx, int options); /*! \brief This function disables CRL verification in the CTX structure. - - \return SSL_SUCCESS returned if the function executes without error. + + \return SSL_SUCCESS returned if the function executes without error. The crlEnabled member of the WOLFSSL_CERT_MANAGER struct is set to 0. - \return BAD_FUNC_ARG returned if either the CTX struct or the CM + \return BAD_FUNC_ARG returned if either the CTX struct or the CM struct has a NULL value. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -9327,29 +9327,29 @@ WOLFSSL_API int wolfSSL_CTX_EnableCRL(WOLFSSL_CTX* ctx, int options); // Failure case. } \endcode - + \sa wolfSSL_CertManagerDisableCRL */ WOLFSSL_API int wolfSSL_CTX_DisableCRL(WOLFSSL_CTX* ctx); /*! - \brief This function loads CRL into the WOLFSSL_CTX structure through + \brief This function loads CRL into the WOLFSSL_CTX structure through wolfSSL_CertManagerLoadCRL(). - - \return SSL_SUCCESS - returned if the function and its subroutines + + \return SSL_SUCCESS - returned if the function and its subroutines execute without error. - \return BAD_FUNC_ARG - returned if this function or any subroutines + \return BAD_FUNC_ARG - returned if this function or any subroutines are passed NULL structures. \return BAD_PATH_ERROR - returned if the path variable opens as NULL. \return MEMORY_E - returned if an allocation of memory failed. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). \param path the path to the certificate. \param type an integer variable holding the type of certificate. - \param monitor an integer variable used to determine if the monitor + \param monitor an integer variable used to determine if the monitor path is requested. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -9357,26 +9357,26 @@ WOLFSSL_API int wolfSSL_CTX_DisableCRL(WOLFSSL_CTX* ctx); … return wolfSSL_CTX_LoadCRL(ctx, path, SSL_FILETYPE_PEM, 0); \endcode - + \sa wolfSSL_CertManagerLoadCRL \sa LoadCRL */ WOLFSSL_API int wolfSSL_CTX_LoadCRL(WOLFSSL_CTX*, const char*, int, int); /*! - \brief This function will set the callback argument to the cbMissingCRL - member of the WOLFSSL_CERT_MANAGER structure by calling + \brief This function will set the callback argument to the cbMissingCRL + member of the WOLFSSL_CERT_MANAGER structure by calling wolfSSL_CertManagerSetCRL_Cb. - - \return SSL_SUCCESS returned for a successful execution. The - WOLFSSL_CERT_MANAGER structure’s member cbMssingCRL was successfully + + \return SSL_SUCCESS returned for a successful execution. The + WOLFSSL_CERT_MANAGER structure’s member cbMssingCRL was successfully set to cb. - \return BAD_FUNC_ARG returned if WOLFSSL_CTX or WOLFSSL_CERT_MANAGER + \return BAD_FUNC_ARG returned if WOLFSSL_CTX or WOLFSSL_CERT_MANAGER are NULL. - - \param ctx a pointer to a WOLFSSL_CTX structure, created with + + \param ctx a pointer to a WOLFSSL_CTX structure, created with wolfSSL_CTX_new(). - \param cb a pointer to a callback function of type CbMissingCRL. + \param cb a pointer to a callback function of type CbMissingCRL. Signature requirement: void (*CbMissingCRL)(const char* url); @@ -9393,27 +9393,27 @@ WOLFSSL_API int wolfSSL_CTX_LoadCRL(WOLFSSL_CTX*, const char*, int, int); // Failure case, cb was not set correctly. } \endcode - + \sa wolfSSL_CertManagerSetCRL_Cb \sa CbMissingCRL */ WOLFSSL_API int wolfSSL_CTX_SetCRL_Cb(WOLFSSL_CTX*, CbMissingCRL); /*! - \brief This function sets options to configure behavior of OCSP - functionality in wolfSSL. The value of options if formed by or’ing - one or more of the following options: - WOLFSSL_OCSP_ENABLE - enable OCSP lookups WOLFSSL_OCSP_URL_OVERRIDE - - use the override URL instead of the URL in certificates. The override URL - is specified using the wolfSSL_CTX_SetOCSP_OverrideURL() function. This - function only sets the OCSP options when wolfSSL has been compiled with + \brief This function sets options to configure behavior of OCSP + functionality in wolfSSL. The value of options if formed by or’ing + one or more of the following options: + WOLFSSL_OCSP_ENABLE - enable OCSP lookups WOLFSSL_OCSP_URL_OVERRIDE - + use the override URL instead of the URL in certificates. The override URL + is specified using the wolfSSL_CTX_SetOCSP_OverrideURL() function. This + function only sets the OCSP options when wolfSSL has been compiled with OCSP support (--enable-ocsp, #define HAVE_OCSP). - + \return SSL_SUCCESS is returned upon success. \return SSL_FAILURE is returned upon failure. - \return NOT_COMPILED_IN is returned when this function has been called, + \return NOT_COMPILED_IN is returned when this function has been called, but OCSP support was not enabled when wolfSSL was compiled. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param options value used to set the OCSP options. @@ -9423,22 +9423,22 @@ WOLFSSL_API int wolfSSL_CTX_SetCRL_Cb(WOLFSSL_CTX*, CbMissingCRL); ... wolfSSL_CTX_OCSP_set_options(ctx, WOLFSSL_OCSP_ENABLE); \endcode - + \sa wolfSSL_CTX_OCSP_set_override_url */ WOLFSSL_API int wolfSSL_CTX_EnableOCSP(WOLFSSL_CTX*, int options); /*! - \brief This function disables OCSP certificate revocation checking by + \brief This function disables OCSP certificate revocation checking by affecting the ocspEnabled member of the WOLFSSL_CERT_MANAGER structure. - - \return SSL_SUCCESS returned if the function executes without error. + + \return SSL_SUCCESS returned if the function executes without error. The ocspEnabled member of the CM has been disabled. \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -9448,67 +9448,67 @@ WOLFSSL_API int wolfSSL_CTX_EnableOCSP(WOLFSSL_CTX*, int options); // OCSP is not disabled } \endcode - + \sa wolfSSL_DisableOCSP \sa wolfSSL_CertManagerDisableOCSP */ WOLFSSL_API int wolfSSL_CTX_DisableOCSP(WOLFSSL_CTX*); /*! - \brief This function manually sets the URL for OCSP to use. By default, - OCSP will use the URL found in the individual certificate unless the + \brief This function manually sets the URL for OCSP to use. By default, + OCSP will use the URL found in the individual certificate unless the WOLFSSL_OCSP_URL_OVERRIDE option is set using the wolfSSL_CTX_EnableOCSP. - + \return SSL_SUCCESS is returned upon success. \return SSL_FAILURE is returned upon failure. - \return NOT_COMPILED_IN is returned when this function has been called, + \return NOT_COMPILED_IN is returned when this function has been called, but OCSP support was not enabled when wolfSSL was compiled. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param url pointer to the OCSP URL for wolfSSL to use. - + _Example_ \code WOLFSSL_CTX* ctx = 0; ... wolfSSL_CTX_OCSP_set_override_url(ctx, “custom-url-here”); \endcode - + \sa wolfSSL_CTX_OCSP_set_options */ WOLFSSL_API int wolfSSL_CTX_SetOCSP_OverrideURL(WOLFSSL_CTX*, const char*); /*! \brief Sets the callback for the OCSP in the WOLFSSL_CTX structure. - - \return SSL_SUCCESS returned if the function executed successfully. The - ocspIOCb, ocspRespFreeCb, and ocspIOCtx members in the CM were + + \return SSL_SUCCESS returned if the function executed successfully. The + ocspIOCb, ocspRespFreeCb, and ocspIOCtx members in the CM were successfully set. - \return BAD_FUNC_ARG returned if the WOLFSSL_CTX or + \return BAD_FUNC_ARG returned if the WOLFSSL_CTX or WOLFSSL_CERT_MANAGER structure is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ioCb a CbOCSPIO type that is a function pointer. \param respFreeCb a CbOCSPRespFree type that is a function pointer. \param ioCbCtx a void pointer that will be held in the WOLFSSL_CERT_MANAGER. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); … - CbOCSPIO ocspIOCb; + CbOCSPIO ocspIOCb; CbOCSPRespFree ocspRespFreeCb; … void* ioCbCtx; - int isSetOCSP = wolfSSL_CTX_SetOCSP_Cb(ctx, ocspIOCb, + int isSetOCSP = wolfSSL_CTX_SetOCSP_Cb(ctx, ocspIOCb, ocspRespFreeCb, ioCbCtx); if(isSetOCSP != SSL_SUCCESS){ // The function did not return successfully. } \endcode - + \sa wolfSSL_CertManagerSetOCSP_Cb \sa CbOCSPIO \sa CbOCSPRespFree @@ -9517,22 +9517,22 @@ WOLFSSL_API int wolfSSL_CTX_SetOCSP_Cb(WOLFSSL_CTX*, CbOCSPIO, CbOCSPRespFree, void*); /*! - \brief This function enables OCSP stapling by calling + \brief This function enables OCSP stapling by calling wolfSSL_CertManagerEnableOCSPStapling(). - - \return SSL_SUCCESS returned if there were no errors and the function + + \return SSL_SUCCESS returned if there were no errors and the function executed successfully. - \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or + \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or otherwise if there was a unpermitted argument value passed to a subroutine. \return MEMORY_E returned if there was an issue allocating memory. - \return SSL_FAILURE returned if the initialization of the OCSP + \return SSL_FAILURE returned if the initialization of the OCSP structure failed. - \return NOT_COMPILED_IN returned if wolfSSL was not compiled with + \return NOT_COMPILED_IN returned if wolfSSL was not compiled with HAVE_CERTIFICATE_STATUS_REQUEST option. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - + _Example_ \code WOLFSSL* ssl = WOLFSSL_new(); @@ -9542,7 +9542,7 @@ WOLFSSL_API int wolfSSL_CTX_SetOCSP_Cb(WOLFSSL_CTX*, // OCSP stapling is not enabled } \endcode - + \sa wolfSSL_CertManagerEnableOCSPStapling \sa InitOCSP */ @@ -9551,25 +9551,25 @@ WOLFSSL_API int wolfSSL_CTX_EnableOCSPStapling(WOLFSSL_CTX*); /*! \ingroup CertsKeys - \brief Normally, at the end of the SSL handshake, wolfSSL frees - temporary arrays. Calling this function before the handshake begins - will prevent wolfSSL from freeing temporary arrays. Temporary arrays - may be needed for things such as wolfSSL_get_keys() or PSK hints. - When the user is done with temporary arrays, either wolfSSL_FreeArrays() - may be called to free the resources immediately, or alternatively the + \brief Normally, at the end of the SSL handshake, wolfSSL frees + temporary arrays. Calling this function before the handshake begins + will prevent wolfSSL from freeing temporary arrays. Temporary arrays + may be needed for things such as wolfSSL_get_keys() or PSK hints. + When the user is done with temporary arrays, either wolfSSL_FreeArrays() + may be called to free the resources immediately, or alternatively the resources will be freed when the associated SSL object is freed. - + \return none No return. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl; ... wolfSSL_KeepArrays(ssl); \endcode - + \sa wolfSSL_FreeArrays */ WOLFSSL_API void wolfSSL_KeepArrays(WOLFSSL*); @@ -9577,46 +9577,46 @@ WOLFSSL_API void wolfSSL_KeepArrays(WOLFSSL*); /*! \ingroup CertsKeys - \brief Normally, at the end of the SSL handshake, wolfSSL frees temporary - arrays. If wolfSSL_KeepArrays() has been called before the handshake, - wolfSSL will not free temporary arrays. This function explicitly frees - temporary arrays and should be called when the user is done with temporary - arrays and does not want to wait for the SSL object to be freed to free + \brief Normally, at the end of the SSL handshake, wolfSSL frees temporary + arrays. If wolfSSL_KeepArrays() has been called before the handshake, + wolfSSL will not free temporary arrays. This function explicitly frees + temporary arrays and should be called when the user is done with temporary + arrays and does not want to wait for the SSL object to be freed to free these resources. - + \return none No return. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl; ... wolfSSL_FreeArrays(ssl); \endcode - + \sa wolfSSL_KeepArrays */ WOLFSSL_API void wolfSSL_FreeArrays(WOLFSSL*); /*! - \brief This function enables the use of Server Name Indication in the SSL - object passed in the 'ssl' parameter. It means that the SNI extension will - be sent on ClientHello by wolfSSL client and wolfSSL server will respond - ClientHello + SNI with either ServerHello + blank SNI or alert fatal in + \brief This function enables the use of Server Name Indication in the SSL + object passed in the 'ssl' parameter. It means that the SNI extension will + be sent on ClientHello by wolfSSL client and wolfSSL server will respond + ClientHello + SNI with either ServerHello + blank SNI or alert fatal in case of SNI mismatch. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG is the error that will be returned in one of these + \return BAD_FUNC_ARG is the error that will be returned in one of these cases: ssl is NULL, data is NULL, type is a unknown value. (see below) \return MEMORY_E is the error returned when there is not enough memory. - + \param ssl pointer to a SSL object, created with wolfSSL_new(). - \param type indicates which type of server name is been passed in data. + \param type indicates which type of server name is been passed in data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 }; \param data pointer to the server name data. \param size size of the server name data. - + _Example_ \code int ret = 0; @@ -9630,13 +9630,13 @@ WOLFSSL_API void wolfSSL_FreeArrays(WOLFSSL*); if (ssl == NULL) { // ssl creation failed } - ret = wolfSSL_UseSNI(ssl, WOLFSSL_SNI_HOST_NAME, "www.yassl.com", + ret = wolfSSL_UseSNI(ssl, WOLFSSL_SNI_HOST_NAME, "www.yassl.com", strlen("www.yassl.com")); if (ret != 0) { // sni usage failed } \endcode - + \sa wolfSSL_new \sa wolfSSL_CTX_UseSNI */ @@ -9644,23 +9644,23 @@ WOLFSSL_API int wolfSSL_UseSNI(WOLFSSL* ssl, unsigned char type, const void* data, unsigned short size); /*! - \brief This function enables the use of Server Name Indication for SSL - objects created from the SSL context passed in the 'ctx' parameter. It - means that the SNI extension will be sent on ClientHello by wolfSSL - clients and wolfSSL servers will respond ClientHello + SNI with either + \brief This function enables the use of Server Name Indication for SSL + objects created from the SSL context passed in the 'ctx' parameter. It + means that the SNI extension will be sent on ClientHello by wolfSSL + clients and wolfSSL servers will respond ClientHello + SNI with either ServerHello + blank SNI or alert fatal in case of SNI mismatch. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG is the error that will be returned in one of these + \return BAD_FUNC_ARG is the error that will be returned in one of these cases: ctx is NULL, data is NULL, type is a unknown value. (see below) \return MEMORY_E is the error returned when there is not enough memory. - + \param ctx pointer to a SSL context, created with wolfSSL_CTX_new(). - \param type indicates which type of server name is been passed in data. + \param type indicates which type of server name is been passed in data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 }; \param data pointer to the server name data. \param size size of the server name data. - + _Example_ \code int ret = 0; @@ -9669,13 +9669,13 @@ WOLFSSL_API int wolfSSL_UseSNI(WOLFSSL* ssl, unsigned char type, if (ctx == NULL) { // context creation failed } - ret = wolfSSL_CTX_UseSNI(ctx, WOLFSSL_SNI_HOST_NAME, "www.yassl.com", + ret = wolfSSL_CTX_UseSNI(ctx, WOLFSSL_SNI_HOST_NAME, "www.yassl.com", strlen("www.yassl.com")); if (ret != 0) { // sni usage failed } \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_UseSNI */ @@ -9683,26 +9683,26 @@ WOLFSSL_API int wolfSSL_CTX_UseSNI(WOLFSSL_CTX* ctx, unsigned char type, const void* data, unsigned short size); /*! - \brief This function is called on the server side to configure the - behavior of the SSL session using Server Name Indication in the SSL + \brief This function is called on the server side to configure the + behavior of the SSL session using Server Name Indication in the SSL object passed in the 'ssl' parameter. The options are explained below. - + \return none No returns. - + \param ssl pointer to a SSL object, created with wolfSSL_new(). - \param type indicates which type of server name is been passed in data. + \param type indicates which type of server name is been passed in data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 }; - \param options a bitwise semaphore with the chosen options. The available - options are: enum { WOLFSSL_SNI_CONTINUE_ON_MISMATCH = 0x01, - WOLFSSL_SNI_ANSWER_ON_MISMATCH = 0x02 }; Normally the server will abort the - handshake by sending a fatal-level unrecognized_name(112) alert if the + \param options a bitwise semaphore with the chosen options. The available + options are: enum { WOLFSSL_SNI_CONTINUE_ON_MISMATCH = 0x01, + WOLFSSL_SNI_ANSWER_ON_MISMATCH = 0x02 }; Normally the server will abort the + handshake by sending a fatal-level unrecognized_name(112) alert if the hostname provided by the client mismatch with the servers. - \param WOLFSSL_SNI_CONTINUE_ON_MISMATCH With this option set, the server + \param WOLFSSL_SNI_CONTINUE_ON_MISMATCH With this option set, the server will not send a SNI response instead of aborting the session. - \param WOLFSSL_SNI_ANSWER_ON_MISMATCH - With this option set, the server - will send a SNI response as if the host names match instead of aborting + \param WOLFSSL_SNI_ANSWER_ON_MISMATCH - With this option set, the server + will send a SNI response as if the host names match instead of aborting the session. - + _Example_ \code int ret = 0; @@ -9720,10 +9720,10 @@ WOLFSSL_API int wolfSSL_CTX_UseSNI(WOLFSSL_CTX* ctx, unsigned char type, if (ret != 0) { // sni usage failed } - wolfSSL_SNI_SetOptions(ssl, WOLFSSL_SNI_HOST_NAME, + wolfSSL_SNI_SetOptions(ssl, WOLFSSL_SNI_HOST_NAME, WOLFSSL_SNI_CONTINUE_ON_MISMATCH); \endcode - + \sa wolfSSL_new \sa wolfSSL_UseSNI \sa wolfSSL_CTX_SNI_SetOptions @@ -9732,27 +9732,27 @@ WOLFSSL_API void wolfSSL_SNI_SetOptions(WOLFSSL* ssl, unsigned char type, unsigned char options); /*! - \brief This function is called on the server side to configure the behavior - of the SSL sessions using Server Name Indication for SSL objects created - from the SSL context passed in the 'ctx' parameter. The options are + \brief This function is called on the server side to configure the behavior + of the SSL sessions using Server Name Indication for SSL objects created + from the SSL context passed in the 'ctx' parameter. The options are explained below. - + \return none No returns. - + \param ctx pointer to a SSL context, created with wolfSSL_CTX_new(). - \param type indicates which type of server name is been passed in data. + \param type indicates which type of server name is been passed in data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 }; - \param options a bitwise semaphore with the chosen options. The available - options are: enum { WOLFSSL_SNI_CONTINUE_ON_MISMATCH = 0x01, - WOLFSSL_SNI_ANSWER_ON_MISMATCH = 0x02 }; Normally the server will abort - the handshake by sending a fatal-level unrecognized_name(112) alert if the + \param options a bitwise semaphore with the chosen options. The available + options are: enum { WOLFSSL_SNI_CONTINUE_ON_MISMATCH = 0x01, + WOLFSSL_SNI_ANSWER_ON_MISMATCH = 0x02 }; Normally the server will abort + the handshake by sending a fatal-level unrecognized_name(112) alert if the hostname provided by the client mismatch with the servers. - \param WOLFSSL_SNI_CONTINUE_ON_MISMATCH With this option set, the + \param WOLFSSL_SNI_CONTINUE_ON_MISMATCH With this option set, the server will not send a SNI response instead of aborting the session. - \param WOLFSSL_SNI_ANSWER_ON_MISMATCH With this option set, the server - will send a SNI response as if the host names match instead of aborting + \param WOLFSSL_SNI_ANSWER_ON_MISMATCH With this option set, the server + will send a SNI response as if the host names match instead of aborting the session. - + _Example_ \code int ret = 0; @@ -9765,10 +9765,10 @@ WOLFSSL_API void wolfSSL_SNI_SetOptions(WOLFSSL* ssl, unsigned char type, if (ret != 0) { // sni usage failed } - wolfSSL_CTX_SNI_SetOptions(ctx, WOLFSSL_SNI_HOST_NAME, + wolfSSL_CTX_SNI_SetOptions(ctx, WOLFSSL_SNI_HOST_NAME, WOLFSSL_SNI_CONTINUE_ON_MISMATCH); \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_UseSNI \sa wolfSSL_SNI_SetOptions @@ -9777,27 +9777,27 @@ WOLFSSL_API void wolfSSL_CTX_SNI_SetOptions(WOLFSSL_CTX* ctx, unsigned char type, unsigned char options); /*! - \brief This function is called on the server side to retrieve the Server - Name Indication provided by the client from the Client Hello message sent - by the client to start a session. It does not requires context or session + \brief This function is called on the server side to retrieve the Server + Name Indication provided by the client from the Client Hello message sent + by the client to start a session. It does not requires context or session setup to retrieve the SNI. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG is the error that will be returned in one of this + \return BAD_FUNC_ARG is the error that will be returned in one of this cases: buffer is NULL, bufferSz <= 0, sni is NULL, inOutSz is NULL or <= 0 - \return BUFFER_ERROR is the error returned when there is a malformed + \return BUFFER_ERROR is the error returned when there is a malformed Client Hello message. - \return INCOMPLETE_DATA is the error returned when there is not enough + \return INCOMPLETE_DATA is the error returned when there is not enough data to complete the extraction. - + \param buffer pointer to the data provided by the client (Client Hello). \param bufferSz size of the Client Hello message. - \param type indicates which type of server name is been retrieved + \param type indicates which type of server name is been retrieved from the buffer. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 }; \param sni pointer to where the output is going to be stored. - \param inOutSz pointer to the output size, this value will be updated + \param inOutSz pointer to the output size, this value will be updated to MIN("SNI's length", inOutSz). - + _Example_ \code unsigned char buffer[1024] = {0}; @@ -9809,7 +9809,7 @@ WOLFSSL_API void wolfSSL_CTX_SNI_SetOptions(WOLFSSL_CTX* ctx, // sni retrieve failed } \endcode - + \sa wolfSSL_UseSNI \sa wolfSSL_CTX_UseSNI \sa wolfSSL_SNI_GetRequest @@ -9822,14 +9822,14 @@ WOLFSSL_API int wolfSSL_SNI_GetFromBuffer( \ingroup IO \brief This function gets the status of an SNI object. - - \return value This function returns the byte value of the SNI struct’s + + \return value This function returns the byte value of the SNI struct’s status member if the SNI is not NULL. \return 0 if the SNI object is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param type the SNI type. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -9842,7 +9842,7 @@ WOLFSSL_API int wolfSSL_SNI_GetFromBuffer( AssertIntEQ(WOLFSSL_SNI_NO_MATCH, wolfSSL_SNI_Status(ssl, type)); … \endcode - + \sa TLSX_SNI_Status \sa TLSX_SNI_find \sa TLSX_Find @@ -9850,16 +9850,16 @@ WOLFSSL_API int wolfSSL_SNI_GetFromBuffer( WOLFSSL_API unsigned char wolfSSL_SNI_Status(WOLFSSL* ssl, unsigned char type); /*! - \brief This function is called on the server side to retrieve the + \brief This function is called on the server side to retrieve the Server Name Indication provided by the client in a SSL session. - + \return size the size of the provided SNI data. - + \param ssl pointer to a SSL object, created with wolfSSL_new(). - \param type indicates which type of server name is been retrieved in + \param type indicates which type of server name is been retrieved in data. The known types are: enum { WOLFSSL_SNI_HOST_NAME = 0 }; \param data pointer to the data provided by the client. - + _Example_ \code int ret = 0; @@ -9882,7 +9882,7 @@ WOLFSSL_API unsigned char wolfSSL_SNI_Status(WOLFSSL* ssl, unsigned char type); unsigned short size = wolfSSL_SNI_GetRequest(ssl, 0, &data); } \endcode - + \sa wolfSSL_UseSNI \sa wolfSSL_CTX_UseSNI */ @@ -9893,21 +9893,21 @@ WOLFSSL_API unsigned short wolfSSL_SNI_GetRequest(WOLFSSL *ssl, \ingroup Setup \brief Setup ALPN use for a wolfSSL session. - + \return SSL_SUCCESS: upon success. - \return BAD_FUNC_ARG Returned if ssl or protocol_name_list - is null or protocol_name_listSz is too large or options + \return BAD_FUNC_ARG Returned if ssl or protocol_name_list + is null or protocol_name_listSz is too large or options contain something not supported. \return MEMORY_ERROR Error allocating memory for protocol list. \return SSL_FAILURE upon failure. - + \param ssl The wolfSSL session to use. - \param protocol_name_list List of protocol names to use. + \param protocol_name_list List of protocol names to use. Comma delimited string is required. \param protocol_name_listSz Size of the list of protocol names. - \param options WOLFSSL_ALPN_CONTINUE_ON_MISMATCH or + \param options WOLFSSL_ALPN_CONTINUE_ON_MISMATCH or WOLFSSL_ALPN_FAILED_ON_MISMATCH. - + _Example_ \code wolfSSL_Init(); @@ -9919,13 +9919,13 @@ WOLFSSL_API unsigned short wolfSSL_SNI_GetRequest(WOLFSSL *ssl, char alpn_list[] = {}; - if(wolfSSL_UseALPN(ssl, alpn_list, sizeof(alpn_list), + if(wolfSSL_UseALPN(ssl, alpn_list, sizeof(alpn_list), WOLFSSL_APN_FAILED_ON_MISMATCH) != SSL_SUCCESS) { // Error setting session ticket } \endcode - + \sa TLSX_UseALPN */ WOLFSSL_API int wolfSSL_UseALPN(WOLFSSL* ssl, char *protocol_name_list, @@ -9936,22 +9936,22 @@ WOLFSSL_API int wolfSSL_UseALPN(WOLFSSL* ssl, char *protocol_name_list, \ingroup TLS \brief This function gets the protocol name set by the server. - - \return SSL_SUCCESS returned on successful execution where no + + \return SSL_SUCCESS returned on successful execution where no errors were thrown. - \return SSL_FATAL_ERROR returned if the extension was not found or - if there was no protocol match with peer. There will also be an + \return SSL_FATAL_ERROR returned if the extension was not found or + if there was no protocol match with peer. There will also be an error thrown if there is more than one protocol name accepted. - \return SSL_ALPN_NOT_FOUND returned signifying that no protocol + \return SSL_ALPN_NOT_FOUND returned signifying that no protocol match with peer was found. - \return BAD_FUNC_ARG returned if there was a NULL argument passed + \return BAD_FUNC_ARG returned if there was a NULL argument passed into the function. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param protocol_name a pointer to a char that represents the protocol + \param protocol_name a pointer to a char that represents the protocol name and will be held in the ALPN structure. \param size a word16 type that represents the size of the protocol_name. - + _Example_ \code WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method ); @@ -9966,7 +9966,7 @@ WOLFSSL_API int wolfSSL_UseALPN(WOLFSSL* ssl, char *protocol_name_list, // Sent ALPN protocol } \endcode - + \sa TLSX_ALPN_GetRequest \sa TLSX_Find */ @@ -9976,27 +9976,27 @@ WOLFSSL_API int wolfSSL_ALPN_GetProtocol(WOLFSSL* ssl, char **protocol_name, /*! \ingroup TLS - \brief This function copies the alpn_client_list data from the SSL + \brief This function copies the alpn_client_list data from the SSL object to the buffer. - - \return SSL_SUCCESS returned if the function executed without error. The - alpn_client_list member of the SSL object has been copied to the + + \return SSL_SUCCESS returned if the function executed without error. The + alpn_client_list member of the SSL object has been copied to the list parameter. \return BAD_FUNC_ARG returned if the list or listSz parameter is NULL. - \return BUFFER_ERROR returned if there will be a problem with the + \return BUFFER_ERROR returned if there will be a problem with the list buffer (either it’s NULL or the size is 0). - \return MEMORY_ERROR returned if there was a problem dynamically + \return MEMORY_ERROR returned if there was a problem dynamically allocating memory. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param list a pointer to the buffer. The data from the SSL object will + \param list a pointer to the buffer. The data from the SSL object will be copied into it. \param listSz the buffer size. - + _Example_ \code #import - + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method); WOLFSSL* ssl = wolfSSL_new(ctx); … @@ -10010,30 +10010,30 @@ WOLFSSL_API int wolfSSL_ALPN_GetProtocol(WOLFSSL* ssl, char **protocol_name, List of protocols names sent by client } \endcode - + \sa wolfSSL_UseALPN */ WOLFSSL_API int wolfSSL_ALPN_GetPeerProtocol(WOLFSSL* ssl, char **list, unsigned short *listSz); /*! - \brief This function is called on the client side to enable the use of - Maximum Fragment Length in the SSL object passed in the 'ssl' parameter. - It means that the Maximum Fragment Length extension will be sent on + \brief This function is called on the client side to enable the use of + Maximum Fragment Length in the SSL object passed in the 'ssl' parameter. + It means that the Maximum Fragment Length extension will be sent on ClientHello by wolfSSL clients. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG is the error that will be returned in one of + \return BAD_FUNC_ARG is the error that will be returned in one of these cases: ssl is NULL, mfl is out of range. \return MEMORY_E is the error returned when there is not enough memory. - + \param ssl pointer to a SSL object, created with wolfSSL_new(). - \param mfl indicates witch is the Maximum Fragment Length requested for the - session. The available options are: enum { WOLFSSL_MFL_2_9 = 1, 512 bytes - WOLFSSL_MFL_2_10 = 2, 1024 bytes WOLFSSL_MFL_2_11 = 3, 2048 bytes - WOLFSSL_MFL_2_12 = 4, 4096 bytes WOLFSSL_MFL_2_13 = 5, 8192 + \param mfl indicates witch is the Maximum Fragment Length requested for the + session. The available options are: enum { WOLFSSL_MFL_2_9 = 1, 512 bytes + WOLFSSL_MFL_2_10 = 2, 1024 bytes WOLFSSL_MFL_2_11 = 3, 2048 bytes + WOLFSSL_MFL_2_12 = 4, 4096 bytes WOLFSSL_MFL_2_13 = 5, 8192 bytes wolfSSL ONLY!!! }; - + _Example_ \code int ret = 0; @@ -10052,30 +10052,30 @@ WOLFSSL_API int wolfSSL_ALPN_GetPeerProtocol(WOLFSSL* ssl, char **list, // max fragment usage failed } \endcode - + \sa wolfSSL_new \sa wolfSSL_CTX_UseMaxFragment */ WOLFSSL_API int wolfSSL_UseMaxFragment(WOLFSSL* ssl, unsigned char mfl); /*! - \brief This function is called on the client side to enable the use - of Maximum Fragment Length for SSL objects created from the SSL context - passed in the 'ctx' parameter. It means that the Maximum Fragment Length + \brief This function is called on the client side to enable the use + of Maximum Fragment Length for SSL objects created from the SSL context + passed in the 'ctx' parameter. It means that the Maximum Fragment Length extension will be sent on ClientHello by wolfSSL clients. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG is the error that will be returned in one of + \return BAD_FUNC_ARG is the error that will be returned in one of these cases: ctx is NULL, mfl is out of range. \return MEMORY_E is the error returned when there is not enough memory. - + \param ctx pointer to a SSL context, created with wolfSSL_CTX_new(). - \param mfl indicates which is the Maximum Fragment Length requested - for the session. The available options are: - enum { WOLFSSL_MFL_2_9 = 1, 512 bytes WOLFSSL_MFL_2_10 = 2, - 1024 bytes WOLFSSL_MFL_2_11 = 3, 2048 bytes WOLFSSL_MFL_2_12 = 4, + \param mfl indicates which is the Maximum Fragment Length requested + for the session. The available options are: + enum { WOLFSSL_MFL_2_9 = 1, 512 bytes WOLFSSL_MFL_2_10 = 2, + 1024 bytes WOLFSSL_MFL_2_11 = 3, 2048 bytes WOLFSSL_MFL_2_12 = 4, 4096 bytes WOLFSSL_MFL_2_13 = 5, 8192 bytes wolfSSL ONLY!!! }; - + _Example_ \code int ret = 0; @@ -10089,25 +10089,25 @@ WOLFSSL_API int wolfSSL_UseMaxFragment(WOLFSSL* ssl, unsigned char mfl); // max fragment usage failed } \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_UseMaxFragment */ WOLFSSL_API int wolfSSL_CTX_UseMaxFragment(WOLFSSL_CTX* ctx, unsigned char mfl); /*! - \brief This function is called on the client side to enable the use of - Truncated HMAC in the SSL object passed in the 'ssl' parameter. It - means that the Truncated HMAC extension will be sent on ClientHello + \brief This function is called on the client side to enable the use of + Truncated HMAC in the SSL object passed in the 'ssl' parameter. It + means that the Truncated HMAC extension will be sent on ClientHello by wolfSSL clients. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG is the error that will be returned in one of + \return BAD_FUNC_ARG is the error that will be returned in one of these cases: ssl is NULL \return MEMORY_E is the error returned when there is not enough memory. - + \param ssl pointer to a SSL object, created with wolfSSL_new() - + _Example_ \code int ret = 0; @@ -10126,25 +10126,25 @@ WOLFSSL_API int wolfSSL_CTX_UseMaxFragment(WOLFSSL_CTX* ctx, unsigned char mfl); // truncated HMAC usage failed } \endcode - + \sa wolfSSL_new \sa wolfSSL_CTX_UseMaxFragment */ WOLFSSL_API int wolfSSL_UseTruncatedHMAC(WOLFSSL* ssl); /*! - \brief This function is called on the client side to enable the use of - Truncated HMAC for SSL objects created from the SSL context passed in - the 'ctx' parameter. It means that the Truncated HMAC extension will + \brief This function is called on the client side to enable the use of + Truncated HMAC for SSL objects created from the SSL context passed in + the 'ctx' parameter. It means that the Truncated HMAC extension will be sent on ClientHello by wolfSSL clients. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG is the error that will be returned in one of + \return BAD_FUNC_ARG is the error that will be returned in one of these cases: ctx is NULL \return MEMORY_E is the error returned when there is not enough memory. - + \param ctx pointer to a SSL context, created with wolfSSL_CTX_new(). - + _Example_ \code int ret = 0; @@ -10158,41 +10158,41 @@ WOLFSSL_API int wolfSSL_UseTruncatedHMAC(WOLFSSL* ssl); // truncated HMAC usage failed } \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_UseMaxFragment */ WOLFSSL_API int wolfSSL_CTX_UseTruncatedHMAC(WOLFSSL_CTX* ctx); /*! - \brief Stapling eliminates the need to contact the CA. Stapling + \brief Stapling eliminates the need to contact the CA. Stapling lowers the cost of certificate revocation check presented in OCSP. - - \return SSL_SUCCESS returned if TLSX_UseCertificateStatusRequest + + \return SSL_SUCCESS returned if TLSX_UseCertificateStatusRequest executes without error. - \return MEMORY_E returned if there is an error with the allocation + \return MEMORY_E returned if there is an error with the allocation of memory. - \return BAD_FUNC_ARG returned if there is an argument that has a + \return BAD_FUNC_ARG returned if there is an argument that has a NULL or otherwise unacceptable value passed into the function. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param status_type a byte type that is passed through to - TLSX_UseCertificateStatusRequest() and stored in the + \param status_type a byte type that is passed through to + TLSX_UseCertificateStatusRequest() and stored in the CertificateStatusRequest structure. - \param options a byte type that is passed through to - TLSX_UseCertificateStatusRequest() and stored in the + \param options a byte type that is passed through to + TLSX_UseCertificateStatusRequest() and stored in the CertificateStatusRequest structure. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); … - if (wolfSSL_UseOCSPStapling(ssl, WOLFSSL_CSR2_OCSP, + if (wolfSSL_UseOCSPStapling(ssl, WOLFSSL_CSR2_OCSP, WOLFSSL_CSR2_OCSP_USE_NONCE) != SSL_SUCCESS){ // Failed case. } \endcode - + \sa TLSX_UseCertificateStatusRequest \sa wolfSSL_CTX_UseOCSPStapling */ @@ -10201,23 +10201,23 @@ WOLFSSL_API int wolfSSL_UseOCSPStapling(WOLFSSL* ssl, /*! \brief This function requests the certificate status during the handshake. - - \return SSL_SUCCESS returned if the function and subroutines execute + + \return SSL_SUCCESS returned if the function and subroutines execute without error. - \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or + \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or otherwise if a unpermitted value is passed to a subroutine. - \return MEMORY_E returned if the function or subroutine failed to properly + \return MEMORY_E returned if the function or subroutine failed to properly allocate memory. - - \param ctx a pointer to a WOLFSSL_CTX structure, + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - \param status_type a byte type that is passed through to - TLSX_UseCertificateStatusRequest() and stored in the + \param status_type a byte type that is passed through to + TLSX_UseCertificateStatusRequest() and stored in the CertificateStatusRequest structure. - \param options a byte type that is passed through to - TLSX_UseCertificateStatusRequest() and stored in the + \param options a byte type that is passed through to + TLSX_UseCertificateStatusRequest() and stored in the CertificateStatusRequest structure. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -10226,13 +10226,13 @@ WOLFSSL_API int wolfSSL_UseOCSPStapling(WOLFSSL* ssl, … switch(statusRequest){ case WOLFSSL_CSR_OCSP: - if(wolfSSL_CTX_UseOCSPStapling(ssl->ctx, WOLFSSL_CSR_OCSP, + if(wolfSSL_CTX_UseOCSPStapling(ssl->ctx, WOLFSSL_CSR_OCSP, WOLF_CSR_OCSP_USE_NONCE) != SSL_SUCCESS){ // UseCertificateStatusRequest failed } // Continue switch cases \endcode - + \sa wolfSSL_UseOCSPStaplingV2 \sa wolfSSL_UseOCSPStapling \sa TLSX_UseCertificateStatusRequest @@ -10242,18 +10242,18 @@ WOLFSSL_API int wolfSSL_CTX_UseOCSPStapling(WOLFSSL_CTX* ctx, /*! \brief The function sets the status type and options for OCSP. - - \return SSL_SUCCESS - returned if the function and subroutines + + \return SSL_SUCCESS - returned if the function and subroutines executed without error. \return MEMORY_E - returned if there was an allocation of memory error. - \return BAD_FUNC_ARG - returned if a NULL or otherwise unaccepted + \return BAD_FUNC_ARG - returned if a NULL or otherwise unaccepted argument was passed to the function or a subroutine. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param status_type a byte type that loads the OCSP status type. - \param options a byte type that holds the OCSP options, set in + \param options a byte type that holds the OCSP options, set in wolfSSL_SNI_SetOptions() and wolfSSL_CTX_SNI_SetOptions(). - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -10262,7 +10262,7 @@ WOLFSSL_API int wolfSSL_CTX_UseOCSPStapling(WOLFSSL_CTX* ctx, // Did not execute properly. Failure case code block. } \endcode - + \sa TLSX_UseCertificatStatusRequestV2 \sa wolfSSL_SNI_SetOptions \sa wolfSSL_CTX_SNI_SetOptions @@ -10271,22 +10271,22 @@ WOLFSSL_API int wolfSSL_UseOCSPStaplingV2(WOLFSSL* ssl, unsigned char status_type, unsigned char options); /*! - \brief Creates and initializes the certificate status request + \brief Creates and initializes the certificate status request for OCSP Stapling. - + \return SSL_SUCCESS if the function and subroutines executed without error. - \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or if + \return BAD_FUNC_ARG returned if the WOLFSSL_CTX structure is NULL or if the side variable is not client side. \return MEMORY_E returned if the allocation of memory failed. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). - \param status_type a byte type that is located in the - CertificatStatusRequest structure and must be either WOLFSSL_CSR2_OCSP + \param status_type a byte type that is located in the + CertificatStatusRequest structure and must be either WOLFSSL_CSR2_OCSP or WOLFSSL_CSR2_OCSP_MULTI. - \param options a byte type that will be held in + \param options a byte type that will be held in CertificateStatusRequestItemV2 struct. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -10297,7 +10297,7 @@ WOLFSSL_API int wolfSSL_UseOCSPStaplingV2(WOLFSSL* ssl, // Failure case. } \endcode - + \sa TLSX_UseCertificateStatusRequestV2 \sa wc_RNG_GenerateBlock \sa TLSX_Push @@ -10306,24 +10306,24 @@ WOLFSSL_API int wolfSSL_CTX_UseOCSPStaplingV2(WOLFSSL_CTX* ctx, unsigned char status_type, unsigned char options); /*! - \brief This function is called on the client side to enable the use of - Supported Elliptic Curves Extension in the SSL object passed in the 'ssl' - parameter. It means that the supported curves enabled will be sent on - ClientHello by wolfSSL clients. This function can be called more than + \brief This function is called on the client side to enable the use of + Supported Elliptic Curves Extension in the SSL object passed in the 'ssl' + parameter. It means that the supported curves enabled will be sent on + ClientHello by wolfSSL clients. This function can be called more than one time to enable multiple curves. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG is the error that will be returned in one of these + \return BAD_FUNC_ARG is the error that will be returned in one of these cases: ssl is NULL, name is a unknown value. (see below) \return MEMORY_E is the error returned when there is not enough memory. - + \param ssl pointer to a SSL object, created with wolfSSL_new(). - \param name indicates which curve will be supported for the session. The - available options are: enum { WOLFSSL_ECC_SECP160R1 = 0x10, - WOLFSSL_ECC_SECP192R1 = 0x13, WOLFSSL_ECC_SECP224R1 = 0x15, - WOLFSSL_ECC_SECP256R1 = 0x17, WOLFSSL_ECC_SECP384R1 = 0x18, + \param name indicates which curve will be supported for the session. The + available options are: enum { WOLFSSL_ECC_SECP160R1 = 0x10, + WOLFSSL_ECC_SECP192R1 = 0x13, WOLFSSL_ECC_SECP224R1 = 0x15, + WOLFSSL_ECC_SECP256R1 = 0x17, WOLFSSL_ECC_SECP384R1 = 0x18, WOLFSSL_ECC_SECP521R1 = 0x19 }; - + _Example_ \code int ret = 0; @@ -10342,31 +10342,31 @@ WOLFSSL_API int wolfSSL_CTX_UseOCSPStaplingV2(WOLFSSL_CTX* ctx, // Elliptic Curve Extension usage failed } \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_UseSupportedCurve */ WOLFSSL_API int wolfSSL_UseSupportedCurve(WOLFSSL* ssl, unsigned short name); /*! - \brief This function is called on the client side to enable the use of - Supported Elliptic Curves Extension for SSL objects created from the SSL - context passed in the 'ctx' parameter. It means that the supported curves - enabled will be sent on ClientHello by wolfSSL clients. This function can + \brief This function is called on the client side to enable the use of + Supported Elliptic Curves Extension for SSL objects created from the SSL + context passed in the 'ctx' parameter. It means that the supported curves + enabled will be sent on ClientHello by wolfSSL clients. This function can be called more than one time to enable multiple curves. - + \return SSL_SUCCESS upon success. - \return BAD_FUNC_ARG is the error that will be returned in one of these + \return BAD_FUNC_ARG is the error that will be returned in one of these cases: ctx is NULL, name is a unknown value. (see below) \return MEMORY_E is the error returned when there is not enough memory. - + \param ctx pointer to a SSL context, created with wolfSSL_CTX_new(). - \param name indicates which curve will be supported for the session. - The available options are: enum { WOLFSSL_ECC_SECP160R1 = 0x10, - WOLFSSL_ECC_SECP192R1 = 0x13, WOLFSSL_ECC_SECP224R1 = 0x15, - WOLFSSL_ECC_SECP256R1 = 0x17, WOLFSSL_ECC_SECP384R1 = 0x18, + \param name indicates which curve will be supported for the session. + The available options are: enum { WOLFSSL_ECC_SECP160R1 = 0x10, + WOLFSSL_ECC_SECP192R1 = 0x13, WOLFSSL_ECC_SECP224R1 = 0x15, + WOLFSSL_ECC_SECP256R1 = 0x17, WOLFSSL_ECC_SECP384R1 = 0x18, WOLFSSL_ECC_SECP521R1 = 0x19 }; - + _Example_ \code int ret = 0; @@ -10380,7 +10380,7 @@ WOLFSSL_API int wolfSSL_UseSupportedCurve(WOLFSSL* ssl, unsigned short name); // Elliptic Curve Extension usage failed } \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_UseSupportedCurve */ @@ -10390,12 +10390,12 @@ WOLFSSL_API int wolfSSL_CTX_UseSupportedCurve(WOLFSSL_CTX* ctx, /*! \ingroup IO - \brief This function forces secure renegotiation for the supplied + \brief This function forces secure renegotiation for the supplied WOLFSSL structure. This is not recommended. \return SSL_SUCCESS Successfully set secure renegotiation. \return BAD_FUNC_ARG Returns error if ssl is null. - \return MEMORY_E Returns error if unable to allocate memory for secure + \return MEMORY_E Returns error if unable to allocate memory for secure renegotiation. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). @@ -10414,7 +10414,7 @@ WOLFSSL_API int wolfSSL_CTX_UseSupportedCurve(WOLFSSL_CTX* ctx, // Error setting secure renegotiation } \endcode - + \sa TLSX_Find \sa TLSX_UseSecureRenegotiation */ @@ -10425,18 +10425,18 @@ WOLFSSL_API int wolfSSL_UseSecureRenegotiation(WOLFSSL* ssl); \brief This function executes a secure renegotiation handshake; this is user forced as wolfSSL discourages this functionality. - + \return SSL_SUCCESS returned if the function executed without error. - \return BAD_FUNC_ARG returned if the WOLFSSL structure was NULL or otherwise + \return BAD_FUNC_ARG returned if the WOLFSSL structure was NULL or otherwise if an unacceptable argument was passed in a subroutine. - \return SECURE_RENEGOTIATION_E returned if there was an error with + \return SECURE_RENEGOTIATION_E returned if there was an error with renegotiating the handshake. - \return SSL_FATAL_ERROR returned if there was an error with the - server or client configuration and the renegotiation could + \return SSL_FATAL_ERROR returned if there was an error with the + server or client configuration and the renegotiation could not be completed. See wolfSSL_negotiate(). - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -10445,7 +10445,7 @@ WOLFSSL_API int wolfSSL_UseSecureRenegotiation(WOLFSSL* ssl); // There was an error and the rehandshake is not successful. } \endcode - + \sa wolfSSL_negotiate \sa wc_InitSha512 \sa wc_InitSha384 @@ -10458,16 +10458,16 @@ WOLFSSL_API int wolfSSL_Rehandshake(WOLFSSL* ssl); /*! \ingroup IO - \brief Force provided WOLFSSL structure to use session ticket. The - constant HAVE_SESSION_TICKET should be defined and the constant + \brief Force provided WOLFSSL structure to use session ticket. The + constant HAVE_SESSION_TICKET should be defined and the constant NO_WOLFSSL_CLIENT should not be defined to use this function. - + \return SSL_SUCCESS Successfully set use session ticket. \return BAD_FUNC_ARG Returned if ssl is null. \return MEMORY_E Error allocating memory for setting session ticket. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code wolfSSL_Init(); @@ -10482,7 +10482,7 @@ WOLFSSL_API int wolfSSL_Rehandshake(WOLFSSL* ssl); // Error setting session ticket } \endcode - + \sa TLSX_UseSessionTicket */ WOLFSSL_API int wolfSSL_UseSessionTicket(WOLFSSL* ssl); @@ -10491,13 +10491,13 @@ WOLFSSL_API int wolfSSL_UseSessionTicket(WOLFSSL* ssl); \ingroup Setup \brief This function sets wolfSSL context to use a session ticket. - + \return SSL_SUCCESS Function executed successfully. \return BAD_FUNC_ARG Returned if ctx is null. \return MEMORY_E Error allocating memory in internal function. - + \param ctx The WOLFSSL_CTX structure to use. - + _Example_ \code wolfSSL_Init(); @@ -10510,7 +10510,7 @@ WOLFSSL_API int wolfSSL_UseSessionTicket(WOLFSSL* ssl); // Error setting session ticket } \endcode - + \sa TLSX_UseSessionTicket */ WOLFSSL_API int wolfSSL_CTX_UseSessionTicket(WOLFSSL_CTX* ctx); @@ -10518,17 +10518,17 @@ WOLFSSL_API int wolfSSL_CTX_UseSessionTicket(WOLFSSL_CTX* ctx); /*! \ingroup IO - \brief This function copies the ticket member of the Session structure to + \brief This function copies the ticket member of the Session structure to the buffer. - + \return SSL_SUCCESS returned if the function executed without error. - \return BAD_FUNC_ARG returned if one of the arguments was NULL or if the + \return BAD_FUNC_ARG returned if one of the arguments was NULL or if the bufSz argument was 0. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param buf a byte pointer representing the memory buffer. \param bufSz a word32 pointer representing the buffer size. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -10542,7 +10542,7 @@ WOLFSSL_API int wolfSSL_CTX_UseSessionTicket(WOLFSSL_CTX* ctx); // the buffer holds the content from ssl->session.ticket } \endcode - + \sa wolfSSL_UseSessionTicket \sa wolfSSL_set_SessionTicket */ @@ -10551,21 +10551,21 @@ WOLFSSL_API int wolfSSL_get_SessionTicket(WOLFSSL*, unsigned char*, unsigned int /*! \ingroup IO - \brief This function sets the ticket member of the WOLFSSL_SESSION - structure within the WOLFSSL struct. The buffer passed into the function + \brief This function sets the ticket member of the WOLFSSL_SESSION + structure within the WOLFSSL struct. The buffer passed into the function is copied to memory. - - \return SSL_SUCCESS returned on successful execution of the function. + + \return SSL_SUCCESS returned on successful execution of the function. The function returned without errors. - \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL. This will - also be thrown if the buf argument is NULL but the bufSz argument + \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL. This will + also be thrown if the buf argument is NULL but the bufSz argument is not zero. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param buf a byte pointer that gets loaded into the ticket member + \param buf a byte pointer that gets loaded into the ticket member of the session structure. \param bufSz a word32 type that represents the size of the buffer. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -10577,24 +10577,24 @@ WOLFSSL_API int wolfSSL_get_SessionTicket(WOLFSSL*, unsigned char*, unsigned int // There was an error loading the buffer to memory. } \endcode - + \sa wolfSSL_set_SessionTicket_cb */ WOLFSSL_API int wolfSSL_set_SessionTicket(WOLFSSL*, const unsigned char*, unsigned int); /*! - \brief This function sets the session ticket callback. The type - CallbackSessionTicket is a function pointer with the signature of: + \brief This function sets the session ticket callback. The type + CallbackSessionTicket is a function pointer with the signature of: int (*CallbackSessionTicket)(WOLFSSL*, const unsigned char*, int, void*) - + \return SSL_SUCCESS returned if the function executed without error. \return BAD_FUNC_ARG returned if the WOLFSSL structure is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param cb a function pointer to the type CallbackSessionTicket. - \param ctx a void pointer to the session_ticket_ctx member of the + \param ctx a void pointer to the session_ticket_ctx member of the WOLFSSL structure. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -10604,7 +10604,7 @@ WOLFSSL_API int wolfSSL_set_SessionTicket(WOLFSSL*, const unsigned char*, unsign void* ctx){ … } wolfSSL_set_SessionTicket_cb(ssl, sessionTicketCB, (void*)”initial session”); \endcode - + \sa wolfSSL_set_SessionTicket \sa CallbackSessionTicket \sa sessionTicketCB @@ -10615,50 +10615,50 @@ WOLFSSL_API int wolfSSL_set_SessionTicket_cb(WOLFSSL*, /*! \brief This function sets the session ticket key encrypt callback function for a server to support session tickets as specified in RFC 5077. - + \return SSL_SUCCESS will be returned upon successfully setting the session. \return BAD_FUNC_ARG will be returned on failure. This is caused by passing invalid arguments to the function. - + \param ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new(). \param cb user callback function to encrypt/decrypt session tickets - \param ssl(Callback) pointer to the WOLFSSL object, created with + \param ssl(Callback) pointer to the WOLFSSL object, created with wolfSSL_new() - \param key_name(Callback) unique key name for this ticket context, should + \param key_name(Callback) unique key name for this ticket context, should be randomly generated - \param iv(Callback) unique IV for this ticket, up to 128 bits, should + \param iv(Callback) unique IV for this ticket, up to 128 bits, should be randomly generated \param mac(Callback) up to 256 bit mac for this ticket - \param enc(Callback) if this encrypt parameter is true the user should fill - in key_name, iv, mac, and encrypt the ticket in-place of length inLen and - set the resulting output length in *outLen. Returning WOLFSSL_TICKET_RET_OK - tells wolfSSL that the encryption was successful. If this encrypt parameter - is false, the user should perform a decrypt of the ticket in-place of length - inLen using key_name, iv, and mac. The resulting decrypt length should be - set in *outLen. Returning WOLFSSL_TICKET_RET_OK tells wolfSSL to proceed - using the decrypted ticket. Returning WOLFSSL_TICKET_RET_CREATE tells - wolfSSL to use the decrypted ticket but also to generate a new one to - send to the client, helpful if recently rolled keys and don’t want to - force a full handshake. Returning WOLFSSL_TICKET_RET_REJECT tells - wolfSSL to reject this ticket, perform a full handshake, and create - a new standard session ID for normal session resumption. Returning - WOLFSSL_TICKET_RET_FATAL tells wolfSSL to end the connection + \param enc(Callback) if this encrypt parameter is true the user should fill + in key_name, iv, mac, and encrypt the ticket in-place of length inLen and + set the resulting output length in *outLen. Returning WOLFSSL_TICKET_RET_OK + tells wolfSSL that the encryption was successful. If this encrypt parameter + is false, the user should perform a decrypt of the ticket in-place of length + inLen using key_name, iv, and mac. The resulting decrypt length should be + set in *outLen. Returning WOLFSSL_TICKET_RET_OK tells wolfSSL to proceed + using the decrypted ticket. Returning WOLFSSL_TICKET_RET_CREATE tells + wolfSSL to use the decrypted ticket but also to generate a new one to + send to the client, helpful if recently rolled keys and don’t want to + force a full handshake. Returning WOLFSSL_TICKET_RET_REJECT tells + wolfSSL to reject this ticket, perform a full handshake, and create + a new standard session ID for normal session resumption. Returning + WOLFSSL_TICKET_RET_FATAL tells wolfSSL to end the connection attempt with a fatal error. \param ticket(Callback) the input/output buffer for the encrypted ticket. See the enc parameter \param inLen(Callback) the input length of the ticket parameter - \param outLen(Callback) the resulting output length of the ticket parameter. - When entering the callback outLen will indicate the maximum size available + \param outLen(Callback) the resulting output length of the ticket parameter. + When entering the callback outLen will indicate the maximum size available in the ticket buffer. - \param userCtx(Callback) the user context set with + \param userCtx(Callback) the user context set with wolfSSL_CTX_set_TicketEncCtx() - + _Example_ \code - See wolfssl/test.h myTicketEncCb() used by the example + See wolfssl/test.h myTicketEncCb() used by the example server and example echoserver. \endcode - + \sa wolfSSL_CTX_set_TicketHint \sa wolfSSL_CTX_set_TicketEncCtx */ @@ -10668,40 +10668,40 @@ WOLFSSL_API int wolfSSL_CTX_set_TicketEncCb(WOLFSSL_CTX* ctx, /*! \brief This function sets the session ticket hint relayed to the client. For server side use. - + \return SSL_SUCCESS will be returned upon successfully setting the session. \return BAD_FUNC_ARG will be returned on failure. This is caused by passing invalid arguments to the function. - + \param ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new(). \param hint number of seconds the ticket might be valid for. Hint to client. - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_set_TicketEncCb */ WOLFSSL_API int wolfSSL_CTX_set_TicketHint(WOLFSSL_CTX* ctx, int); /*! - \brief This function sets the session ticket encrypt user context for the + \brief This function sets the session ticket encrypt user context for the callback. For server side use. - + \return SSL_SUCCESS will be returned upon successfully setting the session. - \return BAD_FUNC_ARG will be returned on failure. This is caused by + \return BAD_FUNC_ARG will be returned on failure. This is caused by passing invalid arguments to the function. - - \param ctx pointer to the WOLFSSL_CTX object, created + + \param ctx pointer to the WOLFSSL_CTX object, created with wolfSSL_CTX_new(). \param userCtx the user context for the callback - + _Example_ \code none \endcode - + \sa wolfSSL_CTX_set_TicketEncCb */ WOLFSSL_API int wolfSSL_CTX_set_TicketEncCtx(WOLFSSL_CTX* ctx, void*); @@ -10710,12 +10710,12 @@ WOLFSSL_API int wolfSSL_CTX_set_TicketEncCtx(WOLFSSL_CTX* ctx, void*); \ingroup IO \brief Checks if QSH is used in the supplied SSL session. - + \return 0 Not used \return 1 Is used - + \param ssl Pointer to the SSL session to check. - + _Example_ \code wolfSSL_Init(); @@ -10727,10 +10727,10 @@ WOLFSSL_API int wolfSSL_CTX_set_TicketEncCtx(WOLFSSL_CTX* ctx, void*); if(wolfSSL_isQSH(ssl) == 1) { - // SSL is using QSH. + // SSL is using QSH. } \endcode - + \sa wolfSSL_UseSupportedQSH */ WOLFSSL_API int wolfSSL_isQSH(WOLFSSL* ssl); @@ -10738,17 +10738,17 @@ WOLFSSL_API int wolfSSL_isQSH(WOLFSSL* ssl); /*! \ingroup Setup - \brief This function sets the ssl session to use supported QSH provided by + \brief This function sets the ssl session to use supported QSH provided by name. - + \return SSL_SUCCESS Successfully set supported QSH. \return BAD_FUNC_ARG ssl is null or name is invalid. \return MEMORY_E Error allocating memory for operation. - + \param ssl Pointer to ssl session to use. \param name Name of a supported QSH. Valid names are WOLFSSL_NTRU_EESS439, WOLFSSL_NTRU_EESS593, or WOLFSSL_NTRU_EESS743. - + _Example_ \code wolfSSL_Init(); @@ -10765,7 +10765,7 @@ WOLFSSL_API int wolfSSL_isQSH(WOLFSSL* ssl); // Error setting QSH } \endcode - + \sa TLSX_UseQSHScheme */ WOLFSSL_API int wolfSSL_UseSupportedQSH(WOLFSSL* ssl, unsigned short name); @@ -10773,16 +10773,16 @@ WOLFSSL_API int wolfSSL_UseSupportedQSH(WOLFSSL* ssl, unsigned short name); /*! \ingroup CertsKeys - \brief If the flag is 1 keys will be sent in hello. If flag is 0 then the + \brief If the flag is 1 keys will be sent in hello. If flag is 0 then the keys will not be sent during hello. - + \return 0 on success. \return BAD_FUNC_ARG if the WOLFSSL structure is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param flag an unsigned char input to determine if the keys will be sent + \param flag an unsigned char input to determine if the keys will be sent during hello. - + _Example_ \code WOLFSSL* ssl; @@ -10792,7 +10792,7 @@ WOLFSSL_API int wolfSSL_UseSupportedQSH(WOLFSSL* ssl, unsigned short name); // The keys will be sent during hello. } \endcode - + \sa wolfSSL_UseALPN \sa wolfSSL_UseSupportedQSH \sa wolfSSL_isQSH @@ -10800,15 +10800,15 @@ WOLFSSL_API int wolfSSL_UseSupportedQSH(WOLFSSL* ssl, unsigned short name); WOLFSSL_API int wolfSSL_UseClientQSHKeys(WOLFSSL* ssl, unsigned char flag); /*! - \brief This function sets the handshake done callback. The hsDoneCb and + \brief This function sets the handshake done callback. The hsDoneCb and hsDoneCtx members of the WOLFSSL structure are set in this function. - - \return SSL_SUCCESS returned if the function executed without an error. + + \return SSL_SUCCESS returned if the function executed without an error. The hsDoneCb and hsDoneCtx members of the WOLFSSL struct are set. \return BAD_FUNC_ARG returned if the WOLFSSL struct is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param cb a function pointer of type HandShakeDoneCb with the signature of + \param cb a function pointer of type HandShakeDoneCb with the signature of the form: int (*HandShakeDoneCb)(WOLFSSL*, void*); \param user_ctx a void pointer to the user registered context. @@ -10823,7 +10823,7 @@ WOLFSSL_API int wolfSSL_UseClientQSHKeys(WOLFSSL* ssl, unsigned char flag); … wolfSSL_SetHsDoneCb(ssl, myHsDoneCb, NULL); \endcode - + \sa HandShakeDoneCb */ WOLFSSL_API int wolfSSL_SetHsDoneCb(WOLFSSL*, HandShakeDoneCb, void*); @@ -10832,15 +10832,15 @@ WOLFSSL_API int wolfSSL_SetHsDoneCb(WOLFSSL*, HandShakeDoneCb, void*); \ingroup IO \brief This function prints the statistics from the session. - + \return SSL_SUCCESS returned if the function and subroutines return without error. The session stats have been successfully retrieved and printed. \return BAD_FUNC_ARG returned if the subroutine wolfSSL_get_session_stats() was passed an unacceptable argument. \return BAD_MUTEX_E returned if there was a mutex error in the subroutine. - + \param none No parameters. - + _Example_ \code // You will need to have a session object to retrieve stats from. @@ -10849,7 +10849,7 @@ WOLFSSL_API int wolfSSL_SetHsDoneCb(WOLFSSL*, HandShakeDoneCb, void*); } \endcode - + \sa wolfSSL_get_session_stats */ WOLFSSL_API int wolfSSL_PrintSessionStats(void); @@ -10858,28 +10858,28 @@ WOLFSSL_API int wolfSSL_PrintSessionStats(void); \ingroup IO \brief This function gets the statistics for the session. - + \return SSL_SUCCESS returned if the function and subroutines return without error. The session stats have been successfully retrieved and printed. \return BAD_FUNC_ARG returned if the subroutine wolfSSL_get_session_stats() was passed an unacceptable argument. \return BAD_MUTEX_E returned if there was a mutex error in the subroutine. - + \param active a word32 pointer representing the total current sessions. \param total a word32 pointer representing the total sessions. \param peak a word32 pointer representing the peak sessions. \param maxSessions a word32 pointer representing the maximum sessions. - + _Example_ \code int wolfSSL_PrintSessionStats(void){ … - ret = wolfSSL_get_session_stats(&totalSessionsNow, + ret = wolfSSL_get_session_stats(&totalSessionsNow, &totalSessionsSeen, &peak, &maxSessions); … return ret; \endcode - + \sa get_locked_session_stats \sa wolfSSL_PrintSessionStats */ @@ -10891,15 +10891,15 @@ WOLFSSL_API int wolfSSL_get_session_stats(unsigned int* active, /*! \ingroup TLS - \brief This function copies the values of cr and sr then passes through to + \brief This function copies the values of cr and sr then passes through to PRF (pseudo random function) and returns that value. - + \return 0 on success - \return BUFFER_E returned if there will be an error + \return BUFFER_E returned if there will be an error with the size of the buffer. - \return MEMORY_E returned if a subroutine failed + \return MEMORY_E returned if a subroutine failed to allocate dynamic memory. - + \param ms the master secret held in the Arrays structure. \param msLen the length of the master secret. \param pms the pre-master secret held in the Arrays structure. @@ -10908,12 +10908,12 @@ WOLFSSL_API int wolfSSL_get_session_stats(unsigned int* active, \param sr the server random. \param tls1_2 signifies that the version is at least tls version 1.2. \param hash_type signifies the hash type. - + _Example_ \code WOLFSSL* ssl; - called in MakeTlsMasterSecret and retrieves the necessary + called in MakeTlsMasterSecret and retrieves the necessary information as follows: int MakeTlsMasterSecret(WOLFSSL* ssl){ @@ -10927,7 +10927,7 @@ WOLFSSL_API int wolfSSL_get_session_stats(unsigned int* active, } \endcode - + \sa PRF \sadoPRF \sa p_hash @@ -10943,27 +10943,27 @@ int wolfSSL_MakeTlsMasterSecret(unsigned char* ms, unsigned int msLen, \ingroup CertsKeys \brief An external facing wrapper to derive TLS Keys. - + \return 0 returned on success. - \return BUFFER_E returned if the sum of labLen and + \return BUFFER_E returned if the sum of labLen and seedLen (computes total size) exceeds the maximum size. \return MEMORY_E returned if the allocation of memory failed. - - \param key_data a byte pointer that is allocateded in DeriveTlsKeys + + \param key_data a byte pointer that is allocateded in DeriveTlsKeys and passed through to PRF to hold the final hash. - \param keyLen a word32 type that is derived in DeriveTlsKeys + \param keyLen a word32 type that is derived in DeriveTlsKeys from the WOLFSSL structure’s specs member. - \param ms a constant pointer type holding the master secret + \param ms a constant pointer type holding the master secret held in the arrays structure within the WOLFSSL structure. - \param msLen a word32 type that holds the length of the + \param msLen a word32 type that holds the length of the master secret in an enumerated define, SECRET_LEN. - \param sr a constant byte pointer to the serverRandom + \param sr a constant byte pointer to the serverRandom member of the arrays structure within the WOLFSSL structure. - \param cr a constant byte pointer to the clientRandom + \param cr a constant byte pointer to the clientRandom member of the arrays structure within the WOLFSSL structure. \param tls1_2 an integer type returned from IsAtLeastTLSv1_2(). \param hash_type an integer type held in the WOLFSSL structure. - + _Example_ \code int DeriveTlsKeys(WOLFSSL* ssl){ @@ -10975,7 +10975,7 @@ int wolfSSL_MakeTlsMasterSecret(unsigned char* ms, unsigned int msLen, … } \endcode - + \sa PRF \sa doPRF \sa DeriveTlsKeys @@ -10988,66 +10988,66 @@ int wolfSSL_DeriveTlsKeys(unsigned char* key_data, unsigned int keyLen, int tls1_2, int hash_type); /*! - \brief wolfSSL_connect_ex() is an extension that allows - a HandShake Callback to be set. This can be useful in - embedded systems for debugging support when a debugger isn’t - available and sniffing is impractical. The HandShake Callback - will be called whether or not a handshake error occurred. - No dynamic memory is used since the maximum number of SSL + \brief wolfSSL_connect_ex() is an extension that allows + a HandShake Callback to be set. This can be useful in + embedded systems for debugging support when a debugger isn’t + available and sniffing is impractical. The HandShake Callback + will be called whether or not a handshake error occurred. + No dynamic memory is used since the maximum number of SSL packets is known. Packet names can be accessed through packetNames[]. - The connect extension also allows a Timeout Callback to be set along - with a timeout value. This is useful if the user doesn’t want - to wait for the TCP stack to timeout. This extension can be called + The connect extension also allows a Timeout Callback to be set along + with a timeout value. This is useful if the user doesn’t want + to wait for the TCP stack to timeout. This extension can be called with either, both, or neither callbacks. - + \return SSL_SUCCESS upon success. - \return GETTIME_ERROR will be returned if gettimeofday() + \return GETTIME_ERROR will be returned if gettimeofday() encountered an error. - \return SETITIMER_ERROR will be returned if setitimer() + \return SETITIMER_ERROR will be returned if setitimer() encountered an error. \return SIGACT_ERROR will be returned if sigaction() encountered an error. - \return SSL_FATAL_ERROR will be returned if the underlying SSL_connect() + \return SSL_FATAL_ERROR will be returned if the underlying SSL_connect() call encountered an error. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_accept_ex */ WOLFSSL_API int wolfSSL_connect_ex(WOLFSSL*, HandShakeCallBack, TimeoutCallBack, Timeval); /*! - \brief wolfSSL_accept_ex() is an extension that allows a HandShake Callback - to be set. This can be useful in embedded systems for debugging support - when a debugger isn’t available and sniffing is impractical. The HandShake - Callback will be called whether or not a handshake error occurred. + \brief wolfSSL_accept_ex() is an extension that allows a HandShake Callback + to be set. This can be useful in embedded systems for debugging support + when a debugger isn’t available and sniffing is impractical. The HandShake + Callback will be called whether or not a handshake error occurred. No dynamic memory is used since the maximum number of SSL packets is known. - Packet names can be accessed through packetNames[]. The connect extension - also allows a Timeout Callback to be set along with a timeout value. + Packet names can be accessed through packetNames[]. The connect extension + also allows a Timeout Callback to be set along with a timeout value. This is useful if the user doesn’t want to wait for the TCP stack to timeout. This extension can be called with either, both, or neither callbacks. - + \return SSL_SUCCESS upon success. - \return GETTIME_ERROR will be returned if gettimeofday() + \return GETTIME_ERROR will be returned if gettimeofday() encountered an error. - \return SETITIMER_ERROR will be returned if setitimer() + \return SETITIMER_ERROR will be returned if setitimer() encountered an error. \return SIGACT_ERROR will be returned if sigaction() encountered an error. - \return SSL_FATAL_ERROR will be returned if the underlying + \return SSL_FATAL_ERROR will be returned if the underlying SSL_accept() call encountered an error. - + \param none No parameters. - + _Example_ \code none \endcode - + \sa wolfSSL_connect_ex */ WOLFSSL_API int wolfSSL_accept_ex(WOLFSSL*, HandShakeCallBack, TimeoutCallBack, @@ -11055,16 +11055,16 @@ WOLFSSL_API int wolfSSL_accept_ex(WOLFSSL*, HandShakeCallBack, TimeoutCallBack, /*! \ingroup IO - + \brief This is used to set the internal file pointer for a BIO. - + \return SSL_SUCCESS On successfully setting file pointer. \return SSL_FAILURE If an error case was encountered. - + \param bio WOLFSSL_BIO structure to set pair. \param fp file pointer to set in bio. \param c close file behavior flag. - + _Example_ \code WOLFSSL_BIO* bio; @@ -11074,7 +11074,7 @@ WOLFSSL_API int wolfSSL_accept_ex(WOLFSSL*, HandShakeCallBack, TimeoutCallBack, ret = wolfSSL_BIO_set_fp(bio, fp, BIO_CLOSE); // check ret value \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_s_mem \sa wolfSSL_BIO_get_fp @@ -11086,10 +11086,10 @@ WOLFSSL_API long wolfSSL_BIO_set_fp(WOLFSSL_BIO *bio, XFILE fp, int c); \ingroup IO \brief This is used to get the internal file pointer for a BIO. - + \return SSL_SUCCESS On successfully getting file pointer. \return SSL_FAILURE If an error case was encountered. - + \param bio WOLFSSL_BIO structure to set pair. \param fp file pointer to set in bio. @@ -11102,7 +11102,7 @@ WOLFSSL_API long wolfSSL_BIO_set_fp(WOLFSSL_BIO *bio, XFILE fp, int c); ret = wolfSSL_BIO_get_fp(bio, &fp); // check ret value \endcode - + \sa wolfSSL_BIO_new \sa wolfSSL_BIO_s_mem \sa wolfSSL_BIO_set_fp @@ -11113,15 +11113,15 @@ WOLFSSL_API long wolfSSL_BIO_get_fp(WOLFSSL_BIO *bio, XFILE* fp); /*! \ingroup Setup - \brief This function checks that the private key is a match + \brief This function checks that the private key is a match with the certificate being used. - + \return SSL_SUCCESS On successfully match. \return SSL_FAILURE If an error case was encountered. \return <0 All error cases other than SSL_FAILURE are negative values. \param ssl WOLFSSL structure to check. - + _Example_ \code WOLFSSL* ssl; @@ -11130,7 +11130,7 @@ WOLFSSL_API long wolfSSL_BIO_get_fp(WOLFSSL_BIO *bio, XFILE* fp); ret = wolfSSL_check_private_key(ssl); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -11139,20 +11139,20 @@ WOLFSSL_API int wolfSSL_check_private_key(const WOLFSSL* ssl); /*! \ingroup CertsKeys - \brief This function looks for and returns the extension + \brief This function looks for and returns the extension matching the passed in NID value. - - \return pointer If successful a STACK_OF(WOLFSSL_ASN1_OBJECT) + + \return pointer If successful a STACK_OF(WOLFSSL_ASN1_OBJECT) pointer is returned. \return NULL If extension is not found or error is encountered. - + \param x509 certificate to get parse through for extension. \param nid extension OID to be found. - \param c if not NULL is set to -2 for multiple extensions found -1 + \param c if not NULL is set to -2 for multiple extensions found -1 if not found, 0 if found and not critical and 1 if found and critical. - \param idx if NULL return first extension matched otherwise if not + \param idx if NULL return first extension matched otherwise if not stored in x509 start at idx. - + _Example_ \code const WOLFSSL_X509* x509; @@ -11163,7 +11163,7 @@ WOLFSSL_API int wolfSSL_check_private_key(const WOLFSSL* ssl); sk = wolfSSL_X509_get_ext_d2i(x509, NID_basic_constraints, &c, &idx); //check sk for NULL and then use it. sk needs freed after done. \endcode - + \sa wolfSSL_sk_ASN1_OBJECT_free */ WOLFSSL_API void* wolfSSL_X509_get_ext_d2i(const WOLFSSL_X509* x509, @@ -11173,15 +11173,15 @@ WOLFSSL_API void* wolfSSL_X509_get_ext_d2i(const WOLFSSL_X509* x509, \ingroup CertsKeys \brief This function returns the hash of the DER certificate. - + \return SSL_SUCCESS On successfully creating a hash. \return SSL_FAILURE Returned on bad input or unsuccessful hash. - + \param x509 certificate to get the hash of. \param digest the hash algorithm to use. \param buf buffer to hold hash. \param len length of buffer. - + _Example_ \code WOLFSSL_X509* x509; @@ -11192,7 +11192,7 @@ WOLFSSL_API void* wolfSSL_X509_get_ext_d2i(const WOLFSSL_X509* x509, ret = wolfSSL_X509_digest(x509, wolfSSL_EVP_sha256(), buffer, &bufferSz); //check ret value \endcode - + \sa none */ WOLFSSL_API int wolfSSL_X509_digest(const WOLFSSL_X509* x509, @@ -11201,15 +11201,15 @@ WOLFSSL_API int wolfSSL_X509_digest(const WOLFSSL_X509* x509, /*! \ingroup Setup - \brief his is used to set the certificate for WOLFSSL structure to use + \brief his is used to set the certificate for WOLFSSL structure to use during a handshake. - + \return SSL_SUCCESS On successful setting argument. \return SSL_FAILURE If a NULL argument passed in. - + \param ssl WOLFSSL structure to set certificate in. \param x509 certificate to use. - + _Example_ \code WOLFSSL* ssl; WOLFSSL_X509* x509 @@ -11218,7 +11218,7 @@ WOLFSSL_API int wolfSSL_X509_digest(const WOLFSSL_X509* x509, ret = wolfSSL_use_certificate(ssl, x509); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -11227,16 +11227,16 @@ WOLFSSL_API int wolfSSL_use_certificate(WOLFSSL* ssl, WOLFSSL_X509* x509); /*! \ingroup Setup - \brief This is used to set the certificate for WOLFSSL structure + \brief This is used to set the certificate for WOLFSSL structure to use during a handshake. A DER formatted buffer is expected. - + \return SSL_SUCCESS On successful setting argument. \return SSL_FAILURE If a NULL argument passed in. - + \param ssl WOLFSSL structure to set certificate in. \param der DER certificate to use. \param derSz size of the DER buffer passed in. - + _Example_ \code WOLFSSL* ssl; @@ -11247,7 +11247,7 @@ WOLFSSL_API int wolfSSL_use_certificate(WOLFSSL* ssl, WOLFSSL_X509* x509); ret = wolfSSL_use_certificate_ASN1(ssl, der, derSz); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -11258,14 +11258,14 @@ WOLFSSL_API int wolfSSL_use_certificate_ASN1(WOLFSSL* ssl, unsigned char* der, \ingroup CertsKeys \brief This is used to set the private key for the WOLFSSL structure. - + \return SSL_SUCCESS On successful setting argument. - \return SSL_FAILURE If a NULL ssl passed in. All error + \return SSL_FAILURE If a NULL ssl passed in. All error cases will be negative values. - + \param ssl WOLFSSL structure to set argument in. \param pkey private key to use. - + _Example_ \code WOLFSSL* ssl; @@ -11275,28 +11275,28 @@ WOLFSSL_API int wolfSSL_use_certificate_ASN1(WOLFSSL* ssl, unsigned char* der, ret = wolfSSL_use_PrivateKey(ssl, pkey); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free -*/ +*/ WOLFSSL_API int wolfSSL_use_PrivateKey(WOLFSSL* ssl, WOLFSSL_EVP_PKEY* pkey); /*! \ingroup CertsKeys - \brief This is used to set the private key for the WOLFSSL + \brief This is used to set the private key for the WOLFSSL structure. A DER formatted key buffer is expected. - - \return SSL_SUCCESS On successful setting parsing and + + \return SSL_SUCCESS On successful setting parsing and setting the private key. - \return SSL_FAILURE If an NULL ssl passed in. All error cases + \return SSL_FAILURE If an NULL ssl passed in. All error cases will be negative values. - + \param pri type of private key. \param ssl WOLFSSL structure to set argument in. \param der buffer holding DER key. \param derSz size of der buffer. - + _Example_ \code WOLFSSL* ssl; @@ -11307,7 +11307,7 @@ WOLFSSL_API int wolfSSL_use_PrivateKey(WOLFSSL* ssl, WOLFSSL_EVP_PKEY* pkey); ret = wolfSSL_use_PrivateKey_ASN1(1, ssl, pkey, pkeySz); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free \sa wolfSSL_use_PrivateKey @@ -11318,18 +11318,18 @@ WOLFSSL_API int wolfSSL_use_PrivateKey_ASN1(int pri, WOLFSSL* ssl, /*! \ingroup CertsKeys - \brief This is used to set the private key for the WOLFSSL + \brief This is used to set the private key for the WOLFSSL structure. A DER formatted RSA key buffer is expected. - - \return SSL_SUCCESS On successful setting parsing and setting + + \return SSL_SUCCESS On successful setting parsing and setting the private key. - \return SSL_FAILURE If an NULL ssl passed in. All error cases + \return SSL_FAILURE If an NULL ssl passed in. All error cases will be negative values. - + \param ssl WOLFSSL structure to set argument in. \param der buffer holding DER key. \param derSz size of der buffer. - + _Example_ \code WOLFSSL* ssl; @@ -11340,7 +11340,7 @@ WOLFSSL_API int wolfSSL_use_PrivateKey_ASN1(int pri, WOLFSSL* ssl, ret = wolfSSL_use_RSAPrivateKey_ASN1(ssl, pkey, pkeySz); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free \sa wolfSSL_use_PrivateKey @@ -11351,14 +11351,14 @@ WOLFSSL_API int wolfSSL_use_RSAPrivateKey_ASN1(WOLFSSL* ssl, unsigned char* der, /*! \ingroup CertsKeys - \brief This function duplicates the parameters in dsa to a + \brief This function duplicates the parameters in dsa to a newly created WOLFSSL_DH structure. - + \return WOLFSSL_DH If duplicated returns WOLFSSL_DH structure \return NULL upon failure - + \param dsa WOLFSSL_DSA structure to duplicate. - + _Example_ \code WOLFSSL_DH* dh; @@ -11368,7 +11368,7 @@ WOLFSSL_API int wolfSSL_use_RSAPrivateKey_ASN1(WOLFSSL* ssl, unsigned char* der, // check dh is not null \endcode - + \sa none */ WOLFSSL_API WOLFSSL_DH *wolfSSL_DSA_dup_DH(const WOLFSSL_DSA *r); @@ -11377,17 +11377,17 @@ WOLFSSL_API WOLFSSL_DH *wolfSSL_DSA_dup_DH(const WOLFSSL_DSA *r); \ingroup Setup \brief This is used to get the master key after completing a handshake. - + \return >0 On successfully getting data returns a value greater than 0 \return 0 If no random data buffer or an error state returns 0 - \return max If outSz passed in is 0 then the maximum buffer + \return max If outSz passed in is 0 then the maximum buffer size needed is returned - + \param ses WOLFSSL_SESSION structure to get master secret buffer from. \param out buffer to hold data. - \param outSz size of out buffer passed in. (if 0 function will + \param outSz size of out buffer passed in. (if 0 function will return max buffer size needed) - + _Example_ \code WOLFSSL_SESSION ssl; @@ -11400,7 +11400,7 @@ WOLFSSL_API WOLFSSL_DH *wolfSSL_DSA_dup_DH(const WOLFSSL_DSA *r); ret = wolfSSL_SESSION_get_master_secret(ses, buffer, bufferSz); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -11411,11 +11411,11 @@ WOLFSSL_API int wolfSSL_SESSION_get_master_key(const WOLFSSL_SESSION* ses, \ingroup Setup \brief This is used to get the master secret key length. - + \return size Returns master secret key size. - + \param ses WOLFSSL_SESSION structure to get master secret buffer from. - + _Example_ \code WOLFSSL_SESSION ssl; @@ -11427,7 +11427,7 @@ WOLFSSL_API int wolfSSL_SESSION_get_master_key(const WOLFSSL_SESSION* ses, buffer = malloc(bufferSz); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -11436,15 +11436,15 @@ WOLFSSL_API int wolfSSL_SESSION_get_master_key_length(const WOLFSSL_SESSION* ses /*! \ingroup Setup - \brief This is a setter function for the WOLFSSL_X509_STORE + \brief This is a setter function for the WOLFSSL_X509_STORE structure in ctx. - + \return none No return. - - \param ctx pointer to the WOLFSSL_CTX structure for setting + + \param ctx pointer to the WOLFSSL_CTX structure for setting cert store pointer. \param str pointer to the WOLFSSL_X509_STORE to set in ctx. - + _Example_ \code WOLFSSL_CTX ctx; @@ -11453,7 +11453,7 @@ WOLFSSL_API int wolfSSL_SESSION_get_master_key_length(const WOLFSSL_SESSION* ses st = wolfSSL_CTX_set_cert_store(ctx, st); //use st \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_free */ @@ -11463,16 +11463,16 @@ WOLFSSL_API void wolfSSL_CTX_set_cert_store(WOLFSSL_CTX* ctx, /*! \ingroup CertsKeys - \brief This function get the DER buffer from bio and converts it + \brief This function get the DER buffer from bio and converts it to a WOLFSSL_X509 structure. - + \return pointer returns a WOLFSSL_X509 structure pointer on success. \return Null returns NULL on failure - - \param bio pointer to the WOLFSSL_BIO structure that has the DER + + \param bio pointer to the WOLFSSL_BIO structure that has the DER certificate buffer. \param x509 pointer that get set to new WOLFSSL_X509 structure created. - + _Example_ \code WOLFSSL_BIO* bio; @@ -11483,7 +11483,7 @@ WOLFSSL_API void wolfSSL_CTX_set_cert_store(WOLFSSL_CTX* ctx, wolfSSL_d2i_X509_bio(bio, &x509); // use x509 returned (check for NULL) \endcode - + \sa none */ WOLFSSL_X509* wolfSSL_d2i_X509_bio(WOLFSSL_BIO* bio, WOLFSSL_X509** x509); @@ -11491,15 +11491,15 @@ WOLFSSL_X509* wolfSSL_d2i_X509_bio(WOLFSSL_BIO* bio, WOLFSSL_X509** x509); /*! \ingroup Setup - \brief This is a getter function for the WOLFSSL_X509_STORE + \brief This is a getter function for the WOLFSSL_X509_STORE structure in ctx. - + \return WOLFSSL_X509_STORE* On successfully getting the pointer. \return NULL Returned if NULL arguments are passed in. - - \param ctx pointer to the WOLFSSL_CTX structure for getting cert + + \param ctx pointer to the WOLFSSL_CTX structure for getting cert store pointer. - + _Example_ \code WOLFSSL_CTX ctx; @@ -11508,7 +11508,7 @@ WOLFSSL_X509* wolfSSL_d2i_X509_bio(WOLFSSL_BIO* bio, WOLFSSL_X509** x509); st = wolfSSL_CTX_get_cert_store(ctx); //use st \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_free \sa wolfSSL_CTX_set_cert_store @@ -11518,16 +11518,16 @@ WOLFSSL_API WOLFSSL_X509_STORE* wolfSSL_CTX_get_cert_store(WOLFSSL_CTX* ctx); /*! \ingroup IO - \brief Gets the number of pending bytes to read. If BIO type is BIO_BIO - then is the number to read from pair. If BIO contains an SSL object then - is pending data from SSL object (wolfSSL_pending(ssl)). If is BIO_MEMORY + \brief Gets the number of pending bytes to read. If BIO type is BIO_BIO + then is the number to read from pair. If BIO contains an SSL object then + is pending data from SSL object (wolfSSL_pending(ssl)). If is BIO_MEMORY type then returns the size of memory buffer. - + \return >=0 number of pending bytes. - - \param bio pointer to the WOLFSSL_BIO structure that has already + + \param bio pointer to the WOLFSSL_BIO structure that has already been created. - + _Example_ \code WOLFSSL_BIO* bio; @@ -11536,7 +11536,7 @@ WOLFSSL_API WOLFSSL_X509_STORE* wolfSSL_CTX_get_cert_store(WOLFSSL_CTX* ctx); … pending = wolfSSL_BIO_ctrl_pending(bio); \endcode - + \sa wolfSSL_BIO_make_bio_pair \sa wolfSSL_BIO_new */ @@ -11545,19 +11545,19 @@ WOLFSSL_API size_t wolfSSL_BIO_ctrl_pending(WOLFSSL_BIO *b); /*! \ingroup Setup - \brief This is used to get the random data sent by the server + \brief This is used to get the random data sent by the server during the handshake. - + \return >0 On successfully getting data returns a value greater than 0 \return 0 If no random data buffer or an error state returns 0 - \return max If outSz passed in is 0 then the maximum buffer size + \return max If outSz passed in is 0 then the maximum buffer size needed is returned - + \param ssl WOLFSSL structure to get clients random data buffer from. \param out buffer to hold random data. - \param outSz size of out buffer passed in. (if 0 function will return max + \param outSz size of out buffer passed in. (if 0 function will return max buffer size needed) - + _Example_ \code WOLFSSL ssl; @@ -11569,7 +11569,7 @@ WOLFSSL_API size_t wolfSSL_BIO_ctrl_pending(WOLFSSL_BIO *b); ret = wolfSSL_get_server_random(ssl, buffer, bufferSz); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -11579,19 +11579,19 @@ WOLFSSL_API size_t wolfSSL_get_server_random(const WOLFSSL *ssl, /*! \ingroup Setup - \brief This is used to get the random data sent by the client during + \brief This is used to get the random data sent by the client during the handshake. - + \return >0 On successfully getting data returns a value greater than 0 \return 0 If no random data buffer or an error state returns 0 - \return max If outSz passed in is 0 then the maximum buffer size needed + \return max If outSz passed in is 0 then the maximum buffer size needed is returned - + \param ssl WOLFSSL structure to get clients random data buffer from. \param out buffer to hold random data. - \param outSz size of out buffer passed in. (if 0 function will return max + \param outSz size of out buffer passed in. (if 0 function will return max buffer size needed) - + _Example_ \code WOLFSSL ssl; @@ -11603,7 +11603,7 @@ WOLFSSL_API size_t wolfSSL_get_server_random(const WOLFSSL *ssl, ret = wolfSSL_get_client_random(ssl, buffer, bufferSz); // check ret value \endcode - + \sa wolfSSL_new \sa wolfSSL_free */ @@ -11614,12 +11614,12 @@ WOLFSSL_API size_t wolfSSL_get_client_random(const WOLFSSL* ssl, \ingroup Setup \brief This is a getter function for the password callback set in ctx. - + \return func On success returns the callback function. \return NULL If ctx is NULL then NULL is returned. - + \param ctx WOLFSSL_CTX structure to get call back from. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -11628,7 +11628,7 @@ WOLFSSL_API size_t wolfSSL_get_client_random(const WOLFSSL* ssl, cb = wolfSSL_CTX_get_default_passwd_cb(ctx); //use cb \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_free */ @@ -11637,14 +11637,14 @@ WOLFSSL_API pem_password_cb* wolfSSL_CTX_get_default_passwd_cb(WOLFSSL_CTX *ctx) /*! \ingroup Setup - \brief This is a getter function for the password callback user + \brief This is a getter function for the password callback user data set in ctx. - + \return pointer On success returns the user data pointer. \return NULL If ctx is NULL then NULL is returned. - + \param ctx WOLFSSL_CTX structure to get user data from. - + _Example_ \code WOLFSSL_CTX* ctx; @@ -11653,7 +11653,7 @@ WOLFSSL_API pem_password_cb* wolfSSL_CTX_get_default_passwd_cb(WOLFSSL_CTX *ctx) data = wolfSSL_CTX_get_default_passwd_cb(ctx); //use data \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_CTX_free */ @@ -11663,18 +11663,18 @@ WOLFSSL_API void *wolfSSL_CTX_get_default_passwd_cb_userdata(WOLFSSL_CTX *ctx); \ingroup CertsKeys \brief This function behaves the same as wolfSSL_PEM_read_bio_X509. - AUX signifies containing extra information such as trusted/rejected use + AUX signifies containing extra information such as trusted/rejected use cases and friendly name for human readability. - - \return WOLFSSL_X509 on successfully parsing the PEM buffer a WOLFSSL_X509 + + \return WOLFSSL_X509 on successfully parsing the PEM buffer a WOLFSSL_X509 structure is returned. \return Null if failed to parse PEM buffer. - + \param bp WOLFSSL_BIO structure to get PEM buffer from. \param x if setting WOLFSSL_X509 by function side effect. \param cb password callback. \param u NULL terminated user password. - + _Example_ \code WOLFSSL_BIO* bio; @@ -11683,7 +11683,7 @@ WOLFSSL_API void *wolfSSL_CTX_get_default_passwd_cb_userdata(WOLFSSL_CTX *ctx); X509 = wolfSSL_PEM_read_bio_X509_AUX(bio, NULL, NULL, NULL); //check x509 is not null and then use it \endcode - + \sa wolfSSL_PEM_read_bio_X509 */ WOLFSSL_API WOLFSSL_X509 *wolfSSL_PEM_read_bio_X509_AUX @@ -11692,19 +11692,19 @@ WOLFSSL_API WOLFSSL_X509 *wolfSSL_PEM_read_bio_X509_AUX /*! \ingroup CertsKeys - \brief Initializes the WOLFSSL_CTX structure’s dh member with the + \brief Initializes the WOLFSSL_CTX structure’s dh member with the Diffie-Hellman parameters. - + \return SSL_SUCCESS returned if the function executed successfully. \return BAD_FUNC_ARG returned if the ctx or dh structures are NULL. - \return SSL_FATAL_ERROR returned if there was an error setting a + \return SSL_FATAL_ERROR returned if there was an error setting a structure value. \return MEMORY_E returned if their was a failure to allocate memory. - - \param ctx a pointer to a WOLFSSL_CTX structure, created using + + \param ctx a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new(). \param dh a pointer to a WOLFSSL_DH structure. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -11712,7 +11712,7 @@ WOLFSSL_API WOLFSSL_X509 *wolfSSL_PEM_read_bio_X509_AUX … return wolfSSL_CTX_set_tmp_dh(ctx, dh); \endcode - + \sa wolfSSL_BN_bn2bin */ WOLFSSL_API long wolfSSL_CTX_set_tmp_dh(WOLFSSL_CTX*, WOLFSSL_DH*); @@ -11721,17 +11721,17 @@ WOLFSSL_API long wolfSSL_CTX_set_tmp_dh(WOLFSSL_CTX*, WOLFSSL_DH*); \ingroup CertsKeys \brief This function get the DSA parameters from a PEM buffer in bio. - - \return WOLFSSL_DSA on successfully parsing the PEM buffer a WOLFSSL_DSA - structure is created and returned. + + \return WOLFSSL_DSA on successfully parsing the PEM buffer a WOLFSSL_DSA + structure is created and returned. \return Null if failed to parse PEM buffer. - - \param bio pointer to the WOLFSSL_BIO structure for getting PEM + + \param bio pointer to the WOLFSSL_BIO structure for getting PEM memory pointer. \param x pointer to be set to new WOLFSSL_DSA structure. \param cb password callback function. \param u null terminated password string. - + _Example_ \code WOLFSSL_BIO* bio; @@ -11741,7 +11741,7 @@ WOLFSSL_API long wolfSSL_CTX_set_tmp_dh(WOLFSSL_CTX*, WOLFSSL_DH*); // check dsa is not NULL and then use dsa \endcode - + \sa none */ WOLFSSL_API WOLFSSL_DSA *wolfSSL_PEM_read_bio_DSAparams(WOLFSSL_BIO *bp, @@ -11750,13 +11750,13 @@ WOLFSSL_API WOLFSSL_DSA *wolfSSL_PEM_read_bio_DSAparams(WOLFSSL_BIO *bp, /*! \ingroup Debug - \brief This function returns the absolute value of the last error from + \brief This function returns the absolute value of the last error from WOLFSSL_ERROR encountered. - + \return error Returns absolute value of last error. - + \param none No parameters. - + _Example_ \code unsigned long err; @@ -11764,7 +11764,7 @@ WOLFSSL_API WOLFSSL_DSA *wolfSSL_PEM_read_bio_DSAparams(WOLFSSL_BIO *bp, err = wolfSSL_ERR_peek_last_error(); // inspect err value \endcode - + \sa wolfSSL_ERR_print_errors_fp */ WOLFSSL_API unsigned long wolfSSL_ERR_peek_last_error(void); @@ -11773,12 +11773,12 @@ WOLFSSL_API unsigned long wolfSSL_ERR_peek_last_error(void); \ingroup CertsKeys \brief This function gets the peer’s certificate chain. - + \return pointer returns a pointer to the peer’s Certificate stack. \return NULL returned if no peer certificate. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -11790,7 +11790,7 @@ WOLFSSL_API unsigned long wolfSSL_ERR_peek_last_error(void); // You have a pointer to the peer certificate chain } \endcode - + \sa wolfSSL_X509_get_issuer_name \sa wolfSSL_X509_get_subject_name \sa wolfSSL_X509_get_isCA @@ -11801,18 +11801,18 @@ WOLFSSL_API WOLF_STACK_OF(WOLFSSL_X509)* wolfSSL_get_peer_cert_chain(const WOLFS \ingroup Setup \brief This function resets option bits of WOLFSSL_CTX object. - + \return option new option bits - + \param ctx pointer to the SSL context. - + _Example_ \code WOLFSSL_CTX* ctx = 0; ... wolfSSL_CTX_clear_options(ctx, SSL_OP_NO_TLSv1); \endcode - + \sa wolfSSL_CTX_new \sa wolfSSL_new \sa wolfSSL_free @@ -11823,25 +11823,25 @@ WOLFSSL_API long wolfSSL_CTX_clear_options(WOLFSSL_CTX*, long); \ingroup IO \brief This function sets the jObjectRef member of the WOLFSSL structure. - + \return SSL_SUCCESS returned if jObjectRef is properly set to objPtr. - \return SSL_FAILURE returned if the function did not properly execute and + \return SSL_FAILURE returned if the function did not properly execute and jObjectRef is not set. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param objPtr a void pointer that will be set to jObjectRef. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); WOLFSSL* ssl = WOLFSSL_new(); void* objPtr = &obj; ... - if(wolfSSL_set_jobject(ssl, objPtr)){ + if(wolfSSL_set_jobject(ssl, objPtr)){ // The success case } \endcode - + \sa wolfSSL_get_jobject */ WOLFSSL_API int wolfSSL_set_jobject(WOLFSSL* ssl, void* objPtr); @@ -11850,13 +11850,13 @@ WOLFSSL_API int wolfSSL_set_jobject(WOLFSSL* ssl, void* objPtr); \ingroup IO \brief This function returns the jObjectRef member of the WOLFSSL structure. - - \return value If the WOLFSSL struct is not NULL, the function returns the + + \return value If the WOLFSSL struct is not NULL, the function returns the jObjectRef value. \return NULL returned if the WOLFSSL struct is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -11868,7 +11868,7 @@ WOLFSSL_API int wolfSSL_set_jobject(WOLFSSL* ssl, void* objPtr); // Success case } \endcode - + \sa wolfSSL_set_jobject */ WOLFSSL_API void* wolfSSL_get_jobject(WOLFSSL* ssl); @@ -11876,14 +11876,14 @@ WOLFSSL_API void* wolfSSL_get_jobject(WOLFSSL* ssl); /*! \ingroup Setup - \brief This function sets a callback in the ssl. The callback is to + \brief This function sets a callback in the ssl. The callback is to observe handshake messages. NULL value of cb resets the callback. - + \return SSL_SUCCESS On success. \return SSL_FAILURE If an NULL ssl passed in. - + \param ssl WOLFSSL structure to set callback argument. - + _Example_ \code static cb(int write_p, int version, int content_type, @@ -11893,7 +11893,7 @@ WOLFSSL_API void* wolfSSL_get_jobject(WOLFSSL* ssl); ret = wolfSSL_set_msg_callback(ssl, cb); // check ret \endcode - + \sa wolfSSL_set_msg_callback_arg */ WOLFSSL_API int wolfSSL_set_msg_callback(WOLFSSL *ssl, SSL_Msg_Cb cb); @@ -11901,13 +11901,13 @@ WOLFSSL_API int wolfSSL_set_msg_callback(WOLFSSL *ssl, SSL_Msg_Cb cb); /*! \ingroup Setup - \brief This function sets associated callback context value in the ssl. + \brief This function sets associated callback context value in the ssl. The value is handed over to the callback argument. - + \return none No return. - + \param ssl WOLFSSL structure to set callback argument. - + _Example_ \code static cb(int write_p, int version, int content_type, @@ -11918,22 +11918,22 @@ WOLFSSL_API int wolfSSL_set_msg_callback(WOLFSSL *ssl, SSL_Msg_Cb cb); // check ret wolfSSL_set_msg_callback(ssl, arg); \endcode - + \sa wolfSSL_set_msg_callback */ WOLFSSL_API int wolfSSL_set_msg_callback_arg(WOLFSSL *ssl, void* arg); /*! \ingroup CertsKeys - + \brief This function returns the next, if any, altname from the peer certificate. - + \return NULL if there is not a next altname. - \return cert->altNamesNext->name from the WOLFSSL_X509 structure that is a + \return cert->altNamesNext->name from the WOLFSSL_X509 structure that is a string value from the altName list is returned if it exists. - + \param cert a pointer to the wolfSSL_X509 structure. - + _Example_ \code WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, @@ -11944,7 +11944,7 @@ WOLFSSL_API int wolfSSL_set_msg_callback_arg(WOLFSSL *ssl, void* arg); //There isn’t another alt name } \endcode - + \sa wolfSSL_X509_get_issuer_name \sa wolfSSL_X509_get_subject_name */ @@ -11952,16 +11952,16 @@ WOLFSSL_API char* wolfSSL_X509_get_next_altname(WOLFSSL_X509*); /*! \ingroup CertsKeys - - \brief The function checks to see if x509 is NULL and if it’s not, it + + \brief The function checks to see if x509 is NULL and if it’s not, it returns the notBefore member of the x509 struct. - - \return pointer This function returns a constant byte pointer to the x509’s + + \return pointer This function returns a constant byte pointer to the x509’s member notAfter. \return NULL the function returns NULL if the x509 structure is NULL. - + \param x509 a pointer to the WOLFSSL_X509 struct. - + _Example_ \code WOLFSSL_X509* x509 = (WOLFSSL_X509)XMALLOC(sizeof(WOLFSSL_X509), NULL, @@ -11972,14 +11972,14 @@ WOLFSSL_API char* wolfSSL_X509_get_next_altname(WOLFSSL_X509*); //The x509 object was NULL } \endcode - + \sa wolfSSL_X509_notAfter */ WOLFSSL_API const unsigned char* wolfSSL_X509_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. @@ -11987,9 +11987,9 @@ wolfSSL takes a different approach to certificate verification than OpenSSL does \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(). - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code int ret = 0; @@ -12003,7 +12003,7 @@ wolfSSL takes a different approach to certificate verification than OpenSSL does printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); } \endcode - + \sa wolfSSL_get_error \sa wolfSSL_accept */ diff --git a/doc/dox_comments/header_files/tfm.h b/doc/dox_comments/header_files/tfm.h index 6b99746ca..8e7d5eefc 100644 --- a/doc/dox_comments/header_files/tfm.h +++ b/doc/dox_comments/header_files/tfm.h @@ -1,29 +1,29 @@ /*! \ingroup Math - - \brief This function checks the runtime fastmath settings for the maximum - size of an integer. It is important when a user is using a wolfCrypt - library independently, as the FP_SIZE must match for each library in order - for math to work correctly. This check is defined as - CheckFastMathSettings(), which simply compares CheckRunTimeFastMath + + \brief This function checks the runtime fastmath settings for the maximum + size of an integer. It is important when a user is using a wolfCrypt + library independently, as the FP_SIZE must match for each library in order + for math to work correctly. This check is defined as + CheckFastMathSettings(), which simply compares CheckRunTimeFastMath and FP_SIZE, returning 0 if there is a mismatch, or 1 if they match. - - \return FP_SIZE Returns FP_SIZE, corresponding to the max size + + \return FP_SIZE Returns FP_SIZE, corresponding to the max size available for the math library. - + \param none No parameters. - + _Example_ \code if (CheckFastMathSettings() != 1) { return err_sys("Build vs. runtime fastmath FP_MAX_BITS mismatch\n"); - } + } // This is converted by the preprocessor to: // if ( (CheckRunTimeFastMath() == FP_SIZE) != 1) { // and confirms that the fast math settings match // the compile time settings \endcode - + \sa CheckRunTimeSettings */ WOLFSSL_API word32 CheckRunTimeFastMath(void); diff --git a/doc/dox_comments/header_files/types.h b/doc/dox_comments/header_files/types.h index 7dcf81c8a..99419bb56 100644 --- a/doc/dox_comments/header_files/types.h +++ b/doc/dox_comments/header_files/types.h @@ -1,24 +1,24 @@ /*! \ingroup Memory - - \brief This is not actually a function, but rather a preprocessor macro, - which allows the user to substitute in their own malloc, realloc, and free + + \brief This is not actually a function, but rather a preprocessor macro, + which allows the user to substitute in their own malloc, realloc, and free functions in place of the standard C memory functions. - To use external memory functions, define XMALLOC_USER. This will cause the + To use external memory functions, define XMALLOC_USER. This will cause the memory functions to be replaced by external functions of the form: extern void *XMALLOC(size_t n, void* heap, int type); extern void *XREALLOC(void *p, size_t n, void* heap, int type); extern void XFREE(void *p, void* heap, int type); - To use the basic C memory functions in place of wolfSSL_Malloc, - wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This + To use the basic C memory functions in place of wolfSSL_Malloc, + wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XREALLOC(p, n, h, t) realloc((p), (n)) - If none of these options are selected, the system will default to use - the wolfSSL memory functions. A user can set custom memory functions - through callback hooks, (see wolfSSL_Malloc, - wolfSSL_Realloc, wolfSSL_Free). This option will replace the + If none of these options are selected, the system will default to use + the wolfSSL memory functions. A user can set custom memory functions + through callback hooks, (see wolfSSL_Malloc, + wolfSSL_Realloc, wolfSSL_Free). This option will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));} @@ -50,25 +50,25 @@ WOLFSSL_API void* XMALLOC(size_t n, void* heap, int type); /*! \ingroup Memory - - \brief This is not actually a function, but rather a preprocessor macro, - which allows the user to substitute in their own malloc, realloc, and + + \brief This is not actually a function, but rather a preprocessor macro, + which allows the user to substitute in their own malloc, realloc, and free functions in place of the standard C memory functions. - To use external memory functions, define XMALLOC_USER. This will cause the + To use external memory functions, define XMALLOC_USER. This will cause the memory functions to be replaced by external functions of the form: extern void *XMALLOC(size_t n, void* heap, int type); extern void *XREALLOC(void *p, size_t n, void* heap, int type); extern void XFREE(void *p, void* heap, int type); - To use the basic C memory functions in place of wolfSSL_Malloc, - wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will + To use the basic C memory functions in place of wolfSSL_Malloc, + wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XREALLOC(p, n, h, t) realloc((p), (n)) - If none of these options are selected, the system will default to - use the wolfSSL memory functions. A user can set custom memory - functions through callback hooks, (see wolfSSL_Malloc, - wolfSSL_Realloc, wolfSSL_Free). This option will replace + If none of these options are selected, the system will default to + use the wolfSSL memory functions. A user can set custom memory + functions through callback hooks, (see wolfSSL_Malloc, + wolfSSL_Realloc, wolfSSL_Free). This option will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));} @@ -96,31 +96,31 @@ WOLFSSL_API void* XREALLOC(void *p, size_t n, void* heap, int type); /*! \ingroup Memory - - \brief This is not actually a function, but rather a preprocessor macro, - which allows the user to substitute in their own malloc, realloc, and + + \brief This is not actually a function, but rather a preprocessor macro, + which allows the user to substitute in their own malloc, realloc, and free functions in place of the standard C memory functions. - To use external memory functions, define XMALLOC_USER. This will cause + To use external memory functions, define XMALLOC_USER. This will cause the memory functions to be replaced by external functions of the form: extern void *XMALLOC(size_t n, void* heap, int type); extern void *XREALLOC(void *p, size_t n, void* heap, int type); extern void XFREE(void *p, void* heap, int type); - To use the basic C memory functions in place of wolfSSL_Malloc, - wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This + To use the basic C memory functions in place of wolfSSL_Malloc, + wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XREALLOC(p, n, h, t) realloc((p), (n)) - If none of these options are selected, the system will default to use - the wolfSSL memory functions. A user can set custom memory functions - through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc, + If none of these options are selected, the system will default to use + the wolfSSL memory functions. A user can set custom memory functions + through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free). This option will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));} #define XREALLOC(p, n, h, t) wolfSSL_Realloc((p), (n)) - + \return none No returns. - + \param p pointer to the address to free \param h (used by custom XFREE function) pointer to the heap to use \param t memory allocation types for user hints. See enum in types.h @@ -144,29 +144,29 @@ WOLFSSL_API void XFREE(void *p, void* heap, int type); /*! \ingroup Math - - \brief This function checks the compile time class settings. It is - important when a user is using a wolfCrypt library independently, as - the settings must match between libraries for math to work correctly. - This check is defined as CheckCtcSettings(), which simply compares - CheckRunTimeSettings and CTC_SETTINGS, returning 0 if there is a + + \brief This function checks the compile time class settings. It is + important when a user is using a wolfCrypt library independently, as + the settings must match between libraries for math to work correctly. + This check is defined as CheckCtcSettings(), which simply compares + CheckRunTimeSettings and CTC_SETTINGS, returning 0 if there is a mismatch, or 1 if they match. - + \return settings Returns the runtime CTC_SETTINGS (Compile Time Settings) - + \param none No Parameters. - + _Example_ \code if (CheckCtcSettings() != 1) { return err_sys("Build vs. runtime math mismatch\n"); - } + } // This is converted by the preprocessor to: // if ( (CheckCtcSettings() == CTC_SETTINGS) != 1) { // and will compare whether the compile time class settings // match the current settings \endcode - + \sa CheckRunTimeFastMath */ WOLFSSL_API word32 CheckRunTimeSettings(void); diff --git a/doc/dox_comments/header_files/wc_encrypt.h b/doc/dox_comments/header_files/wc_encrypt.h index 285e45a4e..d5937d6f5 100644 --- a/doc/dox_comments/header_files/wc_encrypt.h +++ b/doc/dox_comments/header_files/wc_encrypt.h @@ -1,42 +1,42 @@ /*! \ingroup AES - \brief Decrypts a cipher from the input buffer in, and places the - resulting plain text in the output buffer out using cipher block - chaining with AES. This function does not require an AES structure - to be initialized. Instead, it takes in a key and an iv - (initialization vector) and uses these to initialize an + \brief Decrypts a cipher from the input buffer in, and places the + resulting plain text in the output buffer out using cipher block + chaining with AES. This function does not require an AES structure + to be initialized. Instead, it takes in a key and an iv + (initialization vector) and uses these to initialize an AES object and then decrypt the cipher text. - + \return 0 On successfully decrypting message \return BAD_ALIGN_E Returned on block align error - \return BAD_FUNC_ARG Returned if key length is invalid or AES object + \return BAD_FUNC_ARG Returned if key length is invalid or AES object is null during AesSetIV - \return MEMORY_E Returned if WOLFSSL_SMALL_STACK is enabled and + \return MEMORY_E Returned if WOLFSSL_SMALL_STACK is enabled and XMALLOC fails to instantiate an AES object. - - \param out pointer to the output buffer in which to store the plain + + \param out pointer to the output buffer in which to store the plain text of the decrypted message - \param in pointer to the input buffer containing cipher text to be + \param in pointer to the input buffer containing cipher text to be decrypted \param inSz size of input message \param key 16, 24, or 32 byte secret key for decryption \param keySz size of key used for decryption - + _Example_ \code int ret = 0; byte key[] = { some 16, 24, or 32 byte key }; byte iv[] = { some 16 byte iv }; - byte cipher[AES_BLOCK_SIZE * n]; //n being a positive integer making + byte cipher[AES_BLOCK_SIZE * n]; //n being a positive integer making cipher some multiple of 16 bytes // fill cipher with cipher text byte plain [AES_BLOCK_SIZE * n]; - if ((ret = wc_AesCbcDecryptWithKey(plain, cipher, AES_BLOCK_SIZE, key, + if ((ret = wc_AesCbcDecryptWithKey(plain, cipher, AES_BLOCK_SIZE, key, AES_BLOCK_SIZE, iv)) != 0 ) { // Decrypt Error } \endcode - + \sa wc_AesSetKey \sa wc_AesSetIV \sa wc_AesCbcEncrypt @@ -48,25 +48,25 @@ WOLFSSL_API int wc_AesCbcDecryptWithKey(byte* out, const byte* in, word32 inSz, /*! \ingroup 3DES - - \brief This function decrypts the input ciphertext, in, and stores the - resulting plaintext in the output buffer, out. It uses DES encryption - with cipher block chaining (CBC) mode. This function is a substitute - for wc_Des_CbcDecrypt, allowing the user to decrypt a message without + + \brief This function decrypts the input ciphertext, in, and stores the + resulting plaintext in the output buffer, out. It uses DES encryption + with cipher block chaining (CBC) mode. This function is a substitute + for wc_Des_CbcDecrypt, allowing the user to decrypt a message without directly instantiating a Des structure. - + \return 0 Returned upon successfully decrypting the given ciphertext - \return MEMORY_E Returned if there is an error allocating space for a + \return MEMORY_E Returned if there is an error allocating space for a Des structure - + \param out pointer to the buffer in which to store the decrypted plaintext \param in pointer to the input buffer containing the encrypted ciphertext \param sz length of the ciphertext to decrypt - \param key pointer to the buffer containing the 8 byte key to use for + \param key pointer to the buffer containing the 8 byte key to use for decryption - \param iv pointer to the buffer containing the 8 byte iv to use for + \param iv pointer to the buffer containing the 8 byte iv to use for decryption. If no iv is provided, the iv defaults to 0 - + _Example_ \code int ret; @@ -76,12 +76,12 @@ WOLFSSL_API int wc_AesCbcDecryptWithKey(byte* out, const byte* in, word32 inSz, byte cipher[] = { // initialize with ciphertext }; byte decoded[sizeof(cipher)]; - if ( wc_Des_CbcDecryptWithKey(decoded, cipher, sizeof(cipher), key, - iv) != 0) { + if ( wc_Des_CbcDecryptWithKey(decoded, cipher, sizeof(cipher), key, + iv) != 0) { // error decrypting message } \endcode - + \sa wc_Des_CbcDecrypt */ WOLFSSL_API int wc_Des_CbcDecryptWithKey(byte* out, @@ -90,15 +90,15 @@ WOLFSSL_API int wc_Des_CbcDecryptWithKey(byte* out, /*! \ingroup 3DES - - \brief This function encrypts the input plaintext, in, and stores the - resulting ciphertext in the output buffer, out. It uses DES encryption - with cipher block chaining (CBC) mode. This function is a substitute - for wc_Des_CbcEncrypt, allowing the user to encrypt a message without + + \brief This function encrypts the input plaintext, in, and stores the + resulting ciphertext in the output buffer, out. It uses DES encryption + with cipher block chaining (CBC) mode. This function is a substitute + for wc_Des_CbcEncrypt, allowing the user to encrypt a message without directly instantiating a Des structure. - + \return 0 Returned after successfully encrypting data. - \return MEMORY_E Returned if there's an error allocating memory for a + \return MEMORY_E Returned if there's an error allocating memory for a Des structure. \return <0 Returned on any error during encryption. @@ -115,11 +115,11 @@ WOLFSSL_API int wc_Des_CbcDecryptWithKey(byte* out, byte in[] = { // Initialize with plaintext }; byte out[sizeof(in)]; if ( wc_Des_CbcEncryptWithKey(&out, in, sizeof(in), key, iv) != 0) - { + { // error encrypting message } \endcode - + \sa wc_Des_CbcDecryptWithKey \sa wc_Des_CbcEncrypt */ @@ -129,24 +129,24 @@ WOLFSSL_API int wc_Des_CbcEncryptWithKey(byte* out, /*! \ingroup 3DES - - \brief This function encrypts the input plaintext, in, and stores - the resulting ciphertext in the output buffer, out. It uses Triple - DES (3DES) encryption with cipher block chaining (CBC) mode. This - function is a substitute for wc_Des3_CbcEncrypt, allowing the user + + \brief This function encrypts the input plaintext, in, and stores + the resulting ciphertext in the output buffer, out. It uses Triple + DES (3DES) encryption with cipher block chaining (CBC) mode. This + function is a substitute for wc_Des3_CbcEncrypt, allowing the user to encrypt a message without directly instantiating a Des3 structure. - + \return 0 Returned after successfully encrypting data. - \return MEMORY_E Returned if there's an error allocating memory for + \return MEMORY_E Returned if there's an error allocating memory for a Des structure. \return <0 Returned on any error during encryption. - + \parma 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. \param iv Initialization vector - + _Example_ \code byte key[] = { // initialize with 8 byte key }; @@ -156,11 +156,11 @@ WOLFSSL_API int wc_Des_CbcEncryptWithKey(byte* out, byte out[sizeof(in)]; if ( wc_Des3_CbcEncryptWithKey(&out, in, sizeof(in), key, iv) != 0) - { + { // error encrypting message } \endcode - + \sa wc_Des3_CbcDecryptWithKey \sa wc_Des_CbcEncryptWithKey \sa wc_Des_CbcDecryptWithKey @@ -171,25 +171,25 @@ WOLFSSL_API int wc_Des3_CbcEncryptWithKey(byte* out, /*! \ingroup 3DES - - \brief This function decrypts the input ciphertext, in, and stores - the resulting plaintext in the output buffer, out. It uses Triple - Des (3DES) encryption with cipher block chaining (CBC) mode. This - function is a substitute for wc_Des3_CbcDecrypt, allowing the user + + \brief This function decrypts the input ciphertext, in, and stores + the resulting plaintext in the output buffer, out. It uses Triple + Des (3DES) encryption with cipher block chaining (CBC) mode. This + function is a substitute for wc_Des3_CbcDecrypt, allowing the user to decrypt a message without directly instantiating a Des3 structure. - + \return 0 Returned upon successfully decrypting the given ciphertext - \return MEMORY_E Returned if there is an error allocating space for + \return MEMORY_E Returned if there is an error allocating space for a Des structure - + \param out pointer to the buffer in which to store the decrypted plaintext \param in pointer to the input buffer containing the encrypted ciphertext \param sz length of the ciphertext to decrypt - \param key pointer to the buffer containing the 24 byte key to use + \param key pointer to the buffer containing the 24 byte key to use for decryption - \param iv pointer to the buffer containing the 8 byte iv to use for + \param iv pointer to the buffer containing the 8 byte iv to use for decryption. If no iv is provided, the iv defaults to 0 - + _Example_ \code int ret; @@ -199,12 +199,12 @@ WOLFSSL_API int wc_Des3_CbcEncryptWithKey(byte* out, byte cipher[] = { // initialize with ciphertext }; byte decoded[sizeof(cipher)]; - if ( wc_Des3_CbcDecryptWithKey(decoded, cipher, sizeof(cipher), - key, iv) != 0) { + if ( wc_Des3_CbcDecryptWithKey(decoded, cipher, sizeof(cipher), + key, iv) != 0) { // error decrypting message } \endcode - + \sa wc_Des3_CbcDecrypt */ WOLFSSL_API int wc_Des3_CbcDecryptWithKey(byte* out, diff --git a/doc/dox_comments/header_files/wc_port.h b/doc/dox_comments/header_files/wc_port.h index e81bd471f..e9529280a 100644 --- a/doc/dox_comments/header_files/wc_port.h +++ b/doc/dox_comments/header_files/wc_port.h @@ -1,13 +1,13 @@ /*! \ingroup wolfCrypt - + \brief Used to initialize resources used by wolfCrypt. - + \return 0 upon success. \return <0 upon failure of init resources. - + \param none No parameters. - + _Example_ \code ... @@ -15,21 +15,21 @@ WOLFSSL_MSG("Error with wolfCrypt_Init call"); } \endcode - + \sa wolfCrypt_Cleanup */ WOLFSSL_API int wolfCrypt_Init(void); /*! \ingroup wolfCrypt - + \brief Used to clean up resources used by wolfCrypt. - + \return 0 upon success. \return <0 upon failure of cleaning up resources. - + \param none No parameters. - + _Example_ \code ... @@ -37,7 +37,7 @@ WOLFSSL_API int wolfCrypt_Init(void); WOLFSSL_MSG("Error with wolfCrypt_Cleanup call"); } \endcode - + \sa wolfCrypt_Init */ WOLFSSL_API int wolfCrypt_Cleanup(void); diff --git a/doc/dox_comments/header_files/wolfio.h b/doc/dox_comments/header_files/wolfio.h index 79d0effcb..99ba827f6 100644 --- a/doc/dox_comments/header_files/wolfio.h +++ b/doc/dox_comments/header_files/wolfio.h @@ -1,27 +1,27 @@ /*! \brief This function is the receive embedded callback. - + \return Success This function returns the number of bytes read. - \return WOLFSSL_CBIO_ERR_WANT_READ returned with a “Would block” message + \return WOLFSSL_CBIO_ERR_WANT_READ returned with a “Would block” message if the last error was SOCKET_EWOULDBLCOK or SOCKET_EAGAIN. \return WOLFSSL_CBIO_ERR_TIMEOUT returned with a “Socket timeout” message. - \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset” + \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset” message if the last error was SOCKET_ECONNRESET. - \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message + \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message if the last error was SOCKET_EINTR. - \return WOLFSSL_CBIO_ERR_WANT_READ returned with a “Connection refused” + \return WOLFSSL_CBIO_ERR_WANT_READ returned with a “Connection refused” messag if the last error was SOCKET_ECONNREFUSED. - \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Connection aborted” + \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Connection aborted” message if the last error was SOCKET_ECONNABORTED. - \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message + \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message if the last error was not specified. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param buf a char pointer representation of the buffer. \param sz the size of the buffer. - \param ctx a void pointer to user registered context. In the default case + \param ctx a void pointer to user registered context. In the default case the ctx is a socket descriptor pointer. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -34,7 +34,7 @@ // There were no bytes read. Failure case. } \endcode - + \sa wolfSSL_dtls_get_current_timeout \sa TranslateReturnCode \sa RECV_FUNCTION @@ -43,36 +43,36 @@ WOLFSSL_API int EmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx); /*! \brief This function is the send embedded callback. - + \return Success This function returns the number of bytes sent. - \return WOLFSSL_CBIO_ERR_WANT_WRITE returned with a “Would block” message + \return WOLFSSL_CBIO_ERR_WANT_WRITE returned with a “Would block” message if the last error was SOCKET_EWOULDBLOCK or SOCKET_EAGAIN. - \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset” + \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset” message if the last error was SOCKET_ECONNRESET. - \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message + \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message if the last error was SOCKET_EINTR. - \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Socket EPIPE” message + \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Socket EPIPE” message if the last error was SOCKET_EPIPE. - \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message + \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message if the last error was not specified. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param buf a char pointer representing the buffer. \param sz the size of the buffer. \param ctx a void pointer to user registered context. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); char* buf; int sz; - void* ctx; + void* ctx; int dSent = EmbedSend(ssl, buf, sz, ctx); if(dSent <= 0){ // No byes sent. Failure case. } \endcode - + \sa TranslateReturnCode \sa SEND_FUNCTION \sa LastError @@ -83,21 +83,21 @@ WOLFSSL_API int EmbedSend(WOLFSSL* ssl, char* buf, int sz, void* ctx); /*! \brief This function is the receive embedded callback. - - \return Success This function returns the nb bytes read if the execution + + \return Success This function returns the nb bytes read if the execution was successful. - \return WOLFSSL_CBIO_ERR_WANT_READ if the connection refused or if a + \return WOLFSSL_CBIO_ERR_WANT_READ if the connection refused or if a ‘would block’ error was thrown in the function. \return WOLFSSL_CBIO_ERR_TIMEOUT returned if the socket timed out. \return WOLFSSL_CBIO_ERR_CONN_RST returned if the connection reset. \return WOLFSSL_CBIO_ERR_ISR returned if the socket was interrupted. \return WOLFSSL_CBIO_ERR_GENERAL returned if there was a general error. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param buf a constant char pointer to the buffer. \param sz an int type representing the size of the buffer. \param ctx a void pointer to the WOLFSSL_CTX context. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); @@ -111,7 +111,7 @@ WOLFSSL_API int EmbedSend(WOLFSSL* ssl, char* buf, int sz, void* ctx); // nb is the number of bytes written and is positive } \endcode - + \sa TranslateReturnCode \sa RECVFROM_FUNCTION \sa Setsockopt @@ -120,25 +120,25 @@ WOLFSSL_API int EmbedReceiveFrom(WOLFSSL* ssl, char* buf, int sz, void*); /*! \brief This function is the send embedded callback. - + \return Success This function returns the number of bytes sent. - \return WOLFSSL_CBIO_ERR_WANT_WRITE returned with a “Would Block” message + \return WOLFSSL_CBIO_ERR_WANT_WRITE returned with a “Would Block” message if the last error was either SOCKET_EWOULDBLOCK or SOCKET_EAGAIN error. - \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset” + \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset” message if the last error was SOCKET_ECONNRESET. - \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message + \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message if the last error was SOCKET_EINTR. - \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Socket EPIPE” message + \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Socket EPIPE” message if the last error was WOLFSSL_CBIO_ERR_CONN_CLOSE. - \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message + \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message if the last error was not specified. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param buf a char pointer representing the buffer. \param sz the size of the buffer. - \param ctx a void pointer to the user registered context. The default case + \param ctx a void pointer to the user registered context. The default case is a WOLFSSL_DTLS_CTX sructure. - + _Example_ \code WOLFSSL* ssl; @@ -152,7 +152,7 @@ WOLFSSL_API int EmbedReceiveFrom(WOLFSSL* ssl, char* buf, int sz, void*); // No bytes sent. Failure case. } \endcode - + \sa LastError \sa EmbedSend \sa EmbedReceive @@ -161,18 +161,18 @@ WOLFSSL_API int EmbedSendTo(WOLFSSL* ssl, char* buf, int sz, void* ctx); /*! \brief This function is the DTLS Generate Cookie callback. - - \return Success This function returns the number of bytes copied + + \return Success This function returns the number of bytes copied into the buffer. - \return GEN_COOKIE_E returned if the getpeername failed in + \return GEN_COOKIE_E returned if the getpeername failed in EmbedGenerateCookie. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param buf byte pointer representing the buffer. It is the destination + \param buf byte pointer representing the buffer. It is the destination from XMEMCPY(). \param sz the size of the buffer. \param ctx a void pointer to user registered context. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -187,7 +187,7 @@ WOLFSSL_API int EmbedSendTo(WOLFSSL* ssl, char* buf, int sz, void* ctx); // EmbedGenerateCookie code block for success } \endcode - + \sa wc_ShaHash \sa EmbedGenerateCookie \sa XMEMCPY @@ -198,12 +198,12 @@ WOLFSSL_API int EmbedGenerateCookie(WOLFSSL* ssl, unsigned char* buf, /*! \brief This function frees the response buffer. - + \return none No returns. - + \param ctx a void pointer to heap hint. \param resp a byte pointer representing the response. - + _Example_ \code void* ctx; @@ -211,27 +211,27 @@ WOLFSSL_API int EmbedGenerateCookie(WOLFSSL* ssl, unsigned char* buf, … EmbedOcspRespFree(ctx, resp); \endcode - + \sa XFREE */ WOLFSSL_API void EmbedOcspRespFree(void*, unsigned char*); /*! - \brief This function registers a receive callback for wolfSSL to get input - data. By default, wolfSSL uses EmbedReceive() as the callback which uses - the system’s TCP recv() function. The user can register a function to get - input from memory, some other network module, or from anywhere. Please see - the EmbedReceive() function in src/io.c as a guide for how the function - should work and for error codes. In particular, IO_ERR_WANT_READ should + \brief This function registers a receive callback for wolfSSL to get input + data. By default, wolfSSL uses EmbedReceive() as the callback which uses + the system’s TCP recv() function. The user can register a function to get + input from memory, some other network module, or from anywhere. Please see + the EmbedReceive() function in src/io.c as a guide for how the function + should work and for error codes. In particular, IO_ERR_WANT_READ should be returned for non blocking receive when no data is ready. - + \return none no Returns. - + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). - \param callback function to be registered as the receive callback for the - wolfSSL context, ctx. The signature of this function must follow that as + \param callback function to be registered as the receive callback for the + wolfSSL context, ctx. The signature of this function must follow that as shown above in the Synopsis section. - + _Example_ \code WOLFSSL_CTX* ctx = 0; @@ -239,12 +239,12 @@ WOLFSSL_API void EmbedOcspRespFree(void*, unsigned char*); int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx); // Register the custom receive callback with wolfSSL wolfSSL_CTX_SetIORecv(ctx, MyEmbedReceive); - int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx) + int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx) { // custom EmbedReceive function } \endcode - + \sa wolfSSL_CTX_SetIOSend \sa wolfSSL_SetIOReadCtx \sa wolfSSL_SetIOWriteCtx @@ -252,20 +252,20 @@ WOLFSSL_API void EmbedOcspRespFree(void*, unsigned char*); WOLFSSL_API void wolfSSL_CTX_SetIORecv(WOLFSSL_CTX*, CallbackIORecv); /*! - \brief This function registers a context for the SSL session’s receive - callback function. By default, wolfSSL sets the file descriptor passed to - wolfSSL_set_fd() as the context when wolfSSL is using the system’s TCP - library. If you’ve registered your own receive callback you may want to set - a specific context for the session. For example, if you’re using memory - buffers the context may be a pointer to a structure describing where and + \brief This function registers a context for the SSL session’s receive + callback function. By default, wolfSSL sets the file descriptor passed to + wolfSSL_set_fd() as the context when wolfSSL is using the system’s TCP + library. If you’ve registered your own receive callback you may want to set + a specific context for the session. For example, if you’re using memory + buffers the context may be a pointer to a structure describing where and how to access the memory buffers. - + \return none No returns. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - \param rctx pointer to the context to be registered with the SSL session’s + \param rctx pointer to the context to be registered with the SSL session’s (ssl) receive callback function. - + _Example_ \code int sockfd; @@ -275,7 +275,7 @@ WOLFSSL_API void wolfSSL_CTX_SetIORecv(WOLFSSL_CTX*, CallbackIORecv); wolfSSL_SetIOReadCtx(ssl, &sockfd); ... \endcode - + \sa wolfSSL_CTX_SetIORecv \sa wolfSSL_CTX_SetIOSend \sa wolfSSL_SetIOWriteCtx @@ -283,20 +283,20 @@ WOLFSSL_API void wolfSSL_CTX_SetIORecv(WOLFSSL_CTX*, CallbackIORecv); WOLFSSL_API void wolfSSL_SetIOReadCtx( WOLFSSL* ssl, void *ctx); /*! - \brief This function registers a context for the SSL session’s send - callback function. By default, wolfSSL sets the file descriptor passed to - wolfSSL_set_fd() as the context when wolfSSL is using the system’s TCP - library. If you’ve registered your own send callback you may want to set a - specific context for the session. For example, if you’re using memory - buffers the context may be a pointer to a structure describing where and + \brief This function registers a context for the SSL session’s send + callback function. By default, wolfSSL sets the file descriptor passed to + wolfSSL_set_fd() as the context when wolfSSL is using the system’s TCP + library. If you’ve registered your own send callback you may want to set a + specific context for the session. For example, if you’re using memory + buffers the context may be a pointer to a structure describing where and how to access the memory buffers. - + \return none No returns. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - \param wctx pointer to the context to be registered with the SSL session’s + \param wctx pointer to the context to be registered with the SSL session’s (ssl) send callback function. - + _Example_ \code int sockfd; @@ -306,7 +306,7 @@ WOLFSSL_API void wolfSSL_SetIOReadCtx( WOLFSSL* ssl, void *ctx); wolfSSL_SetIOWriteCtx(ssl, &sockfd); ... \endcode - + \sa wolfSSL_CTX_SetIORecv \sa wolfSSL_CTX_SetIOSend \sa wolfSSL_SetIOReadCtx @@ -317,13 +317,13 @@ WOLFSSL_API void wolfSSL_SetIOWriteCtx(WOLFSSL* ssl, void *ctx); \ingroup IO \brief This function returns the IOCB_ReadCtx member of the WOLFSSL struct. - - \return pointer This function returns a void pointer to the IOCB_ReadCtx + + \return pointer This function returns a void pointer to the IOCB_ReadCtx member of the WOLFSSL structure. \return NULL returned if the WOLFSSL struct is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); @@ -334,7 +334,7 @@ WOLFSSL_API void wolfSSL_SetIOWriteCtx(WOLFSSL* ssl, void *ctx); // Failure case. The ssl object was NULL. } \endcode - + \sa wolfSSL_GetIOWriteCtx \sa wolfSSL_SetIOReadFlags \sa wolfSSL_SetIOWriteCtx @@ -347,13 +347,13 @@ WOLFSSL_API void* wolfSSL_GetIOReadCtx( WOLFSSL* ssl); \ingroup IO \brief This function returns the IOCB_WriteCtx member of the WOLFSSL structure. - - \return pointer This function returns a void pointer to the IOCB_WriteCtx + + \return pointer This function returns a void pointer to the IOCB_WriteCtx member of the WOLFSSL structure. \return NULL returned if the WOLFSSL struct is NULL. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL* ssl; @@ -364,7 +364,7 @@ WOLFSSL_API void* wolfSSL_GetIOReadCtx( WOLFSSL* ssl); // The funciton returned NULL. } \endcode - + \sa wolfSSL_GetIOReadCtx \sa wolfSSL_SetIOWriteCtx \sa wolfSSL_SetIOReadCtx @@ -373,32 +373,32 @@ WOLFSSL_API void* wolfSSL_GetIOReadCtx( WOLFSSL* ssl); WOLFSSL_API void* wolfSSL_GetIOWriteCtx(WOLFSSL* ssl); /*! - \brief This function sets the flags for the receive callback to use for - the given SSL session. The receive callback could be either the default - wolfSSL EmbedReceive callback, or a custom callback specified by the user - (see wolfSSL_CTX_SetIORecv). The default flag value is set internally by - wolfSSL to the value of 0. The default wolfSSL receive callback uses the - recv() function to receive data from the socket. From the recv() man page: - “The flags argument to a recv() function is formed by or'ing one or more - of the values: MSG_OOB process out-of-band data, MSG_PEEK peek at incoming - message, MSG_WAITALL wait for full request or error. The MSG_OOB flag - requests receipt of out-of-band data that would not be received in the - normal data stream. Some protocols place expedited data at the head of - the normal data queue, and thus this flag cannot be used with such - protocols. The MSG_PEEK flag causes the receive operation to return - data from the beginning of the receive queue without removing that data - from the queue. Thus, a subsequent receive call will return the same data. - The MSG_WAITALL flag requests that the operation block until the full - request is satisfied. However, the call may still return less data than - requested if a signal is caught, an error or disconnect occurs, or the next + \brief This function sets the flags for the receive callback to use for + the given SSL session. The receive callback could be either the default + wolfSSL EmbedReceive callback, or a custom callback specified by the user + (see wolfSSL_CTX_SetIORecv). The default flag value is set internally by + wolfSSL to the value of 0. The default wolfSSL receive callback uses the + recv() function to receive data from the socket. From the recv() man page: + “The flags argument to a recv() function is formed by or'ing one or more + of the values: MSG_OOB process out-of-band data, MSG_PEEK peek at incoming + message, MSG_WAITALL wait for full request or error. The MSG_OOB flag + requests receipt of out-of-band data that would not be received in the + normal data stream. Some protocols place expedited data at the head of + the normal data queue, and thus this flag cannot be used with such + protocols. The MSG_PEEK flag causes the receive operation to return + data from the beginning of the receive queue without removing that data + from the queue. Thus, a subsequent receive call will return the same data. + The MSG_WAITALL flag requests that the operation block until the full + request is satisfied. However, the call may still return less data than + requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned.” - + \return none No returns. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). - \param flags value of the I/O read flags for the specified SSL + \param flags value of the I/O read flags for the specified SSL session (ssl). - + _Example_ \code WOLFSSL* ssl = 0; @@ -407,7 +407,7 @@ WOLFSSL_API void* wolfSSL_GetIOWriteCtx(WOLFSSL* ssl); wolfSSL_SetIOReadFlags(ssl, 0); ... \endcode - + \sa wolfSSL_CTX_SetIORecv \sa wolfSSL_CTX_SetIOSend \sa wolfSSL_SetIOReadCtx @@ -415,25 +415,25 @@ WOLFSSL_API void* wolfSSL_GetIOWriteCtx(WOLFSSL* ssl); WOLFSSL_API void wolfSSL_SetIOReadFlags( WOLFSSL* ssl, int flags); /*! - \brief This function sets the flags for the send callback to use for the - given SSL session. The send callback could be either the default wolfSSL - EmbedSend callback, or a custom callback specified by the user (see - wolfSSL_CTX_SetIOSend). The default flag value is set internally by wolfSSL - to the value of 0. The default wolfSSL send callback uses the send() - function to send data from the socket. From the send() man page: “The - flags parameter may include one or more of the following: - #define MSG_OOB 0x1 // process out-of-band data, - #define MSG_DONTROUTE 0x4 // bypass routing, use direct interface. - The flag MSG_OOB is used to send ``out-of-band'' data on sockets that - support this notion (e.g. SOCK_STREAM); the underlying protocol must also - support ``out-of-band'' data. MSG_DONTROUTE is usually used only by + \brief This function sets the flags for the send callback to use for the + given SSL session. The send callback could be either the default wolfSSL + EmbedSend callback, or a custom callback specified by the user (see + wolfSSL_CTX_SetIOSend). The default flag value is set internally by wolfSSL + to the value of 0. The default wolfSSL send callback uses the send() + function to send data from the socket. From the send() man page: “The + flags parameter may include one or more of the following: + #define MSG_OOB 0x1 // process out-of-band data, + #define MSG_DONTROUTE 0x4 // bypass routing, use direct interface. + The flag MSG_OOB is used to send ``out-of-band'' data on sockets that + support this notion (e.g. SOCK_STREAM); the underlying protocol must also + support ``out-of-band'' data. MSG_DONTROUTE is usually used only by diagnostic or routing programs.” \return none No returns. - + \param ssl pointer to the SSL session, created with wolfSSL_new(). \param flags value of the I/O send flags for the specified SSL session (ssl). - + _Example_ \code WOLFSSL* ssl = 0; @@ -442,7 +442,7 @@ WOLFSSL_API void wolfSSL_SetIOReadFlags( WOLFSSL* ssl, int flags); wolfSSL_SetIOWriteFlags(ssl, 0); ... \endcode - + \sa wolfSSL_CTX_SetIORecv \sa wolfSSL_CTX_SetIOSend \sa wolfSSL_SetIOReadCtx @@ -452,30 +452,30 @@ WOLFSSL_API void wolfSSL_SetIOWriteFlags(WOLFSSL* ssl, int flags); /*! \ingroup IO - \brief This function sets the nxSocket and nxWait members of the nxCtx + \brief This function sets the nxSocket and nxWait members of the nxCtx struct within the WOLFSSL structure. - + \return none No returns. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param nxSocket a pointer to type NX_TCP_SOCKET that is set to the + \param nxSocket a pointer to type NX_TCP_SOCKET that is set to the nxSocket member of the nxCTX structure. - \param waitOption a ULONG type that is set to the nxWait member of + \param waitOption a ULONG type that is set to the nxWait member of the nxCtx structure. - + _Example_ \code WOLFSSL* ssl = wolfSSL_new(ctx); NX_TCP_SOCKET* nxSocket; ULONG waitOption; … - if(ssl != NULL || nxSocket != NULL || waitOption <= 0){ + if(ssl != NULL || nxSocket != NULL || waitOption <= 0){ wolfSSL_SetIO_NetX(ssl, nxSocket, waitOption); } else { // You need to pass in good parameters. } \endcode - + \sa set_fd \sa NetX_Send \sa NetX_Receive @@ -484,17 +484,17 @@ WOLFSSL_API void wolfSSL_SetIO_NetX(WOLFSSL* ssl, NX_TCP_SOCKET* nxsocket, ULONG waitoption); /*! - \brief This function sets the callback for the CBIOCookie member of the - WOLFSSL_CTX structure. The CallbackGenCookie type is a function pointer - and has the signature: int (*CallbackGenCookie)(WOLFSSL* ssl, unsigned + \brief This function sets the callback for the CBIOCookie member of the + WOLFSSL_CTX structure. The CallbackGenCookie type is a function pointer + and has the signature: int (*CallbackGenCookie)(WOLFSSL* ssl, unsigned char* buf, int sz, void* ctx); - + \return none No returns. - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - \param cb a CallbackGenCookie type function pointer with the signature + \param cb a CallbackGenCookie type function pointer with the signature of CallbackGenCookie. - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -506,7 +506,7 @@ WOLFSSL_API void wolfSSL_SetIO_NetX(WOLFSSL* ssl, NX_TCP_SOCKET* nxsocket, … wolfSSL_CTX_SetGenCookie(ssl->ctx, SetGenCookieCB); \endcode - + \sa CallbackGenCookie */ WOLFSSL_API void wolfSSL_CTX_SetGenCookie(WOLFSSL_CTX*, CallbackGenCookie); @@ -514,15 +514,15 @@ WOLFSSL_API void wolfSSL_CTX_SetGenCookie(WOLFSSL_CTX*, CallbackGenCookie); /*! \ingroup Setup - \brief This function returns the IOCB_CookieCtx member of the + \brief This function returns the IOCB_CookieCtx member of the WOLFSSL structure. - - \return pointer The function returns a void pointer value stored in + + \return pointer The function returns a void pointer value stored in the IOCB_CookieCtx. \return NULL if the WOLFSSL struct is NULL - + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). - + _Example_ \code WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); @@ -534,7 +534,7 @@ WOLFSSL_API void wolfSSL_CTX_SetGenCookie(WOLFSSL_CTX*, CallbackGenCookie); // You have the cookie } \endcode - + \sa wolfSSL_SetCookieCtx \sa wolfSSL_CTX_SetGenCookie */ diff --git a/doc/formats/html/Doxyfile b/doc/formats/html/Doxyfile index a411fc11c..66ad911eb 100644 --- a/doc/formats/html/Doxyfile +++ b/doc/formats/html/Doxyfile @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = +PROJECT_NAME = # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -51,7 +51,7 @@ PROJECT_BRIEF = # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = +PROJECT_LOGO = # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is @@ -1653,7 +1653,7 @@ GENERATE_LATEX = NO # The default directory is: latex. # This tag requires that the tag GENERATE_LATEX is set to YES. -LATEX_OUTPUT = +LATEX_OUTPUT = # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be # invoked. diff --git a/doc/formats/html/html_changes/customdoxygen.css b/doc/formats/html/html_changes/customdoxygen.css index 1df1a2ff7..2c553fdea 100644 --- a/doc/formats/html/html_changes/customdoxygen.css +++ b/doc/formats/html/html_changes/customdoxygen.css @@ -247,11 +247,11 @@ a.elRef { } a.code, a.code:visited, a.line, a.line:visited { - color: #c46715; + color: #c46715; } a.codeRef, a.codeRef:visited, a.lineRef, a.lineRef:visited { - color: #c46715; + color: #c46715; } /* @end */ @@ -521,20 +521,20 @@ span.charliteral { color: #008080 } -span.vhdldigit { - color: #ff00ff +span.vhdldigit { + color: #ff00ff } -span.vhdlchar { - color: #000000 +span.vhdlchar { + color: #000000 } -span.vhdlkeyword { - color: #700070 +span.vhdlkeyword { + color: #700070 } -span.vhdllogic { - color: #ff0000 +span.vhdllogic { + color: #ff0000 } blockquote { @@ -752,9 +752,9 @@ table.memberdecls { } .memdoc, dl.reflist dd { - border-bottom: 1px solid #A8B8D9; - border-left: 1px solid #A8B8D9; - border-right: 1px solid #A8B8D9; + border-bottom: 1px solid #A8B8D9; + border-left: 1px solid #A8B8D9; + border-right: 1px solid #A8B8D9; padding: 6px 10px 2px 10px; background-color: #FBFCFD; border-top-width: 0; @@ -806,18 +806,18 @@ dl.reflist dd { .params, .retval, .exception, .tparams { margin-left: 0px; padding-left: 0px; -} +} .params .paramname, .retval .paramname { font-weight: bold; vertical-align: top; } - + .params .paramtype { font-style: italic; vertical-align: top; -} - +} + .params .paramdir { font-family: "courier new",courier,monospace; vertical-align: top; @@ -1073,8 +1073,8 @@ table.fieldtable { .fieldtable td.fielddoc p:first-child { margin-top: 0px; -} - +} + .fieldtable td.fielddoc p:last-child { margin-bottom: 2px; } @@ -1149,7 +1149,7 @@ table.fieldtable { color: #283A5D; font-family: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); - text-decoration: none; + text-decoration: none; } .navpath li.navelem a:hover @@ -1178,7 +1178,7 @@ div.summary padding-right: 5px; width: 50%; text-align: right; -} +} div.summary a { @@ -1193,7 +1193,7 @@ table.classindex margin-right: 3%; width: 94%; border: 0; - border-spacing: 0; + border-spacing: 0; padding: 0; } @@ -1302,12 +1302,12 @@ dl.section dd { vertical-align: bottom; border-collapse: separate; } - + #projectlogo img -{ +{ border: 0px none; } - + #projectalign { vertical-align: middle; @@ -1319,7 +1319,7 @@ dl.section dd { margin: 0px; padding: 2px 0px; } - + #projectbrief { font: 120% Tahoma, Arial,sans-serif; @@ -1424,7 +1424,7 @@ div.toc ul { list-style: none outside none; border: medium none; padding: 0px; -} +} div.toc li.level1 { margin-left: 0px; diff --git a/doc/formats/html/html_changes/doxygen.css b/doc/formats/html/html_changes/doxygen.css index 266c8b3a6..c49b43f3e 100644 --- a/doc/formats/html/html_changes/doxygen.css +++ b/doc/formats/html/html_changes/doxygen.css @@ -150,11 +150,11 @@ a.elRef { } a.code, a.code:visited, a.line, a.line:visited { - color: #4665A2; + color: #4665A2; } a.codeRef, a.codeRef:visited, a.lineRef, a.lineRef:visited { - color: #4665A2; + color: #4665A2; } /* @end */ @@ -379,20 +379,20 @@ span.charliteral { color: #008080 } -span.vhdldigit { - color: #ff00ff +span.vhdldigit { + color: #ff00ff } -span.vhdlchar { - color: #000000 +span.vhdlchar { + color: #000000 } -span.vhdlkeyword { - color: #700070 +span.vhdlkeyword { + color: #700070 } -span.vhdllogic { - color: #ff0000 +span.vhdllogic { + color: #ff0000 } blockquote { @@ -610,9 +610,9 @@ table.memberdecls { } .memdoc, dl.reflist dd { - border-bottom: 1px solid #A8B8D9; - border-left: 1px solid #A8B8D9; - border-right: 1px solid #A8B8D9; + border-bottom: 1px solid #A8B8D9; + border-left: 1px solid #A8B8D9; + border-right: 1px solid #A8B8D9; padding: 6px 10px 2px 10px; background-color: #FBFCFD; border-top-width: 0; @@ -664,18 +664,18 @@ dl.reflist dd { .params, .retval, .exception, .tparams { margin-left: 0px; padding-left: 0px; -} +} .params .paramname, .retval .paramname { font-weight: bold; vertical-align: top; } - + .params .paramtype { font-style: italic; vertical-align: top; -} - +} + .params .paramdir { font-family: "courier new",courier,monospace; vertical-align: top; @@ -931,8 +931,8 @@ table.fieldtable { .fieldtable td.fielddoc p:first-child { margin-top: 0px; -} - +} + .fieldtable td.fielddoc p:last-child { margin-bottom: 2px; } @@ -1007,7 +1007,7 @@ table.fieldtable { color: #283A5D; font-family: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); - text-decoration: none; + text-decoration: none; } .navpath li.navelem a:hover @@ -1036,7 +1036,7 @@ div.summary padding-right: 5px; width: 50%; text-align: right; -} +} div.summary a { @@ -1051,7 +1051,7 @@ table.classindex margin-right: 3%; width: 94%; border: 0; - border-spacing: 0; + border-spacing: 0; padding: 0; } @@ -1160,12 +1160,12 @@ dl.section dd { vertical-align: bottom; border-collapse: separate; } - + #projectlogo img -{ +{ border: 0px none; } - + #projectalign { vertical-align: middle; @@ -1177,7 +1177,7 @@ dl.section dd { margin: 0px; padding: 2px 0px; } - + #projectbrief { font: 120% Tahoma, Arial,sans-serif; @@ -1282,7 +1282,7 @@ div.toc ul { list-style: none outside none; border: medium none; padding: 0px; -} +} div.toc li.level1 { margin-left: 0px; diff --git a/doc/formats/html/html_changes/menu.js b/doc/formats/html/html_changes/menu.js index ff2c88bcc..9b399756a 100644 --- a/doc/formats/html/html_changes/menu.js +++ b/doc/formats/html/html_changes/menu.js @@ -28,6 +28,6 @@ function initMenu(relPath,searchEnabled,serverSide,searchPage,search) { $('#main-nav').append(makeTree(menudata,relPath)); $('#main-nav').children(':first').addClass('sm sm-dox').attr('id','main-menu'); - + $('#main-menu').smartmenus(); } diff --git a/doc/formats/html/html_changes/search/search.css b/doc/formats/html/html_changes/search/search.css index 0b27e78a1..e1a0d649c 100644 --- a/doc/formats/html/html_changes/search/search.css +++ b/doc/formats/html/html_changes/search/search.css @@ -1,4 +1,4 @@ -/*---------------- Search Box */ +/*---------------- Search Box */ #FSearchBox { float: left; } @@ -128,7 +128,7 @@ span.SelectionMark { a.SelectItem { display: block; outline-style: none; - color: #000000; + color: #000000; text-decoration: none; padding-left: 6px; padding-right: 12px; @@ -136,7 +136,7 @@ a.SelectItem { a.SelectItem:focus, a.SelectItem:active { - color: #000000; + color: #000000; outline-style: none; text-decoration: none; } @@ -170,7 +170,7 @@ iframe#MSearchResults { #SRIndex { - clear:both; + clear:both; padding-bottom: 15px; } @@ -189,7 +189,7 @@ body.SRPage { } .SRChildren { - padding-left: 3ex; padding-bottom: .5em + padding-left: 3ex; padding-bottom: .5em } .SRPage .SRChildren { @@ -197,7 +197,7 @@ body.SRPage { } .SRSymbol { - font-weight: bold; + font-weight: bold; color: #425E97; font-family: Arial, Verdana, sans-serif; text-decoration: none; @@ -206,7 +206,7 @@ body.SRPage { a.SRScope { display: block; - color: #425E97; + color: #425E97; font-family: Arial, Verdana, sans-serif; text-decoration: none; outline: none; diff --git a/doc/formats/pdf/Doxyfile b/doc/formats/pdf/Doxyfile index 493aa76a8..1f8174e34 100644 --- a/doc/formats/pdf/Doxyfile +++ b/doc/formats/pdf/Doxyfile @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = +PROJECT_NAME = # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -51,7 +51,7 @@ PROJECT_BRIEF = # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = +PROJECT_LOGO = # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is @@ -1147,7 +1147,7 @@ HTML_FILE_EXTENSION = .html # of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_HEADER = +HTML_HEADER = # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each # generated HTML page. If the tag is left blank doxygen will generate a standard @@ -1157,7 +1157,7 @@ HTML_HEADER = # that doxygen normally uses. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_FOOTER = +HTML_FOOTER = # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # sheet that is used by each HTML page. It can be used to fine-tune the look of @@ -1736,7 +1736,7 @@ LATEX_HEADER = header.tex # Note: Only use a user-defined footer if you know what you are doing! # This tag requires that the tag GENERATE_LATEX is set to YES. -LATEX_FOOTER = +LATEX_FOOTER = # The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined # LaTeX style sheets that are included after the standard style sheets created diff --git a/doc/generate_documentation.sh b/doc/generate_documentation.sh index 9f886b848..2ad69e8ec 100755 --- a/doc/generate_documentation.sh +++ b/doc/generate_documentation.sh @@ -36,7 +36,7 @@ fi for var in $@ do - case $var in + case $var in -install) INSTALL_DOX=true ;;