mirror of
https://github.com/wolfSSL/wolfssl.git
synced 2026-01-27 09:02:20 +01:00
77d9410aa0
This PR adds Doxygen documentation for native wolfSSL API functions that were previously undocumented. It includes documentation notes for APIs gated on specific preprocessor macros: - WOLF_PRIVATE_KEY_ID: _Id and _Label init helpers (wc_AesInit_Id, wc_AesInit_Label, wc_ecc_init_id, wc_ecc_init_label, wc_InitRsaKey_Id, wc_InitRsaKey_Label) require this for PKCS11 support - WC_NO_CONSTRUCTORS: New/Delete constructor functions (wc_AesNew/Delete, wc_curve25519_new/delete, wc_ed25519_new/delete, wc_NewRsaKey/DeleteRsaKey) are only available when this is not defined. WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is defined. - WOLFSSL_PUBLIC_ASN: ASN functions marked with WOLFSSL_ASN_API include notes indicating they are not public by default - WOLFSSL_DUAL_ALG_CERTS: wc_GeneratePreTBS and wc_MakeSigWithBitStr for Post-Quantum dual algorithm certificate signing The New/Delete functions are documented as being exposed to support allocation of structures using dynamic memory to provide better ABI compatibility.
278 lines
9.3 KiB
C
278 lines
9.3 KiB
C
/*!
|
||
\ingroup Base_Encoding
|
||
|
||
\brief This function decodes the given Base64 encoded input, in, and
|
||
stores the result in the output buffer out. It also sets the size
|
||
written to the output buffer in the variable outLen.
|
||
|
||
\return 0 Returned upon successfully decoding the Base64 encoded input
|
||
\return BAD_FUNC_ARG Returned if the output buffer is too small to
|
||
store the decoded input
|
||
\return ASN_INPUT_E Returned if a character in the input buffer falls
|
||
outside of the Base64 range ([A-Za-z0-9+/=]) or if there is an invalid
|
||
line ending in the Base64 encoded input
|
||
|
||
\param in pointer to the input buffer to decode
|
||
\param inLen length of the input buffer to decode
|
||
\param out pointer to the output buffer in which to store the decoded
|
||
message
|
||
\param outLen pointer to the length of the output buffer. Updated with
|
||
the bytes written at the end of the function call
|
||
|
||
_Example_
|
||
\code
|
||
byte encoded[] = { // initialize text to decode };
|
||
byte decoded[sizeof(encoded)];
|
||
// requires at least (sizeof(encoded) * 3 + 3) / 4 room
|
||
|
||
int outLen = sizeof(decoded);
|
||
|
||
if( Base64_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) {
|
||
// error decoding input buffer
|
||
}
|
||
\endcode
|
||
|
||
\sa Base64_Encode
|
||
\sa Base16_Decode
|
||
*/
|
||
int Base64_Decode(const byte* in, word32 inLen, byte* out,
|
||
word32* outLen);
|
||
|
||
/*!
|
||
\ingroup Base_Encoding
|
||
|
||
\brief This function encodes the given input, in, and stores the Base64
|
||
encoded result in the output buffer out. It writes the data with the
|
||
traditional ‘\n’ line endings, instead of escaped %0A line endings. Upon
|
||
successfully completing, this function also sets outLen to the number
|
||
of bytes written to the output buffer.
|
||
If there is enough room in out to store an extra byte, a NULL terminator
|
||
will be added. This will NOT be included in outLen.
|
||
|
||
\return 0 Returned upon successfully decoding the Base64 encoded input
|
||
\return BAD_FUNC_ARG Returned if the output buffer is too small to
|
||
store the encoded input
|
||
\return BUFFER_E Returned if the output buffer runs out of room
|
||
while encoding
|
||
|
||
\param in pointer to the input buffer to encode
|
||
\param inLen length of the input buffer to encode
|
||
\param out pointer to the output buffer in which to store the
|
||
encoded message
|
||
\param outLen pointer to the length of the output buffer in
|
||
which to store the encoded message
|
||
|
||
_Example_
|
||
\code
|
||
byte plain[] = { // initialize text to encode };
|
||
byte encoded[MAX_BUFFER_SIZE];
|
||
|
||
int outLen = sizeof(encoded);
|
||
|
||
if( Base64_Encode(plain, sizeof(plain), encoded, &outLen) != 0 ) {
|
||
// error encoding input buffer
|
||
}
|
||
\endcode
|
||
|
||
\sa Base64_EncodeEsc
|
||
\sa Base64_Decode
|
||
*/
|
||
|
||
int Base64_Encode(const byte* in, word32 inLen, byte* out,
|
||
word32* outLen);
|
||
|
||
/*!
|
||
\ingroup Base_Encoding
|
||
|
||
\brief This function encodes the given input, in, and stores the
|
||
Base64 encoded result in the output buffer out. It writes the data
|
||
with %0A escaped line endings instead of ‘\n’ line endings.
|
||
Upon successfully completing, this function also sets outLen
|
||
to the number of bytes written to the output buffer.
|
||
|
||
\return 0 Returned upon successfully decoding the Base64 encoded input
|
||
\return BAD_FUNC_ARG Returned if the output buffer is too small
|
||
to store the encoded input
|
||
\return BUFFER_E Returned if the output buffer runs out of
|
||
room while encoding
|
||
\return ASN_INPUT_E Returned if there is an error processing
|
||
the decode on the input message
|
||
|
||
\param in pointer to the input buffer to encode
|
||
\param inLen length of the input buffer to encode
|
||
\param out pointer to the output buffer in which to store
|
||
the encoded message
|
||
\param outLen pointer to the length of the output buffer in
|
||
which to store the encoded message
|
||
|
||
_Example_
|
||
\code
|
||
byte plain[] = { // initialize text to encode };
|
||
byte encoded[MAX_BUFFER_SIZE];
|
||
|
||
int outLen = sizeof(encoded);
|
||
|
||
if( Base64_EncodeEsc(plain, sizeof(plain), encoded, &outLen) != 0 ) {
|
||
// error encoding input buffer
|
||
}
|
||
\endcode
|
||
|
||
\sa Base64_Encode
|
||
\sa Base64_Decode
|
||
*/
|
||
int Base64_EncodeEsc(const byte* in, word32 inLen, byte* out,
|
||
word32* outLen);
|
||
|
||
/*!
|
||
\ingroup Base_Encoding
|
||
|
||
\brief This function encodes the given input, in, and stores the
|
||
Base64 encoded result in the output buffer out. It writes the data
|
||
with no new lines. Upon successfully completing, this function
|
||
also sets outLen to the number of bytes written to the output buffer
|
||
|
||
\return 0 Returned upon successfully decoding the Base64 encoded input
|
||
\return BAD_FUNC_ARG Returned if the output buffer is too small
|
||
to store the encoded input
|
||
\return BUFFER_E Returned if the output buffer runs out of room
|
||
while encoding
|
||
\return ASN_INPUT_E Returned if there is an error processing the
|
||
decode on the input message
|
||
|
||
\param in pointer to the input buffer to encode
|
||
\param inLen length of the input buffer to encode
|
||
\param out pointer to the output buffer in which to store the
|
||
encoded message
|
||
\param outLen pointer to the length of the output buffer in which to
|
||
store the encoded message
|
||
|
||
_Example_
|
||
\code
|
||
byte plain[] = { // initialize text to encode };
|
||
byte encoded[MAX_BUFFER_SIZE];
|
||
int outLen = sizeof(encoded);
|
||
if( Base64_Encode_NoNl(plain, sizeof(plain), encoded, &outLen) != 0 ) {
|
||
// error encoding input buffer
|
||
}
|
||
\endcode
|
||
|
||
\sa Base64_Encode
|
||
\sa Base64_Decode
|
||
*/
|
||
|
||
int Base64_Encode_NoNl(const byte* in, word32 inLen, byte* out,
|
||
word32* outLen);
|
||
|
||
/*!
|
||
\ingroup Base_Encoding
|
||
|
||
\brief This function decodes the given Base16 encoded input, in, and
|
||
stores the result in the output buffer out. It also sets the size written
|
||
to the output buffer in the variable outLen.
|
||
|
||
\return 0 Returned upon successfully decoding the Base16 encoded input
|
||
\return BAD_FUNC_ARG Returned if the output buffer is too small to store
|
||
the decoded input or if the input length is not a multiple of two
|
||
\return ASN_INPUT_E Returned if a character in the input buffer falls
|
||
outside of the Base16 range ([0-9A-F])
|
||
|
||
\param in pointer to the input buffer to decode
|
||
\param inLen length of the input buffer to decode
|
||
\param out pointer to the output buffer in which to store the decoded
|
||
message
|
||
\param outLen pointer to the length of the output buffer. Updated with the
|
||
bytes written at the end of the function call
|
||
|
||
_Example_
|
||
\code
|
||
byte encoded[] = { // initialize text to decode };
|
||
byte decoded[sizeof(encoded)];
|
||
int outLen = sizeof(decoded);
|
||
|
||
if( Base16_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) {
|
||
// error decoding input buffer
|
||
}
|
||
\endcode
|
||
|
||
\sa Base64_Encode
|
||
\sa Base64_Decode
|
||
\sa Base16_Encode
|
||
*/
|
||
|
||
int Base16_Decode(const byte* in, word32 inLen, byte* out, word32* outLen);
|
||
|
||
/*!
|
||
\ingroup Base_Encoding
|
||
|
||
\brief Encode input to base16 output.
|
||
If there is enough room in out to store an extra byte, a NULL terminator
|
||
will be added and included in outLen.
|
||
|
||
\return 0 Success
|
||
\return BAD_FUNC_ARG Returns if in, out, or outLen is null or if outLen is
|
||
less than 2 times inLen plus 1.
|
||
|
||
\param in Pointer to input buffer to be encoded.
|
||
\param inLen Length of input buffer.
|
||
\param out Pointer to output buffer.
|
||
\param outLen Length of output buffer. Is set to len of encoded output.
|
||
|
||
_Example_
|
||
\code
|
||
byte in[] = { // Contents of something to be encoded };
|
||
byte out[NECESSARY_OUTPUT_SIZE];
|
||
word32 outSz = sizeof(out);
|
||
|
||
if(Base16_Encode(in, sizeof(in), out, &outSz) != 0)
|
||
{
|
||
// Handle encode error
|
||
}
|
||
\endcode
|
||
|
||
\sa Base64_Encode
|
||
\sa Base64_Decode
|
||
\sa Base16_Decode
|
||
*/
|
||
|
||
int Base16_Encode(const byte* in, word32 inLen, byte* out, word32* outLen);
|
||
|
||
/*!
|
||
\ingroup Base_Encoding
|
||
\brief This function decodes Base64 encoded input without using
|
||
constant-time operations. This is faster than the constant-time
|
||
version but may be vulnerable to timing attacks. Use only when
|
||
timing attacks are not a concern.
|
||
|
||
\return 0 On successfully decoding the Base64 encoded input.
|
||
\return BAD_FUNC_ARG If the output buffer is too small to store the
|
||
decoded input.
|
||
\return ASN_INPUT_E If a character in the input buffer falls outside
|
||
of the Base64 range or if there is an invalid line ending.
|
||
\return BUFFER_E If running out of buffer while decoding.
|
||
|
||
\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 to store decoded message
|
||
\param outLen pointer to length of output buffer; updated with bytes
|
||
written
|
||
|
||
_Example_
|
||
\code
|
||
byte encoded[] = "SGVsbG8gV29ybGQ="; // "Hello World" in Base64
|
||
byte decoded[64];
|
||
word32 outLen = sizeof(decoded);
|
||
|
||
int ret = Base64_Decode_nonCT(encoded, sizeof(encoded)-1, decoded,
|
||
&outLen);
|
||
if (ret != 0) {
|
||
// error decoding input
|
||
}
|
||
// decoded now contains "Hello World"
|
||
\endcode
|
||
|
||
\sa Base64_Decode
|
||
\sa Base64_Encode
|
||
*/
|
||
int Base64_Decode_nonCT(const byte* in, word32 inLen, byte* out,
|
||
word32* outLen);
|