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

8
doc/check_api.sh
View File

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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').children(':first').addClass('sm sm-dox').attr('id','main-menu');
$('#main-menu').smartmenus();
}

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

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

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

2
doc/generate_documentation.sh
View File

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