feedc0de/wolfssl
1
0
Fork 0
forked from wolfSSL/wolfssl
Code Pull Requests Activity

1. Trailing whitespace removal

Browse Source
This commit is contained in:
abrahamsonn
2018-06-27 16:22:12 -06:00
parent ac3eb470f9
commit 765d97ae01
55 changed files with 6675 additions and 6675 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
doc/README_DOXYGEN
View File

@ -5,11 +5,11 @@ wolfSSL with Doxygen 1.8.13
cmake cmake
make make
git git
latex-see below (With pdflatex included. However the pdflatex dependency can be removed by 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 setting USE_PDFLATEX to NO in the file "Doxyfile" located at
doc/formats/pdf/Doxyfile ) doc/formats/pdf/Doxyfile )
The following texlive packages were installed when creating this The following texlive packages were installed when creating this
documentation on Linux Mint: documentation on Linux Mint:
sudo apt install texlive sudo apt install texlive
sudo apt install texlive-latex-extra sudo apt install texlive-latex-extra
@ -24,7 +24,7 @@ additional dependencies will need to be met:
If you are looking to just generate the html documentation and not interested in 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 how to add your own just run one of the following commands from the main wolfssl
directory: directory:
make dox (this option will make both html and pdf documentation) make dox (this option will make both html and pdf documentation)
make dox-html (only html documentation) make dox-html (only html documentation)
make dox-pdf (only pdf documentation) make dox-pdf (only pdf documentation)
@ -33,32 +33,32 @@ If it is the first time running one of the above commands the command will take
some time to run. This is because the doxygen repository must be clones and then 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. built along with the time taken to make the documentation.
Once documentation generation has completed to open the html use a browser to 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 open doc/html/index.html. To open the generated pdf looking for
refman.pdf located and doc/refman.pdf. refman.pdf located and doc/refman.pdf.
---- Configure ---- ---- Configure ----
Doxygen uses a file called "Doxyfile" to hold all its values for configuration. Doxygen uses a file called "Doxyfile" to hold all its values for configuration.
If needed, to generate a fresh Doxfile run the command If needed, to generate a fresh Doxfile run the command
doxygen -g doxygen -g
Once a Doxyfile is generate there are a few options to keep in mind. Once a Doxyfile is generate there are a few options to keep in mind.
Below are some the the settings that are currently used: Below are some the the settings that are currently used:
EXTRACT_ALL EXTRACT_ALL
- this option determines if all API are extracted or just API that is documented. - this option determines if all API are extracted or just API that is documented.
OPTIMIZE_OUTPUT_FOR_C OPTIMIZE_OUTPUT_FOR_C
- changes the look and naming schemes used in generated documentation. - changes the look and naming schemes used in generated documentation.
RECURSIVE RECURSIVE
- allows doxygen to search subdirectories in a library for documenting. - allows doxygen to search subdirectories in a library for documenting.
GENERATE_LATEX GENERATE_LATEX
- tells doxygen whether or not to generate LATEX documentation. The Latex - tells doxygen whether or not to generate LATEX documentation. The Latex
@ -67,17 +67,17 @@ Below are some the the settings that are currently used:
ENABLE_PREPROCESSING ENABLE_PREPROCESSING
- tells doxygen whether or not to ignore C/C++ preprocessors directives i.e #ifdef, #ifndef - tells doxygen whether or not to ignore C/C++ preprocessors directives i.e #ifdef, #ifndef
EXCLUDE EXCLUDE
- allows the user to specify files or directories to ignore when documenting. - allows the user to specify files or directories to ignore when documenting.
HTML_EXTRA_STYLESHEET HTML_EXTRA_STYLESHEET
-allows the user to specify their own css style sheet to use for the doxygen html. -allows the user to specify their own css style sheet to use for the doxygen html.
SHOW_USED_FILES and SHOW_FILES SHOW_USED_FILES and SHOW_FILES
- when using groups it is important to keep these options set to yes otherwise - 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 functions with documentation that are not part of a group may fail to be included
in the generated documentation. in the generated documentation.
@ -85,10 +85,10 @@ Below are some the the settings that are currently used:
---- Embedding Documentation ---- ---- Embedding Documentation ----
Doxygen API documentation should be placed in the doc/dox_comments/ Doxygen API documentation should be placed in the doc/dox_comments/
directory. The documentation should be stored in a file in this directory with the directory. The documentation should be stored in a file in this directory with the
same name of the file in which the API resides in the wolfssl repository. C code 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 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 file is being documented for the first time be sure to add the to the top of the
original file: original file:
/*! /*!
@ -100,7 +100,7 @@ When specifying a specific file with the \file command be sure to include part o
the file's path so that it is a unique name. This allows for linking to files even 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. when multiple files share the same name.
To ensure that doxygen documents a specific API in to a desired module be sure To ensure that doxygen documents a specific API in to a desired module be sure
to include that module's name in the \ingroup. The current modules to choose from to include that module's name in the \ingroup. The current modules to choose from
are as follows but new group can be made: are as follows but new group can be made:
@ -139,7 +139,7 @@ are as follows but new group can be made:
\ingroup IO \ingroup IO
\ingroup Debug \ingroup Debug
If one of the above modules/ groups does not fit a desired function then a new If one of the above modules/ groups does not fit a desired function then a new
group will need to be created. To do this include add a new group definition 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 to the doxygen_groups.h file located at documentation/formats/pdf/doxygen_groups.h
@ -148,22 +148,22 @@ to the doxygen_groups.h file located at documentation/formats/pdf/doxygen_groups
*/ */
The general outline when documenting within the wolfssl library in doxygen should The general outline when documenting within the wolfssl library in doxygen should
look like as follows: look like as follows:
/*! /*!
\ingroup //if API should be in a separate module \ingroup //if API should be in a separate module
\brief <description of API> \brief <description of API>
\return <name of return> <description> // each return will need \return. \return <name of return> <description> // each return will need \return.
\param <name of param> <description> // stands for parameter, each parameter will need \param. \param <name of param> <description> // stands for parameter, each parameter will need \param.
_Example_ _Example_
\code \code
// any example code here // any example code here
\endcode \endcode
\sa // stands for see also. Each API reference here should begin with \sa \sa // stands for see also. Each API reference here should begin with \sa
\sa <Function> \sa <Function>
\sa <Function> \sa <Function>
@ -174,5 +174,5 @@ When adding new documentation be sure to keep the sections, \ingroup, \brief,
doxygen attempts to generate documentation the sections do not overlap each other 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). 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 Once finished creating new documentation it is highly recommended to generate new
html and pdf to ensure no errors were introduced that prevent documentation html and pdf to ensure no errors were introduced that prevent documentation
generation and that the documentation shows up correctly. generation and that the documentation shows up correctly.

8
doc/check_api.sh
View File

@ -3,7 +3,7 @@
ls ./dox_comments/header_files/ | ls ./dox_comments/header_files/ |
while read h_file; do while read h_file; do
grep -P -h -z -o 'WOLFSSL_API(\n|\s|[^;])*;' ./dox_comments/header_files/$h_file | grep -P -h -z -o 'WOLFSSL_API(\n|\s|[^;])*;' ./dox_comments/header_files/$h_file |
tr '\n' ' ' | tr '\n' ' ' |
sed 's/\\n//g' | sed 's/\\n//g' |
sed 's/ \+/ /g' | sed 's/ \+/ /g' |
sed 's/\x00/\n/g' > dox_api.txt sed 's/\x00/\n/g' > dox_api.txt
@ -13,11 +13,11 @@ while read h_file; do
echo "Checking: $h_file_path" echo "Checking: $h_file_path"
grep -P -h -z -o 'WOLFSSL_API(\n|\s|[^;])*;' "$h_file_path" | grep -P -h -z -o 'WOLFSSL_API(\n|\s|[^;])*;' "$h_file_path" |
sed 's/#.*/ /g' | sed 's/#.*/ /g' |
tr '\n' ' ' | tr '\n' ' ' |
sed 's/\\n//g' | sed 's/\\n//g' |
sed 's/ \+/ /g' | sed 's/ \+/ /g' |
sed 's/\x00/\n/g' > wolf_api.txt sed 's/\x00/\n/g' > wolf_api.txt
api_count="$(wc -l < dox_api.txt)" api_count="$(wc -l < dox_api.txt)"
match_count="$(grep -Ff dox_api.txt wolf_api.txt | wc -l)" match_count="$(grep -Ff dox_api.txt wolf_api.txt | wc -l)"
if [ "$api_count" != "$match_count" ]; then if [ "$api_count" != "$match_count" ]; then
@ -36,7 +36,7 @@ while read h_file; do
fi fi
done || exit 1 done || exit 1
echo 'Next...\n' echo 'Next...\n'
done || exit 1 done || exit 1
rm dox_api.txt rm dox_api.txt

352
doc/dox_comments/header_files/aes.h
View File

@ -1,30 +1,30 @@
/*! /*!
\ingroup AES \ingroup AES
\brief This function initializes an AES structure by setting the key and \brief This function initializes an AES structure by setting the key and
then setting the initialization vector. then setting the initialization vector.
\return 0 On successfully setting key and initialization vector. \return 0 On successfully setting key and initialization vector.
\return BAD_FUNC_ARG Returned if key length is invalid. \return BAD_FUNC_ARG Returned if key length is invalid.
\param aes pointer to the AES structure to modify \param aes pointer to the AES structure to modify
\param key 16, 24, or 32 byte secret key for encryption and decryption \param key 16, 24, or 32 byte secret key for encryption and decryption
\param len length of the key passed in \param len length of the key passed in
\param iv pointer to the initialization vector used to initialize the key \param iv pointer to the initialization vector used to initialize the key
\param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or \param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or
AES_DECRYPTION to decrypt. AES_DECRYPTION to decrypt.
_Example_ _Example_
\code \code
Aes enc; Aes enc;
int ret = 0; int ret = 0;
byte key[] = { some 16, 24 or 32 byte key }; byte key[] = { some 16, 24 or 32 byte key };
byte iv[] = { some 16 byte iv }; byte iv[] = { some 16 byte iv };
if (ret = wc_AesSetKey(&enc, key, AES_BLOCK_SIZE, iv, if (ret = wc_AesSetKey(&enc, key, AES_BLOCK_SIZE, iv,
AES_ENCRYPTION) != 0) { AES_ENCRYPTION) != 0) {
// failed to set aes key // failed to set aes key
} }
\endcode \endcode
\sa wc_AesSetKeyDirect \sa wc_AesSetKeyDirect
\sa wc_AesSetIV \sa wc_AesSetIV
*/ */
@ -33,18 +33,18 @@ WOLFSSL_API int wc_AesSetKey(Aes* aes, const byte* key, word32 len,
/*! /*!
\ingroup AES \ingroup AES
\brief This function sets the initialization vector for a \brief This function sets the initialization vector for a
particular AES object. The AES object should be initialized before particular AES object. The AES object should be initialized before
calling this function. calling this function.
\return 0 On successfully setting initialization vector. \return 0 On successfully setting initialization vector.
\return BAD_FUNC_ARG Returned if AES pointer is NULL. \return BAD_FUNC_ARG Returned if AES pointer is NULL.
\param aes pointer to the AES structure on which to set the \param aes pointer to the AES structure on which to set the
initialization vector initialization vector
\param iv initialization vector used to initialize the AES structure. \param iv initialization vector used to initialize the AES structure.
If the value is NULL, the default action initializes the iv to 0. If the value is NULL, the default action initializes the iv to 0.
_Example_ _Example_
\code \code
Aes enc; Aes enc;
@ -54,7 +54,7 @@ WOLFSSL_API int wc_AesSetKey(Aes* aes, const byte* key, word32 len,
// failed to set aes iv // failed to set aes iv
} }
\endcode \endcode
\sa wc_AesSetKeyDirect \sa wc_AesSetKeyDirect
\sa wc_AesSetKey \sa wc_AesSetKey
*/ */
@ -62,27 +62,27 @@ WOLFSSL_API int wc_AesSetIV(Aes* aes, const byte* iv);
/*! /*!
\ingroup AES \ingroup AES
\brief Encrypts a plaintext message from the input buffer in, and places \brief Encrypts a plaintext message from the input buffer in, and places
the resulting cipher text in the output buffer out using cipher block the resulting cipher text in the output buffer out using cipher block
chaining with AES. This function requires that the AES object has been chaining with AES. This function requires that the AES object has been
initialized by calling AesSetKey before a message is able to be encrypted. initialized by calling AesSetKey before a message is able to be encrypted.
This function assumes that the input message is AES block length aligned. This function assumes that the input message is AES block length aligned.
PKCS#7 style padding should be added beforehand. This differs from the 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 OpenSSL AES-CBC methods which add the padding for you. To make the wolfSSL
function and equivalent OpenSSL functions interoperate, one should specify function and equivalent OpenSSL functions interoperate, one should specify
the -nopad option in the OpenSSL command line function so that it behaves the -nopad option in the OpenSSL command line function so that it behaves
like the wolfSSL AesCbcEncrypt method and does not add extra padding like the wolfSSL AesCbcEncrypt method and does not add extra padding
during encryption. during encryption.
\return 0 On successfully encrypting message. \return 0 On successfully encrypting message.
\return BAD_ALIGN_E: Returned on block align error \return BAD_ALIGN_E: Returned on block align error
\param aes pointer to the AES object used to encrypt data \param aes pointer to the AES object used to encrypt data
\param out pointer to the output buffer in which to store the ciphertext \param out pointer to the output buffer in which to store the ciphertext
of the encrypted message of the encrypted message
\param in pointer to the input buffer containing message to be encrypted \param in pointer to the input buffer containing message to be encrypted
\param sz size of input message \param sz size of input message
_Example_ _Example_
\code \code
Aes enc; Aes enc;
@ -95,7 +95,7 @@ WOLFSSL_API int wc_AesSetIV(Aes* aes, const byte* iv);
// block align error // block align error
} }
\endcode \endcode
\sa wc_AesSetKey \sa wc_AesSetKey
\sa wc_AesSetIV \sa wc_AesSetIV
\sa wc_AesCbcDecrypt \sa wc_AesCbcDecrypt
@ -104,29 +104,29 @@ WOLFSSL_API int wc_AesCbcEncrypt(Aes* aes, byte* out,
const byte* in, word32 sz); const byte* in, word32 sz);
/*! /*!
\ingroup AES \ingroup AES
\brief Decrypts a cipher from the input buffer in, and places the \brief Decrypts a cipher from the input buffer in, and places the
resulting plain text in the output buffer out using cipher block chaining resulting plain text in the output buffer out using cipher block chaining
with AES. This function requires that the AES structure has been with AES. This function requires that the AES structure has been
initialized by calling AesSetKey before a message is able to be decrypted. initialized by calling AesSetKey before a message is able to be decrypted.
This function assumes that the original message was AES block length This function assumes that the original message was AES block length
aligned. This differs from the OpenSSL AES-CBC methods which do not aligned. This differs from the OpenSSL AES-CBC methods which do not
require alignment as it adds PKCS#7 padding automatically. To make the require alignment as it adds PKCS#7 padding automatically. To make the
wolfSSL function and equivalent OpenSSL functions interoperate, one wolfSSL function and equivalent OpenSSL functions interoperate, one
should specify the -nopad option in the OpenSSL command line function should specify the -nopad option in the OpenSSL command line function
so that it behaves like the wolfSSL AesCbcEncrypt method and does not so that it behaves like the wolfSSL AesCbcEncrypt method and does not
create errors during decryption. create errors during decryption.
\return 0 On successfully decrypting message. \return 0 On successfully decrypting message.
\return BAD_ALIGN_E Returned on block align error. \return BAD_ALIGN_E Returned on block align error.
\param aes pointer to the AES object used to decrypt data. \param aes pointer to the AES object used to decrypt data.
\param out pointer to the output buffer in which to store the plain text \param out pointer to the output buffer in which to store the plain text
of the decrypted message. of the decrypted message.
\param in pointer to the input buffer containing cipher text to be \param in pointer to the input buffer containing cipher text to be
decrypted. decrypted.
\param sz size of input message. \param sz size of input message.
_Example_ _Example_
\code \code
Aes dec; Aes dec;
@ -139,7 +139,7 @@ WOLFSSL_API int wc_AesCbcEncrypt(Aes* aes, byte* out,
// block align error // block align error
} }
\endcode \endcode
\sa wc_AesSetKey \sa wc_AesSetKey
\sa wc_AesCbcEncrypt \sa wc_AesCbcEncrypt
*/ */
@ -148,44 +148,44 @@ WOLFSSL_API int wc_AesCbcDecrypt(Aes* aes, byte* out,
/*! /*!
\ingroup AES \ingroup AES
\brief Encrypts/Decrypts a message from the input buffer in, and places \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 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 AES. This function is only enabled if WOLFSSL_AES_COUNTER is enabled at
compile time. The AES structure should be initialized through AesSetKey compile time. The AES structure should be initialized through AesSetKey
before calling this function. Note that this function is used for both before calling this function. Note that this function is used for both
decryption and encryption. _NOTE:_ Regarding using same API for encryption decryption and encryption. _NOTE:_ Regarding using same API for encryption
and decryption. User should differentiate between Aes structures and decryption. User should differentiate between Aes structures
for encrypt/decrypt. for encrypt/decrypt.
\return int integer values corresponding to wolfSSL error or success \return int integer values corresponding to wolfSSL error or success
status status
\param aes pointer to the AES object used to decrypt data \param aes pointer to the AES object used to decrypt data
\param out pointer to the output buffer in which to store the cipher \param out pointer to the output buffer in which to store the cipher
text of the encrypted message text of the encrypted message
\param in pointer to the input buffer containing plain text to be encrypted \param in pointer to the input buffer containing plain text to be encrypted
\param sz size of the input plain text \param sz size of the input plain text
_Example_ _Example_
\code \code
Aes enc; Aes enc;
Aes dec; Aes dec;
// initialize enc and dec with AesSetKeyDirect, using direction // initialize enc and dec with AesSetKeyDirect, using direction
AES_ENCRYPTION AES_ENCRYPTION
// since the underlying API only calls Encrypt and by default calling // since the underlying API only calls Encrypt and by default calling
encrypt on encrypt on
// a cipher results in a decryption of the cipher // a cipher results in a decryption of the cipher
byte msg[AES_BLOCK_SIZE * n]; //n being a positive integer making msg byte msg[AES_BLOCK_SIZE * n]; //n being a positive integer making msg
some multiple of 16 bytes some multiple of 16 bytes
// fill plain with message text // fill plain with message text
byte cipher[AES_BLOCK_SIZE * n]; byte cipher[AES_BLOCK_SIZE * n];
byte decrypted[AES_BLOCK_SIZE * n]; byte decrypted[AES_BLOCK_SIZE * n];
wc_AesCtrEncrypt(&enc, cipher, msg, sizeof(msg)); // encrypt plain wc_AesCtrEncrypt(&enc, cipher, msg, sizeof(msg)); // encrypt plain
wc_AesCtrEncrypt(&dec, decrypted, cipher, sizeof(cipher)); wc_AesCtrEncrypt(&dec, decrypted, cipher, sizeof(cipher));
// decrypt cipher text // decrypt cipher text
\endcode \endcode
\sa wc_AesSetKey \sa wc_AesSetKey
*/ */
WOLFSSL_API int wc_AesCtrEncrypt(Aes* aes, byte* out, WOLFSSL_API int wc_AesCtrEncrypt(Aes* aes, byte* out,
@ -193,19 +193,19 @@ WOLFSSL_API int wc_AesCtrEncrypt(Aes* aes, byte* out,
/*! /*!
\ingroup AES \ingroup AES
\brief This function is a one-block encrypt of the input block, in, into \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) the output block, out. It uses the key and iv (initialization vector)
of the provided AES structure, which should be initialized with of the provided AES structure, which should be initialized with
wc_AesSetKey before calling this function. It is only enabled if the wc_AesSetKey before calling this function. It is only enabled if the
configure option WOLFSSL_AES_DIRECT is enabled. __Warning:__ In nearly all 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 use cases ECB mode is considered to be less secure. Please avoid using ECB
API’s directly whenever possible API’s directly whenever possible
\param aes pointer to the AES object used to encrypt data \param aes pointer to the AES object used to encrypt data
\param out pointer to the output buffer in which to store the cipher \param out pointer to the output buffer in which to store the cipher
text of the encrypted message text of the encrypted message
\param in pointer to the input buffer containing plain text to be encrypted \param in pointer to the input buffer containing plain text to be encrypted
_Example_ _Example_
\code \code
Aes enc; Aes enc;
@ -215,7 +215,7 @@ WOLFSSL_API int wc_AesCtrEncrypt(Aes* aes, byte* out,
byte cipher[AES_BLOCK_SIZE]; byte cipher[AES_BLOCK_SIZE];
wc_AesEncryptDirect(&enc, cipher, msg); wc_AesEncryptDirect(&enc, cipher, msg);
\endcode \endcode
\sa wc_AesDecryptDirect \sa wc_AesDecryptDirect
\sa wc_AesSetKeyDirect \sa wc_AesSetKeyDirect
*/ */
@ -223,23 +223,23 @@ WOLFSSL_API void wc_AesEncryptDirect(Aes* aes, byte* out, const byte* in);
/*! /*!
\ingroup AES \ingroup AES
\brief This function is a one-block decrypt of the input block, in, into \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 output block, out. It uses the key and iv (initialization vector) of
the provided AES structure, which should be initialized with wc_AesSetKey the provided AES structure, which should be initialized with wc_AesSetKey
before calling this function. It is only enabled if the configure option before calling this function. It is only enabled if the configure option
WOLFSSL_AES_DIRECT is enabled, and there is support for direct AES WOLFSSL_AES_DIRECT is enabled, and there is support for direct AES
encryption on the system in question. __Warning:__ In nearly all use cases 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 ECB mode is considered to be less secure. Please avoid using ECB API’s
directly whenever possible directly whenever possible
\return none \return none
\param aes pointer to the AES object used to encrypt data \param aes pointer to the AES object used to encrypt data
\param out pointer to the output buffer in which to store the plain \param out pointer to the output buffer in which to store the plain
text of the decrypted cipher text text of the decrypted cipher text
\param in pointer to the input buffer containing cipher text to be \param in pointer to the input buffer containing cipher text to be
decrypted decrypted
_Example_ _Example_
\code \code
Aes dec; Aes dec;
@ -249,7 +249,7 @@ WOLFSSL_API void wc_AesEncryptDirect(Aes* aes, byte* out, const byte* in);
byte msg[AES_BLOCK_SIZE]; byte msg[AES_BLOCK_SIZE];
wc_AesDecryptDirect(&dec, msg, cipher); wc_AesDecryptDirect(&dec, msg, cipher);
\endcode \endcode
\sa wc_AesEncryptDirect \sa wc_AesEncryptDirect
\sa wc_AesSetKeyDirect \sa wc_AesSetKeyDirect
*/ */
@ -257,38 +257,38 @@ WOLFSSL_API void wc_AesDecryptDirect(Aes* aes, byte* out, const byte* in);
/*! /*!
\ingroup AES \ingroup AES
\brief This function is used to set the AES keys for CTR mode with 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 It initializes an AES object with the given key, iv
(initialization vector), and encryption dir (direction). It is only (initialization vector), and encryption dir (direction). It is only
enabled if the configure option WOLFSSL_AES_DIRECT is enabled. enabled if the configure option WOLFSSL_AES_DIRECT is enabled.
Currently wc_AesSetKeyDirect uses wc_AesSetKey internally. __Warning:__ In Currently wc_AesSetKeyDirect uses wc_AesSetKey internally. __Warning:__ In
nearly all use cases ECB mode is considered to be less secure. Please avoid nearly all use cases ECB mode is considered to be less secure. Please avoid
using ECB API’s directly whenever possible using ECB API’s directly whenever possible
\return 0 On successfully setting the key. \return 0 On successfully setting the key.
\return BAD_FUNC_ARG Returned if the given key is an invalid length. \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 aes pointer to the AES object used to encrypt data
\param key 16, 24, or 32 byte secret key for encryption and decryption \param key 16, 24, or 32 byte secret key for encryption and decryption
\param len length of the key passed in \param len length of the key passed in
\param iv initialization vector used to initialize the key \param iv initialization vector used to initialize the key
\param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or \param dir Cipher direction. Set AES_ENCRYPTION to encrypt, or
AES_DECRYPTION to decrypt. (See enum in wolfssl/wolfcrypt/aes.h) AES_DECRYPTION to decrypt. (See enum in wolfssl/wolfcrypt/aes.h)
(NOTE: If using wc_AesSetKeyDirect with Aes Counter mode (Stream cipher) (NOTE: If using wc_AesSetKeyDirect with Aes Counter mode (Stream cipher)
only use AES_ENCRYPTION for both encrypting and decrypting) only use AES_ENCRYPTION for both encrypting and decrypting)
_Example_ _Example_
\code \code
Aes enc; Aes enc;
int ret = 0; int ret = 0;
byte key[] = { some 16, 24, or 32 byte key }; byte key[] = { some 16, 24, or 32 byte key };
byte iv[] = { some 16 byte iv }; byte iv[] = { some 16 byte iv };
if (ret = wc_AesSetKeyDirect(&enc, key, sizeof(key), iv, if (ret = wc_AesSetKeyDirect(&enc, key, sizeof(key), iv,
AES_ENCRYPTION) != 0) { AES_ENCRYPTION) != 0) {
// failed to set aes key // failed to set aes key
} }
\endcode \endcode
\sa wc_AesEncryptDirect \sa wc_AesEncryptDirect
\sa wc_AesDecryptDirect \sa wc_AesDecryptDirect
\sa wc_AesSetKey \sa wc_AesSetKey
@ -298,18 +298,18 @@ WOLFSSL_API int wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len,
/*! /*!
\ingroup AES \ingroup AES
\brief This function is used to set the key for AES GCM \brief This function is used to set the key for AES GCM
(Galois/Counter Mode). It initializes an AES object with the (Galois/Counter Mode). It initializes an AES object with the
given key. It is only enabled if the configure option given key. It is only enabled if the configure option
HAVE_AESGCM is enabled at compile time. HAVE_AESGCM is enabled at compile time.
\return 0 On successfully setting the key. \return 0 On successfully setting the key.
\return BAD_FUNC_ARG Returned if the given key is an invalid length. \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 aes pointer to the AES object used to encrypt data
\param key 16, 24, or 32 byte secret key for encryption and decryption \param key 16, 24, or 32 byte secret key for encryption and decryption
\param len length of the key passed in \param len length of the key passed in
_Example_ _Example_
\code \code
Aes enc; Aes enc;
@ -319,7 +319,7 @@ WOLFSSL_API int wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len,
// failed to set aes key // failed to set aes key
} }
\endcode \endcode
\sa wc_AesGcmEncrypt \sa wc_AesGcmEncrypt
\sa wc_AesGcmDecrypt \sa wc_AesGcmDecrypt
*/ */
@ -327,33 +327,33 @@ WOLFSSL_API int wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len);
/*! /*!
\ingroup AES \ingroup AES
\brief This function encrypts the input message, held in the buffer in, \brief This function encrypts the input message, held in the buffer in,
and stores the resulting cipher text in the output buffer out. It and stores the resulting cipher text in the output buffer out. It
requires a new iv (initialization vector) for each call to encrypt. requires a new iv (initialization vector) for each call to encrypt.
It also encodes the input authentication vector, authIn, into the It also encodes the input authentication vector, authIn, into the
authentication tag, authTag. authentication tag, authTag.
\return 0 On successfully encrypting the input message \return 0 On successfully encrypting the input message
\param aes - pointer to the AES object used to encrypt data \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 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 in pointer to the input buffer holding the message to encrypt
\param sz length of the input message to encrypt \param sz length of the input message to encrypt
\param iv pointer to the buffer containing the initialization vector \param iv pointer to the buffer containing the initialization vector
\param ivSz length of the initialization vector \param ivSz length of the initialization vector
\param authTag pointer to the buffer in which to store the \param authTag pointer to the buffer in which to store the
authentication tag authentication tag
\param authTagSz length of the desired authentication tag \param authTagSz length of the desired authentication tag
\param authIn pointer to the buffer containing the input \param authIn pointer to the buffer containing the input
authentication vector authentication vector
\param authInSz length of the input authentication vector \param authInSz length of the input authentication vector
_Example_ _Example_
\code \code
Aes enc; Aes enc;
// initialize aes structure by calling wc_AesGcmSetKey // initialize aes structure by calling wc_AesGcmSetKey
byte plain[AES_BLOCK_LENGTH * n]; //n being a positive integer byte plain[AES_BLOCK_LENGTH * n]; //n being a positive integer
making plain some multiple of 16 bytes making plain some multiple of 16 bytes
// initialize plain with msg to encrypt // initialize plain with msg to encrypt
byte cipher[sizeof(plain)]; byte cipher[sizeof(plain)];
@ -364,7 +364,7 @@ WOLFSSL_API int wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len);
wc_AesGcmEncrypt(&enc, cipher, plain, sizeof(cipher), iv, sizeof(iv), wc_AesGcmEncrypt(&enc, cipher, plain, sizeof(cipher), iv, sizeof(iv),
authTag, sizeof(authTag), authIn, sizeof(authIn)); authTag, sizeof(authTag), authIn, sizeof(authIn));
\endcode \endcode
\sa wc_AesGcmSetKey \sa wc_AesGcmSetKey
\sa wc_AesGcmDecrypt \sa wc_AesGcmDecrypt
*/ */
@ -376,15 +376,15 @@ WOLFSSL_API int wc_AesGcmEncrypt(Aes* aes, byte* out,
/*! /*!
\ingroup AES \ingroup AES
\brief This function decrypts the input cipher text, held in the buffer \brief This function decrypts the input cipher text, held in the buffer
in, and stores the resulting message text in the output buffer out. in, and stores the resulting message text in the output buffer out.
It also checks the input authentication vector, authIn, against the It also checks the input authentication vector, authIn, against the
supplied authentication tag, authTag. supplied authentication tag, authTag.
\return 0 On successfully decrypting the input message \return 0 On successfully decrypting the input message
\return AES_GCM_AUTH_E If the authentication tag does not match the \return AES_GCM_AUTH_E If the authentication tag does not match the
supplied authentication code vector, authTag. supplied authentication code vector, authTag.
\param aes pointer to the AES object used to encrypt data \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 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 in pointer to the input buffer holding the cipher text to decrypt
@ -393,16 +393,16 @@ WOLFSSL_API int wc_AesGcmEncrypt(Aes* aes, byte* out,
\param ivSz length of the initialization vector \param ivSz length of the initialization vector
\param authTag pointer to the buffer containing the authentication tag \param authTag pointer to the buffer containing the authentication tag
\param authTagSz length of the desired authentication tag \param authTagSz length of the desired authentication tag
\param authIn pointer to the buffer containing the input \param authIn pointer to the buffer containing the input
authentication vector authentication vector
\param authInSz length of the input authentication vector \param authInSz length of the input authentication vector
_Example_ _Example_
\code \code
Aes enc; //can use the same struct as was passed to wc_AesGcmEncrypt Aes enc; //can use the same struct as was passed to wc_AesGcmEncrypt
// initialize aes structure by calling wc_AesGcmSetKey if not already done // initialize aes structure by calling wc_AesGcmSetKey if not already done
byte cipher[AES_BLOCK_LENGTH * n]; //n being a positive integer byte cipher[AES_BLOCK_LENGTH * n]; //n being a positive integer
making cipher some multiple of 16 bytes making cipher some multiple of 16 bytes
// initialize cipher with cipher text to decrypt // initialize cipher with cipher text to decrypt
byte output[sizeof(cipher)]; byte output[sizeof(cipher)];
@ -413,7 +413,7 @@ WOLFSSL_API int wc_AesGcmEncrypt(Aes* aes, byte* out,
wc_AesGcmDecrypt(&enc, output, cipher, sizeof(cipher), iv, sizeof(iv), wc_AesGcmDecrypt(&enc, output, cipher, sizeof(cipher), iv, sizeof(iv),
authTag, sizeof(authTag), authIn, sizeof(authIn)); authTag, sizeof(authTag), authIn, sizeof(authIn));
\endcode \endcode
\sa wc_AesGcmSetKey \sa wc_AesGcmSetKey
\sa wc_AesGcmEncrypt \sa wc_AesGcmEncrypt
*/ */
@ -425,45 +425,45 @@ WOLFSSL_API int wc_AesGcmDecrypt(Aes* aes, byte* out,
/*! /*!
\ingroup AES \ingroup AES
\brief This function initializes and sets the key for a GMAC object \brief This function initializes and sets the key for a GMAC object
to be used for Galois Message Authentication. to be used for Galois Message Authentication.
\return 0 On successfully setting the key \return 0 On successfully setting the key
\return BAD_FUNC_ARG Returned if key length is invalid. \return BAD_FUNC_ARG Returned if key length is invalid.
\param gmac pointer to the gmac object used for authentication \param gmac pointer to the gmac object used for authentication
\param key 16, 24, or 32 byte secret key for authentication \param key 16, 24, or 32 byte secret key for authentication
\param len length of the key \param len length of the key
_Example_ _Example_
\code \code
Gmac gmac; Gmac gmac;
key[] = { some 16, 24, or 32 byte length key }; key[] = { some 16, 24, or 32 byte length key };
wc_GmacSetKey(&gmac, key, sizeof(key)); wc_GmacSetKey(&gmac, key, sizeof(key));
\endcode \endcode
\sa wc_GmacUpdate \sa wc_GmacUpdate
*/ */
WOLFSSL_API int wc_GmacSetKey(Gmac* gmac, const byte* key, word32 len); WOLFSSL_API int wc_GmacSetKey(Gmac* gmac, const byte* key, word32 len);
/*! /*!
\ingroup AES \ingroup AES
\brief This function generates the Gmac hash of the authIn input and \brief This function generates the Gmac hash of the authIn input and
stores the result in the authTag buffer. After running wc_GmacUpdate, stores the result in the authTag buffer. After running wc_GmacUpdate,
one should compare the generated authTag to a known authentication tag one should compare the generated authTag to a known authentication tag
to verify the authenticity of a message. to verify the authenticity of a message.
\return 0 On successfully computing the Gmac hash. \return 0 On successfully computing the Gmac hash.
\param gmac pointer to the gmac object used for authentication \param gmac pointer to the gmac object used for authentication
\param iv initialization vector used for the hash \param iv initialization vector used for the hash
\param ivSz size of the initialization vector used \param ivSz size of the initialization vector used
\param authIn pointer to the buffer containing the authentication \param authIn pointer to the buffer containing the authentication
vector to verify vector to verify
\param authInSz size of the authentication vector \param authInSz size of the authentication vector
\param authTag pointer to the output buffer in which to store the Gmac hash \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 \param authTagSz the size of the output buffer used to store the Gmac hash
_Example_ _Example_
\code \code
Gmac gmac; Gmac gmac;
@ -474,10 +474,10 @@ WOLFSSL_API int wc_GmacSetKey(Gmac* gmac, const byte* key, word32 len);
authIn[] = { some 16 byte authentication input }; authIn[] = { some 16 byte authentication input };
tag[AES_BLOCK_SIZE]; // will store authentication code tag[AES_BLOCK_SIZE]; // will store authentication code
wc_GmacUpdate(&gmac, iv, sizeof(iv), authIn, sizeof(authIn), tag, wc_GmacUpdate(&gmac, iv, sizeof(iv), authIn, sizeof(authIn), tag,
sizeof(tag)); sizeof(tag));
\endcode \endcode
\sa wc_GmacSetKey \sa wc_GmacSetKey
*/ */
WOLFSSL_API int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz, WOLFSSL_API int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz,
@ -486,16 +486,16 @@ WOLFSSL_API int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz,
/*! /*!
\ingroup AES \ingroup AES
\brief This function sets the key for an AES object using CCM \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 (Counter with CBC-MAC). It takes a pointer to an AES structure and
initializes it with supplied key. initializes it with supplied key.
\return none \return none
\param aes aes structure in which to store the supplied key \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 key 16, 24, or 32 byte secret key for encryption and decryption
\param keySz size of the supplied key \param keySz size of the supplied key
_Example_ _Example_
\code \code
Aes enc; Aes enc;
@ -503,7 +503,7 @@ WOLFSSL_API int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz,
wc_AesCcmSetKey(&aes, key, sizeof(key)); wc_AesCcmSetKey(&aes, key, sizeof(key));
\endcode \endcode
\sa wc_AesCcmEncrypt \sa wc_AesCcmEncrypt
\sa wc_AesCcmDecrypt \sa wc_AesCcmDecrypt
*/ */
@ -511,28 +511,28 @@ WOLFSSL_API int wc_AesCcmSetKey(Aes* aes, const byte* key, word32 keySz);
/*! /*!
\ingroup AES \ingroup AES
\brief This function encrypts the input message, in, into the output \brief This function encrypts the input message, in, into the output
buffer, out, using CCM (Counter with CBC-MAC). It subsequently buffer, out, using CCM (Counter with CBC-MAC). It subsequently
calculates and stores the authorization tag, authTag, from the calculates and stores the authorization tag, authTag, from the
authIn input. authIn input.
\return none \return none
\param aes pointer to the AES object used to encrypt data \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 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 in pointer to the input buffer holding the message to encrypt
\param sz length of the input message to encrypt \param sz length of the input message to encrypt
\param nonce pointer to the buffer containing the nonce \param nonce pointer to the buffer containing the nonce
(number only used once) (number only used once)
\param nonceSz length of the nonce \param nonceSz length of the nonce
\param authTag pointer to the buffer in which to store the \param authTag pointer to the buffer in which to store the
authentication tag authentication tag
\param authTagSz length of the desired authentication tag \param authTagSz length of the desired authentication tag
\param authIn pointer to the buffer containing the input \param authIn pointer to the buffer containing the input
authentication vector authentication vector
\param authInSz length of the input authentication vector \param authInSz length of the input authentication vector
_Example_ _Example_
\code \code
Aes enc; Aes enc;
@ -548,7 +548,7 @@ WOLFSSL_API int wc_AesCcmSetKey(Aes* aes, const byte* key, word32 keySz);
wc_AesCcmEncrypt(&enc, cipher, plain, sizeof(plain), nonce, sizeof(nonce), wc_AesCcmEncrypt(&enc, cipher, plain, sizeof(plain), nonce, sizeof(nonce),
tag, sizeof(tag), authIn, sizeof(authIn)); tag, sizeof(tag), authIn, sizeof(authIn));
\endcode \endcode
\sa wc_AesCcmSetKey \sa wc_AesCcmSetKey
\sa wc_AesCcmDecrypt \sa wc_AesCcmDecrypt
*/ */
@ -560,31 +560,31 @@ WOLFSSL_API int wc_AesCcmEncrypt(Aes* aes, byte* out,
/*! /*!
\ingroup AES \ingroup AES
\brief This function decrypts the input cipher text, in, into \brief This function decrypts the input cipher text, in, into
the output buffer, out, using CCM (Counter with CBC-MAC). It the output buffer, out, using CCM (Counter with CBC-MAC). It
subsequently calculates the authorization tag, authTag, from the subsequently calculates the authorization tag, authTag, from the
authIn input. If the authorization tag is invalid, it sets the authIn input. If the authorization tag is invalid, it sets the
output buffer to zero and returns the error: AES_CCM_AUTH_E. output buffer to zero and returns the error: AES_CCM_AUTH_E.
\return 0 On successfully decrypting the input message \return 0 On successfully decrypting the input message
\return AES_CCM_AUTH_E If the authentication tag does not match the \return AES_CCM_AUTH_E If the authentication tag does not match the
supplied authentication code vector, authTag. supplied authentication code vector, authTag.
\param aes pointer to the AES object used to encrypt data \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 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 in pointer to the input buffer holding the message to encrypt
\param sz length of the input cipher text to decrypt \param sz length of the input cipher text to decrypt
\param nonce pointer to the buffer containing the nonce \param nonce pointer to the buffer containing the nonce
(number only used once) (number only used once)
\param nonceSz length of the nonce \param nonceSz length of the nonce
\param authTag pointer to the buffer in which to store the \param authTag pointer to the buffer in which to store the
authentication tag authentication tag
\param authTagSz length of the desired authentication tag \param authTagSz length of the desired authentication tag
\param authIn pointer to the buffer containing the input \param authIn pointer to the buffer containing the input
authentication vector authentication vector
\param authInSz length of the input authentication vector \param authInSz length of the input authentication vector
_Example_ _Example_
\code \code
Aes dec; Aes dec;
@ -597,13 +597,13 @@ WOLFSSL_API int wc_AesCcmEncrypt(Aes* aes, byte* out,
authIn[] = { some 16 byte authentication input }; authIn[] = { some 16 byte authentication input };
tag[AES_BLOCK_SIZE] = { authentication tag received for verification }; tag[AES_BLOCK_SIZE] = { authentication tag received for verification };
int return = wc_AesCcmDecrypt(&dec, plain, cipher, sizeof(cipher), int return = wc_AesCcmDecrypt(&dec, plain, cipher, sizeof(cipher),
nonce, sizeof(nonce),tag, sizeof(tag), authIn, sizeof(authIn)); nonce, sizeof(nonce),tag, sizeof(tag), authIn, sizeof(authIn));
if(return != 0) { if(return != 0) {
// decrypt error, invalid authentication code // decrypt error, invalid authentication code
} }
\endcode \endcode
\sa wc_AesCcmSetKey \sa wc_AesCcmSetKey
\sa wc_AesCcmEncrypt \sa wc_AesCcmEncrypt
*/ */
@ -616,14 +616,14 @@ WOLFSSL_API int wc_AesCcmDecrypt(Aes* aes, byte* out,
/*! /*!
\ingroup AES \ingroup AES
\brief This is to help with setting keys to correct encrypt or \brief This is to help with setting keys to correct encrypt or
decrypt type. It is up to user to call wc_AesXtsFree on aes key when done. decrypt type. It is up to user to call wc_AesXtsFree on aes key when done.
\return 0 Success \return 0 Success
\param aes AES keys for encrypt/decrypt process \param aes AES keys for encrypt/decrypt process
\param key buffer holding aes key | tweak key \param key buffer holding aes key | tweak key
\param len length of key buffer in bytes. Should be twice that of \param len length of key buffer in bytes. Should be twice that of
key size. key size.
i.e. 32 for a 16 byte key. i.e. 32 for a 16 byte key.
\param dir direction, either AES_ENCRYPTION or AES_DECRYPTION \param dir direction, either AES_ENCRYPTION or AES_DECRYPTION
@ -781,7 +781,7 @@ WOLFSSL_API int wc_AesXtsEncrypt(XtsAes* aes, byte* out,
\param iSz size of i buffer, should always be AES_BLOCK_SIZE but having \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 this input adds a sanity check on how the user calls the
function. function.
_Example_ _Example_
\code \code
XtsAes aes; XtsAes aes;

38
doc/dox_comments/header_files/arc4.h
View File

@ -1,20 +1,20 @@
/*! /*!
\ingroup ARC4 \ingroup ARC4
\brief This function encrypts an input message from the buffer in, placing \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 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 buffer in, placing the plaintext in the output buffer out, using ARC4
encryption. This function is used for both encryption and decryption. encryption. This function is used for both encryption and decryption.
Before this method may be called, one must first initialize the ARC4 Before this method may be called, one must first initialize the ARC4
structure using wc_Arc4SetKey. structure using wc_Arc4SetKey.
\return none \return none
\param arc4 pointer to the ARC4 structure used to process the message \param arc4 pointer to the ARC4 structure used to process the message
\param out pointer to the output buffer in which to store the \param out pointer to the output buffer in which to store the
processed message processed message
\param in pointer to the input buffer containing the message to process \param in pointer to the input buffer containing the message to process
\param length length of the message to process \param length length of the message to process
_Example_ _Example_
\code \code
Arc4 enc; Arc4 enc;
@ -26,34 +26,34 @@
byte decrypted[sizeof(plain)]; byte decrypted[sizeof(plain)];
// encrypt the plain into cipher // encrypt the plain into cipher
wc_Arc4Process(&enc, cipher, plain, sizeof(plain)); wc_Arc4Process(&enc, cipher, plain, sizeof(plain));
// decrypt the cipher // decrypt the cipher
wc_Arc4Process(&enc, decrypted, cipher, sizeof(cipher)); wc_Arc4Process(&enc, decrypted, cipher, sizeof(cipher));
\endcode \endcode
\sa wc_Arc4SetKey \sa wc_Arc4SetKey
*/ */
WOLFSSL_API int wc_Arc4Process(Arc4*, byte*, const byte*, word32); WOLFSSL_API int wc_Arc4Process(Arc4*, byte*, const byte*, word32);
/*! /*!
\ingroup ARC4 \ingroup ARC4
\brief This function sets the key for a ARC4 object, initializing it for \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 use as a cipher. It should be called before using it for encryption
with wc_Arc4Process. with wc_Arc4Process.
\return none \return none
\param arc4 pointer to an arc4 structure to be used for encryption \param arc4 pointer to an arc4 structure to be used for encryption
\param key key with which to initialize the arc4 structure \param key key with which to initialize the arc4 structure
\param length length of the key used to initialize the arc4 structure \param length length of the key used to initialize the arc4 structure
_Example_ _Example_
\code \code
Arc4 enc; Arc4 enc;
byte key[] = { initialize with key to use for encryption }; byte key[] = { initialize with key to use for encryption };
wc_Arc4SetKey(&enc, key, sizeof(key)); wc_Arc4SetKey(&enc, key, sizeof(key));
\endcode \endcode
\sa wc_Arc4Process \sa wc_Arc4Process
*/ */
WOLFSSL_API int wc_Arc4SetKey(Arc4*, const byte*, word32); WOLFSSL_API int wc_Arc4SetKey(Arc4*, const byte*, word32);

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

File diff suppressed because it is too large Load Diff

56
doc/dox_comments/header_files/blake2.h
View File

@ -1,47 +1,47 @@
/*! /*!
\ingroup BLAKE2 \ingroup BLAKE2
\brief This function initializes a Blake2b structure for use with the \brief This function initializes a Blake2b structure for use with the
Blake2 hash function. Blake2 hash function.
\return 0 Returned upon successfully initializing the Blake2b structure and \return 0 Returned upon successfully initializing the Blake2b structure and
setting the digest size. setting the digest size.
\param b2b pointer to the Blake2b structure to initialize \param b2b pointer to the Blake2b structure to initialize
\param digestSz length of the blake 2 digest to implement \param digestSz length of the blake 2 digest to implement
_Example_ _Example_
\code \code
Blake2b b2b; Blake2b b2b;
// initialize Blake2b structure with 64 byte digest // initialize Blake2b structure with 64 byte digest
wc_InitBlake2b(&b2b, 64); wc_InitBlake2b(&b2b, 64);
\endcode \endcode
\sa wc_Blake2bUpdate \sa wc_Blake2bUpdate
*/ */
WOLFSSL_API int wc_InitBlake2b(Blake2b*, word32); WOLFSSL_API int wc_InitBlake2b(Blake2b*, word32);
/*! /*!
\ingroup BLAKE2 \ingroup BLAKE2
\brief This function updates the Blake2b hash with the given input data. \brief This function updates the Blake2b hash with the given input data.
This function should be called after wc_InitBlake2b, and repeated until This function should be called after wc_InitBlake2b, and repeated until
one is ready for the final hash: wc_Blake2bFinal. one is ready for the final hash: wc_Blake2bFinal.
\return 0 Returned upon successfully update the Blake2b structure with \return 0 Returned upon successfully update the Blake2b structure with
the given data the given data
\return -1 Returned if there is a failure while compressing the input data \return -1 Returned if there is a failure while compressing the input data
\param b2b pointer to the Blake2b structure to update \param b2b pointer to the Blake2b structure to update
\param data pointer to a buffer containing the data to append \param data pointer to a buffer containing the data to append
\param sz length of the input data to append \param sz length of the input data to append
_Example_ _Example_
\code \code
int ret; int ret;
Blake2b b2b; Blake2b b2b;
// initialize Blake2b structure with 64 byte digest // initialize Blake2b structure with 64 byte digest
wc_InitBlake2b(&b2b, 64); wc_InitBlake2b(&b2b, 64);
byte plain[] = { // initialize input }; byte plain[] = { // initialize input };
@ -50,7 +50,7 @@ WOLFSSL_API int wc_InitBlake2b(Blake2b*, word32);
// error updating blake2b // error updating blake2b
} }
\endcode \endcode
\sa wc_InitBlake2b \sa wc_InitBlake2b
\sa wc_Blake2bFinal \sa wc_Blake2bFinal
*/ */
@ -58,29 +58,29 @@ WOLFSSL_API int wc_Blake2bUpdate(Blake2b*, const byte*, word32);
/*! /*!
\ingroup BLAKE2 \ingroup BLAKE2
\brief This function computes the Blake2b hash of the previously supplied \brief This function computes the Blake2b hash of the previously supplied
input data. The output hash will be of length requestSz, or, if input data. The output hash will be of length requestSz, or, if
requestSz==0, the digestSz of the b2b structure. This function should be requestSz==0, the digestSz of the b2b structure. This function should be
called after wc_InitBlake2b and wc_Blake2bUpdate has been processed for called after wc_InitBlake2b and wc_Blake2bUpdate has been processed for
each piece of input data desired. each piece of input data desired.
\return 0 Returned upon successfully computing the Blake2b hash \return 0 Returned upon successfully computing the Blake2b hash
\return -1 Returned if there is a failure while parsing 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 b2b pointer to the Blake2b structure to update
\param final pointer to a buffer in which to store the blake2b hash. \param final pointer to a buffer in which to store the blake2b hash.
Should be of length requestSz Should be of length requestSz
\param requestSz length of the digest to compute. When this is zero, \param requestSz length of the digest to compute. When this is zero,
b2b->digestSz will be used instead b2b->digestSz will be used instead
_Example_ _Example_
\code \code
int ret; int ret;
Blake2b b2b; Blake2b b2b;
byte hash[64]; byte hash[64];
// initialize Blake2b structure with 64 byte digest // initialize Blake2b structure with 64 byte digest
wc_InitBlake2b(&b2b, 64); wc_InitBlake2b(&b2b, 64);
... // call wc_Blake2bUpdate to add data to hash ... // call wc_Blake2bUpdate to add data to hash
ret = wc_Blake2bFinal(&b2b, hash, 64); ret = wc_Blake2bFinal(&b2b, hash, 64);
@ -88,7 +88,7 @@ WOLFSSL_API int wc_Blake2bUpdate(Blake2b*, const byte*, word32);
// error generating blake2b hash // error generating blake2b hash
} }
\endcode \endcode
\sa wc_InitBlake2b \sa wc_InitBlake2b
\sa wc_Blake2bUpdate \sa wc_Blake2bUpdate
*/ */

10
doc/dox_comments/header_files/bn.h
View File

@ -1,17 +1,17 @@
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief This function performs the following math “r = (a^p) % m”. \brief This function performs the following math “r = (a^p) % m”.
\return SSL_SUCCESS On successfully performing math operation. \return SSL_SUCCESS On successfully performing math operation.
\return SSL_FAILURE If an error case was encountered. \return SSL_FAILURE If an error case was encountered.
\param r structure to hold result. \param r structure to hold result.
\param a value to be raised by a power. \param a value to be raised by a power.
\param p power to raise a by. \param p power to raise a by.
\param m modulus to use. \param m modulus to use.
\param ctx currently not used with wolfSSL can be NULL. \param ctx currently not used with wolfSSL can be NULL.
_Example_ _Example_
\code \code
WOLFSSL_BIGNUM r,a,p,m; WOLFSSL_BIGNUM r,a,p,m;
@ -20,7 +20,7 @@
ret = wolfSSL_BN_mod_exp(r, a, p, m, NULL); ret = wolfSSL_BN_mod_exp(r, a, p, m, NULL);
// check ret value // check ret value
\endcode \endcode
\sa wolfSSL_BN_new \sa wolfSSL_BN_new
\sa wolfSSL_BN_free \sa wolfSSL_BN_free
*/ */

108
doc/dox_comments/header_files/camellia.h
View File

@ -1,23 +1,23 @@
/*! /*!
\ingroup Camellia \ingroup Camellia
\brief This function sets the key and initialization vector for a \brief This function sets the key and initialization vector for a
camellia object, initializing it for use as a cipher. camellia object, initializing it for use as a cipher.
\return 0 Returned upon successfully setting the key and initialization \return 0 Returned upon successfully setting the key and initialization
vector vector
\return BAD_FUNC_ARG returned if there is an error processing one of \return BAD_FUNC_ARG returned if there is an error processing one of
the input arguments the input arguments
\return MEMORY_E returned if there is an error allocating memory with \return MEMORY_E returned if there is an error allocating memory with
XMALLOC XMALLOC
\param cam pointer to the camellia structure on which to set the key and iv \param cam pointer to the camellia structure on which to set the key and iv
\param key pointer to the buffer containing the 16, 24, or 32 byte key \param key pointer to the buffer containing the 16, 24, or 32 byte key
to use for encryption and decryption to use for encryption and decryption
\param len length of the key passed in \param len length of the key passed in
\param iv pointer to the buffer containing the 16 byte initialization \param iv pointer to the buffer containing the 16 byte initialization
vector for use with this camellia structure vector for use with this camellia structure
_Example_ _Example_
\code \code
Camellia cam; Camellia cam;
@ -25,11 +25,11 @@
// initialize key // initialize key
byte iv[16]; byte iv[16];
// initialize iv // initialize iv
if( wc_CamelliaSetKey(&cam, key, sizeof(key), iv) != 0) { if( wc_CamelliaSetKey(&cam, key, sizeof(key), iv) != 0) {
// error initializing camellia structure // error initializing camellia structure
} }
\endcode \endcode
\sa wc_CamelliaEncryptDirect \sa wc_CamelliaEncryptDirect
\sa wc_CamelliaDecryptDirect \sa wc_CamelliaDecryptDirect
\sa wc_CamelliaCbcEncrypt \sa wc_CamelliaCbcEncrypt
@ -40,56 +40,56 @@ WOLFSSL_API int wc_CamelliaSetKey(Camellia* cam,
/*! /*!
\ingroup Camellia \ingroup Camellia
\brief This function sets the initialization vector for a camellia object. \brief This function sets the initialization vector for a camellia object.
\return 0 Returned upon successfully setting the key and initialization \return 0 Returned upon successfully setting the key and initialization
vector vector
\return BAD_FUNC_ARG returned if there is an error processing one of the \return BAD_FUNC_ARG returned if there is an error processing one of the
input arguments input arguments
\param cam pointer to the camellia structure on which to set the iv \param cam pointer to the camellia structure on which to set the iv
\param iv pointer to the buffer containing the 16 byte initialization \param iv pointer to the buffer containing the 16 byte initialization
vector for use with this camellia structure vector for use with this camellia structure
_Example_ _Example_
\code \code
Camellia cam; Camellia cam;
byte iv[16]; byte iv[16];
// initialize iv // initialize iv
if( wc_CamelliaSetIV(&cam, iv) != 0) { if( wc_CamelliaSetIV(&cam, iv) != 0) {
// error initializing camellia structure // error initializing camellia structure
} }
\endcode \endcode
\sa wc_CamelliaSetKey \sa wc_CamelliaSetKey
*/ */
WOLFSSL_API int wc_CamelliaSetIV(Camellia* cam, const byte* iv); WOLFSSL_API int wc_CamelliaSetIV(Camellia* cam, const byte* iv);
/*! /*!
\ingroup Camellia \ingroup Camellia
\brief This function does a one-block encrypt using the provided 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 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 the encrypted result in the buffer out. Before using this function, one
should initialize the camellia object using wc_CamelliaSetKey. should initialize the camellia object using wc_CamelliaSetKey.
\return none No returns. \return none No returns.
\param cam pointer to the camellia structure to use for encryption \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 out pointer to the buffer in which to store the encrypted block
\param in pointer to the buffer containing the plaintext block to encrypt \param in pointer to the buffer containing the plaintext block to encrypt
_Example_ _Example_
\code \code
Camellia cam; Camellia cam;
// initialize cam structure with key and iv // initialize cam structure with key and iv
byte plain[] = { // initialize with message to encrypt }; byte plain[] = { // initialize with message to encrypt };
byte cipher[16]; byte cipher[16];
wc_CamelliaEncryptDirect(&ca, cipher, plain); wc_CamelliaEncryptDirect(&ca, cipher, plain);
\endcode \endcode
\sa wc_CamelliaDecryptDirect \sa wc_CamelliaDecryptDirect
*/ */
WOLFSSL_API int wc_CamelliaEncryptDirect(Camellia* cam, byte* out, WOLFSSL_API int wc_CamelliaEncryptDirect(Camellia* cam, byte* out,
@ -97,19 +97,19 @@ WOLFSSL_API int wc_CamelliaEncryptDirect(Camellia* cam, byte* out,
/*! /*!
\ingroup Camellia \ingroup Camellia
\brief This function does a one-block decrypt using the provided 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, 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 and stores the result in the buffer out. Before using this function, one
should initialize the camellia object using wc_CamelliaSetKey. should initialize the camellia object using wc_CamelliaSetKey.
\return none No returns. \return none No returns.
\param cam pointer to the camellia structure to use for encryption \param cam pointer to the camellia structure to use for encryption
\param out pointer to the buffer in which to store the decrypted \param out pointer to the buffer in which to store the decrypted
plaintext block plaintext block
\param in pointer to the buffer containing the ciphertext block to decrypt \param in pointer to the buffer containing the ciphertext block to decrypt
_Example_ _Example_
\code \code
Camellia cam; Camellia cam;
@ -119,7 +119,7 @@ WOLFSSL_API int wc_CamelliaEncryptDirect(Camellia* cam, byte* out,
wc_CamelliaDecryptDirect(&cam, decrypted, cipher); wc_CamelliaDecryptDirect(&cam, decrypted, cipher);
\endcode \endcode
\sa wc_CamelliaEncryptDirect \sa wc_CamelliaEncryptDirect
*/ */
WOLFSSL_API int wc_CamelliaDecryptDirect(Camellia* cam, byte* out, WOLFSSL_API int wc_CamelliaDecryptDirect(Camellia* cam, byte* out,
@ -127,42 +127,42 @@ WOLFSSL_API int wc_CamelliaDecryptDirect(Camellia* cam, byte* out,
/*! /*!
\ingroup Camellia \ingroup Camellia
\brief This function encrypts the plaintext from the buffer in and \brief This function encrypts the plaintext from the buffer in and
stores the output in the buffer out. It performs this encryption stores the output in the buffer out. It performs this encryption
using Camellia with Cipher Block Chaining (CBC). using Camellia with Cipher Block Chaining (CBC).
\return none No returns. \return none No returns.
\param cam pointer to the camellia structure to use for encryption \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 out pointer to the buffer in which to store the encrypted ciphertext
\param in pointer to the buffer containing the plaintext to encrypt \param in pointer to the buffer containing the plaintext to encrypt
\param sz the size of the message to encrypt \param sz the size of the message to encrypt
_Example_ _Example_
\code \code
Camellia cam; Camellia cam;
// initialize cam structure with key and iv // initialize cam structure with key and iv
byte plain[] = { // initialize with encrypted message to decrypt }; byte plain[] = { // initialize with encrypted message to decrypt };
byte cipher[sizeof(plain)]; byte cipher[sizeof(plain)];
wc_CamelliaCbcEncrypt(&cam, cipher, plain, sizeof(plain)); wc_CamelliaCbcEncrypt(&cam, cipher, plain, sizeof(plain));
\endcode \endcode
\sa wc_CamelliaCbcDecrypt \sa wc_CamelliaCbcDecrypt
*/ */
WOLFSSL_API int wc_CamelliaCbcEncrypt(Camellia* cam, WOLFSSL_API int wc_CamelliaCbcEncrypt(Camellia* cam,
byte* out, const byte* in, word32 sz); byte* out, const byte* in, word32 sz);
/*! /*!
\ingroup Camellia \ingroup Camellia
\brief This function decrypts the ciphertext from the buffer in and \brief This function decrypts the ciphertext from the buffer in and
stores the output in the buffer out. It performs this decryption using stores the output in the buffer out. It performs this decryption using
Camellia with Cipher Block Chaining (CBC). Camellia with Cipher Block Chaining (CBC).
\return none No returns. \return none No returns.
\param cam pointer to the camellia structure to use for encryption \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 out pointer to the buffer in which to store the decrypted message
\param in pointer to the buffer containing the encrypted ciphertext \param in pointer to the buffer containing the encrypted ciphertext
@ -177,7 +177,7 @@ WOLFSSL_API int wc_CamelliaCbcEncrypt(Camellia* cam,
wc_CamelliaCbcDecrypt(&cam, decrypted, cipher, sizeof(cipher)); wc_CamelliaCbcDecrypt(&cam, decrypted, cipher, sizeof(cipher));
\endcode \endcode
\sa wc_CamelliaCbcEncrypt \sa wc_CamelliaCbcEncrypt
*/ */
WOLFSSL_API int wc_CamelliaCbcDecrypt(Camellia* cam, WOLFSSL_API int wc_CamelliaCbcDecrypt(Camellia* cam,

62
doc/dox_comments/header_files/chacha.h
View File

@ -1,19 +1,19 @@
/*! /*!
\ingroup ChaCha \ingroup ChaCha
\brief This function sets the initialization vector (nonce) for a 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 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 key has been set, using wc_Chacha_SetKey. A difference nonce should be
used for each round of encryption. used for each round of encryption.
\return 0 Returned upon successfully setting the initialization vector \return 0 Returned upon successfully setting the initialization vector
\return BAD_FUNC_ARG returned if there is an error processing the ctx \return BAD_FUNC_ARG returned if there is an error processing the ctx
input argument input argument
\param ctx pointer to the ChaCha structure on which to set the iv \param ctx pointer to the ChaCha structure on which to set the iv
\param inIv pointer to a buffer containing the 12 byte initialization \param inIv pointer to a buffer containing the 12 byte initialization
vector with which to initialize the ChaCha structure vector with which to initialize the ChaCha structure
\param counter the value at which the block counter should start--usually \param counter the value at which the block counter should start--usually
zero. zero.
_Example_ _Example_
@ -21,12 +21,12 @@
ChaCha enc; ChaCha enc;
// initialize enc with wc_Chacha_SetKey // initialize enc with wc_Chacha_SetKey
byte iv[12]; byte iv[12];
// initialize iv // initialize iv
if( wc_Chacha_SetIV(&enc, iv, 0) != 0) { if( wc_Chacha_SetIV(&enc, iv, 0) != 0) {
// error initializing ChaCha structure // error initializing ChaCha structure
} }
\endcode \endcode
\sa wc_Chacha_SetKey \sa wc_Chacha_SetKey
\sa wc_Chacha_Process \sa wc_Chacha_Process
*/ */
@ -34,18 +34,18 @@ WOLFSSL_API int wc_Chacha_SetIV(ChaCha* ctx, const byte* inIv, word32 counter);
/*! /*!
\ingroup ChaCha \ingroup ChaCha
\brief This function processes the text from the buffer input, encrypts \brief This function processes the text from the buffer input, encrypts
or decrypts it, and stores the result in the buffer output. or decrypts it, and stores the result in the buffer output.
\return 0 Returned upon successfully encrypting or decrypting the input \return 0 Returned upon successfully encrypting or decrypting the input
\return BAD_FUNC_ARG returned if there is an error processing the ctx \return BAD_FUNC_ARG returned if there is an error processing the ctx
input argument input argument
\param ctx pointer to the ChaCha structure on which to set the iv \param ctx pointer to the ChaCha structure on which to set the iv
\param output pointer to a buffer in which to store the output ciphertext \param output pointer to a buffer in which to store the output ciphertext
or decrypted plaintext or decrypted plaintext
\param input pointer to the buffer containing the input plaintext to \param input pointer to the buffer containing the input plaintext to
encrypt or the input ciphertext to decrypt encrypt or the input ciphertext to decrypt
\param msglen length of the message to encrypt or the ciphertext to decrypt \param msglen length of the message to encrypt or the ciphertext to decrypt
@ -56,11 +56,11 @@ WOLFSSL_API int wc_Chacha_SetIV(ChaCha* ctx, const byte* inIv, word32 counter);
byte plain[] = { // initialize plaintext }; byte plain[] = { // initialize plaintext };
byte cipher[sizeof(plain)]; byte cipher[sizeof(plain)];
if( wc_Chacha_Process(&enc, cipher, plain, sizeof(plain)) != 0) { if( wc_Chacha_Process(&enc, cipher, plain, sizeof(plain)) != 0) {
// error processing ChaCha cipher // error processing ChaCha cipher
} }
\endcode \endcode
\sa wc_Chacha_SetKey \sa wc_Chacha_SetKey
\sa wc_Chacha_Process \sa wc_Chacha_Process
*/ */
@ -69,30 +69,30 @@ WOLFSSL_API int wc_Chacha_Process(ChaCha* ctx, byte* cipher, const byte* plain,
/*! /*!
\ingroup ChaCha \ingroup ChaCha
\brief This function sets the key for a ChaCha object, initializing it for \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 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. wc_Chacha_SetIV, and before using it for encryption with wc_Chacha_Process.
\return 0 Returned upon successfully setting the key \return 0 Returned upon successfully setting the key
\return BAD_FUNC_ARG returned if there is an error processing the ctx \return BAD_FUNC_ARG returned if there is an error processing the ctx
input argument or if the key is not 16 or 32 bytes long 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 ctx pointer to the ChaCha structure in which to set the key
\param key pointer to a buffer containing the 16 or 32 byte key with \param key pointer to a buffer containing the 16 or 32 byte key with
which to initialize the ChaCha structure which to initialize the ChaCha structure
\param keySz the length of the key passed in \param keySz the length of the key passed in
_Example_ _Example_
\code \code
ChaCha enc; ChaCha enc;
byte key[] = { // initialize key }; byte key[] = { // initialize key };
if( wc_Chacha_SetKey(&enc, key, sizeof(key)) != 0) { if( wc_Chacha_SetKey(&enc, key, sizeof(key)) != 0) {
// error initializing ChaCha structure // error initializing ChaCha structure
} }
\endcode \endcode
\sa wc_Chacha_SetIV \sa wc_Chacha_SetIV
\sa wc_Chacha_Process \sa wc_Chacha_Process
*/ */

62
doc/dox_comments/header_files/chacha20_poly1305.h
View File

@ -1,29 +1,29 @@
/*! /*!
\ingroup ChaCha20Poly1305 \ingroup ChaCha20Poly1305
\brief This function encrypts an input message, inPlaintext, using the \brief This function encrypts an input message, inPlaintext, using the
ChaCha20 stream cipher, into the output buffer, outCiphertext. It ChaCha20 stream cipher, into the output buffer, outCiphertext. It
also performs Poly-1305 authentication (on the cipher text), and also performs Poly-1305 authentication (on the cipher text), and
stores the generated authentication tag in the output buffer, outAuthTag. stores the generated authentication tag in the output buffer, outAuthTag.
\return 0 Returned upon successfully encrypting the message \return 0 Returned upon successfully encrypting the message
\return BAD_FUNC_ARG returned if there is an error during the encryption \return BAD_FUNC_ARG returned if there is an error during the encryption
process process
\param inKey pointer to a buffer containing the 32 byte key to use \param inKey pointer to a buffer containing the 32 byte key to use
for encryption for encryption
\param inIv pointer to a buffer containing the 12 byte iv to use for \param inIv pointer to a buffer containing the 12 byte iv to use for
encryption encryption
\param inAAD pointer to the buffer containing arbitrary length additional \param inAAD pointer to the buffer containing arbitrary length additional
authenticated data (AAD) authenticated data (AAD)
\param inAADLen length of the input AAD \param inAADLen length of the input AAD
\param inPlaintext pointer to the buffer containing the plaintext to \param inPlaintext pointer to the buffer containing the plaintext to
encrypt encrypt
\param inPlaintextLen the length of the plain text 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 outCiphertext pointer to the buffer in which to store the ciphertext
\param outAuthTag pointer to a 16 byte wide buffer in which to store the \param outAuthTag pointer to a 16 byte wide buffer in which to store the
authentication tag authentication tag
_Example_ _Example_
\code \code
byte key[] = { // initialize 32 byte key }; byte key[] = { // initialize 32 byte key };
@ -41,7 +41,7 @@
// error running encrypt // error running encrypt
} }
\endcode \endcode
\sa wc_ChaCha20Poly1305_Decrypt \sa wc_ChaCha20Poly1305_Decrypt
\sa wc_ChaCha_* \sa wc_ChaCha_*
\sa wc_Poly1305* \sa wc_Poly1305*
@ -56,32 +56,32 @@ int wc_ChaCha20Poly1305_Encrypt(
byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]); byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]);
/*! /*!
\ingroup ChaCha20Poly1305 \ingroup ChaCha20Poly1305
\brief This function decrypts input ciphertext, inCiphertext, using the \brief This function decrypts input ciphertext, inCiphertext, using the
ChaCha20 stream cipher, into the output buffer, outPlaintext. It also ChaCha20 stream cipher, into the output buffer, outPlaintext. It also
performs Poly-1305 authentication, comparing the given inAuthTag to an performs Poly-1305 authentication, comparing the given inAuthTag to an
authentication generated with the inAAD (arbitrary length additional authentication generated with the inAAD (arbitrary length additional
authentication data). Note: If the generated authentication tag does authentication data). Note: If the generated authentication tag does
not match the supplied authentication tag, the text is not decrypted. not match the supplied authentication tag, the text is not decrypted.
\return 0 Returned upon successfully decrypting the message \return 0 Returned upon successfully decrypting the message
\return BAD_FUNC_ARG Returned if any of the function arguments do not \return BAD_FUNC_ARG Returned if any of the function arguments do not
match what is expected match what is expected
\return MAC_CMP_FAILED_E Returned if the generated authentication tag \return MAC_CMP_FAILED_E Returned if the generated authentication tag
does not match the supplied inAuthTag. does not match the supplied inAuthTag.
\param inKey pointer to a buffer containing the 32 byte key to use for \param inKey pointer to a buffer containing the 32 byte key to use for
decryption decryption
\param inIv pointer to a buffer containing the 12 byte iv to use for \param inIv pointer to a buffer containing the 12 byte iv to use for
decryption decryption
\param inAAD pointer to the buffer containing arbitrary length additional \param inAAD pointer to the buffer containing arbitrary length additional
authenticated data (AAD) authenticated data (AAD)
\param inAADLen length of the input AAD \param inAADLen length of the input AAD
\param inCiphertext pointer to the buffer containing the ciphertext to \param inCiphertext pointer to the buffer containing the ciphertext to
decrypt decrypt
\param outCiphertextLen the length of the ciphertext to decrypt \param outCiphertextLen the length of the ciphertext to decrypt
\param inAuthTag pointer to the buffer containing the 16 byte digest \param inAuthTag pointer to the buffer containing the 16 byte digest
for authentication for authentication
\param outPlaintext pointer to the buffer in which to store the plaintext \param outPlaintext pointer to the buffer in which to store the plaintext
@ -105,7 +105,7 @@ int wc_ChaCha20Poly1305_Encrypt(
// error with function arguments // error with function arguments
} }
\endcode \endcode
\sa wc_ChaCha20Poly1305_Encrypt \sa wc_ChaCha20Poly1305_Encrypt
\sa wc_ChaCha_* \sa wc_ChaCha_*
\sa wc_Poly1305* \sa wc_Poly1305*

138
doc/dox_comments/header_files/coding.h
View File

@ -1,37 +1,37 @@
/*! /*!
\ingroup Base_Encoding \ingroup Base_Encoding
\brief This function decodes the given Base64 encoded input, in, and \brief This function decodes the given Base64 encoded input, in, and
stores the result in the output buffer out. It also sets the size stores the result in the output buffer out. It also sets the size
written to the output buffer in the variable outLen. written to the output buffer in the variable outLen.
\return 0 Returned upon successfully decoding the Base64 encoded input \return 0 Returned upon successfully decoding the Base64 encoded input
\return BAD_FUNC_ARG Returned if the output buffer is too small to \return BAD_FUNC_ARG Returned if the output buffer is too small to
store the decoded input store the decoded input
\return ASN_INPUT_E Returned if a character in the input buffer falls \return ASN_INPUT_E Returned if a character in the input buffer falls
outside of the Base64 range ([A-Za-z0-9+/=]) or if there is an invalid outside of the Base64 range ([A-Za-z0-9+/=]) or if there is an invalid
line ending in the Base64 encoded input line ending in the Base64 encoded input
\param in pointer to the input buffer to decode \param in pointer to the input buffer to decode
\param inLen length of the input buffer to decode \param inLen length of the input buffer to decode
\param out pointer to the output buffer in which to store the decoded \param out pointer to the output buffer in which to store the decoded
message message
\param outLen pointer to the length of the output buffer. Updated with \param outLen pointer to the length of the output buffer. Updated with
the bytes written at the end of the function call the bytes written at the end of the function call
_Example_ _Example_
\code \code
byte encoded[] = { // initialize text to decode }; byte encoded[] = { // initialize text to decode };
byte decoded[sizeof(encoded)]; byte decoded[sizeof(encoded)];
// requires at least (sizeof(encoded) * 3 + 3) / 4 room // requires at least (sizeof(encoded) * 3 + 3) / 4 room
int outLen = sizeof(decoded); int outLen = sizeof(decoded);
if( Base64_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) { if( Base64_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) {
// error decoding input buffer // error decoding input buffer
} }
\endcode \endcode
\sa Base64_Encode \sa Base64_Encode
\sa Base16_Decode \sa Base16_Decode
*/ */
@ -40,38 +40,38 @@ WOLFSSL_API int Base64_Decode(const byte* in, word32 inLen, byte* out,
/*! /*!
\ingroup Base_Encoding \ingroup Base_Encoding
\brief This function encodes the given input, in, and stores the Base64 \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 encoded result in the output buffer out. It writes the data with the
traditional ‘\n’ line endings, instead of escaped %0A line endings. Upon traditional ‘\n’ line endings, instead of escaped %0A line endings. Upon
successfully completing, this function also sets outLen to the number successfully completing, this function also sets outLen to the number
of bytes written to the output buffer. of bytes written to the output buffer.
\return 0 Returned upon successfully decoding the Base64 encoded input \return 0 Returned upon successfully decoding the Base64 encoded input
\return BAD_FUNC_ARG Returned if the output buffer is too small to \return BAD_FUNC_ARG Returned if the output buffer is too small to
store the encoded input store the encoded input
\return BUFFER_E Returned if the output buffer runs out of room \return BUFFER_E Returned if the output buffer runs out of room
while encoding while encoding
\param in pointer to the input buffer to encode \param in pointer to the input buffer to encode
\param inLen length of the input buffer to encode \param inLen length of the input buffer to encode
\param out pointer to the output buffer in which to store the \param out pointer to the output buffer in which to store the
encoded message encoded message
\param outLen pointer to the length of the output buffer in \param outLen pointer to the length of the output buffer in
which to store the encoded message which to store the encoded message
_Example_ _Example_
\code \code
byte plain[] = { // initialize text to encode }; byte plain[] = { // initialize text to encode };
byte encoded[MAX_BUFFER_SIZE]; byte encoded[MAX_BUFFER_SIZE];
int outLen = sizeof(encoded); int outLen = sizeof(encoded);
if( Base64_Encode(plain, sizeof(plain), encoded, &outLen) != 0 ) { if( Base64_Encode(plain, sizeof(plain), encoded, &outLen) != 0 ) {
// error encoding input buffer // error encoding input buffer
} }
\endcode \endcode
\sa Base64_EncodeEsc \sa Base64_EncodeEsc
\sa Base64_Decode \sa Base64_Decode
*/ */
@ -81,40 +81,40 @@ int Base64_Encode(const byte* in, word32 inLen, byte* out,
/*! /*!
\ingroup Base_Encoding \ingroup Base_Encoding
\brief This function encodes the given input, in, and stores the \brief This function encodes the given input, in, and stores the
Base64 encoded result in the output buffer out. It writes the data Base64 encoded result in the output buffer out. It writes the data
with %0A escaped line endings instead of ‘\n’ line endings. with %0A escaped line endings instead of ‘\n’ line endings.
Upon successfully completing, this function also sets outLen Upon successfully completing, this function also sets outLen
to the number of bytes written to the output buffer. to the number of bytes written to the output buffer.
\return 0 Returned upon successfully decoding the Base64 encoded input \return 0 Returned upon successfully decoding the Base64 encoded input
\return BAD_FUNC_ARG Returned if the output buffer is too small \return BAD_FUNC_ARG Returned if the output buffer is too small
to store the encoded input to store the encoded input
\return BUFFER_E Returned if the output buffer runs out of \return BUFFER_E Returned if the output buffer runs out of
room while encoding room while encoding
\return ASN_INPUT_E Returned if there is an error processing \return ASN_INPUT_E Returned if there is an error processing
the decode on the input message the decode on the input message
\param in pointer to the input buffer to encode \param in pointer to the input buffer to encode
\param inLen length of the input buffer to encode \param inLen length of the input buffer to encode
\param out pointer to the output buffer in which to store \param out pointer to the output buffer in which to store
the encoded message the encoded message
\param outLen pointer to the length of the output buffer in \param outLen pointer to the length of the output buffer in
which to store the encoded message which to store the encoded message
_Example_ _Example_
\code \code
byte plain[] = { // initialize text to encode }; byte plain[] = { // initialize text to encode };
byte encoded[MAX_BUFFER_SIZE]; byte encoded[MAX_BUFFER_SIZE];
int outLen = sizeof(encoded); int outLen = sizeof(encoded);
if( Base64_EncodeEsc(plain, sizeof(plain), encoded, &outLen) != 0 ) { if( Base64_EncodeEsc(plain, sizeof(plain), encoded, &outLen) != 0 ) {
// error encoding input buffer // error encoding input buffer
} }
\endcode \endcode
\sa Base64_Encode \sa Base64_Encode
\sa Base64_Decode \sa Base64_Decode
*/ */
@ -123,37 +123,37 @@ int Base64_EncodeEsc(const byte* in, word32 inLen, byte* out,
/*! /*!
\ingroup Base_Encoding \ingroup Base_Encoding
\brief This function encodes the given input, in, and stores the \brief This function encodes the given input, in, and stores the
Base64 encoded result in the output buffer out. It writes the data Base64 encoded result in the output buffer out. It writes the data
with no new lines. Upon successfully completing, this function with no new lines. Upon successfully completing, this function
also sets outLen to the number of bytes written to the output buffer also sets outLen to the number of bytes written to the output buffer
\return 0 Returned upon successfully decoding the Base64 encoded input \return 0 Returned upon successfully decoding the Base64 encoded input
\return BAD_FUNC_ARG Returned if the output buffer is too small \return BAD_FUNC_ARG Returned if the output buffer is too small
to store the encoded input to store the encoded input
\return BUFFER_E Returned if the output buffer runs out of room \return BUFFER_E Returned if the output buffer runs out of room
while encoding while encoding
\return ASN_INPUT_E Returned if there is an error processing the \return ASN_INPUT_E Returned if there is an error processing the
decode on the input message decode on the input message
\param in pointer to the input buffer to encode \param in pointer to the input buffer to encode
\param inLen length of the input buffer to encode \param inLen length of the input buffer to encode
\param out pointer to the output buffer in which to store the \param out pointer to the output buffer in which to store the
encoded message encoded message
\param outLen pointer to the length of the output buffer in which to \param outLen pointer to the length of the output buffer in which to
store the encoded message store the encoded message
_Example_ _Example_
\code \code
byte plain[] = { // initialize text to encode }; byte plain[] = { // initialize text to encode };
byte encoded[MAX_BUFFER_SIZE]; byte encoded[MAX_BUFFER_SIZE];
int outLen = sizeof(encoded); int outLen = sizeof(encoded);
if( Base64_Encode_NoNl(plain, sizeof(plain), encoded, &outLen) != 0 ) { if( Base64_Encode_NoNl(plain, sizeof(plain), encoded, &outLen) != 0 ) {
// error encoding input buffer // error encoding input buffer
} }
\endcode \endcode
\sa Base64_Encode \sa Base64_Encode
\sa Base64_Decode \sa Base64_Decode
*/ */
@ -163,35 +163,35 @@ int Base64_Encode_NoNl(const byte* in, word32 inLen, byte* out,
/*! /*!
\ingroup Base_Encoding \ingroup Base_Encoding
\brief This function decodes the given Base16 encoded input, in, and \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 stores the result in the output buffer out. It also sets the size written
to the output buffer in the variable outLen. to the output buffer in the variable outLen.
\return 0 Returned upon successfully decoding the Base16 encoded input \return 0 Returned upon successfully decoding the Base16 encoded input
\return BAD_FUNC_ARG Returned if the output buffer is too small to store \return BAD_FUNC_ARG Returned if the output buffer is too small to store
the decoded input or if the input length is not a multiple of two the decoded input or if the input length is not a multiple of two
\return ASN_INPUT_E Returned if a character in the input buffer falls \return ASN_INPUT_E Returned if a character in the input buffer falls
outside of the Base16 range ([0-9A-F]) outside of the Base16 range ([0-9A-F])
\param in pointer to the input buffer to decode \param in pointer to the input buffer to decode
\param inLen length of the input buffer to decode \param inLen length of the input buffer to decode
\param out pointer to the output buffer in which to store the decoded \param out pointer to the output buffer in which to store the decoded
message message
\param outLen pointer to the length of the output buffer. Updated with the \param outLen pointer to the length of the output buffer. Updated with the
bytes written at the end of the function call bytes written at the end of the function call
_Example_ _Example_
\code \code
byte encoded[] = { // initialize text to decode }; byte encoded[] = { // initialize text to decode };
byte decoded[sizeof(encoded)]; byte decoded[sizeof(encoded)];
int outLen = sizeof(decoded); int outLen = sizeof(decoded);
if( Base16_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) { if( Base16_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) {
// error decoding input buffer // error decoding input buffer
} }
\endcode \endcode
\sa Base64_Encode \sa Base64_Encode
\sa Base64_Decode \sa Base64_Decode
\sa Base16_Encode \sa Base16_Encode
@ -201,13 +201,13 @@ int Base16_Decode(const byte* in, word32 inLen, byte* out, word32* outLen);
/*! /*!
\ingroup Base_Encoding \ingroup Base_Encoding
\brief Encode input to base16 output. \brief Encode input to base16 output.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returns if in, out, or outLen is null or if outLen is \return BAD_FUNC_ARG Returns if in, out, or outLen is null or if outLen is
less than 2 times inLen plus 1. less than 2 times inLen plus 1.
\param in Pointer to input buffer to be encoded. \param in Pointer to input buffer to be encoded.
\param inLen Length of input buffer. \param inLen Length of input buffer.
\param out Pointer to output buffer. \param out Pointer to output buffer.
@ -221,10 +221,10 @@ int Base16_Decode(const byte* in, word32 inLen, byte* out, word32* outLen);
if(Base16_Encode(in, sizeof(in), out, &outSz) != 0) if(Base16_Encode(in, sizeof(in), out, &outSz) != 0)
{ {
// Handle encode error // Handle encode error
} }
\endcode \endcode
\sa Base64_Encode \sa Base64_Encode
\sa Base64_Decode \sa Base64_Decode
\sa Base16_Decode \sa Base16_Decode

58
doc/dox_comments/header_files/compress.h
View File

@ -1,72 +1,72 @@
/*! /*!
\ingroup Compression \ingroup Compression
\brief This function compresses the given input data using Huffman coding \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 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 larger than the input buffer because there exists a certain input for
which there will be no compression possible, which will still require a 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 lookup table. It is recommended that one allocate srcSz + 0.1% + 12 for
the output buffer. the output buffer.
\return On successfully compressing the input data, returns the number \return On successfully compressing the input data, returns the number
of bytes stored in the output buffer of bytes stored in the output buffer
\return COMPRESS_INIT_E Returned if there is an error initializing the \return COMPRESS_INIT_E Returned if there is an error initializing the
stream for compression stream for compression
\return COMPRESS_E Returned if an error occurs during compression \return COMPRESS_E Returned if an error occurs during compression
\param out pointer to the output buffer in which to store the compressed \param out pointer to the output buffer in which to store the compressed
data data
\param outSz size available in the output buffer for storage \param outSz size available in the output buffer for storage
\param in pointer to the buffer containing the message to compress \param in pointer to the buffer containing the message to compress
\param inSz size of the input message to compress \param inSz size of the input message to compress
\param flags flags to control how compression operates. Use 0 for normal \param flags flags to control how compression operates. Use 0 for normal
decompression decompression
_Example_ _Example_
\code \code
byte message[] = { // initialize text to compress }; byte message[] = { // initialize text to compress };
byte compressed[(sizeof(message) + sizeof(message) * .001 + 12 )]; byte compressed[(sizeof(message) + sizeof(message) * .001 + 12 )];
// Recommends at least srcSz + .1% + 12 // Recommends at least srcSz + .1% + 12
if( wc_Compress(compressed, sizeof(compressed), message, sizeof(message), if( wc_Compress(compressed, sizeof(compressed), message, sizeof(message),
0) != 0){ 0) != 0){
// error compressing data // error compressing data
} }
\endcode \endcode
\sa wc_DeCompress \sa wc_DeCompress
*/ */
WOLFSSL_API int wc_Compress(byte*, word32, const byte*, word32, word32); WOLFSSL_API int wc_Compress(byte*, word32, const byte*, word32, word32);
/*! /*!
\ingroup Compression \ingroup Compression
\brief This function decompresses the given compressed data using Huffman \brief This function decompresses the given compressed data using Huffman
coding and stores the output in out. coding and stores the output in out.
\return Succes On successfully decompressing the input data, returns the \return Succes On successfully decompressing the input data, returns the
number of bytes stored in the output buffer number of bytes stored in the output buffer
\return COMPRESS_INIT_E: Returned if there is an error initializing the \return COMPRESS_INIT_E: Returned if there is an error initializing the
stream for compression stream for compression
\return COMPRESS_E: Returned if an error occurs during compression \return COMPRESS_E: Returned if an error occurs during compression
\param out pointer to the output buffer in which to store the decompressed \param out pointer to the output buffer in which to store the decompressed
data data
\param outSz size available in the output buffer for storage \param outSz size available in the output buffer for storage
\param in pointer to the buffer containing the message to decompress \param in pointer to the buffer containing the message to decompress
\param inSz size of the input message to decompress \param inSz size of the input message to decompress
_Example_ _Example_
\code \code
byte compressed[] = { // initialize compressed message }; byte compressed[] = { // initialize compressed message };
byte decompressed[MAX_MESSAGE_SIZE]; byte decompressed[MAX_MESSAGE_SIZE];
if( wc_DeCompress(decompressed, sizeof(decompressed), if( wc_DeCompress(decompressed, sizeof(decompressed),
compressed, sizeof(compressed)) != 0 ) { compressed, sizeof(compressed)) != 0 ) {
// error decompressing data // error decompressing data
} }
\endcode \endcode
\sa wc_Compress \sa wc_Compress
*/ */
WOLFSSL_API int wc_DeCompress(byte*, word32, const byte*, word32); WOLFSSL_API int wc_DeCompress(byte*, word32, const byte*, word32);

290
doc/dox_comments/header_files/curve25519.h
View File

@ -1,24 +1,24 @@
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function generates a curve25519 key using the given random \brief This function generates a curve25519 key using the given random
number generator, rng, of the size given (keysize), and stores it in number generator, rng, of the size given (keysize), and stores it in
the given curve25519_key structure. It should be called after the key the given curve25519_key structure. It should be called after the key
structure has been initialized through wc_curve25519_init. structure has been initialized through wc_curve25519_init.
\return 0 Returned on successfully generating the key and and storing \return 0 Returned on successfully generating the key and and storing
it in the given curve25519_key structure it in the given curve25519_key structure
\return ECC_BAD_ARG_E Returned if rng or key evaluate to NULL, or \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 the input keysize does not correspond to the keysize for a
curve25519 key ( 32 bytes) curve25519 key ( 32 bytes)
\return RNG_FAILURE_E Returned if the rng internal status is not \return RNG_FAILURE_E Returned if the rng internal status is not
DRBG_OK or if there is in generating the next random block with rng 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 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 keysize size of the key to generate. Must be 32 bytes for curve25519
\param key pointer to the curve25519_key structure in which to \param key pointer to the curve25519_key structure in which to
store the generated key store the generated key
_Example_ _Example_
\code \code
curve25519_key key; curve25519_key key;
@ -26,11 +26,11 @@
WC_RNG rng; WC_RNG rng;
wc_InitRng(&rng); // initialize random number generator wc_InitRng(&rng); // initialize random number generator
if( wc_curve25519_make_key(&rng, 32, &key) != 0) { if( wc_curve25519_make_key(&rng, 32, &key) != 0) {
// making 25519 key // making 25519 key
} }
\endcode \endcode
\sa wc_curve25519_init \sa wc_curve25519_init
*/ */
WOLFSSL_API WOLFSSL_API
@ -38,25 +38,25 @@ int wc_curve25519_make_key(WC_RNG* rng, int keysize, curve25519_key* key);
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function computes a shared secret key given a secret private \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 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 buffer out and assigns the variable of the secret key to outlen. Only
supports big endian. supports big endian.
\return 0 Returned on successfully computing a shared secret key \return 0 Returned on successfully computing a shared secret key
\return BAD_FUNC_ARG Returned if any of the input parameters passed in \return BAD_FUNC_ARG Returned if any of the input parameters passed in
are NULL are NULL
\return ECC_BAD_ARG_E Returned if the first bit of the public key is \return ECC_BAD_ARG_E Returned if the first bit of the public key is
set, to avoid implementation fingerprinting set, to avoid implementation fingerprinting
\param private_key pointer to the curve25519_key structure initialized \param private_key pointer to the curve25519_key structure initialized
with the user’s private key with the user’s private key
\param public_key pointer to the curve25519_key structure containing \param public_key pointer to the curve25519_key structure containing
the received public key the received public key
\param out pointer to a buffer in which to store the 32 byte computed \param out pointer to a buffer in which to store the 32 byte computed
secret key secret key
\param outlen pointer in which to store the length written to the \param outlen pointer in which to store the length written to the
output buffer output buffer
_Example_ _Example_
@ -66,12 +66,12 @@ int wc_curve25519_make_key(WC_RNG* rng, int keysize, curve25519_key* key);
curve25519_key privKey, pubKey; curve25519_key privKey, pubKey;
// initialize both keys // initialize both keys
if ( wc_curve25519_shared_secret(&privKey, &pubKey, sharedKey, if ( wc_curve25519_shared_secret(&privKey, &pubKey, sharedKey,
&keySz) != 0 ) { &keySz) != 0 ) {
// error generating shared key // error generating shared key
} }
\endcode \endcode
\sa wc_curve25519_init \sa wc_curve25519_init
\sa wc_curve25519_make_key \sa wc_curve25519_make_key
\sa wc_curve25519_shared_secret_ex \sa wc_curve25519_shared_secret_ex
@ -83,27 +83,27 @@ int wc_curve25519_shared_secret(curve25519_key* private_key,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function computes a shared secret key given a secret private \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 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 buffer out and assigns the variable of the secret key to outlen. Supports
both big and little endian. both big and little endian.
\return 0 Returned on successfully computing a shared secret key \return 0 Returned on successfully computing a shared secret key
\return BAD_FUNC_ARG Returned if any of the input parameters passed in \return BAD_FUNC_ARG Returned if any of the input parameters passed in
are NULL are NULL
\return ECC_BAD_ARG_E Returned if the first bit of the public key is set, \return ECC_BAD_ARG_E Returned if the first bit of the public key is set,
to avoid implementation fingerprinting to avoid implementation fingerprinting
\param private_key pointer to the curve25519_key structure initialized \param private_key pointer to the curve25519_key structure initialized
with the user’s private key with the user’s private key
\param public_key pointer to the curve25519_key structure containing \param public_key pointer to the curve25519_key structure containing
the received public key the received public key
\param out pointer to a buffer in which to store the 32 byte computed \param out pointer to a buffer in which to store the 32 byte computed
secret key secret key
\param outlen pointer in which to store the length written to the output \param outlen pointer in which to store the length written to the output
buffer buffer
\param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
form to use. form to use.
_Example_ _Example_
@ -114,12 +114,12 @@ int wc_curve25519_shared_secret(curve25519_key* private_key,
curve25519_key privKey, pubKey; curve25519_key privKey, pubKey;
// initialize both keys // initialize both keys
if ( wc_curve25519_shared_secret_ex(&privKey, &pubKey, sharedKey, &keySz, if ( wc_curve25519_shared_secret_ex(&privKey, &pubKey, sharedKey, &keySz,
EC25519_BIG_ENDIAN) != 0 ) { EC25519_BIG_ENDIAN) != 0 ) {
// error generating shared key // error generating shared key
} }
\endcode \endcode
\sa wc_curve25519_init \sa wc_curve25519_init
\sa wc_curve25519_make_key \sa wc_curve25519_make_key
\sa wc_curve25519_shared_secret \sa wc_curve25519_shared_secret
@ -131,12 +131,12 @@ int wc_curve25519_shared_secret_ex(curve25519_key* private_key,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function initializes a curve25519 key. It should be called \brief This function initializes a curve25519 key. It should be called
before generating a key for the structure with wc_curve25519_init and before generating a key for the structure with wc_curve25519_init and
before using the key to encrypt data. before using the key to encrypt data.
\return 0 Returned on successfully initializing the curve25519_key \return 0 Returned on successfully initializing the curve25519_key
structure structure
\param key pointer to the curve25519_key structure to initialize \param key pointer to the curve25519_key structure to initialize
@ -147,7 +147,7 @@ int wc_curve25519_shared_secret_ex(curve25519_key* private_key,
wc_curve25519_init(&key); // initialize key wc_curve25519_init(&key); // initialize key
// make key and proceed to encryption // make key and proceed to encryption
\endcode \endcode
\sa wc_curve25519_make_key \sa wc_curve25519_make_key
*/ */
WOLFSSL_API WOLFSSL_API
@ -155,13 +155,13 @@ int wc_curve25519_init(curve25519_key* key);
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function frees a curve 25519 object. \brief This function frees a curve 25519 object.
\return none No returns. \return none No returns.
\param key pointer to the key object to free \param key pointer to the key object to free
_Example_ _Example_
\code \code
curve25519_key privKey; curve25519_key privKey;
@ -177,14 +177,14 @@ void wc_curve25519_free(curve25519_key* key);
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function imports a curve25519 private key only. (Big endian). \brief This function imports a curve25519 private key only. (Big endian).
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returns if key or priv is null. \return BAD_FUNC_ARG Returns if key or priv is null.
\return ECC_BAD_ARG_E Returns if privSz is not equal to \return ECC_BAD_ARG_E Returns if privSz is not equal to
wc_curve25519_size(key). wc_curve25519_size(key).
\param priv Private key buffer \param priv Private key buffer
\param privSz Size of private key buffer. \param privSz Size of private key buffer.
\param key The curve25519_key structure to store the private key. \param key The curve25519_key structure to store the private key.
@ -200,7 +200,7 @@ void wc_curve25519_free(curve25519_key* key);
// Some error was thrown // Some error was thrown
} }
\endcode \endcode
\sa wc_curve25519_import_private_ex \sa wc_curve25519_import_private_ex
\sa wc_curve25519_size \sa wc_curve25519_size
*/ */
@ -210,18 +210,18 @@ int wc_curve25519_import_private(const byte* priv, word32 privSz,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief curve25519 private key import only. (Big or Little endian). \brief curve25519 private key import only. (Big or Little endian).
\return 0 Success \return 0 Success
\return Returns if key or priv is null. \return Returns if key or priv is null.
\return ECC_BAD_ARG_E Returns if privSz is not equal to \return ECC_BAD_ARG_E Returns if privSz is not equal to
wc_curve25519_size(key). wc_curve25519_size(key).
\param priv Buffer for private key. \param priv Buffer for private key.
\param privSz Size of private key buffer. \param privSz Size of private key buffer.
\param key The curve25519_key structure to store the private key. \param key The curve25519_key structure to store the private key.
\param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to
set which form to use. set which form to use.
_Example_ _Example_
@ -230,14 +230,14 @@ int wc_curve25519_import_private(const byte* priv, word32 privSz,
curve25519_key key; curve25519_key key;
wc_curve25519_init(&key); wc_curve25519_init(&key);
if(wc_curve25519_import_private_ex(priv, sizeof(priv), &key, if(wc_curve25519_import_private_ex(priv, sizeof(priv), &key,
EC25519_BIG_ENDIAN) != 0) EC25519_BIG_ENDIAN) != 0)
{ {
// Some error was thrown // Some error was thrown
} }
\endcode \endcode
\sa wc_curve25519_import_private \sa wc_curve25519_import_private
\sa wc_curbe25519_size \sa wc_curbe25519_size
*/ */
@ -247,15 +247,15 @@ int wc_curve25519_import_private_ex(const byte* priv, word32 privSz,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function imports a public-private key pair into a \brief This function imports a public-private key pair into a
curve25519_key structure. Big endian only. curve25519_key structure. Big endian only.
\return 0 Returned on importing into the curve25519_key structure \return 0 Returned on importing into the curve25519_key structure
\return ECC_BAD_ARG_E Returned if any of the input parameters \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 are NULL, or the input key’s key size does not match the public
or private key sizes or private key sizes
\param priv pointer to a buffer containing the private key to import \param priv pointer to a buffer containing the private key to import
\param privSz length of 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 pub pointer to a buffer containing the public key to import
@ -272,19 +272,19 @@ int wc_curve25519_import_private_ex(const byte* priv, word32 privSz,
curve25519_key key; curve25519_key key;
wc_curve25519_init(&key); wc_curve25519_init(&key);
// initialize key // initialize key
ret = wc_curve25519_import_private_raw(&priv, sizeof(priv), pub, ret = wc_curve25519_import_private_raw(&priv, sizeof(priv), pub,
sizeof(pub),&key); sizeof(pub),&key);
if (ret != 0) { if (ret != 0) {
// error importing keys // error importing keys
} }
\endcode \endcode
\sa wc_curve25519_init \sa wc_curve25519_init
\sa wc_curve25519_make_key \sa wc_curve25519_make_key
\sa wc_curve25519_import_public \sa wc_curve25519_import_public
\sa wc_curve25519_export_private_raw \sa wc_curve25519_export_private_raw
*/ */
WOLFSSL_API WOLFSSL_API
int wc_curve25519_import_private_raw(const byte* priv, word32 privSz, int wc_curve25519_import_private_raw(const byte* priv, word32 privSz,
@ -292,19 +292,19 @@ int wc_curve25519_import_private_raw(const byte* priv, word32 privSz,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function imports a public-private key pair into a curve25519_key structure. Supports both big and little endian. \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 0 Returned on importing into the curve25519_key structure
\return ECC_BAD_ARG_E Returned if any of the input parameters are NULL, \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL,
or the input key’s key size does not match the public or private key sizes 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 priv pointer to a buffer containing the private key to import
\param privSz length of 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 pub pointer to a buffer containing the public key to import
\param pubSz length of 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 key pointer to the structure in which to store the imported keys
\param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set
which form to use. which form to use.
_Example_ _Example_
@ -316,9 +316,9 @@ int wc_curve25519_import_private_raw(const byte* priv, word32 privSz,
curve25519_key key; curve25519_key key;
wc_curve25519_init(&key); wc_curve25519_init(&key);
// initialize key // initialize key
ret = wc_curve25519_import_private_raw_ex(&priv, sizeof(priv), pub, ret = wc_curve25519_import_private_raw_ex(&priv, sizeof(priv), pub,
sizeof(pub),&key, EC25519_BIG_ENDIAN); sizeof(pub),&key, EC25519_BIG_ENDIAN);
if (ret != 0) { if (ret != 0) {
// error importing keys // error importing keys
@ -338,16 +338,16 @@ int wc_curve25519_import_private_raw_ex(const byte* priv, word32 privSz,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function exports a private key from a curve25519_key structure \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 and stores it in the given out buffer. It also sets outLen to be the size
of the exported key. Big Endian only. of the exported key. Big Endian only.
\return 0 Returned on successfully exporting the private key from the \return 0 Returned on successfully exporting the private key from the
curve25519_key structure curve25519_key structure
\return BAD_FUNC_ARG Returned if any input parameters are NULL. \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. \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 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 out pointer to the buffer in which to store the exported key
\param outLen will store the bytes written to the output buffer \param outLen will store the bytes written to the output buffer
@ -378,12 +378,12 @@ int wc_curve25519_export_private_raw(curve25519_key* key, byte* out,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function exports a private key from a curve25519_key structure \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 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. of the exported key. Can specify whether it's big or little endian.
\return 0 Returned on successfully exporting the private key from the \return 0 Returned on successfully exporting the private key from the
curve25519_key structure curve25519_key structure
\return BAD_FUNC_ARG Returned if any input parameters are NULL. \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. \return ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.
@ -391,7 +391,7 @@ int wc_curve25519_export_private_raw(curve25519_key* key, byte* out,
\param key pointer to the structure from which to export the key \param 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 out pointer to the buffer in which to store the exported key
\param outLen will store the bytes written to the output buffer \param outLen will store the bytes written to the output buffer
\param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
form to use. form to use.
_Example_ _Example_
@ -402,7 +402,7 @@ int wc_curve25519_export_private_raw(curve25519_key* key, byte* out,
int privSz; int privSz;
curve25519_key key; curve25519_key key;
// initialize and make key // initialize and make key
ret = wc_curve25519_export_private_raw_ex(&key, priv, &privSz, ret = wc_curve25519_export_private_raw_ex(&key, priv, &privSz,
EC25519_BIG_ENDIAN); EC25519_BIG_ENDIAN);
if (ret != 0) { if (ret != 0) {
// error exporting key // error exporting key
@ -421,20 +421,20 @@ int wc_curve25519_export_private_raw_ex(curve25519_key* key, byte* out,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function imports a public key from the given in buffer and \brief This function imports a public key from the given in buffer and
stores it in the curve25519_key structure. stores it in the curve25519_key structure.
\return 0 Returned on successfully importing the public key into the \return 0 Returned on successfully importing the public key into the
curve25519_key structure curve25519_key structure
\return ECC_BAD_ARG_E Returned if any of the input parameters are NULL, \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL,
or if the inLen or if the inLen
parameter does not match the key size of the key structure. parameter does not match the key size of the key structure.
\return BAD_FUNC_ARG Returned if any of the input parameters are NULL. \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 in pointer to the buffer containing the public key to import
\param inLen length of the public key to import \param inLen length of the public key to import
\param key pointer to the curve25519_key structure in which to store \param key pointer to the curve25519_key structure in which to store
the key the key
_Example_ _Example_
@ -452,7 +452,7 @@ parameter does not match the key size of the key structure.
// error exporting key // error exporting key
} }
\endcode \endcode
\sa wc_curve25519_init \sa wc_curve25519_init
\sa wc_curve25519_export_public \sa wc_curve25519_export_public
\sa wc_curve25519_import_private_raw \sa wc_curve25519_import_private_raw
@ -464,23 +464,23 @@ int wc_curve25519_import_public(const byte* in, word32 inLen,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function imports a public key from the given in buffer and \brief This function imports a public key from the given in buffer and
stores it in the curve25519_key structure. stores it in the curve25519_key structure.
\brief 0 Returned on successfully importing the public key into the \brief 0 Returned on successfully importing the public key into the
curve25519_key structure curve25519_key structure
\brief ECC_BAD_ARG_E Returned if the inLen parameter does not match the \brief ECC_BAD_ARG_E Returned if the inLen parameter does not match the
key size of the key structure key size of the key structure
\brief BAD_FUNC_ARG Returned if any of the input parameters are NULL. \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 in pointer to the buffer containing the public key to import
\param inLen length of the public key to import \param inLen length of the public key to import
\param key pointer to the curve25519_key structure in which to store \param key pointer to the curve25519_key structure in which to store
the key the key
\param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
form to use. form to use.
_Example_ _Example_
\code \code
int ret; int ret;
@ -489,7 +489,7 @@ int wc_curve25519_import_public(const byte* in, word32 inLen,
curve25519_key key; curve25519_key key;
// initialize key // initialize key
ret = wc_curve25519_import_public_ex(pub,sizeof(pub), &key, ret = wc_curve25519_import_public_ex(pub,sizeof(pub), &key,
EC25519_BIG_ENDIAN); EC25519_BIG_ENDIAN);
if (ret != 0) { if (ret != 0) {
// error exporting key // error exporting key
@ -508,19 +508,19 @@ int wc_curve25519_import_public_ex(const byte* in, word32 inLen,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function exports a public key from the given key structure and \brief This function exports a public key from the given key structure and
stores the result in the out buffer. Big endian only. stores the result in the out buffer. Big endian only.
\return 0 Returned on successfully exporting the public key from the \return 0 Returned on successfully exporting the public key from the
curve25519_key structure curve25519_key structure
\return ECC_BAD_ARG_E Returned if any of the input parameters are NULL \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL
\param key pointer to the curve25519_key structure in from which to \param key pointer to the curve25519_key structure in from which to
export the key export the key
\param out pointer to the buffer in which to store the public 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 outLen will store the bytes written to the output buffer
_Example_ _Example_
\code \code
int ret; int ret;
@ -533,7 +533,7 @@ int wc_curve25519_import_public_ex(const byte* in, word32 inLen,
// error exporting key // error exporting key
} }
\endcode \endcode
\sa wc_curve25519_init \sa wc_curve25519_init
\sa wc_curve25519_export_private_raw \sa wc_curve25519_export_private_raw
\sa wc_curve25519_import_public \sa wc_curve25519_import_public
@ -543,21 +543,21 @@ int wc_curve25519_export_public(curve25519_key* key, byte* out, word32* outLen);
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function exports a public key from the given key structure and \brief This function exports a public key from the given key structure and
stores the result in the out buffer. Supports both big and little endian. stores the result in the out buffer. Supports both big and little endian.
\return 0 Returned on successfully exporting the public key from the \return 0 Returned on successfully exporting the public key from the
curve25519_key structure curve25519_key structure
\return ECC_BAD_ARG_E Returned if any of the input parameters are NULL \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL
\param key pointer to the curve25519_key structure in from which to \param key pointer to the curve25519_key structure in from which to
export the key export the key
\param out pointer to the buffer in which to store the public 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 outLen will store the bytes written to the output buffer
\param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
form to use. form to use.
_Example_ _Example_
\code \code
int ret; int ret;
@ -572,7 +572,7 @@ int wc_curve25519_export_public(curve25519_key* key, byte* out, word32* outLen);
// error exporting key // error exporting key
} }
\endcode \endcode
\sa wc_curve25519_init \sa wc_curve25519_init
\sa wc_curve25519_export_private_raw \sa wc_curve25519_export_private_raw
\sa wc_curve25519_import_public \sa wc_curve25519_import_public
@ -583,19 +583,19 @@ int wc_curve25519_export_public_ex(curve25519_key* key, byte* out,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief Export curve25519 key pair. Big endian only. \brief Export curve25519 key pair. Big endian only.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returned if any input parameters are NULL. \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. \return ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.
\param key Description \param key Description
\param priv Private key buffer. \param priv Private key buffer.
\param privSz Size of private key buffer. \param privSz Size of private key buffer.
\param pub Public key buffer. \param pub Public key buffer.
\param pubSz Size of public key buffer. \param pubSz Size of public key buffer.
_Example_ _Example_
\code \code
int ret; int ret;
@ -612,7 +612,7 @@ int wc_curve25519_export_public_ex(curve25519_key* key, byte* out,
// error exporting key // error exporting key
} }
\endcode \endcode
\sa wc_curve25519_export_key_raw_ex \sa wc_curve25519_export_key_raw_ex
\sa wc_curve25519_export_private_raw \sa wc_curve25519_export_private_raw
\sa wc_curve25519_export_public_raw \sa wc_curve25519_export_public_raw
@ -624,19 +624,19 @@ int wc_curve25519_export_key_raw(curve25519_key* key,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief Export curve25519 key pair. Big or little endian. \brief Export curve25519 key pair. Big or little endian.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returned if any input parameters are NULL. \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. \return ECC_BAD_ARG_E Returned if wc_curve25519_size() is not equal to key.
\param key Description \param key Description
\param priv Private key buffer. \param priv Private key buffer.
\param privSz Size of private key buffer. \param privSz Size of private key buffer.
\param pub Public key buffer. \param pub Public key buffer.
\param pubSz Size of public key buffer. \param pubSz Size of public key buffer.
\param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which \param endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
form to use. form to use.
_Example_ _Example_
@ -651,13 +651,13 @@ int wc_curve25519_export_key_raw(curve25519_key* key,
curve25519_key key; curve25519_key key;
// initialize and make key // initialize and make key
ret = wc_curve25519_export_key_raw_ex(&key,priv, &privSz, pub, &pubSz, ret = wc_curve25519_export_key_raw_ex(&key,priv, &privSz, pub, &pubSz,
EC25519_BIG_ENDIAN); EC25519_BIG_ENDIAN);
if (ret != 0) { if (ret != 0) {
// error exporting key // error exporting key
} }
\endcode \endcode
\sa wc_curve25519_export_key_raw \sa wc_curve25519_export_key_raw
\sa wc_curve25519_export_private_raw_ex \sa wc_curve25519_export_private_raw_ex
\sa wc_curve25519_export_public_ex \sa wc_curve25519_export_public_ex
@ -670,16 +670,16 @@ int wc_curve25519_export_key_raw_ex(curve25519_key* key,
/*! /*!
\ingroup Curve25519 \ingroup Curve25519
\brief This function returns the key size of the given key structure. \brief This function returns the key size of the given key structure.
\return Success Given a valid, initialized curve25519_key structure, \return Success Given a valid, initialized curve25519_key structure,
returns the size of the key. returns the size of the key.
\return 0 Returned if key is NULL \return 0 Returned if key is NULL
\param key pointer to the curve25519_key structure in for which to \param key pointer to the curve25519_key structure in for which to
determine the key size determine the key size
_Example_ _Example_
\code \code
curve25519_key key; curve25519_key key;
@ -687,7 +687,7 @@ int wc_curve25519_export_key_raw_ex(curve25519_key* key,
int keySz; int keySz;
keySz = wc_curve25519_size(&key); keySz = wc_curve25519_size(&key);
\endcode \endcode
\sa wc_curve25519_init \sa wc_curve25519_init
\sa wc_curve25519_make_key \sa wc_curve25519_make_key
*/ */

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

@ -1,23 +1,23 @@
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function sets the key and initialization vector (iv) for the \brief This function sets the key and initialization vector (iv) for the
Des structure given as argument. It also initializes and allocates space Des structure given as argument. It also initializes and allocates space
for the buffers needed for encryption and decryption, if these have not 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) yet been initialized. Note: If no iv is provided (i.e. iv == NULL)
the initialization vector defaults to an iv of 0. the initialization vector defaults to an iv of 0.
\return 0 On successfully setting the key and initialization vector for \return 0 On successfully setting the key and initialization vector for
the Des structure the Des structure
\param des pointer to the Des structure to initialize \param des pointer to the Des structure to initialize
\param key pointer to the buffer containing the 8 byte key with which to \param key pointer to the buffer containing the 8 byte key with which to
initialize the Des structure initialize the Des structure
\param iv pointer to the buffer containing the 8 byte iv with which to \param iv pointer to the buffer containing the 8 byte iv with which to
initialize the Des structure. If this is not provided, the iv defaults to 0 initialize the Des structure. If this is not provided, the iv defaults to 0
\param dir direction of encryption. Valid options are: DES_ENCRYPTION, \param dir direction of encryption. Valid options are: DES_ENCRYPTION,
and DES_DECRYPTION and DES_DECRYPTION
_Example_ _Example_
\code \code
Des enc; // Des structure used for encryption Des enc; // Des structure used for encryption
@ -30,7 +30,7 @@
// error initializing des structure // error initializing des structure
} }
\endcode \endcode
\sa wc_Des_SetIV \sa wc_Des_SetIV
\sa wc_Des3_SetKey \sa wc_Des3_SetKey
*/ */
@ -39,15 +39,15 @@ WOLFSSL_API int wc_Des_SetKey(Des* des, const byte* key,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function sets the initialization vector (iv) for the Des \brief This function sets the initialization vector (iv) for the Des
structure given as argument. When passed a NULL iv, it sets the structure given as argument. When passed a NULL iv, it sets the
initialization vector to 0. initialization vector to 0.
\return none No returns. \return none No returns.
\param des pointer to the Des structure for which to set the iv \param des pointer to the Des structure for which to set the iv
\param iv pointer to the buffer containing the 8 byte iv with which to \param iv pointer to the buffer containing the 8 byte iv with which to
initialize the Des structure. If this is not provided, the iv defaults to 0 initialize the Des structure. If this is not provided, the iv defaults to 0
_Example_ _Example_
@ -58,20 +58,20 @@ WOLFSSL_API int wc_Des_SetKey(Des* des, const byte* key,
wc_Des_SetIV(&enc, iv); wc_Des_SetIV(&enc, iv);
} }
\endcode \endcode
\sa wc_Des_SetKey \sa wc_Des_SetKey
*/ */
WOLFSSL_API void wc_Des_SetIV(Des* des, const byte* iv); WOLFSSL_API void wc_Des_SetIV(Des* des, const byte* iv);
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function encrypts the input message, in, and stores the result \brief This function encrypts the input message, in, and stores the result
in the output buffer, out. It uses DES encryption with cipher block in the output buffer, out. It uses DES encryption with cipher block
chaining (CBC) mode. chaining (CBC) mode.
\return 0 Returned upon successfully encrypting the given input message \return 0 Returned upon successfully encrypting the given input message
\param des pointer to the Des structure to use for encryption \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 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 in pointer to the input buffer containing the message to encrypt
@ -85,11 +85,11 @@ WOLFSSL_API void wc_Des_SetIV(Des* des, const byte* iv);
byte plain[] = { // initialize with message }; byte plain[] = { // initialize with message };
byte cipher[sizeof(plain)]; byte cipher[sizeof(plain)];
if ( wc_Des_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) { if ( wc_Des_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) {
// error encrypting message // error encrypting message
} }
\endcode \endcode
\sa wc_Des_SetKey \sa wc_Des_SetKey
\sa wc_Des_CbcDecrypt \sa wc_Des_CbcDecrypt
*/ */
@ -98,18 +98,18 @@ WOLFSSL_API int wc_Des_CbcEncrypt(Des* des, byte* out,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function decrypts the input ciphertext, in, and stores the \brief This function decrypts the input ciphertext, in, and stores the
resulting plaintext in the output buffer, out. It uses DES encryption resulting plaintext in the output buffer, out. It uses DES encryption
with cipher block chaining (CBC) mode. with cipher block chaining (CBC) mode.
\return 0 Returned upon successfully decrypting the given ciphertext \return 0 Returned upon successfully decrypting the given ciphertext
\param des pointer to the Des structure to use for decryption \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 out pointer to the buffer in which to store the decrypted plaintext
\param in pointer to the input buffer containing the encrypted ciphertext \param in pointer to the input buffer containing the encrypted ciphertext
\param sz length of the ciphertext to decrypt \param sz length of the ciphertext to decrypt
_Example_ _Example_
\code \code
Des dec; // Des structure used for decryption Des dec; // Des structure used for decryption
@ -118,11 +118,11 @@ WOLFSSL_API int wc_Des_CbcEncrypt(Des* des, byte* out,
byte cipher[] = { // initialize with ciphertext }; byte cipher[] = { // initialize with ciphertext };
byte decoded[sizeof(cipher)]; byte decoded[sizeof(cipher)];
if ( wc_Des_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) { if ( wc_Des_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) {
// error decrypting message // error decrypting message
} }
\endcode \endcode
\sa wc_Des_SetKey \sa wc_Des_SetKey
\sa wc_Des_CbcEncrypt \sa wc_Des_CbcEncrypt
*/ */
@ -131,13 +131,13 @@ WOLFSSL_API int wc_Des_CbcDecrypt(Des* des, byte* out,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function encrypts the input message, in, and stores the result \brief This function encrypts the input message, in, and stores the result
in the output buffer, out. It uses Des encryption with Electronic in the output buffer, out. It uses Des encryption with Electronic
Codebook (ECB) mode. Codebook (ECB) mode.
\return 0: Returned upon successfully encrypting the given plaintext. \return 0: Returned upon successfully encrypting the given plaintext.
\param des pointer to the Des structure to use for encryption \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 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 in pointer to the input buffer containing the plaintext to encrypt
@ -151,11 +151,11 @@ WOLFSSL_API int wc_Des_CbcDecrypt(Des* des, byte* out,
byte plain[] = { // initialize with message to encrypt }; byte plain[] = { // initialize with message to encrypt };
byte cipher[sizeof(plain)]; byte cipher[sizeof(plain)];
if ( wc_Des_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) { if ( wc_Des_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) {
// error encrypting message // error encrypting message
} }
\endcode \endcode
\sa wc_Des_SetKe \sa wc_Des_SetKe
*/ */
WOLFSSL_API int wc_Des_EcbEncrypt(Des* des, byte* out, WOLFSSL_API int wc_Des_EcbEncrypt(Des* des, byte* out,
@ -163,15 +163,15 @@ WOLFSSL_API int wc_Des_EcbEncrypt(Des* des, byte* out,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function encrypts the input message, in, and stores the \brief This function encrypts the input message, in, and stores the
result in the output buffer, out. It uses Des3 encryption with result in the output buffer, out. It uses Des3 encryption with
Electronic Codebook (ECB) mode. Warning: In nearly all use cases ECB Electronic Codebook (ECB) mode. Warning: In nearly all use cases ECB
mode is considered to be less secure. Please avoid using ECB API’s mode is considered to be less secure. Please avoid using ECB API’s
directly whenever possible. directly whenever possible.
\return 0 Returned upon successfully encrypting the given plaintext \return 0 Returned upon successfully encrypting the given plaintext
\param des3 pointer to the Des3 structure to use for encryption \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 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 in pointer to the input buffer containing the plaintext to encrypt
@ -185,11 +185,11 @@ WOLFSSL_API int wc_Des_EcbEncrypt(Des* des, byte* out,
byte plain[] = { // initialize with message to encrypt }; byte plain[] = { // initialize with message to encrypt };
byte cipher[sizeof(plain)]; byte cipher[sizeof(plain)];
if ( wc_Des3_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) { if ( wc_Des3_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) {
// error encrypting message // error encrypting message
} }
/endcode /endcode
\sa wc_Des3_SetKey \sa wc_Des3_SetKey
*/ */
WOLFSSL_API int wc_Des3_EcbEncrypt(Des3* des, byte* out, WOLFSSL_API int wc_Des3_EcbEncrypt(Des3* des, byte* out,
@ -197,25 +197,25 @@ WOLFSSL_API int wc_Des3_EcbEncrypt(Des3* des, byte* out,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function sets the key and initialization vector (iv) for \brief This function sets the key and initialization vector (iv) for
the Des3 structure given as argument. It also initializes and allocates the Des3 structure given as argument. It also initializes and allocates
space for the buffers needed for encryption and decryption, if these 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 == have not yet been initialized. Note: If no iv is provided (i.e. iv ==
NULL) the initialization vector defaults to an iv of 0. NULL) the initialization vector defaults to an iv of 0.
\return 0 On successfully setting the key and initialization vector \return 0 On successfully setting the key and initialization vector
for the Des structure for the Des structure
\param des3 pointer to the Des3 structure to initialize \param des3 pointer to the Des3 structure to initialize
\param key pointer to the buffer containing the 24 byte key with which \param key pointer to the buffer containing the 24 byte key with which
to initialize the Des3 structure to initialize the Des3 structure
\param iv pointer to the buffer containing the 8 byte iv with which to \param iv pointer to the buffer containing the 8 byte iv with which to
initialize the Des3 structure. If this is not provided, the iv defaults initialize the Des3 structure. If this is not provided, the iv defaults
to 0 to 0
\param dir direction of encryption. Valid options are: DES_ENCRYPTION, \param dir direction of encryption. Valid options are: DES_ENCRYPTION,
and DES_DECRYPTION and DES_DECRYPTION
_Example_ _Example_
\code \code
Des3 enc; // Des3 structure used for encryption Des3 enc; // Des3 structure used for encryption
@ -228,7 +228,7 @@ WOLFSSL_API int wc_Des3_EcbEncrypt(Des3* des, byte* out,
// error initializing des structure // error initializing des structure
} }
\endcode \endcode
\sa wc_Des3_SetIV \sa wc_Des3_SetIV
\sa wc_Des3_CbcEncrypt \sa wc_Des3_CbcEncrypt
\sa wc_Des3_CbcDecrypt \sa wc_Des3_CbcDecrypt
@ -238,16 +238,16 @@ WOLFSSL_API int wc_Des3_SetKey(Des3* des, const byte* key,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function sets the initialization vector (iv) for the Des3 \brief This function sets the initialization vector (iv) for the Des3
structure given as argument. When passed a NULL iv, it sets the structure given as argument. When passed a NULL iv, it sets the
initialization vector to 0. initialization vector to 0.
\return none No returns. \return none No returns.
\param des pointer to the Des3 structure for which to set the iv \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 \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 initialize the Des3 structure. If this is not provided, the iv
defaults to 0 defaults to 0
_Example_ _Example_
@ -260,25 +260,25 @@ WOLFSSL_API int wc_Des3_SetKey(Des3* des, const byte* key,
wc_Des3_SetIV(&enc, iv); wc_Des3_SetIV(&enc, iv);
} }
\endcode \endcode
\sa wc_Des3_SetKey \sa wc_Des3_SetKey
*/ */
WOLFSSL_API int wc_Des3_SetIV(Des3* des, const byte* iv); WOLFSSL_API int wc_Des3_SetIV(Des3* des, const byte* iv);
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function encrypts the input message, in, and stores the \brief This function encrypts the input message, in, and stores the
result in the output buffer, out. It uses Triple Des (3DES) encryption result in the output buffer, out. It uses Triple Des (3DES) encryption
with cipher block chaining (CBC) mode. with cipher block chaining (CBC) mode.
\return 0 Returned upon successfully encrypting the given input message \return 0 Returned upon successfully encrypting the given input message
\param des pointer to the Des3 structure to use for encryption \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 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 in pointer to the input buffer containing the message to encrypt
\param sz length of the message to encrypt \param sz length of the message to encrypt
_Example_ _Example_
\code \code
Des3 enc; // Des3 structure used for encryption Des3 enc; // Des3 structure used for encryption
@ -287,11 +287,11 @@ WOLFSSL_API int wc_Des3_SetIV(Des3* des, const byte* iv);
byte plain[] = { // initialize with message }; byte plain[] = { // initialize with message };
byte cipher[sizeof(plain)]; byte cipher[sizeof(plain)];
if ( wc_Des3_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) { if ( wc_Des3_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) {
// error encrypting message // error encrypting message
} }
\endcode \endcode
\sa wc_Des3_SetKey \sa wc_Des3_SetKey
\sa wc_Des3_CbcDecrypt \sa wc_Des3_CbcDecrypt
*/ */
@ -300,18 +300,18 @@ WOLFSSL_API int wc_Des3_CbcEncrypt(Des3* des, byte* out,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function decrypts the input ciphertext, in, and stores the \brief This function decrypts the input ciphertext, in, and stores the
resulting plaintext in the output buffer, out. It uses Triple Des (3DES) resulting plaintext in the output buffer, out. It uses Triple Des (3DES)
encryption with cipher block chaining (CBC) mode. encryption with cipher block chaining (CBC) mode.
\return 0 Returned upon successfully decrypting the given ciphertext \return 0 Returned upon successfully decrypting the given ciphertext
\param des pointer to the Des3 structure to use for decryption \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 out pointer to the buffer in which to store the decrypted plaintext
\param in pointer to the input buffer containing the encrypted ciphertext \param in pointer to the input buffer containing the encrypted ciphertext
\param sz length of the ciphertext to decrypt \param sz length of the ciphertext to decrypt
_Example_ _Example_
\code \code
Des3 dec; // Des structure used for decryption Des3 dec; // Des structure used for decryption
@ -320,7 +320,7 @@ WOLFSSL_API int wc_Des3_CbcEncrypt(Des3* des, byte* out,
byte cipher[] = { // initialize with ciphertext }; byte cipher[] = { // initialize with ciphertext };
byte decoded[sizeof(cipher)]; byte decoded[sizeof(cipher)];
if ( wc_Des3_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) { if ( wc_Des3_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) {
// error decrypting message // error decrypting message
} }
\endcode \endcode

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

@ -1,20 +1,20 @@
/*! /*!
\ingroup Diffie-Hellman \ingroup Diffie-Hellman
\brief This function initializes a Diffie-Hellman key for use in \brief This function initializes a Diffie-Hellman key for use in
negotiating a secure secret key with the Diffie-Hellman exchange protocol. negotiating a secure secret key with the Diffie-Hellman exchange protocol.
\return none No returns. \return none No returns.
\param key pointer to the DhKey structure to initialize for use with \param key pointer to the DhKey structure to initialize for use with
secure key exchanges secure key exchanges
_Example_ _Example_
\code \code
DhKey key; DhKey key;
wc_InitDhKey(&key); // initialize DH key wc_InitDhKey(&key); // initialize DH key
\endcode \endcode
\sa wc_FreeDhKey \sa wc_FreeDhKey
\sa wc_DhGenerateKeyPair \sa wc_DhGenerateKeyPair
*/ */
@ -22,50 +22,50 @@ WOLFSSL_API int wc_InitDhKey(DhKey* key);
/*! /*!
\ingroup Diffie-Hellman \ingroup Diffie-Hellman
\brief This function frees a Diffie-Hellman key after it has been used to \brief This function frees a Diffie-Hellman key after it has been used to
negotiate a secure secret key with the Diffie-Hellman exchange protocol. negotiate a secure secret key with the Diffie-Hellman exchange protocol.
\return none No returns. \return none No returns.
\param key pointer to the DhKey structure to free \param key pointer to the DhKey structure to free
_Example_ _Example_
\code \code
DhKey key; DhKey key;
// initialize key, perform key exchange // initialize key, perform key exchange
wc_FreeDhKey(&key); // free DH key to avoid memory leaks wc_FreeDhKey(&key); // free DH key to avoid memory leaks
\endcode \endcode
\sa wc_InitDhKey \sa wc_InitDhKey
*/ */
WOLFSSL_API void wc_FreeDhKey(DhKey* key); WOLFSSL_API void wc_FreeDhKey(DhKey* key);
/*! /*!
\ingroup Diffie-Hellman \ingroup Diffie-Hellman
\brief This function generates a public/private key pair based on the \brief This function generates a public/private key pair based on the
Diffie-Hellman public parameters, storing the private key in priv and 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 public key in pub. It takes an initialized Diffie-Hellman key and an
initialized rng structure. initialized rng structure.
\return BAD_FUNC_ARG Returned if there is an error parsing one of the \return BAD_FUNC_ARG Returned if there is an error parsing one of the
inputs to this function inputs to this function
\return RNG_FAILURE_E Returned if there is an error generating a random \return RNG_FAILURE_E Returned if there is an error generating a random
number using rng number using rng
\return MP_INIT_E May be returned if there is an error in the math library \return MP_INIT_E May be returned if there is an error in the math library
while generating the public key while generating the public key
\return MP_READ_E May be returned if there is an error in the math library \return MP_READ_E May be returned if there is an error in the math library
while generating the public key while generating the public key
\return MP_EXPTMOD_E May be returned if there is an error in the math \return MP_EXPTMOD_E May be returned if there is an error in the math
library while generating the public key library while generating the public key
\return MP_TO_E May be returned if there is an error in the math library \return MP_TO_E May be returned if there is an error in the math library
while generating the public key while generating the public key
\param key pointer to the DhKey structure from which to generate \param key pointer to the DhKey structure from which to generate
the key pair the key pair
\param rng pointer to an initialized random number generator (rng) with \param rng pointer to an initialized random number generator (rng) with
which to generate the keys which to generate the keys
\param priv pointer to a buffer in which to store the private key \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 privSz will store the size of the private key written to priv
@ -86,7 +86,7 @@ WOLFSSL_API void wc_FreeDhKey(DhKey* key);
wc_InitRng(&rng); // initialize rng wc_InitRng(&rng); // initialize rng
ret = wc_DhGenerateKeyPair(&key, &rng, priv, &privSz, pub, &pubSz); ret = wc_DhGenerateKeyPair(&key, &rng, priv, &privSz, pub, &pubSz);
\endcode \endcode
\sa wc_InitDhKey \sa wc_InitDhKey
\sa wc_DhSetKey \sa wc_DhSetKey
\sa wc_DhKeyDecode \sa wc_DhKeyDecode
@ -96,32 +96,32 @@ WOLFSSL_API int wc_DhGenerateKeyPair(DhKey* key, WC_RNG* rng, byte* priv,
/*! /*!
\ingroup Diffie-Hellman \ingroup Diffie-Hellman
\brief This function generates an agreed upon secret key based on a local \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 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 exchange, this function generates an agreed upon secret key for symmetric
communication. On successfully generating a shared secret key, the size of communication. On successfully generating a shared secret key, the size of
the secret key written will be stored in agreeSz. the secret key written will be stored in agreeSz.
\return 0 Returned on successfully generating an agreed upon secret key \return 0 Returned on successfully generating an agreed upon secret key
\return MP_INIT_E May be returned if there is an error while generating \return MP_INIT_E May be returned if there is an error while generating
the shared secret key the shared secret key
\return MP_READ_E May be returned if there is an error while generating \return MP_READ_E May be returned if there is an error while generating
the shared secret key the shared secret key
\return MP_EXPTMOD_E May be returned if there is an error while generating \return MP_EXPTMOD_E May be returned if there is an error while generating
the shared secret key the shared secret key
\return MP_TO_E May be returned if there is an error while generating the \return MP_TO_E May be returned if there is an error while generating the
shared secret key shared secret key
\param key pointer to the DhKey structure to use to compute the shared 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 agree pointer to the buffer in which to store the secret key
\param agreeSz will hold the size of the secret key after \param agreeSz will hold the size of the secret key after
successful generation successful generation
\param priv pointer to the buffer containing the local secret key \param priv pointer to the buffer containing the local secret key
\param privSz size of the local secret key \param privSz size of the local secret key
\param otherPub pointer to a buffer containing the received public key \param otherPub pointer to a buffer containing the received public key
\param pubSz size of the received public key \param pubSz size of the received public key
_Example_ _Example_
\code \code
DhKey key; DhKey key;
@ -133,13 +133,13 @@ WOLFSSL_API int wc_DhGenerateKeyPair(DhKey* key, WC_RNG* rng, byte* priv,
// initialize key, set key prime and base // initialize key, set key prime and base
// wc_DhGenerateKeyPair -- store private key in priv // wc_DhGenerateKeyPair -- store private key in priv
byte pub[] = { // initialized with the received public key }; byte pub[] = { // initialized with the received public key };
ret = wc_DhAgree(&key, agree, &agreeSz, priv, sizeof(priv), pub, ret = wc_DhAgree(&key, agree, &agreeSz, priv, sizeof(priv), pub,
sizeof(pub)); sizeof(pub));
if ( ret != 0 ) { if ( ret != 0 ) {
// error generating shared key // error generating shared key
} }
\endcode \endcode
\sa wc_DhGenerateKeyPair \sa wc_DhGenerateKeyPair
*/ */
WOLFSSL_API int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz, WOLFSSL_API int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz,
@ -148,23 +148,23 @@ WOLFSSL_API int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz,
/*! /*!
\ingroup Diffie-Hellman \ingroup Diffie-Hellman
\brief This function decodes a Diffie-Hellman key from the given input \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 buffer containing the key in DER format. It stores the result in the
DhKey structure. DhKey structure.
\return 0 Returned on successfully decoding the input key \return 0 Returned on successfully decoding the input key
\return ASN_PARSE_E Returned if there is an error parsing the sequence \return ASN_PARSE_E Returned if there is an error parsing the sequence
of the input of the input
\return ASN_DH_KEY_E Returned if there is an error reading the private \return ASN_DH_KEY_E Returned if there is an error reading the private
key parameters from the parsed input key parameters from the parsed input
\param input pointer to the buffer containing the DER formatted \param input pointer to the buffer containing the DER formatted
Diffie-Hellman key Diffie-Hellman key
\param inOutIdx pointer to an integer in which to store the index parsed \param inOutIdx pointer to an integer in which to store the index parsed
to while decoding the key to while decoding the key
\param key pointer to the DhKey structure to initialize with the input key \param key pointer to the DhKey structure to initialize with the input key
\param inSz length of the input buffer. Gives the max length that may \param inSz length of the input buffer. Gives the max length that may
be read be read
_Example_ _Example_
@ -172,7 +172,7 @@ WOLFSSL_API int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz,
DhKey key; DhKey key;
word32 idx = 0; word32 idx = 0;
byte keyBuff[1024]; byte keyBuff[1024];
// initialize with DER formatted key // initialize with DER formatted key
wc_DhKeyInit(&key); wc_DhKeyInit(&key);
ret = wc_DhKeyDecode(keyBuff, &idx, &key, sizeof(keyBuff)); ret = wc_DhKeyDecode(keyBuff, &idx, &key, sizeof(keyBuff));
@ -181,7 +181,7 @@ WOLFSSL_API int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz,
// error decoding key // error decoding key
} }
\endcode \endcode
\sa wc_DhSetKey \sa wc_DhSetKey
*/ */
WOLFSSL_API int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key, WOLFSSL_API int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key,
@ -189,18 +189,18 @@ WOLFSSL_API int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key,
/*! /*!
\ingroup Diffie-Hellman \ingroup Diffie-Hellman
\brief This function sets the key for a DhKey structure using the input \brief This function sets the key for a DhKey structure using the input
private key parameters. Unlike wc_DhKeyDecode, this function does not private key parameters. Unlike wc_DhKeyDecode, this function does not
require that the input key be formatted in DER format, and instead simply require that the input key be formatted in DER format, and instead simply
accepts the parsed input parameters p (prime) and g (base). accepts the parsed input parameters p (prime) and g (base).
\return 0 Returned on successfully setting the key \return 0 Returned on successfully setting the key
\return BAD_FUNC_ARG Returned if any of the input parameters \return BAD_FUNC_ARG Returned if any of the input parameters
evaluate to NULL evaluate to NULL
\return MP_INIT_E Returned if there is an error initializing the key \return MP_INIT_E Returned if there is an error initializing the key
parameters for storage parameters for storage
\return ASN_DH_KEY_E Returned if there is an error reading in the \return ASN_DH_KEY_E Returned if there is an error reading in the
DH key parameters p and g DH key parameters p and g
\param key pointer to the DhKey structure on which to set the key \param key pointer to the DhKey structure on which to set the key
@ -208,7 +208,7 @@ WOLFSSL_API int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key,
\param pSz length of the input prime \param pSz length of the input prime
\param g pointer to the buffer containing the base for use with the key \param g pointer to the buffer containing the base for use with the key
\param gSz length of the input base \param gSz length of the input base
_Example_ _Example_
\code \code
DhKey key; DhKey key;
@ -222,7 +222,7 @@ WOLFSSL_API int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key,
// error setting key // error setting key
} }
\endcode \endcode
\sa wc_DhKeyDecode \sa wc_DhKeyDecode
*/ */
WOLFSSL_API int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g, WOLFSSL_API int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g,
@ -230,26 +230,26 @@ WOLFSSL_API int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g
/*! /*!
\ingroup Diffie-Hellman \ingroup Diffie-Hellman
\brief This function loads the Diffie-Hellman parameters, p (prime) \brief This function loads the Diffie-Hellman parameters, p (prime)
and g (base) out of the given input buffer, DER formatted. and g (base) out of the given input buffer, DER formatted.
\return 0 Returned on successfully extracting the DH parameters \return 0 Returned on successfully extracting the DH parameters
\return ASN_PARSE_E Returned if an error occurs while parsing the DER \return ASN_PARSE_E Returned if an error occurs while parsing the DER
formatted DH certificate formatted DH certificate
\return BUFFER_E Returned if there is inadequate space in p or g to \return BUFFER_E Returned if there is inadequate space in p or g to
store the parsed parameters store the parsed parameters
\parma input pointer to a buffer containing a DER formatted \parma input pointer to a buffer containing a DER formatted
Diffie-Hellman certificate to parse Diffie-Hellman certificate to parse
\parma inSz size of the input buffer \parma inSz size of the input buffer
\parma p pointer to a buffer in which to store the parsed prime \parma p pointer to a buffer in which to store the parsed prime
\parma pInOutSz pointer to a word32 object containing the available \parma pInOutSz pointer to a word32 object containing the available
size in the p buffer. Will be overwritten with the number of bytes size in the p buffer. Will be overwritten with the number of bytes
written to the buffer after completing the function call written to the buffer after completing the function call
\parma g pointer to a buffer in which to store the parsed base \parma g pointer to a buffer in which to store the parsed base
\parma gInOutSz pointer to a word32 object containing the available size \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 in the g buffer. Will be overwritten with the number of bytes written to
the buffer after completing the function call the buffer after completing the function call
_Example_ _Example_
@ -265,7 +265,7 @@ WOLFSSL_API int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g
// error parsing inputs // error parsing inputs
} }
\endcode \endcode
\sa wc_DhSetKey \sa wc_DhSetKey
\sa wc_DhKeyDecode \sa wc_DhKeyDecode
*/ */

182
doc/dox_comments/header_files/dsa.h
View File

@ -1,34 +1,34 @@
/*! /*!
\ingroup DSA \ingroup DSA
\brief This function initializes a DsaKey object in order to use it for \brief This function initializes a DsaKey object in order to use it for
authentication via the Digital Signature Algorithm (DSA). authentication via the Digital Signature Algorithm (DSA).
\return 0 Returned on success. \return 0 Returned on success.
\return BAD_FUNC_ARG Returned if a NULL key is passed in. \return BAD_FUNC_ARG Returned if a NULL key is passed in.
\param key pointer to the DsaKey structure to initialize \param key pointer to the DsaKey structure to initialize
_Example_ _Example_
\code \code
DsaKey key; DsaKey key;
int ret; int ret;
ret = wc_InitDsaKey(&key); // initialize DSA key ret = wc_InitDsaKey(&key); // initialize DSA key
\endcode \endcode
\sa wc_FreeDsaKey \sa wc_FreeDsaKey
*/ */
WOLFSSL_API int wc_InitDsaKey(DsaKey* key); WOLFSSL_API int wc_InitDsaKey(DsaKey* key);
/*! /*!
\ingroup DSA \ingroup DSA
\brief This function frees a DsaKey object after it has been used. \brief This function frees a DsaKey object after it has been used.
\return none No returns. \return none No returns.
\param key pointer to the DsaKey structure to free \param key pointer to the DsaKey structure to free
_Example_ _Example_
\code \code
DsaKey key; DsaKey key;
@ -36,48 +36,48 @@ WOLFSSL_API int wc_InitDsaKey(DsaKey* key);
... ...
wc_FreeDsaKey(&key); // free DSA key wc_FreeDsaKey(&key); // free DSA key
\endcode \endcode
\sa wc_FreeDsaKey \sa wc_FreeDsaKey
*/ */
WOLFSSL_API void wc_FreeDsaKey(DsaKey* key); WOLFSSL_API void wc_FreeDsaKey(DsaKey* key);
/*! /*!
\ingroup DSA \ingroup DSA
\brief This function signs the input digest and stores the result in the \brief This function signs the input digest and stores the result in the
output buffer, out. output buffer, out.
\return 0 Returned on successfully signing the input digest \return 0 Returned on successfully signing the input digest
\return MP_INIT_E may be returned if there is an error in processing the \return MP_INIT_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_READ_E may be returned if there is an error in processing the \return MP_READ_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_CMP_E may be returned if there is an error in processing the \return MP_CMP_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_INVMOD_E may be returned if there is an error in processing the \return MP_INVMOD_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_EXPTMOD_E may be returned if there is an error in processing \return MP_EXPTMOD_E may be returned if there is an error in processing
the DSA signature. the DSA signature.
\return MP_MOD_E may be returned if there is an error in processing the \return MP_MOD_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_MUL_E may be returned if there is an error in processing the \return MP_MUL_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_ADD_E may be returned if there is an error in processing the \return MP_ADD_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_MULMOD_E may be returned if there is an error in processing \return MP_MULMOD_E may be returned if there is an error in processing
the DSA signature. the DSA signature.
\return MP_TO_E may be returned if there is an error in processing the \return MP_TO_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_MEM may be returned if there is an error in processing the \return MP_MEM may be returned if there is an error in processing the
DSA signature. DSA signature.
\param digest pointer to the hash to sign \param digest pointer to the hash to sign
\param out pointer to the buffer in which to store the signature \param out pointer to the buffer in which to store the signature
\param key pointer to the initialized DsaKey structure with which to \param key pointer to the initialized DsaKey structure with which to
generate the signature generate the signature
\param rng pointer to an initialized RNG to use with the signature \param rng pointer to an initialized RNG to use with the signature
generation generation
_Example_ _Example_
\code \code
DsaKey key; DsaKey key;
@ -89,11 +89,11 @@ WOLFSSL_API void wc_FreeDsaKey(DsaKey* key);
byte signature[40]; // signature will be 40 bytes (320 bits) byte signature[40]; // signature will be 40 bytes (320 bits)
ret = wc_DsaSign(hash, signature, &key, &rng); ret = wc_DsaSign(hash, signature, &key, &rng);
if (ret != 0) { if (ret != 0) {
// error generating DSA signature // error generating DSA signature
} }
\endcode \endcode
\sa wc_DsaVerify \sa wc_DsaVerify
*/ */
WOLFSSL_API int wc_DsaSign(const byte* digest, byte* out, WOLFSSL_API int wc_DsaSign(const byte* digest, byte* out,
@ -101,45 +101,45 @@ WOLFSSL_API int wc_DsaSign(const byte* digest, byte* out,
/*! /*!
\ingroup DSA \ingroup DSA
\brief This function verifies the signature of a digest, given a private \brief This function verifies the signature of a digest, given a private
key. It stores whether the key properly verifies in the answer parameter, key. It stores whether the key properly verifies in the answer parameter,
with 1 corresponding to a successful verification, and 0 corresponding to with 1 corresponding to a successful verification, and 0 corresponding to
failed verification. failed verification.
\return 0 Returned on successfully processing the verify request. Note: \return 0 Returned on successfully processing the verify request. Note:
this does not mean that the signature is verified, only that the function this does not mean that the signature is verified, only that the function
succeeded succeeded
\return MP_INIT_E may be returned if there is an error in processing the \return MP_INIT_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_READ_E may be returned if there is an error in processing the \return MP_READ_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_CMP_E may be returned if there is an error in processing the \return MP_CMP_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_INVMOD_E may be returned if there is an error in processing \return MP_INVMOD_E may be returned if there is an error in processing
the DSA signature. the DSA signature.
\return MP_EXPTMOD_E may be returned if there is an error in processing \return MP_EXPTMOD_E may be returned if there is an error in processing
the DSA signature. the DSA signature.
\return MP_MOD_E may be returned if there is an error in processing the \return MP_MOD_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_MUL_E may be returned if there is an error in processing the \return MP_MUL_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_ADD_E may be returned if there is an error in processing the \return MP_ADD_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_MULMOD_E may be returned if there is an error in processing \return MP_MULMOD_E may be returned if there is an error in processing
the DSA signature. the DSA signature.
\return MP_TO_E may be returned if there is an error in processing the \return MP_TO_E may be returned if there is an error in processing the
DSA signature. DSA signature.
\return MP_MEM may be returned if there is an error in processing the \return MP_MEM may be returned if there is an error in processing the
DSA signature. DSA signature.
\param digest pointer to the digest containing the subject of the 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 sig pointer to the buffer containing the signature to verify
\param key pointer to the initialized DsaKey structure with which to \param key pointer to the initialized DsaKey structure with which to
verify the signature verify the signature
\param answer pointer to an integer which will store whether the \param answer pointer to an integer which will store whether the
verification was successful verification was successful
_Example_ _Example_
\code \code
DsaKey key; DsaKey key;
@ -150,13 +150,13 @@ WOLFSSL_API int wc_DsaSign(const byte* digest, byte* out,
byte hash[] = { // initialize with hash digest }; byte hash[] = { // initialize with hash digest };
byte signature[] = { // initialize with signature to verify }; byte signature[] = { // initialize with signature to verify };
ret = wc_DsaVerify(hash, signature, &key, &verified); ret = wc_DsaVerify(hash, signature, &key, &verified);
if (ret != 0) { if (ret != 0) {
// error processing verify request // error processing verify request
} else if (answer == 0) { } else if (answer == 0) {
// invalid signature // invalid signature
} }
\endcode \endcode
\sa wc_DsaSign \sa wc_DsaSign
*/ */
WOLFSSL_API int wc_DsaVerify(const byte* digest, const byte* sig, WOLFSSL_API int wc_DsaVerify(const byte* digest, const byte* sig,
@ -164,21 +164,21 @@ WOLFSSL_API int wc_DsaVerify(const byte* digest, const byte* sig,
/*! /*!
\ingroup DSA \ingroup DSA
\brief This function decodes a DER formatted certificate buffer containing \brief This function decodes a DER formatted certificate buffer containing
a DSA public key, and stores the key in the given DsaKey structure. It 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. also sets the inOutIdx parameter according to the length of the input read.
\return 0 Returned on successfully setting the public key for the DsaKey \return 0 Returned on successfully setting the public key for the DsaKey
object object
\return ASN_PARSE_E Returned if there is an error in the encoding while \return ASN_PARSE_E Returned if there is an error in the encoding while
reading the certificate buffer reading the certificate buffer
\return ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly \return ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly
formatted formatted
\param input pointer to the buffer containing the DER formatted DSA \param input pointer to the buffer containing the DER formatted DSA
public key public key
\param inOutIdx pointer to an integer in which to store the final index \param inOutIdx pointer to an integer in which to store the final index
of the certificate read of the certificate read
\param key pointer to the DsaKey structure in which to store the public key \param key pointer to the DsaKey structure in which to store the public key
\param inSz size of the input buffer \param inSz size of the input buffer
@ -191,11 +191,11 @@ WOLFSSL_API int wc_DsaVerify(const byte* digest, const byte* sig,
wc_InitDsaKey(&key); wc_InitDsaKey(&key);
byte derBuff[] = { // DSA public key}; byte derBuff[] = { // DSA public key};
ret = wc_DsaPublicKeyDecode(derBuff, &idx, &key, inSz); ret = wc_DsaPublicKeyDecode(derBuff, &idx, &key, inSz);
if (ret != 0) { if (ret != 0) {
// error reading public key // error reading public key
} }
\endcode \endcode
\sa wc_InitDsaKey \sa wc_InitDsaKey
\sa wc_DsaPrivateKeyDecode \sa wc_DsaPrivateKeyDecode
*/ */
@ -204,23 +204,23 @@ WOLFSSL_API int wc_DsaPublicKeyDecode(const byte* input, word32* inOutIdx,
/*! /*!
\ingroup DSA \ingroup DSA
\brief This function decodes a DER formatted certificate buffer containing \brief This function decodes a DER formatted certificate buffer containing
a DSA private key, and stores the key in the given DsaKey structure. It 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. also sets the inOutIdx parameter according to the length of the input read.
\return 0 Returned on successfully setting the private key for the DsaKey \return 0 Returned on successfully setting the private key for the DsaKey
object object
\return ASN_PARSE_E Returned if there is an error in the encoding while \return ASN_PARSE_E Returned if there is an error in the encoding while
reading the certificate buffer reading the certificate buffer
\return ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly \return ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly
formatted formatted
\param input pointer to the buffer containing the DER formatted DSA \param input pointer to the buffer containing the DER formatted DSA
private key private key
\param inOutIdx pointer to an integer in which to store the final index \param inOutIdx pointer to an integer in which to store the final index
of the certificate read of the certificate read
\param key pointer to the DsaKey structure in which to store the private \param key pointer to the DsaKey structure in which to store the private
key key
\param inSz size of the input buffer \param inSz size of the input buffer
@ -232,11 +232,11 @@ WOLFSSL_API int wc_DsaPublicKeyDecode(const byte* input, word32* inOutIdx,
wc_InitDsaKey(&key); wc_InitDsaKey(&key);
byte derBuff[] = { // DSA private key }; byte derBuff[] = { // DSA private key };
ret = wc_DsaPrivateKeyDecode(derBuff, &idx, &key, inSz); ret = wc_DsaPrivateKeyDecode(derBuff, &idx, &key, inSz);
if (ret != 0) { if (ret != 0) {
// error reading private key // error reading private key
} }
\endcode \endcode
\sa wc_InitDsaKey \sa wc_InitDsaKey
\sa wc_DsaPublicKeyDecode \sa wc_DsaPublicKeyDecode
*/ */
@ -245,12 +245,12 @@ WOLFSSL_API int wc_DsaPrivateKeyDecode(const byte* input, word32* inOutIdx,
/*! /*!
\ingroup DSA \ingroup DSA
\brief Convert DsaKey key to DER format, write to output (inLen), \brief Convert DsaKey key to DER format, write to output (inLen),
return bytes written. return bytes written.
\return outLen Success, number of bytes written \return outLen Success, number of bytes written
\return BAD_FUNC_ARG key or output are null or key->type is not \return BAD_FUNC_ARG key or output are null or key->type is not
DSA_PRIVATE. DSA_PRIVATE.
\return MEMORY_E Error allocating memory. \return MEMORY_E Error allocating memory.
@ -271,7 +271,7 @@ WOLFSSL_API int wc_DsaPrivateKeyDecode(const byte* input, word32* inOutIdx,
wc_MakeDsaKey(&rng, &key); wc_MakeDsaKey(&rng, &key);
derSz = wc_DsaKeyToDer(&key, der, bufferSize); derSz = wc_DsaKeyToDer(&key, der, bufferSize);
\endcode \endcode
\sa wc_InitDsaKey \sa wc_InitDsaKey
\sa wc_FreeDsaKey \sa wc_FreeDsaKey
\sa wc_MakeDsaKey \sa wc_MakeDsaKey
@ -280,11 +280,11 @@ WOLFSSL_API int wc_DsaKeyToDer(DsaKey* key, byte* output, word32 inLen);
/*! /*!
\ingroup DSA \ingroup DSA
\brief Create a DSA key. \brief Create a DSA key.
\return MP_OKAY Success \return MP_OKAY Success
\return BAD_FUNC_ARG Either rng or dsa is null. \return BAD_FUNC_ARG Either rng or dsa is null.
\return MEMORY_E Couldn't allocate memory for buffer. \return MEMORY_E Couldn't allocate memory for buffer.
\return MP_INIT_E Error initializing mp_int \return MP_INIT_E Error initializing mp_int
@ -302,7 +302,7 @@ WOLFSSL_API int wc_DsaKeyToDer(DsaKey* key, byte* output, word32 inLen);
// Error creating key // Error creating key
} }
\endcode \endcode
\sa wc_InitDsaKey \sa wc_InitDsaKey
\sa wc_FreeDsaKey \sa wc_FreeDsaKey
\sa wc_DsaSign \sa wc_DsaSign
@ -311,10 +311,10 @@ WOLFSSL_API int wc_MakeDsaKey(WC_RNG *rng, DsaKey *dsa);
/*! /*!
\ingroup DSA \ingroup DSA
\brief FIPS 186-4 defines valid for modulus_size values as \brief FIPS 186-4 defines valid for modulus_size values as
(1024, 160) (2048, 256) (3072, 256) (1024, 160) (2048, 256) (3072, 256)
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG rng or dsa is null or modulus_size is invalid. \return BAD_FUNC_ARG rng or dsa is null or modulus_size is invalid.
\return MEMORY_E Error attempting to allocate memory. \return MEMORY_E Error attempting to allocate memory.
@ -334,7 +334,7 @@ WOLFSSL_API int wc_MakeDsaKey(WC_RNG *rng, DsaKey *dsa);
// Handle error // Handle error
} }
\endcode \endcode
\sa wc_MakeDsaKey \sa wc_MakeDsaKey
\sa wc_DsaKeyToDer \sa wc_DsaKeyToDer
\sa wc_InitDsaKey \sa wc_InitDsaKey

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

File diff suppressed because it is too large Load Diff

226
doc/dox_comments/header_files/ed25519.h
View File

@ -1,15 +1,15 @@
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function generates a new ed25519_key and stores it in key. \brief This function generates a new ed25519_key and stores it in key.
\retrun 0 Returned upon successfully making an ed25519_key \retrun 0 Returned upon successfully making an ed25519_key
\retrun BAD_FUNC_ARG Returned if rng or key evaluate to NULL, or if the \retrun BAD_FUNC_ARG Returned if rng or key evaluate to NULL, or if the
specified key size is not 32 bytes (ed25519 has 32 byte keys) specified key size is not 32 bytes (ed25519 has 32 byte keys)
\retrun MEMORY_E Returned if there is an error allocating memory \retrun MEMORY_E Returned if there is an error allocating memory
during function execution during function execution
\param rng pointer to an initialized RNG object with which to \param rng pointer to an initialized RNG object with which to
generate the key generate the key
\param keysize length of key to generate. Should always be 32 for ed25519 \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 \param key pointer to the ed25519_key for which to generate a key
@ -22,7 +22,7 @@
wc_InitRng(&rng); wc_InitRng(&rng);
wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
\endcode \endcode
\sa wc_ed25519_init \sa wc_ed25519_init
*/ */
WOLFSSL_API WOLFSSL_API
@ -30,25 +30,25 @@ int wc_ed25519_make_key(WC_RNG* rng, int keysize, ed25519_key* key);
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function signs a message digest using an ed25519_key object \brief This function signs a message digest using an ed25519_key object
to guarantee authenticity. to guarantee authenticity.
\return 0 Returned upon successfully generating a signature for the \return 0 Returned upon successfully generating a signature for the
message digest message digest
\return BAD_FUNC_ARG Returned any of the input parameters evaluate to \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
NULL, or if the output buffer is too small to store the generated signature NULL, or if the output buffer is too small to store the generated signature
\return MEMORY_E Returned if there is an error allocating memory during \return MEMORY_E Returned if there is an error allocating memory during
function execution function execution
\param in pointer to the buffer containing the message to sign \param in pointer to the buffer containing the message to sign
\param inlen length of the message to sign \param inlen length of the message to sign
\param out buffer in which to store the generated signature \param out buffer in which to store the generated signature
\param outlen max length of the output buffer. Will store the bytes \param outlen max length of the output buffer. Will store the bytes
written to out upon successfully generating a message signature written to out upon successfully generating a message signature
\param key pointer to a private ed25519_key with which to generate the \param key pointer to a private ed25519_key with which to generate the
signature signature
_Example_ _Example_
\code \code
ed25519_key key; ed25519_key key;
@ -67,7 +67,7 @@ int wc_ed25519_make_key(WC_RNG* rng, int keysize, ed25519_key* key);
// error generating message signature // error generating message signature
} }
\endcode \endcode
\sa wc_ed25519_verify_msg \sa wc_ed25519_verify_msg
*/ */
WOLFSSL_API WOLFSSL_API
@ -76,26 +76,26 @@ int wc_ed25519_sign_msg(const byte* in, word32 inlen, byte* out,
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function verifies the ed25519 signature of a message to ensure \brief This function verifies the ed25519 signature of a message to ensure
authenticity. It returns the answer through stat, with 1 corresponding to authenticity. It returns the answer through stat, with 1 corresponding to
a valid signature, and 0 corresponding to an invalid signature. a valid signature, and 0 corresponding to an invalid signature.
\return 0 Returned upon successfully performing the signature \return 0 Returned upon successfully performing the signature
verification. Note: This does not mean that the signature is verified. verification. Note: This does not mean that the signature is verified.
The authenticity information is stored instead in stat The authenticity information is stored instead in stat
\return BAD_FUNC_ARG Returned if any of the input parameters evaluate to \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
NULL, or if the siglen does not match the actual length of a signature NULL, or if the siglen does not match the actual length of a signature
\return 1 Returned if verification completes, but the signature generated \return 1 Returned if verification completes, but the signature generated
does not match the signature provided does not match the signature provided
\param sig pointer to the buffer containing the signature to verify \param sig pointer to the buffer containing the signature to verify
\param siglen length of the signature to verify \param siglen length of the signature to verify
\param msg pointer to the buffer containing the message to verify \param msg pointer to the buffer containing the message to verify
\param msglen length of the message to verify \param msglen length of the message to verify
\param stat pointer to the result of the verification. 1 indicates the \param stat pointer to the result of the verification. 1 indicates the
message was successfully verified message was successfully verified
\param key pointer to a public ed25519 key with which to verify the \param key pointer to a public ed25519 key with which to verify the
signature signature
_Example_ _Example_
@ -106,7 +106,7 @@ int wc_ed25519_sign_msg(const byte* in, word32 inlen, byte* out,
byte sig[] { // initialize with received signature }; byte sig[] { // initialize with received signature };
byte msg[] = { // initialize with message }; byte msg[] = { // initialize with message };
// initialize key with received public key // initialize key with received public key
ret = wc_ed25519_verify_msg(sig, sizeof(sig), msg, sizeof(msg), ret = wc_ed25519_verify_msg(sig, sizeof(sig), msg, sizeof(msg),
&verified, &key); &verified, &key);
if ( return < 0 ) { if ( return < 0 ) {
@ -115,7 +115,7 @@ int wc_ed25519_sign_msg(const byte* in, word32 inlen, byte* out,
// the signature is invalid // the signature is invalid
} }
\endcode \endcode
\sa wc_ed25519_sign_msg \sa wc_ed25519_sign_msg
*/ */
WOLFSSL_API WOLFSSL_API
@ -124,21 +124,21 @@ int wc_ed25519_verify_msg(const byte* sig, word32 siglen, const byte* msg,
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function initializes an ed25519_key object for future use \brief This function initializes an ed25519_key object for future use
with message verification. with message verification.
\return 0 Returned upon successfully initializing the ed25519_key object \return 0 Returned upon successfully initializing the ed25519_key object
\return BAD_FUNC_ARG Returned if key is NULL \return BAD_FUNC_ARG Returned if key is NULL
\param key pointer to the ed25519_key object to initialize \param key pointer to the ed25519_key object to initialize
_Example_ _Example_
\code \code
ed25519_key key; ed25519_key key;
wc_ed25519_init(&key); wc_ed25519_init(&key);
\endcode \endcode
\sa wc_ed25519_make_key \sa wc_ed25519_make_key
\sa wc_ed25519_free \sa wc_ed25519_free
*/ */
@ -147,13 +147,13 @@ int wc_ed25519_init(ed25519_key* key);
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function frees an ed25519 object after it has been used. \brief This function frees an ed25519 object after it has been used.
\return none No returns. \return none No returns.
\param key pointer to the ed25519_key object to free \param key pointer to the ed25519_key object to free
_Example_ _Example_
\code \code
ed25519_key key; ed25519_key key;
@ -161,7 +161,7 @@ int wc_ed25519_init(ed25519_key* key);
... ...
wc_ed25519_free(&key); wc_ed25519_free(&key);
\endcode \endcode
\sa wc_ed25519_init \sa wc_ed25519_init
*/ */
WOLFSSL_API WOLFSSL_API
@ -169,20 +169,20 @@ void wc_ed25519_free(ed25519_key* key);
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function imports a public ed25519_key pair from a buffer \brief This function imports a public ed25519_key pair from a buffer
containing the public key. This function will handle both compressed and containing the public key. This function will handle both compressed and
uncompressed keys. uncompressed keys.
\return 0 Returned on successfully importing the ed25519_key \return 0 Returned on successfully importing the ed25519_key
\return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is
less than the size of an ed25519 key less than the size of an ed25519 key
\param in pointer to the buffer containing the public key \param in pointer to the buffer containing the public key
\param inLen length of the buffer containing the public key \param inLen length of the buffer containing the public key
\param key pointer to the ed25519_key object in which to store the \param key pointer to the ed25519_key object in which to store the
public key public key
_Example_ _Example_
\code \code
int ret; int ret;
@ -195,7 +195,7 @@ void wc_ed25519_free(ed25519_key* key);
// error importing key // error importing key
} }
\endcode \endcode
\sa wc_ed25519_import_private_key \sa wc_ed25519_import_private_key
\sa wc_ed25519_export_public \sa wc_ed25519_export_public
*/ */
@ -204,20 +204,20 @@ int wc_ed25519_import_public(const byte* in, word32 inLen, ed25519_key* key);
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function imports a public/private ed25519 key pair from a \brief This function imports a public/private ed25519 key pair from a
pair of buffers. This function will handle both compressed and pair of buffers. This function will handle both compressed and
uncompressed keys. uncompressed keys.
\return 0 Returned on successfully importing the ed25519_key \return 0 Returned on successfully importing the ed25519_key
\return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if
either privSz or pubSz are less than the size of an ed25519 key either privSz or pubSz are less than the size of an ed25519 key
\param priv pointer to the buffer containing the private key \param priv pointer to the buffer containing the private key
\param privSz size of the private key \param privSz size of the private key
\param pub pointer to the buffer containing the public key \param pub pointer to the buffer containing the public key
\param pubSz length of the public key \param pubSz length of the public key
\param key pointer to the ed25519_key object in which to store the \param key pointer to the ed25519_key object in which to store the
imported private/public key pair imported private/public key pair
_Example_ _Example_
@ -228,13 +228,13 @@ int wc_ed25519_import_public(const byte* in, word32 inLen, ed25519_key* key);
ed25519_key key; ed25519_key key;
wc_ed25519_init_key(&key); wc_ed25519_init_key(&key);
ret = wc_ed25519_import_private_key(priv, sizeof(priv), pub, ret = wc_ed25519_import_private_key(priv, sizeof(priv), pub,
sizeof(pub), &key); sizeof(pub), &key);
if ( ret != 0) { if ( ret != 0) {
// error importing key // error importing key
} }
\endcode \endcode
\sa wc_ed25519_import_public_key \sa wc_ed25519_import_public_key
\sa wc_ed25519_export_private_only \sa wc_ed25519_export_private_only
*/ */
@ -244,22 +244,22 @@ int wc_ed25519_import_private_key(const byte* priv, word32 privSz,
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function exports the private key from an ed25519_key \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 structure. It stores the public key in the buffer out, and sets the bytes
written to this buffer in outLen. written to this buffer in outLen.
\return 0 Returned upon successfully exporting the public key \return 0 Returned upon successfully exporting the public key
\return BAD_FUNC_ARG Returned if any of the input values evaluate to NULL \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 \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 store the private key. Upon returning this error, the function sets the
size required in outLen size required in outLen
\param key pointer to an ed25519_key structure from which to export the \param key pointer to an ed25519_key structure from which to export the
public key public key
\param out pointer to the buffer in which to store 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. \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 Set with the number of bytes written to out after successfully exporting
the private key the private key
_Example_ _Example_
@ -276,7 +276,7 @@ int wc_ed25519_import_private_key(const byte* priv, word32 privSz,
// error exporting public key // error exporting public key
} }
\endcode \endcode
\sa wc_ed25519_import_public_key \sa wc_ed25519_import_public_key
\sa wc_ed25519_export_private_only \sa wc_ed25519_export_private_only
*/ */
@ -285,23 +285,23 @@ int wc_ed25519_export_public(ed25519_key*, byte* out, word32* outLen);
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function exports only the private key from an ed25519_key \brief This function exports only the private key from an ed25519_key
structure. It stores the private key in the buffer out, and sets structure. It stores the private key in the buffer out, and sets
the bytes written to this buffer in outLen. the bytes written to this buffer in outLen.
\return 0 Returned upon successfully exporting the private key \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 ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL
\return BUFFER_E Returned if the buffer provided is not large enough \return BUFFER_E Returned if the buffer provided is not large enough
to store the private key to store the private key
\param key pointer to an ed25519_key structure from which to export \param key pointer to an ed25519_key structure from which to export
the private key the private key
\param out pointer to the buffer in which to store 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 \param outLen pointer to a word32 object with the size available in
out. Set with the number of bytes written to out after successfully out. Set with the number of bytes written to out after successfully
exporting the private key exporting the private key
_Example_ _Example_
\code \code
int ret; int ret;
@ -315,7 +315,7 @@ int wc_ed25519_export_public(ed25519_key*, byte* out, word32* outLen);
// error exporting private key // error exporting private key
} }
\endcode \endcode
\sa wc_ed25519_export_public \sa wc_ed25519_export_public
\sa wc_ed25519_import_private_key \sa wc_ed25519_import_private_key
*/ */
@ -324,7 +324,7 @@ int wc_ed25519_export_private_only(ed25519_key* key, byte* out, word32* outLen);
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief Export the private key, including public part. \brief Export the private key, including public part.
\return 0 Success \return 0 Success
@ -333,9 +333,9 @@ int wc_ed25519_export_private_only(ed25519_key* key, byte* out, word32* outLen);
\param key ed25519_key struct to export from. \param key ed25519_key struct to export from.
\param out Destination for private key. \param out Destination for private key.
\param outLen Max length of output, set to the length of the exported \param outLen Max length of output, set to the length of the exported
private key. private key.
_Example_ _Example_
\code \code
ed25519_key key; ed25519_key key;
@ -354,7 +354,7 @@ int wc_ed25519_export_private_only(ed25519_key* key, byte* out, word32* outLen);
// Check size of out compared to outLen to see if function reset outLen // Check size of out compared to outLen to see if function reset outLen
} }
\endcode \endcode
\sa none \sa none
*/ */
WOLFSSL_API WOLFSSL_API
@ -362,14 +362,14 @@ int wc_ed25519_export_private(ed25519_key* key, byte* out, word32* outLen);
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief Export full private key and public key. \brief Export full private key and public key.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG: Returns if any argument is null. \return BAD_FUNC_ARG: Returns if any argument is null.
\return BUFFER_E: Returns if outLen is less than ED25519_PRV_KEY_SIZE \return BUFFER_E: Returns if outLen is less than ED25519_PRV_KEY_SIZE
or ED25519_PUB_KEY_SIZE or ED25519_PUB_KEY_SIZE
\param key The ed25519_key structure to export to. \param key The ed25519_key structure to export to.
\param priv Byte array to store private key. \param priv Byte array to store private key.
\param privSz Size of priv buffer. \param privSz Size of priv buffer.
@ -392,7 +392,7 @@ int wc_ed25519_export_private(ed25519_key* key, byte* out, word32* outLen);
// error exporting public key // error exporting public key
} }
\endcode \endcode
\sa wc_ed25519_export_private \sa wc_ed25519_export_private
\sa wc_ed25519_export_public \sa wc_ed25519_export_public
*/ */
@ -403,16 +403,16 @@ int wc_ed25519_export_key(ed25519_key* key,
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function returns the key size of an ed25519_key structure, \brief This function returns the key size of an ed25519_key structure,
or 32 bytes. or 32 bytes.
\return Success Given a valid key, returns ED25519_KEY_SIZE (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 \return BAD_FUNC_ARGS Returned if the given key is NULL
\param key pointer to an ed25519_key structure for which to get the \param key pointer to an ed25519_key structure for which to get the
key size key size
_Example_ _Example_
\code \code
int keySz; int keySz;
@ -423,7 +423,7 @@ int wc_ed25519_export_key(ed25519_key* key,
// error determining key size // error determining key size
} }
\endcode \endcode
\sa wc_ed25519_make_key \sa wc_ed25519_make_key
*/ */
WOLFSSL_API WOLFSSL_API
@ -431,14 +431,14 @@ int wc_ed25519_size(ed25519_key* key);
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief Returns the private key size (secret + public) in bytes. \brief Returns the private key size (secret + public) in bytes.
\return BAD_FUNC_ARG Returns if key argument is null. \return BAD_FUNC_ARG Returns if key argument is null.
\return ED25519_PRV_KEY_SIZE The size of the private key. \return ED25519_PRV_KEY_SIZE The size of the private key.
\param key The ed25119_key struct \param key The ed25119_key struct
_Example_ _Example_
\code \code
ed25519_key key; ed25519_key key;
@ -450,7 +450,7 @@ int wc_ed25519_size(ed25519_key* key);
wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
int key_size = wc_ed25519_priv_size(&key); int key_size = wc_ed25519_priv_size(&key);
\endcode \endcode
\sa wc_ed25119_pub_size \sa wc_ed25119_pub_size
*/ */
WOLFSSL_API WOLFSSL_API
@ -458,14 +458,14 @@ int wc_ed25519_priv_size(ed25519_key* key);
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief Returns the compressed key size in bytes (public key). \brief Returns the compressed key size in bytes (public key).
\return BAD_FUNC_ARG returns if key is null. \return BAD_FUNC_ARG returns if key is null.
\return ED25519_PUB_KEY_SIZE Size of key. \return ED25519_PUB_KEY_SIZE Size of key.
\param key Pointer to the ed25519_key struct. \param key Pointer to the ed25519_key struct.
_Example_ _Example_
\code \code
ed25519_key key; ed25519_key key;
@ -476,7 +476,7 @@ int wc_ed25519_priv_size(ed25519_key* key);
wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte ed25519 key
int key_size = wc_ed25519_pub_size(&key); int key_size = wc_ed25519_pub_size(&key);
\endcode \endcode
\sa wc_ed25519_priv_size \sa wc_ed25519_priv_size
*/ */
WOLFSSL_API WOLFSSL_API
@ -484,15 +484,15 @@ int wc_ed25519_pub_size(ed25519_key* key);
/*! /*!
\ingroup ED25519 \ingroup ED25519
\brief This function returns the size of an ed25519 signature (64 in bytes). \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 Success Given a valid key, returns ED25519_SIG_SIZE (64 in bytes)
\return 0 Returned if the given key is NULL \return 0 Returned if the given key is NULL
\param key pointer to an ed25519_key structure for which to get the \param key pointer to an ed25519_key structure for which to get the
signature size signature size
_Example_ _Example_
\code \code
int sigSz; int sigSz;
@ -504,7 +504,7 @@ int wc_ed25519_pub_size(ed25519_key* key);
// error determining sig size // error determining sig size
} }
\endcode \endcode
\sa wc_ed25519_sign_msg \sa wc_ed25519_sign_msg
*/ */
WOLFSSL_API WOLFSSL_API

26
doc/dox_comments/header_files/error-crypt.h
View File

@ -1,15 +1,15 @@
/*! /*!
\ingroup Error \ingroup Error
\brief This function stores the error string for a particular error code \brief This function stores the error string for a particular error code
in the given buffer. in the given buffer.
\return none No returns. \return none No returns.
\param error error code for which to get the string \param error error code for which to get the string
\param buffer buffer in which to store the error string. Buffer should be \param buffer buffer in which to store the error string. Buffer should be
at least WOLFSSL_MAX_ERROR_SZ (80 bytes) long at least WOLFSSL_MAX_ERROR_SZ (80 bytes) long
_Example_ _Example_
\code \code
char errorMsg[WOLFSSL_MAX_ERROR_SZ]; char errorMsg[WOLFSSL_MAX_ERROR_SZ];
@ -19,21 +19,21 @@
wc_ErrorString(err, errorMsg); wc_ErrorString(err, errorMsg);
} }
\endcode \endcode
\sa wc_GetErrorString \sa wc_GetErrorString
*/ */
WOLFSSL_API void wc_ErrorString(int err, char* buff); WOLFSSL_API void wc_ErrorString(int err, char* buff);
/*! /*!
\ingroup Error \ingroup Error
\brief This function returns the error string for a particular error code. \brief This function returns the error string for a particular error code.
\return string Returns the error string for an error code as a \return string Returns the error string for an error code as a
string literal. string literal.
\param error error code for which to get the string \param error error code for which to get the string
_Example_ _Example_
\code \code
char * errorMsg; char * errorMsg;
@ -43,7 +43,7 @@ WOLFSSL_API void wc_ErrorString(int err, char* buff);
errorMsg = wc_GetErrorString(err); errorMsg = wc_GetErrorString(err);
} }
\endcode \endcode
\sa wc_ErrorString \sa wc_ErrorString
*/ */
WOLFSSL_API const char* wc_GetErrorString(int error); WOLFSSL_API const char* wc_GetErrorString(int error);

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

@ -1,64 +1,64 @@
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief Getter functions for the respective WOLFSSL_EVP_CIPHER pointers. \brief Getter functions for the respective WOLFSSL_EVP_CIPHER pointers.
wolfSSL_EVP_init() must be called once in the program first to populate wolfSSL_EVP_init() must be called once in the program first to populate
these cipher strings. WOLFSSL_DES_ECB macro must be defined for these cipher strings. WOLFSSL_DES_ECB macro must be defined for
wolfSSL_EVP_des_ede3_ecb(). wolfSSL_EVP_des_ede3_ecb().
\return pointer Returns a WOLFSSL_EVP_CIPHER pointer for DES EDE3 operations. \return pointer Returns a WOLFSSL_EVP_CIPHER pointer for DES EDE3 operations.
\param none No parameters. \param none No parameters.
_Example_ _Example_
\code \code
printf("block size des ede3 cbc = %d\n", printf("block size des ede3 cbc = %d\n",
wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_cbc())); wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_cbc()));
printf("block size des ede3 ecb = %d\n", printf("block size des ede3 ecb = %d\n",
wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_ecb())); wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_ecb()));
\endcode \endcode
\sa wolfSSL_EVP_CIPHER_CTX_init \sa wolfSSL_EVP_CIPHER_CTX_init
*/ */
WOLFSSL_API const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_ede3_ecb(void); WOLFSSL_API const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_ede3_ecb(void);
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief Getter functions for the respective WOLFSSL_EVP_CIPHER pointers. \brief Getter functions for the respective WOLFSSL_EVP_CIPHER pointers.
wolfSSL_EVP_init() must be called once in the program first to populate wolfSSL_EVP_init() must be called once in the program first to populate
these cipher strings. WOLFSSL_DES_ECB macro must be defined for these cipher strings. WOLFSSL_DES_ECB macro must be defined for
wolfSSL_EVP_des_ecb(). wolfSSL_EVP_des_ecb().
\return pointer Returns a WOLFSSL_EVP_CIPHER pointer for DES operations. \return pointer Returns a WOLFSSL_EVP_CIPHER pointer for DES operations.
\param none No parameters. \param none No parameters.
_Example_ _Example_
\code \code
WOLFSSL_EVP_CIPHER* cipher; WOLFSSL_EVP_CIPHER* cipher;
cipher = wolfSSL_EVP_des_cbc(); cipher = wolfSSL_EVP_des_cbc();
… …
\endcode \endcode
\sa wolfSSL_EVP_CIPHER_CTX_init \sa wolfSSL_EVP_CIPHER_CTX_init
*/ */
WOLFSSL_API const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_cbc(void); WOLFSSL_API const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_cbc(void);
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief Function for initializing WOLFSSL_EVP_MD_CTX. This function is a \brief Function for initializing WOLFSSL_EVP_MD_CTX. This function is a
wrapper for wolfSSL_EVP_DigestInit() because wolfSSL does not wrapper for wolfSSL_EVP_DigestInit() because wolfSSL does not
use WOLFSSL_ENGINE. use WOLFSSL_ENGINE.
\return SSL_SUCCESS If successfully set. \return SSL_SUCCESS If successfully set.
\return SSL_FAILURE If not successful. \return SSL_FAILURE If not successful.
\param ctx structure to initialize. \param ctx structure to initialize.
\param type type of hash to do, for example SHA. \param type type of hash to do, for example SHA.
\param impl engine to use. N/A for wolfSSL, can be NULL. \param impl engine to use. N/A for wolfSSL, can be NULL.
_Example_ _Example_
\code \code
WOLFSSL_EVP_MD_CTX* md = NULL; WOLFSSL_EVP_MD_CTX* md = NULL;
@ -68,11 +68,11 @@ WOLFSSL_API const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_cbc(void);
printf("error setting md\n"); printf("error setting md\n");
return -1; return -1;
} }
printf("cipher md init ret = %d\n", wolfSSL_EVP_DigestInit_ex(md, printf("cipher md init ret = %d\n", wolfSSL_EVP_DigestInit_ex(md,
wolfSSL_EVP_sha1(), e)); wolfSSL_EVP_sha1(), e));
//free resources //free resources
\endcode \endcode
\sa wolfSSL_EVP_MD_CTX_new \sa wolfSSL_EVP_MD_CTX_new
\sa wolfCrypt_Init \sa wolfCrypt_Init
\sa wolfSSL_EVP_MD_CTX_free \sa wolfSSL_EVP_MD_CTX_free
@ -83,21 +83,21 @@ WOLFSSL_API int wolfSSL_EVP_DigestInit_ex(WOLFSSL_EVP_MD_CTX* ctx,
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a \brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a
wrapper for wolfSSL_CipherInit() because wolfSSL does not wrapper for wolfSSL_CipherInit() because wolfSSL does not
use WOLFSSL_ENGINE. use WOLFSSL_ENGINE.
\return SSL_SUCCESS If successfully set. \return SSL_SUCCESS If successfully set.
\return SSL_FAILURE If not successful. \return SSL_FAILURE If not successful.
\param ctx structure to initialize. \param ctx structure to initialize.
\param type type of encryption/decryption to do, for example AES. \param type type of encryption/decryption to do, for example AES.
\param impl engine to use. N/A for wolfSSL, can be NULL. \param impl engine to use. N/A for wolfSSL, can be NULL.
\param key key to set . \param key key to set .
\param iv iv if needed by algorithm. \param iv iv if needed by algorithm.
\param enc encryption (1) or decryption (0) flag. \param enc encryption (1) or decryption (0) flag.
_Example_ _Example_
\code \code
WOLFSSL_EVP_CIPHER_CTX* ctx = NULL; WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;
@ -110,14 +110,14 @@ WOLFSSL_API int wolfSSL_EVP_DigestInit_ex(WOLFSSL_EVP_MD_CTX* ctx,
printf("issue creating ctx\n"); printf("issue creating ctx\n");
return -1; return -1;
} }
printf("cipher init ex error ret = %d\n", wolfSSL_EVP_CipherInit_ex(NULL, printf("cipher init ex error ret = %d\n", wolfSSL_EVP_CipherInit_ex(NULL,
EVP_aes_128_ cbc(), e, key, iv, 1)); EVP_aes_128_ cbc(), e, key, iv, 1));
printf("cipher init ex success ret = %d\n", wolfSSL_EVP_CipherInit_ex(ctx, printf("cipher init ex success ret = %d\n", wolfSSL_EVP_CipherInit_ex(ctx,
EVP_aes_128_c bc(), e, key, iv, 1)); EVP_aes_128_c bc(), e, key, iv, 1));
// free resources // free resources
\endcode \endcode
\sa wolfSSL_EVP_CIPHER_CTX_new \sa wolfSSL_EVP_CIPHER_CTX_new
\sa wolfCrypt_Init \sa wolfCrypt_Init
\sa wolfSSL_EVP_CIPHER_CTX_free \sa wolfSSL_EVP_CIPHER_CTX_free
@ -131,20 +131,20 @@ WOLFSSL_API int wolfSSL_EVP_CipherInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx,
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a \brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a
wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use
WOLFSSL_ENGINE. Sets encrypt flag to be encrypt. WOLFSSL_ENGINE. Sets encrypt flag to be encrypt.
\return SSL_SUCCESS If successfully set. \return SSL_SUCCESS If successfully set.
\return SSL_FAILURE If not successful. \return SSL_FAILURE If not successful.
\param ctx structure to initialize. \param ctx structure to initialize.
\param type type of encryption to do, for example AES. \param type type of encryption to do, for example AES.
\param impl engine to use. N/A for wolfSSL, can be NULL. \param impl engine to use. N/A for wolfSSL, can be NULL.
\param key key to use. \param key key to use.
\param iv iv to use. \param iv iv to use.
_Example_ _Example_
\code \code
WOLFSSL_EVP_CIPHER_CTX* ctx = NULL; WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;
@ -154,7 +154,7 @@ WOLFSSL_API int wolfSSL_EVP_CipherInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx,
printf("error setting ctx\n"); printf("error setting ctx\n");
return -1; return -1;
} }
printf("cipher ctx init ret = %d\n", wolfSSL_EVP_EncryptInit_ex(ctx, printf("cipher ctx init ret = %d\n", wolfSSL_EVP_EncryptInit_ex(ctx,
wolfSSL_EVP_aes_128_cbc(), e, key, iv)); wolfSSL_EVP_aes_128_cbc(), e, key, iv));
//free resources //free resources
\endcode \endcode
@ -171,21 +171,21 @@ WOLFSSL_API int wolfSSL_EVP_EncryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx,
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a \brief Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a
wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use
WOLFSSL_ENGINE. Sets encrypt flag to be decrypt. WOLFSSL_ENGINE. Sets encrypt flag to be decrypt.
\return SSL_SUCCESS If successfully set. \return SSL_SUCCESS If successfully set.
\return SSL_FAILURE If not successful. \return SSL_FAILURE If not successful.
\param ctx structure to initialize. \param ctx structure to initialize.
\param type type of encryption/decryption to do, for example AES. \param type type of encryption/decryption to do, for example AES.
\param impl engine to use. N/A for wolfSSL, can be NULL. \param impl engine to use. N/A for wolfSSL, can be NULL.
\param key key to set . \param key key to set .
\param iv iv if needed by algorithm. \param iv iv if needed by algorithm.
\param enc encryption (1) or decryption (0) flag. \param enc encryption (1) or decryption (0) flag.
_Example_ _Example_
\code \code
WOLFSSL_EVP_CIPHER_CTX* ctx = NULL; WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;
@ -201,13 +201,13 @@ WOLFSSL_API int wolfSSL_EVP_EncryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx,
return -1; return -1;
} }
printf("cipher init ex error ret = %d\n", wolfSSL_EVP_DecryptInit_ex(NULL, printf("cipher init ex error ret = %d\n", wolfSSL_EVP_DecryptInit_ex(NULL,
EVP_aes_128_ cbc(), e, key, iv, 1)); EVP_aes_128_ cbc(), e, key, iv, 1));
printf("cipher init ex success ret = %d\n", wolfSSL_EVP_DecryptInit_ex(ctx, printf("cipher init ex success ret = %d\n", wolfSSL_EVP_DecryptInit_ex(ctx,
EVP_aes_128_c bc(), e, key, iv, 1)); EVP_aes_128_c bc(), e, key, iv, 1));
// free resources // free resources
\endcode \endcode
\sa wolfSSL_EVP_CIPHER_CTX_new \sa wolfSSL_EVP_CIPHER_CTX_new
\sa wolfCrypt_Init \sa wolfCrypt_Init
\sa wolfSSL_EVP_CIPHER_CTX_free \sa wolfSSL_EVP_CIPHER_CTX_free
@ -220,11 +220,11 @@ WOLFSSL_API int wolfSSL_EVP_DecryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx,
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief Function for encrypting/decrypting data. In buffer is added to be \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 encrypted or decrypted and out buffer holds the results. outl will be the
length of encrypted/decrypted information. length of encrypted/decrypted information.
\return SSL_SUCCESS If successfull. \return SSL_SUCCESS If successfull.
\return SSL_FAILURE If not successful. \return SSL_FAILURE If not successful.
@ -233,7 +233,7 @@ WOLFSSL_API int wolfSSL_EVP_DecryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx,
\param outl adjusted to be size of output. \param outl adjusted to be size of output.
\param in buffer to perform operation on. \param in buffer to perform operation on.
\param inl length of input buffer. \param inl length of input buffer.
_Example_ _Example_
\code \code
WOLFSSL_EVP_CIPHER_CTX* ctx = NULL; WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;
@ -249,7 +249,7 @@ WOLFSSL_API int wolfSSL_EVP_DecryptInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx,
// buffer out holds outl bytes of data // buffer out holds outl bytes of data
// free resources // free resources
\endcode \endcode
\sa wolfSSL_EVP_CIPHER_CTX_new \sa wolfSSL_EVP_CIPHER_CTX_new
\sa wolfCrypt_Init \sa wolfCrypt_Init
\sa wolfSSL_EVP_CIPHER_CTX_free \sa wolfSSL_EVP_CIPHER_CTX_free
@ -260,21 +260,21 @@ WOLFSSL_API int wolfSSL_EVP_CipherUpdate(WOLFSSL_EVP_CIPHER_CTX *ctx,
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief This function performs the final cipher operations adding in \brief This function performs the final cipher operations adding in
padding. If WOLFSSL_EVP_CIPH_NO_PADDING flag is set in padding. If WOLFSSL_EVP_CIPH_NO_PADDING flag is set in
WOLFSSL_EVP_CIPHER_CTX structure then 1 is returned and no WOLFSSL_EVP_CIPHER_CTX structure then 1 is returned and no
encryption/decryption is done. If padding flag is seti padding is added and 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 encrypted when ctx is set to encrypt, padding values are checked when set
to decrypt. to decrypt.
\return 1 Returned on success. \return 1 Returned on success.
\return 0 If encountering a failure. \return 0 If encountering a failure.
\param ctx structure to decrypt/encrypt with. \param ctx structure to decrypt/encrypt with.
\param out buffer for final decrypt/encrypt. \param out buffer for final decrypt/encrypt.
\param out1 size of out buffer when data has been added by function. \param out1 size of out buffer when data has been added by function.
_Example_ _Example_
\code \code
WOLFSSL_EVP_CIPHER_CTX* ctx; WOLFSSL_EVP_CIPHER_CTX* ctx;
@ -283,7 +283,7 @@ WOLFSSL_API int wolfSSL_EVP_CipherUpdate(WOLFSSL_EVP_CIPHER_CTX *ctx,
// create ctx // create ctx
wolfSSL_EVP_CipherFinal(ctx, out, &out1); wolfSSL_EVP_CipherFinal(ctx, out, &out1);
\endcode \endcode
\sa wolfSSL_EVP_CIPHER_CTX_new \sa wolfSSL_EVP_CIPHER_CTX_new
*/ */
WOLFSSL_API int wolfSSL_EVP_CipherFinal(WOLFSSL_EVP_CIPHER_CTX *ctx, WOLFSSL_API int wolfSSL_EVP_CipherFinal(WOLFSSL_EVP_CIPHER_CTX *ctx,
@ -291,15 +291,15 @@ WOLFSSL_API int wolfSSL_EVP_CipherFinal(WOLFSSL_EVP_CIPHER_CTX *ctx,
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief Setter function for WOLFSSL_EVP_CIPHER_CTX structure key length. \brief Setter function for WOLFSSL_EVP_CIPHER_CTX structure key length.
\return SSL_SUCCESS If successfully set. \return SSL_SUCCESS If successfully set.
\return SSL_FAILURE If failed to set key length. \return SSL_FAILURE If failed to set key length.
\param ctx structure to set key length. \param ctx structure to set key length.
\param keylen key length. \param keylen key length.
_Example_ _Example_
\code \code
WOLFSSL_EVP_CIPHER_CTX* ctx; WOLFSSL_EVP_CIPHER_CTX* ctx;
@ -307,7 +307,7 @@ WOLFSSL_API int wolfSSL_EVP_CipherFinal(WOLFSSL_EVP_CIPHER_CTX *ctx,
// create ctx // create ctx
wolfSSL_EVP_CIPHER_CTX_set_key_length(ctx, keylen); wolfSSL_EVP_CIPHER_CTX_set_key_length(ctx, keylen);
\endcode \endcode
\sa wolfSSL_EVP_CIPHER_flags \sa wolfSSL_EVP_CIPHER_flags
*/ */
WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_set_key_length(WOLFSSL_EVP_CIPHER_CTX* ctx, WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_set_key_length(WOLFSSL_EVP_CIPHER_CTX* ctx,
@ -315,53 +315,53 @@ WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_set_key_length(WOLFSSL_EVP_CIPHER_CTX* c
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief This is a getter function for the ctx block size. \brief This is a getter function for the ctx block size.
\return size Returns ctx->block_size. \return size Returns ctx->block_size.
\param ctx the cipher ctx to get block size of. \param ctx the cipher ctx to get block size of.
_Example_ _Example_
\code \code
const WOLFSSL_CVP_CIPHER_CTX* ctx; const WOLFSSL_CVP_CIPHER_CTX* ctx;
//set up ctx //set up ctx
printf(“block size = %d\n”, wolfSSL_EVP_CIPHER_CTX_block_size(ctx)); printf(“block size = %d\n”, wolfSSL_EVP_CIPHER_CTX_block_size(ctx));
\endcode \endcode
\sa wolfSSL_EVP_CIPHER_block_size \sa wolfSSL_EVP_CIPHER_block_size
*/ */
WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_block_size(const WOLFSSL_EVP_CIPHER_CTX *ctx); WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_block_size(const WOLFSSL_EVP_CIPHER_CTX *ctx);
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief This is a getter function for the block size of cipher. \brief This is a getter function for the block size of cipher.
\return size returns the block size. \return size returns the block size.
\param cipher cipher to get block size of. \param cipher cipher to get block size of.
_Example_ _Example_
\code \code
printf(“block size = %d\n”, printf(“block size = %d\n”,
wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_aes_256_ecb())); wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_aes_256_ecb()));
\endcode \endcode
\sa wolfSSL_EVP_aes_256_ctr \sa wolfSSL_EVP_aes_256_ctr
*/ */
WOLFSSL_API int wolfSSL_EVP_CIPHER_block_size(const WOLFSSL_EVP_CIPHER *cipher); WOLFSSL_API int wolfSSL_EVP_CIPHER_block_size(const WOLFSSL_EVP_CIPHER *cipher);
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief Setter function for WOLFSSL_EVP_CIPHER_CTX structure. \brief Setter function for WOLFSSL_EVP_CIPHER_CTX structure.
\return none No returns. \return none No returns.
\param ctx structure to set flag. \param ctx structure to set flag.
\param flag flag to set in structure. \param flag flag to set in structure.
_Example_ _Example_
\code \code
WOLFSSL_EVP_CIPHER_CTX* ctx; WOLFSSL_EVP_CIPHER_CTX* ctx;
@ -369,29 +369,29 @@ WOLFSSL_API int wolfSSL_EVP_CIPHER_block_size(const WOLFSSL_EVP_CIPHER *cipher);
// create ctx // create ctx
wolfSSL_EVP_CIPHER_CTX_set_flags(ctx, flag); wolfSSL_EVP_CIPHER_CTX_set_flags(ctx, flag);
\endcode \endcode
\sa wolfSSL_EVP_CIPHER_flags \sa wolfSSL_EVP_CIPHER_flags
*/ */
WOLFSSL_API void wolfSSL_EVP_CIPHER_CTX_set_flags(WOLFSSL_EVP_CIPHER_CTX *ctx, int flags); WOLFSSL_API void wolfSSL_EVP_CIPHER_CTX_set_flags(WOLFSSL_EVP_CIPHER_CTX *ctx, int flags);
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief Setter function for WOLFSSL_EVP_CIPHER_CTX structure to use padding. \brief Setter function for WOLFSSL_EVP_CIPHER_CTX structure to use padding.
\return SSL_SUCCESS If successfully set. \return SSL_SUCCESS If successfully set.
\return BAD_FUNC_ARG If null argument passed in. \return BAD_FUNC_ARG If null argument passed in.
\param ctx structure to set padding flag. \param ctx structure to set padding flag.
\param padding 0 for not setting padding, 1 for setting padding. \param padding 0 for not setting padding, 1 for setting padding.
_Example_ _Example_
\code \code
WOLFSSL_EVP_CIPHER_CTX* ctx; WOLFSSL_EVP_CIPHER_CTX* ctx;
// create ctx // create ctx
wolfSSL_EVP_CIPHER_CTX_set_padding(ctx, 1); wolfSSL_EVP_CIPHER_CTX_set_padding(ctx, 1);
\endcode \endcode
\sa wolfSSL_EVP_CIPHER_flags \sa wolfSSL_EVP_CIPHER_flags
*/ */
WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_set_padding(WOLFSSL_EVP_CIPHER_CTX *c, int pad); WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_set_padding(WOLFSSL_EVP_CIPHER_CTX *c, int pad);

122
doc/dox_comments/header_files/hash.h
View File

@ -1,15 +1,15 @@
/*! /*!
\ingroup wolfCrypt \ingroup wolfCrypt
\brief This function will return the OID for the wc_HashType provided. \brief This function will return the OID for the wc_HashType provided.
\return OID returns value greater than 0 \return OID returns value greater than 0
\return HASH_TYPE_E hash type not supported. \return HASH_TYPE_E hash type not supported.
\return BAD_FUNC_ARG one of the provided arguments is incorrect. \return BAD_FUNC_ARG one of the provided arguments is incorrect.
\param hash_type A hash type from the “enum wc_HashType” such \param hash_type A hash type from the “enum wc_HashType” such
as “WC_HASH_TYPE_SHA256”. as “WC_HASH_TYPE_SHA256”.
_Example_ _Example_
\code \code
enum wc_HashType hash_type = WC_HASH_TYPE_SHA256; enum wc_HashType hash_type = WC_HASH_TYPE_SHA256;
@ -18,7 +18,7 @@
// Success // Success
} }
\endcode \endcode
\sa wc_HashGetDigestSize \sa wc_HashGetDigestSize
\sa wc_Hash \sa wc_Hash
*/ */
@ -26,19 +26,19 @@ WOLFSSL_API int wc_HashGetOID(enum wc_HashType hash_type);
/*! /*!
\ingroup wolfCrypt \ingroup wolfCrypt
\brief This function returns the size of the digest (output) for a \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 hash_type. The returns size is used to make sure the output buffer
provided to wc_Hash is large enough. provided to wc_Hash is large enough.
\return Success A positive return value indicates the digest size \return Success A positive return value indicates the digest size
for the hash. for the hash.
\return Error Returns HASH_TYPE_E if hash_type is not supported. \return Error Returns HASH_TYPE_E if hash_type is not supported.
\return Failure Returns BAD_FUNC_ARG if an invalid hash_type was used. \return Failure Returns BAD_FUNC_ARG if an invalid hash_type was used.
\param hash_type A hash type from the “enum wc_HashType” such as \param hash_type A hash type from the “enum wc_HashType” such as
“WC_HASH_TYPE_SHA256”. “WC_HASH_TYPE_SHA256”.
_Example_ _Example_
\code \code
int hash_len = wc_HashGetDigestSize(hash_type); int hash_len = wc_HashGetDigestSize(hash_type);
@ -47,26 +47,26 @@ WOLFSSL_API int wc_HashGetOID(enum wc_HashType hash_type);
return BAD_FUNC_ARG; return BAD_FUNC_ARG;
} }
\endcode \endcode
\sa wc_Hash \sa wc_Hash
*/ */
WOLFSSL_API int wc_HashGetDigestSize(enum wc_HashType hash_type); WOLFSSL_API int wc_HashGetDigestSize(enum wc_HashType hash_type);
/*! /*!
\ingroup wolfCrypt \ingroup wolfCrypt
\brief This function performs a hash on the provided data buffer \brief This function performs a hash on the provided data buffer
and returns it in the hash buffer provided. and returns it in the hash buffer provided.
\return 0 Success, else error (such as BAD_FUNC_ARG or BUFFER_E). \return 0 Success, else error (such as BAD_FUNC_ARG or BUFFER_E).
\param hash_type A hash type from the “enum wc_HashType” \param hash_type A hash type from the “enum wc_HashType”
such as “WC_HASH_TYPE_SHA256”. such as “WC_HASH_TYPE_SHA256”.
\param data Pointer to buffer containing the data to hash. \param data Pointer to buffer containing the data to hash.
\param data_len Length of the data buffer. \param data_len Length of the data buffer.
\param hash Pointer to buffer used to output the final hash to. \param hash Pointer to buffer used to output the final hash to.
\param hash_len Length of the hash buffer. \param hash_len Length of the hash buffer.
_Example_ _Example_
\code \code
enum wc_HashType hash_type = WC_HASH_TYPE_SHA256; enum wc_HashType hash_type = WC_HASH_TYPE_SHA256;
@ -78,7 +78,7 @@ WOLFSSL_API int wc_HashGetDigestSize(enum wc_HashType hash_type);
} }
} }
\endcode \endcode
\sa wc_HashGetDigestSize \sa wc_HashGetDigestSize
*/ */
WOLFSSL_API int wc_Hash(enum wc_HashType hash_type, WOLFSSL_API int wc_Hash(enum wc_HashType hash_type,
@ -87,14 +87,14 @@ WOLFSSL_API int wc_Hash(enum wc_HashType hash_type,
/*! /*!
\ingroup MD5 \ingroup MD5
\brief Convenience function, handles all the hashing and places the \brief Convenience function, handles all the hashing and places the
result into hash. result into hash.
\return 0 Returned upon successfully hashing the data. \return 0 Returned upon successfully hashing the data.
\return Memory_E memory error, unable to allocate memory. This is only \return Memory_E memory error, unable to allocate memory. This is only
possible with the small stack option enabled. possible with the small stack option enabled.
\param data the data to hash \param data the data to hash
\param len the length of data \param len the length of data
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
@ -105,13 +105,13 @@ WOLFSSL_API int wc_Hash(enum wc_HashType hash_type,
word32 data_len; word32 data_len;
byte* hash; byte* hash;
int ret; int ret;
... ...
ret = wc_Md5Hash(data, data_len, hash); ret = wc_Md5Hash(data, data_len, hash);
if (ret != 0) { if (ret != 0) {
// Md5 Hash Failure Case. // Md5 Hash Failure Case.
} }
\endcode \endcode
\sa wc_Md5Hash \sa wc_Md5Hash
\sa wc_Md5Final \sa wc_Md5Final
\sa wc_InitMd5 \sa wc_InitMd5
@ -120,23 +120,23 @@ WOLFSSL_API int wc_Md5Hash(const byte* data, word32 len, byte* hash);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Convenience function, handles all the hashing and places the \brief Convenience function, handles all the hashing and places the
result into hash. result into hash.
\return 0 Returned upon successfully …. \return 0 Returned upon successfully ….
\return Memory_E memory error, unable to allocate memory. This is only \return Memory_E memory error, unable to allocate memory. This is only
possible with the small stack option enabled. possible with the small stack option enabled.
\param data the data to hash \param data the data to hash
\param len the length of data \param len the length of data
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
none none
\endcode \endcode
\sa wc_ShaHash \sa wc_ShaHash
\sa wc_ShaFinal \sa wc_ShaFinal
\sa wc_InitSha \sa wc_InitSha
@ -145,23 +145,23 @@ WOLFSSL_API int wc_ShaHash(const byte*, word32, byte*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Convenience function, handles all the hashing and places the \brief Convenience function, handles all the hashing and places the
result into hash. result into hash.
\return 0 Returned upon successfully … \return 0 Returned upon successfully …
\return Memory_E memory error, unable to allocate memory. This is only \return Memory_E memory error, unable to allocate memory. This is only
possible with the small stack option enabled. possible with the small stack option enabled.
\param data the data to hash \param data the data to hash
\param len the length of data \param len the length of data
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
none none
\endcode \endcode
\sa wc_Sha256Hash \sa wc_Sha256Hash
\sa wc_Sha256Final \sa wc_Sha256Final
\sa wc_InitSha256 \sa wc_InitSha256
@ -170,22 +170,22 @@ WOLFSSL_API int wc_Sha256Hash(const byte*, word32, byte*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Convenience function, handles all the hashing and places the \brief Convenience function, handles all the hashing and places the
result into hash. result into hash.
\return 0 Success \return 0 Success
\return <0 Error \return <0 Error
\param data the data to hash \param data the data to hash
\param len the length of data \param len the length of data
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
none none
\endcode \endcode
\sa wc_InitSha224 \sa wc_InitSha224
\sa wc_Sha224Update \sa wc_Sha224Update
\sa wc_Sha224Final \sa wc_Sha224Final
@ -194,14 +194,14 @@ WOLFSSL_API int wc_Sha224Hash(const byte*, word32, byte*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Convenience function, handles all the hashing and places the \brief Convenience function, handles all the hashing and places the
result into hash. result into hash.
\return 0 Returned upon successfully hashing the inputted data \return 0 Returned upon successfully hashing the inputted data
\return Memory_E memory error, unable to allocate memory. This is only \return Memory_E memory error, unable to allocate memory. This is only
possible with the small stack option enabled. possible with the small stack option enabled.
\param data the data to hash \param data the data to hash
\param len the length of data \param len the length of data
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
@ -210,7 +210,7 @@ WOLFSSL_API int wc_Sha224Hash(const byte*, word32, byte*);
\code \code
none none
\endcode \endcode
\sa wc_Sha512Hash \sa wc_Sha512Hash
\sa wc_Sha512Final \sa wc_Sha512Final
\sa wc_InitSha512 \sa wc_InitSha512
@ -219,18 +219,18 @@ WOLFSSL_API int wc_Sha512Hash(const byte*, word32, byte*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Convenience function, handles all the hashing and places the \brief Convenience function, handles all the hashing and places the
result into hash. result into hash.
\return 0 Returned upon successfully hashing the data \return 0 Returned upon successfully hashing the data
\return Memory_E memory error, unable to allocate memory. This is only \return Memory_E memory error, unable to allocate memory. This is only
possible with the small stack option enabled. possible with the small stack option enabled.
\param data the data to hash \param data the data to hash
\param len the length of data \param len the length of data
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
none none

42
doc/dox_comments/header_files/hc128.h
View File

@ -1,24 +1,24 @@
/*! /*!
\ingroup HC128 \ingroup HC128
\brief This function encrypts or decrypts a message of any size from the \brief This function encrypts or decrypts a message of any size from the
input buffer input, and stores the resulting plaintext/ciphertext in input buffer input, and stores the resulting plaintext/ciphertext in
the output buffer output. the output buffer output.
\return 0 Returned upon successfully encrypting/decrypting the given input \return 0 Returned upon successfully encrypting/decrypting the given input
\return MEMORY_E Returned if the input and output buffers are not aligned \return MEMORY_E Returned if the input and output buffers are not aligned
along a 4-byte boundary, and there is an error allocating memory along a 4-byte boundary, and there is an error allocating memory
\return BAD_ALIGN_E Returned if the input or output buffers are not \return BAD_ALIGN_E Returned if the input or output buffers are not
aligned along a 4-byte boundary, and NO_WOLFSSL_ALLOC_ALIGN is defined aligned along a 4-byte boundary, and NO_WOLFSSL_ALLOC_ALIGN is defined
\param ctx pointer to a HC-128 context object with an initialized key \param ctx pointer to a HC-128 context object with an initialized key
to use for encryption or decryption to use for encryption or decryption
\param output buffer in which to store the processed input \param output buffer in which to store the processed input
\param input buffer containing the plaintext to encrypt or the \param input buffer containing the plaintext to encrypt or the
ciphertext to decrypt ciphertext to decrypt
\param msglen length of the plaintext to encrypt or the ciphertext \param msglen length of the plaintext to encrypt or the ciphertext
to decrypt to decrypt
_Example_ _Example_
\code \code
HC128 enc; HC128 enc;
@ -33,26 +33,26 @@
// error encrypting msg // error encrypting msg
} }
\endcode \endcode
\sa wc_Hc128_SetKey \sa wc_Hc128_SetKey
*/ */
WOLFSSL_API int wc_Hc128_Process(HC128*, byte*, const byte*, word32); WOLFSSL_API int wc_Hc128_Process(HC128*, byte*, const byte*, word32);
/*! /*!
\ingroup HC128 \ingroup HC128
\brief This function initializes an HC128 context object by \brief This function initializes an HC128 context object by
setting its key and iv. setting its key and iv.
\return 0 Returned upon successfully setting the key and iv \return 0 Returned upon successfully setting the key and iv
for the HC128 context object for the HC128 context object
\param ctx pointer to an HC-128 context object to initialize \param ctx pointer to an HC-128 context object to initialize
\param key pointer to the buffer containing the 16 byte key to \param key pointer to the buffer containing the 16 byte key to
use with encryption/decryption use with encryption/decryption
\param iv pointer to the buffer containing the 16 byte iv (nonce) \param iv pointer to the buffer containing the 16 byte iv (nonce)
with which to initialize the HC128 object with which to initialize the HC128 object
_Example_ _Example_
\code \code
HC128 enc; HC128 enc;
@ -60,7 +60,7 @@ WOLFSSL_API int wc_Hc128_Process(HC128*, byte*, const byte*, word32);
byte iv[] = { // initialize with iv }; byte iv[] = { // initialize with iv };
wc_Hc128_SetKey(&enc, key, iv); wc_Hc128_SetKey(&enc, key, iv);
\endcode \endcode
\sa wc_Hc128_Process \sa wc_Hc128_Process
*/ */
WOLFSSL_API int wc_Hc128_SetKey(HC128*, const byte* key, const byte* iv); WOLFSSL_API int wc_Hc128_SetKey(HC128*, const byte* key, const byte* iv);

106
doc/dox_comments/header_files/hmac.h
View File

@ -1,25 +1,25 @@
/*! /*!
\ingroup HMAC \ingroup HMAC
\brief This function initializes an Hmac object, setting its \brief This function initializes an Hmac object, setting its
encryption type, key and HMAC length. encryption type, key and HMAC length.
\return 0 Returned on successfully initializing the Hmac object \return 0 Returned on successfully initializing the Hmac object
\return BAD_FUNC_ARG Returned if the input type is invalid. Valid options \return BAD_FUNC_ARG Returned if the input type is invalid. Valid options
are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
\return MEMORY_E Returned if there is an error allocating memory for the \return MEMORY_E Returned if there is an error allocating memory for the
structure to use for hashing structure to use for hashing
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation \return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
and the key length specified is shorter than the minimum acceptable and the key length specified is shorter than the minimum acceptable
FIPS standard FIPS standard
\param hmac pointer to the Hmac object to initialize \param hmac pointer to the Hmac object to initialize
\param type type specifying which encryption method the Hmac object \param type type specifying which encryption method the Hmac object
should use. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID should use. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
\param key pointer to a buffer containing the key with which to \param key pointer to a buffer containing the key with which to
initialize the Hmac object initialize the Hmac object
\param length length of the key \param length length of the key
_Example_ _Example_
\code \code
Hmac hmac; Hmac hmac;
@ -28,7 +28,7 @@
// error initializing Hmac object // error initializing Hmac object
} }
\endcode \endcode
\sa wc_HmacUpdate \sa wc_HmacUpdate
\sa wc_HmacFinal \sa wc_HmacFinal
*/ */
@ -36,21 +36,21 @@ WOLFSSL_API int wc_HmacSetKey(Hmac*, int type, const byte* key, word32 keySz);
/*! /*!
\ingroup HMAC \ingroup HMAC
\brief This function updates the message to authenticate using HMAC. \brief This function updates the message to authenticate using HMAC.
It should be called after the Hmac object has been initialized with It should be called after the Hmac object has been initialized with
wc_HmacSetKey. This function may be called multiple times to update wc_HmacSetKey. This function may be called multiple times to update
the message to hash. After calling wc_HmacUpdate as desired, one should the message to hash. After calling wc_HmacUpdate as desired, one should
call wc_HmacFinal to obtain the final authenticated message tag. call wc_HmacFinal to obtain the final authenticated message tag.
\return 0 Returned on successfully updating the message to authenticate \return 0 Returned on successfully updating the message to authenticate
\return MEMORY_E Returned if there is an error allocating memory for \return MEMORY_E Returned if there is an error allocating memory for
use with a hashing algorithm use with a hashing algorithm
\param hmac pointer to the Hmac object for which to update the message \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 msg pointer to the buffer containing the message to append
\param length length of the message to append \param length length of the message to append
_Example_ _Example_
\code \code
Hmac hmac; Hmac hmac;
@ -64,7 +64,7 @@ WOLFSSL_API int wc_HmacSetKey(Hmac*, int type, const byte* key, word32 keySz);
// error updating with second message // error updating with second message
} }
\endcode \endcode
\sa wc_HmacSetKey \sa wc_HmacSetKey
\sa wc_HmacFinal \sa wc_HmacFinal
*/ */
@ -72,18 +72,18 @@ WOLFSSL_API int wc_HmacUpdate(Hmac*, const byte*, word32);
/*! /*!
\ingroup HMAC \ingroup HMAC
\brief This function computes the final hash of an Hmac object's message. \brief This function computes the final hash of an Hmac object's message.
\return 0 Returned on successfully computing the final hash \return 0 Returned on successfully computing the final hash
\return MEMORY_E Returned if there is an error allocating memory for \return MEMORY_E Returned if there is an error allocating memory for
use with a hashing algorithm use with a hashing algorithm
\param hmac pointer to the Hmac object for which to calculate the \param hmac pointer to the Hmac object for which to calculate the
final hash final hash
\param hash pointer to the buffer in which to store the final hash. \param hash pointer to the buffer in which to store the final hash.
Should have room available as required by the hashing algorithm chosen Should have room available as required by the hashing algorithm chosen
_Example_ _Example_
\code \code
Hmac hmac; Hmac hmac;
@ -95,7 +95,7 @@ WOLFSSL_API int wc_HmacUpdate(Hmac*, const byte*, word32);
// error computing hash // error computing hash
} }
\endcode \endcode
\sa wc_HmacSetKey \sa wc_HmacSetKey
\sa wc_HmacUpdate \sa wc_HmacUpdate
*/ */
@ -103,54 +103,54 @@ WOLFSSL_API int wc_HmacFinal(Hmac*, byte*);
/*! /*!
\ingroup HMAC \ingroup HMAC
\brief This function returns the largest HMAC digest size available \brief This function returns the largest HMAC digest size available
based on the configured cipher suites. based on the configured cipher suites.
\return Success Returns the largest HMAC digest size available based \return Success Returns the largest HMAC digest size available based
on the configured cipher suites on the configured cipher suites
\param none No parameters. \param none No parameters.
_Example_ _Example_
\code \code
int maxDigestSz = wolfSSL_GetHmacMaxSize(); int maxDigestSz = wolfSSL_GetHmacMaxSize();
\endcode \endcode
\sa none \sa none
*/ */
WOLFSSL_API int wolfSSL_GetHmacMaxSize(void); WOLFSSL_API int wolfSSL_GetHmacMaxSize(void);
/*! /*!
\ingroup HMAC \ingroup HMAC
\brief This function provides access to a HMAC Key Derivation Function \brief This function provides access to a HMAC Key Derivation Function
(HKDF). It utilizes HMAC to convert inKey, with an optional salt and (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 optional info into a derived key, which it stores in out. The hash type
defaults to MD5 if 0 or NULL is given. defaults to MD5 if 0 or NULL is given.
\return 0 Returned upon successfully generating a key with the given inputs \return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given as \return BAD_FUNC_ARG Returned if an invalid hash type is given as
argument. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID argument. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, BLAKE2B_ID
\return MEMORY_E Returned if there is an error allocating memory \return MEMORY_E Returned if there is an error allocating memory
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation \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 and the key length specified is shorter than the minimum acceptable FIPS
standard standard
\param type hash type to use for the HKDF. Valid types are: MD5, SHA, \param type hash type to use for the HKDF. Valid types are: MD5, SHA,
SHA256, SHA384, SHA512, BLAKE2B_ID SHA256, SHA384, SHA512, BLAKE2B_ID
\param inKey pointer to the buffer containing the key to use for KDF \param inKey pointer to the buffer containing the key to use for KDF
\param inKeySz length of the input key \param inKeySz length of the input key
\param salt pointer to a buffer containing an optional salt. Use NULL \param salt pointer to a buffer containing an optional salt. Use NULL
instead if not using a salt instead if not using a salt
\param saltSz length of the salt. Use 0 if not using a salt \param saltSz length of the salt. Use 0 if not using a salt
\param info pointer to a buffer containing optional additional info. \param info pointer to a buffer containing optional additional info.
Use NULL if not appending extra info Use NULL if not appending extra info
\param infoSz length of additional info. Use 0 if not using additional 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 out pointer to the buffer in which to store the derived key
\param outSz space available in the output buffer to store the \param outSz space available in the output buffer to store the
generated key generated key
_Example_ _Example_
\code \code
byte key[] = { // initialize with key }; byte key[] = { // initialize with key };
@ -163,7 +163,7 @@ WOLFSSL_API int wolfSSL_GetHmacMaxSize(void);
// error generating derived key // error generating derived key
} }
\endcode \endcode
\sa wc_HmacSetKey \sa wc_HmacSetKey
*/ */
WOLFSSL_API int wc_HKDF(int type, const byte* inKey, word32 inKeySz, WOLFSSL_API int wc_HKDF(int type, const byte* inKey, word32 inKeySz,

40
doc/dox_comments/header_files/idea.h
View File

@ -1,12 +1,12 @@
/*! /*!
\ingroup IDEA \ingroup IDEA
\brief Generate the 52, 16-bit key sub-blocks from the 128 key. \brief Generate the 52, 16-bit key sub-blocks from the 128 key.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returns if idea or key is null, keySz is not equal to \return BAD_FUNC_ARG Returns if idea or key is null, keySz is not equal to
IDEA_KEY_SIZE, or dir is not IDEA_ENCRYPTION or IDEA_DECRYPTION. IDEA_KEY_SIZE, or dir is not IDEA_ENCRYPTION or IDEA_DECRYPTION.
\param idea Pointer to Idea structure. \param idea Pointer to Idea structure.
\param key Pointer to key in memory. \param key Pointer to key in memory.
\param keySz Size of key. \param keySz Size of key.
@ -23,7 +23,7 @@
// There was an error // There was an error
} }
\endcode \endcode
\sa wc_IdeaSetIV \sa wc_IdeaSetIV
*/ */
WOLFSSL_API int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz, WOLFSSL_API int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz,
@ -31,7 +31,7 @@ WOLFSSL_API int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz,
/*! /*!
\ingroup IDEA \ingroup IDEA
\brief Sets the IV in an Idea key structure. \brief Sets the IV in an Idea key structure.
\return 0 Success \return 0 Success
@ -39,7 +39,7 @@ WOLFSSL_API int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz,
\param idea Pointer to idea key structure. \param idea Pointer to idea key structure.
\param iv The IV value to set, can be null. \param iv The IV value to set, can be null.
_Example_ _Example_
\code \code
Idea idea; Idea idea;
@ -52,19 +52,19 @@ WOLFSSL_API int wc_IdeaSetKey(Idea *idea, const byte* key, word16 keySz,
// Some error occured // Some error occured
} }
\endcode \endcode
\sa wc_IdeaSetKey \sa wc_IdeaSetKey
*/ */
WOLFSSL_API int wc_IdeaSetIV(Idea *idea, const byte* iv); WOLFSSL_API int wc_IdeaSetIV(Idea *idea, const byte* iv);
/*! /*!
\ingroup IDEA \ingroup IDEA
\brief Encryption or decryption for a block (64 bits). \brief Encryption or decryption for a block (64 bits).
\return 0 upon success. \return 0 upon success.
\return <0 an error occured \return <0 an error occured
\param idea Pointer to idea key structure. \param idea Pointer to idea key structure.
\param out Pointer to destination. \param out Pointer to destination.
\param in Pointer to input data to encrypt or decrypt. \param in Pointer to input data to encrypt or decrypt.
@ -82,7 +82,7 @@ WOLFSSL_API int wc_IdeaSetIV(Idea *idea, const byte* iv);
// There was an error // There was an error
} }
\endcode \endcode
\sa wc_IdeaSetKey \sa wc_IdeaSetKey
\sa wc_IdeaSetIV \sa wc_IdeaSetIV
\sa wc_IdeaCbcEncrypt \sa wc_IdeaCbcEncrypt
@ -92,9 +92,9 @@ WOLFSSL_API int wc_IdeaCipher(Idea *idea, byte* out, const byte* in);
/*! /*!
\ingroup IDEA \ingroup IDEA
\brief Encrypt data using IDEA CBC mode. \brief Encrypt data using IDEA CBC mode.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returns if any arguments are null. \return BAD_FUNC_ARG Returns if any arguments are null.
@ -102,7 +102,7 @@ WOLFSSL_API int wc_IdeaCipher(Idea *idea, byte* out, const byte* in);
\param out Pointer to destination for encryption. \param out Pointer to destination for encryption.
\param in Pointer to input for encryption. \param in Pointer to input for encryption.
\param len length of input. \param len length of input.
_Example_ _Example_
\code \code
Idea idea; Idea idea;
@ -118,7 +118,7 @@ WOLFSSL_API int wc_IdeaCipher(Idea *idea, byte* out, const byte* in);
// Some error occured // Some error occured
} }
\endcode \endcode
\sa wc_IdeaCbcDecrypt \sa wc_IdeaCbcDecrypt
\sa wc_IdeaCipher \sa wc_IdeaCipher
\sa wc_IdeaSetKey \sa wc_IdeaSetKey
@ -128,17 +128,17 @@ WOLFSSL_API int wc_IdeaCbcEncrypt(Idea *idea, byte* out,
/*! /*!
\ingroup IDEA \ingroup IDEA
\brief Decrypt data using IDEA CBC mode. \brief Decrypt data using IDEA CBC mode.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returns if any arguments are null. \return BAD_FUNC_ARG Returns if any arguments are null.
\param idea Pointer to Idea key structure. \param idea Pointer to Idea key structure.
\param out Pointer to destination for encryption. \param out Pointer to destination for encryption.
\param in Pointer to input for encryption. \param in Pointer to input for encryption.
\param len length of input. \param len length of input.
_Example_ _Example_
\code \code
Idea idea; Idea idea;
@ -154,7 +154,7 @@ WOLFSSL_API int wc_IdeaCbcEncrypt(Idea *idea, byte* out,
// Some error occured // Some error occured
} }
\endcode \endcode
\sa wc_IdeaCbcEncrypt \sa wc_IdeaCbcEncrypt
\sa wc_IdeaCipher \sa wc_IdeaCipher
\sa wc_IdeaSetKey \sa wc_IdeaSetKey

44
doc/dox_comments/header_files/logging.h
View File

@ -1,18 +1,18 @@
/*! /*!
\ingroup Logging \ingroup Logging
\brief This function registers a logging callback that will be used to \brief This function registers a logging callback that will be used to
handle the wolfSSL log message. By default, if the system supports it handle the wolfSSL log message. By default, if the system supports it
fprintf() to stderr is used but by using this function anything fprintf() to stderr is used but by using this function anything
can be done by the user. can be done by the user.
\return Success If successful this function will return 0. \return Success If successful this function will return 0.
\return BAD_FUNC_ARG is the error that will be returned if a function \return BAD_FUNC_ARG is the error that will be returned if a function
pointer is not provided. pointer is not provided.
\param log_function function to register as a logging callback. \param log_function function to register as a logging callback.
Function signature must follow the above prototype. Function signature must follow the above prototype.
_Example_ _Example_
\code \code
int ret = 0; int ret = 0;
@ -28,7 +28,7 @@
// custom logging function // custom logging function
} }
\endcode \endcode
\sa wolfSSL_Debugging_ON \sa wolfSSL_Debugging_ON
\sa wolfSSL_Debugging_OFF \sa wolfSSL_Debugging_OFF
*/ */
@ -37,21 +37,21 @@ WOLFSSL_API int wolfSSL_SetLoggingCb(wolfSSL_Logging_cb log_function);
/*! /*!
\ingroup Debug \ingroup Debug
\brief If logging has been enabled at build time this function turns on \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 logging at runtime. To enable logging at build time use --enable-debug
or define DEBUG_WOLFSSL. or define DEBUG_WOLFSSL.
\return 0 upon success. \return 0 upon success.
\return NOT_COMPILED_IN is the error that will be returned if logging \return NOT_COMPILED_IN is the error that will be returned if logging
isn’t enabled for this build. isn’t enabled for this build.
\param none No parameters. \param none No parameters.
_Example_ _Example_
\code \code
wolfSSL_Debugging_ON(); wolfSSL_Debugging_ON();
\endcode \endcode
\sa wolfSSL_Debugging_OFF \sa wolfSSL_Debugging_OFF
\sa wolfSSL_SetLoggingCb \sa wolfSSL_SetLoggingCb
*/ */
@ -60,18 +60,18 @@ WOLFSSL_API int wolfSSL_Debugging_ON(void);
/*! /*!
\ingroup Debug \ingroup Debug
\brief This function turns off runtime logging messages. If they’re \brief This function turns off runtime logging messages. If they’re
already off, no action is taken. already off, no action is taken.
\return none No returns. \return none No returns.
\param none No parameters. \param none No parameters.
_Example_ _Example_
\code \code
wolfSSL_Debugging_OFF(); wolfSSL_Debugging_OFF();
\endcode \endcode
\sa wolfSSL_Debugging_ON \sa wolfSSL_Debugging_ON
\sa wolfSSL_SetLoggingCb \sa wolfSSL_SetLoggingCb
*/ */

40
doc/dox_comments/header_files/md2.h
View File

@ -1,13 +1,13 @@
/*! /*!
\ingroup MD2 \ingroup MD2
\brief This function initializes md2. This is automatically \brief This function initializes md2. This is automatically
called by wc_Md2Hash. called by wc_Md2Hash.
\return 0 Returned upon successfully initializing \return 0 Returned upon successfully initializing
\param md2 pointer to the md2 structure to use for encryption \param md2 pointer to the md2 structure to use for encryption
_Example_ _Example_
\code \code
md2 md2[1]; md2 md2[1];
@ -19,7 +19,7 @@
wc_Md2Final(md2, hash); wc_Md2Final(md2, hash);
} }
\endcode \endcode
\sa wc_Md2Hash \sa wc_Md2Hash
\sa wc_Md2Update \sa wc_Md2Update
\sa wc_Md2Final \sa wc_Md2Final
@ -28,12 +28,12 @@ WOLFSSL_API void wc_InitMd2(Md2*);
/*! /*!
\ingroup MD2 \ingroup MD2
\brief Can be called to continually hash the provided byte \brief Can be called to continually hash the provided byte
array of length len. array of length len.
\return 0 Returned upon successfully adding the data to the digest. \return 0 Returned upon successfully adding the data to the digest.
\param md2 pointer to the md2 structure to use for encryption \param md2 pointer to the md2 structure to use for encryption
\param data the data to be hashed \param data the data to be hashed
\param len length of data to be hashed \param len length of data to be hashed
@ -52,7 +52,7 @@ WOLFSSL_API void wc_InitMd2(Md2*);
wc_Md2Final(md2, hash); wc_Md2Final(md2, hash);
} }
\endcode \endcode
\sa wc_Md2Hash \sa wc_Md2Hash
\sa wc_Md2Final \sa wc_Md2Final
\sa wc_InitMd2 \sa wc_InitMd2
@ -61,9 +61,9 @@ WOLFSSL_API void wc_Md2Update(Md2*, const byte*, word32);
/*! /*!
\ingroup MD2 \ingroup MD2
\brief Finalizes hashing of data. Result is placed into hash. \brief Finalizes hashing of data. Result is placed into hash.
\return 0 Returned upon successfully finalizing. \return 0 Returned upon successfully finalizing.
\param md2 pointer to the md2 structure to use for encryption \param md2 pointer to the md2 structure to use for encryption
@ -83,7 +83,7 @@ WOLFSSL_API void wc_Md2Update(Md2*, const byte*, word32);
wc_Md2Final(md2, hash); wc_Md2Final(md2, hash);
} }
\endcode \endcode
\sa wc_Md2Hash \sa wc_Md2Hash
\sa wc_Md2Final \sa wc_Md2Final
\sa wc_InitMd2 \sa wc_InitMd2
@ -92,14 +92,14 @@ WOLFSSL_API void wc_Md2Final(Md2*, byte*);
/*! /*!
\ingroup MD2 \ingroup MD2
\brief Convenience function, handles all the hashing and places \brief Convenience function, handles all the hashing and places
the result into hash. the result into hash.
\return 0 Returned upon successfully hashing the data. \return 0 Returned upon successfully hashing the data.
\return Memory_E memory error, unable to allocate memory. This is only \return Memory_E memory error, unable to allocate memory. This is only
possible with the small stack option enabled. possible with the small stack option enabled.
\param data the data to hash \param data the data to hash
\param len the length of data \param len the length of data
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
@ -108,7 +108,7 @@ WOLFSSL_API void wc_Md2Final(Md2*, byte*);
\code \code
none none
\endcode \endcode
\sa wc_Md2Hash \sa wc_Md2Hash
\sa wc_Md2Final \sa wc_Md2Final
\sa wc_InitMd2 \sa wc_InitMd2

28
doc/dox_comments/header_files/md4.h
View File

@ -1,13 +1,13 @@
/*! /*!
\ingroup MD4 \ingroup MD4
\brief This function initializes md4. This is automatically \brief This function initializes md4. This is automatically
called by wc_Md4Hash. called by wc_Md4Hash.
\return 0 Returned upon successfully initializing \return 0 Returned upon successfully initializing
\param md4 pointer to the md4 structure to use for encryption \param md4 pointer to the md4 structure to use for encryption
_Example_ _Example_
\code \code
md4 md4[1]; md4 md4[1];
@ -19,7 +19,7 @@
wc_Md4Final(md4, hash); wc_Md4Final(md4, hash);
} }
\endcode \endcode
\sa wc_Md4Hash \sa wc_Md4Hash
\sa wc_Md4Update \sa wc_Md4Update
\sa wc_Md4Final \sa wc_Md4Final
@ -28,16 +28,16 @@ WOLFSSL_API void wc_InitMd4(Md4*);
/*! /*!
\ingroup MD4 \ingroup MD4
\brief Can be called to continually hash the provided byte array \brief Can be called to continually hash the provided byte array
of length len. of length len.
\return 0 Returned upon successfully adding the data to the digest. \return 0 Returned upon successfully adding the data to the digest.
\param md4 pointer to the md4 structure to use for encryption \param md4 pointer to the md4 structure to use for encryption
\param data the data to be hashed \param data the data to be hashed
\param len length of data to be hashed \param len length of data to be hashed
_Example_ _Example_
\code \code
md4 md4[1]; md4 md4[1];
@ -61,11 +61,11 @@ WOLFSSL_API void wc_Md4Update(Md4*, const byte*, word32);
/*! /*!
\ingroup MD4 \ingroup MD4
\brief Finalizes hashing of data. Result is placed into hash. \brief Finalizes hashing of data. Result is placed into hash.
\return 0 Returned upon successfully finalizing. \return 0 Returned upon successfully finalizing.
\param md4 pointer to the md4 structure to use for encryption \param md4 pointer to the md4 structure to use for encryption
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.

64
doc/dox_comments/header_files/md5.h
View File

@ -1,15 +1,15 @@
/*! /*!
\ingroup MD5 \ingroup MD5
\brief This function initializes md5. This is automatically \brief This function initializes md5. This is automatically
called by wc_Md5Hash. called by wc_Md5Hash.
\return 0 Returned upon successfully initializing. \return 0 Returned upon successfully initializing.
\return BAD_FUNC_ARG Returned if the Md5 structure is passed \return BAD_FUNC_ARG Returned if the Md5 structure is passed
as a NULL value. as a NULL value.
\param md5 pointer to the md5 structure to use for encryption \param md5 pointer to the md5 structure to use for encryption
_Example_ _Example_
\code \code
Md5 md5; Md5 md5;
@ -28,7 +28,7 @@
} }
} }
\endcode \endcode
\sa wc_Md5Hash \sa wc_Md5Hash
\sa wc_Md5Update \sa wc_Md5Update
\sa wc_Md5Final \sa wc_Md5Final
@ -37,19 +37,19 @@ WOLFSSL_API int wc_InitMd5(wc_Md5*);
/*! /*!
\ingroup MD5 \ingroup MD5
\brief Can be called to continually hash the provided byte array of \brief Can be called to continually hash the provided byte array of
length len. length len.
\return 0 Returned upon successfully adding the data to the digest. \return 0 Returned upon successfully adding the data to the digest.
\return BAD_FUNC_ARG Returned if the Md5 structure is NULL or if \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 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. 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 md5 pointer to the md5 structure to use for encryption
\param data the data to be hashed \param data the data to be hashed
\param len length of data to be hashed \param len length of data to be hashed
_Example_ _Example_
\code \code
Md5 md5; Md5 md5;
@ -70,7 +70,7 @@ WOLFSSL_API int wc_InitMd5(wc_Md5*);
} }
} }
\endcode \endcode
\sa wc_Md5Hash \sa wc_Md5Hash
\sa wc_Md5Final \sa wc_Md5Final
\sa wc_InitMd5 \sa wc_InitMd5
@ -79,18 +79,18 @@ WOLFSSL_API int wc_Md5Update(wc_Md5*, const byte*, word32);
/*! /*!
\ingroup MD5 \ingroup MD5
\brief Finalizes hashing of data. Result is placed into hash. Md5 \brief Finalizes hashing of data. Result is placed into hash. Md5
Struct is reset. Note: This function will also return the result Struct is reset. Note: This function will also return the result
of calling IntelQaSymMd5() in the case that HAVE_INTEL_QA is defined. of calling IntelQaSymMd5() in the case that HAVE_INTEL_QA is defined.
\return 0 Returned upon successfully finalizing. \return 0 Returned upon successfully finalizing.
\return BAD_FUNC_ARG Returned if the Md5 structure or hash pointer \return BAD_FUNC_ARG Returned if the Md5 structure or hash pointer
is passed in NULL. is passed in NULL.
\param md5 pointer to the md5 structure to use for encryption \param md5 pointer to the md5 structure to use for encryption
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
md5 md5[1]; md5 md5[1];
@ -111,7 +111,7 @@ WOLFSSL_API int wc_Md5Update(wc_Md5*, const byte*, word32);
} }
} }
\endcode \endcode
\sa wc_Md5Hash \sa wc_Md5Hash
\sa wc_InitMd5 \sa wc_InitMd5
\sa wc_Md5GetHash \sa wc_Md5GetHash
@ -120,12 +120,12 @@ WOLFSSL_API int wc_Md5Final(wc_Md5*, byte*);
/*! /*!
\ingroup MD5 \ingroup MD5
\brief Resets the Md5 structure. Note: this is only supported if \brief Resets the Md5 structure. Note: this is only supported if
you have WOLFSSL_TI_HASH defined. you have WOLFSSL_TI_HASH defined.
\return none No returns. \return none No returns.
\param md5 Pointer to the Md5 structure to be reset. \param md5 Pointer to the Md5 structure to be reset.
_Example_ _Example_
@ -143,7 +143,7 @@ WOLFSSL_API int wc_Md5Final(wc_Md5*, byte*);
wc_Md5Free(&md5); wc_Md5Free(&md5);
} }
\endcode \endcode
\sa wc_InitMd5 \sa wc_InitMd5
\sa wc_Md5Update \sa wc_Md5Update
\sa wc_Md5Final \sa wc_Md5Final
@ -152,15 +152,15 @@ WOLFSSL_API void wc_Md5Free(wc_Md5*);
/*! /*!
\ingroup MD5 \ingroup MD5
\brief Gets hash data. Result is placed into hash. Md5 struct \brief Gets hash data. Result is placed into hash. Md5 struct
is not reset. is not reset.
\return none No returns \return none No returns
\param md5 pointer to the md5 structure to use for encryption. \param md5 pointer to the md5 structure to use for encryption.
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
md5 md5[1]; md5 md5[1];
@ -172,7 +172,7 @@ WOLFSSL_API void wc_Md5Free(wc_Md5*);
wc_Md5GetHash(md5, hash); wc_Md5GetHash(md5, hash);
} }
\endcode \endcode
\sa wc_Md5Hash \sa wc_Md5Hash
\sa wc_Md5Final \sa wc_Md5Final
\sa wc_InitMd5 \sa wc_InitMd5

188
doc/dox_comments/header_files/memory.h
View File

@ -1,23 +1,23 @@
/*! /*!
\ingroup Memory \ingroup Memory
\brief This function calls the custom malloc function, if one has been \brief This function calls the custom malloc function, if one has been
defined, or simply calls the default C malloc function if no custom defined, or simply calls the default C malloc function if no custom
function exists. It is not called directly by wolfSSL, but instead function exists. It is not called directly by wolfSSL, but instead
generally called by using XMALLOC, which may be replaced by generally called by using XMALLOC, which may be replaced by
wolfSSL_Malloc during preprocessing. wolfSSL_Malloc during preprocessing.
\return Success On successfully allocating the desired memory, \return Success On successfully allocating the desired memory,
returns a void* to that location returns a void* to that location
\return NULL Returned when there is a failure to allocate memory \return NULL Returned when there is a failure to allocate memory
\param size size, in bytes, of the memory to allocate \param size size, in bytes, of the memory to allocate
_Example_ _Example_
\code \code
int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10); int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
\endcode \endcode
\sa wolfSSL_Free \sa wolfSSL_Free
\sa wolfSSL_Realloc \sa wolfSSL_Realloc
\sa XMALLOC \sa XMALLOC
@ -28,17 +28,17 @@ WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type, const char*
/*! /*!
\ingroup Memory \ingroup Memory
\brief This function calls a custom free function, if one has been \brief This function calls a custom free function, if one has been
defined, or simply calls the default C free function if no custom defined, or simply calls the default C free function if no custom
function exists. It is not called directly by wolfSSL, but instead function exists. It is not called directly by wolfSSL, but instead
generally called by using XFREE, which may be replaced by wolfSSL_Free generally called by using XFREE, which may be replaced by wolfSSL_Free
during preprocessing. during preprocessing.
\return none No returns. \return none No returns.
\param ptr pointer to the memory to free \param ptr pointer to the memory to free
_Example_ _Example_
\code \code
int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10); int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
@ -59,17 +59,17 @@ WOLFSSL_API void wolfSSL_Free(void *ptr, void* heap, int type, const char* func
/*! /*!
\ingroup Memory \ingroup Memory
\brief This function calls a custom realloc function, if one has been \brief This function calls a custom realloc function, if one has been
defined, or simply calls the default C realloc function if no custom defined, or simply calls the default C realloc function if no custom
function exists. It is not called directly by wolfSSL, but instead function exists. It is not called directly by wolfSSL, but instead
generally called by using XREALLOC, which may be replaced by generally called by using XREALLOC, which may be replaced by
wolfSSL_Realloc during preprocessing. wolfSSL_Realloc during preprocessing.
\return Success On successfully reallocating the desired memory, \return Success On successfully reallocating the desired memory,
returns a void* to that location returns a void* to that location
\return NULL Returned when there is a failure to reallocate memory \return NULL Returned when there is a failure to reallocate memory
\param ptr pointer to the memory to the memory to reallocate \param ptr pointer to the memory to the memory to reallocate
\param size desired size after reallocation \param size desired size after reallocation
@ -78,7 +78,7 @@ WOLFSSL_API void wolfSSL_Free(void *ptr, void* heap, int type, const char* func
int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10); int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
int* twentyInts = (int*)realloc(tenInts, sizeof(tenInts)*2); int* twentyInts = (int*)realloc(tenInts, sizeof(tenInts)*2);
\endcode \endcode
\sa wolfSSL_Malloc \sa wolfSSL_Malloc
\sa wolfSSL_Free \sa wolfSSL_Free
\sa XMALLOC \sa XMALLOC
@ -89,20 +89,20 @@ WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type,
/*! /*!
\ingroup Memory \ingroup Memory
\brief This function is similar to malloc(), but calls the memory \brief This function is similar to malloc(), but calls the memory
allocation function which wolfSSL has been configured to use. By default, allocation function which wolfSSL has been configured to use. By default,
wolfSSL uses malloc(). This can be changed using the wolfSSL memory wolfSSL uses malloc(). This can be changed using the wolfSSL memory
abstraction layer - see wolfSSL_SetAllocators(). abstraction layer - see wolfSSL_SetAllocators().
\return pointer If successful, this function returns a pointer to \return pointer If successful, this function returns a pointer to
allocated memory. allocated memory.
\return error If there is an error, NULL will be returned. \return error If there is an error, NULL will be returned.
\return other Specific return values may be dependent on the underlying \return other Specific return values may be dependent on the underlying
memory allocation function being used (if not using the default malloc()). memory allocation function being used (if not using the default malloc()).
\param size number of bytes to allocate. \param size number of bytes to allocate.
_Example_ _Example_
\code \code
char* buffer; char* buffer;
@ -111,7 +111,7 @@ WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type,
// failed to allocate memory // failed to allocate memory
} }
\endcode \endcode
\sa wolfSSL_Free \sa wolfSSL_Free
\sa wolfSSL_Realloc \sa wolfSSL_Realloc
\sa wolfSSL_SetAllocators \sa wolfSSL_SetAllocators
@ -120,23 +120,23 @@ WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type);
/*! /*!
\ingroup Memory \ingroup Memory
\brief This function is similar to realloc(), but calls the memory \brief This function is similar to realloc(), but calls the memory
re-allocation function which wolfSSL has been configured to use. re-allocation function which wolfSSL has been configured to use.
By default, wolfSSL uses realloc(). This can be changed using the By default, wolfSSL uses realloc(). This can be changed using the
wolfSSL memory abstraction layer - see wolfSSL_SetAllocators(). wolfSSL memory abstraction layer - see wolfSSL_SetAllocators().
\return pointer If successful, this function returns a pointer to \return pointer If successful, this function returns a pointer to
re-allocated memory. This may be the same pointer as ptr, or a re-allocated memory. This may be the same pointer as ptr, or a
new pointer location. new pointer location.
\return Null If there is an error, NULL will be returned. \return Null If there is an error, NULL will be returned.
\return other Specific return values may be dependent on the \return other Specific return values may be dependent on the
underlying memory re-allocation function being used underlying memory re-allocation function being used
(if not using the default realloc()). (if not using the default realloc()).
\param ptr pointer to the previously-allocated memory, to be reallocated. \param ptr pointer to the previously-allocated memory, to be reallocated.
\param size number of bytes to allocate. \param size number of bytes to allocate.
_Example_ _Example_
\code \code
char* buffer; char* buffer;
@ -146,7 +146,7 @@ WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type);
// failed to re-allocate memory // failed to re-allocate memory
} }
\endcode \endcode
\sa wolfSSL_Free \sa wolfSSL_Free
\sa wolfSSL_Malloc \sa wolfSSL_Malloc
\sa wolfSSL_SetAllocators \sa wolfSSL_SetAllocators
@ -155,23 +155,23 @@ WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type);
/*! /*!
\ingroup Memory \ingroup Memory
\brief This function is similar to free(), but calls the memory free \brief This function is similar to free(), but calls the memory free
function which wolfSSL has been configured to use. By default, wolfSSL function which wolfSSL has been configured to use. By default, wolfSSL
uses free(). This can be changed using the wolfSSL memory abstraction uses free(). This can be changed using the wolfSSL memory abstraction
layer - see wolfSSL_SetAllocators(). layer - see wolfSSL_SetAllocators().
\return none No returns. \return none No returns.
\param ptr pointer to the memory to be freed. \param ptr pointer to the memory to be freed.
_Example_ _Example_
\code \code
char* buffer; char* buffer;
... ...
wolfSSL_Free(buffer); wolfSSL_Free(buffer);
\endcode \endcode
\sa wolfSSL_Alloc \sa wolfSSL_Alloc
\sa wolfSSL_Realloc \sa wolfSSL_Realloc
\sa wolfSSL_SetAllocators \sa wolfSSL_SetAllocators
@ -180,23 +180,23 @@ WOLFSSL_API void wolfSSL_Free(void *ptr, const char* func, unsigned int line);
/*! /*!
\ingroup Memory \ingroup Memory
\brief This function registers the allocation functions used by wolfSSL. \brief This function registers the allocation functions used by wolfSSL.
By default, if the system supports it, malloc/free and realloc are used. 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 Using this function allows the user at runtime to install their own
memory handlers. memory handlers.
\return Success If successful this function will return 0. \return Success If successful this function will return 0.
\return BAD_FUNC_ARG is the error that will be returned if a \return BAD_FUNC_ARG is the error that will be returned if a
function pointer is not provided. function pointer is not provided.
\param malloc_function memory allocation function for wolfSSL to use. \param malloc_function memory allocation function for wolfSSL to use.
Function signature must match wolfSSL_Malloc_cb prototype, above. Function signature must match wolfSSL_Malloc_cb prototype, above.
\param free_function memory free function for wolfSSL to use. Function \param free_function memory free function for wolfSSL to use. Function
signature must match wolfSSL_Free_cb prototype, above. signature must match wolfSSL_Free_cb prototype, above.
\param realloc_function memory re-allocation function for wolfSSL to use. \param realloc_function memory re-allocation function for wolfSSL to use.
Function signature must match wolfSSL_Realloc_cb prototype, above. Function signature must match wolfSSL_Realloc_cb prototype, above.
_Example_ _Example_
\code \code
int ret = 0; int ret = 0;
@ -226,7 +226,7 @@ WOLFSSL_API void wolfSSL_Free(void *ptr, const char* func, unsigned int line);
// custom realloc function // custom realloc function
} }
\endcode \endcode
\sa none \sa none
*/ */
WOLFSSL_API int wolfSSL_SetAllocators(wolfSSL_Malloc_cb, WOLFSSL_API int wolfSSL_SetAllocators(wolfSSL_Malloc_cb,
@ -235,21 +235,21 @@ WOLFSSL_API int wolfSSL_SetAllocators(wolfSSL_Malloc_cb,
/*! /*!
\ingroup Memory \ingroup Memory
\brief This function is available when static memory feature is used \brief This function is available when static memory feature is used
(--enable-staticmemory). It gives the optimum buffer size for memory (--enable-staticmemory). It gives the optimum buffer size for memory
“buckets”. This allows for a way to compute buffer size so that no “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. 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. The returned value, if positive, is the computed buffer size to use.
\return Success On successfully completing buffer size calculations a \return Success On successfully completing buffer size calculations a
positive value is returned. This returned value is for optimum buffer size. positive value is returned. This returned value is for optimum buffer size.
\return Failure All negative values are considered to be error cases. \return Failure All negative values are considered to be error cases.
\param buffer pointer to buffer \param buffer pointer to buffer
\param size size of buffer \param size size of buffer
\param type desired type of memory ie WOLFMEM_GENERAL or WOLFMEM_IO_POOL \param type desired type of memory ie WOLFMEM_GENERAL or WOLFMEM_IO_POOL
_Example_ _Example_
\code \code
byte buffer[1000]; byte buffer[1000];
@ -257,11 +257,11 @@ WOLFSSL_API int wolfSSL_SetAllocators(wolfSSL_Malloc_cb,
int optimum; int optimum;
optimum = wolfSSL_StaticBufferSz(buffer, size, WOLFMEM_GENERAL); optimum = wolfSSL_StaticBufferSz(buffer, size, WOLFMEM_GENERAL);
if (optimum < 0) { //handle error case } if (optimum < 0) { //handle error case }
printf(“The optimum buffer size to make use of all memory is %d\n”, printf(“The optimum buffer size to make use of all memory is %d\n”,
optimum); optimum);
... ...
\endcode \endcode
\sa wolfSSL_Malloc \sa wolfSSL_Malloc
\sa wolfSSL_Free \sa wolfSSL_Free
*/ */
@ -269,31 +269,31 @@ WOLFSSL_API int wolfSSL_StaticBufferSz(byte* buffer, word32 sz, int flag);
/*! /*!
\ingroup Memory \ingroup Memory
\brief This function is available when static memory feature is used \brief This function is available when static memory feature is used
(--enable-staticmemory). It gives the size of padding needed for each (--enable-staticmemory). It gives the size of padding needed for each
partition of memory. This padding size will be the size needed to partition of memory. This padding size will be the size needed to
contain a memory management structure along with any extra for contain a memory management structure along with any extra for
memory alignment. memory alignment.
\return On successfully memory padding calculation the return value will \return On successfully memory padding calculation the return value will
be a positive value be a positive value
\return All negative values are considered error cases. \return All negative values are considered error cases.
\param none No parameters. \param none No parameters.
_Example_ _Example_
\code \code
int padding; int padding;
padding = wolfSSL_MemoryPaddingSz(); padding = wolfSSL_MemoryPaddingSz();
if (padding < 0) { //handle error case } if (padding < 0) { //handle error case }
printf(“The padding size needed for each \”bucket\” of memory is %d\n”, printf(“The padding size needed for each \”bucket\” of memory is %d\n”,
padding); padding);
// calculation of buffer for IO POOL size is number of buckets // calculation of buffer for IO POOL size is number of buckets
// times (padding + WOLFMEM_IO_SZ) // times (padding + WOLFMEM_IO_SZ)
... ...
\endcode \endcode
\sa wolfSSL_Malloc \sa wolfSSL_Malloc
\sa wolfSSL_Free \sa wolfSSL_Free
*/ */

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

@ -1,12 +1,12 @@
/*! /*!
\ingroup openSSL \ingroup openSSL
\brief This function writes a key into a WOLFSSL_BIO structure \brief This function writes a key into a WOLFSSL_BIO structure
in PEM format. in PEM format.
\return SSL_SUCCESS upon success. \return SSL_SUCCESS upon success.
\return SSL_FAILURE upon failure. \return SSL_FAILURE upon failure.
\param bio WOLFSSL_BIO structure to get PEM buffer from. \param bio WOLFSSL_BIO structure to get PEM buffer from.
\param key key to convert to PEM format. \param key key to convert to PEM format.
\param cipher EVP cipher structure. \param cipher EVP cipher structure.
@ -14,7 +14,7 @@
\param len length of password. \param len length of password.
\param cb password callback. \param cb password callback.
\param arg optional argument. \param arg optional argument.
_Example_ _Example_
\code \code
WOLFSSL_BIO* bio; WOLFSSL_BIO* bio;
@ -24,7 +24,7 @@
ret = wolfSSL_PEM_write_bio_PrivateKey(bio, key, NULL, NULL, 0, NULL, NULL); ret = wolfSSL_PEM_write_bio_PrivateKey(bio, key, NULL, NULL, 0, NULL, NULL);
//check ret value //check ret value
\endcode \endcode
\sa wolfSSL_PEM_read_bio_X509_AUX \sa wolfSSL_PEM_read_bio_X509_AUX
*/ */
WOLFSSL_API WOLFSSL_API

254
doc/dox_comments/header_files/pkcs7.h
View File

@ -1,51 +1,51 @@
/*! /*!
\ingroup PKCS7 \ingroup PKCS7
\brief This function initializes a PKCS7 structure with a DER-formatted \brief This function initializes a PKCS7 structure with a DER-formatted
certificate. To initialize an empty PKCS7 structure, one can pass in a NULL certificate. To initialize an empty PKCS7 structure, one can pass in a NULL
cert and 0 for certSz. cert and 0 for certSz.
\return 0 Returned on successfully initializing the PKCS7 structure \return 0 Returned on successfully initializing the PKCS7 structure
\return MEMORY_E Returned if there is an error allocating memory \return MEMORY_E Returned if there is an error allocating memory
with XMALLOC with XMALLOC
\return ASN_PARSE_E Returned if there is an error parsing the cert header \return ASN_PARSE_E Returned if there is an error parsing the cert header
\return ASN_OBJECT_ID_E Returned if there is an error parsing the \return ASN_OBJECT_ID_E Returned if there is an error parsing the
encryption type from the cert encryption type from the cert
\return ASN_EXPECT_0_E Returned if there is a formatting error in the \return ASN_EXPECT_0_E Returned if there is a formatting error in the
encryption specification of the cert file encryption specification of the cert file
\return ASN_BEFORE_DATE_E Returned if the date is before the certificate \return ASN_BEFORE_DATE_E Returned if the date is before the certificate
start date start date
\return ASN_AFTER_DATE_E Returned if the date is after the certificate \return ASN_AFTER_DATE_E Returned if the date is after the certificate
expiration date expiration date
\return ASN_BITSTR_E Returned if there is an error parsing a bit string \return ASN_BITSTR_E Returned if there is an error parsing a bit string
from the certificate from the certificate
\return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU \return ASN_NTRU_KEY_E Returned if there is an error parsing the NTRU
key from the certificate key from the certificate
\return ECC_CURVE_OID_E Returned if there is an error parsing the ECC \return ECC_CURVE_OID_E Returned if there is an error parsing the ECC
key from the certificate key from the certificate
\return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown \return ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown
key object id key object id
\return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not \return ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not
defined and the certificate is a V1 or V2 certificate defined and the certificate is a V1 or V2 certificate
\return BAD_FUNC_ARG Returned if there is an error processing the \return BAD_FUNC_ARG Returned if there is an error processing the
certificate extension certificate extension
\return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is \return ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is
encountered in processing the certificate encountered in processing the certificate
\return ASN_SIG_OID_E Returned if the signature encryption type is not \return ASN_SIG_OID_E Returned if the signature encryption type is not
the same as the encryption type of the certificate in the provided file the same as the encryption type of the certificate in the provided file
\return ASN_SIG_CONFIRM_E Returned if confirming the certification \return ASN_SIG_CONFIRM_E Returned if confirming the certification
signature fails signature fails
\return ASN_NAME_INVALID_E Returned if the certificate’s name is not \return ASN_NAME_INVALID_E Returned if the certificate’s name is not
permitted by the CA name constraints permitted by the CA name constraints
\return ASN_NO_SIGNER_E Returned if there is no CA signer to verify \return ASN_NO_SIGNER_E Returned if there is no CA signer to verify
the certificate’s authenticity the certificate’s authenticity
\param pkcs7 pointer to the PKCS7 structure in which to \param pkcs7 pointer to the PKCS7 structure in which to
store the decoded cert store the decoded cert
\param cert pointer to a buffer containing a DER formatted ASN.1 \param cert pointer to a buffer containing a DER formatted ASN.1
certificate with which to initialize the PKCS7 structure certificate with which to initialize the PKCS7 structure
\param certSz size of the certificate buffer \param certSz size of the certificate buffer
_Example_ _Example_
\code \code
PKCS7 pkcs7; PKCS7 pkcs7;
@ -54,20 +54,20 @@
// error parsing certificate into pkcs7 format // error parsing certificate into pkcs7 format
} }
\endcode \endcode
\sa wc_PKCS7_Free \sa wc_PKCS7_Free
*/ */
WOLFSSL_API int wc_PKCS7_InitWithCert(PKCS7* pkcs7, byte* cert, word32 certSz); WOLFSSL_API int wc_PKCS7_InitWithCert(PKCS7* pkcs7, byte* cert, word32 certSz);
/*! /*!
\ingroup PKCS7 \ingroup PKCS7
\brief This function releases any memory allocated by a PKCS7 initializer. \brief This function releases any memory allocated by a PKCS7 initializer.
\return none No returns. \return none No returns.
\param pkcs7 pointer to the PKCS7 structure to free \param pkcs7 pointer to the PKCS7 structure to free
_Example_ _Example_
\code \code
PKCS7 pkcs7; PKCS7 pkcs7;
@ -75,28 +75,28 @@ WOLFSSL_API int wc_PKCS7_InitWithCert(PKCS7* pkcs7, byte* cert, word32 certSz);
wc_PKCS7_Free(pkcs7); wc_PKCS7_Free(pkcs7);
\endcode \endcode
\sa wc_PKCS7_InitWithCert \sa wc_PKCS7_InitWithCert
*/ */
WOLFSSL_API void wc_PKCS7_Free(PKCS7* pkcs7); WOLFSSL_API void wc_PKCS7_Free(PKCS7* pkcs7);
/*! /*!
\ingroup PKCS7 \ingroup PKCS7
\brief This function builds the PKCS7 data content type, encoding the \brief This function builds the PKCS7 data content type, encoding the
PKCS7 structure into a buffer containing a parsable PKCS7 data packet. PKCS7 structure into a buffer containing a parsable PKCS7 data packet.
\return Success On successfully encoding the PKCS7 data into the buffer, \return Success On successfully encoding the PKCS7 data into the buffer,
returns the index parsed up to in the PKCS7 structure. This index also returns the index parsed up to in the PKCS7 structure. This index also
corresponds to the bytes written to the output buffer. corresponds to the bytes written to the output buffer.
\return BUFFER_E Returned if the given buffer is not large enough to hold \return BUFFER_E Returned if the given buffer is not large enough to hold
the encoded certificate the encoded certificate
\param pkcs7 pointer to the PKCS7 structure to encode \param pkcs7 pointer to the PKCS7 structure to encode
\param output pointer to the buffer in which to store the encoded \param output pointer to the buffer in which to store the encoded
certificate certificate
\param outputSz size available in the output buffer \param outputSz size available in the output buffer
_Example_ _Example_
\code \code
PKCS7 pkcs7; PKCS7 pkcs7;
@ -118,7 +118,7 @@ WOLFSSL_API void wc_PKCS7_Free(PKCS7* pkcs7);
// error encoding into output buffer // error encoding into output buffer
} }
\endcode \endcode
\sa wc_PKCS7_InitWithCert \sa wc_PKCS7_InitWithCert
*/ */
WOLFSSL_API int wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output, WOLFSSL_API int wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output,
@ -126,46 +126,46 @@ WOLFSSL_API int wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output,
/*! /*!
\ingroup PKCS7 \ingroup PKCS7
\brief This function builds the PKCS7 signed data content type, encoding \brief This function builds the PKCS7 signed data content type, encoding
the PKCS7 structure into a buffer containing a parsable PKCS7 the PKCS7 structure into a buffer containing a parsable PKCS7
signed data packet. signed data packet.
\return Success On successfully encoding the PKCS7 data into the buffer, \return Success On successfully encoding the PKCS7 data into the buffer,
returns the index parsed up to in the PKCS7 structure. This index also returns the index parsed up to in the PKCS7 structure. This index also
corresponds to the bytes written to the output buffer. corresponds to the bytes written to the output buffer.
\return BAD_FUNC_ARG Returned if the PKCS7 structure is missing one or \return BAD_FUNC_ARG Returned if the PKCS7 structure is missing one or
more required elements to generate a signed data packet more required elements to generate a signed data packet
\return MEMORY_E Returned if there is an error allocating memory \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 PUBLIC_KEY_E Returned if there is an error parsing the public key
\return RSA_BUFFER_E Returned if buffer error, output too small or input \return RSA_BUFFER_E Returned if buffer error, output too small or input
too large too large
\return BUFFER_E Returned if the given buffer is not large enough to hold \return BUFFER_E Returned if the given buffer is not large enough to hold
the encoded certificate the encoded certificate
\return MP_INIT_E may be returned if there is an error generating \return MP_INIT_E may be returned if there is an error generating
the signature the signature
\return MP_READ_E may be returned if there is an error generating \return MP_READ_E may be returned if there is an error generating
the signature the signature
\return MP_CMP_E may be returned if there is an error generating \return MP_CMP_E may be returned if there is an error generating
the signature the signature
\return MP_INVMOD_E may be returned if there is an error generating \return MP_INVMOD_E may be returned if there is an error generating
the signature the signature
\return MP_EXPTMOD_E may be returned if there is an error generating \return MP_EXPTMOD_E may be returned if there is an error generating
the signature the signature
\return MP_MOD_E may be returned if there is an error generating \return MP_MOD_E may be returned if there is an error generating
the signature the signature
\return MP_MUL_E may be returned if there is an error generating \return MP_MUL_E may be returned if there is an error generating
the signature the signature
\return MP_ADD_E may be returned if there is an error generating \return MP_ADD_E may be returned if there is an error generating
the signature the signature
\return MP_MULMOD_E may be returned if there is an error generating \return MP_MULMOD_E may be returned if there is an error generating
the signature the signature
\return MP_TO_E may be returned if there is an error generating \return MP_TO_E may be returned if there is an error generating
the signature the signature
\return MP_MEM 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 pkcs7 pointer to the PKCS7 structure to encode
\param output pointer to the buffer in which to store the \param output pointer to the buffer in which to store the
encoded certificate encoded certificate
\param outputSz size available in the output buffer \param outputSz size available in the output buffer
@ -190,7 +190,7 @@ WOLFSSL_API int wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output,
// error encoding into output buffer // error encoding into output buffer
} }
\endcode \endcode
\sa wc_PKCS7_InitWithCert \sa wc_PKCS7_InitWithCert
\sa wc_PKCS7_VerifySignedData \sa wc_PKCS7_VerifySignedData
*/ */
@ -199,53 +199,53 @@ WOLFSSL_API int wc_PKCS7_EncodeSignedData(PKCS7* pkcs7,
/*! /*!
\ingroup PKCS7 \ingroup PKCS7
\brief This function takes in a transmitted PKCS7 signed data message, \brief This function takes in a transmitted PKCS7 signed data message,
extracts the certificate list and certificate revocation list, and then extracts the certificate list and certificate revocation list, and then
verifies the signature. It stores the extracted content in the given verifies the signature. It stores the extracted content in the given
PKCS7 structure. PKCS7 structure.
\return 0 Returned on successfully extracting the information \return 0 Returned on successfully extracting the information
from the message from the message
\return BAD_FUNC_ARG Returned if one of the input parameters is invalid \return BAD_FUNC_ARG Returned if one of the input parameters is invalid
\return ASN_PARSE_E Returned if there is an error parsing from the \return ASN_PARSE_E Returned if there is an error parsing from the
given pkiMsg given pkiMsg
\return PKCS7_OID_E Returned if the given pkiMsg is not a signed data type \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 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 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 PUBLIC_KEY_E Returned if there is an error parsing the public key
\return RSA_BUFFER_E Returned if buffer error, output too small or \return RSA_BUFFER_E Returned if buffer error, output too small or
input too large input too large
\return BUFFER_E Returned if the given buffer is not large enough to \return BUFFER_E Returned if the given buffer is not large enough to
hold the encoded certificate hold the encoded certificate
\return MP_INIT_E may be returned if there is an error generating \return MP_INIT_E may be returned if there is an error generating
the signature the signature
\return MP_READ_E may be returned if there is an error generating \return MP_READ_E may be returned if there is an error generating
the signature the signature
\return MP_CMP_E may be returned if there is an error generating \return MP_CMP_E may be returned if there is an error generating
the signature the signature
\return MP_INVMOD_E may be returned if there is an error generating \return MP_INVMOD_E may be returned if there is an error generating
the signature the signature
\return MP_EXPTMOD_E may be returned if there is an error generating \return MP_EXPTMOD_E may be returned if there is an error generating
the signature the signature
\return MP_MOD_E may be returned if there is an error generating \return MP_MOD_E may be returned if there is an error generating
the signature the signature
\return MP_MUL_E may be returned if there is an error generating \return MP_MUL_E may be returned if there is an error generating
the signature the signature
\return MP_ADD_E may be returned if there is an error generating \return MP_ADD_E may be returned if there is an error generating
the signature the signature
\return MP_MULMOD_E may be returned if there is an error generating \return MP_MULMOD_E may be returned if there is an error generating
the signature the signature
\return MP_TO_E may be returned if there is an error generating \return MP_TO_E may be returned if there is an error generating
the signature the signature
\return MP_MEM may be returned if there is an error generating the signature \return MP_MEM may be returned if there is an error generating the signature
\param pkcs7 pointer to the PKCS7 structure in which to store the parsed \param pkcs7 pointer to the PKCS7 structure in which to store the parsed
certificates certificates
\param pkiMsg pointer to the buffer containing the signed message to verify \param pkiMsg pointer to the buffer containing the signed message to verify
and decode and decode
\param pkiMsgSz size of the signed message \param pkiMsgSz size of the signed message
_Example_ _Example_
\code \code
PKCS7 pkcs7; PKCS7 pkcs7;
@ -267,7 +267,7 @@ WOLFSSL_API int wc_PKCS7_EncodeSignedData(PKCS7* pkcs7,
// error encoding into output buffer // error encoding into output buffer
} }
\endcode \endcode
\sa wc_PKCS7_InitWithCert \sa wc_PKCS7_InitWithCert
\sa wc_PKCS7_EncodeSignedData \sa wc_PKCS7_EncodeSignedData
*/ */
@ -276,30 +276,30 @@ WOLFSSL_API int wc_PKCS7_VerifySignedData(PKCS7* pkcs7,
/*! /*!
\ingroup PKCS7 \ingroup PKCS7
\brief This function builds the PKCS7 enveloped data content type, encoding \brief This function builds the PKCS7 enveloped data content type, encoding
the PKCS7 structure into a buffer containing a parsable PKCS7 enveloped the PKCS7 structure into a buffer containing a parsable PKCS7 enveloped
data packet. data packet.
\return Success Returned on successfully encoding the message in enveloped \return Success Returned on successfully encoding the message in enveloped
data format, returns the size written to the output buffer data format, returns the size written to the output buffer
\return BAD_FUNC_ARG: Returned if one of the input parameters is invalid, \return BAD_FUNC_ARG: Returned if one of the input parameters is invalid,
or if the PKCS7 structure is missing required elements or if the PKCS7 structure is missing required elements
\return ALGO_ID_E Returned if the PKCS7 structure is using an unsupported \return ALGO_ID_E Returned if the PKCS7 structure is using an unsupported
algorithm type. Currently, only DESb and DES3b are supported algorithm type. Currently, only DESb and DES3b are supported
\return BUFFER_E Returned if the given output buffer is too small to store \return BUFFER_E Returned if the given output buffer is too small to store
the output data the output data
\return MEMORY_E Returned if there is an error allocating memory \return MEMORY_E Returned if there is an error allocating memory
\return RNG_FAILURE_E Returned if there is an error initializing the random \return RNG_FAILURE_E Returned if there is an error initializing the random
number generator for encryption number generator for encryption
\return DRBG_FAILED Returned if there is an error generating numbers with \return DRBG_FAILED Returned if there is an error generating numbers with
the random number generator used for encryption the random number generator used for encryption
\param pkcs7 pointer to the PKCS7 structure to encode \param pkcs7 pointer to the PKCS7 structure to encode
\param output pointer to the buffer in which to store the encoded \param output pointer to the buffer in which to store the encoded
certificate certificate
\param outputSz size available in the output buffer \param outputSz size available in the output buffer
_Example_ _Example_
\code \code
PKCS7 pkcs7; PKCS7 pkcs7;
@ -321,7 +321,7 @@ WOLFSSL_API int wc_PKCS7_VerifySignedData(PKCS7* pkcs7,
// error encoding into output buffer // error encoding into output buffer
} }
\endcode \endcode
\sa wc_PKCS7_InitWithCert \sa wc_PKCS7_InitWithCert
\sa wc_PKCS7_DecodeEnvelopedData \sa wc_PKCS7_DecodeEnvelopedData
*/ */
@ -330,51 +330,51 @@ WOLFSSL_API int wc_PKCS7_EncodeEnvelopedData(PKCS7* pkcs7,
/*! /*!
\ingroup PKCS7 \ingroup PKCS7
\brief This function unwraps and decrypts a PKCS7 enveloped data content \brief This function unwraps and decrypts a PKCS7 enveloped data content
type, decoding the message into output. It uses the private key of the type, decoding the message into output. It uses the private key of the
PKCS7 object passed in to decrypt the message. PKCS7 object passed in to decrypt the message.
\return On successfully extracting the information from the message, \return On successfully extracting the information from the message,
returns the bytes written to output returns the bytes written to output
\return BAD_FUNC_ARG Returned if one of the input parameters is invalid \return BAD_FUNC_ARG Returned if one of the input parameters is invalid
\return ASN_PARSE_E Returned if there is an error parsing from the \return ASN_PARSE_E Returned if there is an error parsing from the
given pkiMsg given pkiMsg
\return PKCS7_OID_E Returned if the given pkiMsg is not an enveloped \return PKCS7_OID_E Returned if the given pkiMsg is not an enveloped
data type data type
\return ASN_VERSION_E Returned if the PKCS7 signer info is not version 0 \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 MEMORY_E Returned if there is an error allocating memory
\return ALGO_ID_E Returned if the PKCS7 structure is using an unsupported \return ALGO_ID_E Returned if the PKCS7 structure is using an unsupported
algorithm type. Currently, only DESb and DES3b are supported for algorithm type. Currently, only DESb and DES3b are supported for
encryption, with RSAk for signature generation encryption, with RSAk for signature generation
\return PKCS7_RECIP_E Returned if there is no recipient found in the \return PKCS7_RECIP_E Returned if there is no recipient found in the
enveloped data that matches the recipient provided enveloped data that matches the recipient provided
\return RSA_BUFFER_E Returned if there is an error during RSA signature \return RSA_BUFFER_E Returned if there is an error during RSA signature
verification due to buffer error, output too small or input too large. verification due to buffer error, output too small or input too large.
\return MP_INIT_E may be returned if there is an error during signature \return MP_INIT_E may be returned if there is an error during signature
verification verification
\return MP_READ_E may be returned if there is an error during signature \return MP_READ_E may be returned if there is an error during signature
verification verification
\return MP_CMP_E may be returned if there is an error during signature \return MP_CMP_E may be returned if there is an error during signature
verification verification
\return MP_INVMOD_E may be returned if there is an error during signature \return MP_INVMOD_E may be returned if there is an error during signature
verification verification
\return MP_EXPTMOD_E may be returned if there is an error during signature \return MP_EXPTMOD_E may be returned if there is an error during signature
verification verification
\return MP_MOD_E may be returned if there is an error during signature \return MP_MOD_E may be returned if there is an error during signature
verification verification
\return MP_MUL_E may be returned if there is an error during signature \return MP_MUL_E may be returned if there is an error during signature
verification verification
\return MP_ADD_E may be returned if there is an error during signature \return MP_ADD_E may be returned if there is an error during signature
verification verification
\return MP_MULMOD_E may be returned if there is an error during signature \return MP_MULMOD_E may be returned if there is an error during signature
verification verification
\return MP_TO_E may be returned if there is an error during signature \return MP_TO_E may be returned if there is an error during signature
verification verification
\return MP_MEM may be returned if there is an error during signature \return MP_MEM may be returned if there is an error during signature
verification verification
\param pkcs7 pointer to the PKCS7 structure containing the private key with \param pkcs7 pointer to the PKCS7 structure containing the private key with
which to decode the enveloped data package which to decode the enveloped data package
\param pkiMsg pointer to the buffer containing the enveloped data package \param pkiMsg pointer to the buffer containing the enveloped data package
\param pkiMsgSz size of the enveloped data package \param pkiMsgSz size of the enveloped data package
@ -393,13 +393,13 @@ WOLFSSL_API int wc_PKCS7_EncodeEnvelopedData(PKCS7* pkcs7,
pkcs7.privateKey = key; pkcs7.privateKey = key;
pkcs7.privateKeySz = keySz; pkcs7.privateKeySz = keySz;
decodedSz = wc_PKCS7_DecodeEnvelopedData(&pkcs7, received, decodedSz = wc_PKCS7_DecodeEnvelopedData(&pkcs7, received,
sizeof(received),decoded, sizeof(decoded)); sizeof(received),decoded, sizeof(decoded));
if ( decodedSz != 0 ) { if ( decodedSz != 0 ) {
// error decoding message // error decoding message
} }
\endcode \endcode
\sa wc_PKCS7_InitWithCert \sa wc_PKCS7_InitWithCert
\sa wc_PKCS7_EncodeEnvelopedData \sa wc_PKCS7_EncodeEnvelopedData
*/ */

66
doc/dox_comments/header_files/poly1305.h
View File

@ -1,15 +1,15 @@
/*! /*!
\ingroup Poly1305 \ingroup Poly1305
\brief This function sets the key for a Poly1305 context structure, \brief This function sets the key for a Poly1305 context structure,
initializing it for hashing. Note: A new key should be set after initializing it for hashing. Note: A new key should be set after
generating a message hash with wc_Poly1305Final to ensure security. generating a message hash with wc_Poly1305Final to ensure security.
\return 0 Returned on successfully setting the key and initializing \return 0 Returned on successfully setting the key and initializing
the Poly1305 structure the Poly1305 structure
\return BAD_FUNC_ARG Returned if the given key is not 32 bytes long, \return BAD_FUNC_ARG Returned if the given key is not 32 bytes long,
or the Poly1305 context is NULL or the Poly1305 context is NULL
\param ctx pointer to a Poly1305 structure to initialize \param ctx pointer to a Poly1305 structure to initialize
\param key pointer to the buffer containing the key to use for hashing \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 \param keySz size of the key in the buffer. Should be 32 bytes
@ -20,7 +20,7 @@
byte key[] = { initialize with 32 byte key to use for hashing }; byte key[] = { initialize with 32 byte key to use for hashing };
wc_Poly1305SetKey(&enc, key, sizeof(key)); wc_Poly1305SetKey(&enc, key, sizeof(key));
\endcode \endcode
\sa wc_Poly1305Update \sa wc_Poly1305Update
\sa wc_Poly1305Final \sa wc_Poly1305Final
*/ */
@ -29,16 +29,16 @@ WOLFSSL_API int wc_Poly1305SetKey(Poly1305* poly1305, const byte* key,
/*! /*!
\ingroup Poly1305 \ingroup Poly1305
\brief This function updates the message to hash with the \brief This function updates the message to hash with the
Poly1305 structure. Poly1305 structure.
\return 0 Returned on successfully updating the message to hash \return 0 Returned on successfully updating the message to hash
\return BAD_FUNC_ARG Returned if the Poly1305 structure is NULL \return BAD_FUNC_ARG Returned if the Poly1305 structure is NULL
\param ctx pointer to a Poly1305 structure for which to update \param ctx pointer to a Poly1305 structure for which to update
the message to hash the message to hash
\param m pointer to the buffer containing the message which should \param m pointer to the buffer containing the message which should
be added to the hash be added to the hash
\param bytes size of the message to hash \param bytes size of the message to hash
@ -54,7 +54,7 @@ WOLFSSL_API int wc_Poly1305SetKey(Poly1305* poly1305, const byte* key,
// error updating message to hash // error updating message to hash
} }
\endcode \endcode
\sa wc_Poly1305SetKey \sa wc_Poly1305SetKey
\sa wc_Poly1305Final \sa wc_Poly1305Final
*/ */
@ -62,18 +62,18 @@ WOLFSSL_API int wc_Poly1305Update(Poly1305* poly1305, const byte*, word32);
/*! /*!
\ingroup Poly1305 \ingroup Poly1305
\brief This function calculates the hash of the input messages \brief This function calculates the hash of the input messages
and stores the result in mac. After this is called, the key and stores the result in mac. After this is called, the key
should be reset. should be reset.
\return 0 Returned on successfully computing the final MAC \return 0 Returned on successfully computing the final MAC
\return BAD_FUNC_ARG Returned if the Poly1305 structure is NULL \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 ctx pointer to a Poly1305 structure with which to generate the MAC
\param mac pointer to the buffer in which to store the MAC. \param mac pointer to the buffer in which to store the MAC.
Should be POLY1305_DIGEST_SIZE (16 bytes) wide Should be POLY1305_DIGEST_SIZE (16 bytes) wide
_Example_ _Example_
\code \code
Poly1305 enc; Poly1305 enc;
@ -89,7 +89,7 @@ WOLFSSL_API int wc_Poly1305Update(Poly1305* poly1305, const byte*, word32);
// error computing final MAC // error computing final MAC
} }
\endcode \endcode
\sa wc_Poly1305SetKey \sa wc_Poly1305SetKey
\sa wc_Poly1305Update \sa wc_Poly1305Update
*/ */
@ -97,40 +97,40 @@ WOLFSSL_API int wc_Poly1305Final(Poly1305* poly1305, byte* tag);
/*! /*!
\ingroup Poly1305 \ingroup Poly1305
\brief Takes in an initialized Poly1305 struct that has a key \brief Takes in an initialized Poly1305 struct that has a key
loaded and creates a MAC (tag) using recent TLS AEAD padding scheme. loaded and creates a MAC (tag) using recent TLS AEAD padding scheme.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returned if ctx, input, or tag is null or if \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 additional is null and addSz is greater than 0 or if tagSz is less
than WC_POLY1305_MAC_SZ. than WC_POLY1305_MAC_SZ.
\param ctx Initialized Poly1305 struct to use \param ctx Initialized Poly1305 struct to use
\param additional Additional data to use \param additional Additional data to use
\param addSz Size of additional buffer \param addSz Size of additional buffer
\param input Input buffer to create tag from \param input Input buffer to create tag from
\param sz Size of input buffer \param sz Size of input buffer
\param tag Buffer to hold created tag \param tag Buffer to hold created tag
\param tagSz Size of input tag buffer (must be at least \param tagSz Size of input tag buffer (must be at least
WC_POLY1305_MAC_SZ(16)) WC_POLY1305_MAC_SZ(16))
_Example_ _Example_
\code \code
Poly1305 ctx; Poly1305 ctx;
byte key[] = { }; // initialize with 32 byte key to use for hashing byte key[] = { }; // initialize with 32 byte key to use for hashing
byte additional[] = { }; // initialize with additional data byte additional[] = { }; // initialize with additional data
byte msg[] = { }; // initialize with message byte msg[] = { }; // initialize with message
byte tag[16]; byte tag[16];
wc_Poly1305SetKey(&ctx, key, sizeof(key)); wc_Poly1305SetKey(&ctx, key, sizeof(key));
if(wc_Poly1305_MAC(&ctx, additional, sizeof(additional), (byte*)msg, if(wc_Poly1305_MAC(&ctx, additional, sizeof(additional), (byte*)msg,
sizeof(msg), tag, sizeof(tag)) != 0) sizeof(msg), tag, sizeof(tag)) != 0)
{ {
// Handle the error // Handle the error
} }
\endcode \endcode
\sa wc_Poly1305SetKey \sa wc_Poly1305SetKey
\sa wc_Poly1305Update \sa wc_Poly1305Update
\sa wcPoly1305Final \sa wcPoly1305Final

114
doc/dox_comments/header_files/pwdbased.h
View File

@ -1,45 +1,45 @@
/*! /*!
\ingroup Password \ingroup Password
\brief This function implements the Password Based Key Derivation \brief This function implements the Password Based Key Derivation
Function 1 (PBKDF1), converting an input password with a concatenated salt 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 into a more secure key, which it stores in output. It allows the user to
select between SHA and MD5 as hash functions. select between SHA and MD5 as hash functions.
\return 0 Returned on successfully deriving a key from the input password \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 \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 (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 length (kLen) requested is greater than the hash length of the provided hash
\return MEMORY_E Returned if there is an error allocating memory for a \return MEMORY_E Returned if there is an error allocating memory for a
SHA or MD5 object SHA or MD5 object
\param output pointer to the buffer in which to store the generated key. \param output pointer to the buffer in which to store the generated key.
Should be at least kLen long Should be at least kLen long
\param passwd pointer to the buffer containing the password to use for \param passwd pointer to the buffer containing the password to use for
the key derivation the key derivation
\param pLen length of the password to use for key derivation \param pLen length of the password to use for key derivation
\param salt pointer to the buffer containing the salt to use for \param salt pointer to the buffer containing the salt to use for
key derivation key derivation
\param sLen length of the salt \param sLen length of the salt
\param iterations number of times to process the hash \param iterations number of times to process the hash
\param kLen desired length of the derived key. Should not be longer \param kLen desired length of the derived key. Should not be longer
than the digest size of the hash chosen than the digest size of the hash chosen
\param hashType the hashing algorithm to use. Valid choices are MD5 and SHA \param hashType the hashing algorithm to use. Valid choices are MD5 and SHA
_Example_ _Example_
\code \code
int ret; int ret;
byte key[MD5_DIGEST_SIZE]; byte key[MD5_DIGEST_SIZE];
byte pass[] = { }; // initialize with password byte pass[] = { }; // initialize with password
byte salt[] = { }; // initialize with salt byte salt[] = { }; // initialize with salt
ret = wc_PBKDF1(key, pass, sizeof(pass), salt, sizeof(salt), 1000, ret = wc_PBKDF1(key, pass, sizeof(pass), salt, sizeof(salt), 1000,
sizeof(key), MD5); sizeof(key), MD5);
if ( ret != 0 ) { if ( ret != 0 ) {
// error deriving key from password // error deriving key from password
} }
\endcode \endcode
\sa wc_PBKDF2 \sa wc_PBKDF2
\sa wc_PKCS12_PBKDF \sa wc_PKCS12_PBKDF
*/ */
@ -49,32 +49,32 @@ WOLFSSL_API int wc_PBKDF1(byte* output, const byte* passwd, int pLen,
/*! /*!
\ingroup Password \ingroup Password
\brief This function implements the Password Based Key Derivation \brief This function implements the Password Based Key Derivation
Function 2 (PBKDF2), converting an input password with a concatenated 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 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, to select any of the supported HMAC hash functions, including: MD5, SHA,
SHA256, SHA384, SHA512, and BLAKE2B SHA256, SHA384, SHA512, and BLAKE2B
\return 0 Returned on successfully deriving a key from the input password \return 0 Returned on successfully deriving a key from the input password
\return BAD_FUNC_ARG Returned if there is an invalid hash type given or \return BAD_FUNC_ARG Returned if there is an invalid hash type given or
iterations is less than 1 iterations is less than 1
\return MEMORY_E Returned if there is an allocating memory for \return MEMORY_E Returned if there is an allocating memory for
the HMAC object the HMAC object
\param output pointer to the buffer in which to store the generated key. \param output pointer to the buffer in which to store the generated key.
Should be kLen long Should be kLen long
\param passwd pointer to the buffer containing the password to use for \param passwd pointer to the buffer containing the password to use for
the key derivation the key derivation
\param pLen length of the password to use for key derivation \param pLen length of the password to use for key derivation
\param salt pointer to the buffer containing the salt to use for \param salt pointer to the buffer containing the salt to use for
key derivation key derivation
\param sLen length of the salt \param sLen length of the salt
\param iterations number of times to process the hash \param iterations number of times to process the hash
\param kLen desired length of the derived key \param kLen desired length of the derived key
\param hashType the hashing algorithm to use. Valid choices are: MD5, \param hashType the hashing algorithm to use. Valid choices are: MD5,
SHA, SHA256, SHA384, SHA512, and BLAKE2B SHA, SHA256, SHA384, SHA512, and BLAKE2B
_Example_ _Example_
\code \code
int ret; int ret;
@ -82,13 +82,13 @@ WOLFSSL_API int wc_PBKDF1(byte* output, const byte* passwd, int pLen,
byte pass[] = { }; // initialize with password byte pass[] = { }; // initialize with password
byte salt[] = { }; // initialize with salt byte salt[] = { }; // initialize with salt
ret = wc_PBKDF2(key, pass, sizeof(pass), salt, sizeof(salt), 2048, sizeof(key), ret = wc_PBKDF2(key, pass, sizeof(pass), salt, sizeof(salt), 2048, sizeof(key),
SHA512); SHA512);
if ( ret != 0 ) { if ( ret != 0 ) {
// error deriving key from password // error deriving key from password
} }
\endcode \endcode
\sa wc_PBKDF1 \sa wc_PBKDF1
\sa wc_PKCS12_PBKDF \sa wc_PKCS12_PBKDF
*/ */
@ -98,66 +98,66 @@ WOLFSSL_API int wc_PBKDF2(byte* output, const byte* passwd, int pLen,
/*! /*!
\ingroup Password \ingroup Password
\brief This function implements the Password Based Key Derivation Function \brief This function implements the Password Based Key Derivation Function
(PBKDF) described in RFC 7292 Appendix B. This function converts an input (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 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 in output. It allows the user to select any of the supported HMAC hash
functions, including: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B. functions, including: MD5, SHA, SHA256, SHA384, SHA512, and BLAKE2B.
\return 0 Returned on successfully deriving a key from the input password \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, \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 iterations is less than 1, or the key length (kLen) requested is greater
than the hash length of the provided hash than the hash length of the provided hash
\return MEMORY_E Returned if there is an allocating memory \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_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_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_CMP_E may be returned if there is an error during key generation
\return MP_INVMOD_E may be returned if there is an error during \return MP_INVMOD_E may be returned if there is an error during
key generation key generation
\return MP_EXPTMOD_E may be returned if there is an error during \return MP_EXPTMOD_E may be returned if there is an error during
key generation key generation
\return MP_MOD_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_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_ADD_E may be returned if there is an error during key generation
\return MP_MULMOD_E may be returned if there is an error during \return MP_MULMOD_E may be returned if there is an error during
key generation key generation
\return MP_TO_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 \return MP_MEM may be returned if there is an error during key generation
\param output pointer to the buffer in which to store the generated key. \param output pointer to the buffer in which to store the generated key.
Should be kLen long Should be kLen long
\param passwd pointer to the buffer containing the password to use for \param passwd pointer to the buffer containing the password to use for
the key derivation the key derivation
\param pLen length of the password to use for key derivation \param pLen length of the password to use for key derivation
\param salt pointer to the buffer containing the salt to use \param salt pointer to the buffer containing the salt to use
for key derivation for key derivation
\param sLen length of the salt \param sLen length of the salt
\param iterations number of times to process the hash \param iterations number of times to process the hash
\param kLen desired length of the derived key \param kLen desired length of the derived key
\param hashType the hashing algorithm to use. Valid choices are: MD5, \param hashType the hashing algorithm to use. Valid choices are: MD5,
SHA, SHA256, SHA384, SHA512, and BLAKE2B SHA, SHA256, SHA384, SHA512, and BLAKE2B
\param id this is a byte indetifier indicating the purpose of key \param id this is a byte indetifier indicating the purpose of key
generation. It is used to diversify the key output, and should be 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 assigned as follows: ID=1: pseudorandom bits are to be used as key
material for performing encryption or decryption. ID=2: pseudorandom material for performing encryption or decryption. ID=2: pseudorandom
bits are to be used an IV (Initial Value) for encryption or decryption. 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. ID=3: pseudorandom bits are to be used as an integrity key for MACing.
_Example_ _Example_
\code \code
int ret; int ret;
byte key[64]; byte key[64];
byte pass[] = { }; // initialize with password byte pass[] = { }; // initialize with password
byte salt[] = { }; // initialize with salt byte salt[] = { }; // initialize with salt
ret = wc_PKCS512_PBKDF(key, pass, sizeof(pass), salt, sizeof(salt), 2048, ret = wc_PKCS512_PBKDF(key, pass, sizeof(pass), salt, sizeof(salt), 2048,
sizeof(key), SHA512, 1); sizeof(key), SHA512, 1);
if ( ret != 0 ) { if ( ret != 0 ) {
// error deriving key from password // error deriving key from password
} }
\endcode \endcode
\sa wc_PBKDF1 \sa wc_PBKDF1
\sa wc_PBKDF2 \sa wc_PBKDF2
*/ */

36
doc/dox_comments/header_files/rabbit.h
View File

@ -1,23 +1,23 @@
/*! /*!
\ingroup Rabbit \ingroup Rabbit
\brief This function encrypts or decrypts a message of any size, storing \brief This function encrypts or decrypts a message of any size, storing
the result in output. It requires that the Rabbit ctx structure be the result in output. It requires that the Rabbit ctx structure be
initialized with a key and an iv before encryption. initialized with a key and an iv before encryption.
\return 0 Returned on successfully encrypting/decrypting input \return 0 Returned on successfully encrypting/decrypting input
\return BAD_ALIGN_E Returned if the input message is not 4-byte aligned \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 but is required to be by XSTREAM_ALIGN, but NO_WOLFSSL_ALLOC_ALIGN is
defined defined
\return MEMORY_E Returned if there is an error allocating memory to \return MEMORY_E Returned if there is an error allocating memory to
align the message, if NO_WOLFSSL_ALLOC_ALIGN is not defined align the message, if NO_WOLFSSL_ALLOC_ALIGN is not defined
\param ctx pointer to the Rabbit structure to use for encryption/decryption \param ctx pointer to the Rabbit structure to use for encryption/decryption
\param output pointer to the buffer in which to store the processed \param output pointer to the buffer in which to store the processed
message. Should be at least msglen long message. Should be at least msglen long
\param input pointer to the buffer containing the message to process \param input pointer to the buffer containing the message to process
\param msglen the length of the message to process \param msglen the length of the message to process
_Example_ _Example_
\code \code
int ret; int ret;
@ -32,25 +32,25 @@
wc_RabbitProcess(enc, ciphertext, message, sizeof(message)); wc_RabbitProcess(enc, ciphertext, message, sizeof(message));
\endcode \endcode
\sa wc_RabbitSetKey \sa wc_RabbitSetKey
*/ */
WOLFSSL_API int wc_RabbitProcess(Rabbit*, byte*, const byte*, word32); WOLFSSL_API int wc_RabbitProcess(Rabbit*, byte*, const byte*, word32);
/*! /*!
\ingroup Rabbit \ingroup Rabbit
\brief This function initializes a Rabbit context for use with \brief This function initializes a Rabbit context for use with
encryption or decryption by setting its iv and key. encryption or decryption by setting its iv and key.
\return 0 Returned on successfully setting the key and iv \return 0 Returned on successfully setting the key and iv
\param ctx pointer to the Rabbit structure to initialize \param ctx pointer to the Rabbit structure to initialize
\param key pointer to the buffer containing the 16 byte key to \param key pointer to the buffer containing the 16 byte key to
use for encryption/decryption use for encryption/decryption
\param iv pointer to the buffer containing the 8 byte iv with \param iv pointer to the buffer containing the 8 byte iv with
which to initialize the Rabbit structure which to initialize the Rabbit structure
_Example_ _Example_
\code \code
int ret; int ret;
@ -60,7 +60,7 @@ WOLFSSL_API int wc_RabbitProcess(Rabbit*, byte*, const byte*, word32);
wc_RabbitSetKey(&enc, key, iv) wc_RabbitSetKey(&enc, key, iv)
\endcode \endcode
\sa wc_RabbitProcess \sa wc_RabbitProcess
*/ */
WOLFSSL_API int wc_RabbitSetKey(Rabbit*, const byte* key, const byte* iv); WOLFSSL_API int wc_RabbitSetKey(Rabbit*, const byte* key, const byte* iv);

108
doc/dox_comments/header_files/random.h
View File

@ -1,16 +1,16 @@
/*! /*!
\ingroup Random \ingroup Random
\brief Init global Whitewood netRandom context \brief Init global Whitewood netRandom context
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Either configFile is null or timeout is negative. \return BAD_FUNC_ARG Either configFile is null or timeout is negative.
\return RNG_FAILURE_E There was a failure initializing the rng. \return RNG_FAILURE_E There was a failure initializing the rng.
\param configFile Path to configuration file \param configFile Path to configuration file
\param hmac_cb Optional to create HMAC callback. \param hmac_cb Optional to create HMAC callback.
\param timeout A timeout duration. \param timeout A timeout duration.
_Example_ _Example_
\code \code
char* config = "path/to/config/example.conf"; char* config = "path/to/config/example.conf";
@ -21,21 +21,21 @@
// Some error occured // Some error occured
} }
\endcode \endcode
\sa wc_FreeNetRandom \sa wc_FreeNetRandom
*/ */
WOLFSSL_API int wc_InitNetRandom(const char*, wnr_hmac_key, int); WOLFSSL_API int wc_InitNetRandom(const char*, wnr_hmac_key, int);
/*! /*!
\ingroup Random \ingroup Random
\brief Free global Whitewood netRandom context. \brief Free global Whitewood netRandom context.
\return 0 Success \return 0 Success
\return BAD_MUTEX_E Error locking mutex on wnr_mutex \return BAD_MUTEX_E Error locking mutex on wnr_mutex
\param none No returns. \param none No returns.
_Example_ _Example_
\code \code
int ret = wc_FreeNetRandom(); int ret = wc_FreeNetRandom();
@ -44,40 +44,40 @@ WOLFSSL_API int wc_InitNetRandom(const char*, wnr_hmac_key, int);
// Handle the error // Handle the error
} }
\endcode \endcode
\sa wc_InitNetRandom \sa wc_InitNetRandom
*/ */
WOLFSSL_API int wc_FreeNetRandom(void); WOLFSSL_API int wc_FreeNetRandom(void);
/*! /*!
\ingroup Random \ingroup Random
\brief Gets the seed (from OS) and key cipher for rng. rng->drbg \brief Gets the seed (from OS) and key cipher for rng. rng->drbg
(deterministic random bit generator) allocated (should be deallocated (deterministic random bit generator) allocated (should be deallocated
with wc_FreeRng). This is a blocking operation. with wc_FreeRng). This is a blocking operation.
\return 0 on success. \return 0 on success.
\return MEMORY_E XMALLOC failed \return MEMORY_E XMALLOC failed
\return WINCRYPT_E wc_GenerateSeed: failed to acquire context \return WINCRYPT_E wc_GenerateSeed: failed to acquire context
\return CRYPTGEN_E wc_GenerateSeed: failed to get random \return CRYPTGEN_E wc_GenerateSeed: failed to get random
\return BAD_FUNC_ARG wc_RNG_GenerateBlock input is null or sz exceeds \return BAD_FUNC_ARG wc_RNG_GenerateBlock input is null or sz exceeds
MAX_REQUEST_LEN MAX_REQUEST_LEN
\return DRBG_CONT_FIPS_E wc_RNG_GenerateBlock: Hash_gen returned \return DRBG_CONT_FIPS_E wc_RNG_GenerateBlock: Hash_gen returned
DRBG_CONT_FAILURE DRBG_CONT_FAILURE
\return RNG_FAILURE_E wc_RNG_GenerateBlock: Default error. rng’s \return RNG_FAILURE_E wc_RNG_GenerateBlock: Default error. rng’s
status originally not ok, or set to DRBG_FAILED status originally not ok, or set to DRBG_FAILED
\param rng random number generator to be initialized for use \param rng random number generator to be initialized for use
with a seed and key cipher with a seed and key cipher
_Example_ _Example_
\code \code
RNG rng; RNG rng;
int ret; int ret;
#ifdef HAVE_CAVIUM #ifdef HAVE_CAVIUM
ret = wc_InitRngCavium(&rng, CAVIUM_DEV_ID); ret = wc_InitRngCavium(&rng, CAVIUM_DEV_ID);
if (ret != 0){ if (ret != 0){
printf(“RNG Nitrox init for device: %d failed”, CAVIUM_DEV_ID); printf(“RNG Nitrox init for device: %d failed”, CAVIUM_DEV_ID);
return -1; return -1;
} }
@ -88,7 +88,7 @@ WOLFSSL_API int wc_FreeNetRandom(void);
return -1; return -1;
} }
\endcode \endcode
\sa wc_InitRngCavium \sa wc_InitRngCavium
\sa wc_RNG_GenerateBlock \sa wc_RNG_GenerateBlock
\sa wc_RNG_GenerateByte \sa wc_RNG_GenerateByte
@ -99,20 +99,20 @@ WOLFSSL_API int wc_InitRng(WC_RNG*);
/*! /*!
\ingroup Random \ingroup Random
\brief Copies a sz bytes of pseudorandom data to output. Will \brief Copies a sz bytes of pseudorandom data to output. Will
reseed rng if needed (blocking). reseed rng if needed (blocking).
\return 0 on success \return 0 on success
\return BAD_FUNC_ARG an input is null or sz exceeds MAX_REQUEST_LEN \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 DRBG_CONT_FIPS_E Hash_gen returned DRBG_CONT_FAILURE
\return RNG_FAILURE_E Default error. rng’s status originally not \return RNG_FAILURE_E Default error. rng’s status originally not
ok, or set to DRBG_FAILED ok, or set to DRBG_FAILED
\param rng random number generator initialized with wc_InitRng \param rng random number generator initialized with wc_InitRng
\param output buffer to which the block is copied \param output buffer to which the block is copied
\param sz size of output in bytes \param sz size of output in bytes
_Example_ _Example_
\code \code
RNG rng; RNG rng;
@ -123,13 +123,13 @@ WOLFSSL_API int wc_InitRng(WC_RNG*);
if (ret != 0) { if (ret != 0) {
return -1; //init of rng failed! return -1; //init of rng failed!
} }
ret = wc_RNG_GenerateBlock(&rng, block, sz); ret = wc_RNG_GenerateBlock(&rng, block, sz);
if (ret != 0) { if (ret != 0) {
return -1; //generating block failed! return -1; //generating block failed!
} }
\endcode \endcode
\sa wc_InitRngCavium, wc_InitRng \sa wc_InitRngCavium, wc_InitRng
\sa wc_RNG_GenerateByte \sa wc_RNG_GenerateByte
\sa wc_FreeRng \sa wc_FreeRng
@ -139,19 +139,19 @@ WOLFSSL_API int wc_RNG_GenerateBlock(WC_RNG*, byte*, word32 sz);
/*! /*!
\ingroup Random \ingroup Random
\brief Calls wc_RNG_GenerateBlock to copy a byte of pseudorandom \brief Calls wc_RNG_GenerateBlock to copy a byte of pseudorandom
data to b. Will reseed rng if needed. data to b. Will reseed rng if needed.
\return 0 on success \return 0 on success
\return BAD_FUNC_ARG an input is null or sz exceeds MAX_REQUEST_LEN \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 DRBG_CONT_FIPS_E Hash_gen returned DRBG_CONT_FAILURE
\return RNG_FAILURE_E Default error. rng’s status originally not \return RNG_FAILURE_E Default error. rng’s status originally not
ok, or set to DRBG_FAILED ok, or set to DRBG_FAILED
\param rng: random number generator initialized with wc_InitRng \param rng: random number generator initialized with wc_InitRng
\param b one byte buffer to which the block is copied \param b one byte buffer to which the block is copied
_Example_ _Example_
\code \code
RNG rng; RNG rng;
@ -168,7 +168,7 @@ WOLFSSL_API int wc_RNG_GenerateBlock(WC_RNG*, byte*, word32 sz);
return -1; //generating block failed! return -1; //generating block failed!
} }
\endcode \endcode
\sa wc_InitRngCavium \sa wc_InitRngCavium
\sa wc_InitRng \sa wc_InitRng
\sa wc_RNG_GenerateBlock \sa wc_RNG_GenerateBlock
@ -179,16 +179,16 @@ WOLFSSL_API int wc_RNG_GenerateByte(WC_RNG*, byte*);
/*! /*!
\ingroup Random \ingroup Random
\brief Should be called when RNG no longer needed in order to securely \brief Should be called when RNG no longer needed in order to securely
free drgb. Zeros and XFREEs rng-drbg. free drgb. Zeros and XFREEs rng-drbg.
\return 0 on success \return 0 on success
\return BAD_FUNC_ARG rng or rng->drgb null \return BAD_FUNC_ARG rng or rng->drgb null
\return RNG_FAILURE_E Failed to deallocated drbg \return RNG_FAILURE_E Failed to deallocated drbg
\param rng random number generator initialized with wc_InitRng \param rng random number generator initialized with wc_InitRng
_Example_ _Example_
\code \code
RNG rng; RNG rng;
@ -198,38 +198,38 @@ WOLFSSL_API int wc_RNG_GenerateByte(WC_RNG*, byte*);
} }
int ret = wc_FreeRng(&rng); int ret = wc_FreeRng(&rng);
if (ret != 0) { if (ret != 0) {
return -1; //free of rng failed! return -1; //free of rng failed!
} }
\endcode \endcode
\sa wc_InitRngCavium \sa wc_InitRngCavium
\sa wc_InitRng \sa wc_InitRng
\sa wc_RNG_GenerateBlock \sa wc_RNG_GenerateBlock
\sa wc_RNG_GenerateByte, \sa wc_RNG_GenerateByte,
\sa wc_RNG_HealthTest \sa wc_RNG_HealthTest
*/ */
WOLFSSL_API int wc_FreeRng(WC_RNG*); WOLFSSL_API int wc_FreeRng(WC_RNG*);
/*! /*!
\ingroup Random \ingroup Random
\brief Creates and tests functionality of drbg. \brief Creates and tests functionality of drbg.
\return 0 on success \return 0 on success
\return BAD_FUNC_ARG entropyA and output must not be null. If reseed \return BAD_FUNC_ARG entropyA and output must not be null. If reseed
set entropyB must not be null set entropyB must not be null
\return -1 test failed \return -1 test failed
\param int reseed: if set, will test reseed functionality \param int reseed: if set, will test reseed functionality
\param entropyA: entropy to instantiate drgb with \param entropyA: entropy to instantiate drgb with
\param entropyASz: size of entropyA in bytes \param entropyASz: size of entropyA in bytes
\param entropyB: If reseed set, drbg will be reseeded with entropyB \param entropyB: If reseed set, drbg will be reseeded with entropyB
\param entropyBSz: size of entropyB in bytes \param entropyBSz: size of entropyB in bytes
\param output: initialized to random data seeded with entropyB if \param output: initialized to random data seeded with entropyB if
seedrandom is set, and entropyA otherwise seedrandom is set, and entropyA otherwise
\param outputSz: length of output in bytes \param outputSz: length of output in bytes
_Example_ _Example_
\code \code
byte output[SHA256_DIGEST_SIZE * 4]; byte output[SHA256_DIGEST_SIZE * 4];
@ -249,11 +249,11 @@ WOLFSSL_API int wc_FreeRng(WC_RNG*);
ret = wc_RNG_HealthTest(1, test2EntropyA, sizeof(test2EntropyA), ret = wc_RNG_HealthTest(1, test2EntropyA, sizeof(test2EntropyA),
test2EntropyB, sizeof(test2EntropyB), test2EntropyB, sizeof(test2EntropyB),
output, sizeof(output)); output, sizeof(output));
if (XMEMCMP(test2Output, output, sizeof(output)) != 0) if (XMEMCMP(test2Output, output, sizeof(output)) != 0)
return -1; //compare to testvector failed return -1; //compare to testvector failed
\endcode \endcode
\sa wc_InitRngCavium \sa wc_InitRngCavium
\sa wc_InitRng \sa wc_InitRng
\sa wc_RNG_GenerateBlock \sa wc_RNG_GenerateBlock

62
doc/dox_comments/header_files/ripemd.h
View File

@ -1,15 +1,15 @@
/*! /*!
\ingroup RIPEMD \ingroup RIPEMD
\brief This function initializes a ripemd structure by initializing \brief This function initializes a ripemd structure by initializing
ripemd’s digest, buffer, loLen and hiLen. ripemd’s digest, buffer, loLen and hiLen.
\return 0 returned on successful execution of the function. The RipeMd \return 0 returned on successful execution of the function. The RipeMd
structure is initialized. structure is initialized.
\return BAD_FUNC_ARG returned if the RipeMd structure is NULL. \return BAD_FUNC_ARG returned if the RipeMd structure is NULL.
\param ripemd pointer to the ripemd structure to initialize \param ripemd pointer to the ripemd structure to initialize
_Example_ _Example_
\code \code
RipeMd md; RipeMd md;
@ -19,7 +19,7 @@
// Failure case. // Failure case.
} }
\endcode \endcode
\sa wc_RipeMdUpdate \sa wc_RipeMdUpdate
\sa wc_RipeMdFinal \sa wc_RipeMdFinal
*/ */
@ -27,18 +27,18 @@ WOLFSSL_API int wc_InitRipeMd(RipeMd*);
/*! /*!
\ingroup RIPEMD \ingroup RIPEMD
\brief This function generates the RipeMd digest of the data input and \brief This function generates the RipeMd digest of the data input and
stores the result in the ripemd->digest buffer. After running stores the result in the ripemd->digest buffer. After running
wc_RipeMdUpdate, one should compare the generated ripemd->digest to a wc_RipeMdUpdate, one should compare the generated ripemd->digest to a
known authentication tag to verify the authenticity of a message. known authentication tag to verify the authenticity of a message.
\return 0 Returned on successful execution of the function. \return 0 Returned on successful execution of the function.
\return BAD_FUNC_ARG Returned if the RipeMd structure is NULL or if data \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 is NULL and len is not zero. This function should execute if data is NULL
and len is 0. and len is 0.
\param ripemd: pointer to the ripemd structure to be initialized with \param ripemd: pointer to the ripemd structure to be initialized with
wc_InitRipeMd wc_InitRipeMd
\param data data to be hashed \param data data to be hashed
\param len sizeof data in bytes \param len sizeof data in bytes
@ -55,37 +55,37 @@ WOLFSSL_API int wc_InitRipeMd(RipeMd*);
if (ret != 0) { if (ret != 0) {
// Failure case … // Failure case …
\endcode \endcode
\sa wc_InitRipeMd \sa wc_InitRipeMd
\sa wc_RipeMdFinal \sa wc_RipeMdFinal
*/ */
WOLFSSL_API int wc_RipeMdUpdate(RipeMd*, const byte*, word32); WOLFSSL_API int wc_RipeMdUpdate(RipeMd*, const byte*, word32);
/*! /*!
\ingroup RIPEMD \ingroup RIPEMD
\brief This function copies the computed digest into hash. If there is a \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 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 include that block’s round in the digest before copying to hash. State
of ripemd is reset. of ripemd is reset.
\return 0 Returned on successful execution of the function. The state of \return 0 Returned on successful execution of the function. The state of
the RipeMd structure has been reset. the RipeMd structure has been reset.
\return BAD_FUNC_ARG Returned if the RipeMd structure or hash parameters \return BAD_FUNC_ARG Returned if the RipeMd structure or hash parameters
are NULL. are NULL.
\param ripemd pointer to the ripemd structure to be initialized with \param ripemd pointer to the ripemd structure to be initialized with
wc_InitRipeMd, and containing hashes from wc_RipeMdUpdate. State will wc_InitRipeMd, and containing hashes from wc_RipeMdUpdate. State will
be reset be reset
\param hash buffer to copy digest to. Should be RIPEMD_DIGEST_SIZE bytes \param hash buffer to copy digest to. Should be RIPEMD_DIGEST_SIZE bytes
_Example_ _Example_
\code \code
RipeMd md; RipeMd md;
int ret; int ret;
byte digest[RIPEMD_DIGEST_SIZE]; byte digest[RIPEMD_DIGEST_SIZE];
const byte* data; // The data to be hashed const byte* data; // The data to be hashed
... ...
ret = wc_InitRipeMd(&md); ret = wc_InitRipeMd(&md);
if (ret == 0) { if (ret == 0) {
ret = wc_RipeMdUpdate(&md, plain, sizeof(plain)); ret = wc_RipeMdUpdate(&md, plain, sizeof(plain));
@ -97,7 +97,7 @@ WOLFSSL_API int wc_RipeMdUpdate(RipeMd*, const byte*, word32);
// RipeMd Final Failure Case. // RipeMd Final Failure Case.
}... }...
\endcode \endcode
\sa none \sa none
*/ */
WOLFSSL_API int wc_RipeMdFinal(RipeMd*, byte*); WOLFSSL_API int wc_RipeMdFinal(RipeMd*, byte*);

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

@ -1,19 +1,19 @@
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function initializes a provided RsaKey struct. It also takes \brief This function initializes a provided RsaKey struct. It also takes
in a heap identifier, for use with user defined memory overrides in a heap identifier, for use with user defined memory overrides
(see XMALLOC, XFREE, XREALLOC). (see XMALLOC, XFREE, XREALLOC).
\return 0 Returned upon successfully initializing the RSA structure for \return 0 Returned upon successfully initializing the RSA structure for
use with encryption and decryption use with encryption and decryption
\return BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL \return BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL
\param key pointer to the RsaKey structure to initialize \param key pointer to the RsaKey structure to initialize
\param heap pointer to a heap identifier, for use with memory overrides, \param heap pointer to a heap identifier, for use with memory overrides,
allowing custom handling of memory allocation. This heap will be the allowing custom handling of memory allocation. This heap will be the
default used when allocating memory for use with this RSA object default used when allocating memory for use with this RSA object
_Example_ _Example_
\code \code
RsaKey enc; RsaKey enc;
@ -23,7 +23,7 @@
// error initializing RSA key // error initializing RSA key
} }
\endcode \endcode
\sa wc_RsaInitCavium \sa wc_RsaInitCavium
\sa wc_FreeRsaKey \sa wc_FreeRsaKey
*/ */
@ -31,13 +31,13 @@ WOLFSSL_API int wc_InitRsaKey(RsaKey* key, void* heap);
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function frees a provided RsaKey struct using mp_clear. \brief This function frees a provided RsaKey struct using mp_clear.
\return 0 Returned upon successfully freeing the key \return 0 Returned upon successfully freeing the key
\param key pointer to the RsaKey structure to free \param key pointer to the RsaKey structure to free
_Example_ _Example_
\code \code
RsaKey enc; RsaKey enc;
@ -46,61 +46,61 @@ WOLFSSL_API int wc_InitRsaKey(RsaKey* key, void* heap);
wc_FreeRsaKey(&enc); wc_FreeRsaKey(&enc);
\endcode \endcode
\sa wc_InitRsaKey \sa wc_InitRsaKey
*/ */
WOLFSSL_API int wc_FreeRsaKey(RsaKey* key); WOLFSSL_API int wc_FreeRsaKey(RsaKey* key);
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function encrypts a message from in and stores the result \brief This function encrypts a message from in and stores the result
in out. It requires an initialized public key and a random number in out. It requires an initialized public key and a random number
generator. As a side effect, this function will return the bytes written generator. As a side effect, this function will return the bytes written
to out in outLen. to out in outLen.
\return Success Upon successfully encrypting the input message, returns \return Success Upon successfully encrypting the input message, returns
the number bytes written to out the number bytes written to out
\return -1 Returned if there is an error during RSA encryption and \return -1 Returned if there is an error during RSA encryption and
hardware acceleration via Cavium is enabled hardware acceleration via Cavium is enabled
\return BAD_FUNC_ARG Returned if any of the input parameters are invalid \return BAD_FUNC_ARG Returned if any of the input parameters are invalid
\return RSA_BUFFER_E Returned if the output buffer is too small to store \return RSA_BUFFER_E Returned if the output buffer is too small to store
the ciphertext the ciphertext
\return RNG_FAILURE_E Returned if there is an error generating a random \return RNG_FAILURE_E Returned if there is an error generating a random
block using the provided RNG structure block using the provided RNG structure
\return MP_INIT_E May be returned if there is an error in the math \return MP_INIT_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_READ_E May be returned if there is an error in the math \return MP_READ_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_CMP_E May be returned if there is an error in the math \return MP_CMP_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_INVMOD_E May be returned if there is an error in the math \return MP_INVMOD_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_EXPTMOD_E May be returned if there is an error in the math \return MP_EXPTMOD_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_MOD_E May be returned if there is an error in the math \return MP_MOD_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_MUL_E May be returned if there is an error in the math \return MP_MUL_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_ADD_E May be returned if there is an error in the math \return MP_ADD_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_MULMOD_E May be returned if there is an error in the math \return MP_MULMOD_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_TO_E May be returned if there is an error in the math \return MP_TO_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_MEM May be returned if there is an error in the math \return MP_MEM May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\return MP_ZERO_E May be returned if there is an error in the math \return MP_ZERO_E May be returned if there is an error in the math
library used while encrypting the message library used while encrypting the message
\param in pointer to a buffer containing the input message to encrypt \param in pointer to a buffer containing the input message to encrypt
\param inLen the length of the 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 out pointer to the buffer in which to store the output ciphertext
\param outLen the length of the output buffer \param outLen the length of the output buffer
\param key pointer to the RsaKey structure containing the public \param key pointer to the RsaKey structure containing the public
key to use for encryption key to use for encryption
\param rng The RNG structure with which to generate random block padding \param rng The RNG structure with which to generate random block padding
_Example_ _Example_
\code \code
RsaKey pub; RsaKey pub;
@ -108,9 +108,9 @@ WOLFSSL_API int wc_FreeRsaKey(RsaKey* key);
byte n[] = { // initialize with received n component of public key }; byte n[] = { // initialize with received n component of public key };
byte e[] = { // initialize with received e component of public key }; byte e[] = { // initialize with received e component of public key };
byte msg[] = { // initialize with plaintext of message to encrypt }; byte msg[] = { // initialize with plaintext of message to encrypt };
byte cipher[256]; // 256 bytes is large enough to store 2048 bit RSA byte cipher[256]; // 256 bytes is large enough to store 2048 bit RSA
ciphertext ciphertext
wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub); wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
// initialize with received public key parameters // initialize with received public key parameters
@ -119,7 +119,7 @@ WOLFSSL_API int wc_FreeRsaKey(RsaKey* key);
// error encrypting message // error encrypting message
} }
\endcode \endcode
\sa wc_RsaPrivateDecrypt \sa wc_RsaPrivateDecrypt
*/ */
WOLFSSL_API int wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out, WOLFSSL_API int wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out,
@ -127,23 +127,23 @@ WOLFSSL_API int wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out,
/*! /*!
\ingroup RSA \ingroup RSA
\brief This functions is utilized by the wc_RsaPrivateDecrypt function \brief This functions is utilized by the wc_RsaPrivateDecrypt function
for decrypting. for decrypting.
\return Success Length of decrypted data. \return Success Length of decrypted data.
\return RSA_PAD_E RsaUnPad error, bad formatting \return RSA_PAD_E RsaUnPad error, bad formatting
\param in The byte array to be decrypted. \param in The byte array to be decrypted.
\param inLen The length of in. \param inLen The length of in.
\param out The byte array for the decrypted data to be stored. \param out The byte array for the decrypted data to be stored.
\param key The key to use for decryption. \param key The key to use for decryption.
_Example_ _Example_
\code \code
none none
\endcode \endcode
\sa wc_RsaPrivateDecrypt \sa wc_RsaPrivateDecrypt
*/ */
WOLFSSL_API int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out, WOLFSSL_API int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out,
@ -151,9 +151,9 @@ WOLFSSL_API int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out,
/*! /*!
\ingroup RSA \ingroup RSA
\brief This functions provides private RSA decryption. \brief This functions provides private RSA decryption.
\return Success length of decrypted data. \return Success length of decrypted data.
\return MEMORY_E -125, out of memory error \return MEMORY_E -125, out of memory error
\return BAD_FUNC_ARG -173, Bad function argument provided \return BAD_FUNC_ARG -173, Bad function argument provided
@ -163,7 +163,7 @@ WOLFSSL_API int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out,
\param out The byte array for the decrypted data to be stored. \param out The byte array for the decrypted data to be stored.
\param outLen The length of out. \param outLen The length of out.
\param key The key to use for decryption. \param key The key to use for decryption.
_Example_ _Example_
\code \code
ret = wc_RsaPublicEncrypt(in, inLen, out, sizeof(out), &key, &rng); ret = wc_RsaPublicEncrypt(in, inLen, out, sizeof(out), &key, &rng);
@ -185,19 +185,19 @@ WOLFSSL_API int wc_RsaPrivateDecrypt(const byte* in, word32 inLen, byte* out,
/*! /*!
\ingroup RSA \ingroup RSA
\brief Signs the provided array with the private key. \brief Signs the provided array with the private key.
\return RSA_BUFFER_E: -131, RSA buffer error, output too small or \return RSA_BUFFER_E: -131, RSA buffer error, output too small or
input too large input too large
\param in The byte array to be encrypted. \param in The byte array to be encrypted.
\param inLen The length of in. \param inLen The length of in.
\param out The byte array for the encrypted data to be stored. \param out The byte array for the encrypted data to be stored.
\param outLen The length of out. \param outLen The length of out.
\param key The key to use for encryption. \param key The key to use for encryption.
\param RNG The RNG struct to use for random number purposes. \param RNG The RNG struct to use for random number purposes.
_Example_ _Example_
\code \code
ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng); ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
@ -210,7 +210,7 @@ WOLFSSL_API int wc_RsaPrivateDecrypt(const byte* in, word32 inLen, byte* out,
return -1; return -1;
} }
\endcode \endcode
\sa wc_RsaPad \sa wc_RsaPad
*/ */
WOLFSSL_API int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out, WOLFSSL_API int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out,
@ -218,18 +218,18 @@ WOLFSSL_API int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out,
/*! /*!
\ingroup RSA \ingroup RSA
\brief Used to verify that the message was signed by RSA key. The output \brief Used to verify that the message was signed by RSA key. The output
uses the same byte array as the input. uses the same byte array as the input.
\return >0 Length of text. \return >0 Length of text.
\return <0 An error occurred. \return <0 An error occurred.
\param in Byte array to be decrypted. \param in Byte array to be decrypted.
\param inLen Length of the buffer input. \param inLen Length of the buffer input.
\param out Pointer to a pointer for decrypted information. \param out Pointer to a pointer for decrypted information.
\param key RsaKey to use. \param key RsaKey to use.
_Example_ _Example_
\code \code
RsaKey key; RsaKey key;
@ -247,7 +247,7 @@ WOLFSSL_API int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out,
// handle error // handle error
} }
\endcode \endcode
\sa wc_RsaSSL_Verify \sa wc_RsaSSL_Verify
\sa wc_RsaSSL_Sign \sa wc_RsaSSL_Sign
*/ */
@ -256,9 +256,9 @@ WOLFSSL_API int wc_RsaSSL_VerifyInline(byte* in, word32 inLen, byte** out,
/*! /*!
\ingroup RSA \ingroup RSA
\brief Used to verify that the message was signed by key. \brief Used to verify that the message was signed by key.
\return Success Length of text on no error. \return Success Length of text on no error.
\return MEMORY_E memory exception. \return MEMORY_E memory exception.
@ -280,7 +280,7 @@ WOLFSSL_API int wc_RsaSSL_VerifyInline(byte* in, word32 inLen, byte** out,
return -1; return -1;
} }
\endcode \endcode
\sa wc_RsaSSL_Sign \sa wc_RsaSSL_Sign
*/ */
WOLFSSL_API int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out, WOLFSSL_API int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out,
@ -288,18 +288,18 @@ WOLFSSL_API int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out,
/*! /*!
\ingroup RSA \ingroup RSA
\brief Returns the encryption size for the provided key structure. \brief Returns the encryption size for the provided key structure.
\return Success Encryption size for the provided key structure. \return Success Encryption size for the provided key structure.
\param key The key to use for verification. \param key The key to use for verification.
_Example_ _Example_
\code \code
int sz = wc_RsaEncryptSize(&key); int sz = wc_RsaEncryptSize(&key);
\endcode \endcode
\sa wc_InitRsaKey \sa wc_InitRsaKey
\sa wc_InitRsaKey_ex \sa wc_InitRsaKey_ex
\sa wc_MakeRsaKey \sa wc_MakeRsaKey
@ -309,28 +309,28 @@ WOLFSSL_API int wc_RsaEncryptSize(RsaKey* key);
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function parses a DER-formatted RSA private key, extracts the \brief This function parses a DER-formatted RSA private key, extracts the
private key and stores it in the given RsaKey structure. It also sets the private key and stores it in the given RsaKey structure. It also sets the
distance parsed in idx. distance parsed in idx.
\return 0 Returned upon successfully parsing the private key from the DER \return 0 Returned upon successfully parsing the private key from the DER
encoded input encoded input
\return ASN_PARSE_E Returned if there is an error parsing the private key \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 from the input buffer. This may happen if the input private key is not
properly formatted according to ASN.1 standards properly formatted according to ASN.1 standards
\return ASN_RSA_KEY_E Returned if there is an error reading the private \return ASN_RSA_KEY_E Returned if there is an error reading the private
key elements of the RSA key input key elements of the RSA key input
\param input pointer to the buffer containing the DER formatted private \param input pointer to the buffer containing the DER formatted private
key to decode key to decode
\param inOutIdx pointer to the index in the buffer at which the key begins \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 (usually 0). As a side effect of this function, inOutIdx will store the
distance parsed through the input buffer distance parsed through the input buffer
\param key pointer to the RsaKey structure in which to store the decoded \param key pointer to the RsaKey structure in which to store the decoded
private key private key
\param inSz size of the input buffer \param inSz size of the input buffer
_Example_ _Example_
\code \code
RsaKey enc; RsaKey enc;
@ -341,10 +341,10 @@ WOLFSSL_API int wc_RsaEncryptSize(RsaKey* key);
wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
ret = wc_RsaPrivateKeyDecode(der, &idx, &enc, sizeof(der)); ret = wc_RsaPrivateKeyDecode(der, &idx, &enc, sizeof(der));
if( ret != 0 ) { if( ret != 0 ) {
// error parsing private key // error parsing private key
} }
\endcode \endcode
\sa wc_RsaPublicKeyDecode \sa wc_RsaPublicKeyDecode
\sa wc_MakeRsaKey \sa wc_MakeRsaKey
*/ */
@ -353,31 +353,31 @@ WOLFSSL_API int wc_RsaPrivateKeyDecode(const byte* input, word32* inOutIdx,
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function parses a DER-formatted RSA public key, extracts the \brief This function parses a DER-formatted RSA public key, extracts the
public key and stores it in the given RsaKey structure. It also sets the public key and stores it in the given RsaKey structure. It also sets the
distance parsed in idx. distance parsed in idx.
\return 0 Returned upon successfully parsing the public key from the DER \return 0 Returned upon successfully parsing the public key from the DER
encoded input encoded input
\return ASN_PARSE_E Returned if there is an error parsing the public key \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 from the input buffer. This may happen if the input public key is not
properly formatted according to ASN.1 standards properly formatted according to ASN.1 standards
\return ASN_OBJECT_ID_E Returned if the ASN.1 Object ID does not match \return ASN_OBJECT_ID_E Returned if the ASN.1 Object ID does not match
that of a RSA public key that of a RSA public key
\return ASN_EXPECT_0_E Returned if the input key is not correctly \return ASN_EXPECT_0_E Returned if the input key is not correctly
formatted according to ASN.1 standards formatted according to ASN.1 standards
\return ASN_BITSTR_E Returned if the input key is not correctly formatted \return ASN_BITSTR_E Returned if the input key is not correctly formatted
according to ASN.1 standards according to ASN.1 standards
\return ASN_RSA_KEY_E Returned if there is an error reading the public key \return ASN_RSA_KEY_E Returned if there is an error reading the public key
elements of the RSA key input elements of the RSA key input
\param input pointer to the buffer containing the input DER-encoded RSA \param input pointer to the buffer containing the input DER-encoded RSA
public key to decode public key to decode
\param inOutIdx pointer to the index in the buffer at which the key \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 begins (usually 0). As a side effect of this function, inOutIdx will
store the distance parsed through the input buffer store the distance parsed through the input buffer
\param key pointer to the RsaKey structure in which to store the decoded \param key pointer to the RsaKey structure in which to store the decoded
public key public key
\param inSz size of the input buffer \param inSz size of the input buffer
@ -391,10 +391,10 @@ WOLFSSL_API int wc_RsaPrivateKeyDecode(const byte* input, word32* inOutIdx,
wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
ret = wc_RsaPublicKeyDecode(der, &idx, &pub, sizeof(der)); ret = wc_RsaPublicKeyDecode(der, &idx, &pub, sizeof(der));
if( ret != 0 ) { if( ret != 0 ) {
// error parsing public key // error parsing public key
} }
\endcode \endcode
\sa wc_RsaPublicKeyDecodeRaw \sa wc_RsaPublicKeyDecodeRaw
*/ */
WOLFSSL_API int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx, WOLFSSL_API int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx,
@ -402,28 +402,28 @@ WOLFSSL_API int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx,
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function decodes the raw elements of an RSA public key, taking \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 public modulus (n) and exponent (e). It stores these raw elements
in the provided RsaKey structure, allowing one to use them in the in the provided RsaKey structure, allowing one to use them in the
encryption/decryption process. encryption/decryption process.
\return 0 Returned upon successfully decoding the raw elements of the \return 0 Returned upon successfully decoding the raw elements of the
public key into the RsaKey structure public key into the RsaKey structure
\return BAD_FUNC_ARG Returned if any of the input arguments evaluates to \return BAD_FUNC_ARG Returned if any of the input arguments evaluates to
NULL NULL
\return MP_INIT_E Returned if there is an error initializing an integer \return MP_INIT_E Returned if there is an error initializing an integer
for use with the multiple precision integer (mp_int) library for use with the multiple precision integer (mp_int) library
\return ASN_GETINT_E Returned if there is an error reading one of the \return ASN_GETINT_E Returned if there is an error reading one of the
provided RSA key elements, n or e provided RSA key elements, n or e
\param n pointer to a buffer containing the raw modulus parameter of the \param n pointer to a buffer containing the raw modulus parameter of the
public RSA key public RSA key
\param nSz size of the buffer containing n \param nSz size of the buffer containing n
\param e pointer to a buffer containing the raw exponent parameter of \param e pointer to a buffer containing the raw exponent parameter of
the public RSA key the public RSA key
\param eSz size of the buffer containing e \param eSz size of the buffer containing e
\param key pointer to the RsaKey struct to initialize with the provided \param key pointer to the RsaKey struct to initialize with the provided
public key elements public key elements
_Example_ _Example_
@ -439,7 +439,7 @@ WOLFSSL_API int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx,
// error parsing public key elements // error parsing public key elements
} }
\endcode \endcode
\sa wc_RsaPublicKeyDecode \sa wc_RsaPublicKeyDecode
*/ */
WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz, WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz,
@ -447,19 +447,19 @@ WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz,
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function converts an RsaKey key to DER format. The result is \brief This function converts an RsaKey key to DER format. The result is
written to output and it returns the number of bytes written. written to output and it returns the number of bytes written.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returned if key or output is null, or if key->type \return BAD_FUNC_ARG Returned if key or output is null, or if key->type
is not RSA_PRIVATE, or if inLen isn't large enough for output buffer. 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. \return MEMORY_E Returned if there is an error allocating memory.
\param key Initialized RsaKey structure. \param key Initialized RsaKey structure.
\param output Pointer to output buffer. \param output Pointer to output buffer.
\param inLen Size of output buffer. \param inLen Size of output buffer.
_Example_ _Example_
\code \code
byte* der; byte* der;
@ -468,7 +468,7 @@ WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz,
RsaKey key; RsaKey key;
WC_WC_RNG rng; WC_WC_RNG rng;
long e = 65537; // standard value to use for exponent long e = 65537; // standard value to use for exponent
ret = wc_MakeRsaKey(&key, 2048, e, &rng); // generate 2048 bit long ret = wc_MakeRsaKey(&key, 2048, e, &rng); // generate 2048 bit long
private key private key
wc_InitRsaKey(&key, NULL); wc_InitRsaKey(&key, NULL);
wc_InitRng(&rng); wc_InitRng(&rng);
@ -477,7 +477,7 @@ WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz,
// Handle the error thrown // Handle the error thrown
} }
\endcode \endcode
\sa wc_RsaKeyToPublicDer \sa wc_RsaKeyToPublicDer
\sa wc_InitRsaKey \sa wc_InitRsaKey
\sa wc_MakeRsaKey \sa wc_MakeRsaKey
@ -487,14 +487,14 @@ WOLFSSL_API int wc_RsaKeyToDer(RsaKey*, byte* output, word32 inLen);
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function performs RSA encrypt while allowing the choice of \brief This function performs RSA encrypt while allowing the choice of
which padding to use. which padding to use.
\return size On successfully encryption the size of the encrypted buffer \return size On successfully encryption the size of the encrypted buffer
is returned is returned
\return RSA_BUFFER_E RSA buffer error, output too small or input too large \return RSA_BUFFER_E RSA buffer error, output too small or input too large
\param in pointer to the buffer for encryption \param in pointer to the buffer for encryption
\param inLen length of the buffer to encrypt \param inLen length of the buffer to encrypt
\param out encrypted msg created \param out encrypted msg created
@ -516,13 +516,13 @@ WOLFSSL_API int wc_RsaKeyToDer(RsaKey*, byte* output, word32 inLen);
int ret; int ret;
… …
ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng, ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng,
WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0); WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
if (ret < 0) { if (ret < 0) {
//handle error //handle error
} }
\endcode \endcode
\sa wc_RsaPublicEncrypt \sa wc_RsaPublicEncrypt
\sa wc_RsaPrivateDecrypt_ex \sa wc_RsaPrivateDecrypt_ex
*/ */
@ -532,17 +532,17 @@ WOLFSSL_API int wc_RsaPublicEncrypt_ex(const byte* in, word32 inLen, byte* out,
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function uses RSA to decrypt a message and gives the \brief This function uses RSA to decrypt a message and gives the
option of what padding type. option of what padding type.
\return size On successful decryption, the size of the decrypted message \return size On successful decryption, the size of the decrypted message
is returned. is returned.
\return MEMORY_E Returned if not enough memory on system to malloc a \return MEMORY_E Returned if not enough memory on system to malloc a
needed array. needed array.
\return BAD_FUNC_ARG Returned if a bad argument was passed into the \return BAD_FUNC_ARG Returned if a bad argument was passed into the
function. function.
\param in pointer to the buffer for decryption \param in pointer to the buffer for decryption
\param inLen length of the buffer to decrypt \param inLen length of the buffer to decrypt
\param out decrypted msg created \param out decrypted msg created
@ -563,20 +563,20 @@ WOLFSSL_API int wc_RsaPublicEncrypt_ex(const byte* in, word32 inLen, byte* out,
byte plain[256]; byte plain[256];
int ret; int ret;
… …
ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key,
&rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0); &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
if (ret < 0) { if (ret < 0) {
//handle error //handle error
} }
… …
ret = wc_RsaPrivateDecrypt_ex(out, ret, plain, sizeof(plain), &key, ret = wc_RsaPrivateDecrypt_ex(out, ret, plain, sizeof(plain), &key,
WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0); WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
if (ret < 0) { if (ret < 0) {
//handle error //handle error
} }
\endcode \endcode
\sa none \sa none
*/ */
WOLFSSL_API int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen, WOLFSSL_API int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen,
@ -585,20 +585,20 @@ WOLFSSL_API int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen,
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function uses RSA to decrypt a message inline and gives the \brief This function uses RSA to decrypt a message inline and gives the
option of what padding type. The in buffer will contain the decrypted 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 message after being called and the out byte pointer will point to the
location in the “in” buffer where the plain text is. location in the “in” buffer where the plain text is.
\return size On successful decryption, the size of the decrypted message \return size On successful decryption, the size of the decrypted message
is returned. is returned.
\return MEMORY_E: Returned if not enough memory on system to malloc a \return MEMORY_E: Returned if not enough memory on system to malloc a
needed array. needed array.
\return RSA_PAD_E: Returned if an error in the padding was encountered. \return RSA_PAD_E: Returned if an error in the padding was encountered.
\return BAD_PADDING_E: Returned if an error happened during parsing past \return BAD_PADDING_E: Returned if an error happened during parsing past
padding. padding.
\return BAD_FUNC_ARG: Returned if a bad argument was passed into the \return BAD_FUNC_ARG: Returned if a bad argument was passed into the
function. function.
\param in pointer to the buffer for decryption \param in pointer to the buffer for decryption
@ -620,21 +620,21 @@ WOLFSSL_API int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen,
byte* plain; byte* plain;
int ret; int ret;
… …
ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key,
&rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0); &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
if (ret < 0) { if (ret < 0) {
//handle error //handle error
} }
… …
ret = wc_RsaPrivateDecryptInline_ex(out, ret, &plain, &key, ret = wc_RsaPrivateDecryptInline_ex(out, ret, &plain, &key,
WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0); WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
if (ret < 0) { if (ret < 0) {
//handle error //handle error
} }
\endcode \endcode
\sa none \sa none
*/ */
WOLFSSL_API int wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen, WOLFSSL_API int wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen,
@ -643,23 +643,23 @@ WOLFSSL_API int wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen,
/*! /*!
\ingroup RSA \ingroup RSA
\brief Flattens the RsaKey structure into individual elements (e, n) \brief Flattens the RsaKey structure into individual elements (e, n)
used for the RSA algorithm. used for the RSA algorithm.
\return 0 Returned if the function executed normally, without error. \return 0 Returned if the function executed normally, without error.
\return BAD_FUNC_ARG: Returned if any of the parameters are passed in \return BAD_FUNC_ARG: Returned if any of the parameters are passed in
with a null value. with a null value.
\return RSA_BUFFER_E: Returned if the e or n buffers passed in are not \return RSA_BUFFER_E: Returned if the e or n buffers passed in are not
the correct size. the correct size.
\return MP_MEM: Returned if an internal function has memory errors. \return MP_MEM: Returned if an internal function has memory errors.
\return MP_VAL: Returned if an internal function argument is not valid. \return MP_VAL: Returned if an internal function argument is not valid.
\param key The key to use for verification. \param key The key to use for verification.
\param e a buffer for the value of e. e is a large positive integer in \param e a buffer for the value of e. e is a large positive integer in
the RSA modular arithmetic operation. the RSA modular arithmetic operation.
\param eSz the size of the e buffer. \param eSz the size of the e buffer.
\param n a buffer for the value of n. n is a large positive integer in \param n a buffer for the value of n. n is a large positive integer in
the RSA modular arithmetic operation. the RSA modular arithmetic operation.
\param nSz the size of the n buffer. \param nSz the size of the n buffer.
@ -677,7 +677,7 @@ WOLFSSL_API int wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen,
// Failure case. // Failure case.
} }
\endcode \endcode
\sa wc_InitRsaKey \sa wc_InitRsaKey
\sa wc_InitRsaKey_ex \sa wc_InitRsaKey_ex
\sa wc_MakeRsaKey \sa wc_MakeRsaKey
@ -688,10 +688,10 @@ WOLFSSL_API int wc_RsaFlattenPublicKey(RsaKey*, byte*, word32*, byte*,
/*! /*!
\ingroup RSA \ingroup RSA
\brief Convert Rsa Public key to DER format. Writes to output, and \brief Convert Rsa Public key to DER format. Writes to output, and
returns count of bytes written. returns count of bytes written.
\return >0 Success, number of bytes written. \return >0 Success, number of bytes written.
\return BAD_FUNC_ARG Returned if key or output is null. \return BAD_FUNC_ARG Returned if key or output is null.
\return MEMORY_E Returned when an error allocating memory occurs. \return MEMORY_E Returned when an error allocating memory occurs.
@ -700,7 +700,7 @@ WOLFSSL_API int wc_RsaFlattenPublicKey(RsaKey*, byte*, word32*, byte*,
\param key The RSA key structure to convert. \param key The RSA key structure to convert.
\param output Output buffer to hold DER. \param output Output buffer to hold DER.
\param inLen Length of buffer. \param inLen Length of buffer.
_Example_ _Example_
\code \code
RsaKey key; RsaKey key;
@ -715,7 +715,7 @@ WOLFSSL_API int wc_RsaFlattenPublicKey(RsaKey*, byte*, word32*, byte*,
// Handle Error // Handle Error
} }
\endcode \endcode
\sa wc_RsaKeyToPublicDer \sa wc_RsaKeyToPublicDer
\sa wc_RsaInitKey \sa wc_RsaInitKey
*/ */
@ -723,53 +723,53 @@ WOLFSSL_API int wc_RsaKeyToPublicDer(RsaKey*, byte* output, word32 inLen);
/*! /*!
\ingroup RSA \ingroup RSA
\brief This function generates a RSA private key of length size (in bits) \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 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 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 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 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. available, the option WOLFSSL_KEY_GEN must be enabled at compile time.
This can be accomplished with --enable-keygen if using ./configure. This can be accomplished with --enable-keygen if using ./configure.
\return 0 Returned upon successfully generating a RSA private key \return 0 Returned upon successfully generating a RSA private key
\return BAD_FUNC_ARG Returned if any of the input arguments are NULL, \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 the size parameter falls outside of the necessary bounds, or e is
incorrectly chosen incorrectly chosen
\return RNG_FAILURE_E Returned if there is an error generating a random \return RNG_FAILURE_E Returned if there is an error generating a random
block using the provided RNG structure block using the provided RNG structure
\return MP_INIT_E \return MP_INIT_E
\return MP_READ_E May be May be returned if there is an error in the math \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 library used while generating the RSA key returned if there is an error
in the math library used while generating the RSA key in the math library used while generating the RSA key
\return MP_CMP_E May be returned if there is an error in the math library \return MP_CMP_E May be returned if there is an error in the math library
used while generating the RSA key used while generating the RSA key
\return MP_INVMOD_E May be returned if there is an error in the math \return MP_INVMOD_E May be returned if there is an error in the math
library used while generating the RSA key library used while generating the RSA key
\return MP_EXPTMOD_E May be returned if there is an error in the math \return MP_EXPTMOD_E May be returned if there is an error in the math
library used while generating the RSA key library used while generating the RSA key
\return MP_MOD_E May be returned if there is an error in the math \return MP_MOD_E May be returned if there is an error in the math
library used while generating the RSA key library used while generating the RSA key
\return MP_MUL_E May be returned if there is an error in the math \return MP_MUL_E May be returned if there is an error in the math
library used while generating the RSA key library used while generating the RSA key
\return MP_ADD_E May be returned if there is an error in the math \return MP_ADD_E May be returned if there is an error in the math
library used while generating the RSA key library used while generating the RSA key
\return MP_MULMOD_E May be returned if there is an error in the math \return MP_MULMOD_E May be returned if there is an error in the math
library used while generating the RSA key library used while generating the RSA key
\return MP_TO_E May be returned if there is an error in the math \return MP_TO_E May be returned if there is an error in the math
library used while generating the RSA key library used while generating the RSA key
\return MP_MEM May be returned if there is an error in the math \return MP_MEM May be returned if there is an error in the math
library used while generating the RSA key library used while generating the RSA key
\return MP_ZERO_E May be returned if there is an error in the math \return MP_ZERO_E May be returned if there is an error in the math
library used while generating the RSA key library used while generating the RSA key
\param key pointer to the RsaKey structure in which to store the \param key pointer to the RsaKey structure in which to store the
generated private key generated private key
\param size desired keylenth, in bits. Required to be greater than \param size desired keylenth, in bits. Required to be greater than
RSA_MIN_SIZE and less than RSA_MAX_SIZE RSA_MIN_SIZE and less than RSA_MAX_SIZE
\param e exponent parameter to use for generating the key. A secure \param e exponent parameter to use for generating the key. A secure
choice is 65537 choice is 65537
\param rng pointer to an RNG structure to use for random number generation \param rng pointer to an RNG structure to use for random number generation
while making the ke while making the ke
_Example_ _Example_
@ -782,12 +782,12 @@ WOLFSSL_API int wc_RsaKeyToPublicDer(RsaKey*, byte* output, word32 inLen);
wc_InitRsaKey(&priv, NULL); // not using heap hint. No custom memory wc_InitRsaKey(&priv, NULL); // not using heap hint. No custom memory
wc_InitRng(&rng); wc_InitRng(&rng);
// generate 2048 bit long private key // generate 2048 bit long private key
ret = wc_MakeRsaKey(&priv, 2048, e, &rng); ret = wc_MakeRsaKey(&priv, 2048, e, &rng);
if( ret != 0 ) { if( ret != 0 ) {
// error generating private key // error generating private key
} }
\endcode \endcode
\sa none \sa none
*/ */
WOLFSSL_API int wc_MakeRsaKey(RsaKey* key, int size, long e, WC_RNG* rng); WOLFSSL_API int wc_MakeRsaKey(RsaKey* key, int size, long e, WC_RNG* rng);

58
doc/dox_comments/header_files/sha.h
View File

@ -1,13 +1,13 @@
/*! /*!
\ingroup SHA \ingroup SHA
\brief This function initializes SHA. This is automatically called \brief This function initializes SHA. This is automatically called
by wc_ShaHash. by wc_ShaHash.
\return 0 Returned upon successfully initializing \return 0 Returned upon successfully initializing
\param sha pointer to the sha structure to use for encryption \param sha pointer to the sha structure to use for encryption
_Example_ _Example_
\code \code
Sha sha[1]; Sha sha[1];
@ -19,7 +19,7 @@
wc_ShaFinal(sha, hash); wc_ShaFinal(sha, hash);
} }
\endcode \endcode
\sa wc_ShaHash \sa wc_ShaHash
\sa wc_ShaUpdate \sa wc_ShaUpdate
\sa wc_ShaFinal \sa wc_ShaFinal
@ -28,16 +28,16 @@ WOLFSSL_API int wc_InitSha(wc_Sha*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Can be called to continually hash the provided byte array of \brief Can be called to continually hash the provided byte array of
length len. length len.
\return 0 Returned upon successfully adding the data to the digest. \return 0 Returned upon successfully adding the data to the digest.
\param sha pointer to the sha structure to use for encryption \param sha pointer to the sha structure to use for encryption
\param data the data to be hashed \param data the data to be hashed
\param len length of data to be hashed \param len length of data to be hashed
_Example_ _Example_
\code \code
Sha sha[1]; Sha sha[1];
@ -52,7 +52,7 @@ WOLFSSL_API int wc_InitSha(wc_Sha*);
wc_ShaFinal(sha, hash); wc_ShaFinal(sha, hash);
} }
\endcode \endcode
\sa wc_ShaHash \sa wc_ShaHash
\sa wc_ShaFinal \sa wc_ShaFinal
\sa wc_InitSha \sa wc_InitSha
@ -61,15 +61,15 @@ WOLFSSL_API int wc_ShaUpdate(wc_Sha*, const byte*, word32);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Finalizes hashing of data. Result is placed into hash. \brief Finalizes hashing of data. Result is placed into hash.
Resets state of sha struct. Resets state of sha struct.
\return 0 Returned upon successfully finalizing. \return 0 Returned upon successfully finalizing.
\param sha pointer to the sha structure to use for encryption \param sha pointer to the sha structure to use for encryption
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
Sha sha[1]; Sha sha[1];
@ -84,7 +84,7 @@ WOLFSSL_API int wc_ShaUpdate(wc_Sha*, const byte*, word32);
wc_ShaFinal(sha, hash); wc_ShaFinal(sha, hash);
} }
\endcode \endcode
\sa wc_ShaHash \sa wc_ShaHash
\sa wc_InitSha \sa wc_InitSha
\sa wc_ShaGetHash \sa wc_ShaGetHash
@ -93,14 +93,14 @@ WOLFSSL_API int wc_ShaFinal(wc_Sha*, byte*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Used to clean up memory used by an initialized Sha struct. \brief Used to clean up memory used by an initialized Sha struct.
Note: this is only supported if you have WOLFSSL_TI_HASH defined. Note: this is only supported if you have WOLFSSL_TI_HASH defined.
\return No returns. \return No returns.
\param sha Pointer to the Sha struct to free. \param sha Pointer to the Sha struct to free.
_Example_ _Example_
\code \code
Sha sha; Sha sha;
@ -108,7 +108,7 @@ WOLFSSL_API int wc_ShaFinal(wc_Sha*, byte*);
// Use sha // Use sha
wc_ShaFree(&sha); wc_ShaFree(&sha);
\endcode \endcode
\sa wc_InitSha \sa wc_InitSha
\sa wc_ShaUpdate \sa wc_ShaUpdate
\sa wc_ShaFinal \sa wc_ShaFinal
@ -117,15 +117,15 @@ WOLFSSL_API void wc_ShaFree(wc_Sha*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Gets hash data. Result is placed into hash. Does not reset state \brief Gets hash data. Result is placed into hash. Does not reset state
of sha struct. of sha struct.
\return 0 Returned upon successfully finalizing. \return 0 Returned upon successfully finalizing.
\param sha pointer to the sha structure to use for encryption \param sha pointer to the sha structure to use for encryption
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
Sha sha[1]; Sha sha[1];
@ -137,7 +137,7 @@ WOLFSSL_API void wc_ShaFree(wc_Sha*);
wc_ShaGetHash(sha, hash); wc_ShaGetHash(sha, hash);
} }
\endcode \endcode
\sa wc_ShaHash \sa wc_ShaHash
\sa wc_ShaFinal \sa wc_ShaFinal
\sa wc_InitSha \sa wc_InitSha

88
doc/dox_comments/header_files/sha256.h
View File

@ -1,13 +1,13 @@
/*! /*!
\ingroup SHA \ingroup SHA
\brief This function initializes SHA256. This is automatically \brief This function initializes SHA256. This is automatically
called by wc_Sha256Hash. called by wc_Sha256Hash.
\return 0 Returned upon successfully initializing \return 0 Returned upon successfully initializing
\param sha256 pointer to the sha256 structure to use for encryption \param sha256 pointer to the sha256 structure to use for encryption
_Example_ _Example_
\code \code
Sha256 sha256[1]; Sha256 sha256[1];
@ -19,7 +19,7 @@
wc_Sha256Final(sha256, hash); wc_Sha256Final(sha256, hash);
} }
\endcode \endcode
\sa wc_Sha256Hash \sa wc_Sha256Hash
\sa wc_Sha256Update \sa wc_Sha256Update
\sa wc_Sha256Final \sa wc_Sha256Final
@ -28,16 +28,16 @@ WOLFSSL_API int wc_InitSha256(wc_Sha256*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Can be called to continually hash the provided byte \brief Can be called to continually hash the provided byte
array of length len. array of length len.
\return 0 Returned upon successfully adding the data to the digest. \return 0 Returned upon successfully adding the data to the digest.
\param sha256 pointer to the sha256 structure to use for encryption \param sha256 pointer to the sha256 structure to use for encryption
\param data the data to be hashed \param data the data to be hashed
\param len length of data to be hashed \param len length of data to be hashed
_Example_ _Example_
\code \code
Sha256 sha256[1]; Sha256 sha256[1];
@ -52,7 +52,7 @@ WOLFSSL_API int wc_InitSha256(wc_Sha256*);
wc_Sha256Final(sha256, hash); wc_Sha256Final(sha256, hash);
} }
\endcode \endcode
\sa wc_Sha256Hash \sa wc_Sha256Hash
\sa wc_Sha256Final \sa wc_Sha256Final
\sa wc_InitSha256 \sa wc_InitSha256
@ -61,15 +61,15 @@ WOLFSSL_API int wc_Sha256Update(wc_Sha256*, const byte*, word32);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Finalizes hashing of data. Result is placed into hash. \brief Finalizes hashing of data. Result is placed into hash.
Resets state of sha256 struct. Resets state of sha256 struct.
\return 0 Returned upon successfully finalizing. \return 0 Returned upon successfully finalizing.
\param sha256 pointer to the sha256 structure to use for encryption \param sha256 pointer to the sha256 structure to use for encryption
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
Sha256 sha256[1]; Sha256 sha256[1];
@ -84,7 +84,7 @@ WOLFSSL_API int wc_Sha256Update(wc_Sha256*, const byte*, word32);
wc_Sha256Final(sha256, hash); wc_Sha256Final(sha256, hash);
} }
\endcode \endcode
\sa wc_Sha256Hash \sa wc_Sha256Hash
\sa wc_Sha256GetHash \sa wc_Sha256GetHash
\sa wc_InitSha256 \sa wc_InitSha256
@ -93,12 +93,12 @@ WOLFSSL_API int wc_Sha256Final(wc_Sha256*, byte*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Resets the Sha256 structure. Note: this is only supported \brief Resets the Sha256 structure. Note: this is only supported
if you have WOLFSSL_TI_HASH defined. if you have WOLFSSL_TI_HASH defined.
\return none No returns. \return none No returns.
\param sha256 Pointer to the sha256 structure to be freed. \param sha256 Pointer to the sha256 structure to be freed.
_Example_ _Example_
@ -116,7 +116,7 @@ WOLFSSL_API int wc_Sha256Final(wc_Sha256*, byte*);
wc_Sha256Free(&sha256); wc_Sha256Free(&sha256);
} }
\endcode \endcode
\sa wc_InitSha256 \sa wc_InitSha256
\sa wc_Sha256Update \sa wc_Sha256Update
\sa wc_Sha256Final \sa wc_Sha256Final
@ -125,15 +125,15 @@ WOLFSSL_API void wc_Sha256Free(wc_Sha256*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Gets hash data. Result is placed into hash. Does not \brief Gets hash data. Result is placed into hash. Does not
reset state of sha256 struct. reset state of sha256 struct.
\return 0 Returned upon successfully finalizing. \return 0 Returned upon successfully finalizing.
\param sha256 pointer to the sha256 structure to use for encryption \param sha256 pointer to the sha256 structure to use for encryption
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
Sha256 sha256[1]; Sha256 sha256[1];
@ -145,7 +145,7 @@ WOLFSSL_API void wc_Sha256Free(wc_Sha256*);
wc_Sha256GetHash(sha256, hash); wc_Sha256GetHash(sha256, hash);
} }
\endcode \endcode
\sa wc_Sha256Hash \sa wc_Sha256Hash
\sa wc_Sha256Final \sa wc_Sha256Final
\sa wc_InitSha256 \sa wc_InitSha256
@ -154,14 +154,14 @@ WOLFSSL_API int wc_Sha256GetHash(wc_Sha256*, byte*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Used to initialize a Sha224 struct. \brief Used to initialize a Sha224 struct.
\return 0 Success \return 0 Success
\return 1 Error returned because sha224 is null. \return 1 Error returned because sha224 is null.
\param sha224 Pointer to a Sha224 struct to initialize. \param sha224 Pointer to a Sha224 struct to initialize.
_Example_ _Example_
\code \code
Sha224 sha224; Sha224 sha224;
@ -170,7 +170,7 @@ WOLFSSL_API int wc_Sha256GetHash(wc_Sha256*, byte*);
// Handle error // Handle error
} }
\endcode \endcode
\sa wc_Sha224Hash \sa wc_Sha224Hash
\sa wc_Sha224Update \sa wc_Sha224Update
\sa wc_Sha224Final \sa wc_Sha224Final
@ -179,10 +179,10 @@ WOLFSSL_API int wc_InitSha224(wc_Sha224*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Can be called to continually hash the provided byte array \brief Can be called to continually hash the provided byte array
of length len. of length len.
\return 0 Success \return 0 Success
\return 1 Error returned if function fails. \return 1 Error returned if function fails.
\return BAD_FUNC_ARG Error returned if sha224 or data is null. \return BAD_FUNC_ARG Error returned if sha224 or data is null.
@ -205,7 +205,7 @@ WOLFSSL_API int wc_InitSha224(wc_Sha224*);
wc_Sha224Final(&sha224, hash); wc_Sha224Final(&sha224, hash);
} }
\endcode \endcode
\sa wc_InitSha224 \sa wc_InitSha224
\sa wc_Sha224Final \sa wc_Sha224Final
\sa wc_Sha224Hash \sa wc_Sha224Hash
@ -214,16 +214,16 @@ WOLFSSL_API int wc_Sha224Update(wc_Sha224*, const byte*, word32);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Finalizes hashing of data. Result is placed into hash. \brief Finalizes hashing of data. Result is placed into hash.
Resets state of sha224 struct. Resets state of sha224 struct.
\return 0 Success \return 0 Success
\return <0 Error \return <0 Error
\param sha224 pointer to the sha224 structure to use for encryption \param sha224 pointer to the sha224 structure to use for encryption
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
Sha224 sha224; Sha224 sha224;
@ -238,7 +238,7 @@ WOLFSSL_API int wc_Sha224Update(wc_Sha224*, const byte*, word32);
wc_Sha224Final(&sha224, hash); wc_Sha224Final(&sha224, hash);
} }
\endcode \endcode
\sa wc_InitSha224 \sa wc_InitSha224
\sa wc_Sha224Hash \sa wc_Sha224Hash
\sa wc_Sha224Update \sa wc_Sha224Update

68
doc/dox_comments/header_files/sha512.h
View File

@ -1,13 +1,13 @@
/*! /*!
\ingroup SHA \ingroup SHA
\brief This function initializes SHA512. This is automatically called \brief This function initializes SHA512. This is automatically called
by wc_Sha512Hash. by wc_Sha512Hash.
\return 0 Returned upon successfully initializing \return 0 Returned upon successfully initializing
\param sha512 pointer to the sha512 structure to use for encryption \param sha512 pointer to the sha512 structure to use for encryption
_Example_ _Example_
\code \code
Sha512 sha512[1]; Sha512 sha512[1];
@ -19,7 +19,7 @@
wc_Sha512Final(sha512, hash); wc_Sha512Final(sha512, hash);
} }
\endcode \endcode
\sa wc_Sha512Hash \sa wc_Sha512Hash
\sa wc_Sha512Update \sa wc_Sha512Update
\sa wc_Sha512Final \sa wc_Sha512Final
@ -28,16 +28,16 @@ WOLFSSL_API int wc_InitSha512(wc_Sha512*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Can be called to continually hash the provided byte array \brief Can be called to continually hash the provided byte array
of length len. of length len.
\return 0 Returned upon successfully adding the data to the digest. \return 0 Returned upon successfully adding the data to the digest.
\param sha512 pointer to the sha512 structure to use for encryption \param sha512 pointer to the sha512 structure to use for encryption
\param data the data to be hashed \param data the data to be hashed
\param len length of data to be hashed \param len length of data to be hashed
_Example_ _Example_
\code \code
Sha512 sha512[1]; Sha512 sha512[1];
@ -51,8 +51,8 @@ WOLFSSL_API int wc_InitSha512(wc_Sha512*);
wc_Sha512Update(sha512, data, len); wc_Sha512Update(sha512, data, len);
wc_Sha512Final(sha512, hash); wc_Sha512Final(sha512, hash);
} }
\endcode \endcode
\sa wc_Sha512Hash \sa wc_Sha512Hash
\sa wc_Sha512Final \sa wc_Sha512Final
\sa wc_InitSha512 \sa wc_InitSha512
@ -61,14 +61,14 @@ WOLFSSL_API int wc_Sha512Update(wc_Sha512*, const byte*, word32);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Finalizes hashing of data. Result is placed into hash. \brief Finalizes hashing of data. Result is placed into hash.
\return 0 Returned upon successfully finalizing the hash. \return 0 Returned upon successfully finalizing the hash.
\param sha512 pointer to the sha512 structure to use for encryption \param sha512 pointer to the sha512 structure to use for encryption
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
Sha512 sha512[1]; Sha512 sha512[1];
@ -83,7 +83,7 @@ WOLFSSL_API int wc_Sha512Update(wc_Sha512*, const byte*, word32);
wc_Sha512Final(sha512, hash); wc_Sha512Final(sha512, hash);
} }
\endcode \endcode
\sa wc_Sha512Hash \sa wc_Sha512Hash
\sa wc_Sha512Final \sa wc_Sha512Final
\sa wc_InitSha512 \sa wc_InitSha512
@ -92,14 +92,14 @@ WOLFSSL_API int wc_Sha512Final(wc_Sha512*, byte*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief This function initializes SHA384. This is automatically called \brief This function initializes SHA384. This is automatically called
by wc_Sha384Hash. by wc_Sha384Hash.
\return 0 Returned upon successfully initializing \return 0 Returned upon successfully initializing
\param sha384 pointer to the sha384 structure to use for encryption \param sha384 pointer to the sha384 structure to use for encryption
_Example_ _Example_
\code \code
Sha384 sha384[1]; Sha384 sha384[1];
@ -111,7 +111,7 @@ WOLFSSL_API int wc_Sha512Final(wc_Sha512*, byte*);
wc_Sha384Final(sha384, hash); wc_Sha384Final(sha384, hash);
} }
\endcode \endcode
\sa wc_Sha384Hash \sa wc_Sha384Hash
\sa wc_Sha384Update \sa wc_Sha384Update
\sa wc_Sha384Final \sa wc_Sha384Final
@ -120,12 +120,12 @@ WOLFSSL_API int wc_InitSha384(wc_Sha384*);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Can be called to continually hash the provided byte array \brief Can be called to continually hash the provided byte array
of length len. of length len.
\return 0 Returned upon successfully adding the data to the digest. \return 0 Returned upon successfully adding the data to the digest.
\param sha384 pointer to the sha384 structure to use for encryption \param sha384 pointer to the sha384 structure to use for encryption
\param data the data to be hashed \param data the data to be hashed
\param len length of data to be hashed \param len length of data to be hashed
@ -144,7 +144,7 @@ WOLFSSL_API int wc_InitSha384(wc_Sha384*);
wc_Sha384Final(sha384, hash); wc_Sha384Final(sha384, hash);
} }
\endcode \endcode
\sa wc_Sha384Hash \sa wc_Sha384Hash
\sa wc_Sha384Final \sa wc_Sha384Final
\sa wc_InitSha384 \sa wc_InitSha384
@ -153,14 +153,14 @@ WOLFSSL_API int wc_Sha384Update(wc_Sha384*, const byte*, word32);
/*! /*!
\ingroup SHA \ingroup SHA
\brief Finalizes hashing of data. Result is placed into hash. \brief Finalizes hashing of data. Result is placed into hash.
\return 0 Returned upon successfully finalizing. \return 0 Returned upon successfully finalizing.
\param sha384 pointer to the sha384 structure to use for encryption \param sha384 pointer to the sha384 structure to use for encryption
\param hash Byte array to hold hash value. \param hash Byte array to hold hash value.
_Example_ _Example_
\code \code
Sha384 sha384[1]; Sha384 sha384[1];
@ -175,7 +175,7 @@ WOLFSSL_API int wc_Sha384Update(wc_Sha384*, const byte*, word32);
wc_Sha384Final(sha384, hash); wc_Sha384Final(sha384, hash);
} }
\endcode \endcode
\sa wc_Sha384Hash \sa wc_Sha384Hash
\sa wc_Sha384Final \sa wc_Sha384Final
\sa wc_InitSha384 \sa wc_InitSha384

52
doc/dox_comments/header_files/signature.h
View File

@ -1,17 +1,17 @@
/*! /*!
\ingroup Signature \ingroup Signature
\brief This function returns the maximum size of the resulting signature. \brief This function returns the maximum size of the resulting signature.
\return Returns SIG_TYPE_E if sig_type is not supported. Returns \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 BAD_FUNC_ARG if sig_type was invalid. A positive return value indicates
the maximum size of a signature. the maximum size of a signature.
\param sig_type A signature type enum value such as \param sig_type A signature type enum value such as
WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA. WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA.
\param key Pointer to a key structure such as ecc_key or RsaKey. \param key Pointer to a key structure such as ecc_key or RsaKey.
\param key_len Size of the key structure. \param key_len Size of the key structure.
_Example_ _Example_
\code \code
// Get signature length // Get signature length
@ -24,7 +24,7 @@
// Success // Success
} }
\endcode \endcode
\sa wc_HashGetDigestSize \sa wc_HashGetDigestSize
\sa wc_SignatureGenerate \sa wc_SignatureGenerate
\sa wc_SignatureVerify \sa wc_SignatureVerify
@ -34,18 +34,18 @@ WOLFSSL_API int wc_SignatureGetSize(enum wc_SignatureType sig_type,
/*! /*!
\ingroup Signature \ingroup Signature
\brief This function validates a signature by hashing the data and \brief This function validates a signature by hashing the data and
using the resulting hash and key to verify the signature. using the resulting hash and key to verify the signature.
\return 0 Success \return 0 Success
\return SIG_TYPE_E -231, signature type not enabled/ available \return SIG_TYPE_E -231, signature type not enabled/ available
\return BAD_FUNC_ARG -173, bad function argument provided \return BAD_FUNC_ARG -173, bad function argument provided
\return BUFFER_E -132, output buffer too small or input too large. \return BUFFER_E -132, output buffer too small or input too large.
\param hash_type A hash type from the “enum wc_HashType” such as \param hash_type A hash type from the “enum wc_HashType” such as
“WC_HASH_TYPE_SHA256”. “WC_HASH_TYPE_SHA256”.
\param sig_type A signature type enum value such as \param sig_type A signature type enum value such as
WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA. WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA.
\param data Pointer to buffer containing the data to hash. \param data Pointer to buffer containing the data to hash.
\param data_len Length of the data buffer. \param data_len Length of the data buffer.
@ -53,7 +53,7 @@ WOLFSSL_API int wc_SignatureGetSize(enum wc_SignatureType sig_type,
\param sig_len Length of the signature output buffer. \param sig_len Length of the signature output buffer.
\param key Pointer to a key structure such as ecc_key or RsaKey. \param key Pointer to a key structure such as ecc_key or RsaKey.
\param key_len Size of the key structure. \param key_len Size of the key structure.
_Example_ _Example_
\code \code
int ret; int ret;
@ -68,11 +68,11 @@ WOLFSSL_API int wc_SignatureGetSize(enum wc_SignatureType sig_type,
fileBuf, fileLen, fileBuf, fileLen,
sigBuf, sigLen, sigBuf, sigLen,
&eccKey, sizeof(eccKey)); &eccKey, sizeof(eccKey));
printf("Signature Verification: %s printf("Signature Verification: %s
(%d)\n", (ret == 0) ? "Pass" : "Fail", ret); (%d)\n", (ret == 0) ? "Pass" : "Fail", ret);
wc_ecc_free(&eccKey); wc_ecc_free(&eccKey);
\endcode \endcode
\sa wc_SignatureGetSize \sa wc_SignatureGetSize
\sa wc_SignatureGenerate \sa wc_SignatureGenerate
*/ */
@ -84,18 +84,18 @@ WOLFSSL_API int wc_SignatureVerify(
/*! /*!
\ingroup Signature \ingroup Signature
\brief This function generates a signature from the data using a \brief This function generates a signature from the data using a
key. It first creates a hash of the data then signs the hash using the key. key. It first creates a hash of the data then signs the hash using the key.
\return 0 Success \return 0 Success
\return SIG_TYPE_E -231, signature type not enabled/ available \return SIG_TYPE_E -231, signature type not enabled/ available
\return BAD_FUNC_ARG -173, bad function argument provided \return BAD_FUNC_ARG -173, bad function argument provided
\return BUFFER_E -132, output buffer too small or input too large. \return BUFFER_E -132, output buffer too small or input too large.
\param hash_type A hash type from the “enum wc_HashType” \param hash_type A hash type from the “enum wc_HashType”
such as “WC_HASH_TYPE_SHA256”. such as “WC_HASH_TYPE_SHA256”.
\param sig_type A signature type enum value such as \param sig_type A signature type enum value such as
WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA. WC_SIGNATURE_TYPE_ECC or WC_SIGNATURE_TYPE_RSA.
\param data Pointer to buffer containing the data to hash. \param data Pointer to buffer containing the data to hash.
\param data_len Length of the data buffer. \param data_len Length of the data buffer.
@ -104,13 +104,13 @@ WOLFSSL_API int wc_SignatureVerify(
\param key Pointer to a key structure such as ecc_key or RsaKey. \param key Pointer to a key structure such as ecc_key or RsaKey.
\param key_len Size of the key structure. \param key_len Size of the key structure.
\param rng Pointer to an initialized RNG structure. \param rng Pointer to an initialized RNG structure.
_Example_ _Example_
\code \code
int ret; int ret;
WC_RNG rng; WC_RNG rng;
ecc_key eccKey; ecc_key eccKey;
wc_InitRng(&rng); wc_InitRng(&rng);
wc_ecc_init(&eccKey); wc_ecc_init(&eccKey);
@ -128,14 +128,14 @@ WOLFSSL_API int wc_SignatureVerify(
sigBuf, &sigLen, sigBuf, &sigLen,
&eccKey, sizeof(eccKey), &eccKey, sizeof(eccKey),
&rng); &rng);
printf("Signature Generation: %s printf("Signature Generation: %s
(%d)\n", (ret == 0) ? "Pass" : "Fail", ret); (%d)\n", (ret == 0) ? "Pass" : "Fail", ret);
free(sigBuf); free(sigBuf);
wc_ecc_free(&eccKey); wc_ecc_free(&eccKey);
wc_FreeRng(&rng); wc_FreeRng(&rng);
\endcode \endcode
\sa wc_SignatureGetSize \sa wc_SignatureGetSize
\sa wc_SignatureVerify \sa wc_SignatureVerify
*/ */

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

@ -1,19 +1,19 @@
/*! /*!
\ingroup SRP \ingroup SRP
\brief Initializes the Srp struct for usage. \brief Initializes the Srp struct for usage.
\return 0 on success. \return 0 on success.
\return BAD_FUNC_ARG Returns when there's an issue with the arguments such \return BAD_FUNC_ARG Returns when there's an issue with the arguments such
as srp being null or SrpSide not being SRP_CLIENT_SIDE or SRP_SERVER_SIDE. as srp being null or SrpSide not being SRP_CLIENT_SIDE or SRP_SERVER_SIDE.
\return NOT_COMPILED_IN Returns when a type is passed as an argument but \return NOT_COMPILED_IN Returns when a type is passed as an argument but
hasn't been configured in the wolfCrypt build. hasn't been configured in the wolfCrypt build.
\return <0 on error. \return <0 on error.
\param srp the Srp structure to be initialized. \param srp the Srp structure to be initialized.
\param type the hash type to be used. \param type the hash type to be used.
\param side the side of the communication. \param side the side of the communication.
_Example_ _Example_
\code \code
Srp srp; Srp srp;
@ -26,7 +26,7 @@
wc_SrpTerm(&srp); wc_SrpTerm(&srp);
} }
\endcode \endcode
\sa wc_SrpTerm \sa wc_SrpTerm
\sa wc_SrpSetUsername \sa wc_SrpSetUsername
*/ */
@ -34,13 +34,13 @@ WOLFSSL_API int wc_SrpInit(Srp* srp, SrpType type, SrpSide side);
/*! /*!
\ingroup SRP \ingroup SRP
\brief Releases the Srp struct resources after usage. \brief Releases the Srp struct resources after usage.
\return none No returns. \return none No returns.
\param srp Pointer to the Srp structure to be terminated. \param srp Pointer to the Srp structure to be terminated.
_Example_ _Example_
\code \code
Srp srp; Srp srp;
@ -48,26 +48,26 @@ WOLFSSL_API int wc_SrpInit(Srp* srp, SrpType type, SrpSide side);
// Use srp // Use srp
wc_SrpTerm(&srp) wc_SrpTerm(&srp)
\endcode \endcode
\sa wc_SrpInit \sa wc_SrpInit
*/ */
WOLFSSL_API void wc_SrpTerm(Srp* srp); WOLFSSL_API void wc_SrpTerm(Srp* srp);
/*! /*!
\ingroup SRP \ingroup SRP
\brief Sets the username. This function MUST be called after wc_SrpInit. \brief Sets the username. This function MUST be called after wc_SrpInit.
\return 0 Username set successfully. \return 0 Username set successfully.
\return BAD_FUNC_ARG: Return if srp or username is null. \return BAD_FUNC_ARG: Return if srp or username is null.
\return MEMORY_E: Returns if there is an issue allocating memory \return MEMORY_E: Returns if there is an issue allocating memory
for srp->user for srp->user
\return < 0: Error. \return < 0: Error.
\param srp the Srp structure. \param srp the Srp structure.
\param username the buffer containing the username. \param username the buffer containing the username.
\param size the username size in bytes \param size the username size in bytes
_Example_ _Example_
\code \code
Srp srp; Srp srp;
@ -81,7 +81,7 @@ WOLFSSL_API void wc_SrpTerm(Srp* srp);
} }
wc_SrpTerm(&srp); wc_SrpTerm(&srp);
\endcode \endcode
\sa wc_SrpInit \sa wc_SrpInit
\sa wc_SrpSetParams \sa wc_SrpSetParams
\sa wc_SrpTerm \sa wc_SrpTerm
@ -90,16 +90,16 @@ WOLFSSL_API int wc_SrpSetUsername(Srp* srp, const byte* username, word32 size);
/*! /*!
\ingroup SRP \ingroup SRP
\brief Sets the srp parameters based on the username.. Must be called \brief Sets the srp parameters based on the username.. Must be called
after wc_SrpSetUsername. after wc_SrpSetUsername.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returns if srp, N, g, or salt is null or if nSz < gSz. \return BAD_FUNC_ARG Returns if srp, N, g, or salt is null or if nSz < gSz.
\return SRP_CALL_ORDER_E Returns if wc_SrpSetParams is called before \return SRP_CALL_ORDER_E Returns if wc_SrpSetParams is called before
wc_SrpSetUsername. wc_SrpSetUsername.
\return <0 Error \return <0 Error
\param srp the Srp structure. \param srp the Srp structure.
\param N the Modulus. N = 2q+1, [q, N] are primes. \param N the Modulus. N = 2q+1, [q, N] are primes.
\param nSz the N size in bytes. \param nSz the N size in bytes.
@ -121,14 +121,14 @@ wc_SrpSetUsername.
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE); wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize); wc_SrpSetUsername(&srp, username, usernameSize);
if(wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, if(wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt,
sizeof(salt)) != 0) sizeof(salt)) != 0)
{ {
// Error setting params // Error setting params
} }
wc_SrpTerm(&srp); wc_SrpTerm(&srp);
\endcode \endcode
\sa wc_SrpInit \sa wc_SrpInit
\sa wc_SrpSetUsername \sa wc_SrpSetUsername
\sa wc_SrpTerm \sa wc_SrpTerm
@ -139,16 +139,16 @@ WOLFSSL_API int wc_SrpSetParams(Srp* srp, const byte* N, word32 nSz,
/*! /*!
\ingroup SRP \ingroup SRP
\brief Sets the password. Setting the password does not persists the \brief Sets the password. Setting the password does not persists the
clear password data in the srp structure. The client calculates 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 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. MUST be called after wc_SrpSetParams and is CLIENT SIDE ONLY.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returns if srp or password is null or if srp->side \return BAD_FUNC_ARG Returns if srp or password is null or if srp->side
is not set to SRP_CLIENT_SIDE. is not set to SRP_CLIENT_SIDE.
\return SRP_CALL_ORDER_E Returns when wc_SrpSetPassword is called out \return SRP_CALL_ORDER_E Returns when wc_SrpSetPassword is called out
of order. of order.
\return <0 Error \return <0 Error
@ -179,7 +179,7 @@ WOLFSSL_API int wc_SrpSetParams(Srp* srp, const byte* N, word32 nSz,
wc_SrpTerm(&srp); wc_SrpTerm(&srp);
\endcode \endcode
\sa wc_SrpInit \sa wc_SrpInit
\sa wc_SrpSetUsername \sa wc_SrpSetUsername
\sa wc_SrpSetParams \sa wc_SrpSetParams
@ -188,12 +188,12 @@ WOLFSSL_API int wc_SrpSetPassword(Srp* srp, const byte* password, word32 size);
/*! /*!
\ingroup SRP \ingroup SRP
\brief Sets the verifier. This function MUST be called after \brief Sets the verifier. This function MUST be called after
wc_SrpSetParams and is SERVER SIDE ONLY. wc_SrpSetParams and is SERVER SIDE ONLY.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returned if srp or verifier is null or \return BAD_FUNC_ARG Returned if srp or verifier is null or
srp->side is not SRP_SERVER_SIDE. srp->side is not SRP_SERVER_SIDE.
\return <0 Error \return <0 Error
@ -222,7 +222,7 @@ WOLFSSL_API int wc_SrpSetPassword(Srp* srp, const byte* password, word32 size);
wc_SrpTerm(&srp); wc_SrpTerm(&srp);
\endcode \endcode
\sa wc_SrpInit \sa wc_SrpInit
\sa wc_SrpSetParams \sa wc_SrpSetParams
\sa wc_SrpGetVerifier \sa wc_SrpGetVerifier
@ -231,23 +231,23 @@ WOLFSSL_API int wc_SrpSetVerifier(Srp* srp, const byte* verifier, word32 size);
/*! /*!
\ingroup SRP \ingroup SRP
\brief Gets the verifier. The client calculates the verifier \brief Gets the verifier. The client calculates the verifier
with v = g ^ x % N. with v = g ^ x % N.
This function MAY be called after wc_SrpSetPassword and This function MAY be called after wc_SrpSetPassword and
is CLIENT SIDE ONLY. is CLIENT SIDE ONLY.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returned if srp, verifier or size is null \return BAD_FUNC_ARG Returned if srp, verifier or size is null
or if srp->side is not SRP_CLIENT_SIDE. or if srp->side is not SRP_CLIENT_SIDE.
\return SRP_CALL_ORDER_E Returned if wc_SrpGetVerifier is called \return SRP_CALL_ORDER_E Returned if wc_SrpGetVerifier is called
out of order. out of order.
\return <0 Error \return <0 Error
\param srp The Srp structure. \param srp The Srp structure.
\param verifier The buffer to write the verifier. \param verifier The buffer to write the verifier.
\param size Buffer size in bytes. Updated with the verifier size. \param size Buffer size in bytes. Updated with the verifier size.
_Example_ _Example_
\code \code
Srp srp; Srp srp;
@ -274,7 +274,7 @@ WOLFSSL_API int wc_SrpSetVerifier(Srp* srp, const byte* verifier, word32 size);
} }
wc_SrpTerm(&srp); wc_SrpTerm(&srp);
\endcode \endcode
\sa wc_SrpSetVerifier \sa wc_SrpSetVerifier
\sa wc_SrpSetPassword \sa wc_SrpSetPassword
*/ */
@ -282,22 +282,22 @@ WOLFSSL_API int wc_SrpGetVerifier(Srp* srp, byte* verifier, word32* size);
/*! /*!
\ingroup SRP \ingroup SRP
\brief Sets the private ephemeral value. The private ephemeral value \brief Sets the private ephemeral value. The private ephemeral value
is known as: is known as:
a at the client side. a = random() a at the client side. a = random()
b at the server side. b = random() b at the server side. b = random()
This function is handy for unit test cases or if the developer wants This function is handy for unit test cases or if the developer wants
to use an external to use an external
random source to set the ephemeral value. This function MAY be called random source to set the ephemeral value. This function MAY be called
before wc_SrpGetPublic. before wc_SrpGetPublic.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returned if srp, private, or size is null. \return BAD_FUNC_ARG Returned if srp, private, or size is null.
\return SRP_CALL_ORDER_E Returned if wc_SrpSetPrivate is called out \return SRP_CALL_ORDER_E Returned if wc_SrpSetPrivate is called out
of order. of order.
\return <0 Error \return <0 Error
\param srp the Srp structure. \param srp the Srp structure.
\param priv the ephemeral value. \param priv the ephemeral value.
\param size the private size in bytes. \param size the private size in bytes.
@ -325,31 +325,31 @@ WOLFSSL_API int wc_SrpGetVerifier(Srp* srp, byte* verifier, word32* size);
wc_SrpTerm(&srp); wc_SrpTerm(&srp);
\endcode \endcode
\sa wc_SrpGetPublic \sa wc_SrpGetPublic
*/ */
WOLFSSL_API int wc_SrpSetPrivate(Srp* srp, const byte* priv, word32 size); WOLFSSL_API int wc_SrpSetPrivate(Srp* srp, const byte* priv, word32 size);
/*! /*!
\ingroup SRP \ingroup SRP
\brief Gets the public ephemeral value. The public ephemeral value \brief Gets the public ephemeral value. The public ephemeral value
is known as: is known as:
A at the client side. A = g ^ a % N A at the client side. A = g ^ a % N
B at the server side. B = (k * v + (g ˆ b % N)) % N B at the server side. B = (k * v + (g ˆ b % N)) % N
This function MUST be called after wc_SrpSetPassword or wc_SrpSetVerifier. This function MUST be called after wc_SrpSetPassword or wc_SrpSetVerifier.
The function wc_SrpSetPrivate may be called before wc_SrpGetPublic. The function wc_SrpSetPrivate may be called before wc_SrpGetPublic.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returned if srp, pub, or size is null. \return BAD_FUNC_ARG Returned if srp, pub, or size is null.
\return SRP_CALL_ORDER_E Returned if wc_SrpGetPublic is called out \return SRP_CALL_ORDER_E Returned if wc_SrpGetPublic is called out
of order. of order.
\return BUFFER_E Returned if size < srp.N. \return BUFFER_E Returned if size < srp.N.
\return <0 Error \return <0 Error
\param srp the Srp structure. \param srp the Srp structure.
\param pub the buffer to write the public ephemeral value. \param pub the buffer to write the public ephemeral value.
\param size the the buffer size in bytes. Will be updated with \param size the the buffer size in bytes. Will be updated with
the ephemeral value size. the ephemeral value size.
_Example_ _Example_
@ -378,7 +378,7 @@ WOLFSSL_API int wc_SrpSetPrivate(Srp* srp, const byte* priv, word32 size);
wc_SrpTerm(&srp); wc_SrpTerm(&srp);
\endcode \endcode
\sa wc_SrpSetPrivate \sa wc_SrpSetPrivate
\sa wc_SrpSetPassword \sa wc_SrpSetPassword
\sa wc_SrpSetVerifier \sa wc_SrpSetVerifier
@ -387,17 +387,17 @@ WOLFSSL_API int wc_SrpGetPublic(Srp* srp, byte* pub, word32* size);
/*! /*!
\ingroup SRP \ingroup SRP
\brief Computes the session key. The key can be accessed at \brief Computes the session key. The key can be accessed at
srp->key after success. srp->key after success.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returned if srp, clientPubKey, or serverPubKey \return BAD_FUNC_ARG Returned if srp, clientPubKey, or serverPubKey
or if clientPubKeySz or serverPubKeySz is 0. or if clientPubKeySz or serverPubKeySz is 0.
\return SRP_CALL_ORDER_E Returned if wc_SrpComputeKey is called out \return SRP_CALL_ORDER_E Returned if wc_SrpComputeKey is called out
of order. of order.
\return <0 Error \return <0 Error
\param srp the Srp structure. \param srp the Srp structure.
\param clientPubKey the client's public ephemeral value. \param clientPubKey the client's public ephemeral value.
\param clientPubKeySz the client's public ephemeral value size. \param clientPubKeySz the client's public ephemeral value size.
@ -431,7 +431,7 @@ WOLFSSL_API int wc_SrpGetPublic(Srp* srp, byte* pub, word32* size);
serverPubKey, serverPubKeySize) serverPubKey, serverPubKeySize)
wc_SrpTerm(&server); wc_SrpTerm(&server);
\endcode \endcode
\sa wc_SrpGetPublic \sa wc_SrpGetPublic
*/ */
WOLFSSL_API int wc_SrpComputeKey(Srp* srp, WOLFSSL_API int wc_SrpComputeKey(Srp* srp,
@ -440,9 +440,9 @@ WOLFSSL_API int wc_SrpComputeKey(Srp* srp,
/*! /*!
\ingroup SRP \ingroup SRP
\brief Gets the proof. This function MUST be called after wc_SrpComputeKey. \brief Gets the proof. This function MUST be called after wc_SrpComputeKey.
\return 0 Success \return 0 Success
\return BAD_FUNC_ARG Returns if srp, proof, or size is null. \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 BUFFER_E Returns if size is less than the hash size of srp->type.
@ -465,24 +465,24 @@ WOLFSSL_API int wc_SrpComputeKey(Srp* srp,
// Error getting proof // Error getting proof
} }
\endcode \endcode
\sa wc_SrpComputeKey \sa wc_SrpComputeKey
*/ */
WOLFSSL_API int wc_SrpGetProof(Srp* srp, byte* proof, word32* size); WOLFSSL_API int wc_SrpGetProof(Srp* srp, byte* proof, word32* size);
/*! /*!
\ingroup SRP \ingroup SRP
\brief Verifies the peers proof. This function MUST be called before \brief Verifies the peers proof. This function MUST be called before
wc_SrpGetSessionKey. wc_SrpGetSessionKey.
\return 0 Success \return 0 Success
\return <0 Error \return <0 Error
\param srp the Srp structure. \param srp the Srp structure.
\param proof the peers proof. \param proof the peers proof.
\param size the proof size in bytes. \param size the proof size in bytes.
_Example_ _Example_
\code \code
Srp cli; Srp cli;
@ -499,7 +499,7 @@ WOLFSSL_API int wc_SrpGetProof(Srp* srp, byte* proof, word32* size);
// Error verifying proof // Error verifying proof
} }
\endcode \endcode
\sa wc_SrpGetSessionKey \sa wc_SrpGetSessionKey
\sa wc_SrpGetProof \sa wc_SrpGetProof
\sa wc_SrpTerm \sa wc_SrpTerm

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

File diff suppressed because it is too large Load Diff

24
doc/dox_comments/header_files/tfm.h
View File

@ -1,29 +1,29 @@
/*! /*!
\ingroup Math \ingroup Math
\brief This function checks the runtime fastmath settings for the maximum \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 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 library independently, as the FP_SIZE must match for each library in order
for math to work correctly. This check is defined as for math to work correctly. This check is defined as
CheckFastMathSettings(), which simply compares CheckRunTimeFastMath CheckFastMathSettings(), which simply compares CheckRunTimeFastMath
and FP_SIZE, returning 0 if there is a mismatch, or 1 if they match. and FP_SIZE, returning 0 if there is a mismatch, or 1 if they match.
\return FP_SIZE Returns FP_SIZE, corresponding to the max size \return FP_SIZE Returns FP_SIZE, corresponding to the max size
available for the math library. available for the math library.
\param none No parameters. \param none No parameters.
_Example_ _Example_
\code \code
if (CheckFastMathSettings() != 1) { if (CheckFastMathSettings() != 1) {
return err_sys("Build vs. runtime fastmath FP_MAX_BITS mismatch\n"); return err_sys("Build vs. runtime fastmath FP_MAX_BITS mismatch\n");
} }
// This is converted by the preprocessor to: // This is converted by the preprocessor to:
// if ( (CheckRunTimeFastMath() == FP_SIZE) != 1) { // if ( (CheckRunTimeFastMath() == FP_SIZE) != 1) {
// and confirms that the fast math settings match // and confirms that the fast math settings match
// the compile time settings // the compile time settings
\endcode \endcode
\sa CheckRunTimeSettings \sa CheckRunTimeSettings
*/ */
WOLFSSL_API word32 CheckRunTimeFastMath(void); WOLFSSL_API word32 CheckRunTimeFastMath(void);

84
doc/dox_comments/header_files/types.h
View File

@ -1,24 +1,24 @@
/*! /*!
\ingroup Memory \ingroup Memory
\brief This is not actually a function, but rather a preprocessor macro, \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 which allows the user to substitute in their own malloc, realloc, and free
functions in place of the standard C memory functions. functions in place of the standard C memory functions.
To use external memory functions, define XMALLOC_USER. This will cause the To use external memory functions, define XMALLOC_USER. This will cause the
memory functions to be replaced by external functions of the form: memory functions to be replaced by external functions of the form:
extern void *XMALLOC(size_t n, void* heap, int type); extern void *XMALLOC(size_t n, void* heap, int type);
extern void *XREALLOC(void *p, 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); extern void XFREE(void *p, void* heap, int type);
To use the basic C memory functions in place of wolfSSL_Malloc, To use the basic C memory functions in place of wolfSSL_Malloc,
wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This
will replace the memory functions with: will replace the memory functions with:
#define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s)))
#define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));}
#define XREALLOC(p, n, h, t) realloc((p), (n)) #define XREALLOC(p, n, h, t) realloc((p), (n))
If none of these options are selected, the system will default to use If none of these options are selected, the system will default to use
the wolfSSL memory functions. A user can set custom memory functions the wolfSSL memory functions. A user can set custom memory functions
through callback hooks, (see wolfSSL_Malloc, through callback hooks, (see wolfSSL_Malloc,
wolfSSL_Realloc, wolfSSL_Free). This option will replace the wolfSSL_Realloc, wolfSSL_Free). This option will replace the
memory functions with: memory functions with:
#define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #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 XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));}
@ -50,25 +50,25 @@ WOLFSSL_API void* XMALLOC(size_t n, void* heap, int type);
/*! /*!
\ingroup Memory \ingroup Memory
\brief This is not actually a function, but rather a preprocessor macro, \brief This is not actually a function, but rather a preprocessor macro,
which allows the user to substitute in their own malloc, realloc, and which allows the user to substitute in their own malloc, realloc, and
free functions in place of the standard C memory functions. free functions in place of the standard C memory functions.
To use external memory functions, define XMALLOC_USER. This will cause the To use external memory functions, define XMALLOC_USER. This will cause the
memory functions to be replaced by external functions of the form: memory functions to be replaced by external functions of the form:
extern void *XMALLOC(size_t n, void* heap, int type); extern void *XMALLOC(size_t n, void* heap, int type);
extern void *XREALLOC(void *p, 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); extern void XFREE(void *p, void* heap, int type);
To use the basic C memory functions in place of wolfSSL_Malloc, To use the basic C memory functions in place of wolfSSL_Malloc,
wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will
replace the memory functions with: replace the memory functions with:
#define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s)))
#define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));}
#define XREALLOC(p, n, h, t) realloc((p), (n)) #define XREALLOC(p, n, h, t) realloc((p), (n))
If none of these options are selected, the system will default to If none of these options are selected, the system will default to
use the wolfSSL memory functions. A user can set custom memory use the wolfSSL memory functions. A user can set custom memory
functions through callback hooks, (see wolfSSL_Malloc, functions through callback hooks, (see wolfSSL_Malloc,
wolfSSL_Realloc, wolfSSL_Free). This option will replace wolfSSL_Realloc, wolfSSL_Free). This option will replace
the memory functions with: the memory functions with:
#define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #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 XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));}
@ -96,31 +96,31 @@ WOLFSSL_API void* XREALLOC(void *p, size_t n, void* heap, int type);
/*! /*!
\ingroup Memory \ingroup Memory
\brief This is not actually a function, but rather a preprocessor macro, \brief This is not actually a function, but rather a preprocessor macro,
which allows the user to substitute in their own malloc, realloc, and which allows the user to substitute in their own malloc, realloc, and
free functions in place of the standard C memory functions. free functions in place of the standard C memory functions.
To use external memory functions, define XMALLOC_USER. This will cause To use external memory functions, define XMALLOC_USER. This will cause
the memory functions to be replaced by external functions of the form: the memory functions to be replaced by external functions of the form:
extern void *XMALLOC(size_t n, void* heap, int type); extern void *XMALLOC(size_t n, void* heap, int type);
extern void *XREALLOC(void *p, 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); extern void XFREE(void *p, void* heap, int type);
To use the basic C memory functions in place of wolfSSL_Malloc, To use the basic C memory functions in place of wolfSSL_Malloc,
wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This
will replace the memory functions with: will replace the memory functions with:
#define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s)))
#define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));}
#define XREALLOC(p, n, h, t) realloc((p), (n)) #define XREALLOC(p, n, h, t) realloc((p), (n))
If none of these options are selected, the system will default to use If none of these options are selected, the system will default to use
the wolfSSL memory functions. A user can set custom memory functions the wolfSSL memory functions. A user can set custom memory functions
through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc, through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc,
wolfSSL_Free). This option will replace the memory functions with: wolfSSL_Free). This option will replace the memory functions with:
#define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #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 XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));}
#define XREALLOC(p, n, h, t) wolfSSL_Realloc((p), (n)) #define XREALLOC(p, n, h, t) wolfSSL_Realloc((p), (n))
\return none No returns. \return none No returns.
\param p pointer to the address to free \param p pointer to the address to free
\param h (used by custom XFREE function) pointer to the heap to use \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 \param t memory allocation types for user hints. See enum in types.h
@ -144,29 +144,29 @@ WOLFSSL_API void XFREE(void *p, void* heap, int type);
/*! /*!
\ingroup Math \ingroup Math
\brief This function checks the compile time class settings. It is \brief This function checks the compile time class settings. It is
important when a user is using a wolfCrypt library independently, as important when a user is using a wolfCrypt library independently, as
the settings must match between libraries for math to work correctly. the settings must match between libraries for math to work correctly.
This check is defined as CheckCtcSettings(), which simply compares This check is defined as CheckCtcSettings(), which simply compares
CheckRunTimeSettings and CTC_SETTINGS, returning 0 if there is a CheckRunTimeSettings and CTC_SETTINGS, returning 0 if there is a
mismatch, or 1 if they match. mismatch, or 1 if they match.
\return settings Returns the runtime CTC_SETTINGS (Compile Time Settings) \return settings Returns the runtime CTC_SETTINGS (Compile Time Settings)
\param none No Parameters. \param none No Parameters.
_Example_ _Example_
\code \code
if (CheckCtcSettings() != 1) { if (CheckCtcSettings() != 1) {
return err_sys("Build vs. runtime math mismatch\n"); return err_sys("Build vs. runtime math mismatch\n");
} }
// This is converted by the preprocessor to: // This is converted by the preprocessor to:
// if ( (CheckCtcSettings() == CTC_SETTINGS) != 1) { // if ( (CheckCtcSettings() == CTC_SETTINGS) != 1) {
// and will compare whether the compile time class settings // and will compare whether the compile time class settings
// match the current settings // match the current settings
\endcode \endcode
\sa CheckRunTimeFastMath \sa CheckRunTimeFastMath
*/ */
WOLFSSL_API word32 CheckRunTimeSettings(void); WOLFSSL_API word32 CheckRunTimeSettings(void);

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

@ -1,42 +1,42 @@
/*! /*!
\ingroup AES \ingroup AES
\brief Decrypts a cipher from the input buffer in, and places the \brief Decrypts a cipher from the input buffer in, and places the
resulting plain text in the output buffer out using cipher block resulting plain text in the output buffer out using cipher block
chaining with AES. This function does not require an AES structure chaining with AES. This function does not require an AES structure
to be initialized. Instead, it takes in a key and an iv to be initialized. Instead, it takes in a key and an iv
(initialization vector) and uses these to initialize an (initialization vector) and uses these to initialize an
AES object and then decrypt the cipher text. AES object and then decrypt the cipher text.
\return 0 On successfully decrypting message \return 0 On successfully decrypting message
\return BAD_ALIGN_E Returned on block align error \return BAD_ALIGN_E Returned on block align error
\return BAD_FUNC_ARG Returned if key length is invalid or AES object \return BAD_FUNC_ARG Returned if key length is invalid or AES object
is null during AesSetIV is null during AesSetIV
\return MEMORY_E Returned if WOLFSSL_SMALL_STACK is enabled and \return MEMORY_E Returned if WOLFSSL_SMALL_STACK is enabled and
XMALLOC fails to instantiate an AES object. XMALLOC fails to instantiate an AES object.
\param out pointer to the output buffer in which to store the plain \param out pointer to the output buffer in which to store the plain
text of the decrypted message text of the decrypted message
\param in pointer to the input buffer containing cipher text to be \param in pointer to the input buffer containing cipher text to be
decrypted decrypted
\param inSz size of input message \param inSz size of input message
\param key 16, 24, or 32 byte secret key for decryption \param key 16, 24, or 32 byte secret key for decryption
\param keySz size of key used for decryption \param keySz size of key used for decryption
_Example_ _Example_
\code \code
int ret = 0; int ret = 0;
byte key[] = { some 16, 24, or 32 byte key }; byte key[] = { some 16, 24, or 32 byte key };
byte iv[] = { some 16 byte iv }; byte iv[] = { some 16 byte iv };
byte cipher[AES_BLOCK_SIZE * n]; //n being a positive integer making byte cipher[AES_BLOCK_SIZE * n]; //n being a positive integer making
cipher some multiple of 16 bytes cipher some multiple of 16 bytes
// fill cipher with cipher text // fill cipher with cipher text
byte plain [AES_BLOCK_SIZE * n]; byte plain [AES_BLOCK_SIZE * n];
if ((ret = wc_AesCbcDecryptWithKey(plain, cipher, AES_BLOCK_SIZE, key, if ((ret = wc_AesCbcDecryptWithKey(plain, cipher, AES_BLOCK_SIZE, key,
AES_BLOCK_SIZE, iv)) != 0 ) { AES_BLOCK_SIZE, iv)) != 0 ) {
// Decrypt Error // Decrypt Error
} }
\endcode \endcode
\sa wc_AesSetKey \sa wc_AesSetKey
\sa wc_AesSetIV \sa wc_AesSetIV
\sa wc_AesCbcEncrypt \sa wc_AesCbcEncrypt
@ -48,25 +48,25 @@ WOLFSSL_API int wc_AesCbcDecryptWithKey(byte* out, const byte* in, word32 inSz,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function decrypts the input ciphertext, in, and stores the \brief This function decrypts the input ciphertext, in, and stores the
resulting plaintext in the output buffer, out. It uses DES encryption resulting plaintext in the output buffer, out. It uses DES encryption
with cipher block chaining (CBC) mode. This function is a substitute with cipher block chaining (CBC) mode. This function is a substitute
for wc_Des_CbcDecrypt, allowing the user to decrypt a message without for wc_Des_CbcDecrypt, allowing the user to decrypt a message without
directly instantiating a Des structure. directly instantiating a Des structure.
\return 0 Returned upon successfully decrypting the given ciphertext \return 0 Returned upon successfully decrypting the given ciphertext
\return MEMORY_E Returned if there is an error allocating space for a \return MEMORY_E Returned if there is an error allocating space for a
Des structure Des structure
\param out pointer to the buffer in which to store the decrypted plaintext \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 in pointer to the input buffer containing the encrypted ciphertext
\param sz length of the ciphertext to decrypt \param sz length of the ciphertext to decrypt
\param key pointer to the buffer containing the 8 byte key to use for \param key pointer to the buffer containing the 8 byte key to use for
decryption decryption
\param iv pointer to the buffer containing the 8 byte iv to use for \param iv pointer to the buffer containing the 8 byte iv to use for
decryption. If no iv is provided, the iv defaults to 0 decryption. If no iv is provided, the iv defaults to 0
_Example_ _Example_
\code \code
int ret; int ret;
@ -76,12 +76,12 @@ WOLFSSL_API int wc_AesCbcDecryptWithKey(byte* out, const byte* in, word32 inSz,
byte cipher[] = { // initialize with ciphertext }; byte cipher[] = { // initialize with ciphertext };
byte decoded[sizeof(cipher)]; byte decoded[sizeof(cipher)];
if ( wc_Des_CbcDecryptWithKey(decoded, cipher, sizeof(cipher), key, if ( wc_Des_CbcDecryptWithKey(decoded, cipher, sizeof(cipher), key,
iv) != 0) { iv) != 0) {
// error decrypting message // error decrypting message
} }
\endcode \endcode
\sa wc_Des_CbcDecrypt \sa wc_Des_CbcDecrypt
*/ */
WOLFSSL_API int wc_Des_CbcDecryptWithKey(byte* out, WOLFSSL_API int wc_Des_CbcDecryptWithKey(byte* out,
@ -90,15 +90,15 @@ WOLFSSL_API int wc_Des_CbcDecryptWithKey(byte* out,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function encrypts the input plaintext, in, and stores the \brief This function encrypts the input plaintext, in, and stores the
resulting ciphertext in the output buffer, out. It uses DES encryption resulting ciphertext in the output buffer, out. It uses DES encryption
with cipher block chaining (CBC) mode. This function is a substitute with cipher block chaining (CBC) mode. This function is a substitute
for wc_Des_CbcEncrypt, allowing the user to encrypt a message without for wc_Des_CbcEncrypt, allowing the user to encrypt a message without
directly instantiating a Des structure. directly instantiating a Des structure.
\return 0 Returned after successfully encrypting data. \return 0 Returned after successfully encrypting data.
\return MEMORY_E Returned if there's an error allocating memory for a \return MEMORY_E Returned if there's an error allocating memory for a
Des structure. Des structure.
\return <0 Returned on any error during encryption. \return <0 Returned on any error during encryption.
@ -115,11 +115,11 @@ WOLFSSL_API int wc_Des_CbcDecryptWithKey(byte* out,
byte in[] = { // Initialize with plaintext }; byte in[] = { // Initialize with plaintext };
byte out[sizeof(in)]; byte out[sizeof(in)];
if ( wc_Des_CbcEncryptWithKey(&out, in, sizeof(in), key, iv) != 0) if ( wc_Des_CbcEncryptWithKey(&out, in, sizeof(in), key, iv) != 0)
{ {
// error encrypting message // error encrypting message
} }
\endcode \endcode
\sa wc_Des_CbcDecryptWithKey \sa wc_Des_CbcDecryptWithKey
\sa wc_Des_CbcEncrypt \sa wc_Des_CbcEncrypt
*/ */
@ -129,24 +129,24 @@ WOLFSSL_API int wc_Des_CbcEncryptWithKey(byte* out,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function encrypts the input plaintext, in, and stores \brief This function encrypts the input plaintext, in, and stores
the resulting ciphertext in the output buffer, out. It uses Triple the resulting ciphertext in the output buffer, out. It uses Triple
DES (3DES) encryption with cipher block chaining (CBC) mode. This DES (3DES) encryption with cipher block chaining (CBC) mode. This
function is a substitute for wc_Des3_CbcEncrypt, allowing the user function is a substitute for wc_Des3_CbcEncrypt, allowing the user
to encrypt a message without directly instantiating a Des3 structure. to encrypt a message without directly instantiating a Des3 structure.
\return 0 Returned after successfully encrypting data. \return 0 Returned after successfully encrypting data.
\return MEMORY_E Returned if there's an error allocating memory for \return MEMORY_E Returned if there's an error allocating memory for
a Des structure. a Des structure.
\return <0 Returned on any error during encryption. \return <0 Returned on any error during encryption.
\parma out Final encrypted data \parma out Final encrypted data
\param in Data to be encrypted, must be padded to Des block size. \param in Data to be encrypted, must be padded to Des block size.
\param sz Size of input buffer. \param sz Size of input buffer.
\param key Pointer to the key to use for encryption. \param key Pointer to the key to use for encryption.
\param iv Initialization vector \param iv Initialization vector
_Example_ _Example_
\code \code
byte key[] = { // initialize with 8 byte key }; byte key[] = { // initialize with 8 byte key };
@ -156,11 +156,11 @@ WOLFSSL_API int wc_Des_CbcEncryptWithKey(byte* out,
byte out[sizeof(in)]; byte out[sizeof(in)];
if ( wc_Des3_CbcEncryptWithKey(&out, in, sizeof(in), key, iv) != 0) if ( wc_Des3_CbcEncryptWithKey(&out, in, sizeof(in), key, iv) != 0)
{ {
// error encrypting message // error encrypting message
} }
\endcode \endcode
\sa wc_Des3_CbcDecryptWithKey \sa wc_Des3_CbcDecryptWithKey
\sa wc_Des_CbcEncryptWithKey \sa wc_Des_CbcEncryptWithKey
\sa wc_Des_CbcDecryptWithKey \sa wc_Des_CbcDecryptWithKey
@ -171,25 +171,25 @@ WOLFSSL_API int wc_Des3_CbcEncryptWithKey(byte* out,
/*! /*!
\ingroup 3DES \ingroup 3DES
\brief This function decrypts the input ciphertext, in, and stores \brief This function decrypts the input ciphertext, in, and stores
the resulting plaintext in the output buffer, out. It uses Triple the resulting plaintext in the output buffer, out. It uses Triple
Des (3DES) encryption with cipher block chaining (CBC) mode. This Des (3DES) encryption with cipher block chaining (CBC) mode. This
function is a substitute for wc_Des3_CbcDecrypt, allowing the user function is a substitute for wc_Des3_CbcDecrypt, allowing the user
to decrypt a message without directly instantiating a Des3 structure. to decrypt a message without directly instantiating a Des3 structure.
\return 0 Returned upon successfully decrypting the given ciphertext \return 0 Returned upon successfully decrypting the given ciphertext
\return MEMORY_E Returned if there is an error allocating space for \return MEMORY_E Returned if there is an error allocating space for
a Des structure a Des structure
\param out pointer to the buffer in which to store the decrypted plaintext \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 in pointer to the input buffer containing the encrypted ciphertext
\param sz length of the ciphertext to decrypt \param sz length of the ciphertext to decrypt
\param key pointer to the buffer containing the 24 byte key to use \param key pointer to the buffer containing the 24 byte key to use
for decryption for decryption
\param iv pointer to the buffer containing the 8 byte iv to use for \param iv pointer to the buffer containing the 8 byte iv to use for
decryption. If no iv is provided, the iv defaults to 0 decryption. If no iv is provided, the iv defaults to 0
_Example_ _Example_
\code \code
int ret; int ret;
@ -199,12 +199,12 @@ WOLFSSL_API int wc_Des3_CbcEncryptWithKey(byte* out,
byte cipher[] = { // initialize with ciphertext }; byte cipher[] = { // initialize with ciphertext };
byte decoded[sizeof(cipher)]; byte decoded[sizeof(cipher)];
if ( wc_Des3_CbcDecryptWithKey(decoded, cipher, sizeof(cipher), if ( wc_Des3_CbcDecryptWithKey(decoded, cipher, sizeof(cipher),
key, iv) != 0) { key, iv) != 0) {
// error decrypting message // error decrypting message
} }
\endcode \endcode
\sa wc_Des3_CbcDecrypt \sa wc_Des3_CbcDecrypt
*/ */
WOLFSSL_API int wc_Des3_CbcDecryptWithKey(byte* out, WOLFSSL_API int wc_Des3_CbcDecryptWithKey(byte* out,

20
doc/dox_comments/header_files/wc_port.h
View File

@ -1,13 +1,13 @@
/*! /*!
\ingroup wolfCrypt \ingroup wolfCrypt
\brief Used to initialize resources used by wolfCrypt. \brief Used to initialize resources used by wolfCrypt.
\return 0 upon success. \return 0 upon success.
\return <0 upon failure of init resources. \return <0 upon failure of init resources.
\param none No parameters. \param none No parameters.
_Example_ _Example_
\code \code
... ...
@ -15,21 +15,21 @@
WOLFSSL_MSG("Error with wolfCrypt_Init call"); WOLFSSL_MSG("Error with wolfCrypt_Init call");
} }
\endcode \endcode
\sa wolfCrypt_Cleanup \sa wolfCrypt_Cleanup
*/ */
WOLFSSL_API int wolfCrypt_Init(void); WOLFSSL_API int wolfCrypt_Init(void);
/*! /*!
\ingroup wolfCrypt \ingroup wolfCrypt
\brief Used to clean up resources used by wolfCrypt. \brief Used to clean up resources used by wolfCrypt.
\return 0 upon success. \return 0 upon success.
\return <0 upon failure of cleaning up resources. \return <0 upon failure of cleaning up resources.
\param none No parameters. \param none No parameters.
_Example_ _Example_
\code \code
... ...
@ -37,7 +37,7 @@ WOLFSSL_API int wolfCrypt_Init(void);
WOLFSSL_MSG("Error with wolfCrypt_Cleanup call"); WOLFSSL_MSG("Error with wolfCrypt_Cleanup call");
} }
\endcode \endcode
\sa wolfCrypt_Init \sa wolfCrypt_Init
*/ */
WOLFSSL_API int wolfCrypt_Cleanup(void); WOLFSSL_API int wolfCrypt_Cleanup(void);

306
doc/dox_comments/header_files/wolfio.h
View File

@ -1,27 +1,27 @@
/*! /*!
\brief This function is the receive embedded callback. \brief This function is the receive embedded callback.
\return Success This function returns the number of bytes read. \return Success This function returns the number of bytes read.
\return WOLFSSL_CBIO_ERR_WANT_READ returned with a “Would block” message \return WOLFSSL_CBIO_ERR_WANT_READ returned with a “Would block” message
if the last error was SOCKET_EWOULDBLCOK or SOCKET_EAGAIN. 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_TIMEOUT returned with a “Socket timeout” message.
\return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset” \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset”
message if the last error was SOCKET_ECONNRESET. message if the last error was SOCKET_ECONNRESET.
\return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message
if the last error was SOCKET_EINTR. if the last error was SOCKET_EINTR.
\return WOLFSSL_CBIO_ERR_WANT_READ returned with a “Connection refused” \return WOLFSSL_CBIO_ERR_WANT_READ returned with a “Connection refused”
messag if the last error was SOCKET_ECONNREFUSED. messag if the last error was SOCKET_ECONNREFUSED.
\return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Connection aborted” \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Connection aborted”
message if the last error was SOCKET_ECONNABORTED. message if the last error was SOCKET_ECONNABORTED.
\return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message
if the last error was not specified. if the last error was not specified.
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
\param buf a char pointer representation of the buffer. \param buf a char pointer representation of the buffer.
\param sz the size of the buffer. \param sz the size of the buffer.
\param ctx a void pointer to user registered context. In the default case \param ctx a void pointer to user registered context. In the default case
the ctx is a socket descriptor pointer. the ctx is a socket descriptor pointer.
_Example_ _Example_
\code \code
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
@ -34,7 +34,7 @@
// There were no bytes read. Failure case. // There were no bytes read. Failure case.
} }
\endcode \endcode
\sa wolfSSL_dtls_get_current_timeout \sa wolfSSL_dtls_get_current_timeout
\sa TranslateReturnCode \sa TranslateReturnCode
\sa RECV_FUNCTION \sa RECV_FUNCTION
@ -43,36 +43,36 @@ WOLFSSL_API int EmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx);
/*! /*!
\brief This function is the send embedded callback. \brief This function is the send embedded callback.
\return Success This function returns the number of bytes sent. \return Success This function returns the number of bytes sent.
\return WOLFSSL_CBIO_ERR_WANT_WRITE returned with a “Would block” message \return WOLFSSL_CBIO_ERR_WANT_WRITE returned with a “Would block” message
if the last error was SOCKET_EWOULDBLOCK or SOCKET_EAGAIN. if the last error was SOCKET_EWOULDBLOCK or SOCKET_EAGAIN.
\return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset” \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset”
message if the last error was SOCKET_ECONNRESET. message if the last error was SOCKET_ECONNRESET.
\return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message
if the last error was SOCKET_EINTR. if the last error was SOCKET_EINTR.
\return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Socket EPIPE” message \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Socket EPIPE” message
if the last error was SOCKET_EPIPE. if the last error was SOCKET_EPIPE.
\return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message
if the last error was not specified. if the last error was not specified.
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
\param buf a char pointer representing the buffer. \param buf a char pointer representing the buffer.
\param sz the size of the buffer. \param sz the size of the buffer.
\param ctx a void pointer to user registered context. \param ctx a void pointer to user registered context.
_Example_ _Example_
\code \code
WOLFSSL* ssl = wolfSSL_new(ctx); WOLFSSL* ssl = wolfSSL_new(ctx);
char* buf; char* buf;
int sz; int sz;
void* ctx; void* ctx;
int dSent = EmbedSend(ssl, buf, sz, ctx); int dSent = EmbedSend(ssl, buf, sz, ctx);
if(dSent <= 0){ if(dSent <= 0){
// No byes sent. Failure case. // No byes sent. Failure case.
} }
\endcode \endcode
\sa TranslateReturnCode \sa TranslateReturnCode
\sa SEND_FUNCTION \sa SEND_FUNCTION
\sa LastError \sa LastError
@ -83,21 +83,21 @@ WOLFSSL_API int EmbedSend(WOLFSSL* ssl, char* buf, int sz, void* ctx);
/*! /*!
\brief This function is the receive embedded callback. \brief This function is the receive embedded callback.
\return Success This function returns the nb bytes read if the execution \return Success This function returns the nb bytes read if the execution
was successful. was successful.
\return WOLFSSL_CBIO_ERR_WANT_READ if the connection refused or if a \return WOLFSSL_CBIO_ERR_WANT_READ if the connection refused or if a
‘would block’ error was thrown in the function. ‘would block’ error was thrown in the function.
\return WOLFSSL_CBIO_ERR_TIMEOUT returned if the socket timed out. \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_CONN_RST returned if the connection reset.
\return WOLFSSL_CBIO_ERR_ISR returned if the socket was interrupted. \return WOLFSSL_CBIO_ERR_ISR returned if the socket was interrupted.
\return WOLFSSL_CBIO_ERR_GENERAL returned if there was a general error. \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 ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
\param buf a constant char pointer to the buffer. \param buf a constant char pointer to the buffer.
\param sz an int type representing the size of the buffer. \param sz an int type representing the size of the buffer.
\param ctx a void pointer to the WOLFSSL_CTX context. \param ctx a void pointer to the WOLFSSL_CTX context.
_Example_ _Example_
\code \code
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method ); WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
@ -111,7 +111,7 @@ WOLFSSL_API int EmbedSend(WOLFSSL* ssl, char* buf, int sz, void* ctx);
// nb is the number of bytes written and is positive // nb is the number of bytes written and is positive
} }
\endcode \endcode
\sa TranslateReturnCode \sa TranslateReturnCode
\sa RECVFROM_FUNCTION \sa RECVFROM_FUNCTION
\sa Setsockopt \sa Setsockopt
@ -120,25 +120,25 @@ WOLFSSL_API int EmbedReceiveFrom(WOLFSSL* ssl, char* buf, int sz, void*);
/*! /*!
\brief This function is the send embedded callback. \brief This function is the send embedded callback.
\return Success This function returns the number of bytes sent. \return Success This function returns the number of bytes sent.
\return WOLFSSL_CBIO_ERR_WANT_WRITE returned with a “Would Block” message \return WOLFSSL_CBIO_ERR_WANT_WRITE returned with a “Would Block” message
if the last error was either SOCKET_EWOULDBLOCK or SOCKET_EAGAIN error. if the last error was either SOCKET_EWOULDBLOCK or SOCKET_EAGAIN error.
\return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset” \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset”
message if the last error was SOCKET_ECONNRESET. message if the last error was SOCKET_ECONNRESET.
\return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message
if the last error was SOCKET_EINTR. if the last error was SOCKET_EINTR.
\return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Socket EPIPE” message \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Socket EPIPE” message
if the last error was WOLFSSL_CBIO_ERR_CONN_CLOSE. if the last error was WOLFSSL_CBIO_ERR_CONN_CLOSE.
\return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message
if the last error was not specified. if the last error was not specified.
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
\param buf a char pointer representing the buffer. \param buf a char pointer representing the buffer.
\param sz the size of the buffer. \param sz the size of the buffer.
\param ctx a void pointer to the user registered context. The default case \param ctx a void pointer to the user registered context. The default case
is a WOLFSSL_DTLS_CTX sructure. is a WOLFSSL_DTLS_CTX sructure.
_Example_ _Example_
\code \code
WOLFSSL* ssl; WOLFSSL* ssl;
@ -152,7 +152,7 @@ WOLFSSL_API int EmbedReceiveFrom(WOLFSSL* ssl, char* buf, int sz, void*);
// No bytes sent. Failure case. // No bytes sent. Failure case.
} }
\endcode \endcode
\sa LastError \sa LastError
\sa EmbedSend \sa EmbedSend
\sa EmbedReceive \sa EmbedReceive
@ -161,18 +161,18 @@ WOLFSSL_API int EmbedSendTo(WOLFSSL* ssl, char* buf, int sz, void* ctx);
/*! /*!
\brief This function is the DTLS Generate Cookie callback. \brief This function is the DTLS Generate Cookie callback.
\return Success This function returns the number of bytes copied \return Success This function returns the number of bytes copied
into the buffer. into the buffer.
\return GEN_COOKIE_E returned if the getpeername failed in \return GEN_COOKIE_E returned if the getpeername failed in
EmbedGenerateCookie. EmbedGenerateCookie.
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
\param buf byte pointer representing the buffer. It is the destination \param buf byte pointer representing the buffer. It is the destination
from XMEMCPY(). from XMEMCPY().
\param sz the size of the buffer. \param sz the size of the buffer.
\param ctx a void pointer to user registered context. \param ctx a void pointer to user registered context.
_Example_ _Example_
\code \code
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
@ -187,7 +187,7 @@ WOLFSSL_API int EmbedSendTo(WOLFSSL* ssl, char* buf, int sz, void* ctx);
// EmbedGenerateCookie code block for success // EmbedGenerateCookie code block for success
} }
\endcode \endcode
\sa wc_ShaHash \sa wc_ShaHash
\sa EmbedGenerateCookie \sa EmbedGenerateCookie
\sa XMEMCPY \sa XMEMCPY
@ -198,12 +198,12 @@ WOLFSSL_API int EmbedGenerateCookie(WOLFSSL* ssl, unsigned char* buf,
/*! /*!
\brief This function frees the response buffer. \brief This function frees the response buffer.
\return none No returns. \return none No returns.
\param ctx a void pointer to heap hint. \param ctx a void pointer to heap hint.
\param resp a byte pointer representing the response. \param resp a byte pointer representing the response.
_Example_ _Example_
\code \code
void* ctx; void* ctx;
@ -211,27 +211,27 @@ WOLFSSL_API int EmbedGenerateCookie(WOLFSSL* ssl, unsigned char* buf,
… …
EmbedOcspRespFree(ctx, resp); EmbedOcspRespFree(ctx, resp);
\endcode \endcode
\sa XFREE \sa XFREE
*/ */
WOLFSSL_API void EmbedOcspRespFree(void*, unsigned char*); WOLFSSL_API void EmbedOcspRespFree(void*, unsigned char*);
/*! /*!
\brief This function registers a receive callback for wolfSSL to get input \brief This function registers a receive callback for wolfSSL to get input
data. By default, wolfSSL uses EmbedReceive() as the callback which uses 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 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 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 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 should work and for error codes. In particular, IO_ERR_WANT_READ should
be returned for non blocking receive when no data is ready. be returned for non blocking receive when no data is ready.
\return none no Returns. \return none no Returns.
\param ctx pointer to the SSL context, created with wolfSSL_CTX_new(). \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
\param callback function to be registered as the receive callback for the \param callback function to be registered as the receive callback for the
wolfSSL context, ctx. The signature of this function must follow that as wolfSSL context, ctx. The signature of this function must follow that as
shown above in the Synopsis section. shown above in the Synopsis section.
_Example_ _Example_
\code \code
WOLFSSL_CTX* ctx = 0; WOLFSSL_CTX* ctx = 0;
@ -239,12 +239,12 @@ WOLFSSL_API void EmbedOcspRespFree(void*, unsigned char*);
int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx); int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx);
// Register the custom receive callback with wolfSSL // Register the custom receive callback with wolfSSL
wolfSSL_CTX_SetIORecv(ctx, MyEmbedReceive); wolfSSL_CTX_SetIORecv(ctx, MyEmbedReceive);
int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx) int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx)
{ {
// custom EmbedReceive function // custom EmbedReceive function
} }
\endcode \endcode
\sa wolfSSL_CTX_SetIOSend \sa wolfSSL_CTX_SetIOSend
\sa wolfSSL_SetIOReadCtx \sa wolfSSL_SetIOReadCtx
\sa wolfSSL_SetIOWriteCtx \sa wolfSSL_SetIOWriteCtx
@ -252,20 +252,20 @@ WOLFSSL_API void EmbedOcspRespFree(void*, unsigned char*);
WOLFSSL_API void wolfSSL_CTX_SetIORecv(WOLFSSL_CTX*, CallbackIORecv); WOLFSSL_API void wolfSSL_CTX_SetIORecv(WOLFSSL_CTX*, CallbackIORecv);
/*! /*!
\brief This function registers a context for the SSL session’s receive \brief This function registers a context for the SSL session’s receive
callback function. By default, wolfSSL sets the file descriptor passed to 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 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 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 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 buffers the context may be a pointer to a structure describing where and
how to access the memory buffers. how to access the memory buffers.
\return none No returns. \return none No returns.
\param ssl pointer to the SSL session, created with wolfSSL_new(). \param ssl pointer to the SSL session, created with wolfSSL_new().
\param rctx pointer to the context to be registered with the SSL session’s \param rctx pointer to the context to be registered with the SSL session’s
(ssl) receive callback function. (ssl) receive callback function.
_Example_ _Example_
\code \code
int sockfd; int sockfd;
@ -275,7 +275,7 @@ WOLFSSL_API void wolfSSL_CTX_SetIORecv(WOLFSSL_CTX*, CallbackIORecv);
wolfSSL_SetIOReadCtx(ssl, &sockfd); wolfSSL_SetIOReadCtx(ssl, &sockfd);
... ...
\endcode \endcode
\sa wolfSSL_CTX_SetIORecv \sa wolfSSL_CTX_SetIORecv
\sa wolfSSL_CTX_SetIOSend \sa wolfSSL_CTX_SetIOSend
\sa wolfSSL_SetIOWriteCtx \sa wolfSSL_SetIOWriteCtx
@ -283,20 +283,20 @@ WOLFSSL_API void wolfSSL_CTX_SetIORecv(WOLFSSL_CTX*, CallbackIORecv);
WOLFSSL_API void wolfSSL_SetIOReadCtx( WOLFSSL* ssl, void *ctx); WOLFSSL_API void wolfSSL_SetIOReadCtx( WOLFSSL* ssl, void *ctx);
/*! /*!
\brief This function registers a context for the SSL session’s send \brief This function registers a context for the SSL session’s send
callback function. By default, wolfSSL sets the file descriptor passed to 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 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 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 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 buffers the context may be a pointer to a structure describing where and
how to access the memory buffers. how to access the memory buffers.
\return none No returns. \return none No returns.
\param ssl pointer to the SSL session, created with wolfSSL_new(). \param ssl pointer to the SSL session, created with wolfSSL_new().
\param wctx pointer to the context to be registered with the SSL session’s \param wctx pointer to the context to be registered with the SSL session’s
(ssl) send callback function. (ssl) send callback function.
_Example_ _Example_
\code \code
int sockfd; int sockfd;
@ -306,7 +306,7 @@ WOLFSSL_API void wolfSSL_SetIOReadCtx( WOLFSSL* ssl, void *ctx);
wolfSSL_SetIOWriteCtx(ssl, &sockfd); wolfSSL_SetIOWriteCtx(ssl, &sockfd);
... ...
\endcode \endcode
\sa wolfSSL_CTX_SetIORecv \sa wolfSSL_CTX_SetIORecv
\sa wolfSSL_CTX_SetIOSend \sa wolfSSL_CTX_SetIOSend
\sa wolfSSL_SetIOReadCtx \sa wolfSSL_SetIOReadCtx
@ -317,13 +317,13 @@ WOLFSSL_API void wolfSSL_SetIOWriteCtx(WOLFSSL* ssl, void *ctx);
\ingroup IO \ingroup IO
\brief This function returns the IOCB_ReadCtx member of the WOLFSSL struct. \brief This function returns the IOCB_ReadCtx member of the WOLFSSL struct.
\return pointer This function returns a void pointer to the IOCB_ReadCtx \return pointer This function returns a void pointer to the IOCB_ReadCtx
member of the WOLFSSL structure. member of the WOLFSSL structure.
\return NULL returned if the WOLFSSL struct is NULL. \return NULL returned if the WOLFSSL struct is NULL.
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
_Example_ _Example_
\code \code
WOLFSSL* ssl = wolfSSL_new(ctx); WOLFSSL* ssl = wolfSSL_new(ctx);
@ -334,7 +334,7 @@ WOLFSSL_API void wolfSSL_SetIOWriteCtx(WOLFSSL* ssl, void *ctx);
// Failure case. The ssl object was NULL. // Failure case. The ssl object was NULL.
} }
\endcode \endcode
\sa wolfSSL_GetIOWriteCtx \sa wolfSSL_GetIOWriteCtx
\sa wolfSSL_SetIOReadFlags \sa wolfSSL_SetIOReadFlags
\sa wolfSSL_SetIOWriteCtx \sa wolfSSL_SetIOWriteCtx
@ -347,13 +347,13 @@ WOLFSSL_API void* wolfSSL_GetIOReadCtx( WOLFSSL* ssl);
\ingroup IO \ingroup IO
\brief This function returns the IOCB_WriteCtx member of the WOLFSSL structure. \brief This function returns the IOCB_WriteCtx member of the WOLFSSL structure.
\return pointer This function returns a void pointer to the IOCB_WriteCtx \return pointer This function returns a void pointer to the IOCB_WriteCtx
member of the WOLFSSL structure. member of the WOLFSSL structure.
\return NULL returned if the WOLFSSL struct is NULL. \return NULL returned if the WOLFSSL struct is NULL.
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
_Example_ _Example_
\code \code
WOLFSSL* ssl; WOLFSSL* ssl;
@ -364,7 +364,7 @@ WOLFSSL_API void* wolfSSL_GetIOReadCtx( WOLFSSL* ssl);
// The funciton returned NULL. // The funciton returned NULL.
} }
\endcode \endcode
\sa wolfSSL_GetIOReadCtx \sa wolfSSL_GetIOReadCtx
\sa wolfSSL_SetIOWriteCtx \sa wolfSSL_SetIOWriteCtx
\sa wolfSSL_SetIOReadCtx \sa wolfSSL_SetIOReadCtx
@ -373,32 +373,32 @@ WOLFSSL_API void* wolfSSL_GetIOReadCtx( WOLFSSL* ssl);
WOLFSSL_API void* wolfSSL_GetIOWriteCtx(WOLFSSL* ssl); WOLFSSL_API void* wolfSSL_GetIOWriteCtx(WOLFSSL* ssl);
/*! /*!
\brief This function sets the flags for the receive callback to use for \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 the given SSL session. The receive callback could be either the default
wolfSSL EmbedReceive callback, or a custom callback specified by the user wolfSSL EmbedReceive callback, or a custom callback specified by the user
(see wolfSSL_CTX_SetIORecv). The default flag value is set internally by (see wolfSSL_CTX_SetIORecv). The default flag value is set internally by
wolfSSL to the value of 0. The default wolfSSL receive callback uses the 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: 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 “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 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 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 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 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 the normal data queue, and thus this flag cannot be used with such
protocols. The MSG_PEEK flag causes the receive operation to return protocols. The MSG_PEEK flag causes the receive operation to return
data from the beginning of the receive queue without removing that data 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. 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 The MSG_WAITALL flag requests that the operation block until the full
request is satisfied. However, the call may still return less data than 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 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.” data to be received is of a different type than that returned.”
\return none No returns. \return none No returns.
\param ssl pointer to the SSL session, created with wolfSSL_new(). \param ssl pointer to the SSL session, created with wolfSSL_new().
\param flags value of the I/O read flags for the specified SSL \param flags value of the I/O read flags for the specified SSL
session (ssl). session (ssl).
_Example_ _Example_
\code \code
WOLFSSL* ssl = 0; WOLFSSL* ssl = 0;
@ -407,7 +407,7 @@ WOLFSSL_API void* wolfSSL_GetIOWriteCtx(WOLFSSL* ssl);
wolfSSL_SetIOReadFlags(ssl, 0); wolfSSL_SetIOReadFlags(ssl, 0);
... ...
\endcode \endcode
\sa wolfSSL_CTX_SetIORecv \sa wolfSSL_CTX_SetIORecv
\sa wolfSSL_CTX_SetIOSend \sa wolfSSL_CTX_SetIOSend
\sa wolfSSL_SetIOReadCtx \sa wolfSSL_SetIOReadCtx
@ -415,25 +415,25 @@ WOLFSSL_API void* wolfSSL_GetIOWriteCtx(WOLFSSL* ssl);
WOLFSSL_API void wolfSSL_SetIOReadFlags( WOLFSSL* ssl, int flags); WOLFSSL_API void wolfSSL_SetIOReadFlags( WOLFSSL* ssl, int flags);
/*! /*!
\brief This function sets the flags for the send callback to use for the \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 given SSL session. The send callback could be either the default wolfSSL
EmbedSend callback, or a custom callback specified by the user (see EmbedSend callback, or a custom callback specified by the user (see
wolfSSL_CTX_SetIOSend). The default flag value is set internally by wolfSSL wolfSSL_CTX_SetIOSend). The default flag value is set internally by wolfSSL
to the value of 0. The default wolfSSL send callback uses the send() 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 function to send data from the socket. From the send() man page: “The
flags parameter may include one or more of the following: flags parameter may include one or more of the following:
#define MSG_OOB 0x1 // process out-of-band data, #define MSG_OOB 0x1 // process out-of-band data,
#define MSG_DONTROUTE 0x4 // bypass routing, use direct interface. #define MSG_DONTROUTE 0x4 // bypass routing, use direct interface.
The flag MSG_OOB is used to send ``out-of-band'' data on sockets that 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 this notion (e.g. SOCK_STREAM); the underlying protocol must also
support ``out-of-band'' data. MSG_DONTROUTE is usually used only by support ``out-of-band'' data. MSG_DONTROUTE is usually used only by
diagnostic or routing programs.” diagnostic or routing programs.”
\return none No returns. \return none No returns.
\param ssl pointer to the SSL session, created with wolfSSL_new(). \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). \param flags value of the I/O send flags for the specified SSL session (ssl).
_Example_ _Example_
\code \code
WOLFSSL* ssl = 0; WOLFSSL* ssl = 0;
@ -442,7 +442,7 @@ WOLFSSL_API void wolfSSL_SetIOReadFlags( WOLFSSL* ssl, int flags);
wolfSSL_SetIOWriteFlags(ssl, 0); wolfSSL_SetIOWriteFlags(ssl, 0);
... ...
\endcode \endcode
\sa wolfSSL_CTX_SetIORecv \sa wolfSSL_CTX_SetIORecv
\sa wolfSSL_CTX_SetIOSend \sa wolfSSL_CTX_SetIOSend
\sa wolfSSL_SetIOReadCtx \sa wolfSSL_SetIOReadCtx
@ -452,30 +452,30 @@ WOLFSSL_API void wolfSSL_SetIOWriteFlags(WOLFSSL* ssl, int flags);
/*! /*!
\ingroup IO \ingroup IO
\brief This function sets the nxSocket and nxWait members of the nxCtx \brief This function sets the nxSocket and nxWait members of the nxCtx
struct within the WOLFSSL structure. struct within the WOLFSSL structure.
\return none No returns. \return none No returns.
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
\param nxSocket a pointer to type NX_TCP_SOCKET that is set to the \param nxSocket a pointer to type NX_TCP_SOCKET that is set to the
nxSocket member of the nxCTX structure. nxSocket member of the nxCTX structure.
\param waitOption a ULONG type that is set to the nxWait member of \param waitOption a ULONG type that is set to the nxWait member of
the nxCtx structure. the nxCtx structure.
_Example_ _Example_
\code \code
WOLFSSL* ssl = wolfSSL_new(ctx); WOLFSSL* ssl = wolfSSL_new(ctx);
NX_TCP_SOCKET* nxSocket; NX_TCP_SOCKET* nxSocket;
ULONG waitOption; ULONG waitOption;
… …
if(ssl != NULL || nxSocket != NULL || waitOption <= 0){ if(ssl != NULL || nxSocket != NULL || waitOption <= 0){
wolfSSL_SetIO_NetX(ssl, nxSocket, waitOption); wolfSSL_SetIO_NetX(ssl, nxSocket, waitOption);
} else { } else {
// You need to pass in good parameters. // You need to pass in good parameters.
} }
\endcode \endcode
\sa set_fd \sa set_fd
\sa NetX_Send \sa NetX_Send
\sa NetX_Receive \sa NetX_Receive
@ -484,17 +484,17 @@ WOLFSSL_API void wolfSSL_SetIO_NetX(WOLFSSL* ssl, NX_TCP_SOCKET* nxsocket,
ULONG waitoption); ULONG waitoption);
/*! /*!
\brief This function sets the callback for the CBIOCookie member of the \brief This function sets the callback for the CBIOCookie member of the
WOLFSSL_CTX structure. The CallbackGenCookie type is a function pointer WOLFSSL_CTX structure. The CallbackGenCookie type is a function pointer
and has the signature: int (*CallbackGenCookie)(WOLFSSL* ssl, unsigned and has the signature: int (*CallbackGenCookie)(WOLFSSL* ssl, unsigned
char* buf, int sz, void* ctx); char* buf, int sz, void* ctx);
\return none No returns. \return none No returns.
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
\param cb a CallbackGenCookie type function pointer with the signature \param cb a CallbackGenCookie type function pointer with the signature
of CallbackGenCookie. of CallbackGenCookie.
_Example_ _Example_
\code \code
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
@ -506,7 +506,7 @@ WOLFSSL_API void wolfSSL_SetIO_NetX(WOLFSSL* ssl, NX_TCP_SOCKET* nxsocket,
… …
wolfSSL_CTX_SetGenCookie(ssl->ctx, SetGenCookieCB); wolfSSL_CTX_SetGenCookie(ssl->ctx, SetGenCookieCB);
\endcode \endcode
\sa CallbackGenCookie \sa CallbackGenCookie
*/ */
WOLFSSL_API void wolfSSL_CTX_SetGenCookie(WOLFSSL_CTX*, CallbackGenCookie); WOLFSSL_API void wolfSSL_CTX_SetGenCookie(WOLFSSL_CTX*, CallbackGenCookie);
@ -514,15 +514,15 @@ WOLFSSL_API void wolfSSL_CTX_SetGenCookie(WOLFSSL_CTX*, CallbackGenCookie);
/*! /*!
\ingroup Setup \ingroup Setup
\brief This function returns the IOCB_CookieCtx member of the \brief This function returns the IOCB_CookieCtx member of the
WOLFSSL structure. WOLFSSL structure.
\return pointer The function returns a void pointer value stored in \return pointer The function returns a void pointer value stored in
the IOCB_CookieCtx. the IOCB_CookieCtx.
\return NULL if the WOLFSSL struct is NULL \return NULL if the WOLFSSL struct is NULL
\param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new(). \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
_Example_ _Example_
\code \code
WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method ); WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
@ -534,7 +534,7 @@ WOLFSSL_API void wolfSSL_CTX_SetGenCookie(WOLFSSL_CTX*, CallbackGenCookie);
// You have the cookie // You have the cookie
} }
\endcode \endcode
\sa wolfSSL_SetCookieCtx \sa wolfSSL_SetCookieCtx
\sa wolfSSL_CTX_SetGenCookie \sa wolfSSL_CTX_SetGenCookie
*/ */

6
doc/formats/html/Doxyfile
View File

@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8
# title of most generated pages and in a few other places. # title of most generated pages and in a few other places.
# The default value is: My Project. # The default value is: My Project.
PROJECT_NAME = PROJECT_NAME =
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This # 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 # could be handy for archiving the generated documentation or if some version
@ -51,7 +51,7 @@ PROJECT_BRIEF =
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory. # the logo to the output directory.
PROJECT_LOGO = PROJECT_LOGO =
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # 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 # into which the generated documentation will be written. If a relative path is
@ -1653,7 +1653,7 @@ GENERATE_LATEX = NO
# The default directory is: latex. # The default directory is: latex.
# This tag requires that the tag GENERATE_LATEX is set to YES. # This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_OUTPUT = LATEX_OUTPUT =
# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
# invoked. # invoked.

54
doc/formats/html/html_changes/customdoxygen.css
View File

@ -247,11 +247,11 @@ a.elRef {
} }
a.code, a.code:visited, a.line, a.line:visited { a.code, a.code:visited, a.line, a.line:visited {
color: #c46715; color: #c46715;
} }
a.codeRef, a.codeRef:visited, a.lineRef, a.lineRef:visited { a.codeRef, a.codeRef:visited, a.lineRef, a.lineRef:visited {
color: #c46715; color: #c46715;
} }
/* @end */ /* @end */
@ -521,20 +521,20 @@ span.charliteral {
color: #008080 color: #008080
} }
span.vhdldigit { span.vhdldigit {
color: #ff00ff color: #ff00ff
} }
span.vhdlchar { span.vhdlchar {
color: #000000 color: #000000
} }
span.vhdlkeyword { span.vhdlkeyword {
color: #700070 color: #700070
} }
span.vhdllogic { span.vhdllogic {
color: #ff0000 color: #ff0000
} }
blockquote { blockquote {
@ -752,9 +752,9 @@ table.memberdecls {
} }
.memdoc, dl.reflist dd { .memdoc, dl.reflist dd {
border-bottom: 1px solid #A8B8D9; border-bottom: 1px solid #A8B8D9;
border-left: 1px solid #A8B8D9; border-left: 1px solid #A8B8D9;
border-right: 1px solid #A8B8D9; border-right: 1px solid #A8B8D9;
padding: 6px 10px 2px 10px; padding: 6px 10px 2px 10px;
background-color: #FBFCFD; background-color: #FBFCFD;
border-top-width: 0; border-top-width: 0;
@ -806,18 +806,18 @@ dl.reflist dd {
.params, .retval, .exception, .tparams { .params, .retval, .exception, .tparams {
margin-left: 0px; margin-left: 0px;
padding-left: 0px; padding-left: 0px;
} }
.params .paramname, .retval .paramname { .params .paramname, .retval .paramname {
font-weight: bold; font-weight: bold;
vertical-align: top; vertical-align: top;
} }
.params .paramtype { .params .paramtype {
font-style: italic; font-style: italic;
vertical-align: top; vertical-align: top;
} }
.params .paramdir { .params .paramdir {
font-family: "courier new",courier,monospace; font-family: "courier new",courier,monospace;
vertical-align: top; vertical-align: top;
@ -1073,8 +1073,8 @@ table.fieldtable {
.fieldtable td.fielddoc p:first-child { .fieldtable td.fielddoc p:first-child {
margin-top: 0px; margin-top: 0px;
} }
.fieldtable td.fielddoc p:last-child { .fieldtable td.fielddoc p:last-child {
margin-bottom: 2px; margin-bottom: 2px;
} }
@ -1149,7 +1149,7 @@ table.fieldtable {
color: #283A5D; color: #283A5D;
font-family: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; font-family: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif;
text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9);
text-decoration: none; text-decoration: none;
} }
.navpath li.navelem a:hover .navpath li.navelem a:hover
@ -1178,7 +1178,7 @@ div.summary
padding-right: 5px; padding-right: 5px;
width: 50%; width: 50%;
text-align: right; text-align: right;
} }
div.summary a div.summary a
{ {
@ -1193,7 +1193,7 @@ table.classindex
margin-right: 3%; margin-right: 3%;
width: 94%; width: 94%;
border: 0; border: 0;
border-spacing: 0; border-spacing: 0;
padding: 0; padding: 0;
} }
@ -1302,12 +1302,12 @@ dl.section dd {
vertical-align: bottom; vertical-align: bottom;
border-collapse: separate; border-collapse: separate;
} }
#projectlogo img #projectlogo img
{ {
border: 0px none; border: 0px none;
} }
#projectalign #projectalign
{ {
vertical-align: middle; vertical-align: middle;
@ -1319,7 +1319,7 @@ dl.section dd {
margin: 0px; margin: 0px;
padding: 2px 0px; padding: 2px 0px;
} }
#projectbrief #projectbrief
{ {
font: 120% Tahoma, Arial,sans-serif; font: 120% Tahoma, Arial,sans-serif;
@ -1424,7 +1424,7 @@ div.toc ul {
list-style: none outside none; list-style: none outside none;
border: medium none; border: medium none;
padding: 0px; padding: 0px;
} }
div.toc li.level1 { div.toc li.level1 {
margin-left: 0px; margin-left: 0px;

54
doc/formats/html/html_changes/doxygen.css
View File

@ -150,11 +150,11 @@ a.elRef {
} }
a.code, a.code:visited, a.line, a.line:visited { a.code, a.code:visited, a.line, a.line:visited {
color: #4665A2; color: #4665A2;
} }
a.codeRef, a.codeRef:visited, a.lineRef, a.lineRef:visited { a.codeRef, a.codeRef:visited, a.lineRef, a.lineRef:visited {
color: #4665A2; color: #4665A2;
} }
/* @end */ /* @end */
@ -379,20 +379,20 @@ span.charliteral {
color: #008080 color: #008080
} }
span.vhdldigit { span.vhdldigit {
color: #ff00ff color: #ff00ff
} }
span.vhdlchar { span.vhdlchar {
color: #000000 color: #000000
} }
span.vhdlkeyword { span.vhdlkeyword {
color: #700070 color: #700070
} }
span.vhdllogic { span.vhdllogic {
color: #ff0000 color: #ff0000
} }
blockquote { blockquote {
@ -610,9 +610,9 @@ table.memberdecls {
} }
.memdoc, dl.reflist dd { .memdoc, dl.reflist dd {
border-bottom: 1px solid #A8B8D9; border-bottom: 1px solid #A8B8D9;
border-left: 1px solid #A8B8D9; border-left: 1px solid #A8B8D9;
border-right: 1px solid #A8B8D9; border-right: 1px solid #A8B8D9;
padding: 6px 10px 2px 10px; padding: 6px 10px 2px 10px;
background-color: #FBFCFD; background-color: #FBFCFD;
border-top-width: 0; border-top-width: 0;
@ -664,18 +664,18 @@ dl.reflist dd {
.params, .retval, .exception, .tparams { .params, .retval, .exception, .tparams {
margin-left: 0px; margin-left: 0px;
padding-left: 0px; padding-left: 0px;
} }
.params .paramname, .retval .paramname { .params .paramname, .retval .paramname {
font-weight: bold; font-weight: bold;
vertical-align: top; vertical-align: top;
} }
.params .paramtype { .params .paramtype {
font-style: italic; font-style: italic;
vertical-align: top; vertical-align: top;
} }
.params .paramdir { .params .paramdir {
font-family: "courier new",courier,monospace; font-family: "courier new",courier,monospace;
vertical-align: top; vertical-align: top;
@ -931,8 +931,8 @@ table.fieldtable {
.fieldtable td.fielddoc p:first-child { .fieldtable td.fielddoc p:first-child {
margin-top: 0px; margin-top: 0px;
} }
.fieldtable td.fielddoc p:last-child { .fieldtable td.fielddoc p:last-child {
margin-bottom: 2px; margin-bottom: 2px;
} }
@ -1007,7 +1007,7 @@ table.fieldtable {
color: #283A5D; color: #283A5D;
font-family: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; font-family: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif;
text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9);
text-decoration: none; text-decoration: none;
} }
.navpath li.navelem a:hover .navpath li.navelem a:hover
@ -1036,7 +1036,7 @@ div.summary
padding-right: 5px; padding-right: 5px;
width: 50%; width: 50%;
text-align: right; text-align: right;
} }
div.summary a div.summary a
{ {
@ -1051,7 +1051,7 @@ table.classindex
margin-right: 3%; margin-right: 3%;
width: 94%; width: 94%;
border: 0; border: 0;
border-spacing: 0; border-spacing: 0;
padding: 0; padding: 0;
} }
@ -1160,12 +1160,12 @@ dl.section dd {
vertical-align: bottom; vertical-align: bottom;
border-collapse: separate; border-collapse: separate;
} }
#projectlogo img #projectlogo img
{ {
border: 0px none; border: 0px none;
} }
#projectalign #projectalign
{ {
vertical-align: middle; vertical-align: middle;
@ -1177,7 +1177,7 @@ dl.section dd {
margin: 0px; margin: 0px;
padding: 2px 0px; padding: 2px 0px;
} }
#projectbrief #projectbrief
{ {
font: 120% Tahoma, Arial,sans-serif; font: 120% Tahoma, Arial,sans-serif;
@ -1282,7 +1282,7 @@ div.toc ul {
list-style: none outside none; list-style: none outside none;
border: medium none; border: medium none;
padding: 0px; padding: 0px;
} }
div.toc li.level1 { div.toc li.level1 {
margin-left: 0px; margin-left: 0px;

2
doc/formats/html/html_changes/menu.js
View File

@ -28,6 +28,6 @@ function initMenu(relPath,searchEnabled,serverSide,searchPage,search) {
$('#main-nav').append(makeTree(menudata,relPath)); $('#main-nav').append(makeTree(menudata,relPath));
$('#main-nav').children(':first').addClass('sm sm-dox').attr('id','main-menu'); $('#main-nav').children(':first').addClass('sm sm-dox').attr('id','main-menu');
$('#main-menu').smartmenus(); $('#main-menu').smartmenus();
} }

14
doc/formats/html/html_changes/search/search.css
View File

@ -1,4 +1,4 @@
/*---------------- Search Box */ /*---------------- Search Box */
#FSearchBox { #FSearchBox {
float: left; float: left;
} }
@ -128,7 +128,7 @@ span.SelectionMark {
a.SelectItem { a.SelectItem {
display: block; display: block;
outline-style: none; outline-style: none;
color: #000000; color: #000000;
text-decoration: none; text-decoration: none;
padding-left: 6px; padding-left: 6px;
padding-right: 12px; padding-right: 12px;
@ -136,7 +136,7 @@ a.SelectItem {
a.SelectItem:focus, a.SelectItem:focus,
a.SelectItem:active { a.SelectItem:active {
color: #000000; color: #000000;
outline-style: none; outline-style: none;
text-decoration: none; text-decoration: none;
} }
@ -170,7 +170,7 @@ iframe#MSearchResults {
#SRIndex { #SRIndex {
clear:both; clear:both;
padding-bottom: 15px; padding-bottom: 15px;
} }
@ -189,7 +189,7 @@ body.SRPage {
} }
.SRChildren { .SRChildren {
padding-left: 3ex; padding-bottom: .5em padding-left: 3ex; padding-bottom: .5em
} }
.SRPage .SRChildren { .SRPage .SRChildren {
@ -197,7 +197,7 @@ body.SRPage {
} }
.SRSymbol { .SRSymbol {
font-weight: bold; font-weight: bold;
color: #425E97; color: #425E97;
font-family: Arial, Verdana, sans-serif; font-family: Arial, Verdana, sans-serif;
text-decoration: none; text-decoration: none;
@ -206,7 +206,7 @@ body.SRPage {
a.SRScope { a.SRScope {
display: block; display: block;
color: #425E97; color: #425E97;
font-family: Arial, Verdana, sans-serif; font-family: Arial, Verdana, sans-serif;
text-decoration: none; text-decoration: none;
outline: none; outline: none;

10
doc/formats/pdf/Doxyfile
View File

@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8
# title of most generated pages and in a few other places. # title of most generated pages and in a few other places.
# The default value is: My Project. # The default value is: My Project.
PROJECT_NAME = PROJECT_NAME =
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This # 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 # could be handy for archiving the generated documentation or if some version
@ -51,7 +51,7 @@ PROJECT_BRIEF =
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory. # the logo to the output directory.
PROJECT_LOGO = PROJECT_LOGO =
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # 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 # into which the generated documentation will be written. If a relative path is
@ -1147,7 +1147,7 @@ HTML_FILE_EXTENSION = .html
# of the possible markers and block names see the documentation. # of the possible markers and block names see the documentation.
# This tag requires that the tag GENERATE_HTML is set to YES. # This tag requires that the tag GENERATE_HTML is set to YES.
HTML_HEADER = HTML_HEADER =
# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each # 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 # generated HTML page. If the tag is left blank doxygen will generate a standard
@ -1157,7 +1157,7 @@ HTML_HEADER =
# that doxygen normally uses. # that doxygen normally uses.
# This tag requires that the tag GENERATE_HTML is set to YES. # This tag requires that the tag GENERATE_HTML is set to YES.
HTML_FOOTER = HTML_FOOTER =
# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # 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 # sheet that is used by each HTML page. It can be used to fine-tune the look of
@ -1736,7 +1736,7 @@ LATEX_HEADER = header.tex
# Note: Only use a user-defined footer if you know what you are doing! # Note: Only use a user-defined footer if you know what you are doing!
# This tag requires that the tag GENERATE_LATEX is set to YES. # This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_FOOTER = LATEX_FOOTER =
# The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined # The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined
# LaTeX style sheets that are included after the standard style sheets created # LaTeX style sheets that are included after the standard style sheets created

2
doc/generate_documentation.sh
View File

@ -36,7 +36,7 @@ fi
for var in $@ for var in $@
do do
case $var in case $var in
-install) -install)
INSTALL_DOX=true INSTALL_DOX=true
;; ;;