diff --git a/IDE/MDK-ARM/MDK-ARM/wolfSSL/time-CortexM3-4.c b/IDE/MDK-ARM/MDK-ARM/wolfSSL/time-CortexM3-4.c index 115a4f672..4c355b930 100644 --- a/IDE/MDK-ARM/MDK-ARM/wolfSSL/time-CortexM3-4.c +++ b/IDE/MDK-ARM/MDK-ARM/wolfSSL/time-CortexM3-4.c @@ -29,8 +29,8 @@ #define DWT ((DWT_Type *) (0xE0001000UL) ) typedef struct { - uint32_t CTRL; /*!< Offset: 0x000 (R/W) Control Register */ - uint32_t CYCCNT; /*!< Offset: 0x004 (R/W) Cycle Count Register */ + uint32_t CTRL; /*< Offset: 0x000 (R/W) Control Register */ + uint32_t CYCCNT; /*< Offset: 0x004 (R/W) Cycle Count Register */ } DWT_Type; extern uint32_t SystemCoreClock ; diff --git a/Makefile.am b/Makefile.am index a8cb71d78..aec8e4fa3 100644 --- a/Makefile.am +++ b/Makefile.am @@ -207,3 +207,4 @@ merge-clean: @find ./ | $(GREP) \.OTHER | xargs rm -f @find ./ | $(GREP) \.BASE | xargs rm -f @find ./ | $(GREP) \~$$ | xargs rm -f + diff --git a/doc/README_DOXYGEN b/doc/README_DOXYGEN new file mode 100644 index 000000000..871c6b79e --- /dev/null +++ b/doc/README_DOXYGEN @@ -0,0 +1,178 @@ +wolfSSL with Doxygen 1.8.13 + +---- Dependencies ---- + +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 +doc/formats/pdf/Doxyfile ) + +The following texlive packages were installed when creating this +documentation on Linux Mint: +sudo apt install texlive +sudo apt install texlive-latex-extra + +For Mac users Basic Tex from TUG is recommended. After installing BasicTex +additional dependencies will need to be met: +% sudo tlmgr update --self +% sudo tlmgr install tabu varwidth multirow adjustbox collectbox sectsty tocloft collection-fontsextra + +---- Generating the Documentation ---- + +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) + +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 +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 + + 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. + + 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 + that is generated is used to generate a PDF as well. + + 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. + +---- 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 +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 +original file: + + /*! + \file wolfssl/PATH_TO_FILE/FILE_NAME + */ + +This ensures that the file will be linked to in the doxygen generated html. +When specifying a specific file with the \file command be sure to include part of +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 include that module's name in the \ingroup. The current modules to choose from +are as follows but new group can be made: + + \ingroup 3DES + \ingroup AES + \ingroup ARC4 + \ingroup BLAKE2 + \ingroup Camellia + \ingroup ChaCha + \ingroup ChaCha20Poly1305 + \ingroup Curve25519 + \ingroup DSA Algorithms + \ingroup Diffie-Hellman + \ingroup ECC + \ingroup ED25519 + \ingroup HC128 + \ingroup HMAC + \ingroup IDEA + \ingroup MD2 + \ingroup MD4 + \ingroup MD5 + \ingroup PKCS7 + \ingroup Password + \ingroup Poly1305 + \ingroup RIPEMD + \ingroup RSA + \ingroup Rabbit + \ingroup SHA + \ingroup SRP + \ingroup wolfCrypt + \ingroup openSSL + \ingroup CertManager + \ingroup TLS + \ingroup CertsKeys + \ingroup Setup + \ingroup IO + \ingroup Debug + +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 + + /*! + \defgroup + */ + +The general outline when documenting within the wolfssl library in doxygen should +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 + */ + +When adding new documentation be sure to keep the sections, \ingroup, \brief, +\param, \return, Etc. separated with at least 1 newline. This insures that when +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 +generation and that the documentation shows up correctly. diff --git a/doc/check_api.sh b/doc/check_api.sh new file mode 100755 index 000000000..4b6aa8b77 --- /dev/null +++ b/doc/check_api.sh @@ -0,0 +1,43 @@ +#!/bin/sh + +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' ' ' | + sed 's/\\n//g' | + sed 's/ \+/ /g' | + sed 's/\x00/\n/g' > dox_api.txt + + find ../ -not -path '../doc/*' -name $h_file | + while read -r h_file_path; do + echo "Checking: $h_file_path" + grep -P -h -z -o 'WOLFSSL_API(\n|\s|[^;])*;' "$h_file_path" | + sed 's/#.*/ /g' | + 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 + echo "Mistmatch" + echo "Dox_api: $api_count" + echo "Matched_api: $match_count" + echo "Header file: $h_file" + echo "Check API: " + sort dox_api.txt -o dox_api.txt + sort wolf_api.txt -o wolf_api.txt + comm -23 dox_api.txt wolf_api.txt + exit 1 + else + echo "$h_file is all good" + break + fi + done || exit 1 + echo 'Next...\n' + +done || exit 1 + +rm dox_api.txt +rm wolf_api.txt diff --git a/doc/dox_comments/header_files/aes.h b/doc/dox_comments/header_files/aes.h new file mode 100644 index 000000000..d65f1a1f2 --- /dev/null +++ b/doc/dox_comments/header_files/aes.h @@ -0,0 +1,811 @@ +/*! + \ingroup AES + \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 + 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, + AES_ENCRYPTION) != 0) { + // failed to set aes key + } + \endcode + + \sa wc_AesSetKeyDirect + \sa wc_AesSetIV +*/ +WOLFSSL_API int wc_AesSetKey(Aes* aes, const byte* key, word32 len, + const byte* iv, int dir); +/*! + \ingroup AES + \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 + initialization vector + \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; + // set enc key + byte iv[] = { some 16 byte iv }; + if (ret = wc_AesSetIV(&enc, iv) != 0) { + // failed to set aes iv + } + \endcode + + \sa wc_AesSetKeyDirect + \sa wc_AesSetKey +*/ +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 + 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 + 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; + int ret = 0; + // initialize enc with AesSetKey, using direction AES_ENCRYPTION + byte msg[AES_BLOCK_SIZE * n]; // multiple of 16 bytes + // fill msg with data + byte cipher[AES_BLOCK_SIZE * n]; // Some multiple of 16 bytes + if ((ret = wc_AesCbcEncrypt(&enc, cipher, message, sizeof(msg))) != 0 ) { + // block align error + } + \endcode + + \sa wc_AesSetKey + \sa wc_AesSetIV + \sa wc_AesCbcDecrypt +*/ +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 + 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 + of the decrypted message. + \param in pointer to the input buffer containing cipher text to be + decrypted. + \param sz size of input message. + + _Example_ + \code + Aes dec; + int ret = 0; + // initialize dec with AesSetKey, using direction AES_DECRYPTION + byte cipher[AES_BLOCK_SIZE * n]; // some multiple of 16 bytes + // fill cipher with cipher text + byte plain [AES_BLOCK_SIZE * n]; + if ((ret = wc_AesCbcDecrypt(&dec, plain, cipher, sizeof(cipher))) != 0 ) { + // block align error + } + \endcode + + \sa wc_AesSetKey + \sa wc_AesCbcEncrypt +*/ +WOLFSSL_API int wc_AesCbcDecrypt(Aes* aes, byte* out, + const byte* in, word32 sz); +/*! + \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 + 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 + 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 + AES_ENCRYPTION + // 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 + 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)); + // decrypt cipher text + \endcode + + \sa wc_AesSetKey +*/ + WOLFSSL_API int wc_AesCtrEncrypt(Aes* aes, byte* out, + const byte* in, word32 sz); +/*! + \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 + 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 + text of the encrypted message + \param in pointer to the input buffer containing plain text to be encrypted + + _Example_ + \code + Aes enc; + // initialize enc with AesSetKey, using direction AES_ENCRYPTION + byte msg [AES_BLOCK_SIZE]; // 16 bytes + // initialize msg with plain text to encrypt + byte cipher[AES_BLOCK_SIZE]; + wc_AesEncryptDirect(&enc, cipher, msg); + \endcode + + \sa wc_AesDecryptDirect + \sa wc_AesSetKeyDirect +*/ + 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 + 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 + text of the decrypted cipher text + \param in pointer to the input buffer containing cipher text to be + decrypted + + _Example_ + \code + Aes dec; + // initialize enc with AesSetKey, using direction AES_DECRYPTION + byte cipher [AES_BLOCK_SIZE]; // 16 bytes + // initialize cipher with cipher text to decrypt + byte msg[AES_BLOCK_SIZE]; + wc_AesDecryptDirect(&dec, msg, cipher); + \endcode + + \sa wc_AesEncryptDirect + \sa wc_AesSetKeyDirect + */ + 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 + 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) + 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, + AES_ENCRYPTION) != 0) { + // failed to set aes key + } + \endcode + + \sa wc_AesEncryptDirect + \sa wc_AesDecryptDirect + \sa wc_AesSetKey +*/ + WOLFSSL_API int wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len, + const byte* iv, int dir); +/*! + \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 + 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; + int ret = 0; + byte key[] = { some 16, 24,32 byte key }; + if (ret = wc_AesGcmSetKey(&enc, key, sizeof(key)) != 0) { + // failed to set aes key + } + \endcode + + \sa wc_AesGcmEncrypt + \sa wc_AesGcmDecrypt +*/ + 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 + 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 + authentication tag + \param authTagSz length of the desired authentication tag + \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 + making plain some multiple of 16 bytes + // initialize plain with msg to encrypt + byte cipher[sizeof(plain)]; + byte iv[] = // some 16 byte iv + byte authTag[AUTH_TAG_LENGTH]; + byte authIn[] = // Authentication Vector + + wc_AesGcmEncrypt(&enc, cipher, plain, sizeof(cipher), iv, sizeof(iv), + authTag, sizeof(authTag), authIn, sizeof(authIn)); + \endcode + + \sa wc_AesGcmSetKey + \sa wc_AesGcmDecrypt +*/ + WOLFSSL_API int wc_AesGcmEncrypt(Aes* aes, byte* out, + const byte* in, word32 sz, + const byte* iv, word32 ivSz, + byte* authTag, word32 authTagSz, + const byte* authIn, word32 authInSz); +/*! + \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 + 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 + 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 + \param sz length of the cipher text to decrypt + \param iv pointer to the buffer containing the initialization vector + \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 + 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 + // initialize aes structure by calling wc_AesGcmSetKey if not already done + + 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)]; + byte iv[] = // some 16 byte iv + byte authTag[AUTH_TAG_LENGTH]; + byte authIn[] = // Authentication Vector + + wc_AesGcmDecrypt(&enc, output, cipher, sizeof(cipher), iv, sizeof(iv), + authTag, sizeof(authTag), authIn, sizeof(authIn)); + \endcode + + \sa wc_AesGcmSetKey + \sa wc_AesGcmEncrypt +*/ + WOLFSSL_API int wc_AesGcmDecrypt(Aes* aes, byte* out, + const byte* in, word32 sz, + const byte* iv, word32 ivSz, + const byte* authTag, word32 authTagSz, + const byte* authIn, word32 authInSz); +/*! + \ingroup AES + \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 + 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 + 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; + key[] = { some 16, 24, or 32 byte length key }; + iv[] = { some 16 byte length iv }; + + wc_GmacSetKey(&gmac, key, sizeof(key)); + authIn[] = { some 16 byte authentication input }; + tag[AES_BLOCK_SIZE]; // will store authentication code + + 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, + const byte* authIn, word32 authInSz, + byte* authTag, word32 authTagSz); +/*! + \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 + 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; + key[] = { some 16, 24, or 32 byte length key }; + + wc_AesCcmSetKey(&aes, key, sizeof(key)); + \endcode + + \sa wc_AesCcmEncrypt + \sa wc_AesCcmDecrypt +*/ + 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 + 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 + (number only used once) + \param nonceSz length of the nonce + \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 + authentication vector + \param authInSz length of the input authentication vector + + _Example_ + \code + Aes enc; + // initialize enc with wc_AesCcmSetKey + + nonce[] = { initialize nonce }; + plain[] = { some plain text message }; + cipher[sizeof(plain)]; + + authIn[] = { some 16 byte authentication input }; + tag[AES_BLOCK_SIZE]; // will store authentication code + + wc_AesCcmEncrypt(&enc, cipher, plain, sizeof(plain), nonce, sizeof(nonce), + tag, sizeof(tag), authIn, sizeof(authIn)); + \endcode + + \sa wc_AesCcmSetKey + \sa wc_AesCcmDecrypt +*/ + WOLFSSL_API int wc_AesCcmEncrypt(Aes* aes, byte* out, + const byte* in, word32 inSz, + const byte* nonce, word32 nonceSz, + byte* authTag, word32 authTagSz, + const byte* authIn, word32 authInSz); +/*! + \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 + 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 + 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 + (number only used once) + \param nonceSz length of the nonce + \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 + authentication vector + \param authInSz length of the input authentication vector + + _Example_ + \code + Aes dec; + // initialize dec with wc_AesCcmSetKey + + nonce[] = { initialize nonce }; + cipher[] = { encrypted message }; + plain[sizeof(cipher)]; + + authIn[] = { some 16 byte authentication input }; + tag[AES_BLOCK_SIZE] = { authentication tag received for verification }; + + 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 +*/ + WOLFSSL_API int wc_AesCcmDecrypt(Aes* aes, byte* out, + const byte* in, word32 inSz, + const byte* nonce, word32 nonceSz, + const byte* authTag, word32 authTagSz, + const byte* authIn, word32 authInSz); +/*! + \ingroup AES + + \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 + key size. + i.e. 32 for a 16 byte key. + \param dir direction, either AES_ENCRYPTION or AES_DECRYPTION + \param heap heap hint to use for memory. Can be NULL + \param devId id to use with async crypto. Can be 0 + + _Example_ + \code + XtsAes aes; + + if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0) != 0) + { + // Handle error + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsEncrypt + \sa wc_AesXtsDecrypt + \sa wc_AesXtsFree +*/ +WOLFSSL_API int wc_AesXtsSetKey(XtsAes* aes, const byte* key, + word32 len, int dir, void* heap, int devId); +/*! + \ingroup AES + + \brief Same process as wc_AesXtsEncrypt but uses a word64 type as the tweak + value instead of a byte array. This just converts the word64 to a + byte array and calls wc_AesXtsEncrypt. + + \return 0 Success + + \param aes AES keys to use for block encrypt/decrypt + \param out output buffer to hold cipher text + \param in input plain text buffer to encrypt + \param sz size of both out and in buffers + \param sector value to use for tweak + + _Example_ + \code + XtsAes aes; + unsigned char plain[SIZE]; + unsigned char cipher[SIZE]; + word64 s = VALUE; + + //set up keys with AES_ENCRYPTION as dir + + if(wc_AesXtsEncryptSector(&aes, cipher, plain, SIZE, s) != 0) + { + // Handle error + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsEncrypt + \sa wc_AesXtsDecrypt + \sa wc_AesXtsSetKey + \sa wc_AesXtsFree +*/ +WOLFSSL_API int wc_AesXtsEncryptSector(XtsAes* aes, byte* out, + const byte* in, word32 sz, word64 sector); +/*! + \ingroup AES + + \brief Same process as wc_AesXtsDecrypt but uses a word64 type as the tweak + value instead of a byte array. This just converts the word64 to a + byte array. + + \return 0 Success + + \param aes AES keys to use for block encrypt/decrypt + \param out output buffer to hold plain text + \param in input cipher text buffer to decrypt + \param sz size of both out and in buffers + \param sector value to use for tweak + + _Example_ + \code + XtsAes aes; + unsigned char plain[SIZE]; + unsigned char cipher[SIZE]; + word64 s = VALUE; + + //set up aes key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION + + if(wc_AesXtsDecryptSector(&aes, plain, cipher, SIZE, s) != 0) + { + // Handle error + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsEncrypt + \sa wc_AesXtsDecrypt + \sa wc_AesXtsSetKey + \sa wc_AesXtsFree +*/ +WOLFSSL_API int wc_AesXtsDecryptSector(XtsAes* aes, byte* out, + const byte* in, word32 sz, word64 sector); +/*! + \ingroup AES + + \brief AES with XTS mode. (XTS) XEX encryption with Tweak and cipher text + Stealing. + + \return 0 Success + + \param aes AES keys to use for block encrypt/decrypt + \param out output buffer to hold cipher text + \param in input plain text buffer to encrypt + \param sz size of both out and in buffers + \param i value to use for tweak + \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; + unsigned char plain[SIZE]; + unsigned char cipher[SIZE]; + unsigned char i[AES_BLOCK_SIZE]; + + //set up key with AES_ENCRYPTION as dir + + if(wc_AesXtsEncrypt(&aes, cipher, plain, SIZE, i, sizeof(i)) != 0) + { + // Handle error + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsDecrypt + \sa wc_AesXtsSetKey + \sa wc_AesXtsFree +*/ +WOLFSSL_API int wc_AesXtsEncrypt(XtsAes* aes, byte* out, + const byte* in, word32 sz, const byte* i, word32 iSz); +/*! + \ingroup AES + + \brief Same process as encryption but Aes key is AES_DECRYPTION type. + + \return 0 Success + + \param aes AES keys to use for block encrypt/decrypt + \param out output buffer to hold plain text + \param in input cipher text buffer to decrypt + \param sz size of both out and in buffers + \param i value to use for tweak + \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; + unsigned char plain[SIZE]; + unsigned char cipher[SIZE]; + unsigned char i[AES_BLOCK_SIZE]; + + //set up key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION + + if(wc_AesXtsDecrypt(&aes, plain, cipher, SIZE, i, sizeof(i)) != 0) + { + // Handle error + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsEncrypt + \sa wc_AesXtsSetKey + \sa wc_AesXtsFree +*/ +WOLFSSL_API int wc_AesXtsDecrypt(XtsAes* aes, byte* out, + const byte* in, word32 sz, const byte* i, word32 iSz); +/*! + \ingroup AES + + \brief This is to free up any resources used by the XtsAes structure + + \return 0 Success + + \param aes AES keys to free + + _Example_ + \code + XtsAes aes; + + if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0) != 0) + { + // Handle error + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsEncrypt + \sa wc_AesXtsDecrypt + \sa wc_AesXtsSetKey +*/ +WOLFSSL_API int wc_AesXtsFree(XtsAes* aes); diff --git a/doc/dox_comments/header_files/arc4.h b/doc/dox_comments/header_files/arc4.h new file mode 100644 index 000000000..4966356c1 --- /dev/null +++ b/doc/dox_comments/header_files/arc4.h @@ -0,0 +1,58 @@ +/*! + \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 + 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 + 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; + byte key[] = { key to use for encryption }; + wc_Arc4SetKey(&enc, key, sizeof(key)); + + byte plain[] = { plain text to encode }; + byte cipher[sizeof(plain)]; + 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)); + \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 + 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.h b/doc/dox_comments/header_files/asn.h new file mode 100644 index 000000000..1a8f2aaa5 --- /dev/null +++ b/doc/dox_comments/header_files/asn.h @@ -0,0 +1,34 @@ +/*! + \ingroup ASN + + \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 + the certificate generated + \return MEMORY_E Returned if the call to XMALLOC fails + + \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 + converted certificate + \param derSz size of the char buffer in which to store the + converted certificate + + _Example_ + \code + char * file = “./certs/client-cert.pem”; + int derSz; + byte * der = (byte*)XMALLOC(EIGHTK_BUF, NULL, DYNAMIC_TYPE_CERT); + + derSz = wolfsSSL_PemCertToDer(file, der, EIGHTK_BUF); + if(derSz <= 0) { + //PemCertToDer error + } + \endcode + + \sa none +*/ +WOLFSSL_API +int wolfSSL_PemCertToDer(const char* fileName,unsigned char* derBuf,int derSz); diff --git a/doc/dox_comments/header_files/asn_public.h b/doc/dox_comments/header_files/asn_public.h new file mode 100644 index 000000000..67ad9fa1a --- /dev/null +++ b/doc/dox_comments/header_files/asn_public.h @@ -0,0 +1,1304 @@ +/*! + \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, + 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 +*/ +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 + must be initialized with wc_InitCert before this method is called. + + \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 + with XMALLOC + \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 + generation is not successful. + + \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 + to generate the certificate + \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); + RNG rng; + //initialize rng; + RsaKey key; + //initialize key; + byte * derCert = malloc(FOURK_BUF); + 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 + 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 + request generated. + \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 + the generated 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 + 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 + to generate the certificate request + \param eccKey pointer to an EccKey structure containing the ecc key used + to generate the certificate request + + _Example_ + \code + Cert myCert; + // initialize myCert + EccKey key; + //initialize key; + byte* derCert = (byte*)malloc(FOURK_BUF); + + 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() + or wc_MakeCertReq() if creating a CA signed cert. + + \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 + memory with XMALLOC + \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 + generation is not successful. + + \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, + CTC_SHAwRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, andCTC_SHA256wRSA + \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 + signed certificate + \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 + to used to sign the certificate + \param rng pointer to the random number generator used to sign + the certificate + + _Example_ + \code + Cert myCert; + byte* derCert = (byte*)malloc(FOURK_BUF); + // initialize myCert, derCert + RsaKey key; + // initialize key; + RNG rng; + // initialize rng + + word32 certSz; + 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, + generating a self-signed certificate. + + \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 + with XMALLOC + \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 + 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 + used to sign the certificate + \param rng pointer to the random number generator used to generate + and sign the certificate + + _Example_ + \code + Cert myCert; + byte* derCert = (byte*)malloc(FOURK_BUF); + // initialize myCert, derCert + RsaKey key; + // initialize key; + RNG rng; + // initialize rng + + 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 + 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 header file + \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 encryption specification of the cert file + \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 + expiration date + \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 + from the certificate + \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 + key object id + \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 + certificate extension + \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 same as the encryption type of the certificate in the provided file + \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 + permitted by the CA name constraints + \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; + // initialize myCert + if(wc_SetIssuer(&myCert, ”./path/to/ca-cert.pem”) != 0) { + // error setting issuer + } + \endcode + + \sa wc_InitCert + \sa wc_SetSubject + \sa wc_SetIssuerBuffer +*/ +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 + 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 + header file + \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 + encryption specification of the cert file + \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 + expiration date + \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 + from the certificate + \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 + key object id + \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 + certificate extension + \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 same as the encryption type of the certificate in the provided file + \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 + permitted by the CA name constraints + \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; + // initialize myCert + if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) { + // error setting subject + } + \endcode + + \sa wc_InitCert + \sa wc_SetIssuer +*/ +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 + 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 + with XMALLOC + \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 + encryption type from the cert + \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 + start date + \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 + from the certificate + \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 + from the certificate + \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 + defined and the certificate is a V1 or V2 certificate + \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 + encountered in processing the certificate + \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 + signature fails + \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 + 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; + // initialize myCert + if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) { + // error setting alt names + } + \endcode + + \sa wc_InitCert + \sa wc_SetIssuer +*/ + 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 + 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 + with XMALLOC + \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 + encryption type from the cert + \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 + start date + \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 + from the certificate + \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 from the certificate + \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 + defined and the certificate is a V1 or V2 certificate + \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 + encountered in processing the certificate + \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 + signature fails + \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 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 + from which to grab the issuer + \param derSz size of the buffer containing the der formatted certificate + from which to grab the issuer + + _Example_ + \code + Cert myCert; + // initialize myCert + byte* der; + der = (byte*)malloc(FOURK_BUF); + // initialize der + if(wc_SetIssuerBuffer(&myCert, der, FOURK_BUF) != 0) { + // error setting issuer + } + \endcode + + \sa wc_InitCert + \sa wc_SetIssuer +*/ +WOLFSSL_API int wc_SetIssuerBuffer(Cert*, const byte*, int); +/*! + \ingroup ASN + + \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 + with XMALLOC + \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 + encryption type from the cert + \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 + start date + \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 + from the certificate + \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 + from the certificate + \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 + defined and the certificate is a V1 or V2 certificate + \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 + encountered in processing the certificate + \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 + signature fails + \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 + 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 + from which to grab the subject + \param derSz size of the buffer containing the der formatted certificate + from which to grab the subject + + _Example_ + \code + Cert myCert; + // initialize myCert + byte* der; + der = (byte*)malloc(FOURK_BUF); + // initialize der + if(wc_SetSubjectBuffer(&myCert, der, FOURK_BUF) != 0) { + // error setting subject + } + \endcode + + \sa wc_InitCert + \sa wc_SetSubject +*/ +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 + method is used to set fields prior to signing. + + \return 0 Returned on successfully setting the alternate names 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 + header file + \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 + encryption specification of the cert file + \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 + expiration date + \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 + from the certificate + \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 + key object id + \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 + certificate extension + \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 + same as the encryption type of the certificate in the provided file + \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 + permitted by the CA name constraints + \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 + from which to grab the alternate names + \param derSz size of the buffer containing the der formatted certificate + from which to grab the alternate names + + _Example_ + \code + Cert myCert; + // initialize myCert + byte* der; + der = (byte*)malloc(FOURK_BUF); + // initialize der + if(wc_SetAltNamesBuffer(&myCert, der, FOURK_BUF) != 0) { + // error setting subject + } + \endcode + + \sa wc_InitCert + \sa wc_SetAltNames +*/ +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 + to signing. + + \return 0 Returned on successfully setting the dates 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 + header file + \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 + encryption specification of the cert file + \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 + expiration date + \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 + from the certificate + \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 + key object id + \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 + certificate extension + \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 same as the encryption type of the certificate in the provided file + \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 + permitted by the CA name constraints + \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 + from which to grab the date range + \param derSz size of the buffer containing the der formatted certificate + from which to grab the date range + + _Example_ + \code + Cert myCert; + // initialize myCert + byte* der; + der = (byte*)malloc(FOURK_BUF); + // initialize der + if(wc_SetDatesBuffer(&myCert, der, FOURK_BUF) != 0) { + // 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 + 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. + + _Example_ + \code + Cert myCert; + RsaKey keypub; + + wc_InitRsaKey(&keypub, 0); + + if (wc_SetAuthKeyIdFromPublicKey(&myCert, &keypub, NULL) != 0) + { + // Handle error + } + \endcode + + \sa wc_SetSubjectKeyId + \sa wc_SetAuthKeyId + \sa wc_SetAuthKeyIdFromCert +*/ +WOLFSSL_API int wc_SetAuthKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey, + ecc_key *eckey); +/*! + \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. + + _Example_ + \code + Cert some_cert; + byte some_der[] = { // Initialize a DER buffer }; + wc_InitCert(&some_cert); + if(wc_SetAuthKeyIdFromCert(&some_cert, some_der, sizeof(some_der) != 0) + { + // Handle error + } + \endcode + + \sa wc_SetAuthKeyIdFromPublicKey + \sa wc_SetAuthKeyId +*/ +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. + + _Example_ + \code + char* file_name = "/path/to/file"; + cert some_cert; + wc_InitCert(&some_cert); + + if(wc_SetAuthKeyId(&some_cert, file_name) != 0) + { + // Handle Error + } + \endcode + + \sa wc_SetAuthKeyIdFromPublicKey + \sa wc_SetAuthKeyIdFromCert +*/ +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 eckey Pointer to an ecc_key structure + + _Example_ + \code + Cert some_cert; + RsaKey some_key; + wc_InitCert(&some_cert); + wc_InitRsaKey(&some_key); + + if(wc_SetSubjectKeyIdFromPublicKey(&some_cert,&some_key, NULL) != 0) + { + // 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 + 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"; + Cert some_cert; + wc_InitCert(&some_cert); + + if(wc_SetSubjectKeyId(&some_cert, file_name) != 0) + { + // Handle Error + } + \endcode + + \sa wc_SetSubjectKeyIdFromNtruPublicKey + \sa wc_SetSubjectKeyIdFromPublicKey +*/ +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; + wc_InitCert(&some_cert); + byte some_ntru_key[] = { // Load an NTRU key }; + word32 ntru_size = sizeof(some_ntru_key); + + 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 + 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; + wc_InitCert(&cert); + + if(wc_SetKeyUsage(&cert, "cRLSign,keyCertSign") != 0) + { + // Handle error + } + \endcode + + \sa wc_InitCert + \sa wc_MakeRsaKey + */ +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 + with wc_InitCert before this method is called. + + \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 + with XMALLOC + \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 + generation is not successful. + + \param cert pointer to an initialized cert structure + \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 + certificate + \param keySz size of the key used to generate the NTRU certificate + \param rng pointer to the random number generator used to generate + the NTRU certificate + + _Example_ + \code + Cert myCert; + // initialize myCert + RNG rng; + //initialize rng; + byte ntruPublicKey[NTRU_KEY_SIZE]; + //initialize ntruPublicKey; + byte * derCert = malloc(FOURK_BUF); + + word32 certSz; + 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 Keys + + \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. + \return MEMORY_E There is an error allocating memory for the file buffer. + \return BUFFER_E derBuf is not large enough to hold the converted key. + + \param fileName Name of the file to load. + \param derBuf Buffer for DER encoded key. + \param derSz Size of DER buffer. + + _Example_ + \code + char* some_file = "filename"; + unsigned char der[]; + + if(wolfSSL_PemPubKeyToDer(some_file, der, sizeof(der)) != 0) + { + //Handle Error + } + \endcode + + \sa wolfSSL_PubKeyPemToDer +*/ + WOLFSSL_API int wolfSSL_PemPubKeyToDer(const char* fileName, + unsigned char* derBuf, int derSz); +/*! + \ingroup Keys + + \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(wolfSSL_PubKeyPemToDer(some_pem, sizeof(some_pem), out_buffer, + sizeof(out_buffer)) < 0) + { + // Handle error + } + \endcode + + \sa wolfSSL_PemPubKeyToDer +*/ + WOLFSSL_API int wolfSSL_PubKeyPemToDer(const unsigned char*, int, + unsigned char*, int); +/*! + \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 + formatted output. + + \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 + and storing it as a pem file + \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 + 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 + formatted certificate + \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: + CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE. + + _Example_ + \code + byte* der; + // initialize der with certificate + byte* pemFormatted[FOURK_BUF]; + + word32 pemSz; + pemSz = wc_DerToPem(der, derSz,pemFormatted,FOURK_BUF, CERT_TYPE); + \endcode + + \sa wolfSSL_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 + pem formatted output. Allows setting cipher info. + + \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 + and storing it as a pem file + \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 + 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 + formatted certificate + \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: + CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE. + + _Example_ + \code + byte* der; + // initialize der with certificate + byte* pemFormatted[FOURK_BUF]; + + word32 pemSz; + byte* cipher_info[] { Additional cipher info. } + pemSz = wc_DerToPemEx(der, derSz,pemFormatted,FOURK_BUF, ,CERT_TYPE); + \endcode + + \sa wolfSSL_PemCertToDer +*/ + WOLFSSL_API int wc_DerToPemEx(const byte* der, word32 derSz, byte* output, + word32 outputSz, byte *cipherIno, int type); +/*! + \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, + which it stores in key. + + \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 + and storing it as a pem file + \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 + the specified max certificate size + \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 + 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 + 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 + 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 + the buffer at which to start + \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 + + byte* tmp; // tmp buffer to read key from + tmp = (byte*) malloc(FOURK_BUF); + + int inSz; + inSz = fread(tmp, 1, FOURK_BUF, privateKeyFile); + // read key into tmp buffer + + wc_ecc_init(&key); // initialize key + ret = wc_Ecc_PrivateKeyDecode(tmp, &idx, &key, (word32)inSz); + if(ret < 0) { + // 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, + 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 + with XMALLOC + \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 + 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 + 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 + der formatted key + + _Example_ + \code + int derSz; + ecc_key key; + // initialize and make key + byte der[FOURK_BUF]; + // store der formatted key here + + derSz = wc_EccKeyToDer(&key, der, FOURK_BUF); + if(derSz < 0) { + // 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 + 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. + 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, + 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; + word32 idx = 0; + byte buff[] = { // initialize with key }; + ecc_key pubKey; + wc_ecc_init_key(&pubKey); + if ( wc_EccPublicKeyDecode(buff, &idx, &pubKey, sizeof(buff)) != 0) { + // 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 + 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 + Algorithm and Curve information. + + _Example_ + \code + ecc_key key; + wc_ecc_init(&key); + WC_RNG rng; + wc_InitRng(&rng); + wc_ecc_make_key(&rng, 24, &key); + int derSz = // Some appropriate size for der; + byte der[derSz]; + + if(wc_EccPublicKeyToDer(&key, der, derSz, 1) < 0) + { + // 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, + and returns the size of the encoded signature created. + + \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. + + \endcode + \code + int signSz; + byte encodedSig[MAX_ENCODED_SIG_SZ]; + Sha256 sha256; + // initialize sha256 for hashing + + byte* dig = = (byte*)malloc(SHA256_DIGEST_SIZE); + // perform hashing and hash updating so dig stores SHA-256 hash + // (see wc_InitSha256, wc_Sha256Update and wc_Sha256Final) + signSz = wc_EncodeSignature(encodedSig, dig, SHA256_DIGEST_SIZE,SHA256h); + \endcode + + \sa none +*/ +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 + identifier corresponding to a SHA512 hash, SHA512h. + + \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, + SHA384, and SHA512. + + _Example_ + \code + int hashOID; + + hashOID = wc_GetCTC_HashOID(SHA512); + if (hashOID == 0) { + // 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 new file mode 100644 index 000000000..7699b7cb9 --- /dev/null +++ b/doc/dox_comments/header_files/blake2.h @@ -0,0 +1,93 @@ +/*! + \ingroup BLAKE2 + + \brief This function initializes a Blake2b structure for use with the + Blake2 hash function. + + \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); + \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 + one is ready for the final hash: wc_Blake2bFinal. + + \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); + + byte plain[] = { // initialize input }; + + ret = wc_Blake2bUpdate(&b2b, plain, sizeof(plain)); + if( ret != 0) { + // error updating blake2b + } + \endcode + + \sa wc_InitBlake2b + \sa wc_Blake2bFinal +*/ +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 + 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. + Should be of length requestSz + \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); + ... // call wc_Blake2bUpdate to add data to hash + + ret = 2c_Blake2bFinal(&b2b, hash, 64); + if( ret != 0) { + // error generating blake2b hash + } + \endcode + + \sa wc_InitBlake2b + \sa wc_Blake2bUpdate +*/ +WOLFSSL_API int wc_Blake2bFinal(Blake2b*, byte*, word32); diff --git a/doc/dox_comments/header_files/bn.h b/doc/dox_comments/header_files/bn.h new file mode 100644 index 000000000..e3dcf1bde --- /dev/null +++ b/doc/dox_comments/header_files/bn.h @@ -0,0 +1,28 @@ +/*! + \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; + int ret; + // set big number values + ret = wolfSSL_BN_mod_exp(r, a, p, m, NULL); + // check ret value + \endcode + + \sa wolfSSL_BN_new + \sa wolfSSL_BN_free +*/ +WOLFSSL_API int wolfSSL_BN_mod_exp(WOLFSSL_BIGNUM *r, const WOLFSSL_BIGNUM *a, + const WOLFSSL_BIGNUM *p, const WOLFSSL_BIGNUM *m, WOLFSSL_BN_CTX *ctx); diff --git a/doc/dox_comments/header_files/camellia.h b/doc/dox_comments/header_files/camellia.h new file mode 100644 index 000000000..485281ec0 --- /dev/null +++ b/doc/dox_comments/header_files/camellia.h @@ -0,0 +1,179 @@ +/*! + \ingroup Camellia + + \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 + vector + \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 + 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 + 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 + vector for use with this camellia structure + + _Example_ + \code + Camellia cam; + byte key[32]; + // initialize key + byte iv[16]; + // initialize iv + if( wc_CamelliaSetKey(&cam, key, sizeof(key), iv) != 0) { + // error initializing camellia structure + } + \endcode + + \sa wc_CamelliaEncryptDirect + \sa wc_CamelliaDecryptDirect + \sa wc_CamelliaCbcEncrypt + \sa wc_CamelliaCbcDecrypt +*/ +WOLFSSL_API int wc_CamelliaSetKey(Camellia* cam, + const byte* key, word32 len, const byte* iv); +/*! + \ingroup Camellia + + \brief This function sets the initialization vector for a camellia object. + + \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 + 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 + vector for use with this camellia structure + + _Example_ + \code + Camellia cam; + byte iv[16]; + // initialize iv + 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. + + \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_CamelliaEncrypt(&ca, cipher, plain); + \endcode + + \sa wc_CamelliaDecryptDirect +*/ +WOLFSSL_API int wc_CamelliaEncryptDirect(Camellia* cam, byte* out, + const byte* in); +/*! + \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 + 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 + plaintext block + \param in pointer to the buffer containing the ciphertext block to decrypt + + _Example_ + \code + Camellia cam; + // initialize cam structure with key and iv + byte cipher[] = { // initialize with encrypted message to decrypt }; + byte decrypted[16]; + + wc_CamelliaDecryptDirect(&cam, decrypted, cipher); + \endcode + + \sa wc_CamelliaEncryptDirect +*/ +WOLFSSL_API int wc_CamelliaDecryptDirect(Camellia* cam, byte* out, + const byte* in); +/*! + \ingroup Camellia + + \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 + 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 + \param sz the size of the message to encrypt + + _Example_ + \code + Camellia cam; + // initialize cam structure with key and iv + byte cipher[] = { // initialize with encrypted message to decrypt }; + byte decrypted[sizeof(cipher)]; + + wc_CamelliaCbcDecrypt(&cam, decrypted, cipher, sizeof(cipher)); + \endcode + + \sa wc_CamelliaCbcEncrypt +*/ +WOLFSSL_API int wc_CamelliaCbcDecrypt(Camellia* cam, + byte* out, const byte* in, word32 sz); diff --git a/doc/dox_comments/header_files/chacha.h b/doc/dox_comments/header_files/chacha.h new file mode 100644 index 000000000..eb876de1e --- /dev/null +++ b/doc/dox_comments/header_files/chacha.h @@ -0,0 +1,97 @@ +/*! + \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 + 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 + 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 + vector with which to initialize the ChaCha structure + \param counter the value at which the block counter should start--usually + zero. + + _Example_ + \code + ChaCha enc; + // initialize enc with wc_Chacha_SetKey + byte iv[12]; + // initialize iv + if( wc_Chacha_SetIV(&enc, iv, 0) != 0) { + // error initializing ChaCha structure + } + \endcode + + \sa wc_Chacha_SetKey + \sa wc_Chacha_Process +*/ +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 + 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 + 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 + or decrypted plaintext + \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 + + _Example_ + \code + ChaCha enc; + // initialize enc with wc_Chacha_SetKey and wc_Chacha_SetIV + + byte plain[] = { // initialize plaintext }; + byte cipher[sizeof(plain)]; + if( wc_Chacha_Process(&enc, cipher, plain, sizeof(plain)) != 0) { + // error processing ChaCha cipher + } + \endcode + + \sa wc_Chacha_SetKey + \sa wc_Chacha_Process +*/ +WOLFSSL_API int wc_Chacha_Process(ChaCha* ctx, byte* cipher, const byte* plain, + word32 msglen); +/*! + \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 + 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 + 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 + 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) { + // error initializing ChaCha structure + } + \endcode + + \sa wc_Chacha_SetIV + \sa wc_Chacha_Process +*/ +WOLFSSL_API int wc_Chacha_SetKey(ChaCha* ctx, const byte* key, word32 keySz); diff --git a/doc/dox_comments/header_files/chacha20_poly1305.h b/doc/dox_comments/header_files/chacha20_poly1305.h new file mode 100644 index 000000000..7b3ae5876 --- /dev/null +++ b/doc/dox_comments/header_files/chacha20_poly1305.h @@ -0,0 +1,119 @@ +/*! + \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 + 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 + process + + \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 + encryption + \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 + 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 + authentication tag + + _Example_ + \code + byte key[] = { // initialize 32 byte key }; + byte iv[] = { // initialize 12 byte key }; + byte inAAD[] = { // initialize AAD }; + + byte plain[] = { // initialize message to encrypt }; + byte cipher[sizeof(plain)]; + byte authTag[16]; + + int ret = wc_ChaCha20Poly1305_Encrypt(key, iv, inAAD, sizeof(inAAD), + plain, sizeof(plain), cipher, authTag); + + if(ret != 0) { + // error running encrypt + } + \endcode + + \sa wc_ChaCha20Poly1305_Decrypt + \sa wc_ChaCha_* + \sa wc_Poly1305* +*/ +WOLFSSL_API +int wc_ChaCha20Poly1305_Encrypt( + const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE], + const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE], + const byte* inAAD, const word32 inAADLen, + const byte* inPlaintext, const word32 inPlaintextLen, + byte* outCiphertext, + 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 + 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 + match what is expected + \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 + decryption + \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 + authenticated data (AAD) + \param inAADLen length of the input AAD + \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 + for authentication + \param outPlaintext pointer to the buffer in which to store the plaintext + + _Example_ + \code + byte key[] = { // initialize 32 byte key }; + byte iv[] = { // initialize 12 byte key }; + byte inAAD[] = { // initialize AAD }; + + byte cipher[] = { // initialize with received ciphertext }; + byte authTag[16] = { // initialize with received authentication tag }; + + byte plain[sizeof(cipher)]; + + int ret = wc_ChaCha20Poly1305_Decrypt(key, iv, inAAD, sizeof(inAAD), + cipher, sizeof(cipher), plain, authTag); + + if(ret == MAC_CMP_FAILED_E) { + // error during authentication + } else if( ret != 0) { + // error with function arguments + } + \endcode + + \sa wc_ChaCha20Poly1305_Encrypt + \sa wc_ChaCha_* + \sa wc_Poly1305* +*/ +WOLFSSL_API +int wc_ChaCha20Poly1305_Decrypt( + const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE], + const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE], + const byte* inAAD, const word32 inAADLen, + const byte* inCiphertext, const word32 inCiphertextLen, + const byte inAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE], + byte* outPlaintext); diff --git a/doc/dox_comments/header_files/coding.h b/doc/dox_comments/header_files/coding.h new file mode 100644 index 000000000..9ab6ad2a4 --- /dev/null +++ b/doc/dox_comments/header_files/coding.h @@ -0,0 +1,228 @@ +/*! + \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 + 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 + 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 + 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 + message + \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)]; + // requires at least (sizeof(encoded) * 3 + 3) / 4 room + + int outLen = sizeof(decoded); + + if( Base64_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) { + // error decoding input buffer + } + \endcode + + \sa Base64_Encode + \sa Base16_Decode +*/ +WOLFSSL_API int Base64_Decode(const byte* in, word32 inLen, byte* out, + word32* outLen); +/*! + \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 + 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 + store the encoded input + \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 + encoded message + \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]; + + int outLen = sizeof(encoded); + + if( Base64_Encode(plain, sizeof(plain), encoded, &outLen) != 0 ) { + // error encoding input buffer + } + \endcode + + \sa Base64_EncodeEsc + \sa Base64_Decode +*/ + WOLFSSL_API + int Base64_Encode(const byte* in, word32 inLen, byte* out, + word32* outLen); +/*! + \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 + 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 store the encoded input + \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 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 encoded message + \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]; + + int outLen = sizeof(encoded); + + if( Base64_EncodeEsc(plain, sizeof(plain), encoded, &outLen) != 0 ) { + // error encoding input buffer + } + \endcode + + \sa Base64_Encode + \sa Base64_Decode +*/ + int Base64_EncodeEsc(const byte* in, word32 inLen, byte* out, + word32* outLen); +/*! + \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 + 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 store the encoded input + \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 + 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 + encoded message + \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]; + int outLen = sizeof(encoded); + if( Base64_Encode_NoNl(plain, sizeof(plain), encoded, &outLen) != 0 ) { + // error encoding input buffer + } + \endcode + + \sa Base64_Encode + \sa Base64_Decode +*/ + WOLFSSL_API + int Base64_Encode_NoNl(const byte* in, word32 inLen, byte* out, + word32* outLen); +/*! + \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 + 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 + 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 + 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 + message + \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)]; + int outLen = sizeof(decoded); + + if( Base16_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) { + // error decoding input buffer + } + \endcode + + \sa Base64_Encode + \sa Base64_Decode + \sa Base16_Encode +*/ + WOLFSSL_API + 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 + 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. + \param outLen Length of output buffer. Is set to len of encoded output. + + _Example_ + \code + byte in[] = { // Contents of something to be encoded }; + byte out[NECESSARY_OUTPUT_SIZE]; + word32 outSz = sizeof(out); + + if(Base16_Encode(in, sizeof(in), out, &outSz) != 0) + { + // Handle encode error + } + \endcode + + \sa Base64_Encode + \sa Base64_Decode + \sa Base16_Decode +*/ + WOLFSSL_API + int Base16_Encode(const byte* in, word32 inLen, byte* out, word32* outLen); diff --git a/doc/dox_comments/header_files/compress.h b/doc/dox_comments/header_files/compress.h new file mode 100644 index 000000000..8ed438ad4 --- /dev/null +++ b/doc/dox_comments/header_files/compress.h @@ -0,0 +1,71 @@ +/*! + \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 + the output buffer. + + \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 + 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 + data + \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 + decompression + + _Example_ + \code + byte message[] = { // initialize text to compress }; + 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){ + // 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 + coding and stores the output in out. + + \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 + 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 + data + \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]; + + 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 new file mode 100644 index 000000000..45a8954bd --- /dev/null +++ b/doc/dox_comments/header_files/curve25519.h @@ -0,0 +1,678 @@ +/*! + \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 + structure has been initialized through wc_curve25519_init. + + \return 0 Returned on successfully generating the key and and storing + it in the given curve25519_key structure + \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 + 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 + store the generated key + + _Example_ + \code + curve25519_key key; + wc_curve25519_init(&key); // initialize key + RNG rng; + wc_InitRng(&rng); // initialize random number generator + + if( wc_curve25519_make_key(&rng, 32, &key) != 0) { + // making 25519 key + } + \endcode + + \sa wc_curve25519_init +*/ +WOLFSSL_API +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 + supports big endian. + + \return 0 Returned on successfully computing a shared secret key + \return BAD_FUNC_ARG Returned if any of the input parameters passed in + are NULL + \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 + with the user’s private key + \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 + secret key + \param outlen pointer in which to store the length written to the + output buffer + + _Example_ + \code + byte sharedKey[32]; + word32 keySz; + curve25519_key privKey, pubKey; + // initialize both keys + + 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 +*/ +WOLFSSL_API +int wc_curve25519_shared_secret(curve25519_key* private_key, + curve25519_key* public_key, + byte* out, word32* outlen); +/*! + \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 + both big and little endian. + + \return 0 Returned on successfully computing a shared secret key + \return BAD_FUNC_ARG Returned if any of the input parameters passed in + are NULL + \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 + with the user’s private key + \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 + secret key + \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 + form to use. + + _Example_ + \code + byte sharedKey[32]; + word32 keySz; + + curve25519_key privKey, pubKey; + // initialize both keys + + 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 +*/ +WOLFSSL_API +int wc_curve25519_shared_secret_ex(curve25519_key* private_key, + curve25519_key* public_key, + byte* out, word32* outlen, int endian); +/*! + \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 + before using the key to encrypt data. + + \return 0 Returned on successfully initializing the curve25519_key + structure + + \param key pointer to the curve25519_key structure to initialize + + _Example_ + \code + curve25519_key key; + wc_curve25519_init(&key); // initialize key + // make key and proceed to encryption + \endcode + + \sa wc_curve25519_make_key +*/ +WOLFSSL_API +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; + // initialize key, use it to generate shared secret key + wc_curve25519_free(&privKey); + \endcode + + \sa wc_curve25519_init + \sa wc_curve25519_make_key +*/ +WOLFSSL_API +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 + 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. + + _Example_ + \code + byte priv[] = { Contents of private key }; + curve25519_key key; + wc_curve25519_init(&key); + + if(wc_curve25519_import_private(priv, sizeof(priv), &key) != 0) + { + // Some error was thrown + } + \endcode + + \sa wc_curve25519_import_private_ex + \sa wc_curve25519_size +*/ +WOLFSSL_API +int wc_curve25519_import_private(const byte* priv, word32 privSz, + curve25519_key* key); +/*! + \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 + 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 + set which form to use. + + _Example_ + \code + byte priv[] = { // Contents of private key }; + curve25519_key key; + wc_curve25519_init(&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 +*/ +WOLFSSL_API +int wc_curve25519_import_private_ex(const byte* priv, word32 privSz, + curve25519_key* key, int endian); +/*! + \ingroup Curve25519 + + \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 + 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 + + _Example_ + \code + int ret; + + byte priv[32]; + byte pub[32]; + // initialize with public and private keys + curve25519_key key; + + wc_curve25519_init(&key); + // initialize key + + 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 +*/ +WOLFSSL_API +int wc_curve25519_import_private_raw(const byte* priv, word32 privSz, + const byte* pub, word32 pubSz, curve25519_key* key); +/*! + \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, + 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 + which form to use. + + _Example_ + \code + int ret; + byte priv[32]; + byte pub[32]; + // initialize with public and private keys + curve25519_key key; + + wc_curve25519_init(&key); + // initialize key + + ret = wc_curve25519_import_private_raw_ex(&priv, sizeof(priv), pub, + sizeof(pub),&key, EC25519_BIG_ENDIAN); + 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_rawm + \sa wc_curve25519_import_private_raw +*/ +WOLFSSL_API +int wc_curve25519_import_private_raw_ex(const byte* priv, word32 privSz, + const byte* pub, word32 pubSz, + curve25519_key* key, int endian); +/*! + \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 + of the exported key. Big Endian only. + + \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 + + _Example_ + \code + int ret; + byte priv[32]; + int privSz; + + curve25519_key key; + // initialize and make key + + ret = wc_curve25519_export_private_raw(&key, priv, &privSz); + if (ret != 0) { + // error exporting key + } + \endcode + + \sa wc_curve25519_init + \sa wc_curve25519_make_key + \sa wc_curve25519_import_private_raw + \sa wc_curve25519_export_private_raw_ex +*/ +WOLFSSL_API +int wc_curve25519_export_private_raw(curve25519_key* key, byte* out, + word32* outLen); +/*! + \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 + of the exported key. Can specify whether it's big or little endian. + + \return 0 Returned on successfully exporting the private key from the + curve25519_key structure + \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 + \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which + form to use. + + _Example_ + \code + int ret; + + byte priv[32]; + int privSz; + curve25519_key key; + // initialize and make key + ret = wc_curve25519_export_private_raw_ex(&key, priv, &privSz, + EC25519_BIG_ENDIAN); + if (ret != 0) { + // error exporting key + } + \endcode + + \sa wc_curve25519_init + \sa wc_curve25519_make_key + \sa wc_curve25519_import_private_raw + \sa wc_curve25519_export_private_raw + \sa wc_curve25519_size +*/ +WOLFSSL_API +int wc_curve25519_export_private_raw_ex(curve25519_key* key, byte* out, + word32* outLen, int endian); +/*! + \ingroup Curve25519 + + \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 + curve25519_key structure + \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 + the key + + _Example_ + \code + int ret; + + byte pub[32]; + // initialize pub with public key + + curve25519_key key; + // initialize key + + ret = wc_curve25519_import_public(pub,sizeof(pub), &key); + if (ret != 0) { + // error exporting key + } + \endcode + + \sa wc_curve25519_init + \sa wc_curve25519_export_public + \sa wc_curve25519_import_private_raw + \sa wc_curve25519_public_ex +*/ +WOLFSSL_API +int wc_curve25519_import_public(const byte* in, word32 inLen, + curve25519_key* key); +/*! + \ingroup Curve25519 + + \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 + curve25519_key structure + \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 + the key + \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which + form to use. + + _Example_ + \code + int ret; + byte pub[32]; + // initialize pub with public key + curve25519_key key; + // initialize key + + ret = wc_curve25519_import_public_ex(pub,sizeof(pub), &key, + EC25519_BIG_ENDIAN); + if (ret != 0) { + // error exporting key + } + \endcode + + \sa wc_curve25519_init + \sa wc_curve25519_export_public + \sa wc_curve25519_import_private_raw + \sa wc_curve25519_import_public + \sa wc_25519_size +*/ +WOLFSSL_API +int wc_curve25519_import_public_ex(const byte* in, word32 inLen, + curve25519_key* key, int endian); +/*! + \ingroup Curve25519 + + \brief This function exports a public key from the given key structure and + stores the result in the out buffer. Big endian only. + + \return 0 Returned on successfully exporting the public key from the + curve25519_key structure + \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL + + \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; + byte pub[32]; + int pubSz; + curve25519_key key; + // initialize and make key + ret = wc_curve25519_export_public(&key,pub, &pubSz); + if (ret != 0) { + // error exporting key + } + \endcode + + \sa wc_curve25519_init + \sa wc_curve25519_export_private_raw + \sa wc_curve25519_import_public +*/ +WOLFSSL_API +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 + stores the result in the out buffer. Supports both big and little endian. + + \return 0 Returned on successfully exporting the public key from the + curve25519_key structure + \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 + 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 + form to use. + + _Example_ + \code + int ret; + + byte pub[32]; + int pubSz; + curve25519_key key; + // initialize and make key + + ret = wc_curve25519_export_public_ex(&key,pub, &pubSz, EC25519_BIG_ENDIAN); + if (ret != 0) { + // error exporting key + } + \endcode + + \sa wc_curve25519_init + \sa wc_curve25519_export_private_raw + \sa wc_curve25519_import_public +*/ +WOLFSSL_API +int wc_curve25519_export_public_ex(curve25519_key* key, byte* out, + word32* outLen, int endian); +/*! + \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; + byte pub[32]; + byte priv[32]; + int pubSz; + int privSz; + + curve25519_key key; + // initialize and make key + + ret = wc_curve25519_export_key_raw(&key, priv, &privSz, pub, &pubSz); + if (ret != 0) { + // error exporting key + } + \endcode + + \sa wc_curve25519_export_key_raw_ex + \sa wc_curve25519_export_private_raw + \sa wc_curve25519_export_public_raw +*/ +WOLFSSL_API +int wc_curve25519_export_key_raw(curve25519_key* key, + byte* priv, word32 *privSz, + byte* pub, word32 *pubSz); +/*! + \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 + form to use. + + _Example_ + \code + int ret; + + byte pub[32]; + byte priv[32]; + int pubSz; + int privSz; + + curve25519_key key; + // initialize and make key + + 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 +*/ +WOLFSSL_API +int wc_curve25519_export_key_raw_ex(curve25519_key* key, + byte* priv, word32 *privSz, + byte* pub, word32 *pubSz, + int endian); +/*! + \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 0 Returned if key is NULL + + \param key pointer to the curve25519_key structure in for which to + determine the key size + + _Example_ + \code + curve25519_key key; + // initialize and make key + int keySz; + keySz = wc_curve25519_size(&key); + \endcode + + \sa wc_curve25519_init + \sa wc_curve25519_make_key +*/ +WOLFSSL_API +int wc_curve25519_size(curve25519_key* key); diff --git a/doc/dox_comments/header_files/des3.h b/doc/dox_comments/header_files/des3.h new file mode 100644 index 000000000..59a45479d --- /dev/null +++ b/doc/dox_comments/header_files/des3.h @@ -0,0 +1,323 @@ +/*! + \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) + the initialization vector defaults to an iv of 0. + + \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 + initialize the Des structure + \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, + and DES_DECRYPTION + + _Example_ + \code + Des enc; // Des structure used for encryption + int ret; + byte key[] = { // initialize with 8 byte key }; + byte iv[] = { // initialize with 8 byte iv }; + + ret = wc_Des_SetKey(&des, key, iv, DES_ENCRYPTION); + if (ret != 0) { + // error initializing des structure + } + \endcode + + \sa wc_Des_SetIV + \sa wc_Des3_SetKey +*/ +WOLFSSL_API int wc_Des_SetKey(Des* des, const byte* key, + const byte* iv, int dir); +/*! + \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 + 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 + initialize the Des structure. If this is not provided, the iv defaults to 0 + + _Example_ + \code + Des enc; // Des structure used for encryption + // initialize enc with wc_Des_SetKey + byte iv[] = { // initialize with 8 byte iv }; + 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 + 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 + \param sz length of the message to encrypt + + _Example_ + \code + Des enc; // Des structure used for encryption + // initialize enc with wc_Des_SetKey, use mode DES_ENCRYPTION + + byte plain[] = { // initialize with message }; + byte cipher[sizeof(plain)]; + + if ( wc_Des_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) { + // error encrypting message + } + \endcode + + \sa wc_Des_SetKey + \sa wc_Des_CbcDecrypt +*/ +WOLFSSL_API int wc_Des_CbcEncrypt(Des* des, byte* out, + const byte* in, word32 sz); +/*! + \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. + + \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 + // initialize dec with wc_Des_SetKey, use mode DES_DECRYPTION + + byte cipher[] = { // initialize with ciphertext }; + byte decoded[sizeof(cipher)]; + + if ( wc_Des_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) { + // error decrypting message + } + \endcode + + \sa wc_Des_SetKey + \sa wc_Des_CbcEncrypt +*/ +WOLFSSL_API int wc_Des_CbcDecrypt(Des* des, byte* out, + const byte* in, word32 sz); +/*! + \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 + 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 + \param sz length of the plaintext to encrypt + + _Example_ + \code + Des enc; // Des structure used for encryption + // initialize enc with wc_Des_SetKey, use mode DES_ENCRYPTION + + byte plain[] = { // initialize with message to encrypt }; + byte cipher[sizeof(plain)]; + + 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, + const byte* in, word32 sz); +/*! + \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 + 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 + \param sz length of the plaintext to encrypt + + _Example_ + /code + Des3 enc; // Des3 structure used for encryption + // initialize enc with wc_Des3_SetKey, use mode DES_ENCRYPTION + + byte plain[] = { // initialize with message to encrypt }; + byte cipher[sizeof(plain)]; + + 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, + const byte* in, word32 sz); +/*! + \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 == + NULL) the initialization vector defaults to an iv of 0. + + \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 + 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 + to 0 + \param dir direction of encryption. Valid options are: DES_ENCRYPTION, + and DES_DECRYPTION + + _Example_ + \code + Des3 enc; // Des3 structure used for encryption + int ret; + byte key[] = { // initialize with 24 byte key }; + byte iv[] = { // initialize with 8 byte iv }; + + ret = wc_Des3_SetKey(&des, key, iv, DES_ENCRYPTION); + if (ret != 0) { + // error initializing des structure + } + \endcode + + \sa wc_Des3_SetIV + \sa wc_Des3_CbcEncrypt + \sa wc_Des3_CbcDecrypt +*/ +WOLFSSL_API int wc_Des3_SetKey(Des3* des, const byte* key, + const byte* iv,int dir); +/*! + \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 + 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 + defaults to 0 + + _Example_ + \code + Des3 enc; // Des3 structure used for encryption + // initialize enc with wc_Des3_SetKey + + byte iv[] = { // initialize with 8 byte iv }; + + 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 + 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 + // initialize enc with wc_Des3_SetKey, use mode DES_ENCRYPTION + + byte plain[] = { // initialize with message }; + byte cipher[sizeof(plain)]; + + if ( wc_Des3_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) { + // error encrypting message + } + \endcode + + \sa wc_Des3_SetKey + \sa wc_Des3_CbcDecrypt +*/ +WOLFSSL_API int wc_Des3_CbcEncrypt(Des3* des, byte* out, + const byte* in,word32 sz); +/*! + \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. + + \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 + // initialize dec with wc_Des3_SetKey, use mode DES_DECRYPTION + + byte cipher[] = { // initialize with ciphertext }; + byte decoded[sizeof(cipher)]; + + if ( wc_Des3_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) { + // error decrypting message + } + \endcode + + \sa wc_Des3_SetKey + \sa wc_Des3_CbcEncrypt +*/ +WOLFSSL_API int wc_Des3_CbcDecrypt(Des3* des, byte* out, + const byte* in,word32 sz); diff --git a/doc/dox_comments/header_files/dh.h b/doc/dox_comments/header_files/dh.h new file mode 100644 index 000000000..3c8a696ee --- /dev/null +++ b/doc/dox_comments/header_files/dh.h @@ -0,0 +1,267 @@ +/*! + \ingroup Diffie-Hellman + + \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 + secure key exchanges + + _Example_ + \code + DhKey key; + wc_InitDhKey(&key); // initialize DH key + \endcode + + \sa wc_FreeDhKey + \sa wc_DhGenerateKeyPair +*/ +WOLFSSL_API int wc_InitDhKey(DhKey* key); +/*! + \ingroup Diffie-Hellman + + \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; + // 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 + initialized rng structure. + + \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 + while generating the public key + \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 + library while generating the public key + \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 + the key pair + \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 + \param pub pointer to a buffer in which to store the public key + \param pubSz will store the size of the private key written to pub + + _Example_ + \code + DhKey key; + int ret; + byte priv[256]; + byte pub[256]; + word32 privSz, pubSz; + + wc_InitDhKey(&key); // initialize key + // Set DH parameters using wc_DhSetKey or wc_DhKeyDecode + RNG rng; + wc_InitRng(&rng); // initialize rng + ret = wc_DhGenerateKeyPair(&key, &rng, priv, &privSz, pub, &pubSz); + \endcode + + \sa wc_InitDhKey + \sa wc_DhSetKey + \sa wc_DhKeyDecode +*/ +WOLFSSL_API int wc_DhGenerateKeyPair(DhKey* key, WC_RNG* rng, byte* priv, + word32* privSz, byte* pub, word32* pubSz); +/*! + \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 + 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 + the shared secret key + \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 + the shared secret key + \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 + 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; + int ret; + byte priv[256]; + byte agree[256]; + word32 agreeSz; + + // 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, + sizeof(pub)); + if ( ret != 0 ) { + // error generating shared key + } + \endcode + + \sa wc_DhGenerateKeyPair +*/ +WOLFSSL_API int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz, + const byte* priv, word32 privSz, const byte* otherPub, + word32 pubSz); +/*! + \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 + DhKey structure. + + \return 0 Returned on successfully decoding the input key + \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 + key parameters from the parsed input + + \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 + 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 + be read + + _Example_ + \code + DhKey key; + word32 idx = 0; + + byte keyBuff[1024]; + // initialize with DER formatted key + wc_DhKeyInit(&key); + ret = wc_DhKeyDecode(keyBuff, &idx, &key, sizeof(keyBuff)); + + if ( ret != 0 ) { + // error decoding key + } + \endcode + + \sa wc_DhSetKey +*/ +WOLFSSL_API int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key, + word32); +/*! + \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 + 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 + 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 + DH key parameters p and g + + \param key pointer to the DhKey structure on which to set the key + \param p pointer to the buffer containing the prime for use with the 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; + + byte p[] = { // initialize with prime }; + byte g[] = { // initialize with base }; + wc_DhKeyInit(&key); + ret = wc_DhSetKey(key, p, sizeof(p), g, sizeof(g)); + + if ( ret != 0 ) { + // error setting key + } + \endcode + + \sa wc_DhKeyDecode +*/ +WOLFSSL_API int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g, + word32 gSz); +/*! + \ingroup Diffie-Hellman + + \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 + formatted DH certificate + \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 + 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 + 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 + the buffer after completing the function call + + _Example_ + \code + byte dhCert[] = { initialize with DER formatted certificate }; + byte p[MAX_DH_SIZE]; + byte g[MAX_DH_SIZE]; + word32 pSz = MAX_DH_SIZE; + word32 gSz = MAX_DH_SIZE; + + ret = wc_DhParamsLoad(dhCert, sizeof(dhCert), p, &pSz, g, &gSz); + if ( ret != 0 ) { + // error parsing inputs + } + \endcode + + \sa wc_DhSetKey + \sa wc_DhKeyDecode +*/ +WOLFSSL_API int wc_DhParamsLoad(const byte* input, word32 inSz, byte* p, + word32* pInOutSz, byte* g, word32* gInOutSz); diff --git a/doc/dox_comments/header_files/doxygen_groups.h b/doc/dox_comments/header_files/doxygen_groups.h new file mode 100644 index 000000000..e5a4975cf --- /dev/null +++ b/doc/dox_comments/header_files/doxygen_groups.h @@ -0,0 +1,47 @@ +/*! + \defgroup 3DES Algorithms - 3DES + \defgroup AES Algorithms - AES + \defgroup ARC4 Algorithms - ARC4 + \defgroup BLAKE2 Algorithms - BLAKE2 + \defgroup Camellia Algorithms - Camellia + \defgroup ChaCha Algorithms - ChaCha + \defgroup ChaCha20Poly1305 Algorithms - ChaCha20_Poly1305 + \defgroup Curve25519 Algorithms - Curve25519 + \defgroup DSA Algorithms - DSA + \defgroup Diffie-Hellman Algorithms - Diffie-Hellman + \defgroup ECC Algorithms - ECC + \defgroup ED25519 Algorithms - ED25519 + \defgroup HC128 Algorithms - HC-128 + \defgroup HMAC Algorithms - HMAC + \defgroup IDEA Algorithms - IDEA + \defgroup MD2 Algorithms - MD2 + \defgroup MD4 Algorithms - MD4 + \defgroup MD5 Algorithms - MD5 + \defgroup PKCS7 Algorithms - PKCS7 + \defgroup Password Algorithms - Password Based + \defgroup Poly1305 Algorithms - Poly1305 + \defgroup RIPEMD Algorithms - RIPEMD + \defgroup RSA Algorithms - RSA + \defgroup Rabbit Algorithms - Rabbit + \defgroup SHA Algorithms - SHA 128/224/256/384/512 + \defgroup SRP Algorithms - SRP + + \defgroup ASN ASN.1 + \defgroup Base_Encoding Base Encoding + \defgroup CertManager CertManager API + \defgroup Compression Compression + \defgroup Error Error Reporting + \defgroup Keys Key and Cert Conversion + \defgroup Logging Logging + \defgroup Math Math API + \defgroup Memory Memory Handling + \defgroup Random Random Number Generation + \defgroup Signature Signature API + \defgroup openSSL OpenSSL API + \defgroup wolfCrypt wolfCrypt Init and Cleanup + \defgroup TLS wolfSSL Initialization/Shutdown + \defgroup CertsKeys wolfSSL Certificates and Keys + \defgroup Setup wolfSSL Context and Session Set Up + \defgroup IO wolfSSL Connection, Session, and I/O + \defgroup Debug wolfSSL Error Handling and Reporting +*/ diff --git a/doc/dox_comments/header_files/dsa.h b/doc/dox_comments/header_files/dsa.h new file mode 100644 index 000000000..0c574b8c1 --- /dev/null +++ b/doc/dox_comments/header_files/dsa.h @@ -0,0 +1,334 @@ +/*! + \ingroup DSA + + \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; + // initialize key, use for authentication + ... + 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 + 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 + DSA signature. + \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 + DSA signature. + \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 + the DSA signature. + \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 + DSA signature. + \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 + the DSA signature. + \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 + 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 + generate the signature + \param rng pointer to an initialized RNG to use with the signature + generation + + _Example_ + \code + DsaKey key; + // initialize DSA key, load private Key + int ret; + RNG rng; + wc_InitRng(&rng); + byte hash[] = { // initialize with hash digest }; + byte signature[40]; // signature will be 40 bytes (320 bits) + + ret = wc_DsaSign(hash, signature, &key, &rng); + if (ret != 0) { + // error generating DSA signature + } + \endcode + + \sa wc_DsaVerify +*/ +WOLFSSL_API int wc_DsaSign(const byte* digest, byte* out, + DsaKey* key, WC_RNG* rng); +/*! + \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 + 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 + succeeded + \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 + DSA signature. + \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 DSA signature. + \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 + DSA signature. + \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 + DSA signature. + \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 + DSA signature. + \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 + verify the signature + \param answer pointer to an integer which will store whether the + verification was successful + + _Example_ + \code + DsaKey key; + // initialize DSA key, load public Key + + int ret; + int verified; + byte hash[] = { // initialize with hash digest }; + byte signature[] = { // initialize with signature to verify }; + ret = wc_DsaVerify(hash, signature, &key, &verified); + 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, + DsaKey* key, int* answer); +/*! + \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 + 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 + object + \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 + formatted + + \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 + 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 + + _Example_ + \code + int ret, idx=0; + + DsaKey key; + wc_InitDsaKey(&key); + byte derBuff[] = { // DSA public key}; + ret = wc_DsaPublicKeyDecode(derBuff, &idx, &key, inSz); + if (ret != 0) { + // error reading public key + } + \endcode + + \sa wc_InitDsaKey + \sa wc_DsaPrivateKeyDecode +*/ +WOLFSSL_API int wc_DsaPublicKeyDecode(const byte* input, word32* inOutIdx, + DsaKey*, word32); +/*! + \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 + 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 + object + \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 + formatted + + \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 + of the certificate read + \param key pointer to the DsaKey structure in which to store the private + key + \param inSz size of the input buffer + + _Example_ + \code + int ret, idx=0; + + DsaKey key; + wc_InitDsaKey(&key); + byte derBuff[] = { // DSA private key }; + ret = wc_DsaPrivateKeyDecode(derBuff, &idx, &key, inSz); + if (ret != 0) { + // error reading private key + } + \endcode + + \sa wc_InitDsaKey + \sa wc_DsaPublicKeyDecode +*/ +WOLFSSL_API int wc_DsaPrivateKeyDecode(const byte* input, word32* inOutIdx, + DsaKey*, word32); +/*! + \ingroup DSA + + \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 + DSA_PRIVATE. + \return MEMORY_E Error allocating memory. + + \param key Pointer to DsaKey structure to convert. + \param output Pointer to output buffer for converted key. + \param inLen Length of key input. + + _Example_ + \code + DsaKey key; + WC_RNG rng; + int derSz; + int bufferSize = // Sufficient buffer size; + byte der[bufferSize]; + + wc_InitDsaKey(&key); + wc_InitRng(&rng); + wc_MakeDsaKey(&rng, &key); + derSz = wc_DsaKeyToDer(&key, der, bufferSize); + \endcode + + \sa wc_InitDsaKey + \sa wc_FreeDsaKey + \sa wc_MakeDsaKey +*/ +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 MEMORY_E Couldn't allocate memory for buffer. + \return MP_INIT_E Error initializing mp_int + + \param rng Pointer to WC_RNG structure. + \param dsa Pointer to DsaKey structure. + + _Example_ + \code + WC_RNG rng; + DsaKey dsa; + wc_InitRng(&rng); + wc_InitDsa(&dsa); + if(wc_MakeDsaKey(&rng, &dsa) != 0) + { + // Error creating key + } + \endcode + + \sa wc_InitDsaKey + \sa wc_FreeDsaKey + \sa wc_DsaSign +*/ +WOLFSSL_API int wc_MakeDsaKey(WC_RNG *rng, DsaKey *dsa); +/*! + \ingroup DSA + + \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. + + \param rng pointer to wolfCrypt rng. + \param modulus_size 1024, 2048, or 3072 are valid values. + \param dsa Pointer to a DsaKey structure. + + _Example_ + \code + DsaKey key; + WC_RNG rng; + wc_InitDsaKey(&key); + wc_InitRng(&rng); + if(wc_MakeDsaParameters(&rng, 1024, &genKey) != 0) + { + // Handle error + } + \endcode + + \sa wc_MakeDsaKey + \sa wc_DsaKeyToDer + \sa wc_InitDsaKey +*/ +WOLFSSL_API int wc_MakeDsaParameters(WC_RNG *rng, int modulus_size, DsaKey *dsa); diff --git a/doc/dox_comments/header_files/ecc.h b/doc/dox_comments/header_files/ecc.h new file mode 100644 index 000000000..942351ef6 --- /dev/null +++ b/doc/dox_comments/header_files/ecc.h @@ -0,0 +1,1631 @@ +/*! + \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 + correct range of supported keys + \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 + the ecc key + \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 + ecc key + \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 + the ecc key + \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 + ecc key + \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 + the ecc key + \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 + ecc key + + \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 + + _Example_ + \code + ecc_key key; + wc_ecc_init(&key); + RNG rng; + 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 +*/ +WOLFSSL_API +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; + RNG rng; + int check_result; + wc_ecc_init(&key); + wc_InitRng(&rng); + wc_ecc_make_key(&rng, 32, &key); + check_result = wc_ecc_check_key(&key); + + if (check_result == MP_OKAY) + { + // key check succeeded + } + else + { + // key check failed + } + \endcode + + \sa wc_ecc_point_is_at_infinity +*/ +WOLFSSL_API +int wc_ecc_make_pub(ecc_key* key, ecc_point* pubOut); +/*! + \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 + buffer. + + \return 0 Returned upon successfully generating a shared secret key + \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 + 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 + to store in the provided buffer + \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 + shared key + \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 + the shared key + \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 + shared key + \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 + shared key + \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 + shared key + \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 + private key + \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 + 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 + buffer upon successfully generating a shared secret key + + _Example_ + \code + ecc_key priv, pub; + RNG rng; + byte secret[1024]; // can hold 1024 byte shared secret key + word32 secretSz = sizeof(secret); + int ret; + + wc_InitRng(&rng); // initialize rng + 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); + // generate secret key + if ( ret != 0 ) { + // error generating shared secret key + } + \endcode + + \sa wc_ecc_init + \sa wc_ecc_make_key +*/ +WOLFSSL_API +int wc_ecc_shared_secret(ecc_key* private_key, ecc_key* public_key, byte* out, + word32* outlen); +/*! + \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 + 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 + EC-DH from ANSI X9.63. + \param outlen Input the max size and output the resulting size of + the shared secret. + + _Example_ + \code + ecc_key key; + ecc_point* point; + byte shared_secret[]; + int secret_size; + int result; + + point = wc_ecc_new_point(); + + result = wc_ecc_shared_secret_ssh(&key, point, + &shared_secret, &secret_size); + + if (result != MP_OKAY) + { + // Handle error + } + \endcode + + \sa wc_ecc_verify_hash_ex +*/ +WOLFSSL_API +int wc_ecc_shared_secret_ex(ecc_key* private_key, ecc_point* point, + byte* out, word32 *outlen); +/*! + \ingroup ECC + + \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 + message digest + \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 + if the ECC OID is invalid + \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 message signature + \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 + message signature + \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 + the message signature + \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 + message signature + \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 + the message signature + \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 + 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 + written to out upon successfully generating a message signature + \param key pointer to a private ECC key with which to generate the + signature + + _Example_ + \code + ecc_key key; + RNG rng; + int ret, sigSz; + + byte sig[512]; // will hold generated signature + sigSz = sizeof(sig); + byte digest[] = { // initialize with message hash }; + wc_InitRng(&rng); // initialize rng + wc_ecc_init(&key); // initialize key + wc_ecc_make_key(&rng, 32, &key); // make public/private key pair + ret = wc_ecc_sign_hash(digest, sizeof(digest), sig, &sigSz, &key); + if ( ret != 0 ) { + // error generating message signature + } + \endcode + + \sa wc_ecc_verify_hash +*/ +WOLFSSL_API +int wc_ecc_sign_hash(const byte* in, word32 inlen, byte* out, word32 *outlen, + WC_RNG* rng, ecc_key* key); +/*! + \ingroup ECC + + \brief Sign a message digest. + + \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 + 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 + satisfactory key + \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 + message signature + \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 + the message signature + \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 + message signature + \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 + message signature + \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 + message signature + \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. + \param key A private ECC key. + \param r The destination for r component of the signature. + \param s The destination for s component of the signature. + + _Example_ + \code + ecc_key key; + WC_RNG rng; + int ret, sigSz; + mp_int r; // destination for r component of signature. + mp_int s; // destination for s component of signature. + + byte sig[512]; // will hold generated signature + sigSz = sizeof(sig); + byte digest[] = { initialize with message hash }; + wc_InitRng(&rng); // initialize rng + wc_ecc_init(&key); // initialize key + wc_ecc_make_key(&rng, 32, &key); // make public/private key pair + ret = wc_ecc_sign_hash_ex(digest, sizeof(digest), &rng, &key, &r, &s); + + if ( ret != MP_OKAY ) { + // error generating message signature + } + \endcode + + \sa wc_ecc_verify_hash_ex +*/ +WOLFSSL_API +int wc_ecc_sign_hash_ex(const byte* in, word32 inlen, WC_RNG* rng, + ecc_key* key, mp_int *r, mp_int *s); +/*! + \ingroup ECC + + \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. + 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 + the message signature + \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 message signature + \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 the message signature + \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 message signature + \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 + the message signature + \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 + 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 + verified + \param hashlen length of the hash of the message verified + \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 + + _Example_ + \code + ecc_key key; + int ret, verified = 0; + + 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), + &verified, &key); + if ( ret != 0 ) { + // error performing verification + } else if ( verified == 0 ) { + // the signature is invalid + } + \endcode + + \sa wc_ecc_sign_hash + \sa wc_ecc_verify_hash_ex +*/ +WOLFSSL_API +int wc_ecc_verify_hash(const byte* sig, word32 siglen, const byte* hash, + word32 hashlen, int* stat, ecc_key* key); +/*! + \ingroup ECC + + \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 + key-idx is invalid. + \return MEMORY_E Error allocating ints or points. + + \param r The signature R component to verify + \param s The signature S component to verify + \param hash The hash (message digest) that was signed + \param hashlen The length of the hash (octets) + \param stat Result of signature, 1==valid, 0==invalid + \param key The corresponding public ECC key + + _Example_ + \code + mp_int r; + mp_int s; + int stat; + byte hash[] = { Some hash } + ecc_key key; + + if(wc_ecc_verify_hash_ex(&r, &s, hash, hashlen, &stat, &key) == MP_OKAY) + { + // Check stat + } + \endcode + + \sa wc_ecc_verify_hash +*/ +WOLFSSL_API +int wc_ecc_verify_hash_ex(mp_int *r, mp_int *s, const byte* hash, + word32 hashlen, int* stat, ecc_key* key); +/*! + \ingroup ECC + + \brief This function initializes an ecc_key object for future + use with message verification or key negotiation. + + \return 0 Returned upon successfully initializing the ecc_key object + \return MEMORY_E Returned if there is an error allocating memory + + \param key pointer to the ecc_key object to initialize + + _Example_ + \code + ecc_key key; + wc_ecc_init(&key); + \endcode + + \sa wc_ecc_make_key + \sa wc_ecc_free +*/ +WOLFSSL_API +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 +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, + FP_ECC (fixed-point ecc), should be defined. + + \return none No returns. + + \param none No parameters. + + _Example_ + \code + ecc_key key; + // initialize key and perform secure exchanges + ... + + wc_ecc_fp_free(); + \endcode + + \sa wc_ecc_free +*/ +WOLFSSL_API +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; + RNG rng; + int is_valid; + wc_ecc_init(&key); + wc_InitRng(&rng); + wc_ecc_make_key(&rng, 32, &key); + is_valid = wc_ecc_is_valid_idx(key.idx); + if (is_valid == 1) + { + // idx is valid + } + else if (is_valid == 0) + { + // idx is not valid + } + \endcode + + \sa none +*/ +WOLFSSL_API +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; + point = wc_ecc_new_point(); + if (point == NULL) + { + // Handle point creation error + } + // Do stuff with point + \endcode + + \sa wc_ecc_del_point + \sa wc_ecc_cmp_point + \sa wc_ecc_copy_point +*/ +WOLFSSL_API +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; + point = wc_ecc_new_point(); + if (point == NULL) + { + // Handle point creation error + } + // 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 +*/ +WOLFSSL_API +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; + ecc_point* copied_point; + int copy_return; + + point = wc_ecc_new_point(); + copy_return = wc_ecc_copy_point(point, copied_point); + if (copy_return != MP_OKAY) + { + // Handle error + } + \endcode + + \sa wc_ecc_new_point + \sa wc_ecc_cmp_point + \sa wc_ecc_del_point +*/ +WOLFSSL_API +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 + points are not equal. + + \param a First point to compare. + \param b Second point to compare. + + _Example_ + \code + ecc_point* point; + ecc_point* point_to_compare; + int cmp_result; + + point = wc_ecc_new_point(); + point_to_compare = wc_ecc_new_point(); + cmp_result = wc_ecc_cmp_point(point, point_to_compare); + if (cmp_result == BAD_FUNC_ARG) + { + // arguments are invalid + } + else if (cmp_result == MP_EQ) + { + // Points are equal + } + else + { + // Points are not equal + } + \endcode + + \sa wc_ecc_new_point + \sa wc_ecc_del_point + \sa wc_ecc_copy_point +*/ +WOLFSSL_API +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 + 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; + int is_infinity; + point = wc_ecc_new_point(); + + is_infinity = wc_ecc_point_is_at_infinity(point); + if (is_infinity < 0) + { + // Handle error + } + else if (is_infinity == 0) + { + // Point is not at infinity + } + else if (is_infinity == 1) + { + // Point is at infinity + } + \endcode + + \sa wc_ecc_new_point + \sa wc_ecc_del_point + \sa wc_ecc_cmp_point + \sa wc_ecc_copy_point +*/ +WOLFSSL_API +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 + 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, + otherwise it's left in jacobian-montgomery form. + + _Example_ + \code + ecc_point* base; + ecc_point* destination; + // Initialize points + base = wc_ecc_new_point(); + destination = wc_ecc_new_point(); + // Setup other arguments + mp_int multiplicand; + mp_int modulus; + int map; + \endcode + + \sa none +*/ +WOLFSSL_API +int wc_ecc_mulmod(mp_int* k, ecc_point *G, ecc_point *R, + mp_int* a, mp_int* modulus, int map); +/*! + \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. + + \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 + 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 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 + returned in outLen + \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 + ecc_key + \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 + ecc_key + \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 + ecc_key + \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 + ecc_key + \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 + 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 + formatted key + \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; + byte buff[1024]; + word32 buffSz = sizeof(buff); + + ecc_key key; + // initialize key, make key + ret = wc_ecc_export_x963(&key, buff, &buffSz); + if ( ret != 0) { + // error exporting key + } + \endcode + + \sa wc_ecc_export_x963_ex + \sa wc_ecc_import_x963 +*/ +WOLFSSL_API +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 + 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 + 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 + only returning the length required to store the key + \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 + returned in outLen + \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 + ecc_key + \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 + ecc_key + \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 ecc_key + \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 + ecc_key + \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 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 + formatted key + \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 + format. 1==compressed, 0==uncompressed + + _Example_ + \code + int ret; + byte buff[1024]; + word32 buffSz = sizeof(buff); + ecc_key key; + // initialize key, make key + ret = wc_ecc_export_x963_ex(&key, buff, &buffSz, 1); + if ( ret != 0) { + // error exporting key + } + \endcode + + \sa wc_ecc_export_x963 + \sa wc_ecc_import_x963 +*/ +WOLFSSL_API +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 + 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 + compile time, but the key is stored in compressed format + \return ECC_BAD_ARG_E Returned if in or key evaluate to NULL, or the + inLen is even (according to the x9.63 standard, the key must be odd) + \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; + 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 + on the ECC curve + \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 + ecc_key + \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 + ecc_key + \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 + ecc_key + \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 + ecc_key + \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; + byte buff[] = { initialize with ANSI X9.63 formatted key }; + + ecc_key pubKey; + wc_ecc_init_key(&pubKey); + + ret = wc_ecc_import_x963(buff, sizeof(buff), &pubKey); + if ( ret != 0) { + // error importing key + } + \endcode + + \sa wc_ecc_export_x963 + \sa wc_ecc_import_private_key +*/ +WOLFSSL_API +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 + 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 + time, but the key is stored in compressed format + \return ECC_BAD_ARG_E Returned if in or key evaluate to NULL, or the + inLen is even (according to the x9.63 standard, the key must be odd) + \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; + 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 + on the ECC curve + \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 + ecc_key + \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 ecc_key + \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 + ecc_key + \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 + ecc_key + \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 + 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 + private/public key pair + + _Example_ + \code + int ret; + byte pub[] = { initialize with ANSI X9.63 formatted key }; + byte priv[] = { initialize with the raw private key }; + + ecc_key key; + wc_ecc_init_key(&key); + 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 +*/ +WOLFSSL_API +int wc_ecc_import_private_key(const byte* priv, word32 privSz, const byte* pub, + word32 pubSz, ecc_key* key); +/*! + \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 + 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 + DER-encoded ECDSA signature + \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 ecc_key + \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 ecc_key + \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 + ecc_key + \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 + ecc_key + \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 + as a string + \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 + signature + \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_ + \code + int ret; + ecc_key key; + // initialize key, generate R and S + + char r[] = { initialize with R }; + char s[] = { initialize with S }; + 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); + if ( ret != 0) { + // error converting parameters to signature + } + \endcode + + \sa wc_ecc_sign_hash + \sa wc_ecc_sig_size +*/ +WOLFSSL_API +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 + 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 + store the parameters of the ecc_key + \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 + input parameters + \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 + input parameters + \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 + input parameters + \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 + input parameters + \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 + the input parameters + \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 + 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 + point as an ASCII hex string + \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 + hex string + \param curveName pointer to a string containing the ECC curve name, + as found in ecc_sets + + _Example_ + \code + int ret; + ecc_key key; + wc_ecc_init(&key); + + char qx[] = { initialize with x component of base point }; + char qy[] = { initialize with y component of base point }; + char d[] = { initialize with private key }; + ret = wc_ecc_import_raw(&key,qx, qy, d, "ECC-256"); + if ( ret != 0) { + // error initializing key with given inputs + } + \endcode + + \sa wc_ecc_import_private_key +*/ +WOLFSSL_API +int wc_ecc_import_raw(ecc_key* key, const char* qx, const char* qy, + const char* d, const char* curveName); +/*! + \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 + 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 + to store the parameters of the ecc_key + \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 input parameters + \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 + input parameters + \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 input parameters + \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 + input parameters + \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 + the input parameters + \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 + input parameters + + \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 + exporting the private key + + _Example_ + \code + int ret; + ecc_key key; + // initialize key, make key + + char priv[ECC_KEY_SIZE]; + word32 privSz = sizeof(priv); + ret = wc_ecc_export_private_only(&key, priv, &privSz); + if ( ret != 0) { + // error exporting private key + } + \endcode + + \sa wc_ecc_import_private_key +*/ +WOLFSSL_API +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 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. + + \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 + final size of output + + _Example_ + \code + int curve_idx; + ecc_point* point; + byte out[]; + word32 outLen; + wc_ecc_export_point_der(curve_idx, point, out, &outLen); + \endcode + + \sa wc_ecc_import_point_der +*/ +WOLFSSL_API +int wc_ecc_export_point_der(const int curve_idx, ecc_point* point, + byte* out, word32* outLen); +/*! + \ingroup ECC + + \brief Import point from der format. + + \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 + 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. + \param point Destination for point. + + _Example_ + \code + byte in[]; + word32 inLen; + int curve_idx; + ecc_point* point; + wc_ecc_import_point_der(in, inLen, curve_idx, point); + \endcode + + \sa wc_ecc_export_point_der +*/ +WOLFSSL_API +int wc_ecc_import_point_der(byte* in, word32 inLen, const int curve_idx, + ecc_point* point); +/*! + \ingroup ECC + + \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; + ecc_key key; + // initialize key, make key + keySz = wc_ecc_size(&key); + if ( keySz == 0) { + // error determining key size + } + \endcode + + \sa wc_ecc_make_key +*/ +WOLFSSL_API +int wc_ecc_size(ecc_key* key); +/*! + \ingroup ECC + + \brief This function returns the worst case size for an ECC signature, + given by: keySz * 2 + SIG_HEADER_SZ + 4 The actual signature size can + be computed with wc_ecc_sign_hash. + + \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 + signature size + + _Example_ + \code + int sigSz; + ecc_key key; + // initialize key, make key + + sigSz = wc_ecc_sig_size(&key); + if ( sigSz == 0) { + // error determining sig size + } + \endcode + + \sa wc_ecc_sign_hash +*/ +WOLFSSL_API +int wc_ecc_sig_size(ecc_key* key); +/*! + \ingroup 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, + returns a pointer to that object + \return NULL Returned if the function fails to generate a new + ecEncCtx object + + \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; + RNG rng; + wc_InitRng(&rng); + ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng); + if(ctx == NULL) { + // error generating new ecEncCtx object + } + \endcode + + \sa wc_ecc_encrypt + \sa wc_ecc_decrypt +*/ +WOLFSSL_API +ecEncCtx* wc_ecc_ctx_new(int flags, WC_RNG* rng); +/*! + \ingroup ECC + + \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; + RNG rng; + wc_InitRng(&rng); + ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng); + // do secure communication + ... + wc_ecc_ctx_free(&ctx); + \endcode + + \sa wc_ecc_ctx_new +*/ +WOLFSSL_API +void wc_ecc_ctx_free(ecEncCtx*); +/*! + \ingroup ECC + + \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 + 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; + RNG rng; + wc_InitRng(&rng); + ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng); + // do secure communication + ... + wc_ecc_ctx_reset(&ctx, &rng); + // do more secure communication + \endcode + + \sa wc_ecc_ctx_new +*/ +WOLFSSL_API +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 + 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 + ecCLI_BAD_STATE, respectively + + \param ctx pointer to the ecEncCtx object from which to get the salt + + _Example_ + \code + ecEncCtx* ctx; + RNG rng; + const byte* salt; + wc_InitRng(&rng); + ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng); + salt = wc_ecc_ctx_get_own_salt(&ctx); + if(salt == NULL) { + // error getting salt + } + \endcode + + \sa wc_ecc_ctx_new + \sa wc_ecc_ctx_set_peer_salt +*/ +WOLFSSL_API +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 + ecEncCtx object. + \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 + 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; + RNG rng; + const byte* cliSalt, srvSalt; + int ret; + + wc_InitRng(&rng); + cliCtx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng); + srvCtx = wc_ecc_ctx_new(REQ_RESP_SERVER, &rng); + + cliSalt = wc_ecc_ctx_get_own_salt(&cliCtx); + 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 +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 + an ecEncCtx object. + + \return 0 Returned upon successfully setting the information + for the ecEncCtx object. + \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; + byte info[] = { initialize with information }; + // initialize ctx, get salt, + if(wc_ecc_ctx_set_info(&ctx, info, sizeof(info))) { + // error setting info + } + \endcode + + \sa wc_ecc_ctx_new +*/ +WOLFSSL_API +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 + 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 + encryption type + \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 + small to store the encrypted ciphertext + \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 key to use for encryption + \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, + holds the number of bytes written to the output buffer + \param ctx Optional: pointer to an ecEncCtx object specifying different + encryption algorithms to use + + _Example_ + \code + byte msg[] = { initialize with msg to encrypt. Ensure padded to block size }; + byte out[sizeof(msg)]; + word32 outSz = sizeof(out); + int ret; + ecc_key cli, serv; + // initialize cli with private key + // initialize serv with received public key + + ecEncCtx* cliCtx, servCtx; + // initialize cliCtx and servCtx + // exchange salts + ret = wc_ecc_encrypt(&cli, &serv, msg, sizeof(msg), out, &outSz, cliCtx); + if(ret != 0) { + // error encrypting message + } + \endcode + + \sa wc_ecc_decrypt +*/ +WOLFSSL_API +int wc_ecc_encrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg, + word32 msgSz, byte* out, word32* outSz, ecEncCtx* ctx); +/*! + \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 + 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 + encryption type + \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 + small to store the decrypted plaintext + \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 + key to use for decryption + \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 + ciphertext, holds the number of bytes written to the output buffer + \param ctx Optional: pointer to an ecEncCtx object specifying + different decryption algorithms to use + + _Example_ + \code + byte cipher[] = { initialize with + ciphertext to decrypt. Ensure padded to block size }; + byte plain[sizeof(cipher)]; + word32 plainSz = sizeof(plain); + int ret; + ecc_key cli, serv; + // initialize cli with private key + // initialize serv with received public key + ecEncCtx* cliCtx, servCtx; + // initialize cliCtx and servCtx + // exchange salts + ret = wc_ecc_decrypt(&cli, &serv, cipher, sizeof(cipher), + plain, &plainSz, cliCtx); + + if(ret != 0) { + // error decrypting message + } + \endcode + + \sa Wc_ecc_encrypt +*/ +WOLFSSL_API +int wc_ecc_decrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg, + word32 msgSz, byte* out, word32* outSz, ecEncCtx* ctx); diff --git a/doc/dox_comments/header_files/ed25519.h b/doc/dox_comments/header_files/ed25519.h new file mode 100644 index 000000000..62717ed6f --- /dev/null +++ b/doc/dox_comments/header_files/ed25519.h @@ -0,0 +1,497 @@ +/*! + \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 + specified key size is not 32 bytes (ed25519 has 32 byte keys) + \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 + 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 + + _Example_ + \code + ed25519_key key; + wc_ed25519_init(&key); + RNG rng; + wc_InitRng(&rng); + wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key + \endcode + + \sa wc_ed25519_init +*/ +WOLFSSL_API +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 + to guarantee authenticity. + + \return 0 Returned upon successfully generating a signature for the + message digest + \return BAD_FUNC_ARG Returned any of the input parameters evaluate to + NULL, or if the output buffer is too small to store the generated signature + \return MEMORY_E Returned if there is an error allocating memory during + function execution + + \param in 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 + written to out upon successfully generating a message signature + \param key pointer to a private ed25519_key with which to generate the + signature + + _Example_ + \code + ed25519_key key; + RNG rng; + int ret, sigSz; + + byte sig[64]; // will hold generated signature + sigSz = sizeof(sig); + byte message[] = { // initialize with message }; + + wc_InitRng(&rng); // initialize rng + wc_ed25519_init(&key); // initialize key + wc_ed25519_make_key(&rng, 32, &key); // make public/private key pair + ret = wc_ed25519_sign_msg(message, sizeof(message), sig, &sigSz, &key); + if ( ret != 0 ) { + // error generating message signature + } + \endcode + + \sa wc_ed25519_verify_msg +*/ +WOLFSSL_API +int wc_ed25519_sign_msg(const byte* in, word32 inlen, byte* out, + word32 *outlen, ed25519_key* key); +/*! + \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 + 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. + The authenticity information is stored instead in stat + \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to + NULL, or if the siglen does not match the actual length of a signature + \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 + message was successfully verified + \param key pointer to a public ed25519 key with which to verify the + signature + + _Example_ + \code + ed25519_key key; + int ret, verified = 0; + + 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), + &verified, &key); + + if ( return < 0 ) { + // error performing verification + } else if ( verified == 0 ) + // the signature is invalid + } + \endcode + + \sa wc_ed25519_sign_msg +*/ +WOLFSSL_API +int wc_ed25519_verify_msg(const byte* sig, word32 siglen, const byte* msg, + word32 msglen, int* stat, ed25519_key* key); +/*! + \ingroup ED25519 + + \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 +*/ +WOLFSSL_API +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; + // initialize key and perform secure exchanges + ... + wc_ed25519_free(&key); + \endcode + + \sa wc_ed25519_init +*/ +WOLFSSL_API +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 + 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 + 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 + public key + + _Example_ + \code + int ret; + byte pub[] = { // initialize ed25519 public key }; + + ed_25519 key; + wc_ed25519_init_key(&key); + ret = wc_ed25519_import_public(pub, sizeof(pub), &key); + if ( ret != 0) { + // error importing key + } + \endcode + + \sa wc_ed25519_import_private_key + \sa wc_ed25519_export_public +*/ +WOLFSSL_API +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 + uncompressed keys. + + \return 0 Returned on successfully importing the ed25519_key + \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if + either privSz 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 + imported private/public key pair + + _Example_ + \code + int ret; + byte priv[] = { // initialize with 32 byte private key }; + byte pub[] = { // initialize with the corresponding public key }; + + ed25519_key key; + wc_ed25519_init_key(&key); + ret = wc_ed25519_import_private_key(priv, sizeof(priv), pub, + sizeof(pub), &key); + if ( ret != 0) { + // error importing key + } + \endcode + + \sa wc_ed25519_import_public_key + \sa wc_ed25519_export_private_only +*/ +WOLFSSL_API +int wc_ed25519_import_private_key(const byte* priv, word32 privSz, + const byte* pub, word32 pubSz, ed25519_key* key); +/*! + \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 + written to this buffer in outLen. + + \return 0 Returned upon successfully exporting the public key + \return BAD_FUNC_ARG Returned if any of the input values evaluate to NULL + \return BUFFER_E Returned if the buffer provided is not large enough to + store the private key. Upon returning this error, the function sets the + size required in outLen + + \param 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 + the private key + + _Example_ + \code + int ret; + ed25519_key key; + // initialize key, make key + + char pub[32]; + word32 pubSz = sizeof(pub); + + ret = wc_ed25519_export_public(&key, pub, &pubSz); + if ( ret != 0) { + // error exporting public key + } + \endcode + + \sa wc_ed25519_import_public_key + \sa wc_ed25519_export_private_only +*/ +WOLFSSL_API +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 + the bytes written to this buffer in outLen. + + \return 0 Returned upon successfully exporting the private key + \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL + \return BUFFER_E Returned if the buffer provided is not large enough + to store the private key + + \param 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 + exporting the private key + + _Example_ + \code + int ret; + ed25519_key key; + // initialize key, make key + + char priv[32]; // 32 bytes because only private key + word32 privSz = sizeof(priv); + ret = wc_ed25519_export_private_only(&key, priv, &privSz); + if ( ret != 0) { + // error exporting private key + } + \endcode + + \sa wc_ed25519_export_public + \sa wc_ed25519_import_private_key +*/ +WOLFSSL_API +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 + \return BAD_FUNC_ARG Returns if any argument is null. + \return BUFFER_E Returns if outLen is less than ED25519_PRV_KEY_SIZE + + \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 + private key. + + _Example_ + \code + ed25519_key key; + wc_ed25519_init(&key); + + RNG rng; + wc_InitRng(&rng); + + wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key + + byte out[32]; // out needs to be a sufficient buffer size + word32 outLen = sizeof(out); + int key_size = wc_ed25519_export_private(&key, out, &outLen); + if(key_size == BUFFER_E) + { + // Check size of out compared to outLen to see if function reset outLen + } + \endcode + + \sa none +*/ +WOLFSSL_API +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 + 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. + \param pub Byte array to store public key. + \param pubSz Size of pub buffer. + + _Example_ + \code + int ret; + ed25519_key key; + // initialize key, make key + + char pub[32]; + word32 pubSz = sizeof(pub); + char priv[32]; + word32 privSz = sizeof(priv); + + ret = wc_ed25519_export_key(&key, priv, &pubSz, pub, &pubSz); + if ( ret != 0) { + // error exporting public key + } + \endcode + + \sa wc_ed25519_export_private + \sa wc_ed25519_export_public +*/ +WOLFSSL_API +int wc_ed25519_export_key(ed25519_key* key, + byte* priv, word32 *privSz, + byte* pub, word32 *pubSz); +/*! + \ingroup ED25519 + + \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 + key size + + _Example_ + \code + int keySz; + ed25519_key key; + // initialize key, make key + keySz = wc_ed25519_size(&key); + if ( keySz == 0) { + // error determining key size + } + \endcode + + \sa wc_ed25519_make_key +*/ +WOLFSSL_API +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; + wc_ed25519_init(&key); + + RNG rng; + wc_InitRng(&rng); + + 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 +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; + wc_ed25519_init(&key); + RNG rng; + wc_InitRng(&rng); + + 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 +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 + signature size + + _Example_ + \code + int sigSz; + ed25519_key key; + // initialize key, make key + + sigSz = wc_ed25519_sig_size(&key); + if ( sigSz == 0) { + // error determining sig size + } + \endcode + + \sa wc_ed25519_sign_msg +*/ +WOLFSSL_API +int wc_ed25519_sig_size(ed25519_key* key); diff --git a/doc/dox_comments/header_files/error-crypt.h b/doc/dox_comments/header_files/error-crypt.h new file mode 100644 index 000000000..6d3d40e9c --- /dev/null +++ b/doc/dox_comments/header_files/error-crypt.h @@ -0,0 +1,48 @@ +/*! + \ingroup Error + + \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 + at least WOLFSSL_MAX_ERROR_SZ (80 bytes) long + + _Example_ + \code + char errorMsg[WOLFSSL_MAX_ERROR_SZ]; + int err = wc_some_function(); + + if( err != 0) { // error occurred + 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 + string literal. + + \param error error code for which to get the string + + _Example_ + \code + char * errorMsg; + int err = wc_some_function(); + + if( err != 0) { // error occurred + 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 new file mode 100644 index 000000000..0a1bd1547 --- /dev/null +++ b/doc/dox_comments/header_files/evp.h @@ -0,0 +1,385 @@ +/*! + \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 + 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", + wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_cbc())); + 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 + 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_ecb(); + … + \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 + 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; + wolfCrypt_Init(); + md = wolfSSL_EVP_MD_CTX_new(); + if (md == NULL) { + printf("error setting md\n"); + return -1; + } + 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 +*/ +WOLFSSL_API int wolfSSL_EVP_DigestInit_ex(WOLFSSL_EVP_MD_CTX* ctx, + const WOLFSSL_EVP_MD* type, + WOLFSSL_ENGINE *impl); +/*! + \ingroup openSSL + + \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; + WOLFSSL_ENGINE* e = NULL; + unsigned char key[16]; + unsigned char iv[12]; + wolfCrypt_Init(); + ctx = wolfSSL_EVP_CIPHER_CTX_new(); + if (ctx == NULL) { + printf("issue creating ctx\n"); + return -1; + } + + 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, + 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 +*/ +WOLFSSL_API int wolfSSL_EVP_CipherInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, + const WOLFSSL_EVP_CIPHER* type, + WOLFSSL_ENGINE *impl, + const unsigned char* key, + const unsigned char* iv, + int enc); +/*! + \ingroup openSSL + + \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; + wolfCrypt_Init(); + ctx = wolfSSL_EVP_CIPHER_CTX_new(); + if (ctx == NULL) { + printf("error setting ctx\n"); + return -1; + } + printf("cipher ctx init ret = %d\n", wolfSSL_EVP_EncryptInit_ex(ctx, + wolfSSL_EVP_aes_128_cbc(), e, key, iv)); + //free resources + \endcode + + \sa wolfSSL_EVP_CIPHER_CTX_new + \sa wolfCrypt_Init + \sa wolfSSL_EVP_CIPHER_CTX_free +*/ +WOLFSSL_API int wolfSSL_EVP_EncryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, + const WOLFSSL_EVP_CIPHER* type, + WOLFSSL_ENGINE *impl, + const unsigned char* key, + const unsigned char* iv); +/*! + \ingroup openSSL + + \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; + WOLFSSL_ENGINE* e = NULL; + unsigned char key[16]; + unsigned char iv[12]; + + wolfCrypt_Init(); + + ctx = wolfSSL_EVP_CIPHER_CTX_new(); + if (ctx == NULL) { + printf("issue creating ctx\n"); + return -1; + } + + 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, + 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 +*/ +WOLFSSL_API int wolfSSL_EVP_DecryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, + const WOLFSSL_EVP_CIPHER* type, + WOLFSSL_ENGINE *impl, + const unsigned char* key, + const unsigned char* iv); +/*! + \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 + length of encrypted/decrypted information. + + \return SSL_SUCCESS If successfull. + \return SSL_FAILURE If not successful. + + \param ctx structure to get cipher type from. + \param out buffer to hold output. + \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; + unsigned char out[100]; + int outl; + unsigned char in[100]; + int inl = 100; + + ctx = wolfSSL_EVP_CIPHER_CTX_new(); + // set up ctx + ret = wolfSSL_EVP_CipherUpdate(ctx, out, outl, in, inl); + // check ret value + // 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 +*/ +WOLFSSL_API int wolfSSL_EVP_CipherUpdate(WOLFSSL_EVP_CIPHER_CTX *ctx, + unsigned char *out, int *outl, + const unsigned char *in, int inl); +/*! + \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 + 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; + int out1; + unsigned char out[64]; + // 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, + unsigned char *out, int *outl); +/*! + \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; + int keylen; + // 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, + int keylen); +/*! + \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”, + 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; + int flag; + // 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 new file mode 100644 index 000000000..474018c3a --- /dev/null +++ b/doc/dox_comments/header_files/hash.h @@ -0,0 +1,235 @@ +/*! + \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 + as “WC_HASH_TYPE_SHA256”. + + _Example_ + \code + enum wc_HashType hash_type = WC_HASH_TYPE_SHA256; + int oid = wc_HashGetOID(hash_type); + if (oid > 0) { + // Success + } + \endcode + + \sa wc_HashGetDigestSize + \sa wc_Hash +*/ +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 + provided to wc_Hash is large enough. + + \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 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 + “WC_HASH_TYPE_SHA256”. + + _Example_ + \code + int hash_len = wc_HashGetDigestSize(hash_type); + if (hash_len <= 0) { + WOLFSSL_MSG("Invalid hash type/len"); + 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 + 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” + 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; + int hash_len = wc_HashGetDigestSize(hash_type); + if (hash_len > 0) { + int ret = wc_Hash(hash_type, data, data_len, hash_data, hash_len); + if(ret == 0) { + // Success + } + } + \endcode + + \sa wc_HashGetDigestSize +*/ +WOLFSSL_API int wc_Hash(enum wc_HashType hash_type, + const byte* data, word32 data_len, + byte* hash, word32 hash_len); +/*! + \ingroup MD5 + + \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 + 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 + const byte* data; + 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 +*/ +WOLFSSL_API int wc_Md5Hash(const byte* data, word32 len, byte* hash); +/*! + \ingroup SHA + + \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 + 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 +*/ +WOLFSSL_API int wc_ShaHash(const byte*, word32, byte*); +/*! + \ingroup SHA + + \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 + 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 +*/ +WOLFSSL_API int wc_Sha256Hash(const byte*, word32, byte*); +/*! + \ingroup SHA + + \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 +*/ + WOLFSSL_API int wc_Sha224Hash(const byte*, word32, byte*); +/*! + \ingroup SHA + + \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 + 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_Sha512Hash + \sa wc_Sha512Final + \sa wc_InitSha512 +*/ +WOLFSSL_API int wc_Sha512Hash(const byte*, word32, byte*); +/*! + \ingroup SHA + + \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 + 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_Sha384Hash + \sa wc_Sha384Final + \sa wc_InitSha384 +*/ + WOLFSSL_API int wc_Sha384Hash(const byte*, word32, byte*); diff --git a/doc/dox_comments/header_files/hc128.h b/doc/dox_comments/header_files/hc128.h new file mode 100644 index 000000000..a9f251c6f --- /dev/null +++ b/doc/dox_comments/header_files/hc128.h @@ -0,0 +1,65 @@ +/*! + \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 + 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 + 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 + 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 + 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 + ciphertext to decrypt + \param msglen length of the plaintext to encrypt or the ciphertext + to decrypt + + _Example_ + \code + HC128 enc; + byte key[] = { // initialize with key }; + byte iv[] = { // initialize with iv }; + wc_Hc128_SetKey(&enc, key, iv); + + byte msg[] = { // initialize with message }; + byte cipher[sizeof(msg)]; + + if (wc_Hc128_Process(*enc, cipher, plain, sizeof(plain)) != 0) { + // 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 + setting its 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 + use with encryption/decryption + \param iv pointer to the buffer containing the 16 byte iv (nonce) + with which to initialize the HC128 object + + _Example_ + \code + HC128 enc; + byte key[] = { // initialize with key }; + 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 new file mode 100644 index 000000000..aa12f01f7 --- /dev/null +++ b/doc/dox_comments/header_files/hmac.h @@ -0,0 +1,168 @@ +/*! + \ingroup HMAC + + \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 + are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID + \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 + FIPS standard + + \param hmac pointer to the Hmac object to initialize + \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 + initialize the Hmac object + \param length length of the key + + _Example_ + \code + Hmac hmac; + byte key[] = { // initialize with key to use for encryption }; + if (wc_HmacSetKey(&hmac, MD5, key, sizeof(key)) != 0) { + // error initializing Hmac object + } + \endcode + + \sa wc_HmacUpdate + \sa wc_HmacFinal +*/ +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. + + \return 0 Returned on successfully updating the message to authenticate + \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; + byte msg[] = { // initialize with message to authenticate }; + byte msg2[] = { // initialize with second half of message }; + // initialize hmac + if( wc_HmacUpdate(&hmac, msg, sizeof(msg)) != 0) { + // error updating message + } + if( wc_HmacUpdate(&hmac, msg2, sizeof(msg)) != 0) { + // error updating with second message + } + \endcode + + \sa wc_HmacSetKey + \sa wc_HmacFinal +*/ +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 + use with a hashing algorithm + + \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. + Should have room available as required by the hashing algorithm chosen + + _Example_ + \code + Hmac hmac; + byte hash[MD5_DIGEST_SIZE]; + // initialize hmac with MD5 as type + // wc_HmacUpdate() with messages + + if (wc_HmacFinal(&hmac, hash) != 0) { + // error computing hash + } + \endcode + + \sa wc_HmacSetKey + \sa wc_HmacUpdate +*/ +WOLFSSL_API int wc_HmacFinal(Hmac*, byte*); +/*! + \ingroup HMAC + + \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 + 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 + 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 + 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 + standard + + \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 + 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. + 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 + generated key + + _Example_ + \code + byte key[] = { // initialize with key }; + byte salt[] = { // initialize with salt }; + byte derivedKey[MAX_DIGEST_SIZE]; + + int ret = wc_HKDF(SHA512, key, sizeof(key), salt, sizeof(salt), + NULL, 0, derivedKey, sizeof(derivedKey)); + if ( ret != 0 ) { + // error generating derived key + } + \endcode + + \sa wc_HmacSetKey +*/ +WOLFSSL_API int wc_HKDF(int type, const byte* inKey, word32 inKeySz, + const byte* salt, word32 saltSz, + const byte* info, word32 infoSz, + byte* out, word32 outSz); diff --git a/doc/dox_comments/header_files/idea.h b/doc/dox_comments/header_files/idea.h new file mode 100644 index 000000000..b4becaf2d --- /dev/null +++ b/doc/dox_comments/header_files/idea.h @@ -0,0 +1,159 @@ +/*! + \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 + 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. + \param iv Value for IV in Idea structure. Can be null. + \param dir Direction, either IDEA_ENCRYPTION or IDEA_DECRYPTION + + _Example_ + \code + byte v_key[IDEA_KEY_SIZE] = { }; // Some Key + Idea idea; + int ret = wc_IdeaSetKey(&idea v_key, IDEA_KEY_SIZE, NULL, IDEA_ENCRYPTION); + if (ret != 0) + { + // There was an error + } + \endcode + + \sa wc_IdeaSetIV +*/ +WOLFSSL_API int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz, + const byte *iv, int dir); +/*! + \ingroup IDEA + + \brief Sets the IV in an Idea key structure. + + \return 0 Success + \return BAD_FUNC_ARG Returns if idea is null. + + \param idea Pointer to idea key structure. + \param iv The IV value to set, can be null. + + _Example_ + \code + Idea idea; + // Initialize idea + + byte iv[] = { }; // Some IV + int ret = wc_IdeaSetIV(&idea, iv); + if(ret != 0) + { + // 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. + + _Example_ + \code + byte v_key[IDEA_KEY_SIZE] = { }; // Some Key + byte data[IDEA_BLOCK_SIZE] = { }; // Some encrypted data + Idea idea; + wc_IdeaSetKey(&idea, v_key, IDEA_KEY_SIZE, NULL, IDEA_DECRYPTION); + int ret = wc_IdeaCipher(&idea, data, data); + + if (ret != 0) + { + // There was an error + } + \endcode + + \sa wc_IdeaSetKey + \sa wc_IdeaSetIV + \sa wc_IdeaCbcEncrypt + \sa wc_IdeaCbcDecrypt +*/ +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. + + \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; + // Initialize idea structure for encryption + const char *message = "International Data Encryption Algorithm"; + byte msg_enc[40], msg_dec[40]; + + memset(msg_enc, 0, sizeof(msg_enc)); + ret = wc_IdeaCbcEncrypt(&idea, msg_enc, (byte *)message, + (word32)strlen(message)+1); + if(ret != 0) + { + // Some error occured + } + \endcode + + \sa wc_IdeaCbcDecrypt + \sa wc_IdeaCipher + \sa wc_IdeaSetKey +*/ +WOLFSSL_API int wc_IdeaCbcEncrypt(Idea *idea, byte* out, + const byte* in, word32 len); +/*! + \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; + // Initialize idea structure for decryption + const char *message = "International Data Encryption Algorithm"; + byte msg_enc[40], msg_dec[40]; + + memset(msg_dec, 0, sizeof(msg_dec)); + ret = wc_IdeaCbcDecrypt(&idea, msg_dec, msg_enc, + (word32)strlen(message)+1); + if(ret != 0) + { + // Some error occured + } + \endcode + + \sa wc_IdeaCbcEncrypt + \sa wc_IdeaCipher + \sa wc_IdeaSetKey +*/ +WOLFSSL_API int wc_IdeaCbcDecrypt(Idea *idea, byte* out, + const byte* in, word32 len); diff --git a/doc/dox_comments/header_files/logging.h b/doc/dox_comments/header_files/logging.h new file mode 100644 index 000000000..12a954233 --- /dev/null +++ b/doc/dox_comments/header_files/logging.h @@ -0,0 +1,76 @@ +/*! + \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 + 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 + pointer is not provided. + + \param log_function function to register as a logging callback. + Function signature must follow the above prototype. + + _Example_ + \code + int ret = 0; + // Logging callback prototype + void MyLoggingCallback(const int logLevel, const char* const logMessage); + // Register the custom logging callback with wolfSSL + ret = wolfSSL_SetLoggingCb(MyLoggingCallback); + if (ret != 0) { + // failed to set logging callback + } + void MyLoggingCallback(const int logLevel, const char* const logMessage) + { + // custom logging function + } + \endcode + + \sa wolfSSL_Debugging_ON + \sa wolfSSL_Debugging_OFF +*/ +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 + or define DEBUG_WOLFSSL. + + \return 0 upon success. + \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 +*/ +WOLFSSL_API int wolfSSL_Debugging_ON(void); +/*! + \ingroup Debug + + \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 +*/ +WOLFSSL_API void wolfSSL_Debugging_OFF(void); diff --git a/doc/dox_comments/header_files/md2.h b/doc/dox_comments/header_files/md2.h new file mode 100644 index 000000000..f5251c199 --- /dev/null +++ b/doc/dox_comments/header_files/md2.h @@ -0,0 +1,113 @@ +/*! + \ingroup MD2 + + \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]; + if ((ret = wc_InitMd2(md2)) != 0) { + WOLFSSL_MSG("wc_Initmd2 failed"); + } + else { + wc_Md2Update(md2, data, len); + wc_Md2Final(md2, hash); + } + \endcode + + \sa wc_Md2Hash + \sa wc_Md2Update + \sa wc_Md2Final +*/ +WOLFSSL_API void wc_InitMd2(Md2*); +/*! + \ingroup MD2 + + \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 + + _Example_ + \code + md2 md2[1]; + byte data[] = { }; // Data to be hashed + word32 len = sizeof(data); + + if ((ret = wc_InitMd2(md2)) != 0) { + WOLFSSL_MSG("wc_Initmd2 failed"); + } + else { + wc_Md2Update(md2, data, len); + wc_Md2Final(md2, hash); + } + \endcode + + \sa wc_Md2Hash + \sa wc_Md2Final + \sa wc_InitMd2 +*/ +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 + \param hash Byte array to hold hash value. + + _Example_ + \code + md2 md2[1]; + byte data[] = { }; // Data to be hashed + word32 len = sizeof(data); + + if ((ret = wc_InitMd2(md2)) != 0) { + WOLFSSL_MSG("wc_Initmd2 failed"); + } + else { + wc_Md2Update(md2, data, len); + wc_Md2Final(md2, hash); + } + \endcode + + \sa wc_Md2Hash + \sa wc_Md2Final + \sa wc_InitMd2 +*/ +WOLFSSL_API void wc_Md2Final(Md2*, byte*); +/*! + \ingroup MD2 + + \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 + 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_Md2Hash + \sa wc_Md2Final + \sa wc_InitMd2 +*/ +WOLFSSL_API int wc_Md2Hash(const byte*, word32, byte*); diff --git a/doc/dox_comments/header_files/md4.h b/doc/dox_comments/header_files/md4.h new file mode 100644 index 000000000..e7f25ff28 --- /dev/null +++ b/doc/dox_comments/header_files/md4.h @@ -0,0 +1,86 @@ +/*! + \ingroup MD4 + + \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]; + if ((ret = wc_InitMd4(md4)) != 0) { + WOLFSSL_MSG("wc_Initmd4 failed"); + } + else { + wc_Md4Update(md4, data, len); + wc_Md4Final(md4, hash); + } + \endcode + + \sa wc_Md4Hash + \sa wc_Md4Update + \sa wc_Md4Final +*/ +WOLFSSL_API void wc_InitMd4(Md4*); +/*! + \ingroup MD4 + + \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]; + byte data[] = { }; // Data to be hashed + word32 len = sizeof(data); + + if ((ret = wc_InitMd4(md4)) != 0) { + WOLFSSL_MSG("wc_Initmd4 failed"); + } + else { + wc_Md4Update(md4, data, len); + wc_Md4Final(md4, hash); + } + \endcode + + \sa wc_Md4Hash + \sa wc_Md4Final + \sa wc_InitMd4 +*/ +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. + + _Example_ + \code + md4 md4[1]; + if ((ret = wc_InitMd4(md4)) != 0) { + WOLFSSL_MSG("wc_Initmd4 failed"); + } + else { + wc_Md4Update(md4, data, len); + wc_Md4Final(md4, hash); + } + \endcode + + \sa wc_Md4Hash + \sa wc_Md4Final + \sa wc_InitMd4 +*/ +WOLFSSL_API void wc_Md4Final(Md4*, byte*); diff --git a/doc/dox_comments/header_files/md5.h b/doc/dox_comments/header_files/md5.h new file mode 100644 index 000000000..d6d1ea69d --- /dev/null +++ b/doc/dox_comments/header_files/md5.h @@ -0,0 +1,176 @@ +/*! + \ingroup MD5 + + \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 + as a NULL value. + + \param md5 pointer to the md5 structure to use for encryption + + _Example_ + \code + Md5 md5; + byte* hash; + if ((ret = wc_InitMd5(&md5)) != 0) { + WOLFSSL_MSG("wc_Initmd5 failed"); + } + else { + ret = wc_Md5Update(&md5, data, len); + if (ret != 0) { + // Md5 Update Failure Case. + } + ret = wc_Md5Final(&md5, hash); + if (ret != 0) { + // Md5 Final Failure Case. + } + } + \endcode + + \sa wc_Md5Hash + \sa wc_Md5Update + \sa wc_Md5Final +*/ +WOLFSSL_API int wc_InitMd5(wc_Md5*); +/*! + \ingroup MD5 + + \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 + 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; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitMd5(&md5)) != 0) { + WOLFSSL_MSG("wc_Initmd5 failed"); + } + else { + ret = wc_Md5Update(&md5, data, len); + if (ret != 0) { + // Md5 Update Error Case. + } + ret = wc_Md5Final(&md5, hash); + if (ret != 0) { + // Md5 Final Error Case. + } + } + \endcode + + \sa wc_Md5Hash + \sa wc_Md5Final + \sa wc_InitMd5 +*/ +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 + 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 + 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]; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitMd5(md5)) != 0) { + WOLFSSL_MSG("wc_Initmd5 failed"); + } + else { + ret = wc_Md5Update(md5, data, len); + if (ret != 0) { + // Md5 Update Failure Case. + } + ret = wc_Md5Final(md5, hash); + if (ret != 0) { + // Md5 Final Failure Case. + } + } + \endcode + + \sa wc_Md5Hash + \sa wc_InitMd5 + \sa wc_Md5GetHash +*/ +WOLFSSL_API int wc_Md5Final(wc_Md5*, byte*); +/*! + \ingroup MD5 + + \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_ + \code + Md5 md5; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitMd5(&md5)) != 0) { + WOLFSSL_MSG("wc_InitMd5 failed"); + } + else { + wc_Md5Update(&md5, data, len); + wc_Md5Final(&md5, hash); + wc_Md5Free(&md5); + } + \endcode + + \sa wc_InitMd5 + \sa wc_Md5Update + \sa wc_Md5Final +*/ +WOLFSSL_API void wc_Md5Free(wc_Md5*); +/*! + \ingroup MD5 + + \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]; + if ((ret = wc_InitMd5(md5)) != 0) { + WOLFSSL_MSG("wc_Initmd5 failed"); + } + else { + wc_Md5Update(md5, data, len); + wc_Md5GetHash(md5, hash); + } + \endcode + + \sa wc_Md5Hash + \sa wc_Md5Final + \sa wc_InitMd5 +*/ +WOLFSSL_API int wc_Md5GetHash(wc_Md5*, byte*); diff --git a/doc/dox_comments/header_files/memory.h b/doc/dox_comments/header_files/memory.h new file mode 100644 index 000000000..78bc3787d --- /dev/null +++ b/doc/dox_comments/header_files/memory.h @@ -0,0 +1,292 @@ +/*! + \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 + wolfSSL_Malloc during preprocessing. + + \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 + \sa XFREE + \sa XREALLOC +*/ + WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type, const char* func, unsigned int line); +/*! + \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 + during preprocessing. + + \return none No returns. + + \param ptr pointer to the memory to free + + _Example_ + \code + int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10); + // process data as desired + ... + if(tenInts) { + wolfSSL_Free(tenInts); + } + \endcode + + \sa wolfSSL_Malloc + \sa wolfSSL_Realloc + \sa XMALLOC + \sa XFREE + \sa XREALLOC +*/ + WOLFSSL_API void wolfSSL_Free(void *ptr, void* heap, int type, const char* func, unsigned int line); +/*! + \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 + wolfSSL_Realloc during preprocessing. + + \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 + + _Example_ + \code + 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 + \sa XFREE + \sa XREALLOC +*/ + WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type, const char* func, unsigned int line); +/*! + \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 + abstraction layer - see wolfSSL_SetAllocators(). + + \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 + memory allocation function being used (if not using the default malloc()). + + \param size number of bytes to allocate. + + _Example_ + \code + char* buffer; + buffer = (char*) wolfSSL_Malloc(20); + if (buffer == NULL) { + // failed to allocate memory + } + \endcode + + \sa wolfSSL_Free + \sa wolfSSL_Realloc + \sa wolfSSL_SetAllocators +*/ + 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 + 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 + 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 + (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; + + buffer = (char*) wolfSSL_Realloc(30); + if (buffer == NULL) { + // failed to re-allocate memory + } + \endcode + + \sa wolfSSL_Free + \sa wolfSSL_Malloc + \sa wolfSSL_SetAllocators +*/ + 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 + 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 +*/ + 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 + memory handlers. + + \return Success If successful this function will return 0. + \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. + Function signature must match wolfSSL_Malloc_cb prototype, above. + \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. + Function signature must match wolfSSL_Realloc_cb prototype, above. + + _Example_ + \code + int ret = 0; + // Memory function prototypes + void* MyMalloc(size_t size); + void MyFree(void* ptr); + void* MyRealloc(void* ptr, size_t size); + + // Register custom memory functions with wolfSSL + ret = wolfSSL_SetAllocators(MyMalloc, MyFree, MyRealloc); + if (ret != 0) { + // failed to set memory functions + } + + void* MyMalloc(size_t size) + { + // custom malloc function + } + + void MyFree(void* ptr) + { + // custom free function + } + + void* MyRealloc(void* ptr, size_t size) + { + // custom realloc function + } + \endcode + + \sa none +*/ +WOLFSSL_API int wolfSSL_SetAllocators(wolfSSL_Malloc_cb, + wolfSSL_Free_cb, + wolfSSL_Realloc_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 + 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]; + word32 size = sizeof(buffer); + 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”, + optimum); + ... + \endcode + + \sa wolfSSL_Malloc + \sa wolfSSL_Free +*/ + 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 + memory alignment. + + \return On successfully memory padding calculation the return value will + be a positive value + \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”, + padding); + // calculation of buffer for IO POOL size is number of buckets + // times (padding + WOLFMEM_IO_SZ) + ... + \endcode + + \sa wolfSSL_Malloc + \sa wolfSSL_Free +*/ + WOLFSSL_API int wolfSSL_MemoryPaddingSz(void); diff --git a/doc/dox_comments/header_files/pem.h b/doc/dox_comments/header_files/pem.h new file mode 100644 index 000000000..0b4519b51 --- /dev/null +++ b/doc/dox_comments/header_files/pem.h @@ -0,0 +1,34 @@ +/*! + \ingroup openSSL + + \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. + \param passwd password. + \param len length of password. + \param cb password callback. + \param arg optional argument. + + _Example_ + \code + WOLFSSL_BIO* bio; + WOLFSSL_EVP_PKEY* key; + int ret; + // create bio and setup key + 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 +int wolfSSL_PEM_write_bio_PrivateKey(WOLFSSL_BIO* bio, WOLFSSL_EVP_PKEY* key, + const WOLFSSL_EVP_CIPHER* cipher, + unsigned char* passwd, int len, + pem_password_cb* cb, void* arg); diff --git a/doc/dox_comments/header_files/pkcs7.h b/doc/dox_comments/header_files/pkcs7.h new file mode 100644 index 000000000..4b453ee42 --- /dev/null +++ b/doc/dox_comments/header_files/pkcs7.h @@ -0,0 +1,402 @@ +/*! + \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. + + \return 0 Returned on successfully initializing the PKCS7 structure + \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 + encryption type from the cert + \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 + start date + \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 + from the certificate + \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 from the certificate + \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 + defined and the certificate is a V1 or V2 certificate + \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 + encountered in processing the certificate + \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 + signature fails + \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 certificate’s authenticity + + \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 + certificate with which to initialize the PKCS7 structure + \param certSz size of the certificate buffer + + _Example_ + \code + PKCS7 pkcs7; + byte derBuff[] = { }; // initialize with DER-encoded certificate + if ( wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff)) != 0 ) { + // 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; + // initialize and use PKCS7 object + + 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 + 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 + corresponds to the bytes written to the output buffer. + \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 + certificate + \param outputSz size available in the output buffer + + _Example_ + \code + PKCS7 pkcs7; + int ret; + + byte derBuff[] = { }; // initialize with DER-encoded certificate + byte pkcs7Buff[FOURK_BUF]; + + wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff)); + // update message and data to encode + pkcs7.privateKey = key; + pkcs7.privateKeySz = keySz; + pkcs7.content = data; + pkcs7.contentSz = dataSz; + ... etc. + + ret = wc_PKCS7_EnocodeData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff)); + if ( ret != 0 ) { + // error encoding into output buffer + } + \endcode + + \sa wc_PKCS7_InitWithCert +*/ +WOLFSSL_API int wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output, + word32 outputSz); +/*! + \ingroup 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 + corresponds to the bytes written to the output buffer. + \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 + too large + \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 + the signature + \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 + the signature + \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 + the signature + \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 + the signature + \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 + the signature + \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 + encoded certificate + \param outputSz size available in the output buffer + + _Example_ + \code + PKCS7 pkcs7; + int ret; + + byte derBuff[] = { }; // initialize with DER-encoded certificate + byte pkcs7Buff[FOURK_BUF]; + + wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff)); + // update message and data to encode + pkcs7.privateKey = key; + pkcs7.privateKeySz = keySz; + pkcs7.content = data; + pkcs7.contentSz = dataSz; + ... etc. + + ret = wc_PKCS7_EnocodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff)); + if ( ret != 0 ) { + // error encoding into output buffer + } + \endcode + + \sa wc_PKCS7_InitWithCert + \sa wc_PKCS7_VerifySignedData +*/ +WOLFSSL_API int wc_PKCS7_EncodeSignedData(PKCS7* pkcs7, + byte* output, word32 outputSz); +/*! + \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 + PKCS7 structure. + + \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 + 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 + input too large + \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 + the signature + \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 + the signature + \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 + the signature + \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 + the signature + \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 + the signature + \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 + certificates + \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; + int ret; + + byte derBuff[] = { }; // initialize with DER-encoded certificate + byte pkcs7Buff[FOURK_BUF]; + + wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff)); + // update message and data to encode + pkcs7.privateKey = key; + pkcs7.privateKeySz = keySz; + pkcs7.content = data; + pkcs7.contentSz = dataSz; + ... etc. + + ret = wc_PKCS7_EnocodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff)); + if ( ret != 0 ) { + // error encoding into output buffer + } + \endcode + + \sa wc_PKCS7_InitWithCert + \sa wc_PKCS7_EncodeSignedData +*/ +WOLFSSL_API int wc_PKCS7_VerifySignedData(PKCS7* pkcs7, + byte* pkiMsg, word32 pkiMsgSz); +/*! + \ingroup PKCS7 + + \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 + data format, returns the size written to the output buffer + \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 + 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 + number generator for encryption + \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 + certificate + \param outputSz size available in the output buffer + + _Example_ + \code + PKCS7 pkcs7; + int ret; + + byte derBuff[] = { }; // initialize with DER-encoded certificate + byte pkcs7Buff[FOURK_BUF]; + + wc_PKCS7_InitWithCert(&pkcs7, derBuff, sizeof(derBuff)); + // update message and data to encode + pkcs7.privateKey = key; + pkcs7.privateKeySz = keySz; + pkcs7.content = data; + pkcs7.contentSz = dataSz; + ... etc. + + ret = wc_PKCS7_EncodeEnvelopedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff)); + if ( ret != 0 ) { + // error encoding into output buffer + } + \endcode + + \sa wc_PKCS7_InitWithCert + \sa wc_PKCS7_DecodeEnvelopedData +*/ +WOLFSSL_API int wc_PKCS7_EncodeEnvelopedData(PKCS7* pkcs7, + byte* output, word32 outputSz); +/*! + \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 + PKCS7 object passed in to decrypt 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 + given pkiMsg + \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 + encryption, with RSAk for signature generation + \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 + 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 + verification + \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 + verification + \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 + verification + \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 + verification + \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 + verification + \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 + verification + + \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 + \param output pointer to the buffer in which to store the decoded message + \param outputSz size available in the output buffer + + _Example_ + \code + PKCS7 pkcs7; + byte received[] = { }; // initialize with received enveloped message + byte decoded[FOURK_BUF]; + int decodedSz; + + // initialize pkcs7 with certificate + // update key + pkcs7.privateKey = key; + pkcs7.privateKeySz = keySz; + + 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 +*/ +WOLFSSL_API int wc_PKCS7_DecodeEnvelopedData(PKCS7* pkcs7, byte* pkiMsg, + word32 pkiMsgSz, byte* output, + word32 outputSz); diff --git a/doc/dox_comments/header_files/poly1305.h b/doc/dox_comments/header_files/poly1305.h new file mode 100644 index 000000000..8c59547cb --- /dev/null +++ b/doc/dox_comments/header_files/poly1305.h @@ -0,0 +1,136 @@ +/*! + \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 + generating a message hash with wc_Poly1305Final to ensure security. + + \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, + 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 + + _Example_ + \code + Poly1305 enc; + byte key[] = { initialize with 32 byte key to use for hashing }; + wc_Poly1305SetKey(&enc, key, sizeof(key)); + \endcode + + \sa wc_Poly1305Update + \sa wc_Poly1305Final +*/ +WOLFSSL_API int wc_Poly1305SetKey(Poly1305* poly1305, const byte* key, + word32 kySz); +/*! + \ingroup Poly1305 + + \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 + the message to hash + \param m pointer to the buffer containing the message which should + be added to the hash + \param bytes size of the message to hash + + _Example_ + \code + Poly1305 enc; + byte key[] = { }; // initialize with 32 byte key to use for encryption + + byte msg[] = { }; // initialize with message to hash + wc_Poly1305SetKey(&enc, key, sizeof(key)); + + if( wc_Poly1305Update(key, msg, sizeof(msg)) != 0 ) { + // error updating message to hash + } + \endcode + + \sa wc_Poly1305SetKey + \sa wc_Poly1305Final +*/ +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 + 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. + Should be POLY1305_DIGEST_SIZE (16 bytes) wide + + _Example_ + \code + Poly1305 enc; + byte mac[POLY1305_DIGEST_SIZE]; // space for a 16 byte mac + + byte key[] = { }; // initialize with 32 byte key to use for encryption + + byte msg[] = { }; // initialize with message to hash + wc_Poly1305SetKey(&enc, key, sizeof(key)); + wc_Poly1305Update(key, msg, sizeof(msg)); + + if ( wc_Poly1305Final(&enc, mac) != 0 ) { + // error computing final MAC + } + \endcode + + \sa wc_Poly1305SetKey + \sa wc_Poly1305Update +*/ +WOLFSSL_API int wc_Poly1305Final(Poly1305* poly1305, byte* tag); +/*! + \ingroup Poly1305 + + \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 + 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 + 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 msg[] = { }; // initialize with message + byte tag[16]; + + wc_Poly1305SetKey(&ctx, key, sizeof(key)); + 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 +*/ +WOLFSSL_API int wc_Poly1305_MAC(Poly1305* ctx, byte* additional, word32 addSz, + byte* input, word32 sz, byte* tag, word32 tagSz); diff --git a/doc/dox_comments/header_files/pwdbased.h b/doc/dox_comments/header_files/pwdbased.h new file mode 100644 index 000000000..1104472f8 --- /dev/null +++ b/doc/dox_comments/header_files/pwdbased.h @@ -0,0 +1,164 @@ +/*! + \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 + 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 + 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 + SHA or MD5 object + + \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 + 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 + 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 + 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 salt[] = { }; // initialize with salt + + 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 +*/ +WOLFSSL_API int wc_PBKDF1(byte* output, const byte* passwd, int pLen, + const byte* salt, int sLen, int iterations, int kLen, + int typeH); +/*! + \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, + 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 + iterations is less than 1 + \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. + Should be kLen long + \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 + 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, + SHA, SHA256, SHA384, SHA512, and BLAKE2B + + _Example_ + \code + int ret; + byte key[64]; + byte pass[] = { }; // initialize with password + byte salt[] = { }; // initialize with salt + + 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 +*/ +WOLFSSL_API int wc_PBKDF2(byte* output, const byte* passwd, int pLen, + const byte* salt, int sLen, int iterations, int kLen, + int typeH); +/*! + \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 + 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 + 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 + key generation + \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 + 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. + Should be kLen long + \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 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, + 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. + 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 salt[] = { }; // initialize with salt + + 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 +*/ +WOLFSSL_API int wc_PKCS12_PBKDF(byte* output, const byte* passwd, int pLen, + const byte* salt, int sLen, int iterations, + int kLen, int typeH, int purpose); diff --git a/doc/dox_comments/header_files/rabbit.h b/doc/dox_comments/header_files/rabbit.h new file mode 100644 index 000000000..41601563b --- /dev/null +++ b/doc/dox_comments/header_files/rabbit.h @@ -0,0 +1,65 @@ +/*! + \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 + 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 + defined + \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 + 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; + Rabbit enc; + byte key[] = { }; // initialize with 16 byte key + byte iv[] = { }; // initialize with 8 byte iv + + wc_RabbitSetKey(&enc, key, iv); + + byte message[] = { }; // initialize with plaintext message + byte ciphertext[sizeof(message)]; + + 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 + 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 + use for encryption/decryption + \param iv pointer to the buffer containing the 8 byte iv with + which to initialize the Rabbit structure + + _Example_ + \code + int ret; + Rabbit enc; + byte key[] = { }; // initialize with 16 byte key + byte iv[] = { }; // initialize with 8 byte iv + + 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 new file mode 100644 index 000000000..cf6d64a96 --- /dev/null +++ b/doc/dox_comments/header_files/random.h @@ -0,0 +1,260 @@ +/*! + \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"; + int time = // Some sufficient timeout value; + + if (wc_InitNetRandom(config, NULL, time) != 0) + { + // 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(); + if(ret != 0) + { + // 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 + 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 + MAX_REQUEST_LEN + \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 + status originally not ok, or set to DRBG_FAILED + + \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){ + printf(“RNG Nitrox init for device: %d failed”, CAVIUM_DEV_ID); + return -1; + } + #endif + ret = wc_InitRng(&rng); + if (ret != 0){ + printf(“RNG init failed”); + return -1; + } + \endcode + + \sa wc_InitRngCavium + \sa wc_RNG_GenerateBlock + \sa wc_RNG_GenerateByte + \sa wc_FreeRng + \sa wc_RNG_HealthTest +*/ +WOLFSSL_API int wc_InitRng(WC_RNG*); +/*! + \ingroup Random + + \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 + 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; + int sz = 32; + byte block[sz]; + + int ret = wc_InitRng(&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 + \sa wc_RNG_HealthTest +*/ +WOLFSSL_API int wc_RNG_GenerateBlock(WC_RNG*, byte*, word32 sz); +/*! + \ingroup Random + + \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 + 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; + int sz = 32; + byte b[1]; + + int ret = wc_InitRng(&rng); + if (ret != 0) { + return -1; //init of rng failed! + } + + ret = wc_RNG_GenerateByte(&rng, b); + if (ret != 0) { + return -1; //generating block failed! + } + \endcode + + \sa wc_InitRngCavium + \sa wc_InitRng + \sa wc_RNG_GenerateBlock + \sa wc_FreeRng + \sa wc_RNG_HealthTest +*/ +WOLFSSL_API int wc_RNG_GenerateByte(WC_RNG*, byte*); +/*! + \ingroup Random + + \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; + int ret = wc_InitRng(&rng); + if (ret != 0) { + return -1; //init of rng failed! + } + + int ret = wc_FreeRng(&rng); + 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_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 + 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 + seedrandom is set, and entropyA otherwise + \param outputSz: length of output in bytes + + _Example_ + \code + byte output[SHA256_DIGEST_SIZE * 4]; + const byte test1EntropyB[] = ....; // test input for reseed false + const byte test1Output[] = ....; // testvector: expected output of + // reseed false + ret = wc_RNG_HealthTest(0, test1Entropy, sizeof(test1Entropy), NULL, 0, + output, sizeof(output)); + if (ret != 0) + return -1;//healthtest without reseed failed + + if (XMEMCMP(test1Output, output, sizeof(output)) != 0) + return -1; //compare to testvector failed: unexpected output + + const byte test2EntropyB[] = ....; // test input for reseed + const byte test2Output[] = ....; // testvector expected output of reseed + 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 + \sa wc_RNG_GenerateByte + \sa wc_FreeRng +*/ + WOLFSSL_API int wc_RNG_HealthTest(int reseed, + const byte* entropyA, word32 entropyASz, + const byte* entropyB, word32 entropyBSz, + byte* output, word32 outputSz); diff --git a/doc/dox_comments/header_files/ripemd.h b/doc/dox_comments/header_files/ripemd.h new file mode 100644 index 000000000..24aaf022d --- /dev/null +++ b/doc/dox_comments/header_files/ripemd.h @@ -0,0 +1,101 @@ +/*! + \ingroup RIPEMD + + \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 + 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; + int ret; + ret = wc_InitRipeMd(&md); + if (ret != 0) { + // Failure case. + } + \endcode + + \sa wc_RipeMdUpdate + \sa wc_RipeMdFinal +*/ +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 + 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 + and len is 0. + + \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 + + _Example_ + \code + const byte* data; // The data to be hashed + .... + RipeMd md; + int ret; + ret = wc_InitRipeMd(&md); + if (ret == 0) { + ret = wc_RipeMdUpdate(&md, plain, sizeof(plain)); + 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 + of ripemd is reset. + + \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 + are NULL. + + \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)); + if (ret != 0) { + // RipeMd Update Failure Case. + } + ret = wc_RipeMdFinal(&md, digest); + if (ret != 0) { + // 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 new file mode 100644 index 000000000..66543a882 --- /dev/null +++ b/doc/dox_comments/header_files/rsa.h @@ -0,0 +1,775 @@ +/*! + \ingroup RSA + + \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 + 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 + default used when allocating memory for use with this RSA object + + _Example_ + \code + RsaKey enc; + int ret; + ret = wc_RsaInitKey(&enc, NULL); // not using heap hint. No custom memory + if ( ret != 0 ) { + // error initializing RSA key + } + \endcode + + \sa wc_RsaInitCavium + \sa wc_FreeRsaKey +*/ +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; + wc_RsaInitKey(&enc, NULL); // not using heap hint. No custom memory + ... set key, do encryption + + 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 + to out in outLen. + + \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 + 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 + the ciphertext + \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 + library used while encrypting the message + \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 + library used while encrypting the message + \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 + library used while encrypting the message + \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 + library used while encrypting the message + \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 + library used while encrypting the message + \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 + library used while encrypting the message + \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 + key to use for encryption + \param rng The RNG structure with which to generate random block padding + + _Example_ + \code + RsaKey pub; + int ret = 0; + 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 + 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 + ret = wc_RsaPublicEncrypt(msg, sizeof(msg), out, sizeof(out), &pub, &rng); + if ( ret != 0 ) { + // error encrypting message + } + \endcode + + \sa wc_RsaPrivateDecrypt +*/ +WOLFSSL_API int wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out, + word32 outLen, RsaKey* key, WC_RNG* rng); +/*! + \ingroup RSA + + \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, + RsaKey* key); +/*! + \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 + + \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 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); + if (ret < 0) { + return -1; + } + ret = wc_RsaPrivateDecrypt(out, ret, plain, sizeof(plain), &key); + if (ret < 0) { + return -1; + } + \endcode + + \sa RsaUnPad + \sa wc_RsaFunction + \sa wc_RsaPrivateDecryptInline +*/ +WOLFSSL_API int wc_RsaPrivateDecrypt(const byte* in, word32 inLen, byte* out, + word32 outLen, RsaKey* key); +/*! + \ingroup RSA + + \brief Signs the provided array with the private key. + + \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); + if (ret < 0) { + return -1; + } + memset(plain, 0, sizeof(plain)); + ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key); + if (ret < 0) { + return -1; + } + \endcode + + \sa wc_RsaPad +*/ +WOLFSSL_API int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out, + word32 outLen, RsaKey* key, WC_RNG* rng); +/*! + \ingroup RSA + + \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; + RNG rng; + int ret = 0; + long e = 65537; // standard value to use for exponent + wc_InitRsaKey(&key, NULL); // not using heap hint. No custom memory + wc_InitRng(&rng); + wc_MakeRsaKey(&key, 2048, e, &rng); + + byte in[] = { // Initialize with some RSA encrypted information } + byte* out; + if(wc_RsaSSL_VerifyInline(in, sizeof(in), &out, &key) < 0) + { + // handle error + } + \endcode + + \sa wc_RsaSSL_Verify + \sa wc_RsaSSL_Sign +*/ +WOLFSSL_API int wc_RsaSSL_VerifyInline(byte* in, word32 inLen, byte** out, + RsaKey* key); +/*! + \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. + + \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 outLen The length of out. + \param key The key to use for verification. + + _Example_ + \code + ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng); + if (ret < 0) { + return -1; + } + memset(plain, 0, sizeof(plain)); + ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key); + if (ret < 0) { + return -1; + } + \endcode + + \sa wc_RsaSSL_Sign +*/ +WOLFSSL_API int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out, + word32 outLen, RsaKey* key); +/*! + \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 + \sa XMEMSET +*/ +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 + distance parsed in idx. + + \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 + properly formatted according to ASN.1 standards + \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 + 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 + distance parsed through the input buffer + \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; + word32 idx = 0; + int ret = 0; + byte der[] = { // initialize with DER-encoded RSA private 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 + } + \endcode + + \sa wc_RsaPublicKeyDecode + \sa wc_MakeRsaKey +*/ +WOLFSSL_API int wc_RsaPrivateKeyDecode(const byte* input, word32* inOutIdx, + RsaKey*, word32); +/*! + \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 + distance parsed in idx. + + \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 + properly formatted according to ASN.1 standards + \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 + 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 + elements of the RSA key input + + \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 + store the distance parsed through the input buffer + \param key pointer to the RsaKey structure in which to store the decoded + public key + \param inSz size of the input buffer + + _Example_ + \code + RsaKey pub; + word32 idx = 0; + int ret = 0; + byte der[] = { // initialize with DER-encoded RSA public key }; + + 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 + } + \endcode + + \sa wc_RsaPublicKeyDecodeRaw +*/ +WOLFSSL_API int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx, + RsaKey*, word32); +/*! + \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 + encryption/decryption process. + + \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 + NULL + \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 + provided RSA key elements, n or e + + \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 + the public RSA key + \param eSz size of the buffer containing e + \param key pointer to the RsaKey struct to initialize with the provided + public key elements + + _Example_ + \code + RsaKey pub; + int ret = 0; + byte n[] = { // initialize with received n component of public key }; + byte e[] = { // initialize with received e component of public key }; + + wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory + ret = wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub); + if( ret != 0 ) { + // error parsing public key elements + } + \endcode + + \sa wc_RsaPublicKeyDecode +*/ +WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz, + const byte* e, word32 eSz, RsaKey* key); +/*! + \ingroup RSA + + \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 + 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; + // Allocate memory for der + int derSz = // Amount of memory allocated for der; + RsaKey key; + RNG rng; + long e = 65537; // standard value to use for exponent + ret = wc_MakeRsaKey(&key, 2048, e, &rng); // generate 2048 bit long + private key + wc_InitRsaKey(&key, NULL); + wc_InitRng(&rng); + if(wc_RsaKeyToDer(&key, der, derSz) != 0) + { + // Handle the error thrown + } + \endcode + + \sa wc_RsaKeyToPublicDer + \sa wc_InitRsaKey + \sa wc_MakeRsaKey + \sa wc_InitRng +*/ + WOLFSSL_API int wc_RsaKeyToDer(RsaKey*, byte* output, word32 inLen); +/*! + \ingroup RSA + + \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 + 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 + \param outLen length of buffer available to hold encrypted msg + \param key initialized RSA key struct + \param rng initialized WC_RNG struct + \param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD) + \param hash type of hash to use (choices can be found in hash.h) + \param mgf type of mask generation function to use + \param label an optional label to associate with encrypted message + \param labelSz size of the optional label used + + _Example_ + \code + WC_RNG rng; + RsaKey key; + byte in[] = “I use Turing Machines to ask questions” + byte out[256]; + int ret; + … + + 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 +*/ +WOLFSSL_API int wc_RsaPublicEncrypt_ex(const byte* in, word32 inLen, byte* out, + word32 outLen, RsaKey* key, WC_RNG* rng, int type, + enum wc_HashType hash, int mgf, byte* label, word32 lableSz); +/*! + \ingroup RSA + + \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 + is returned. + \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 + function. + + \param in pointer to the buffer for decryption + \param inLen length of the buffer to decrypt + \param out decrypted msg created + \param outLen length of buffer available to hold decrypted msg + \param key initialized RSA key struct + \param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD) + \param hash type of hash to use (choices can be found in hash.h) + \param mgf type of mask generation function to use + \param label an optional label to associate with encrypted message + \param labelSz size of the optional label used + + _Example_ + \code + WC_RNG rng; + RsaKey key; + byte in[] = “I use Turing Machines to ask questions” + byte out[256]; + byte plain[256]; + int ret; + … + 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, + 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, + byte* out, word32 outLen, RsaKey* key, int type, + enum wc_HashType hash, int mgf, byte* label, word32 lableSz); +/*! + \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 + location in the “in” buffer where the plain text is. + + \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 + 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 + padding. + \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 pointer to location of decrypted message in “in” buffer + \param key initialized RSA key struct + \param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD) + \param hash type of hash to use (choices can be found in hash.h) + \param mgf type of mask generation function to use + \param label an optional label to associate with encrypted message + \param labelSz size of the optional label used + + _Example_ + \code + WC_RNG rng; + RsaKey key; + byte in[] = “I use Turing Machines to ask questions” + byte out[256]; + byte* plain; + int ret; + … + 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, + 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, + byte** out, RsaKey* key, int type, enum wc_HashType hash, + int mgf, byte* label, word32 lableSz); +/*! + \ingroup RSA + + \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 + with a null value. + \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 + 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 + the RSA modular arithmetic operation. + \param nSz the size of the n buffer. + + _Example_ + \code + Rsa key; // A valid RSA key. + byte e[ buffer sz E.g. 256 ]; + byte n[256]; + int ret; + word32 eSz = sizeof(e); + word32 nSz = sizeof(n); + ... + ret = wc_RsaFlattenPublicKey(&key, e, &eSz, n, &nSz); + if (ret != 0) { + // Failure case. + } + \endcode + + \sa wc_InitRsaKey + \sa wc_InitRsaKey_ex + \sa wc_MakeRsaKey + \sa XMEMSET +*/ +WOLFSSL_API int wc_RsaFlattenPublicKey(RsaKey*, byte*, word32*, byte*, + word32*); +/*! + \ingroup RSA + + \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. + \return <0 Error + + \param key The RSA key structure to convert. + \param output Output buffer to hold DER. + \param inLen Length of buffer. + + _Example_ + \code + RsaKey key; + + wc_RsaInitKey(&key, NULL); + // Use key + + int BUFFER_SIZE = // Some adequate size for the buffer + byte output[BUFFER_SIZE]; + if(wc_RsaKeyToPublicDer(&key, output, sizeof(output)) != 0) + { + // Handle Error + } + \endcode + + \sa wc_RsaKeyToPublicDer + \sa wc_RsaInitKey +*/ + 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. + 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 + incorrectly chosen + \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 + 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 + used while generating the RSA key + \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 + library used while generating the RSA key + \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 + library used while generating the RSA key + \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 + library used while generating the RSA key + \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 + library used while generating the RSA key + \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 + generated private key + \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 + choice is 65537 + \param rng pointer to an RNG structure to use for random number generation + while making the ke + + _Example_ + \code + RsaKey priv; + RNG rng; + int ret = 0; + long e = 65537; // standard value to use for exponent + + 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); + 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 new file mode 100644 index 000000000..0b22d5939 --- /dev/null +++ b/doc/dox_comments/header_files/sha.h @@ -0,0 +1,141 @@ +/*! + \ingroup SHA + + \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]; + if ((ret = wc_InitSha(sha)) != 0) { + WOLFSSL_MSG("wc_InitSha failed"); + } + else { + wc_ShaUpdate(sha, data, len); + wc_ShaFinal(sha, hash); + } + \endcode + + \sa wc_ShaHash + \sa wc_ShaUpdate + \sa wc_ShaFinal +*/ +WOLFSSL_API int wc_InitSha(wc_Sha*); +/*! + \ingroup SHA + + \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]; + byte data[] = { // Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha(sha)) != 0) { + WOLFSSL_MSG("wc_InitSha failed"); + } + else { + wc_ShaUpdate(sha, data, len); + wc_ShaFinal(sha, hash); + } + \endcode + + \sa wc_ShaHash + \sa wc_ShaFinal + \sa wc_InitSha +*/ +WOLFSSL_API int wc_ShaUpdate(wc_Sha*, const byte*, word32); +/*! + \ingroup SHA + + \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]; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha(sha)) != 0) { + WOLFSSL_MSG("wc_InitSha failed"); + } + else { + wc_ShaUpdate(sha, data, len); + wc_ShaFinal(sha, hash); + } + \endcode + + \sa wc_ShaHash + \sa wc_InitSha + \sa wc_ShaGetHash +*/ +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; + wc_InitSha(&sha); + // Use sha + wc_ShaFree(&sha); + \endcode + + \sa wc_InitSha + \sa wc_ShaUpdate + \sa wc_ShaFinal +*/ +WOLFSSL_API void wc_ShaFree(wc_Sha*); +/*! + \ingroup SHA + + \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]; + if ((ret = wc_InitSha(sha)) != 0) { + WOLFSSL_MSG("wc_InitSha failed"); + } + else { + wc_ShaUpdate(sha, data, len); + wc_ShaGetHash(sha, hash); + } + \endcode + + \sa wc_ShaHash + \sa wc_ShaFinal + \sa wc_InitSha +*/ +WOLFSSL_API int wc_ShaGetHash(wc_Sha*, byte*); diff --git a/doc/dox_comments/header_files/sha256.h b/doc/dox_comments/header_files/sha256.h new file mode 100644 index 000000000..998e8be90 --- /dev/null +++ b/doc/dox_comments/header_files/sha256.h @@ -0,0 +1,239 @@ +/*! + \ingroup SHA + + \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]; + if ((ret = wc_InitSha356(sha256)) != 0) { + WOLFSSL_MSG("wc_InitSha256 failed"); + } + else { + wc_Sha256Update(sha256, data, len); + wc_Sha256Final(sha256, hash); + } + \endcode + + \sa wc_Sha256Hash + \sa wc_Sha256Update + \sa wc_Sha256Final +*/ +WOLFSSL_API int wc_InitSha256(wc_Sha256*); +/*! + \ingroup SHA + + \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]; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha256(sha256)) != 0) { + WOLFSSL_MSG("wc_InitSha256 failed"); + } + else { + wc_Sha256Update(sha256, data, len); + wc_Sha256Final(sha256, hash); + } + \endcode + + \sa wc_Sha256Hash + \sa wc_Sha256Final + \sa wc_InitSha256 +*/ +WOLFSSL_API int wc_Sha256Update(wc_Sha256*, const byte*, word32); +/*! + \ingroup SHA + + \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]; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha356(sha256)) != 0) { + WOLFSSL_MSG("wc_InitSha256 failed"); + } + else { + wc_Sha256Update(sha256, data, len); + wc_Sha256Final(sha256, hash); + } + \endcode + + \sa wc_Sha256Hash + \sa wc_Sha256GetHash + \sa wc_InitSha256 +*/ +WOLFSSL_API int wc_Sha256Final(wc_Sha256*, byte*); +/*! + \ingroup SHA + + \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_ + \code + Sha256 sha256; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha256(&sha256)) != 0) { + WOLFSSL_MSG("wc_InitSha256 failed"); + } + else { + wc_Sha256Update(&sha256, data, len); + wc_Sha256Final(&sha256, hash); + wc_Sha256Free(&sha256); + } + \endcode + + \sa wc_InitSha256 + \sa wc_Sha256Update + \sa wc_Sha256Final +*/ +WOLFSSL_API void wc_Sha256Free(wc_Sha256*); +/*! + \ingroup SHA + + \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]; + if ((ret = wc_InitSha356(sha256)) != 0) { + WOLFSSL_MSG("wc_InitSha256 failed"); + } + else { + wc_Sha256Update(sha256, data, len); + wc_Sha256GetHash(sha256, hash); + } + \endcode + + \sa wc_Sha256Hash + \sa wc_Sha256Final + \sa wc_InitSha256 +*/ +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; + if(wc_InitSha224(&sha224) != 0) + { + // Handle error + } + \endcode + + \sa wc_Sha224Hash + \sa wc_Sha224Update + \sa wc_Sha224Final +*/ +WOLFSSL_API int wc_InitSha224(wc_Sha224*); +/*! + \ingroup SHA + + \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. + + \param sha224 Pointer to the Sha224 structure to use for encryption. + \param data Data to be hashed. + \param len Length of data to be hashed. + + _Example_ + \code + Sha224 sha224; + byte data[] = { /* Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha224(&sha224)) != 0) { + WOLFSSL_MSG("wc_InitSha224 failed"); + } + else { + wc_Sha224Update(&sha224, data, len); + wc_Sha224Final(&sha224, hash); + } + \endcode + + \sa wc_InitSha224 + \sa wc_Sha224Final + \sa wc_Sha224Hash +*/ +WOLFSSL_API int wc_Sha224Update(wc_Sha224*, const byte*, word32); +/*! + \ingroup SHA + + \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; + byte data[] = { /* Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha224(&sha224)) != 0) { + WOLFSSL_MSG("wc_InitSha224 failed"); + } + else { + wc_Sha256Update(&sha224, data, len); + wc_Sha256Final(&sha224, hash); + } + \endcode + + \sa wc_InitSha224 + \sa wc_Sha224Hash + \sa wc_Sha224Update +*/ +WOLFSSL_API int wc_Sha224Final(wc_Sha224*, byte*); diff --git a/doc/dox_comments/header_files/sha512.h b/doc/dox_comments/header_files/sha512.h new file mode 100644 index 000000000..0fae9bf8b --- /dev/null +++ b/doc/dox_comments/header_files/sha512.h @@ -0,0 +1,178 @@ +/*! + \ingroup SHA + + \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]; + if ((ret = wc_InitSha512(sha512)) != 0) { + WOLFSSL_MSG("wc_InitSha512 failed"); + } + else { + wc_Sha512Update(sha512, data, len); + wc_Sha512Final(sha512, hash); + } + \endcode + + \sa wc_Sha512Hash + \sa wc_Sha512Update + \sa wc_Sha512Final +*/ +WOLFSSL_API int wc_InitSha512(wc_Sha512*); +/*! + \ingroup SHA + + \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]; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha512(sha512)) != 0) { + WOLFSSL_MSG("wc_InitSha512 failed"); + } + else { + wc_Sha512Update(sha512, data, len); + wc_Sha512Final(sha512, hash); + } + \endcode + + \sa wc_Sha512Hash + \sa wc_Sha512Final + \sa wc_InitSha512 +*/ +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]; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha512(sha512)) != 0) { + WOLFSSL_MSG("wc_InitSha512 failed"); + } + else { + wc_Sha512Update(sha512, data, len); + wc_Sha512Final(sha512, hash); + } + \endcode + + \sa wc_Sha512Hash + \sa wc_Sha512Final + \sa wc_InitSha512 +*/ +WOLFSSL_API int wc_Sha512Final(wc_Sha512*, byte*); +/*! + \ingroup SHA + + \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]; + if ((ret = wc_InitSha384(sha384)) != 0) { + WOLFSSL_MSG("wc_InitSha384 failed"); + } + else { + wc_Sha384Update(sha384, data, len); + wc_Sha384Final(sha384, hash); + } + \endcode + + \sa wc_Sha384Hash + \sa wc_Sha384Update + \sa wc_Sha384Final +*/ +WOLFSSL_API int wc_InitSha384(wc_Sha384*); +/*! + \ingroup SHA + + \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 + + _Example_ + \code + Sha384 sha384[1]; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha384(sha384)) != 0) { + WOLFSSL_MSG("wc_InitSha384 failed"); + } + else { + wc_Sha384Update(sha384, data, len); + wc_Sha384Final(sha384, hash); + } + \endcode + + \sa wc_Sha384Hash + \sa wc_Sha384Final + \sa wc_InitSha384 +*/ +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]; + byte data[] = { Data to be hashed }; + word32 len = sizeof(data); + + if ((ret = wc_InitSha384(sha384)) != 0) { + WOLFSSL_MSG("wc_InitSha384 failed"); + } + else { + wc_Sha384Update(sha384, data, len); + wc_Sha384Final(sha384, hash); + } + \endcode + + \sa wc_Sha384Hash + \sa wc_Sha384Final + \sa wc_InitSha384 +*/ +WOLFSSL_API int wc_Sha384Final(wc_Sha384*, byte*); diff --git a/doc/dox_comments/header_files/signature.h b/doc/dox_comments/header_files/signature.h new file mode 100644 index 000000000..72660e25e --- /dev/null +++ b/doc/dox_comments/header_files/signature.h @@ -0,0 +1,145 @@ +/*! + \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 + the maximum size of a signature. + + \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 + enum wc_SignatureType sig_type = WC_SIGNATURE_TYPE_ECC; + ecc_key eccKey; + word32 sigLen; + wc_ecc_init(&eccKey); + sigLen = wc_SignatureGetSize(sig_type, &eccKey, sizeof(eccKey)); + if (sigLen > 0) { + // Success + } + \endcode + + \sa wc_HashGetDigestSize + \sa wc_SignatureGenerate + \sa wc_SignatureVerify +*/ +WOLFSSL_API int wc_SignatureGetSize(enum wc_SignatureType sig_type, + const void* key, word32 key_len); +/*! + \ingroup Signature + + \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 + “WC_HASH_TYPE_SHA256”. + \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. + \param sig Pointer to buffer to output signature. + \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; + ecc_key eccKey; + + // Import the public key + wc_ecc_init(&eccKey); + ret = wc_ecc_import_x963(eccPubKeyBuf, eccPubKeyLen, &eccKey); + // Perform signature verification using public key + ret = wc_SignatureVerify( + WC_HASH_TYPE_SHA256, WC_SIGNATURE_TYPE_ECC, + fileBuf, fileLen, + sigBuf, sigLen, + &eccKey, sizeof(eccKey)); + printf("Signature Verification: %s + (%d)\n", (ret == 0) ? "Pass" : "Fail", ret); + wc_ecc_free(&eccKey); + \endcode + + \sa wc_SignatureGetSize + \sa wc_SignatureGenerate +*/ +WOLFSSL_API int wc_SignatureVerify( + enum wc_HashType hash_type, enum wc_SignatureType sig_type, + const byte* data, word32 data_len, + const byte* sig, word32 sig_len, + const void* key, word32 key_len); +/*! + \ingroup Signature + + \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” + such as “WC_HASH_TYPE_SHA256”. + \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. + \param sig Pointer to buffer to output signature. + \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. + \param rng Pointer to an initialized RNG structure. + + _Example_ + \code + int ret; + RNG rng; + ecc_key eccKey; + + wc_InitRng(&rng); + wc_ecc_init(&eccKey); + + // Generate key + ret = wc_ecc_make_key(&rng, 32, &eccKey); + + // Get signature length and allocate buffer + sigLen = wc_SignatureGetSize(sig_type, &eccKey, sizeof(eccKey)); + sigBuf = malloc(sigLen); + + // Perform signature verification using public key + ret = wc_SignatureGenerate( + WC_HASH_TYPE_SHA256, WC_SIGNATURE_TYPE_ECC, + fileBuf, fileLen, + sigBuf, &sigLen, + &eccKey, sizeof(eccKey), + &rng); + 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 +*/ +WOLFSSL_API int wc_SignatureGenerate( + enum wc_HashType hash_type, enum wc_SignatureType sig_type, + const byte* data, word32 data_len, + byte* sig, word32 *sig_len, + const void* key, word32 key_len, + WC_RNG* rng); diff --git a/doc/dox_comments/header_files/srp.h b/doc/dox_comments/header_files/srp.h new file mode 100644 index 000000000..1829e0bb1 --- /dev/null +++ b/doc/dox_comments/header_files/srp.h @@ -0,0 +1,496 @@ +/*! + \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 + 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 + 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; + if (wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE) != 0) + { + // Initialization error + } + else + { + wc_SrpTerm(&srp); + } + \endcode + + \sa wc_SrpTerm + \sa wc_SrpSetUsername +*/ +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; + wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_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 + 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; + byte username[] = "user"; + word32 usernameSize = 4; + + wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE); + if(wc_SrpSetUsername(&srp, username, usernameSize) != 0) + { + // Error occurred setting username. + } + wc_SrpTerm(&srp); + \endcode + + \sa wc_SrpInit + \sa wc_SrpSetParams + \sa wc_SrpTerm +*/ +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 + 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 +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. + \param g the Generator modulo N. + \param gSz the g size in bytes + \param salt a small random salt. Specific for each username. + \param saltSz the salt size in bytes + + _Example_ + \code + Srp srp; + byte username[] = "user"; + word32 usernameSize = 4; + + byte N[] = { }; // Contents of byte array N + byte g[] = { }; // Contents of byte array g + byte salt[] = { }; // Contents of byte array salt + + 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, + sizeof(salt)) != 0) + { + // Error setting params + } + wc_SrpTerm(&srp); + \endcode + + \sa wc_SrpInit + \sa wc_SrpSetUsername + \sa wc_SrpTerm +*/ +WOLFSSL_API int wc_SrpSetParams(Srp* srp, const byte* N, word32 nSz, + const byte* g, word32 gSz, + const byte* salt, word32 saltSz); +/*! + \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 + 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 + is not set to SRP_CLIENT_SIDE. + \return SRP_CALL_ORDER_E Returns when wc_SrpSetPassword is called out + of order. + \return <0 Error + + \param srp The Srp structure. + \param password The buffer containing the password. + \param size The size of the password in bytes. + + _Example_ + \code + Srp srp; + byte username[] = "user"; + word32 usernameSize = 4; + byte password[] = "password"; + word32 passwordSize = 8; + + byte N[] = { }; // Contents of byte array N + byte g[] = { }; // Contents of byte array g + byte salt[] = { }; // Contents of byte array salt + + wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE); + wc_SrpSetUsername(&srp, username, usernameSize); + wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt)); + + if(wc_SrpSetPassword(&srp, password, passwordSize) != 0) + { + // Error setting password + } + + wc_SrpTerm(&srp); + \endcode + + \sa wc_SrpInit + \sa wc_SrpSetUsername + \sa wc_SrpSetParams +*/ +WOLFSSL_API int wc_SrpSetPassword(Srp* srp, const byte* password, word32 size); +/*! + \ingroup SRP + + \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 + srp->side is not SRP_SERVER_SIDE. + \return <0 Error + + \param srp The Srp structure. + \param verifier The structure containing the verifier. + \param size The verifier size in bytes. + + _Example_ + \code + Srp srp; + byte username[] = "user"; + word32 usernameSize = 4; + + byte N[] = { }; // Contents of byte array N + byte g[] = { }; // Contents of byte array g + byte salt[] = { }; // Contents of byte array salt + wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_SERVER_SIDE); + wc_SrpSetUsername(&srp, username, usernameSize); + wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt)) + byte verifier[] = { }; // Contents of some verifier + + if(wc_SrpSetVerifier(&srp, verifier, sizeof(verifier)) != 0) + { + // Error setting verifier + } + + wc_SrpTerm(&srp); + \endcode + + \sa wc_SrpInit + \sa wc_SrpSetParams + \sa wc_SrpGetVerifier +*/ +WOLFSSL_API int wc_SrpSetVerifier(Srp* srp, const byte* verifier, word32 size); +/*! + \ingroup SRP + + \brief Gets the verifier. The client calculates the verifier + with v = g ^ x % N. + 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 + or if srp->side is not SRP_CLIENT_SIDE. + \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; + byte username[] = "user"; + word32 usernameSize = 4; + byte password[] = "password"; + word32 passwordSize = 8; + + byte N[] = { }; // Contents of byte array N + byte g[] = { }; // Contents of byte array g + byte salt[] = { }; // Contents of byte array salt + byte v[64]; + word32 vSz = 0; + vSz = sizeof(v); + + wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE); + wc_SrpSetUsername(&srp, username, usernameSize); + wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt)) + wc_SrpSetPassword(&srp, password, passwordSize) + + if( wc_SrpGetVerifier(&srp, v, &vSz ) != 0) + { + // Error getting verifier + } + wc_SrpTerm(&srp); + \endcode + + \sa wc_SrpSetVerifier + \sa wc_SrpSetPassword +*/ +WOLFSSL_API int wc_SrpGetVerifier(Srp* srp, byte* verifier, word32* size); +/*! + \ingroup SRP + + \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 + to use an external + 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 + of order. + \return <0 Error + + \param srp the Srp structure. + \param priv the ephemeral value. + \param size the private size in bytes. + + _Example_ + \code + Srp srp; + byte username[] = "user"; + word32 usernameSize = 4; + + byte N[] = { }; // Contents of byte array N + byte g[] = { }; // Contents of byte array g + byte salt[] = { }; // Contents of byte array salt + byte verifier = { }; // Contents of some verifier + wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_SERVER_SIDE); + wc_SrpSetUsername(&srp, username, usernameSize); + wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt)) + wc_SrpSetVerifier(&srp, verifier, sizeof(verifier)) + + byte b[] = { }; // Some ephemeral value + if( wc_SrpSetPrivate(&srp, b, sizeof(b)) != 0) + { + // Error setting private ephemeral + } + + 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 + 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 + 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 + the ephemeral value size. + + _Example_ + \code + Srp srp; + byte username[] = "user"; + word32 usernameSize = 4; + byte password[] = "password"; + word32 passwordSize = 8; + + byte N[] = { }; // Contents of byte array N + byte g[] = { }; // Contents of byte array g + byte salt[] = { }; // Contents of byte array salt + wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE); + wc_SrpSetUsername(&srp, username, usernameSize); + wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt)); + wc_SrpSetPassword(&srp, password, passwordSize) + + byte public[64]; + word32 publicSz = 0; + + if( wc_SrpGetPublic(&srp, public, &publicSz) != 0) + { + // Error getting public ephemeral + } + + wc_SrpTerm(&srp); + \endcode + + \sa wc_SrpSetPrivate + \sa wc_SrpSetPassword + \sa wc_SrpSetVerifier +*/ +WOLFSSL_API int wc_SrpGetPublic(Srp* srp, byte* pub, word32* size); +/*! + \ingroup SRP + + \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 + or if clientPubKeySz or serverPubKeySz is 0. + \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. + \param serverPubKey the server's public ephemeral value. + \param serverPubKeySz the server's public ephemeral value size. + + _Example_ + \code + Srp server; + + byte username[] = "user"; + word32 usernameSize = 4; + byte password[] = "password"; + word32 passwordSize = 8; + byte N[] = { }; // Contents of byte array N + byte g[] = { }; // Contents of byte array g + byte salt[] = { }; // Contents of byte array salt + byte verifier[] = { }; // Contents of some verifier + byte serverPubKey[] = { }; // Contents of server pub key + word32 serverPubKeySize = sizeof(serverPubKey); + byte clientPubKey[64]; + word32 clientPubKeySize = 64; + + wc_SrpInit(&server, SRP_TYPE_SHA, SRP_SERVER_SIDE); + wc_SrpSetUsername(&server, username, usernameSize); + wc_SrpSetParams(&server, N, sizeof(N), g, sizeof(g), salt, sizeof(salt)); + wc_SrpSetVerifier(&server, verifier, sizeof(verifier)); + wc_SrpGetPublic(&server, serverPubKey, &serverPubKeySize); + + wc_SrpComputeKey(&server, clientPubKey, clientPubKeySz, + serverPubKey, serverPubKeySize) + wc_SrpTerm(&server); + \endcode + + \sa wc_SrpGetPublic +*/ +WOLFSSL_API int wc_SrpComputeKey(Srp* srp, + byte* clientPubKey, word32 clientPubKeySz, + byte* serverPubKey, word32 serverPubKeySz); +/*! + \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. + \return <0 Error + + \param srp the Srp structure. + \param proof the peers proof. + \param size the proof size in bytes. + + _Example_ + \code + Srp cli; + byte clientProof[SRP_MAX_DIGEST_SIZE]; + word32 clientProofSz = SRP_MAX_DIGEST_SIZE; + + // Initialize Srp following steps from previous examples + + if (wc_SrpGetProof(&cli, clientProof, &clientProofSz) != 0) + { + // 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 + 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; + Srp srv; + byte clientProof[SRP_MAX_DIGEST_SIZE]; + word32 clientProofSz = SRP_MAX_DIGEST_SIZE; + + // Initialize Srp following steps from previous examples + // First get the proof + wc_SrpGetProof(&cli, clientProof, &clientProofSz) + + if (wc_SrpVerifyPeersProof(&srv, clientProof, clientProofSz) != 0) + { + // Error verifying proof + } + \endcode + + \sa wc_SrpGetSessionKey + \sa wc_SrpGetProof + \sa wc_SrpTerm +*/ +WOLFSSL_API int wc_SrpVerifyPeersProof(Srp* srp, byte* proof, word32 size); diff --git a/doc/dox_comments/header_files/ssl.h b/doc/dox_comments/header_files/ssl.h new file mode 100644 index 000000000..5259c6d83 --- /dev/null +++ b/doc/dox_comments/header_files/ssl.h @@ -0,0 +1,11711 @@ +/*! + \brief This function initializes the DTLS v1.2 client method. + + \return pointer This function returns a pointer to a new + WOLFSSL_METHOD structure. + + \param none No parameters. + + _Example_ + \code + wolfSSL_Init(); + WOLFSSL_CTX* ctx = wolfSSL_CTX_new(wolfDTLSv1_2_client_method()); + … + WOLFSSL* ssl = wolfSSL_new(ctx); + … + \endcode + + \sa wolfSSL_Init + \sa wolfSSL_CTX_new +*/ +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 + which side yet (server/client). + + \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 +*/ +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 + with wolfSSL_CTX_new(). + + \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 + (typically NULL with errno will be set to ENOMEM). + + \param none No parameters. + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfSSLv3_server_method(); + if (method == NULL) { + unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfTLSv1_server_method + \sa wolfTLSv1_1_server_method + \sa wolfTLSv1_2_server_method + \sa wolfDTLSv1_server_method + \sa wolfSSLv23_server_method + \sa wolfSSL_CTX_new + +*/ +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 + context with wolfSSL_CTX_new(). + + \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 (typically NULL with errno will be set to ENOMEM). + + \param none No parameters. + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfSSLv3_client_method(); + if (method == NULL) { + unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfTLSv1_client_method + \sa wolfTLSv1_1_client_method + \sa wolfTLSv1_2_client_method + \sa wolfDTLSv1_client_method + \sa wolfSSLv23_client_method + \sa wolfSSL_CTX_new +*/ +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 + wolfSSL_CTX_new(). + + \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 + (typically NULL with errno will be set to ENOMEM). + + \param none No parameters. + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfTLSv1_server_method(); + if (method == NULL) { + unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_server_method + \sa wolfTLSv1_1_server_method + \sa wolfTLSv1_2_server_method + \sa wolfDTLSv1_server_method + \sa wolfSSLv23_server_method + \sa wolfSSL_CTX_new +*/ +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 + with wolfSSL_CTX_new(). + + \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 (typically NULL with errno will be set to ENOMEM). + + \param none No parameters. + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfTLSv1_client_method(); + if (method == NULL) { + unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_client_method + \sa wolfTLSv1_1_client_method + \sa wolfTLSv1_2_client_method + \sa wolfDTLSv1_client_method + \sa wolfSSLv23_client_method + \sa wolfSSL_CTX_new +*/ +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 + context with wolfSSL_CTX_new(). + + \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 + (typically NULL with errno will be set to ENOMEM). + + \param none No parameters. + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfTLSv1_1_server_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_server_method + \sa wolfTLSv1_server_method + \sa wolfTLSv1_2_server_method + \sa wolfDTLSv1_server_method + \sa wolfSSLv23_server_method + \sa wolfSSL_CTX_new +*/ +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 + context with wolfSSL_CTX_new(). + + \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 + (typically NULL with errno will be set to ENOMEM). + + \param none No parameters. + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfTLSv1_1_client_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_client_method + \sa wolfTLSv1_client_method + \sa wolfTLSv1_2_client_method + \sa wolfDTLSv1_client_method + \sa wolfSSLv23_client_method + \sa wolfSSL_CTX_new +*/ +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 + with wolfSSL_CTX_new(). + + \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 + (typically NULL with errno will be set to ENOMEM). + + \param none No parameters. + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfTLSv1_2_server_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_server_method + \sa wolfTLSv1_server_method + \sa wolfTLSv1_1_server_method + \sa wolfDTLSv1_server_method + \sa wolfSSLv23_server_method + \sa wolfSSL_CTX_new +*/ +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 + with wolfSSL_CTX_new(). + + \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 + (typically NULL with errno will be set to ENOMEM). + + \param none No parameters. + + _Example_ + \code + #include + + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfTLSv1_2_client_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_client_method + \sa wolfTLSv1_client_method + \sa wolfTLSv1_1_client_method + \sa wolfDTLSv1_client_method + \sa wolfSSLv23_client_method + \sa wolfSSL_CTX_new +*/ +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, + or by defining wolfSSL_DTLS). + + \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 + (typically NULL with errno will be set to ENOMEM). + + \param none No parameters. + + _Example_ + \code + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfDTLSv1_client_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_client_method + \sa wolfTLSv1_client_method + \sa wolfTLSv1_1_client_method + \sa wolfTLSv1_2_client_method + \sa wolfSSLv23_client_method + \sa wolfSSL_CTX_new +*/ +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, + or by defining wolfSSL_DTLS). + + \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 + (typically NULL with errno will be set to ENOMEM). + + \param none No parameters. + + _Example_ + \code + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfDTLSv1_server_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_server_method + \sa wolfTLSv1_server_method + \sa wolfTLSv1_1_server_method + \sa wolfTLSv1_2_server_method + \sa wolfSSLv23_server_method + \sa wolfSSL_CTX_new +*/ +WOLFSSL_API WOLFSSL_METHOD *wolfDTLSv1_server_method(void); +/*! + \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()); + WOLFSSL* ssl = WOLFSSL_new(ctx); + … + \endcode + + \sa wolfSSL_CTX_new +*/ +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 + 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 + of 0. + + _Example_ + \code + int ret = 0; + WOLFSSL* ssl; + ... + + ret = wolfSSL_use_old_poly(ssl, 1); + if (ret != 0) { + // 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 + handshake has been completed. + + \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 + 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; + int ret; + unsigned char buf[MAX]; + bufSz = MAX; + ... + //get information sent from wc_dtls_export function and place it in buf + fread(buf, 1, bufSz, input); + ret = wolfSSL_dtls_import(ssl, buf, bufSz); + if (ret < 0) { + // handle error case + } + // no wolfSSL_accept needed since handshake was already done + ... + ret = wolfSSL_write(ssl) and wolfSSL_read(ssl); + ... + \endcode + + \sa wolfSSL_new + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_dtls_set_export +*/ +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 + 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 + 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 + // buf (serialized session) to destination + WOLFSSL_CTX* ctx; + int ret; + ... + ret = wolfSSL_CTX_dtls_set_export(ctx, send_session); + if (ret != SSL_SUCCESS) { + // handle error case + } + ... + ret = wolfSSL_accept(ssl); + ... + \endcode + + \sa wolfSSL_new + \sa wolfSSL_CTX_new + \sa wolfSSL_dtls_set_export + \sa Static buffer use +*/ +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 + 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 + // buf (serialized session) to destination + WOLFSSL* ssl; + int ret; + ... + ret = wolfSSL_dtls_set_export(ssl, send_session); + if (ret != SSL_SUCCESS) { + // handle error case + } + ... + ret = wolfSSL_accept(ssl); + ... + \endcode + + \sa wolfSSL_new + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_dtls_set_export +*/ +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 + for serializing the WOLFSSL session. + + \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; + int ret; + unsigned char buf[MAX]; + bufSz = MAX; + ... + ret = wolfSSL_dtls_export(ssl, buf, bufSz); + if (ret < 0) { + // handle error case + } + ... + \endcode + + \sa wolfSSL_new + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_dtls_set_export + \sa wolfSSL_dtls_import +*/ +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 + 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 + 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; + WOLFSSL* ssl; + int ret; + unsigned char memory[MAX]; + int memorySz = MAX; + unsigned char IO[MAX]; + int IOSz = MAX; + int flag = WOLFMEM_IO_FIXED | WOLFMEM_TRACK_STATS; + ... + // 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, + 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, + 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 +*/ +WOLFSSL_API int wolfSSL_CTX_load_static_memory(WOLFSSL_CTX** ctx, + wolfSSL_method_func method, + unsigned char* buf, unsigned int sz, + int flag, int max); +/*! + \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 + wolfSSL_CTX_new(). + \param mem_stats structure to hold information about static memory usage. + + _Example_ + \code + WOLFSSL_CTX* ctx; + int ret; + WOLFSSL_MEM_STATS mem_stats; + ... + //get information about static memory with CTX + ret = wolfSSL_CTX_is_static_memory(ctx, &mem_stats); + if (ret == 1) { + // handle case of is using static memory + // print out or inspect elements of mem_stats + } + if (ret == 0) { + //handle case of ctx not using static memory + } + … + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_load_static_memory + \sa wolfSSL_is_static_memory +*/ +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 + 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. + + _Example_ + \code + WOLFSSL* ssl; + int ret; + WOLFSSL_MEM_CONN_STATS mem_stats; + ... + ret = wolfSSL_is_static_memory(ssl, mem_stats); + if (ret == 1) { + // handle case when is static memory + // investigate elements in mem_stats if WOLFMEM_TRACK_STATS flag + } + ... + \endcode + + \sa wolfSSL_new + \sa wolfSSL_CTX_is_static_memory +*/ +WOLFSSL_API int wolfSSL_is_static_memory(WOLFSSL* ssl, + WOLFSSL_MEM_CONN_STATS* mem_stats); +/*! + \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 + 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 + fails on the file. + + \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 + to be loaded into the wolfSSL SSL context. + \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; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_use_certificate_file(ctx, “./client-cert.pem”, + SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + // error loading cert file + } + ... + \endcode + + \sa wolfSSL_CTX_use_certificate_buffer + \sa wolfSSL_use_certificate_file + \sa wolfSSL_use_certificate_buffer +*/ +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 + 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 + is provided. + + \param none No parameters. + + _Example_ + \code + int ret = 0; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_use_PrivateKey_file(ctx, “./server-key.pem”, + SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + // error loading key file + } + ... + \endcode + + \sa wolfSSL_CTX_use_PrivateKey_buffer + \sa wolfSSL_use_PrivateKey_file + \sa wolfSSL_use_PrivateKey_buffer +*/ +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 + “-----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 + 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 + 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 + receiving buffer. + \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 + certificates. + \param path pointer to the name of a directory to load PEM-formatted + certificates from. + + _Example_ + \code + int ret = 0; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_load_verify_locations(ctx, “./ca-cert.pem”, 0); + if (ret != SSL_SUCCESS) { + // error loading CA certs + } + ... + \endcode + + \sa wolfSSL_CTX_load_verify_buffer + \sa wolfSSL_CTX_use_certificate_file + \sa wolfSSL_CTX_use_PrivateKey_file + \sa wolfSSL_CTX_use_NTRUPrivateKey_file + \sa wolfSSL_CTX_use_certificate_chain_file + \sa wolfSSL_use_certificate_file + \sa wolfSSL_use_PrivateKey_file + \sa wolfSSL_use_certificate_chain_file +*/ +WOLFSSL_API int wolfSSL_CTX_load_verify_locations(WOLFSSL_CTX*, const char*, + 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 + examples for proper usage. + + \return SSL_SUCCES upon success. + \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 + 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 + 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”, + 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 + \sa wolfSSL_CTX_use_NTRUPrivateKey_file + \sa wolfSSL_CTX_use_certificate_chain_file + \sa wolfSSL_CTX_trust_peer_buffer + \sa wolfSSL_CTX_Unload_trust_peers + \sa wolfSSL_use_certificate_file + \sa wolfSSL_use_PrivateKey_file + \sa wolfSSL_use_certificate_chain_file +*/ +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 + (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, + or is corrupted, an out of memory condition occurs. + + \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 + must be in PEM format. + + _Example_ + \code + int ret = 0; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_use_certificate_chain_file(ctx, “./cert-chain.pem”); + if (ret != SSL_SUCCESS) { + // error loading cert file + } + ... + \endcode + + \sa wolfSSL_CTX_use_certificate_file + \sa wolfSSL_CTX_use_certificate_buffer + \sa wolfSSL_use_certificate_file + \sa wolfSSL_use_certificate_buffer +*/ +WOLFSSL_API int wolfSSL_CTX_use_certificate_chain_file(WOLFSSL_CTX *, + const char *file); +/*! + \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 + 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 + be read, or is corrupted, an out of memory condition occurs. + + \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 + by format. + \param 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; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_use_RSAPrivateKey_file(ctx, “./server-key.pem”, + SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + // error loading private key file + } + ... + \endcode + + \sa wolfSSL_CTX_use_PrivateKey_buffer + \sa wolfSSL_CTX_use_PrivateKey_file + \sa wolfSSL_use_RSAPrivateKey_file + \sa wolfSSL_use_PrivateKey_buffer + \sa wolfSSL_use_PrivateKey_file +*/ +WOLFSSL_API int wolfSSL_CTX_use_RSAPrivateKey_file(WOLFSSL_CTX*, const char*, int); +/*! + \ingroup IO + + \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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + ... + long sslDep = wolfSSL_get_verify_depth(ssl); + + if(sslDep > EXPECTED){ + // The verified depth is greater than what was expected + } else { + // 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); +/*! + \ingroup Setup + + \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 + 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 + wolfSSL_CTX_new(). + + _Example_ + \code + WOLFSSL_METHOD method; // protocol method + WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(method); + … + long ret = wolfSSL_CTX_get_verify_depth(ctx); + + if(ret == EXPECTED){ + // You have the expected value + } else { + // Handle an unexpected depth + } + \endcode + + \sa wolfSSL_CTX_use_certificate_chain_file + \sa wolfSSL_get_verify_depth +*/ +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 - + 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 + 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. + Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1. + + _Example_ + \code + int ret = 0; + WOLFSSL* ssl; + ... + ret = wolfSSL_use_certificate_file(ssl, “./client-cert.pem”, + SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + // error loading cert file + } + ... + \endcode + + \sa wolfSSL_CTX_use_certificate_buffer + \sa wolfSSL_CTX_use_certificate_file + \sa wolfSSL_use_certificate_buffer +*/ +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 - + 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 + 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 + 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 + values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1. + + _Example_ + \code + int ret = 0; + WOLFSSL* ssl; + ... + ret = wolfSSL_use_PrivateKey_file(ssl, “./server-key.pem”, + SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + // error loading key file + } + ... + \endcode + + \sa wolfSSL_CTX_use_PrivateKey_buffer + \sa wolfSSL_CTX_use_PrivateKey_file + \sa wolfSSL_use_PrivateKey_buffer +*/ +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 + 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, + 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. + Certificates must be in PEM format. + + _Example_ + \code + int ret = 0; + WOLFSSL* ctx; + ... + ret = wolfSSL_use_certificate_chain_file(ssl, “./cert-chain.pem”); + if (ret != SSL_SUCCESS) { + // error loading cert file + } + ... + \endcode + + \sa wolfSSL_CTX_use_certificate_chain_file + \sa wolfSSL_CTX_use_certificate_chain_buffer + \sa wolfSSL_use_certificate_chain_buffer +*/ +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 + 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 + 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 + by format. + \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; + WOLFSSL* ssl; + ... + ret = wolfSSL_use_RSAPrivateKey_file(ssl, “./server-key.pem”, + SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + // error loading private key file + } + ... + \endcode + + \sa wolfSSL_CTX_use_RSAPrivateKey_file + \sa wolfSSL_CTX_use_PrivateKey_buffer + \sa wolfSSL_CTX_use_PrivateKey_file + \sa wolfSSL_use_PrivateKey_buffer + \sa wolfSSL_use_PrivateKey_file +*/ +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 + 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 + 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 + as specified by format. + \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; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_der_load_verify_locations(ctx, “./ca-cert.der”, + SSL_FILETYPE_ASN1); + if (ret != SSL_SUCCESS) { + // error loading CA certs + } + ... + \endcode + + \sa wolfSSL_CTX_load_verify_locations + \sa wolfSSL_CTX_load_verify_buffer +*/ + WOLFSSL_API int wolfSSL_CTX_der_load_verify_locations(WOLFSSL_CTX*, + const char*, int); +/*! + \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) + 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 + 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 + receiving buffer. + \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 + wolfSSL_CTX_new() + \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; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_use_NTRUPrivateKey_file(ctx, “./ntru-key.raw”); + if (ret != SSL_SUCCESS) { + // error loading NTRU private key + } + ... + \endcode + + \sa wolfSSL_CTX_load_verify_buffer + \sa wolfSSL_CTX_use_certificate_buffer + \sa wolfSSL_CTX_use_PrivateKey_buffer + \sa wolfSSL_CTX_use_certificate_chain_buffer + \sa wolfSSL_use_certificate_buffer + \sa wolfSSL_use_PrivateKey_buffer + \sa wolfSSL_use_certificate_chain_buffer +*/ + WOLFSSL_API int wolfSSL_CTX_use_NTRUPrivateKey_file(WOLFSSL_CTX*, const char*); +/*! + \ingroup openSSL + + \brief Loads the PEM certificate from fileName and converts it into DER + format, placing the result into derBuffer which is of size derSz. + + \return Success If successful the call will return the number of bytes + written to derBuffer. + \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 SSL_NO_PEM_HEADER will be returned if the PEM certificate header + can’t be found. + \return BUFFER_E will be returned if a chain buffer is bigger than the + receiving buffer. + + \param filename pointer to the name of the PEM-formatted certificate for + conversion. + \param derBuffer the buffer for which the converted PEM certificate will + be placed in DER format. + \param derSz size of derBuffer. + + _Example_ + \code + int derSz; + byte derBuf[...]; + derSz = wolfSSL_PemCertToDer(“./cert.pem”, derBuf, sizeof(derBuf)); + \endcode + + \sa SSL_get_peer_certificate +*/ + WOLFSSL_API int wolfSSL_PemCertToDer(const char*, unsigned char*, int); +/*! + \ingroup Setup + + \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 + 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() + functions to specify SSL/TLS/DTLS protocol level. + + _Example_ + \code + WOLFSSL_CTX* ctx = 0; + WOLFSSL_METHOD* method = 0; + + method = wolfSSLv3_client_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + \endcode + + \sa wolfSSL_new +*/ +WOLFSSL_API WOLFSSL_CTX* wolfSSL_CTX_new(WOLFSSL_METHOD*); +/*! + \ingroup Setup + + \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 + 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; + + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + + ssl = wolfSSL_new(ctx); + if (ssl == NULL) { + // SSL object creation failed + } + \endcode + + \sa wolfSSL_CTX_new +*/ +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 + 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; + WOLFSSL* ssl = 0; + ... + + ret = wolfSSL_set_fd(ssl, sockfd); + if (ret != SSL_SUCCESS) { + // failed to set SSL file descriptor + } + \endcode + + \sa wolfSSL_SetIOSend + \sa wolfSSL_SetIORecv + \sa wolfSSL_SetIOReadCtx + \sa wolfSSL_SetIOWriteCtx +*/ +WOLFSSL_API int wolfSSL_set_fd (WOLFSSL*, int); +/*! + \ingroup IO + + \brief Get the name of cipher at priority level passed in. + + \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 +*/ +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 + len argument was less than or equal to zero. + \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){ + char* ciphers; + int ret = wolfSSL_get_ciphers(ciphers, (int)sizeof(ciphers)); + + if(ret == SSL_SUCCES){ + printf(“%s\n”, ciphers); + } + } + \endcode + + \sa GetCipherNames + \sa wolfSSL_get_cipher_list + \sa ShowCiphers +*/ +WOLFSSL_API int wolfSSL_get_ciphers(char*, int); +/*! + \ingroup IO + + \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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + … + char* cipherS = wolfSSL_get_cipher_name(ssl); + + if(cipher == NULL){ + // There was not a cipher suite matched + } else { + // There was a cipher suite matched + printf(“%s\n”, cipherS); + } + \endcode + + \sa wolfSSL_CIPHER_get_name + \sa wolfSSL_get_current_cipher + \sa wolfSSL_get_cipher_name_internal +*/ +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 + will be a socket file descriptor. + + \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; + WOLFSSL* ssl = 0; + ... + sockfd = wolfSSL_get_fd(ssl); + ... + \endcode + + \sa wolfSSL_set_fd +*/ +WOLFSSL_API int wolfSSL_get_fd(const WOLFSSL*); +/*! + \ingroup Setup + + \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 + 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 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. + 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 +*/ +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 + 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; + WOLFSSL* ssl = 0; + ... + ret = wolfSSL_get_using_nonblock(ssl); + if (ret == 1) { + // underlying I/O is non-blocking + } + ... + \endcode + + \sa wolfSSL_set_session +*/ +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 + 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 + 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 + 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; + char msg[64] = “hello wolfssl!”; + int msgSz = (int)strlen(msg); + int flags; + int ret; + ... + + ret = wolfSSL_write(ssl, msg, msgSz); + if (ret <= 0) { + // wolfSSL_write() failed, call wolfSSL_get_error() + } + \endcode + + \sa wolfSSL_send + \sa wolfSSL_read + \sa wolfSSL_recv +*/ +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 + 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 + 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 + 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; + char reply[1024]; + ... + + input = wolfSSL_read(ssl, reply, sizeof(reply)); + if (input > 0) { + // “input” number of bytes returned into buffer “reply” + } + + See wolfSSL examples (client, server, echoclient, echoserver) for more + complete examples of wolfSSL_read(). + \endcode + + \sa wolfSSL_recv + \sa wolfSSL_write + \sa wolfSSL_peek + \sa wolfSSL_pending +*/ +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 + 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 + 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 + 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); +/*! + \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 + 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 + 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; + int err = 0; + WOLFSSL* ssl; + char buffer[80]; + ... + + ret = wolfSSL_accept(ssl); + if (ret != SSL_SUCCESS) { + err = wolfSSL_get_error(ssl, ret); + 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 + 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 + 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; + int err = 0; + WOLFSSL* ssl; + char buffer[80]; + ... + + ret = wolfSSL_connect(ssl); + if (ret != SSL_SUCCESS) { + err = wolfSSL_get_error(ssl, ret); + printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); + } + \endcode + + \sa wolfSSL_get_error + \sa wolfSSL_accept +*/ +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 + 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 +*/ +WOLFSSL_API void wolfSSL_CTX_free(WOLFSSL_CTX*); +/*! + \ingroup Setup + + \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 + + WOLFSSL* ssl = 0; + ... + wolfSSL_free(ssl); + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_new + \sa wolfSSL_CTX_free +*/ +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 + 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 + finished, and the function should be called again. + \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; + ... + ret = wolfSSL_shutdown(ssl); + if (ret != 0) { + // failed to shut down SSL connection + } + \endcode + + \sa wolfSSL_free + \sa wolfSSL_CTX_free +*/ +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 + 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 + 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 + 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; + char msg[64] = “hello wolfssl!”; + int msgSz = (int)strlen(msg); + int flags = ... ; + ... + + input = wolfSSL_send(ssl, msg, msgSz, flags); + if (input != msgSz) { + // wolfSSL_send() failed + } + \endcode + + \sa wolfSSL_write + \sa wolfSSL_read + \sa wolfSSL_recv +*/ +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 + 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 + 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 + 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; + char reply[1024]; + int flags = ... ; + ... + + input = wolfSSL_recv(ssl, reply, sizeof(reply), flags); + if (input > 0) { + // “input” number of bytes returned into buffer “reply” + } + \endcode + + \sa wolfSSL_read + \sa wolfSSL_write + \sa wolfSSL_peek + \sa wolfSSL_pending +*/ +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 + information. + + \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 + return code. + + _Example_ + \code + int err = 0; + WOLFSSL* ssl; + char buffer[80]; + ... + err = wolfSSL_get_error(ssl, 0); + 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 + \sa wolfSSL_load_error_strings +*/ +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 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 + WOLFSSL struct’s alert_history member’s value. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method); + WOLFSSL* ssl = wolfSSL_new(ctx); + WOLFSSL_ALERT_HISTORY* h; + ... + 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 *); +/*! + \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 + 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 + 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 + for ssl. + + _Example_ + \code + int ret = 0; + WOLFSSL* ssl = 0; + WOLFSSL_SESSION* session; + ... + + ret = wolfSSL_get_session(ssl, session); + if (ret != SSL_SUCCESS) { + // failed to set the SSL session + } + ... + \endcode + + \sa wolfSSL_get_session +*/ +WOLFSSL_API int wolfSSL_set_session(WOLFSSL* ssl,WOLFSSL_SESSION* 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. + The wolfSSL server code allows session resumption by default. + + \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 + functions fail. + + \param ssl pointer to the SSL session, created with wolfSSL_new(). + + _Example_ + \code + WOLFSSL* ssl = 0; + WOLFSSL_SESSION* session = 0; + ... + session = wolfSSL_get_session(ssl); + if (session == NULL) { + // failed to get session pointer + } + ... + \endcode + + \sa wolfSSL_set_session +*/ +WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL* ssl); +/*! + \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 + wolfSSL is compiled with the OpenSSL compatibility layer. + + \return none No returns. + + \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 +*/ +WOLFSSL_API void wolfSSL_flush_sessions(WOLFSSL_CTX *ctx, long tm); +/*! + \ingroup TLS + + \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 + 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 + 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 + to reuse a session or not. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol ); + WOLFSSL* ssl = WOLFSSL_new(ctx); + const byte id[MAX_SIZE]; // or dynamically create space + int len = 0; // initialize length + int newSession = 0; // flag to allow + … + int ret = wolfSSL_SetServerID(ssl, id, len, newSession); + + if(ret){ + // The Id was successfully set + } + \endcode + + \sa GetSessionClient +*/ +WOLFSSL_API int wolfSSL_SetServerID(WOLFSSL* ssl, const unsigned char*, + int, int); +/*! + \ingroup IO + + \brief This function gets the session index of the WOLFSSL structure. + + \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 ); + WOLFSSL* ssl = WOLFSSL_new(ctx); + ... + int sesIdx = wolfSSL_GetSessionIndex(ssl); + + if(sesIdx < 0 || sesIdx > sizeof(ssl->sessionIndex)/sizeof(int)){ + // You have an out of bounds index number and something is not right. + } + \endcode + + \sa wolfSSL_GetSessionAtIndex +*/ +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 + the session information. + + \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. + WOLFSSL_SESSION* session; // Buffer to copy to. + ... + if(wolfSSL_GetSessionAtIndex(idx, session) != SSL_SUCCESS){ + // Failure case. + } + \endcode + + \sa UnLockMutex + \sa LockMutex + \sa wolfSSL_GetSessionIndex +*/ +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 + contains the peer certification chain. + + \param session a pointer to a WOLFSSL_SESSION structure. + + _Example_ + \code + WOLFSSL_SESSION* session; + WOLFSSL_X509_CHAIN* chain; + ... + chain = wolfSSL_SESSION_get_peer_chain(session); + if(!chain){ + // There was no chain. Failure case. + } + \endcode + + \sa get_locked_session_stats + \sa wolfSSL_GetSessionAtIndex + \sa wolfSSL_GetSessionIndex + \sa AddSession +*/ +WOLFSSL_API + WOLFSSL_X509_CHAIN* wolfSSL_SESSION_get_peer_chain(WOLFSSL_SESSION* session); +/*! + \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 + 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 + verify_callback. + + _Example_ + \code + WOLFSSL_CTX* ctx = 0; + ... + 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, + VerifyCallback verify_callback); +/*! + \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 + 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 + 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); +/*! + \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 + member’s value. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + (void*)ctx; + ... + if(ssl != NULL){ + wolfSSL_SetCertCbCtx(ssl, ctx); + } else { + // 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 +*/ +WOLFSSL_API void wolfSSL_SetCertCbCtx(WOLFSSL*, void*); +/*! + \ingroup IO + + \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; + WOLFSSL* ssl = 0; + ... + + 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 +*/ +WOLFSSL_API int wolfSSL_pending(WOLFSSL*); +/*! + \ingroup Debug + + \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 + \sa wolfSSL_ERR_print_errors_fp + \sa wolfSSL_load_error_strings +*/ +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 + 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; + ret = wolfSSL_library_init(); + if (ret != SSL_SUCCESS) { + failed to initialize wolfSSL + } + ... + \endcode + + \sa wolfSSL_Init + \sa wolfSSL_Cleanup +*/ +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 + 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. + + _Example_ + \code + WOLFSSL_CTX* ctx = 0; + ... + ret = wolfSSL_CTX_set_session_cache_mode(ctx, SSL_SESS_CACHE_OFF); + if (ret != SSL_SUCCESS) { + // failed to turn SSL session caching off + } + \endcode + + \sa wolfSSL_flush_sessions + \sa wolfSSL_get_session + \sa wolfSSL_set_session + \sa wolfSSL_get_sessionID + \sa wolfSSL_CTX_set_timeout +*/ +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 + the WOLFSSL struct is set to the parameter cb. + + \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 + 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, + 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*); +/*! + \ingroup IO + + \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. + The session cache has been written to a file. + \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; + ... + if(wolfSSL_save_session_cache(fname) != SSL_SUCCESS){ + // Fail to write to file. + } + \endcode + + \sa XFWRITE + \sa wolfSSL_restore_session_cache + \sa wolfSSL_memrestore_session_cache +*/ +WOLFSSL_API int wolfSSL_save_session_cache(const char*); +/*! + \ingroup IO + + \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 + 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 + 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; + ... + if(wolfSSL_restore_session_cache(fname) != SSL_SUCCESS){ + // Failure case. The function did not return SSL_SUCCESS. + } + \endcode + + \sa XFREAD + \sa XFOPEN +*/ +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. + 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 + copy, XMEMCPY(). + \param sz an int type representing the size of mem. + + _Example_ + \code + void* mem; + int sz; // Max size of the memory buffer. + … + if(wolfSSL_memsave_session_cache(mem, sz) != SSL_SUCCESS){ + // Failure case, you did not persist the session cache to memory + } + \endcode + + \sa XMEMCPY + \sa wolfSSL_get_session_cache_memsize +*/ +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 + failed. + + \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; + 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); +/*! + \ingroup IO + + \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 + the session cache save buffer. + + \param none No parameters. + + _Example_ + \code + int sz = // Minimum size for error checking; + ... + if(sz < wolfSSL_get_session_cache_memsize()){ + // Memory buffer is too small + } + \endcode + + \sa wolfSSL_memrestore_session_cache +*/ +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 + certificate information. + \param fname the cert cache buffer. + + _Example_ + \code + WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol def ); + const char* fname; + ... + if(wolfSSL_CTX_save_cert_cache(ctx, fname)){ + // file was written. + } + \endcode + + \sa CM_SaveCertCache + \sa DoMemSaveCertCache +*/ +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, + executes normally. + \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 + 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 + information. + \param fname the cert cache buffer. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + const char* fname = "path to file"; + ... + if(wolfSSL_CTX_restore_cert_cache(ctx, fname)){ + // check to see if the execution was successful + } + \endcode + + \sa CM_RestoreCertCache + \sa XFOPEN +*/ +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. + No errors were thrown. + \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 + 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 + 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 ); + void* mem; + int sz; + int* used; + ... + if(wolfSSL_CTX_memsave_cert_cache(ctx, mem, sz, used) != SSL_SUCCESS){ + // The function returned with an error + } + \endcode + + \sa DoMemSaveCertCache + \sa GetCertCacheMemSize + \sa CM_MemRestoreCertCache + \sa CM_GetCertCacheMemSize +*/ +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 + executed without an error. + \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 + header mismatch. + \return BAD_MUTEX_E returned if the lock mutex on failed. + + \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 + 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 ); + WOLFSSL* ssl = WOLFSSL_new(ctx); + void* mem; + int sz = (*int) sizeof(mem); + … + 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); +/*! + \ingroup CertsKeys + + \brief Returns the size the certificate cache save buffer needs to be. + + \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 + wolfSSL_CTX_new(). + + _Example_ + \code + WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(protocol); + ... + int certCacheSize = wolfSSL_CTX_get_cert_cache_memsize(ctx); + + if(certCacheSize != BAD_FUNC_ARG || certCacheSize != BAD_MUTEX_E){ + // Successfully retrieved the memory size. + } + \endcode + + \sa CM_GetCertCacheMemSize +*/ +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 + 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 + cipher suites to use with the specified SSL context. + + _Example_ + \code + WOLFSSL_CTX* ctx = 0; + ... + ret = wolfSSL_CTX_set_cipher_list(ctx, + “DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256”); + if (ret != SSL_SUCCESS) { + // failed to set cipher suite list + } + \endcode + + \sa wolfSSL_set_cipher_list + \sa wolfSSL_CTX_new +*/ +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 + 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 + cipher suites to use with the specified SSL session. + + _Example_ + \code + int ret = 0; + WOLFSSL* ssl = 0; + ... + ret = wolfSSL_set_cipher_list(ssl, + “DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256”); + if (ret != SSL_SUCCESS) { + // failed to set cipher suite list + } + \endcode + + \sa wolfSSL_CTX_set_cipher_list + \sa wolfSSL_new +*/ +WOLFSSL_API int wolfSSL_set_cipher_list(WOLFSSL*, const char*); +/*! + \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; + WOLFSSL* ssl; + ... + 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 + \sa wolfSSL_dtls_set_peer +*/ +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. + 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 + 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 + member of the WOLFSSL structure. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + int timeout = TIMEOUT; + ... + if(wolfSSL_dtls_set_timeout_init(ssl, timeout)){ + // the dtls timeout was set + } else { + // Failed to set DTLS timeout. + } + \endcode + + \sa wolfSSL_dtls_set_timeout_max + \sa wolfSSL_dtls_got_timeout +*/ +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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + int timeout = TIMEOUTVAL; + ... + int ret = wolfSSL_dtls_set_timeout_max(ssl); + if(!ret){ + // 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 + 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 + retransmissions/timeouts without getting a response from the peer. + \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 + \sa wolfSSL_dtls +*/ +WOLFSSL_API int wolfSSL_dtls_got_timeout(WOLFSSL* ssl); +/*! + \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 0 otherwise. + + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + _Example_ + \code + int ret = 0; + WOLFSSL* ssl; + ... + ret = wolfSSL_dtls(ssl); + if (ret) { + // SSL session has been configured to use DTLS + } + \endcode + + \sa wolfSSL_dtls_get_current_timeout + \sa wolfSSL_dtls_get_peer + \sa wolfSSL_dtls_got_timeout + \sa wolfSSL_dtls_set_peer +*/ +WOLFSSL_API int wolfSSL_dtls(WOLFSSL* ssl); +/*! + \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 + 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; + WOLFSSL* ssl; + sockaddr_in addr; + ... + ret = wolfSSL_dtls_set_peer(ssl, &addr, sizeof(addr)); + if (ret != SSL_SUCCESS) { + // failed to set DTLS peer + } + \endcode + + \sa wolfSSL_dtls_get_current_timeout + \sa wolfSSL_dtls_get_peer + \sa wolfSSL_dtls_got_timeout + \sa wolfSSL_dtls +*/ +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 + 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 + 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 + 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; + WOLFSSL* ssl; + sockaddr_in addr; + ... + ret = wolfSSL_dtls_get_peer(ssl, &addr, sizeof(addr)); + if (ret != SSL_SUCCESS) { + // failed to get DTLS peer + } + \endcode + + \sa wolfSSL_dtls_get_current_timeout + \sa wolfSSL_dtls_got_timeout + \sa wolfSSL_dtls_set_peer + \sa wolfSSL_dtls +*/ +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 + MAX_ERROR_SZ is wolfssl/wolfcrypt/error.h. + + \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 + appropriate failure reason, msg. + + \param errNumber error code returned by wolfSSL_get_error(). + \param data output buffer containing human-readable error string matching + errNumber. + + _Example_ + \code + int err = 0; + WOLFSSL* ssl; + char buffer[80]; + ... + err = wolfSSL_get_error(ssl, 0); + 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 + \sa wolfSSL_load_error_strings +*/ +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. + 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; + WOLFSSL* ssl; + char buffer[80]; + ... + err = wolfSSL_get_error(ssl, 0); + 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 + \sa wolfSSL_load_error_strings +*/ +WOLFSSL_API void wolfSSL_ERR_error_string_n(unsigned long e, char* buf, + unsigned long sz); +/*! + \ingroup TLS + + \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 + wolfSSL_new(). + + _Example_ + \code + #include + + WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method ); + WOLFSSL* ssl = WOLFSSL_new(ctx); + … + int ret; + ret = wolfSSL_get_shutdown(ssl); + + if(ret == 1){ + SSL_SENT_SHUTDOWN + } else if(ret == 2){ + SSL_RECEIVED_SHUTDOWN + } else { + Fatal error. + } + \endcode + + \sa wolfSSL_SESSION_free +*/ +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 + be established. + + \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); + … + if(!wolfSSL_session_reused(sslResume)){ + // No session reuse allowed. + } + \endcode + + \sa wolfSSL_SESSION_free + \sa wolfSSL_GetSessionIndex + \sa wolfSSL_memsave_session_cache +*/ +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 + struct is NULL or the handshake is not done. + \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); + ... + if(wolfSSL_is_init_finished(ssl)){ + Handshake is done and connection is established + } + \endcode + + \sa wolfSSL_set_accept_state + \sa wolfSSL_get_keys + \sa wolfSSL_set_shutdown +*/ +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 + \return "TLSv1.2" Using TLSv1.2 + \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 + being used. + + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + _Example_ + \code + wolfSSL_Init(); + WOLFSSL_CTX* ctx; + WOLFSSL* ssl; + WOLFSSL_METHOD method = // Some wolfSSL method + ctx = wolfSSL_CTX_new(method); + 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*); +/*! + \ingroup IO + + \brief Returns the current cipher suit an ssl session is using. + + \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(); + WOLFSSL_CTX* ctx; + WOLFSSL* ssl; + 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 +*/ +WOLFSSL_API int wolfSSL_get_current_cipher_suite(WOLFSSL* ssl); +/*! + \ingroup IO + + \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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + … + WOLFSSL_CIPHER* cipherCurr = wolfSSL_get_current_cipher; + + if(!cipherCurr){ + // Failure case. + } else { + // The cipher was returned to cipherCurr + } + \endcode + + \sa wolfSSL_get_cipher + \sa wolfSSL_get_cipher_name_internal + \sa wolfSSL_get_cipher_name +*/ +WOLFSSL_API WOLFSSL_CIPHER* wolfSSL_get_current_cipher(WOLFSSL*); +/*! + \ingroup IO + + \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 + 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 ... + const char* wolfSSL_get_cipher_name_internal(WOLFSSL* ssl){ + WOLFSSL_CIPHER* cipher; + const char* fullName; + … + cipher = wolfSSL_get_curent_cipher(ssl); + fullName = wolfSSL_CIPHER_get_name(cipher); + + if(fullName){ + // sanity check on returned cipher + } + \endcode + + \sa wolfSSL_get_cipher + \sa wolfSSL_get_current_cipher + \sa wolfSSL_get_cipher_name_internal + \sa wolfSSL_get_cipher_name +*/ +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 + the available suites. + + \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 + … + // make sure a valid suite is used + if(wolfSSL_get_cipher(ssl) == NULL){ + WOLFSSL_MSG(“Can not match cipher suite imported”); + return MATCH_SUITE_ERROR; + } + … + #endif // WOLFSSL_DTLS + \endcode + + \sa wolfSSL_CIPHER_get_name + \sa wolfSSL_get_current_cipher +*/ +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; + WOLFSSL_SESSION* ses; + // attempt/complete handshake + ses = wolfSSL_get1_session(ssl); + // check ses information + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +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 + connect to a server running SSLv3 - TLSv1.2. + + \return pointer upon succes 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 + returned (typically NULL with errno will be set to ENOMEM). + + \param none No parameters + + _Example_ + \code + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + method = wolfSSLv23_client_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_client_method + \sa wolfTLSv1_client_method + \sa wolfTLSv1_1_client_method + \sa wolfTLSv1_2_client_method + \sa wolfDTLSv1_client_method + \sa wolfSSL_CTX_new +*/ +WOLFSSL_API WOLFSSL_METHOD* wolfSSLv23_client_method(void); +/*! + \ingroup IO + + \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; + const byte* p; + int ret; + bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem()); + 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 + \sa wolfSSL_BIO_free +*/ +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; + int fd; + // setup bio + wolfSSL_BIO_set_fd(bio, fd, BIO_NOCLOSE); + \endcode + + \sa wolfSSL_BIO_new + \sa wolfSSL_BIO_free +*/ +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 + 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 +*/ +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 + 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; + int ret; + bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem()); + 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 +*/ +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 + (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; + WOLFSSL_BIO* bio2; + int ret; + bio = wolfSSL_BIO_new(wolfSSL_BIO_s_bio()); + bio2 = wolfSSL_BIO_new(wolfSSL_BIO_s_bio()); + 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 +*/ +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; + int ret; + ... + 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 +*/ +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 + 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; + char* bufPt; + int ret; + // set up bio + ret = wolfSSL_BIO_nread0(bio, &bufPt); // read as many bytes as possible + // handle negative ret check + // read ret bytes from bufPt + \endcode + + \sa wolfSSL_BIO_new + \sa wolfSSL_BIO_nwrite0 +*/ +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 + 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; + char* bufPt; + int ret; + + // set up bio + ret = wolfSSL_BIO_nread(bio, &bufPt, 10); // try to read 10 bytes + // handle negative ret check + // read ret bytes from bufPt + \endcode + + \sa wolfSSL_BIO_new + \sa wolfSSL_BIO_nwrite +*/ +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 + returned can result in writing out of bounds. + + \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 + 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. + + _Example_ + \code + WOLFSSL_BIO* bio; + char* bufPt; + int ret; + // set up bio + ret = wolfSSL_BIO_nwrite(bio, &bufPt, 10); // try to write 10 bytes + // handle negative ret check + // write ret bytes to bufPt + \endcode + + \sa wolfSSL_BIO_new + \sa wolfSSL_BIO_free + \sa wolfSSL_BIO_nread +*/ +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 + 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; + // setup bio + wolfSSL_BIO_reset(bio); + //use pt + \endcode + + \sa wolfSSL_BIO_new + \sa wolfSSL_BIO_free +*/ +WOLFSSL_API int wolfSSL_BIO_reset(WOLFSSL_BIO *bio); +/*! + \ingroup IO + + \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; + XFILE fp; + int ret; + bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file()); + ret = wolfSSL_BIO_set_fp(bio, &fp); + // check ret value + ret = wolfSSL_BIO_seek(bio, 3); + // check ret value + \endcode + + \sa wolfSSL_BIO_new + \sa wolfSSL_BIO_s_mem + \sa wolfSSL_BIO_set_fp + \sa wolfSSL_BIO_free +*/ +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 + 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; + int ret; + bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file()); + 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 + \sa wolfSSL_BIO_free +*/ +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 + 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; + int ret; + bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem()); + 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_set_fp + \sa wolfSSL_BIO_free +*/ +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 + returned (currently value of 1). + \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 + bio’s memory. + + _Example_ + \code + WOLFSSL_BIO* bio; + WOLFSSL_BUF_MEM* pt; + // setup bio + wolfSSL_BIO_get_mem_ptr(bio, &pt); + //use pt + \endcode + + \sa wolfSSL_BIO_new + \sa wolfSSL_BIO_s_mem +*/ +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 + 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 + WOLFSSL_X509_NAME structure. + \param sz the maximum size of the buffer. + + _Example_ + \code + WOLFSSL_X509 x509; + char* name; + ... + name = wolfSSL_X509_NAME_oneline(wolfSSL_X509_get_issuer_name(x509), 0, 0); + + if(name <= 0){ + // There’s nothing in the buffer. + } + \endcode + + \sa wolfSSL_X509_get_subject_name + \sa wolfSSL_X509_get_issuer_name + \sa wolfSSL_X509_get_isCA + \sa wolfSSL_get_peer_certificate + \sa wolfSSL_X509_version +*/ +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 + returned. + \return NULL if the cert passed in is NULL. + + \param cert a pointer to a WOLFSSL_X509 structure. + + _Example_ + \code + WOLFSSL_X509* x509; + WOLFSSL_X509_NAME issuer; + ... + issuer = wolfSSL_X509_NAME_oneline(wolfSSL_X509_get_issuer_name(x509), 0, 0); + + if(!issuer){ + // NULL was returned + } else { + // 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 + \sa wolfSSL_X509_NAME_oneline +*/ +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 + 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 + the structure is NULL. + + \param cert a pointer to a WOLFSSL_X509 structure. + + _Example_ + \code + WOLFSSL_X509* cert; + WOLFSSL_X509_NAME name; + … + name = wolfSSL_X509_get_subject_name(cert); + if(name == NULL){ + // Deal with the NULL cacse + } + \endcode + + \sa wolfSSL_X509_get_issuer_name + \sa wolfSSL_X509_get_isCA + \sa wolfSSL_get_peer_certificate +*/ +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 + the value. + + \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; + ... + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + ... + if(wolfSSL_X509_get_isCA(ssl)){ + // This is the CA + }else { + // Failure case + } + \endcode + + \sa wolfSSL_X509_get_issuer_name + \sa wolfSSL_X509_get_isCA +*/ +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; + char buffer[100]; + int bufferSz; + int ret; + // get WOLFSSL_X509_NAME + 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( + WOLFSSL_X509_NAME*, int, char*, int); +/*! + \ingroup CertsKeys + + \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 + 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, + DYNAMIC_TYPE_X509); + ... + int x509SigType = wolfSSL_X509_get_signature_type(x509); + + if(x509SigType != EXPECTED){ + // Deal with an unexpected value + } + \endcode + + \sa wolfSSL_X509_get_signature + \sa wolfSSL_X509_version + \sa wolfSSL_X509_get_der + \sa wolfSSL_X509_get_serial_number + \sa wolfSSL_X509_notBefore + \sa wolfSSL_X509_notAfter + \sa wolfSSL_X509_free +*/ +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. + 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 + (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, + DYNAMIC_TYPE_X509); + unsigned char* buf; // Initialize + int* bufSz = sizeof(buf)/sizeof(unsigned char); + ... + if(wolfSSL_X509_get_signature(x509, buf, bufSz) != SSL_SUCCESS){ + // The function did not execute successfully. + } else{ + // 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 +*/ +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; + WOLFSSL_X509* x509; + int ret; + ret = wolfSSL_X509_STORE_add_cert(str, x509); + //check ret value + \endcode + + \sa wolfSSL_X509_free +*/ +WOLFSSL_API int wolfSSL_X509_STORE_add_cert( + WOLFSSL_X509_STORE*, WOLFSSL_X509*); +/*! + \ingroup CertsKeys + + \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 + (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; + WOLFSSL_X509_STORE_CTX* ctx; + 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( + WOLFSSL_X509_STORE_CTX* ctx); +/*! + \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 + 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; + int ret; + // create and set up str + ret = wolfSSL_X509_STORE_set_flags(str, WOLFSSL_CRL_CHECKALL); + If (ret != SSL_SUCCESS) { + //check ret value and handle error case + } + \endcode + + \sa wolfSSL_X509_STORE_new + \sa wolfSSL_X509_STORE_free +*/ +WOLFSSL_API int wolfSSL_X509_STORE_set_flags(WOLFSSL_X509_STORE* store, + unsigned long flag); +/*! + \ingroup Setup + + \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 + 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 + structure will be created. + + _Example_ + \code + WOLFSSL_ASN1_INTEGER* ai; + WOLFSSL_BIGNUM* bn; + // create ai + bn = wolfSSL_ASN1_INTEGER_to_BN(ai, NULL); + + // or if having already created bn and wanting to reuse structure + // 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, + WOLFSSL_BIGNUM *bn); +/*! + \ingroup Setup + + \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; + WOLFSSL_X509* x509; + int ret; + // create ctx + ret = wolfSSL_CTX_add_extra_chain_cert(ctx, x509); + // check ret value + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_free +*/ +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 + 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; + int flag; + // setup ctx + flag = wolfSSL_CTX_get_read_ahead(ctx); + //check flag + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_free + \sa wolfSSL_CTX_set_read_ahead +*/ +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; + int flag; + int ret; + // setup 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 +*/ +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; + void* data; + int ret; + // setup ctx + ret = wolfSSL_CTX_set_tlsext_status_arg(ctx, data); + + //check ret value + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_free +*/ +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 + 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; + void* data; + int ret; + // setup ctx + ret = wolfSSL_CTX_set_tlsext_opaques_prf_input_callback_arg(ctx, data); + //check ret value + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_free +*/ +WOLFSSL_API long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg( + WOLFSSL_CTX*, void* 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, + 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: + 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 + + _Example_ + \code + WOLFSSL* ssl; + unsigned long mask; + mask = SSL_OP_NO_TLSv1 + mask = wolfSSL_set_options(ssl, mask); + // check mask + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free + \sa wolfSSL_get_options +*/ +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; + unsigned long mask; + mask = wolfSSL_get_options(ssl); + // check mask + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free + \sa wolfSSL_set_options +*/ +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; + void* args; + int ret; + // create ssl object + ret = wolfSSL_set_tlsext_debug_arg(ssl, args); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +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 + 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 + only supported. + + _Example_ + \code + WOLFSSL *ssl; + WOLFSSL_CTX *ctx; + int ret; + ctx = wolfSSL_CTX_new(wolfSSLv23_server_method()); + ssl = wolfSSL_new(ctx); + ret = WolfSSL_set_tlsext_status_type(ssl,TLSEXT_STATUSTYPE_ocsp); + wolfSSL_free(ssl); + wolfSSL_CTX_free(ctx); + \endcode + + \sa wolfSSL_new + \sa wolfSSL_CTX_new + \sa wolfSSL_free + \sa wolfSSL_CTX_free +*/ +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 + 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; + long ret; + // attempt/complete handshake + ret = wolfSSL_get_verify_result(ssl); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +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 + 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; + WOLFSSL* ssl; + FILE* fp = ... + ... + 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 + \sa wolfSSL_load_error_strings +*/ +WOLFSSL_API void wolfSSL_ERR_print_errors_fp(FILE*, int err); +/*! + \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 + wolfSSL_CTX_new(). + \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 ); + … + static INLINE unsigned int my_psk_client_cb(WOLFSSL* ssl, const char* hint, + char* identity, unsigned int id_max_len, unsigned char* key, + Unsigned int key_max_len){ + … + 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 + \sa wolfSSL_CTX_set_psk_client_callback +*/ + WOLFSSL_API void wolfSSL_CTX_set_psk_client_callback(WOLFSSL_CTX*, + wc_psk_client_callback); +/*! + \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; + unsigned int cb(WOLFSSL*, const char*, char*) // Header of function* + { + // Funciton body + } + … + cb = wc_psk_client_callback; + if(ssl){ + wolfSSL_set_psk_client_callback(ssl, cb); + } else { + // 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 +*/ + WOLFSSL_API void wolfSSL_set_psk_client_callback(WOLFSSL*, + wc_psk_client_callback); +/*! + \ingroup CertsKeys + + \brief This function returns the psk identity hint. + + \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); + char* idHint; + ... + idHint = wolfSSL_get_psk_identity_hint(ssl); + if(idHint){ + // The hint was retrieved + return idHint; + } else { + // Hint wasn’t successfully retrieved + } + \endcode + + \sa wolfSSL_get_psk_identity +*/ + WOLFSSL_API const char* wolfSSL_get_psk_identity_hint(const WOLFSSL*); +/*! + \ingroup CertsKeys + + \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 + Arrays structure. + \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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + const char* pskID; + ... + pskID = wolfSSL_get_psk_identity(ssl); + + if(pskID == NULL){ + // There is not a value in pskID + } + \endcode + + \sa wolfSSL_get_psk_identity_hint + \sa wolfSSL_use_psk_identity_hint +*/ + WOLFSSL_API const char* wolfSSL_get_psk_identity(const WOLFSSL*); +/*! + \ingroup CertsKeys + + \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 + wolfSSL_CTX_new(). + \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 ); + const char* hint; + int ret; + … + ret = wolfSSL_CTX_use_psk_identity_hint(ctx, hint); + if(ret == SSL_SUCCESS){ + // Function was succesfull. + return ret; + } else { + // Failure case. + } + \endcode + + \sa wolfSSL_use_psk_identity_hint +*/ + 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 + of the Arrays structure within the WOLFSSL structure. + + \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 + in memory. + + _Example_ + \code + WOLFSSL* ssl = wolfSSL_new(ctx); + const char* hint; + ... + if(wolfSSL_use_psk_identity_hint(ssl, hint) != SSL_SUCCESS){ + // 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 + 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 + the WOLFSSL_CTX structure. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + … + unsigned int cb(WOLFSSL*, const char*, unsigned char*, unsigned int) + // signature requirement + { + // Function body. + } + … + if(ctx != NULL){ + wolfSSL_CTX_set_psk_server_callback(ctx, cb); + } else { + // 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 + \sa wolfSSL_CTX_set_psk_client_callback +*/ + 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 + 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 + the WOLFSSL structure. + + _Example_ + \code + WOLFSSL_CTX* ctx; + WOLFSSL* ssl; + … + int cb(WOLFSSL*, const char*, unsigned char*, unsigned int) // Required sig. + { + // Function body. + } + … + if(ssl != NULL && cb != NULL){ + 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 + \sa wolfSSL_get_psk_identity_hint + \sa wc_psk_server_callback + \sa InitSuites +*/ + WOLFSSL_API void wolfSSL_set_psk_server_callback(WOLFSSL*, + wc_psk_server_callback); +/*! + \ingroup Setup + + \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 + 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 + wolfSSL_CTX_new(). + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + ... + #ifdef HAVE_ANON + if(cipherList == NULL){ + wolfSSL_CTX_allow_anon_cipher(ctx); + 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*); +/*! + \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 + creating the SSL/TLS context with wolfSSL_CTX_new(). + + \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 + (typically NULL with errno will be set to ENOMEM). + + \param none No parameters + + _Example_ + \code + WOLFSSL_METHOD* method; + WOLFSSL_CTX* ctx; + + method = wolfSSLv23_server_method(); + if (method == NULL) { + // unable to get method + } + + ctx = wolfSSL_CTX_new(method); + ... + \endcode + + \sa wolfSSLv3_server_method + \sa wolfTLSv1_server_method + \sa wolfTLSv1_1_server_method + \sa wolfTLSv1_2_server_method + \sa wolfDTLSv1_server_method + \sa wolfSSL_CTX_new +*/ +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; + int ret; + // create ssl object + ret = wolfSSL_state(ssl); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + ... + WOLFSSL_X509* peerCert = wolfSSL_get_peer_certificate(ssl); + + if(peerCert){ + // 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 +*/ +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 + is SSL_ERROR_WANT_READ, this function will return 1, otherwise, 0. + + \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; + WOLFSSL* ssl = 0; + ... + + ret = wolfSSL_want_read(ssl); + if (ret == 1) { + // underlying I/O has data available for reading (SSL_ERROR_WANT_READ) + } + \endcode + + \sa wolfSSL_want_write + \sa wolfSSL_get_error +*/ +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 + 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 + 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; + WOLFSSL* ssl = 0; + ... + ret = wolfSSL_want_write(ssl); + if (ret == 1) { + // underlying I/O needs data to be written (SSL_ERROR_WANT_WRITE) + } + \endcode + + \sa wolfSSL_want_read + \sa wolfSSL_get_error +*/ +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 + 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; + WOLFSSL* ssl; + char* domain = (char*) “www.yassl.com”; + ... + + ret = wolfSSL_check_domain_name(ssl, domain); + if (ret != SSL_SUCCESS) { + // failed to enable domain name check + } + \endcode + + \sa none +*/ +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 + 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; + ret = wolfSSL_Init(); + if (ret != SSL_SUCCESS) { + failed to initialize wolfSSL library + } + + \endcode + + \sa wolfSSL_Cleanup +*/ +WOLFSSL_API int wolfSSL_Init(void); +/*! + \ingroup TLS + + \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); +/*! + \ingroup IO + + \brief This function returns the current library version. + + \return LIBWOLFSSL_VERSION_STRING a const char pointer defining the + version. + + \param none No parameters. + + _Example_ + \code + char version[MAXSIZE]; + version = wolfSSL_KeepArrays(); + … + if(version != ExpectedVersion){ + // Handle the mismatch case + } + \endcode + + \sa word32_wolfSSL_lib_version_hex +*/ +WOLFSSL_API const char* wolfSSL_lib_version(void); +/*! + \ingroup IO + + \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; + libV = wolfSSL_lib_version_hex(); + + if(libV != EXPECTED_HEX){ + // How to handle an unexpected value + } else { + // The expected result for libV + } + \endcode + + \sa wolfSSL_lib_version +*/ +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 + while a wolfSSL_accept() is performed if called from the server side. + + \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 + 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; + WOLFSSL* ssl = 0; + ... + ret = wolfSSL_negotiate(ssl); + if (ret == SSL_FATAL_ERROR) { + // SSL establishment failed + int error_code = wolfSSL_get_error(ssl); + ... + } + ... + \endcode + + \sa SSL_connect + \sa SSL_accept +*/ +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 + 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 + built into the library. + + \param ssl pointer to the SSL session, created with wolfSSL_new(). + + _Example_ + \code + int ret = 0; + WOLFSSL* ssl = 0; + ... + ret = wolfSSL_set_compression(ssl); + if (ret == SSL_SUCCESS) { + // successfully enabled compression for SSL session + } + \endcode + + \sa none +*/ +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; + WOLFSSL* ssl = 0; + ... + + ret = wolfSSL_set_timeout(ssl, 500); + if (ret != SSL_SUCCESS) { + // failed to set session timeout value + } + ... + \endcode + + \sa wolfSSL_get_session + \sa wolfSSL_set_session +*/ +WOLFSSL_API int wolfSSL_set_timeout(WOLFSSL*, unsigned int); +/*! + \ingroup Setup + + \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; + ... + ret = wolfSSL_CTX_set_timeout(ctx, 500); + if (ret != SSL_SUCCESS) { + // failed to set session timeout value + } + \endcode + + \sa wolfSSL_flush_sessions + \sa wolfSSL_get_session + \sa wolfSSL_set_session + \sa wolfSSL_get_sessionID + \sa wolfSSL_CTX_set_session_cache_mode +*/ +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 + certificate chain. + \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 + \sa wolfSSL_get_chain_cert_pem +*/ +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 + chain count. + \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 + at index (idx). + + \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 + 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_cert + \sa wolfSSL_get_chain_cert_pem +*/ +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 + certificate by index. + \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 + \sa wolfSSL_get_chain_cert_pem +*/ +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 + 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 + memory SESSION_CACHE. + \param idx the index of the WOLFSSL_X509 certificate. + + _Example_ + \code + WOLFSSL_X509_CHAIN* chain = &session->chain; + int idx = 999; // set idx + ... + WOLFSSL_X509_CHAIN ptr; + prt = wolfSSL_get_chain_X509(chain, idx); + + if(ptr != NULL){ + //ptr contains the cert at the index specified + } else { + // ptr is NULL + } + \endcode + + \sa InitDecodedCert + \sa ParseCertRelative + \sa CopyDecodedToX509 +*/ +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 + certificate by index. + \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 + \sa wolfSSL_get_chain_cert +*/ +WOLFSSL_API int wolfSSL_get_chain_cert_pem(WOLFSSL_X509_CHAIN*, int idx, + unsigned char* buf, int inLen, int* outLen); +/*! + \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 + 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 + 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 + in buffer. + + _Example_ + \code + none + \endcode + + \sa SSL_get_peer_certificate +*/ +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 + name is returned upon success + + \param x509 a pointer to a WOLFSSL_X509 structure containing + certificate information. + + _Example_ + \code + WOLFSSL_X509 x509 = (WOLFSSL_X509*)XMALLOC(sizeof(WOLFSSL_X509), NULL, + DYNAMIC_TYPE_X509); + ... + int x509Cn = wolfSSL_X509_get_subjectCN(x509); + if(x509Cn == NULL){ + // Deal with NULL case + } else { + // x509Cn contains the common name + } + \endcode + + \sa wolfSSL_X509_Name_get_entry + \sa wolfSSL_X509_get_next_altname + \sa wolfSSL_X509_get_issuer_name + \sa wolfSSL_X509_get_subject_name + +*/ +WOLFSSL_API char* wolfSSL_X509_get_subjectCN(WOLFSSL_X509*); +/*! + \ingroup CertsKeys + + \brief This function gets the DER encoded certificate in the + WOLFSSL_X509 struct. + + \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 + 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, + DYNAMIC_TYPE_X509); + int* outSz; // initialize + ... + byte* x509Der = wolfSSL_X509_get_der(x509, outSz); + if(x509Der == NULL){ + // 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 + \sa wolfSSL_X509_get_issuer_name + \sa wolfSSL_X509_get_subject_name +*/ +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, + it returns the notAfter member of the x509 struct. + + \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, + DYNAMIC_TYPE_X509) ; + ... + byte* notAfter = wolfSSL_X509_notAfter(x509); + if(notAfter == NULL){ + // Failure case, the x509 object is null. + } + \endcode + + \sa none +*/ +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; + int version; + ... + version = wolfSSL_X509_version(x509); + if(!version){ + // The function returned 0, failure case. + } + \endcode + + \sa wolfSSL_X509_get_subject_name + \sa wolfSSL_X509_get_issuer_name + \sa wolfSSL_X509_get_isCA + \sa wolfSSL_get_peer_certificate +*/ +WOLFSSL_API int wolfSSL_X509_version(WOLFSSL_X509*); +/*! + \ingroup CertsKeys + + \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 + 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, + DYNAMIC_TYPE_X509); + WOLFSSL_X509** x509 = x509a; + XFILE file; (mapped to struct fs_file*) + ... + WOLFSSL_X509* newX509 = wolfSSL_X509_d2i_fp(x509, file); + if(newX509 == NULL){ + // The function returned NULL + } + \endcode + + \sa wolfSSL_X509_d2i + \sa XFTELL + \sa XREWIND + \sa XFSEEK +*/ + WOLFSSL_API WOLFSSL_X509* + wolfSSL_X509_d2i_fp(WOLFSSL_X509** x509, FILE* file); +/*! + \ingroup CertsKeys + + \brief The function loads the x509 certificate into memory. + + \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); + AssertNotNull(x509); + \endcode + + \sa InitDecodedCert + \sa PemToDer + \sa wolfSSL_get_certificate + \sa AssertNotNull +*/ +WOLFSSL_API WOLFSSL_X509* + wolfSSL_X509_load_certificate_file(const char* fname, int format); +/*! + \ingroup CertsKeys + + \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 + the x509 structure. + \return NULL returned if the buffer size is NULL. + + \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 + (the buffer). + \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, + DYNAMIC_TYPE_X509); + byte* in; + int* inOutSz; + ... + byte* deviceType = wolfSSL_X509_get_device_type(x509, in, inOutSz); + + if(!deviceType){ + // Failure case, NULL was returned. + } + \endcode + + \sa wolfSSL_X509_get_hw_type + \sa wolfSSL_X509_get_hw_serial_number + \sa wolfSSL_X509_d2i +*/ + WOLFSSL_API unsigned char* + wolfSSL_X509_get_device_type(WOLFSSL_X509*, unsigned char*, int*); +/*! + \ingroup CertsKeys + + \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 + 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 + 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 + byte* in; // initialize the buffer + int* inOutSz; // holds the size of the buffer + ... + byte* hwType = wolfSSL_X509_get_hw_type(x509, in, inOutSz); + + if(hwType == NULL){ + // Failure case function returned NULL. + } + \endcode + + \sa wolfSSL_X509_get_hw_serial_number + \sa wolfSSL_X509_get_device_type +*/ + WOLFSSL_API unsigned char* + wolfSSL_X509_get_hw_type(WOLFSSL_X509*, unsigned char*, int*); +/*! + \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 + 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; + ... + serial = wolfSSL_X509_get_hw_serial_number(x509, in, inOutSz); + + if(serial == NULL || serial <= 0){ + // Failure case + } + \endcode + + \sa wolfSSL_X509_get_subject_name + \sa wolfSSL_X509_get_issuer_name + \sa wolfSSL_X509_get_isCA + \sa wolfSSL_get_peer_certificate + \sa wolfSSL_X509_version +*/ + WOLFSSL_API unsigned char* + wolfSSL_X509_get_hw_serial_number(WOLFSSL_X509*, unsigned char*, int*); +/*! + \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 + 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 + detailed error code, call wolfSSL_get_error(). + + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + _Example_ + \code + int ret = 0; + int err = 0; + WOLFSSL* ssl; + char buffer[80]; + ... + ret = wolfSSL_connect_cert(ssl); + if (ret != SSL_SUCCESS) { + err = wolfSSL_get_error(ssl, ret); + printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); + } + \endcode + + \sa wolfSSL_get_error + \sa wolfSSL_connect + \sa wolfSSL_accept +*/ +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 + then be parsed and decrypted by calling. + + \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. + Can be NULL + + _Example_ + \code + WC_PKCS12* pkcs; + WOLFSSL_BIO* bio; + WOLFSSL_X509* cert; + WOLFSSL_EVP_PKEY* pkey; + STACK_OF(X509) certs; + //bio loads in PKCS12 file + wolfSSL_d2i_PKCS12_bio(bio, &pkcs); + wolfSSL_PKCS12_parse(pkcs, “a password”, &pkey, &cert, &certs) + wc_PKCS12_free(pkcs) + //use cert, pkey, and optionally certs stack + \endcode + + \sa wolfSSL_PKCS12_parse + \sa wc_PKCS12_free +*/ +WOLFSSL_API WC_PKCS12* wolfSSL_d2i_PKCS12_bio(WOLFSSL_BIO* bio, + WC_PKCS12** pkcs12); +/*! + \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 + 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; + WOLFSSL_BIO* bio; + WOLFSSL_X509* cert; + WOLFSSL_EVP_PKEY* pkey; + STACK_OF(X509) certs; + //bio loads in PKCS12 file + wolfSSL_d2i_PKCS12_bio(bio, &pkcs); + wolfSSL_PKCS12_parse(pkcs, “a password”, &pkey, &cert, &certs) + wc_PKCS12_free(pkcs) + //use cert, pkey, and optionally certs stack + \endcode + + \sa wolfSSL_d2i_PKCS12_bio + \sa wc_PKCS12_free +*/ +WOLFSSL_API int wolfSSL_PKCS12_parse(WC_PKCS12* pkcs12, const char* psw, + WOLFSSL_EVP_PKEY** pkey, WOLFSSL_X509** cert, WOLF_STACK_OF(WOLFSSL_X509)** ca); +/*! + \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 + 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 + 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; + static unsigned char p[] = {...}; + static unsigned char g[] = {...}; + ... + 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, + const unsigned char* g, int gSz); +/*! + \ingroup CertsKeys + + \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 normally. + \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 + 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 + wolfSSL_SetTmpDH() or in wolfSSL_CTX_SetTmpDH(). + \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 + (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 + format. + + _Example_ + \code + Static int wolfSSL_SetTmpDH_file_wrapper(WOLFSSL_CTX* ctx, WOLFSSL* ssl, + Const char* fname, int format); + long sz = 0; + byte* myBuffer = staticBuffer[FILE_BUFFER_SIZE]; + … + if(ssl) + ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format); + \endcode + + \sa wolfSSL_SetTmpDH_buffer_wrapper + \sa wc_DhParamsLoad + \sa wolfSSL_SetTmpDH + \sa PemToDer + \sa wolfSSL_CTX_SetTmpDH + \sa wolfSSL_CTX_SetTmpDH_file +*/ +WOLFSSL_API int wolfSSL_SetTmpDH_buffer(WOLFSSL*, const unsigned char* b, long sz, + int format); +/*! + \ingroup CertsKeys + + \brief This function calls wolfSSL_SetTmpDH_file_wrapper to set server + Diffie-Hellman parameters. + + \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 + or a subroutine. + \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 + 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, + wolfSSL_SetTmpDH_file(ssl, dhParam, SSL_FILETYPE_PEM)); + \endcode + + \sa wolfSSL_CTX_SetTmpDH_file + \sa wolfSSL_SetTmpDH_file_wrapper + \sa wolfSSL_SetTmpDH_buffer + \sa wolfSSL_CTX_SetTmpDH_buffer + \sa wolfSSL_SetTmpDH_buffer_wrapper + \sa wolfSSL_SetTmpDH + \sa wolfSSL_CTX_SetTmpDH +*/ + 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 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 + WOLFSSL_CTX struct is not the correct size. + \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 + wolfSSL_CTX_new(). + \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 + to MAX_DH_SIZE. + \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 + MAX_DH_SIZE. + + _Exmaple_ + \code + WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol ); + byte* p; + byte* g; + word32 pSz = (word32)sizeof(p)/sizeof(byte); + word32 gSz = (word32)sizeof(g)/sizeof(byte); + … + int ret = wolfSSL_CTX_SetTmpDH(ctx, p, pSz, g, gSz); + + if(ret != SSL_SUCCESS){ + // Failure case + } + \endcode + + \sa wolfSSL_SetTmpDH + \sa wc_DhParamsLoad +*/ +WOLFSSL_API int wolfSSL_CTX_SetTmpDH(WOLFSSL_CTX*, const unsigned char* p, + int pSz, const unsigned char* g, int gSz); +/*! + \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 + wolfSSL_CTX_new(). + \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 + in wolfSSL_SetTmpDH_file_wrapper(). + \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 + #else + byte* staticBuffer; + long sz = 0; + … + if(ssl){ + ret = wolfSSL_SetTmpDH_buffer(ssl, myBuffer, sz, format); + } else { + ret = wolfSSL_CTX_SetTmpDH_buffer(ctx, myBuffer, sz, format); + } + \endcode + + \sa wolfSSL_SetTmpDH_buffer_wrapper + \sa wolfSSL_SetTMpDH_buffer + \sa wolfSSL_SetTmpDH_file_wrapper + \sa wolfSSL_CTX_SetTmpDH_file +*/ +WOLFSSL_API int wolfSSL_CTX_SetTmpDH_buffer(WOLFSSL_CTX*, const unsigned char* b, + long sz, int format); +/*! + \ingroup CertsKeys + + \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 + of its subroutines return successfully. + \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 + a subroutine is passed a NULL argument. + \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 + wolfSSL_SetTmpDH_buffer_wrapper(). + \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 + 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 + failure. + + \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 + the certificate format. + + _Example_ + \code + #define dhParam “certs/dh2048.pem” + #DEFINE aSSERTiNTne(x, y) AssertInt(x, y, !=, ==) + WOLFSSL_CTX* ctx; + … + AssertNotNull(ctx = wolfSSL_CTX_new(wolfSSLv23_client_method())) + … + 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 + \sa wolfSSL_SetTmpDH_buffer + \sa wolfSSL_CTX_SetTmpDH_buffer + \sa wolfSSL_SetTmpDH_file_wrapper + \sa AllocDer + \sa PemToDer +*/ + WOLFSSL_API int wolfSSL_CTX_SetTmpDH_file(WOLFSSL_CTX*, const char* f, + int format); +/*! + \ingroup CertsKeys + + \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 + 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 + 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 + \sa wolfSSL_CTX_SetTMpDH_file +*/ +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 + 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 + 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); + word16 keySz; + ... + if(wolfSSL_SetMinDhKey(ssl, keySz) != SSL_SUCCESS){ + // Failed to set. + } + \endcode + + \sa wolfSSL_GetDhKey_Sz +*/ +WOLFSSL_API int wolfSSL_SetMinDhKey_Sz(WOLFSSL*, unsigned short); +/*! + \ingroup CertsKeys + + \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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + int dhKeySz; + ... + dhKeySz = wolfSSL_GetDhKey_Sz(ssl); + + if(dhKeySz == BAD_FUNC_ARG || dhKeySz <= 0){ + // Failure case + } else { + // dhKeySz holds the size of the key. + } + \endcode + + \sa wolfSSL_SetMinDhKey_sz + \sa wolfSSL_CTX_SetMinDhKey_Sz + \sa wolfSSL_CTX_SetTmpDH + \sa wolfSSL_SetTmpDH + \sa wolfSSL_CTX_SetTmpDH_file +*/ +WOLFSSL_API int wolfSSL_GetDhKey_Sz(WOLFSSL*); +/*! + \ingroup CertsKeys + + \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 + is less than zero or not divisible by 8. + + \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 + structure and the cm structure converted to bytes. + + _Example_ + \code + WOLFSSL_CTX* ctx = SSL_CTX_new(method); + (void)minDhKeyBits; + ourCert = myoptarg; + … + minDhKeyBits = atoi(myoptarg); + … + if(wolfSSL_CTX_SetMinRsaKey_Sz(ctx, minRsaKeyBits) != SSL_SUCCESS){ + … + \endcode + + \sa wolfSSL_SetMinRsaKey_Sz +*/ +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 + 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 + 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); + short keySz; + … + + int isSet = wolfSSL_SetMinRsaKey_Sz(ssl, keySz); + if(isSet != SSL_SUCCESS){ + Failed to set. + } + \endcode + + \sa wolfSSL_CTX_SetMinRsaKey_Sz +*/ +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 + structure and the WOLFSSL_CERT_MANAGER structure. + + \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 + the keySz is negative or not divisible by 8. + + \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 + size in bits. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); + short keySz; // minimum key size + … + if(wolfSSL_CTX_SetMinEccKey(ctx, keySz) != SSL_SUCCESS){ + // Failed to set min key size + } + \endcode + + \sa wolfSSL_SetMinEccKey_Sz +*/ +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 + accessed through the ssl parameter. + + \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 + 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 + value in the options structure. + + _Example_ + \code + WOLFSSL* ssl = wolfSSL_new(ctx); // New session + short keySz = 999; // should be set to min key size allowable + ... + if(wolfSSL_SetMinEccKey_Sz(ssl, keySz) != SSL_SUCCESS){ + // Failure case. + } + \endcode + + \sa wolfSSL_CTX_SetMinEccKey_Sz + \sa wolfSSL_CTX_SetMinRsaKey_Sz + \sa wolfSSL_SetMinRsaKey_Sz +*/ +WOLFSSL_API int wolfSSL_SetMinEccKey_Sz(WOLFSSL*, short); +/*! + \ingroup CertsKeys + + \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 + 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 + of the p_hash function. + \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);; + void* msk; + unsigned int len; + const char* label; + … + return wolfSSL_make_eap_keys(ssl, msk, len, label); + \endcode + + \sa PRF + \sa doPRF + \sa p_hash + \sa wc_HmacFinal + \sa wc_HmacUpdate +*/ +WOLFSSL_API int wolfSSL_make_eap_keys(WOLFSSL*, void* key, unsigned int len, + const char* label); +/*! + \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. + 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 + 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 + 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; + char *bufA = “hello\n”; + char *bufB = “hello world\n”; + int iovcnt; + struct iovec iov[2]; + + iov[0].iov_base = buffA; + iov[0].iov_len = strlen(buffA); + iov[1].iov_base = buffB; + iov[1].iov_len = strlen(buffB); + iovcnt = 2; + ... + 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, + int iovcnt); +/*! + \ingroup Setup + + \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 + are otherwise unpermitted argument values passed in a subroutine. + \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 + wolfSSL_CTX_new(). + + _Example_ + \code + 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 + \sa UnlockMutex +*/ + 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 + 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, + 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; + WOLFSSL_CTX* ctx; + ... + ret = wolfSSL_CTX_Unload_trust_peers(ctx); + if (ret != SSL_SUCCESS) { + // error unloading trusted peer certs + } + ... + \endcode + + \sa wolfSSL_CTX_trust_peer_buffer + \sa wolfSSL_CTX_trust_peer_cert +*/ + 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 + 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 + 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 + 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 + SSL_FILETYPE_PEM. + + _Example_ + \code + int ret = 0; + WOLFSSL_CTX* ctx; + ... + + 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 + \sa wolfSSL_CTX_use_NTRUPrivateKey_file + \sa wolfSSL_CTX_use_certificate_chain_file + \sa wolfSSL_CTX_trust_peer_cert + \sa wolfSSL_CTX_Unload_trust_peers + \sa wolfSSL_use_certificate_file + \sa wolfSSL_use_PrivateKey_file + \sa wolfSSL_use_certificate_chain_file +*/ + WOLFSSL_API int wolfSSL_CTX_trust_peer_buffer(WOLFSSL_CTX*, + const unsigned char*, long, int); +/*! + \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 + 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, + 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 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 + or SSL_FILETYPE_PEM. + + _Example_ + \code + int ret = 0; + int sz = 0; + 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 + + \sa wolfSSL_CTX_load_verify_locations + \sa wolfSSL_CTX_use_certificate_buffer + \sa wolfSSL_CTX_use_PrivateKey_buffer + \sa wolfSSL_CTX_use_NTRUPrivateKey_file + \sa wolfSSL_CTX_use_certificate_chain_buffer + \sa wolfSSL_use_certificate_buffer + \sa wolfSSL_use_PrivateKey_buffer + \sa wolfSSL_use_certificate_chain_buffer +*/ + WOLFSSL_API int wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX*, + const unsigned char*, long, int); +/*! + \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 + 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 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 + buffer (in). Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. + + _Example_ + \code + int ret = 0; + int sz = 0; + WOLFSSL_CTX* ctx; + byte certBuff[...]; + ... + ret = wolfSSL_CTX_use_certificate_buffer(ctx, certBuff, sz, SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + // error loading certificate from buffer + } + ... + \endcode + + \sa wolfSSL_CTX_load_verify_buffer + \sa wolfSSL_CTX_use_PrivateKey_buffer + \sa wolfSSL_CTX_use_NTRUPrivateKey_file + \sa wolfSSL_CTX_use_certificate_chain_buffer + \sa wolfSSL_use_certificate_buffer + \sa wolfSSL_use_PrivateKey_buffer + \sa wolfSSL_use_certificate_chain_buffer +*/ + WOLFSSL_API int wolfSSL_CTX_use_certificate_buffer(WOLFSSL_CTX*, + const unsigned char*, long, int); +/*! + \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 + 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 + 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 + 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 + buffer (in). Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. + + _Example_ + \code + int ret = 0; + int sz = 0; + WOLFSSL_CTX* ctx; + byte keyBuff[...]; + ... + ret = wolfSSL_CTX_use_PrivateKey_buffer(ctx, keyBuff, sz, SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + // error loading private key from buffer + } + ... + \endcode + + \sa wolfSSL_CTX_load_verify_buffer + \sa wolfSSL_CTX_use_certificate_buffer + \sa wolfSSL_CTX_use_NTRUPrivateKey_file + \sa wolfSSL_CTX_use_certificate_chain_buffer + \sa wolfSSL_use_certificate_buffer + \sa wolfSSL_use_PrivateKey_buffer + \sa wolfSSL_use_certificate_chain_buffer +*/ + WOLFSSL_API int wolfSSL_CTX_use_PrivateKey_buffer(WOLFSSL_CTX*, + const unsigned char*, long, int); +/*! + \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 + 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, + 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 receiving buffer. + + \param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). + \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; + int sz = 0; + WOLFSSL_CTX* ctx; + byte certChainBuff[...]; + ... + ret = wolfSSL_CTX_use_certificate_chain_buffer(ctx, certChainBuff, sz); + if (ret != SSL_SUCCESS) { + // error loading certificate chain from buffer + } + ... + \endcode + + \sa wolfSSL_CTX_load_verify_buffer + \sa wolfSSL_CTX_use_certificate_buffer + \sa wolfSSL_CTX_use_PrivateKey_buffer + \sa wolfSSL_CTX_use_NTRUPrivateKey_file + \sa wolfSSL_use_certificate_buffer + \sa wolfSSL_use_PrivateKey_buffer + \sa wolfSSL_use_certificate_chain_buffer +*/ + WOLFSSL_API int wolfSSL_CTX_use_certificate_chain_buffer(WOLFSSL_CTX*, + const unsigned char*, long); +/*! + \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. + 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 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. + Possible values are SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. + + _Example_ + \code + int buffSz; + int ret; + byte certBuff[...]; + WOLFSSL* ssl = 0; + ... + + ret = wolfSSL_use_certificate_buffer(ssl, certBuff, buffSz, SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + // 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 + \sa wolfSSL_CTX_use_NTRUPrivateKey_file + \sa wolfSSL_CTX_use_certificate_chain_buffer + \sa wolfSSL_use_PrivateKey_buffer + \sa wolfSSL_use_certificate_chain_buffer +*/ + WOLFSSL_API int wolfSSL_use_certificate_buffer(WOLFSSL*, const unsigned char*, + long, int); +/*! + \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 + 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 + 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 + 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 + SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. + + _Example_ + \code + int buffSz; + int ret; + byte keyBuff[...]; + WOLFSSL* ssl = 0; + ... + ret = wolfSSL_use_PrivateKey_buffer(ssl, keyBuff, buffSz, SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + // failed to load private key from buffer + } + \endcode + + \sa wolfSSL_use_PrivateKey + \sa wolfSSL_CTX_load_verify_buffer + \sa wolfSSL_CTX_use_certificate_buffer + \sa wolfSSL_CTX_use_PrivateKey_buffer + \sa wolfSSL_CTX_use_NTRUPrivateKey_file + \sa wolfSSL_CTX_use_certificate_chain_buffer + \sa wolfSSL_use_certificate_buffer + \sa wolfSSL_use_certificate_chain_buffer +*/ + WOLFSSL_API int wolfSSL_use_PrivateKey_buffer(WOLFSSL*, const unsigned char*, + long, int); +/*! + \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. + 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, + 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 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; + int ret; + byte certChainBuff[...]; + WOLFSSL* ssl = 0; + ... + ret = wolfSSL_use_certificate_chain_buffer(ssl, certChainBuff, buffSz); + if (ret != SSL_SUCCESS) { + // 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 + \sa wolfSSL_CTX_use_NTRUPrivateKey_file + \sa wolfSSL_CTX_use_certificate_chain_buffer + \sa wolfSSL_use_certificate_buffer + \sa wolfSSL_use_PrivateKey_buffer +*/ + WOLFSSL_API int wolfSSL_use_certificate_chain_buffer(WOLFSSL*, + const unsigned char*, long); +/*! + \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); + ... + int unloadKeys = wolfSSL_UnloadCertsKeys(ssl); + if(unloadKeys != SSL_SUCCESS){ + // Failure case. + } + \endcode + + \sa wolfSSL_CTX_UnloadCAs +*/ + 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; + ... + ret = wolfSSL_CTX_set_group_messages(ctx); + if (ret != SSL_SUCCESS) { + // failed to set handshake message grouping + } + \endcode + + \sa wolfSSL_set_group_messages + \sa wolfSSL_CTX_new +*/ +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; + ... + ret = wolfSSL_set_group_messages(ssl); + if (ret != SSL_SUCCESS) { + // failed to set handshake message grouping + } + \endcode + + \sa wolfSSL_CTX_set_group_messages + \sa wolfSSL_new +*/ +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 + type, void* fuzzCtx); + \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 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 + 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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + const* byte secret; + word32 secretSz; // size of secret + … + if(!wolfSSL_DTLS_SetCookieSecret(ssl, secret, secretSz)){ + // Code block for failure to set DTLS cookie secret + } else { + // Success! Cookie secret is set. + } + \endcode + + \sa ForceZero + \sa wc_RNG_GenerateBlock + \sa XMEMCPY +*/ +WOLFSSL_API int wolfSSL_DTLS_SetCookieSecret(WOLFSSL*, + const unsigned char*, + unsigned int); +/*! + \ingroup Setup + + \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 + error and the minimum version is set. + \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 + 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 + WOLFSSL_TLSV1_2 = 3. + + _Example_ + \code + WOLFSSL_CTX* ctx = WOLFSSL_CTX_new( protocol method ); + WOLFSSL* ssl = WOLFSSL_new(ctx); + int version; // macrop representation + … + if(wolfSSL_CTX_SetMinVersion(ssl->ctx, version) != SSL_SUCCESS){ + // Failed to set min version + } + \endcode + + \sa SetMinVersionHelper +*/ +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 + (wolfSSLv23_client_method or wolfSSLv23_server_method). + + \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 + 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 + WOLFSSL_TLSV1_2 = 3. + + _Example_ + \code + WOLFSSL_CTX* ctx = WOLFSSL_CTX_new(protocol method); + WOLFSSL* ssl = WOLFSSL_new(ctx); + 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 + 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 + 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 + maximum TLS fragment size (see wolfSSL_GetMaxOutputSize()) + \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 + completed. + + \return size Upon success, the maximum output size will be returned + \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 + \endcode + + \sa wolfSSL_GetOutputSize +*/ +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()) + method type. + + \return SSL_SUCCESS upon success. + \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 + WOLFSSL_SSLV3, WOLFSSL_TLSV1, WOLFSSL_TLSV1_1, WOLFSSL_TLSV1_2. + + _Example_ + \code + int ret = 0; + WOLFSSL* ssl; + ... + + ret = wolfSSL_SetVersion(ssl, WOLFSSL_TLSV1); + if (ret != SSL_SUCCESS) { + // failed to set SSL session protocol version + } + \endcode + + \sa wolfSSL_CTX_new +*/ +WOLFSSL_API int wolfSSL_SetVersion(WOLFSSL* ssl, int version); +/*! + \ingroup CertsKeys + + \brief Converts a key in PEM format to DER format. + + \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 + 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, + const char* keyFile, + int typeKey, const char* pasword); + … + bufSz = wolfSSL_KeyPemToDer(loadBuf, (int)fileSz, saveBuf, + (int)fileSz, password); + + if(saveBufSz > 0){ + // Bytes were written to the buffer. + } + \endcode + + \sa PemToDer + \sa wolfssl_decrypt_buffer_key +*/ +WOLFSSL_API int wolfSSL_KeyPemToDer(const unsigned char*, int, + unsigned char*, int, const char*); +/*! + \ingroup CertsKeys + + \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; + ... + if(wolfSSL_CertPemToDer(pem, pemSz, buff, buffSz, type) <= 0) { + // There were bytes written to buffer + } + \endcode + + \sa PemToDer +*/ +WOLFSSL_API int wolfSSL_CertPemToDer(const unsigned char*, int, + unsigned char*, int, int); +/*! + \ingroup CertsKeys + + \brief Converts the PEM format to DER format. + + \return int an int type representing the bytes written to buffer. + \param <0 returned for an error. + \param BAD_FUNC_ARG returned if the DER length is incorrect or if the + pem buff, or buffSz arguments are NULL. + + _Example_ + \code + unsigned char* pem = “pem file”; + int pemSz = sizeof(pem)/sizeof(char); + unsigned char* buff; + int buffSz; + ... + if(wolfSSL_PubKeyPemToDer(pem, pemSz, buff, buffSz)!= SSL_SUCCESS){ + // Conversion was not successful + } + \endcode + + \sa wolfSSL_PubKeyPemToDer + \sa wolfSSL_PemPubKeyToDer + \sa PemToDer +*/ + WOLFSSL_API int wolfSSL_PubKeyPemToDer(const unsigned char*, int, + unsigned char*, int); +/*! + \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 + 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 + wolfSSL_SetMacEncryptCtx(). + + \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. + 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 +*/ +WOLFSSL_API void wolfSSL_CTX_SetDecryptVerifyCb(WOLFSSL_CTX*, + CallbackDecryptVerify); +/*! + \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 + wolfSSL_SetDecryptVerifyCtx(). + + \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 + peer message. + + \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 + 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) + from the handshake process. + + \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() +*/ +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 + 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) + from the handshake process. + + \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 +*/ +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 +*/ +WOLFSSL_API int wolfSSL_GetKeySize(WOLFSSL*); +/*! + \ingroup CertsKeys + + \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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + int ivSize; + ... + ivSize = wolfSSL_GetIVSize(ssl); + + if(ivSize > 0){ + // ivSize holds the specs.iv_size value. + } + \endcode + + \sa wolfSSL_GetKeySize + \sa wolfSSL_GetClientWriteIV + \sa wolfSSL_GetServerWriteIV +*/ +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 + 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 + is at least TLS version 1.1 or greater. + + \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 + 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, + 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 + the handshake. + + \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 + handshake. For cipher type WOLFSSL_AEAD_TYPE. + + \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 + handshake. For cipher types except WOLFSSL_AEAD_TYPE. + + \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 + handshake. For cipher types except WOLFSSL_AEAD_TYPE. + + \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 + from the handshake. + + \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 + 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 +*/ +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 + 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 + 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 + Context previously stored with wolfSSL_SetEccSignCtx(). + + \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 + 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 + 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 + Context previously stored with wolfSSL_SetEccVerifyCtx(). + + \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 + 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 + 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 + Context previously stored with wolfSSL_SetRsaSignCtx(). + + \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. + 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 + 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 + Context previously stored with wolfSSL_SetRsaVerifyCtx(). + + \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 + 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 + 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 + Callback Context previously stored with wolfSSL_SetRsaEncCtx(). + + \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 + 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 + 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 + Callback Context previously stored with wolfSSL_SetRsaDecCtx(). + + \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 + 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 + as shown above in the Synopsis section. + + _Example_ + \code + WOLFSSL_CTX* ctx = 0; + + // CA callback prototype + int MyCACallback(unsigned char *der, int sz, int type); + + // Register the custom CA callback with the SSL context + wolfSSL_CTX_SetCACb(ctx, MyCACallback); + + 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” + } + \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 + load certificates, verify certificates, and check the revocation status. + + \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 + load certificates, verify certificates, and check the revocation status. + + \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 + 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 + 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 + 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, + 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 not provided. + \return SSL_FATAL_ERROR - will be returned upon failure. + + \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 + 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 + certificate directory is desired. + + _Example_ + \code + #include + + int ret = 0; + WOLFSSL_CERT_MANAGER* cm; + ... + ret = wolfSSL_CertManagerLoadCA(cm, “path/to/cert-file.pem”, 0); + if (ret != SSL_SUCCESS) { + // error loading CA certs into cert manager + } + \endcode + + \sa wolfSSL_CertManagerVerify +*/ + WOLFSSL_API int wolfSSL_CertManagerLoadCA(WOLFSSL_CERT_MANAGER*, const char* f, + const char* d); +/*! + \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 + in the cm passed into the function. + + \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 + 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; + … + const unsigned char* in; + long sz; + int format; + … + if(wolfSSL_CertManagerLoadCABuffer(vp, sz, format) != SSL_SUCCESS){ + Error returned. Failure case code block. + } + \endcode + + \sa wolfSSL_CTX_load_verify_buffer + \sa ProcessChainBuffer + \sa ProcessBuffer + \sa cm_pick_method +*/ + WOLFSSL_API int wolfSSL_CertManagerLoadCABuffer(WOLFSSL_CERT_MANAGER*, + const unsigned char* in, long sz, int format); +/*! + \ingroup CertManager + \brief This function unloads the CA signer list. + + \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, + created using wolfSSL_CertManagerNew(). + + _Example_ + \code + #include + + WOLFSSL_CTX* ctx = wolfSSL_CTX_new(protocol method); + WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew(); + ... + if(wolfSSL_CertManagerUnloadCAs(ctx->cm) != SSL_SUCCESS){ + Failure case. + } + \endcode + + \sa FreeSignerTable + \sa UnlockMutex +*/ + WOLFSSL_API int wolfSSL_CertManagerUnloadCAs(WOLFSSL_CERT_MANAGER* cm); +/*! + \ingroup CertManager + \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 + WOLFSSL_CERT_MANAGER struct, is 0 (nill). + + \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(); + ... + if(wolfSSL_CertManagerUnload_trust_peers(cm) != SSL_SUCCESS){ + 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 + 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 + verified. + \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 + has been revoked. + \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 + before date. + \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 + 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 + not provided. + + \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 + to verify. + \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”, + SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + error verifying certificate + } + \endcode + + \sa wolfSSL_CertManagerLoadCA + \sa wolfSSL_CertManagerVerifyBuffer +*/ + WOLFSSL_API int wolfSSL_CertManagerVerify(WOLFSSL_CERT_MANAGER*, const char* f, + int format); +/*! + \ingroup CertManager + \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 + be verified. + \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 + has been revoked. + \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 before date. + \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 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 not provided. + + \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 + SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. + + _Example_ + \code + #include + + int ret = 0; + int sz = 0; + WOLFSSL_CERT_MANAGER* cm; + byte certBuff[...]; + ... + + ret = wolfSSL_CertManagerVerifyBuffer(cm, certBuff, sz, SSL_FILETYPE_PEM); + if (ret != SSL_SUCCESS) { + error verifying certificate + } + + \endcode + + \sa wolfSSL_CertManagerLoadCA + \sa wolfSSL_CertManagerVerify +*/ + 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 + CRL list. + + \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; + byte* der; + int sz; // size of der + ... + if(wolfSSL_CertManagerCheckCRL(cm, der, sz) != SSL_SUCCESS){ + // Error returned. Deal with failure case. + } + \endcode + + \sa CheckCertCRL + \sa ParseCertRelative + \sa wolfSSL_CertManagerSetCRL_CB + \sa InitDecodedCert +*/ + WOLFSSL_API int wolfSSL_CertManagerCheckCRL(WOLFSSL_CERT_MANAGER*, + unsigned char*, int sz); +/*! + \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 + 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 + 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 + is not provided. + \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 + wolfSSL_CertManagerNew(). + \param options options to use when enabling the Certification Manager, cm. + + _Example_ + \code + #include + + int ret = 0; + WOLFSSL_CERT_MANAGER* cm; + ... + + ret = wolfSSL_CertManagerEnableCRL(cm, 0); + if (ret != SSL_SUCCESS) { + error enabling cert manager + } + + ... + \endcode + + \sa wolfSSL_CertManagerDisableCRL +*/ + WOLFSSL_API int wolfSSL_CertManagerEnableCRL(WOLFSSL_CERT_MANAGER*, + int options); +/*! + \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 + 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 + pointer is not provided. + + \param cm a pointer to a WOLFSSL_CERT_MANAGER structure, created using + wolfSSL_CertManagerNew(). + + _Example_ + \code + #include + + int ret = 0; + WOLFSSL_CERT_MANAGER* cm; + ... + ret = wolfSSL_CertManagerDisableCRL(cm); + if (ret != SSL_SUCCESS) { + error disabling 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 + cert into the CRL for revocation checking. + + \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 + 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 + 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 monitor); + … + wolfSSL_CertManagerLoadCRL(ssl->ctx->cm, path, type, monitor); + \endcode + + \sa wolfSSL_CertManagerEnableCRL + \sa wolfSSL_LoadCRL +*/ + WOLFSSL_API int wolfSSL_CertManagerLoadCRL(WOLFSSL_CERT_MANAGER*, + const char*, int, int); +/*! + \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 + 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; + long sz; size of buffer + int type; cert type + ... + int ret = wolfSSL_CertManagerLoadCRLBuffer(cm, buff, sz, type); + if(ret == SSL_SUCCESS){ + return ret; + } else { + Failure case. + } + \endcode + + \sa BufferLoadCRL + \sa wolfSSL_CertManagerEnableCRL +*/ + WOLFSSL_API int wolfSSL_CertManagerLoadCRLBuffer(WOLFSSL_CERT_MANAGER*, + const unsigned char*, long sz, int); +/*! + \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 + allows you to externally retrieve the CRL and load it. + + \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 + the certificate. + \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); + … + void cb(const char* url){ + Function body. + } + … + CbMissingCRL cb = CbMissingCRL; + … + if(ctx){ + return wolfSSL_CertManagerSetCRL_Cb(ssl->ctx->cm, cb); + } + \endcode + + \sa CbMissingCRL + \sa wolfSSL_SetCRL_Cb +*/ + WOLFSSL_API int wolfSSL_CertManagerSetCRL_Cb(WOLFSSL_CERT_MANAGER*, + CbMissingCRL); +/*! + \ingroup CertManager + \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 + ocspEnabled member of the WOLFSSL_CERT_MANAGER is enabled. + \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 + this function or a subroutine. + + \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 + ... + if(wolfSSL_CertManagerCheckOCSP(cm, der, sz) != SSL_SUCCESS){ + Failure case. + } + \endcode + + \sa ParseCertRelative + \sa CheckCertOCSP +*/ + WOLFSSL_API int wolfSSL_CertManagerCheckOCSP(WOLFSSL_CERT_MANAGER*, + unsigned char*, int sz); +/*! + \ingroup CertManager + \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 + 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 + 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; + … + if(wolfSSL_CertManagerEnableOCSP(ssl->ctx->cm, options) != SSL_SUCCESS){ + Failure case. + } + \endcode + + \sa wolfSSL_CertManagerNew +*/ + WOLFSSL_API int wolfSSL_CertManagerEnableOCSP(WOLFSSL_CERT_MANAGER*, + int options); +/*! + \ingroup CertManager + \brief Disables OCSP certificate revocation. + + \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); + ... + if(wolfSSL_CertManagerDisableOCSP(ssl) != SSL_SUCCESS){ + 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 + 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 + ocspOverrideURL member of the certificate manager. + + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + _Example_ + \code + #include + WOLFSSL_CERT_MANAGER* cm = wolfSSL_CertManagerNew(); + const char* url; + … + int wolfSSL_SetOCSP_OverrideURL(WOLFSSL* ssl, const char* url) + … + if(wolfSSL_CertManagerSetOCSPOverrideURL(ssl->ctx->cm, url) != SSL_SUCCESS){ + Failure case. + } + \endcode + + \sa ocspOverrideURL + \sa wolfSSL_SetOCSP_OverrideURL +*/ + WOLFSSL_API int wolfSSL_CertManagerSetOCSPOverrideURL(WOLFSSL_CERT_MANAGER*, + const char*); +/*! + \ingroup CertManager + \brief The function sets the OCSP callback in the WOLFSSL_CERT_MANAGER. + + \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 + registered context. + + _Example_ + \code + #include + + 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 + \sa wolfSSL_ENableOCSP + \sa wolfSSL_DisableOCSP + \sa wolfSSL_SetOCSP_Cb +*/ + WOLFSSL_API int wolfSSL_CertManagerSetOCSP_Cb(WOLFSSL_CERT_MANAGER*, + CbOCSPIO, CbOCSPRespFree, void*); +/*! + \ingroup CertManager + \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 + 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 + a subroutine. + \return MEMORY_E returned if there was an issue allocating memory. + \return SSL_FAILURE returned if the initialization of the OCSP + structure failed. + \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 + 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( + WOLFSSL_CERT_MANAGER* cm); +/*! + \brief Enables CRL certificate revocation. + + \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 + 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 + 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 + a subroutine + } + \endcode + + \sa wolfSSL_CertManagerEnableCRL + \sa InitCRL +*/ + WOLFSSL_API int wolfSSL_EnableCRL(WOLFSSL* ssl, int options); +/*! + \brief Disables CRL certificate revocation. + + \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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + ... + if(wolfSSL_DisableCRL(ssl) != SSL_SUCCESS){ + // 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 + certificate for revocation checking. + + \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 successfully. + \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 + crl file. + \param type an integer representing the type of certificate. + \param monitor an integer variable used to verify the monitor path if + requested. + + _Example_ + \code + WOLFSSL* ssl = wolfSSL_new(ctx); + const char* crlPemDir; + … + if(wolfSSL_LoadCRL(ssl, crlPemDir, SSL_FILETYPE_PEM, 0) != SSL_SUCCESS){ + // Failure case. Did not return SSL_SUCCESS. + } + \endcode + + \sa wolfSSL_CertManagerLoadCRL + \sa wolfSSL_CertManagerEnableCRL + \sa LoadCRL +*/ + 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 + without error. The cbMissingCRL member of the WOLFSSL_CERT_MANAGER is set. + \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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + … + void cb(const char* url) // required signature + { + // Function body + } + … + int crlCb = wolfSSL_SetCRL_Cb(ssl, cb); + if(crlCb != SSL_SUCCESS){ + // The callback was not set properly + } + \endcode + + \sa CbMissingCRL + \sa wolfSSL_CertManagerSetCRL_Cb +*/ + 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 + without errors. + \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 + a structure or other variable. + \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() + used for settings check. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + int options; // initialize to option constant + … + int ret = wolfSSL_EnableOCSP(ssl, options); + if(ret != SSL_SUCCESS){ + // 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 + 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); + … + if(wolfSSL_DisableOCSP(ssl) != SSL_SUCCESS){ + // 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 + 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 + unpermitted argument was passed to a subroutine. + \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 + ocspOverrideURL member of the WOLFSSL_CERT_MANAGER structure. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + char url[URLSZ]; + ... + if(wolfSSL_SetOCSP_OverrideURL(ssl, url)){ + // 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 + WOLFSSL_CERT_MANAGER structure. + + \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 + 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 + call to free the response memory. + \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, + unsigned char**){ // must have this signature + // Function Body + } + … + void OCSPRespFree_CB(void* , unsigned char* ){ // must have this signature + // function body + } + … + void* ioCbCtx; + CbOCSPRespFree 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 +*/ + 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 + was otherwise an invalid argument passed in a subroutine. + \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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + ... + if(wolfSSL_CTX_EnableCRL(ssl->ctx, options) != SSL_SUCCESS){ + // The function failed + } + \endcode + + \sa wolfSSL_CertManagerEnableCRL + \sa InitCRL + \sa wolfSSL_CTX_DisableCRL +*/ + 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. + 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 + struct has a NULL value. + + \param ctx a pointer to a WOLFSSL_CTX structure, created using + wolfSSL_CTX_new(). + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + ... + if(wolfSSL_CTX_DisableCRL(ssl->ctx) != SSL_SUCCESS){ + // 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 + wolfSSL_CertManagerLoadCRL(). + + \return SSL_SUCCESS - returned if the function and its subroutines + execute without error. + \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 + 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 + path is requested. + + _Example_ + \code + WOLFSSL_CTX* ctx; + const char* path; + … + 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 + wolfSSL_CertManagerSetCRL_Cb. + + \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 + are NULL. + + \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. + Signature requirement: + void (*CbMissingCRL)(const char* url); + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); + … + void cb(const char* url) // Required signature + { + // Function body + } + … + if (wolfSSL_CTX_SetCRL_Cb(ctx, cb) != SSL_SUCCESS){ + // 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 + 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, + 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. + + _Example_ + \code + WOLFSSL_CTX* ctx = 0; + ... + 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 + affecting the ocspEnabled member of the WOLFSSL_CERT_MANAGER structure. + + \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 + wolfSSL_CTX_new(). + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + ... + if(!wolfSSL_CTX_DisableOCSP(ssl->ctx)){ + // 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 + 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, + 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 + successfully set. + \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; + CbOCSPRespFree ocspRespFreeCb; + … + void* ioCbCtx; + + 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 +*/ + WOLFSSL_API int wolfSSL_CTX_SetOCSP_Cb(WOLFSSL_CTX*, + CbOCSPIO, CbOCSPRespFree, void*); +/*! + \brief This function enables OCSP stapling by calling + wolfSSL_CertManagerEnableOCSPStapling(). + + \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 + 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 + structure failed. + \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 + wolfSSL_CTX_new(). + + _Example_ + \code + WOLFSSL* ssl = WOLFSSL_new(); + ssl->method.version; // set to desired protocol + ... + if(!wolfSSL_CTX_EnableOCSPStapling(ssl->ctx)){ + // OCSP stapling is not enabled + } + \endcode + + \sa wolfSSL_CertManagerEnableOCSPStapling + \sa InitOCSP +*/ + 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 + 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*); +/*! + \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 + 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 + case of SNI mismatch. + + \return SSL_SUCCESS upon success. + \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. + 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; + WOLFSSL_CTX* ctx = 0; + WOLFSSL* ssl = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + ssl = wolfSSL_new(ctx); + if (ssl == NULL) { + // ssl creation failed + } + 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 +*/ +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 + 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 + 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. + 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; + WOLFSSL_CTX* ctx = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + 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 +*/ +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 + 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. + 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 + hostname provided by the client mismatch with the servers. + \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 + the session. + + _Example_ + \code + int ret = 0; + WOLFSSL_CTX* ctx = 0; + WOLFSSL* ssl = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + ssl = wolfSSL_new(ctx); + if (ssl == NULL) { + // ssl creation failed + } + ret = wolfSSL_UseSNI(ssl, 0, "www.yassl.com", strlen("www.yassl.com")); + if (ret != 0) { + // sni usage failed + } + 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 +*/ +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 + 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. + 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 + hostname provided by the client mismatch with the servers. + \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 + the session. + + _Example_ + \code + int ret = 0; + WOLFSSL_CTX* ctx = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + ret = wolfSSL_CTX_UseSNI(ctx, 0, "www.yassl.com", strlen("www.yassl.com")); + if (ret != 0) { + // sni usage failed + } + 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 +*/ +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 + 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 + 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 + Client Hello message. + \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 + 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 + to MIN("SNI's length", inOutSz). + + _Example_ + \code + unsigned char buffer[1024] = {0}; + unsigned char result[32] = {0}; + int length = 32; + // read Client Hello to buffer... + ret = wolfSSL_SNI_GetFromBuffer(buffer, sizeof(buffer), 0, result, &length)); + if (ret != SSL_SUCCESS) { + // sni retrieve failed + } + \endcode + + \sa wolfSSL_UseSNI + \sa wolfSSL_CTX_UseSNI + \sa wolfSSL_SNI_GetRequest +*/ +WOLFSSL_API int wolfSSL_SNI_GetFromBuffer( + const unsigned char* clientHello, unsigned int helloSz, + unsigned char type, unsigned char* sni, unsigned int* inOutSz); +/*! + \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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + … + #define AssertIntEQ(x, y) AssertInt(x, y, ==, !=) + … + Byte type = WOLFSSL_SNI_HOST_NAME; + char* request = (char*)&type; + AssertIntEQ(WOLFSSL_SNI_NO_MATCH, wolfSSL_SNI_Status(ssl, type)); + … + \endcode + + \sa TLSX_SNI_Status + \sa TLSX_SNI_find + \sa TLSX_Find +*/ +WOLFSSL_API unsigned char wolfSSL_SNI_Status(WOLFSSL* ssl, unsigned char type); +/*! + \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 + 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; + WOLFSSL_CTX* ctx = 0; + WOLFSSL* ssl = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + ssl = wolfSSL_new(ctx); + if (ssl == NULL) { + // ssl creation failed + } + ret = wolfSSL_UseSNI(ssl, 0, "www.yassl.com", strlen("www.yassl.com")); + if (ret != 0) { + // sni usage failed + } + if (wolfSSL_accept(ssl) == SSL_SUCCESS) { + void *data = NULL; + unsigned short size = wolfSSL_SNI_GetRequest(ssl, 0, &data); + } + \endcode + + \sa wolfSSL_UseSNI + \sa wolfSSL_CTX_UseSNI +*/ +WOLFSSL_API unsigned short wolfSSL_SNI_GetRequest(WOLFSSL *ssl, + unsigned char type, void** data); +/*! + \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 + 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. + Comma delimited string is required. + \param protocol_name_listSz Size of the list of protocol names. + \param options WOLFSSL_ALPN_CONTINUE_ON_MISMATCH or + WOLFSSL_ALPN_FAILED_ON_MISMATCH. + + _Example_ + \code + wolfSSL_Init(); + WOLFSSL_CTX* ctx; + WOLFSSL* ssl; + WOLFSSL_METHOD method = // Some wolfSSL method + ctx = wolfSSL_CTX_new(method); + ssl = wolfSSL_new(ctx); + + char 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, + unsigned int protocol_name_listSz, + unsigned char options); +/*! + \ingroup TLS + + \brief This function gets the protocol name set by the server. + + \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 + error thrown if there is more than one protocol name accepted. + \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 + 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 + 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 ); + WOLFSSL* ssl = WOLFSSL_new(ctx); + ... + int err; + char* protocol_name = NULL; + Word16 protocol_nameSz = 0; + err = wolfSSL_ALPN_GetProtocol(ssl, &protocol_name, &protocol_nameSz); + + if(err == SSL_SUCCESS){ + // Sent ALPN protocol + } + \endcode + + \sa TLSX_ALPN_GetRequest + \sa TLSX_Find +*/ +WOLFSSL_API int wolfSSL_ALPN_GetProtocol(WOLFSSL* ssl, char **protocol_name, + unsigned short *size); +/*! + \ingroup TLS + + \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 + 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 + list buffer (either it’s NULL or the size is 0). + \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 + 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); + … + #ifdef HAVE_ALPN + char* list = NULL; + word16 listSz = 0; + … + err = wolfSSL_ALPN_GetPeerProtocol(ssl, &list, &listSz); + + if(err == SSL_SUCCESS){ + 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 + ClientHello by wolfSSL clients. + + \return SSL_SUCCESS upon success. + \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 + bytes wolfSSL ONLY!!! }; + + _Example_ + \code + int ret = 0; + WOLFSSL_CTX* ctx = 0; + WOLFSSL* ssl = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + ssl = wolfSSL_new(ctx); + if (ssl == NULL) { + // ssl creation failed + } + ret = wolfSSL_UseMaxFragment(ssl, WOLFSSL_MFL_2_11); + if (ret != 0) { + // 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 + 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 + 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, + 4096 bytes WOLFSSL_MFL_2_13 = 5, 8192 bytes wolfSSL ONLY!!! }; + + _Example_ + \code + int ret = 0; + WOLFSSL_CTX* ctx = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + ret = wolfSSL_CTX_UseMaxFragment(ctx, WOLFSSL_MFL_2_11); + if (ret != 0) { + // 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 + by wolfSSL clients. + + \return SSL_SUCCESS upon success. + \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; + WOLFSSL_CTX* ctx = 0; + WOLFSSL* ssl = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + ssl = wolfSSL_new(ctx); + if (ssl == NULL) { + // ssl creation failed + } + ret = wolfSSL_UseTruncatedHMAC(ssl); + if (ret != 0) { + // 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 + 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 + 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; + WOLFSSL_CTX* ctx = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + ret = wolfSSL_CTX_UseTruncatedHMAC(ctx); + if (ret != 0) { + // 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 + lowers the cost of certificate revocation check presented in OCSP. + + \return SSL_SUCCESS returned if TLSX_UseCertificateStatusRequest + executes without error. + \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 + 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 + CertificateStatusRequest structure. + \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, + WOLFSSL_CSR2_OCSP_USE_NONCE) != SSL_SUCCESS){ + // Failed case. + } + \endcode + + \sa TLSX_UseCertificateStatusRequest + \sa wolfSSL_CTX_UseOCSPStapling +*/ +WOLFSSL_API int wolfSSL_UseOCSPStapling(WOLFSSL* ssl, + unsigned char status_type, unsigned char options); +/*! + \brief This function requests the certificate status during the handshake. + + \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 + otherwise if a unpermitted value is passed to a subroutine. + \return MEMORY_E returned if the function or subroutine failed to properly + allocate memory. + + \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 + CertificateStatusRequest structure. + \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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + byte statusRequest = 0; // Initialize status request + … + switch(statusRequest){ + case 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 +*/ +WOLFSSL_API int wolfSSL_CTX_UseOCSPStapling(WOLFSSL_CTX* ctx, + unsigned char status_type, unsigned char options); +/*! + \brief The function sets the status type and options for OCSP. + + \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 + 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 + wolfSSL_SNI_SetOptions() and wolfSSL_CTX_SNI_SetOptions(). + + _Example_ + \code + WOLFSSL* ssl = wolfSSL_new(ctx); + ... + if (wolfSSL_UseOCSPStaplingV2(ssl, WOLFSSL_CSR2_OCSP_MULTI, 0) != SSL_SUCCESS){ + // Did not execute properly. Failure case code block. + } + \endcode + + \sa TLSX_UseCertificatStatusRequestV2 + \sa wolfSSL_SNI_SetOptions + \sa wolfSSL_CTX_SNI_SetOptions +*/ +WOLFSSL_API int wolfSSL_UseOCSPStaplingV2(WOLFSSL* ssl, + unsigned char status_type, unsigned char options); +/*! + \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 + 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 + wolfSSL_CTX_new(). + \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 + CertificateStatusRequestItemV2 struct. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); + byte status_type; + byte options; + ... + if(wolfSSL_CTX_UseOCSPStaplingV2(ctx, status_type, options); != SSL_SUCCESS){ + // Failure case. + } + \endcode + + \sa TLSX_UseCertificateStatusRequestV2 + \sa wc_RNG_GenerateBlock + \sa TLSX_Push +*/ +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 + 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 + 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, + WOLFSSL_ECC_SECP521R1 = 0x19 }; + + _Example_ + \code + int ret = 0; + WOLFSSL_CTX* ctx = 0; + WOLFSSL* ssl = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + ssl = wolfSSL_new(ctx); + if (ssl == NULL) { + // ssl creation failed + } + ret = wolfSSL_UseSupportedCurve(ssl, WOLFSSL_ECC_SECP256R1); + if (ret != 0) { + // 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 + 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 + 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, + WOLFSSL_ECC_SECP521R1 = 0x19 }; + + _Example_ + \code + int ret = 0; + WOLFSSL_CTX* ctx = 0; + ctx = wolfSSL_CTX_new(method); + if (ctx == NULL) { + // context creation failed + } + ret = wolfSSL_CTX_UseSupportedCurve(ctx, WOLFSSL_ECC_SECP256R1); + if (ret != 0) { + // Elliptic Curve Extension usage failed + } + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_UseSupportedCurve +*/ +WOLFSSL_API int wolfSSL_CTX_UseSupportedCurve(WOLFSSL_CTX* ctx, + unsigned short name); +/*! + \ingroup IO + + \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 + renegotiation. + + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + _Example_ + \code + wolfSSL_Init(); + WOLFSSL_CTX* ctx; + WOLFSSL* ssl; + WOLFSSL_METHOD method = // Some wolfSSL method + ctx = wolfSSL_CTX_new(method); + ssl = wolfSSL_new(ctx); + + if(wolfSSL_UseSecureRenegotiation(ssl) != SSL_SUCCESS) + { + // Error setting secure renegotiation + } + \endcode + + \sa TLSX_Find + \sa TLSX_UseSecureRenegotiation +*/ +WOLFSSL_API int wolfSSL_UseSecureRenegotiation(WOLFSSL* ssl); +/*! + \ingroup IO + + \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 + if an unacceptable argument was passed in a subroutine. + \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 + 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); + ... + if(wolfSSL_Rehandshake(ssl) != SSL_SUCCESS){ + // There was an error and the rehandshake is not successful. + } + \endcode + + \sa wolfSSL_negotiate + \sa wc_InitSha512 + \sa wc_InitSha384 + \sa wc_InitSha256 + \sa wc_InitSha + \sa wc_InitMd5 +*/ +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 + 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(); + WOLFSSL_CTX* ctx; + WOLFSSL* ssl; + WOLFSSL_METHOD method = // Some wolfSSL method + ctx = wolfSSL_CTX_new(method); + ssl = wolfSSL_new(ctx); + + if(wolfSSL_UseSessionTicket(ssl) != SSL_SUCCESS) + { + // Error setting session ticket + } + \endcode + + \sa TLSX_UseSessionTicket +*/ +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(); + WOLFSSL_CTX* ctx; + WOLFSSL_METHOD method = // Some wolfSSL method ; + ctx = wolfSSL_CTX_new(method); + + if(wolfSSL_CTX_UseSessionTicket(ctx) != SSL_SUCCESS) + { + // Error setting session ticket + } + \endcode + + \sa TLSX_UseSessionTicket +*/ +WOLFSSL_API int wolfSSL_CTX_UseSessionTicket(WOLFSSL_CTX* ctx); +/*! + \ingroup IO + + \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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + byte* buf; + word32 bufSz; // Initialize with buf size + … + if(wolfSSL_get_SessionTicket(ssl, buf, bufSz) <= 0){ + // Nothing was written to the buffer + } else { + // the buffer holds the content from ssl->session.ticket + } + \endcode + + \sa wolfSSL_UseSessionTicket + \sa wolfSSL_set_SessionTicket +*/ +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 + is copied to memory. + + \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 + 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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + byte* buffer; // File to load + word32 bufSz; + ... + if(wolfSSL_KeepArrays(ssl, buffer, bufSz) != SSL_SUCCESS){ + // 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: + 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 + WOLFSSL structure. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + … + int sessionTicketCB(WOLFSSL* ssl, const unsigned char* ticket, int ticketSz, + void* ctx){ … } + wolfSSL_set_SessionTicket_cb(ssl, sessionTicketCB, (void*)”initial session”); + \endcode + + \sa wolfSSL_set_SessionTicket + \sa CallbackSessionTicket + \sa sessionTicketCB +*/ +WOLFSSL_API int wolfSSL_set_SessionTicket_cb(WOLFSSL*, + CallbackSessionTicket, void*); +/*! + \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 + wolfSSL_new() + \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 + 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 + 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 + in the ticket buffer. + \param userCtx(Callback) the user context set with + wolfSSL_CTX_set_TicketEncCtx() + + _Example_ + \code + See wolfssl/test.h myTicketEncCb() used by the example + server and example echoserver. + \endcode + + \sa wolfSSL_CTX_set_TicketHint + \sa wolfSSL_CTX_set_TicketEncCtx +*/ +WOLFSSL_API int wolfSSL_CTX_set_TicketEncCb(WOLFSSL_CTX* ctx, + SessionTicketEncCb); +/*! + \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 + 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 + passing invalid arguments to the function. + + \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*); +/*! + \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(); + WOLFSSL_CTX* ctx; + WOLFSSL* ssl; + WOLFSSL_METHOD method = // Some wolfSSL method + ctx = wolfSSL_CTX_new(method); + ssl = wolfSSL_new(ctx); + + if(wolfSSL_isQSH(ssl) == 1) + { + // SSL is using QSH. + } + \endcode + + \sa wolfSSL_UseSupportedQSH +*/ +WOLFSSL_API int wolfSSL_isQSH(WOLFSSL* ssl); +/*! + \ingroup Setup + + \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(); + WOLFSSL_CTX* ctx; + WOLFSSL* ssl; + WOLFSSL_METHOD method = // Some wolfSSL method ; + ctx = wolfSSL_CTX_new(method); + ssl = wolfSSL_new(ctx); + + word16 qsh_name = WOLFSSL_NTRU_EESS439; + + if(wolfSSL_UseSupportedQSH(ssl,qsh_name) != SSL_SUCCESS) + { + // Error setting QSH + } + \endcode + + \sa TLSX_UseQSHScheme +*/ +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 + 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 + during hello. + + _Example_ + \code + WOLFSSL* ssl; + unsigned char flag = 1; // send keys + ... + if(!wolfSSL_UseClientQSHKeys(ssl, flag)){ + // The keys will be sent during hello. + } + \endcode + + \sa wolfSSL_UseALPN + \sa wolfSSL_UseSupportedQSH + \sa wolfSSL_isQSH +*/ + WOLFSSL_API int wolfSSL_UseClientQSHKeys(WOLFSSL* ssl, unsigned char flag); +/*! + \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. + 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 + the form: int (*HandShakeDoneCb)(WOLFSSL*, void*); + \param user_ctx a void pointer to the user registered context. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + … + int myHsDoneCb(WOLFSSL* ssl, void* user_ctx){ + // callback function + } + … + wolfSSL_SetHsDoneCb(ssl, myHsDoneCb, NULL); + \endcode + + \sa HandShakeDoneCb +*/ +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. + if(wolfSSL_PrintSessionStats(void) != SSL_SUCCESS ){ + // Did not print session stats + } + + \endcode + + \sa wolfSSL_get_session_stats +*/ +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, + &totalSessionsSeen, &peak, &maxSessions); + … + return ret; + \endcode + + \sa get_locked_session_stats + \sa wolfSSL_PrintSessionStats +*/ +WOLFSSL_API int wolfSSL_get_session_stats(unsigned int* active, + unsigned int* total, + unsigned int* peak, + unsigned int* maxSessions); +/*! + \ingroup TLS + + \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 + with the size of the buffer. + \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. + \param pmsLen the length of the pre-master secret. + \param cr the client random. + \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 + information as follows: + + int MakeTlsMasterSecret(WOLFSSL* ssl){ + int ret; + ret = wolfSSL_makeTlsMasterSecret(ssl->arrays->masterSecret, SECRET_LEN, + ssl->arrays->preMasterSecret, ssl->arrays->preMasterSz, + ssl->arrays->clientRandom, ssl->arrays->serverRandom, + IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm); + … + return ret; + + } + \endcode + + \sa PRF + \sadoPRF + \sa p_hash + \sa MakeTlsMasterSecret +*/ +WOLFSSL_API +int wolfSSL_MakeTlsMasterSecret(unsigned char* ms, unsigned int msLen, + const unsigned char* pms, unsigned int pmsLen, + const unsigned char* cr, const unsigned char* sr, + int tls1_2, int hash_type); +/*! + \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 + 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 + and passed through to PRF to hold the final hash. + \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 + held in the arrays structure within the WOLFSSL structure. + \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 + member of the arrays structure within the WOLFSSL structure. + \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){ + int ret; + … + ret = wolfSSL_DeriveTlsKeys(key_data, length, ssl->arrays->masterSecret, + SECRET_LEN, ssl->arrays->clientRandom, + IsAtLeastTLSv1_2(ssl), ssl->specs.mac_algorithm); + … + } + \endcode + + \sa PRF + \sa doPRF + \sa DeriveTlsKeys + \sa IsAtLeastTLSv1_2 +*/ +WOLFSSL_API +int wolfSSL_DeriveTlsKeys(unsigned char* key_data, unsigned int keyLen, + const unsigned char* ms, unsigned int msLen, + const unsigned char* sr, const unsigned char* cr, + 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 + 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 + with either, both, or neither callbacks. + + \return SSL_SUCCESS upon success. + \return GETTIME_ERROR will be returned if gettimeofday() + encountered an error. + \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() + 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. + 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 with either, both, or neither callbacks. + + \return SSL_SUCCESS upon success. + \return GETTIME_ERROR will be returned if gettimeofday() + encountered an error. + \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_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, + Timeval); +/*! + \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; + XFILE fp; + int ret; + bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file()); + 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 + \sa wolfSSL_BIO_free +*/ +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. + + _Example_ + \code + WOLFSSL_BIO* bio; + XFILE fp; + int ret; + bio = wolfSSL_BIO_new(wolfSSL_BIO_s_file()); + 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 + \sa wolfSSL_BIO_free +*/ +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 + 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; + int ret; + // create and set up ssl + ret = wolfSSL_check_private_key(ssl); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +WOLFSSL_API int wolfSSL_check_private_key(const WOLFSSL* ssl); +/*! + \ingroup CertsKeys + + \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) + 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 + 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 + stored in x509 start at idx. + + _Example_ + \code + const WOLFSSL_X509* x509; + int c; + int idx = 0; + STACK_OF(WOLFSSL_ASN1_OBJECT)* sk; + + 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, + int nid, int* c, int* idx); +/*! + \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; + unsigned char buffer[64]; + unsigned int bufferSz; + int ret; + + 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, + const WOLFSSL_EVP_MD* digest, unsigned char* buf, unsigned int* len); +/*! + \ingroup Setup + + \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 + int ret; + // create ssl object and x509 + ret = wolfSSL_use_certificate(ssl, x509); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +WOLFSSL_API int wolfSSL_use_certificate(WOLFSSL* ssl, WOLFSSL_X509* x509); +/*! + \ingroup Setup + + \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; + unsigned char* der; + int derSz; + int ret; + // create ssl object and set DER variables + ret = wolfSSL_use_certificate_ASN1(ssl, der, derSz); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +WOLFSSL_API int wolfSSL_use_certificate_ASN1(WOLFSSL* ssl, unsigned char* der, + int derSz); +/*! + \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 + cases will be negative values. + + \param ssl WOLFSSL structure to set argument in. + \param pkey private key to use. + + _Example_ + \code + WOLFSSL* ssl; + WOLFSSL_EVP_PKEY* pkey; + int ret; + // create ssl object and set up private key + 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 + structure. A DER formatted key buffer is expected. + + \return SSL_SUCCESS On successful setting parsing and + setting the private key. + \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; + unsigned char* pkey; + long pkeySz; + int ret; + // create ssl object and set up private key + ret = wolfSSL_use_PrivateKey_ASN1(1, ssl, pkey, pkeySz); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free + \sa wolfSSL_use_PrivateKey +*/ +WOLFSSL_API int wolfSSL_use_PrivateKey_ASN1(int pri, WOLFSSL* ssl, + unsigned char* der, long derSz); +/*! + \ingroup CertsKeys + + \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 + the private key. + \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; + unsigned char* pkey; + long pkeySz; + int ret; + // create ssl object and set up RSA private key + ret = wolfSSL_use_RSAPrivateKey_ASN1(ssl, pkey, pkeySz); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free + \sa wolfSSL_use_PrivateKey +*/ +WOLFSSL_API int wolfSSL_use_RSAPrivateKey_ASN1(WOLFSSL* ssl, unsigned char* der, + long derSz); +/*! + \ingroup CertsKeys + + \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; + WOLFSSL_DSA* dsa; + // set up dsa + dh = wolfSSL_DSA_dup_DH(dsa); + + // check dh is not null + \endcode + + \sa none +*/ +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 + 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 + return max buffer size needed) + + _Example_ + \code + WOLFSSL_SESSION ssl; + unsigned char* buffer; + size_t bufferSz; + size_t ret; + // complete handshake and get session structure + bufferSz = wolfSSL_SESSION_get_master_secret(ses, NULL, 0); + buffer = malloc(bufferSz); + ret = wolfSSL_SESSION_get_master_secret(ses, buffer, bufferSz); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +WOLFSSL_API int wolfSSL_SESSION_get_master_key(const WOLFSSL_SESSION* ses, + unsigned char* out, int outSz); +/*! + \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; + unsigned char* buffer; + size_t bufferSz; + size_t ret; + // complete handshake and get session structure + bufferSz = wolfSSL_SESSION_get_master_secret_length(ses); + buffer = malloc(bufferSz); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +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 + structure in ctx. + + \return none No return. + + \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; + WOLFSSL_X509_STORE* st; + // setup ctx and st + st = wolfSSL_CTX_set_cert_store(ctx, st); + //use st + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_free +*/ +WOLFSSL_API void wolfSSL_CTX_set_cert_store(WOLFSSL_CTX* ctx, + WOLFSSL_X509_STORE* str); +/*! + \ingroup CertsKeys + + \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 + certificate buffer. + \param x509 pointer that get set to new WOLFSSL_X509 structure created. + + _Example_ + \code + WOLFSSL_BIO* bio; + WOLFSSL_X509* x509; + // load DER into bio + x509 = wolfSSL_d2i_X509_bio(bio, NULL); + Or + 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); +/*! + \ingroup Setup + + \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 + store pointer. + + _Example_ + \code + WOLFSSL_CTX ctx; + WOLFSSL_X509_STORE* st; + // setup ctx + st = wolfSSL_CTX_get_cert_store(ctx); + //use st + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_free + \sa wolfSSL_CTX_set_cert_store +*/ +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 + 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 + been created. + + _Example_ + \code + WOLFSSL_BIO* bio; + int pending; + bio = wolfSSL_BIO_new(); + … + pending = wolfSSL_BIO_ctrl_pending(bio); + \endcode + + \sa wolfSSL_BIO_make_bio_pair + \sa wolfSSL_BIO_new +*/ +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 + 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 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 + buffer size needed) + + _Example_ + \code + WOLFSSL ssl; + unsigned char* buffer; + size_t bufferSz; + size_t ret; + bufferSz = wolfSSL_get_server_random(ssl, NULL, 0); + buffer = malloc(bufferSz); + ret = wolfSSL_get_server_random(ssl, buffer, bufferSz); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +WOLFSSL_API size_t wolfSSL_get_server_random(const WOLFSSL *ssl, + unsigned char *out, size_t outlen); +/*! + \ingroup Setup + + \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 + 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 + buffer size needed) + + _Example_ + \code + WOLFSSL ssl; + unsigned char* buffer; + size_t bufferSz; + size_t ret; + bufferSz = wolfSSL_get_client_random(ssl, NULL, 0); + buffer = malloc(bufferSz); + ret = wolfSSL_get_client_random(ssl, buffer, bufferSz); + // check ret value + \endcode + + \sa wolfSSL_new + \sa wolfSSL_free +*/ +WOLFSSL_API size_t wolfSSL_get_client_random(const WOLFSSL* ssl, + unsigned char* out, size_t outSz); +/*! + \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; + Pem_password_cb cb; + // setup ctx + cb = wolfSSL_CTX_get_default_passwd_cb(ctx); + //use cb + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_free +*/ +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 + 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; + void* data; + // setup ctx + data = wolfSSL_CTX_get_default_passwd_cb(ctx); + //use data + \endcode + + \sa wolfSSL_CTX_new + \sa wolfSSL_CTX_free +*/ +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 + cases and friendly name for human readability. + + \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; + WOLFSSL_X509* x509; + // setup bio + 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 + (WOLFSSL_BIO *bp, WOLFSSL_X509 **x, pem_password_cb *cb, void *u); +/*! + \ingroup CertsKeys + + \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 + 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 + wolfSSL_CTX_new(). + \param dh a pointer to a WOLFSSL_DH structure. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); + WOLFSSL_DH* dh; + … + 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*); +/*! + \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 Null if failed to parse PEM buffer. + + \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; + WOLFSSL_DSA* dsa; + // setup bio + dsa = wolfSSL_PEM_read_bio_DSAparams(bio, NULL, NULL, NULL); + + // check dsa is not NULL and then use dsa + \endcode + + \sa none +*/ +WOLFSSL_API WOLFSSL_DSA *wolfSSL_PEM_read_bio_DSAparams(WOLFSSL_BIO *bp, + WOLFSSL_DSA **x, pem_password_cb *cb, void *u); +/*! + \ingroup Debug + + \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; + ... + 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); +/*! + \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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + ... + wolfSSL_connect(ssl); + STACK_OF(WOLFSSL_X509)* chain = wolfSSL_get_peer_cert_chain(ssl); + ifchain){ + // 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 +*/ +WOLFSSL_API WOLF_STACK_OF(WOLFSSL_X509)* wolfSSL_get_peer_cert_chain(const WOLFSSL*); +/*! + \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 +*/ +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 + 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)){ + // The success case + } + \endcode + + \sa wolfSSL_get_jobject +*/ +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 + 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 ); + WOLFSSL* ssl = wolfSSL(ctx); + ... + void* jobject = wolfSSL_get_jobject(ssl); + + if(jobject != NULL){ + // Success case + } + \endcode + + \sa wolfSSL_set_jobject +*/ +WOLFSSL_API void* wolfSSL_get_jobject(WOLFSSL* ssl); +/*! + \ingroup Setup + + \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, + const void *buf, size_t len, WOLFSSL *ssl, void *arg) + … + 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); +/*! + \ingroup Setup + + \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, + const void *buf, size_t len, WOLFSSL *ssl, void *arg) + … + WOLFSSL* ssl; + ret = wolfSSL_set_msg_callback(ssl, 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 + 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, + DYNAMIC_TYPE_X509); + … + int x509NextAltName = wolfSSL_X509_get_next_altname(x509); + if(x509NextAltName == NULL){ + //There isn’t another alt name + } + \endcode + + \sa wolfSSL_X509_get_issuer_name + \sa wolfSSL_X509_get_subject_name +*/ +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 + returns the notBefore member of the x509 struct. + + \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, + DYNAMIC_TYPE_X509) ; + … + byte* notAfter = wolfSSL_X509_notAfter(x509); + if(notAfter == NULL){ + //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. +wolfSSL takes a different approach to certificate verification than OpenSSL does. The default policy for the client is to verify the server, this means that if you don't load CAs to verify the server you'll get a connect error, unable to verify (-155). It you want to mimic OpenSSL behavior of having SSL_connect succeed even if verifying the server fails and reducing security you can do this by calling: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0); before calling SSL_new(); Though it's not recommended. + + \return SSL_SUCCESS If successful. + \return SSL_FATAL_ERROR will be returned if an error occurred. To get a more detailed error code, call wolfSSL_get_error(). + + \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). + + _Example_ + \code + int ret = 0; + int err = 0; + WOLFSSL* ssl; + char buffer[80]; + ... + ret = wolfSSL_connect(ssl); + if (ret != SSL_SUCCESS) { + err = wolfSSL_get_error(ssl, ret); + printf(“error = %d, %s\n”, err, wolfSSL_ERR_error_string(err, buffer)); + } + \endcode + + \sa wolfSSL_get_error + \sa wolfSSL_accept +*/ +int wolfSSL_connect(WOLFSSL* ssl); diff --git a/doc/dox_comments/header_files/tfm.h b/doc/dox_comments/header_files/tfm.h new file mode 100644 index 000000000..6b99746ca --- /dev/null +++ b/doc/dox_comments/header_files/tfm.h @@ -0,0 +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 + 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 + 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 new file mode 100644 index 000000000..21efafa1c --- /dev/null +++ b/doc/dox_comments/header_files/types.h @@ -0,0 +1,169 @@ +/*! + \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 + functions in place of the standard C memory functions. + 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 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 + 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 pointer Return a pointer to allocated memory on success + \return NULL on failure + + \param s size of memory to allocate + \param h (used by custom XMALLOC function) pointer to the heap to use + \param t memory allocation types for user hints. See enum in types.h + + _Example_ + \code + int* 10 ints = XMALLOC(10 * sizeof(int), NULL, DYNAMIC_TYPE_TMP_BUFFER); + + if ( ints == NULL) { + // error allocating space + return MEMORY_E; + } + \endcode + + \sa wolfSSL_Malloc + \sa wolfSSL_Realloc + \sa wolfSSL_Free + \sa wolfSSL_SetAllocators +*/ + 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 + free functions in place of the standard C memory functions. + 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 + 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 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 Return a pointer to allocated memory on success + \return NULL on failure + + \param p pointer to the address to reallocate + \param n size of memory to allocate + \param h (used by custom XREALLOC function) pointer to the heap to use + \param t memory allocation types for user hints. See enum in types.h + + _Example_ + \code + none + \endcode + + \sa wolfSSL_Malloc + \sa wolfSSL_Realloc + \sa wolfSSL_Free + \sa wolfSSL_SetAllocators +*/ + 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 + free functions in place of the standard C memory functions. + 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 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 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 + + _Example_ + \code + int* 10 ints = XMALLOC(10 * sizeof(int), NULL, DYNAMIC_TYPE_TMP_BUFFER); + + if ( ints == NULL) { + // error allocating space + return MEMORY_E; + } + \endcode + + \sa wolfSSL_Malloc + \sa wolfSSL_Realloc + \sa wolfSSL_Free + \sa wolfSSL_SetAllocators +*/ + 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 + 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 new file mode 100644 index 000000000..e11711181 --- /dev/null +++ b/doc/dox_comments/header_files/wc_encrypt.h @@ -0,0 +1,208 @@ +/*! + \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 + 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 + is null during AesSetIV + \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 + text of the decrypted message + \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 + 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, + AES_BLOCK_SIZE, iv)) != 0 ) { + // Decrypt Error + } + \endcode + + \sa wc_AesSetKey + \sa wc_AesSetIV + \sa wc_AesCbcEncrypt + \sa wc_AesCbcDecrypt +*/ +WOLFSSL_API int wc_AesCbcDecryptWithKey(byte* out, const byte* in, word32 inSz, + const byte* key, word32 keySz, + const byte* iv); +/*! + \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 + 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 + 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 + decryption + \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; + byte key[] = { // initialize with 8 byte key }; + byte iv[] = { // initialize with 8 byte iv }; + + byte cipher[] = { // initialize with ciphertext }; + byte decoded[sizeof(cipher)]; + + 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, + const byte* in, word32 sz, + const byte* key, const byte* iv); +/*! + \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 + 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 + Des structure. + \return <0 Returned on any error during encryption. + + \param out Final encrypted data + \param in Data to be encrypted, must be padded to Des block size. + \param sz Size of input buffer. + \param key Pointer to the key to use for encryption. + \param iv Initialization vector + + _Example_ + \code + byte key[] = { // initialize with 8 byte key }; + byte iv[] = { // initialize with 8 byte iv }; + 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 +*/ +WOLFSSL_API int wc_Des_CbcEncryptWithKey(byte* out, + const byte* in, word32 sz, + const byte* key, const byte* iv); +/*! + \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 + 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 + 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 }; + byte iv[] = { // initialize with 8 byte iv }; + + byte in[] = { // Initialize with plaintext }; + 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 +*/ +WOLFSSL_API int wc_Des3_CbcEncryptWithKey(byte* out, + const byte* in, word32 sz, + const byte* key, const byte* iv); +/*! + \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 + 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 + 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 + for decryption + \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; + byte key[] = { // initialize with 24 byte key }; + byte iv[] = { // initialize with 8 byte iv }; + + byte cipher[] = { // initialize with ciphertext }; + byte decoded[sizeof(cipher)]; + + 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, + const byte* in, word32 sz, + const byte* key, const byte* iv); diff --git a/doc/dox_comments/header_files/wc_port.h b/doc/dox_comments/header_files/wc_port.h new file mode 100644 index 000000000..2a187cf72 --- /dev/null +++ b/doc/dox_comments/header_files/wc_port.h @@ -0,0 +1,21 @@ +/*! + \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 + ... + if (wolfCrypt_Cleanup() != 0) { + 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 new file mode 100644 index 000000000..68537abbd --- /dev/null +++ b/doc/dox_comments/header_files/wolfio.h @@ -0,0 +1,526 @@ +/*! + \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 + 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” + message if the last error was SOCKET_ECONNRESET. + \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” + messag if the last error was SOCKET_ECONNREFUSED. + \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 + 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 + the ctx is a socket descriptor pointer. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + char* buf; + int sz; + void* ctx; + int bytesRead = EmbedReceive(ssl, buf, sz, ctx); + if(bytesRead <= 0){ + // There were no bytes read. Failure case. + } + \endcode + + \sa wolfSSL_dtls_get_current_timeout + \sa TranslateReturnCode + \sa RECV_FUNCTION +*/ + 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 + if the last error was SOCKET_EWOULDBLOCK or SOCKET_EAGAIN. + \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 + if the last error was SOCKET_EINTR. + \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 + 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; + int dSent = EmbedSend(ssl, buf, sz, ctx); + if(dSent <= 0){ + // No byes sent. Failure case. + } + \endcode + + \sa TranslateReturnCode + \sa SEND_FUNCTION + \sa LastError + \sa InitSSL_Ctx + \sa LastError +*/ + 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 + was successful. + \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 ); + WOLFSSL* ssl = WOLFSSL_new(ctx); + char* buf; + int sz = sizeof(buf)/sizeof(char); + (void*)ctx; + … + int nb = EmbedReceiveFrom(ssl, buf, sz, ctx); + if(nb > 0){ + // nb is the number of bytes written and is positive + } + \endcode + + \sa TranslateReturnCode + \sa RECVFROM_FUNCTION + \sa Setsockopt +*/ + 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 + if the last error was either SOCKET_EWOULDBLOCK or SOCKET_EAGAIN error. + \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 + if the last error was SOCKET_EINTR. + \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 + 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 + is a WOLFSSL_DTLS_CTX sructure. + + _Example_ + \code + WOLFSSL* ssl; + … + char* buf; + int sz; + void* ctx; + + int sEmbed = EmbedSendto(ssl, buf, sz, ctx); + if(sEmbed <= 0){ + // No bytes sent. Failure case. + } + \endcode + + \sa LastError + \sa EmbedSend + \sa EmbedReceive +*/ + 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 + into the buffer. + \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 + 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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + byte buffer[BUFFER_SIZE]; + int sz = sizeof(buffer)/sizeof(byte); + void* ctx; + … + int ret = EmbedGenerateCookie(ssl, buffer, sz, ctx); + + if(ret > 0){ + // EmbedGenerateCookie code block for success + } + \endcode + + \sa wc_ShaHash + \sa EmbedGenerateCookie + \sa XMEMCPY + \sa XMEMSET +*/ + WOLFSSL_API int EmbedGenerateCookie(WOLFSSL* ssl, unsigned char* buf, + int sz, void*); +/*! + \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; + byte* resp; // Response buffer. + … + 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 + 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 + shown above in the Synopsis section. + + _Example_ + \code + WOLFSSL_CTX* ctx = 0; + // Receive callback prototype + int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx); + // Register the custom receive callback with wolfSSL + wolfSSL_SetIORecv(ctx, MyEmbedReceive); + int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx) + { + // custom EmbedReceive function + } + \endcode + + \sa wolfSSL_SetIOSend + \sa wolfSSL_SetIOReadCtx + \sa wolfSSL_SetIOWriteCtx +*/ +WOLFSSL_API void wolfSSL_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 + 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 + (ssl) receive callback function. + + _Example_ + \code + int sockfd; + WOLFSSL* ssl = 0; + ... + // Manually setting the socket fd as the receive CTX, for example + wolfSSL_SetIOReadCtx(ssl, &sockfd); + ... + \endcode + + \sa wolfSSL_SetIORecv + \sa wolfSSL_SetIOSend + \sa wolfSSL_SetIOWriteCtx +*/ +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 + 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 + (ssl) send callback function. + + _Example_ + \code + int sockfd; + WOLFSSL* ssl = 0; + ... + // Manually setting the socket fd as the send CTX, for example + wolfSSL_SetIOSendCtx(ssl, &sockfd); + ... + \endcode + + \sa wolfSSL_SetIORecv + \sa wolfSSL_SetIOSend + \sa wolfSSL_SetIOReadCtx +*/ +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 + 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); + void* ioRead; + ... + ioRead = wolfSSL_GetIOReadCtx(ssl); + if(ioRead == NULL){ + // Failure case. The ssl object was NULL. + } + \endcode + + \sa wolfSSL_GetIOWriteCtx + \sa wolfSSL_SetIOReadFlags + \sa wolfSSL_SetIOWriteCtx + \sa wolfSSL_SetIOReadCtx + \sa wolfSSL_SetIOSend +*/ +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 + 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; + void* ioWrite; + ... + ioWrite = wolfSSL_GetIOWriteCtx(ssl); + if(ioWrite == NULL){ + // The funciton returned NULL. + } + \endcode + + \sa wolfSSL_GetIOReadCtx + \sa wolfSSL_SetIOWriteCtx + \sa wolfSSL_SetIOReadCtx + \sa wolfSSL_SetIOSend +*/ +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_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 + session (ssl). + + _Example_ + \code + WOLFSSL* ssl = 0; + ... + // Manually setting recv flags to 0 + wolfSSL_SetIOReadFlags(ssl, 0); + ... + \endcode + + \sa wolfSSL_SetIORecv + \sa wolfSSL_SetIOSend + \sa wolfSSL_SetIOReadCtx +*/ +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_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; + ... + // Manually setting send flags to 0 + wolfSSL_SetIOSendFlags(ssl, 0); + ... + \endcode + + \sa wolfSSL_SetIORecv + \sa wolfSSL_SetIOSend + \sa wolfSSL_SetIOReadCtx +*/ +WOLFSSL_API void wolfSSL_SetIOWriteFlags(WOLFSSL* ssl, int flags); +/*! + \ingroup IO + + \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 + nxSocket member of the nxCTX structure. + \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){ + wolfSSL_SetIO_NetX(ssl, nxSocket, waitOption); + } else { + // You need to pass in good parameters. + } + \endcode + + \sa set_fd + \sa NetX_Send + \sa NetX_Receive +*/ + 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 + 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 + of CallbackGenCookie. + + _Example_ + \code + WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); + WOLFSSL* ssl = wolfSSL_new(ctx); + … + int SetGenCookieCB(WOLFSSL* ssl, unsigned char* buf, int sz, void* ctx){ + // Callback function body. + } + … + wolfSSL_CTX_SetGenCookie(ssl->ctx, SetGenCookieCB); + \endcode + + \sa CallbackGenCookie +*/ + WOLFSSL_API void wolfSSL_CTX_SetGenCookie(WOLFSSL_CTX*, CallbackGenCookie); +/*! + \ingroup Setup + + \brief This function returns the IOCB_CookieCtx member of the + WOLFSSL structure. + + \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 ); + WOLFSSL* ssl = wolfSSL_new(ctx); + void* cookie; + ... + cookie = wolfSSL_GetCookieCtx(ssl); + if(cookie != NULL){ + // You have the cookie + } + \endcode + + \sa wolfSSL_SetCookieCtx + \sa wolfSSL_CTX_SetGenCookie +*/ + WOLFSSL_API void* wolfSSL_GetCookieCtx(WOLFSSL* ssl); diff --git a/doc/formats/html/Doxyfile b/doc/formats/html/Doxyfile new file mode 100644 index 000000000..a411fc11c --- /dev/null +++ b/doc/formats/html/Doxyfile @@ -0,0 +1,2471 @@ +# Doxyfile 1.8.14 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all text +# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv +# built into libc) for the transcoding. See +# https://www.gnu.org/software/libiconv/ for the list of possible encodings. +# The default value is: UTF-8. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. + +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 +# control system is used. + +PROJECT_NUMBER = + +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify a logo or an icon that is included +# in the documentation. The maximum height of the logo should not exceed 55 +# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy +# the logo to the output directory. + +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 +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. + +OUTPUT_DIRECTORY = + +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- +# directories (in 2 levels) under the output directory of each output format and +# will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. +# The default value is: NO. + +CREATE_SUBDIRS = NO + +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. +# The default value is: English. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. +# The default value is: YES. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. + +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# doxygen will generate a detailed section even if there is only a brief +# description. +# The default value is: NO. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. +# The default value is: NO. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. + +FULL_PATH_NAMES = YES + +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. + +JAVADOC_AUTOBRIEF = NO + +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# page for each member. If set to NO, the documentation of a member will be part +# of the file/class/namespace that contains it. +# The default value is: NO. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. + +TAB_SIZE = 4 + +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:\n" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". You can put \n's in the value part of an alias to insert +# newlines. + +ALIASES = + +# This tag can be used to specify a number of word-keyword mappings (TCL only). +# A mapping has the form "name=value". For example adding "class=itcl::class" +# will allow you to use the command class in the itcl::class meaning. + +TCL_SUBST = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_FOR_C = YES + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, Javascript, +# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: +# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: +# Fortran. In the later case the parser tries to guess whether the code is fixed +# or free formatted code, this is the default for Fortran type files), VHDL. For +# instance to make doxygen treat .inc files as Fortran files (default is PHP), +# and .f files as C (default is Fortran), use: inc=Fortran f=C. +# +# Note: For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See http://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. + +MARKDOWN_SUPPORT = YES + +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 0. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 0 + +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. + +AUTOLINK_SUPPORT = YES + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. +# The default value is: NO. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. +# The default value is: NO. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. +# The default value is: NO. + +DISTRIBUTE_GROUP_DOC = NO + +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. + +SUBGROUPING = YES + +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. + +TYPEDEF_HIDES_STRUCT = NO + +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. + +EXTRACT_ALL = NO + +# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will +# be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be +# included in the documentation. +# The default value is: NO. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO, +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. + +EXTRACT_LOCAL_CLASSES = NO + +# This flag is only useful for Objective-C code. If set to YES, local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO, only methods in the interface are +# included. +# The default value is: NO. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO, these classes will be included in the various overviews. This option +# has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# (class|struct|union) declarations. If set to NO, these declarations will be +# included in the documentation. +# The default value is: NO. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO, these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file +# names in lower-case letters. If set to YES, upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. +# The default value is: system dependent. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES, the +# scope will be hidden. +# The default value is: NO. + +HIDE_SCOPE_NAMES = NO + +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO + +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. + +SHOW_INCLUDE_FILES = YES + +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. +# The default value is: YES. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. + +SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. + +SORT_BY_SCOPE_NAME = NO + +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo +# list. This list is created by putting \todo commands in the documentation. +# The default value is: YES. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test +# list. This list is created by putting \test commands in the documentation. +# The default value is: YES. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if ... \endif and \cond +# ... \endcond blocks. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES, the +# list will mention the files that were used to generate the documentation. +# The default value is: YES. + +SHOW_USED_FILES = NO + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. + +LAYOUT_FILE = + +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. See also \cite for info how to create references. + +CITE_BIB_FILES = + +#--------------------------------------------------------------------------- +# Configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. + +QUIET = YES + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. + +WARNINGS = YES + +# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. + +WARN_IF_UNDOCUMENTED = NO + +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some parameters +# in a documented function, or documenting parameters that don't exist or using +# markup commands wrongly. +# The default value is: YES. + +WARN_IF_DOC_ERROR = NO + +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO, doxygen will only warn about wrong or incomplete +# parameter documentation, but not about the absence of documentation. +# The default value is: NO. + +WARN_NO_PARAMDOC = NO + +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. +# The default value is: NO. + +WARN_AS_ERROR = NO + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# The default value is: $file:$line: $text. + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). + +WARN_LOGFILE = doxygen_warnings + +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING +# Note: If this tag is empty the current directory is searched. + +INPUT = ../ ./mainpage.dox + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: https://www.gnu.org/software/libiconv/) for the list of +# possible encodings. +# The default value is: UTF-8. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# read by doxygen. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, +# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf. + +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.idl \ + *.ddl \ + *.odl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.cs \ + *.d \ + *.php \ + *.php4 \ + *.php5 \ + *.phtml \ + *.inc \ + *.m \ + *.markdown \ + *.md \ + *.mm \ + *.dox \ + *.py \ + *.pyw \ + *.f90 \ + *.f95 \ + *.f03 \ + *.f08 \ + *.f \ + *.for \ + *.tcl \ + *.vhd \ + *.vhdl \ + *.ucf \ + *.qsf + +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. + +EXCLUDE = ./build + +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. +# The default value is: NO. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. + +EXAMPLE_PATTERNS = * + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command: +# +# +# +# where is the value of the INPUT_FILTER tag, and is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. + +FILTER_SOURCE_FILES = NO + +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = + +#--------------------------------------------------------------------------- +# Configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. + +SOURCE_BROWSER = NO + +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# function all documented functions referencing it will be listed. +# The default value is: NO. + +REFERENCED_BY_RELATION = NO + +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. + +REFERENCES_RELATION = NO + +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. + +REFERENCES_LINK_SOURCE = YES + +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see https://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# Configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. + +ALPHABETICAL_INDEX = YES + +# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in +# which the alphabetical index list will be split. +# Minimum value: 1, maximum value: 20, default value: 5. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all classes will +# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag +# can be used to specify a prefix (or a list of prefixes) that should be ignored +# while generating the index headers. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output +# The default value is: YES. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a +# standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_HEADER = header.html + +# 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 +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FOOTER = footer.html + +# 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 +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_STYLESHEET = + +# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# cascading style sheets that are included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefore more robust against future updates. +# Doxygen will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). For an example see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_STYLESHEET = html_changes/customdoxygen.css + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the style sheet and background images according to +# this color. Hue is specified as an angle on a colorwheel, see +# https://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use grayscales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting this +# to YES can help to show when doxygen was last run and thus if the +# documentation is up to date. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_TIMESTAMP = NO + + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: https://developer.apple.com/tools/xcode/), introduced with +# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a +# Makefile in the HTML output directory. Running make will produce the docset in +# that directory and running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See https://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_DOCSET = NO + +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on +# Windows. +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_HTMLHELP = NO + +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be +# written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_FILE = + +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler (hhc.exe). If non-empty, +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +HHC_LOCATION = + +# The GENERATE_CHI flag controls if a separate .chi index file is generated +# (YES) or that it should be included in the master .chm file (NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +GENERATE_CHI = NO + +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_INDEX_ENCODING = + +# The BINARY_TOC flag controls whether a binary table of contents is generated +# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: http://doc.qt.io/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: http://doc.qt.io/qt-4.8/qthelpproject.html#virtual-folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_VIRTUAL_FOLDER = doc + +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://doc.qt.io/qt-4.8/qthelpproject.html#custom-filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: http://doc.qt.io/qt-4.8/qthelpproject.html#custom-filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# http://doc.qt.io/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_SECT_FILTER_ATTRS = + +# The QHG_LOCATION tag can be used to specify the location of Qt's +# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the +# generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +DISABLE_INDEX = NO + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can +# further fine-tune the look of the index. As an example, the default style +# sheet generated by doxygen has an example that shows how to put an image at +# the root of the tree instead of the PROJECT_NAME. Since the tree basically has +# the same information as the tab index, you could consider setting +# DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_TREEVIEW = NO + +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. + +ENUM_VALUES_PER_LINE = 4 + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. + +TREEVIEW_WIDTH = 250 + +# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANSPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are not +# supported properly for IE 6.0, but are supported on all modern browsers. +# +# Note that when changing this option you need to delete any form_*.png files in +# the HTML output directory before the changes have effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_TRANSPARENT = YES + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# https://www.mathjax.org) which uses client side Javascript for the rendering +# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +USE_MATHJAX = NO + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. See the MathJax site (see: +# http://docs.mathjax.org/en/latest/output.html) for more details. +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility), NativeMML (i.e. MathML) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from https://www.mathjax.org before deployment. +# The default value is: http://cdn.mathjax.org/mathjax/latest. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use + S +# (what the is depends on the OS and browser, but it is typically +# , /