wolfSSL/wolfssl
1
0
Fork 1
mirror of https://github.com/wolfSSL/wolfssl.git synced 2025-07-30 02:37:28 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation for HKDF functions. Improve param comments for devId.

Browse Source
This commit is contained in:
David Garske
2023-12-27 13:56:40 -08:00
parent cca6cc0495
commit 1c4d7285d3
8 changed files with 504 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -668,13 +668,13 @@ int wc_AesCcmDecrypt(Aes* aes, byte* out,
\param aes AES keys for encrypt/decrypt process
\param heap heap hint to use for memory. Can be NULL
\param devId id to use with async crypto. Can be 0
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code
XtsAes aes;
if(wc_AesXtsInit(&aes, NULL, 0) != 0)
if(wc_AesXtsInit(&aes, NULL, INVALID_DEVID) != 0)
{
// Handle error
}
@ -749,13 +749,13 @@ int wc_AesXtsSetKeyNoInit(XtsAes* aes, const byte* key,
i.e. 32 for a 16 byte key.
\param dir direction, either AES_ENCRYPTION or AES_DECRYPTION
\param heap heap hint to use for memory. Can be NULL
\param devId id to use with async crypto. Can be 0
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code
XtsAes aes;
if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0) != 0)
if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, INVALID_DEVID) != 0)
{
// Handle error
}
@ -974,7 +974,7 @@ int wc_AesXtsFree(XtsAes* aes);
\param aes aes structure in to initialize
\param heap heap hint to use for malloc / free if needed
\param devId ID to use with async hardware
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code
@ -1455,7 +1455,7 @@ WOLFSSL_API int wc_AesEaxEncryptUpdate(AesEax* eax, byte* out,
This argument should be NULL if not used
\param authInSz size in bytes of the input authentication data
_Example_
\code
AesEax eax;
@ -1571,8 +1571,8 @@ WOLFSSL_API int wc_AesEaxAuthDataUpdate(AesEax* eax,
/*!
\ingroup AES
\brief This function finalizes the encrypt AEAD operation, producing an auth
tag over the current authentication stream. \c eax must have been previously
\brief This function finalizes the encrypt AEAD operation, producing an auth
tag over the current authentication stream. \c eax must have been previously
initialized with a call to \ref wc_AesEaxInit. When done using the \c AesEax
context structure, make sure to free it using \ref wc_AesEaxFree.
@ -1632,10 +1632,10 @@ WOLFSSL_API int wc_AesEaxEncryptFinal(AesEax* eax,
/*!
\ingroup AES
\brief This function finalizes the decrypt AEAD operation, finalizing the
\brief This function finalizes the decrypt AEAD operation, finalizing the
auth tag computation and checking it for validity against the user supplied
tag. \c eax must have been previously initialized with a call to
\ref wc_AesEaxInit. When done using the \c AesEax context structure, make
tag. \c eax must have been previously initialized with a call to
\ref wc_AesEaxInit. When done using the \c AesEax context structure, make
sure to free it using \ref wc_AesEaxFree.
\return 0 if data is authenticated successfully

2
doc/dox_comments/header_files/cmac.h
View File

@ -40,7 +40,7 @@ int wc_InitCmac(Cmac* cmac,
\param type Always WC_CMAC_AES = 1
\param unused not used, exists for potential future use around compatibility
\param heap pointer to the heap hint used for dynamic allocation. Typically used with our static memory option. Can be NULL.
\param devId ID to use with async hardware. Set to INVALID_DEVID if not using async hardware.
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code

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

@ -572,8 +572,8 @@ int wc_ecc_init(ecc_key* key);
\return MEMORY_E Returned if there is an error allocating memory
\param key pointer to the ecc_key object to initialize
\param devId ID to use with async hardware
\param heap pointer to a heap identifier
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code
@ -1968,7 +1968,7 @@ int wc_ecc_decrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
/*!
\ingroup ECC
\brief Enable ECC support for non-blocking operations. Supported for
\brief Enable ECC support for non-blocking operations. Supported for
Single Precision (SP) math with the following build options:
WOLFSSL_SP_NONBLOCK
WOLFSSL_SP_SMALL
@ -1978,7 +1978,7 @@ int wc_ecc_decrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
\return 0 Returned upon successfully setting the callback context the input message
\param key pointer to the ecc_key object
\param ctx pointer to ecc_nb_ctx_t structure with stack data cache for SP
\param ctx pointer to ecc_nb_ctx_t structure with stack data cache for SP
_Example_
\code
@ -1998,7 +1998,7 @@ int wc_ecc_decrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
&key
);
// TODO: Real-time work can be called here
// TODO: Real-time work can be called here
} while (ret == FP_WOULDBLOCK);
}
wc_ecc_free(&key);

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

@ -129,6 +129,9 @@ int wolfSSL_GetHmacMaxSize(void);
optional info into a derived key, which it stores in out. The hash type
defaults to MD5 if 0 or NULL is given.
The HMAC configure option is --enable-hmac (on by default) or if building
sources directly HAVE_HKDF
\return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
\return MEMORY_E Returned if there is an error allocating memory
@ -170,3 +173,439 @@ int wc_HKDF(int type, const byte* inKey, word32 inKeySz,
const byte* salt, word32 saltSz,
const byte* info, word32 infoSz,
byte* out, word32 outSz);
/*!
\ingroup HMAC
\brief This function provides access to a HMAC Key Derivation Function
(HKDF). It utilizes HMAC to convert inKey, with an optional salt
into a derived key, which it stores in out. The hash type
defaults to MD5 if 0 or NULL is given.
The HMAC configure option is --enable-hmac (on by default) or if building
sources directly HAVE_HKDF
\return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
\return MEMORY_E Returned if there is an error allocating memory
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
and the key length specified is shorter than the minimum acceptable FIPS
standard
\param type hash type to use for the HKDF. Valid types are: WC_MD5, WC_SHA,
WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or
WC_SHA3_512
\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 inKey pointer to the buffer containing the key to use for KDF
\param inKeySz length of the input key
\param out pointer to the buffer in which to store the derived key
_Example_
\code
byte key[] = { // initialize with key };
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];
int ret = wc_HKDF_Extract(WC_SHA512, salt, sizeof(salt), key, sizeof(key),
derivedKey);
if ( ret != 0 ) {
// error generating derived key
}
\endcode
\sa wc_HKDF
\sa wc_HKDF_Extract_ex
\sa wc_HKDF_Expand
\sa wc_HKDF_Expand_ex
*/
int wc_HKDF_Extract(
int type,
const byte* salt, word32 saltSz,
const byte* inKey, word32 inKeySz,
byte* out);
/*!
\ingroup HMAC
\brief This function provides access to a HMAC Key Derivation Function
(HKDF). It utilizes HMAC to convert inKey, with an optional salt
into a derived key, which it stores in out. The hash type
defaults to MD5 if 0 or NULL is given. This is the _ex version adding
heap hint and device identifier.
The HMAC configure option is --enable-hmac (on by default) or if building
sources directly HAVE_HKDF
\return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
\return MEMORY_E Returned if there is an error allocating memory
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
and the key length specified is shorter than the minimum acceptable FIPS
standard
\param type hash type to use for the HKDF. Valid types are: WC_MD5, WC_SHA,
WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or
WC_SHA3_512
\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 inKey pointer to the buffer containing the key to use for KDF
\param inKeySz length of the input key
\param out pointer to the buffer in which to store the derived key
\param heap heap hint to use for memory. Can be NULL
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code
byte key[] = { // initialize with key };
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];
int ret = wc_HKDF_Extract_ex(WC_SHA512, salt, sizeof(salt), key, sizeof(key),
derivedKey, NULL, INVALID_DEVID);
if ( ret != 0 ) {
// error generating derived key
}
\endcode
\sa wc_HKDF
\sa wc_HKDF_Extract
\sa wc_HKDF_Expand
\sa wc_HKDF_Expand_ex
*/
int wc_HKDF_Extract_ex(
int type,
const byte* salt, word32 saltSz,
const byte* inKey, word32 inKeySz,
byte* out,
void* heap, int devId);
/*!
\ingroup HMAC
\brief This function provides access to a HMAC Key Derivation Function
(HKDF). It utilizes HMAC to convert inKey, with optional info into a
derived key, which it stores in out. The hash type
defaults to MD5 if 0 or NULL is given.
The HMAC configure option is --enable-hmac (on by default) or if building
sources directly HAVE_HKDF
\return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
\return MEMORY_E Returned if there is an error allocating memory
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
and the key length specified is shorter than the minimum acceptable FIPS
standard
\param type hash type to use for the HKDF. Valid types are: WC_MD5, WC_SHA,
WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or
WC_SHA3_512
\param inKey pointer to the buffer containing the key to use for KDF
\param inKeySz length of the input key
\param info pointer to a buffer containing optional additional info.
Use NULL if not appending extra info
\param infoSz length of additional info. Use 0 if not using additional info
\param out pointer to the buffer in which to store the derived key
\param outSz space available in the output buffer to store the
generated key
_Example_
\code
byte key[] = { // initialize with key };
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];
int ret = wc_HKDF_Expand(WC_SHA512, key, sizeof(key), NULL, 0,
derivedKey, sizeof(derivedKey));
if ( ret != 0 ) {
// error generating derived key
}
\endcode
\sa wc_HKDF
\sa wc_HKDF_Extract
\sa wc_HKDF_Extract_ex
\sa wc_HKDF_Expand_ex
*/
int wc_HKDF_Expand(
int type,
const byte* inKey, word32 inKeySz,
const byte* info, word32 infoSz,
byte* out, word32 outSz);
/*!
\ingroup HMAC
\brief This function provides access to a HMAC Key Derivation Function
(HKDF). It utilizes HMAC to convert inKey, with optional info into a
derived key, which it stores in out. The hash type
defaults to MD5 if 0 or NULL is given. This is the _ex version adding
heap hint and device identifier.
The HMAC configure option is --enable-hmac (on by default) or if building
sources directly HAVE_HKDF
\return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
\return MEMORY_E Returned if there is an error allocating memory
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
and the key length specified is shorter than the minimum acceptable FIPS
standard
\param type hash type to use for the HKDF. Valid types are: WC_MD5, WC_SHA,
WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or
WC_SHA3_512
\param inKey pointer to the buffer containing the key to use for KDF
\param inKeySz length of the input key
\param info pointer to a buffer containing optional additional info.
Use NULL if not appending extra info
\param infoSz length of additional info. Use 0 if not using additional info
\param out pointer to the buffer in which to store the derived key
\param outSz space available in the output buffer to store the
generated key
\param heap heap hint to use for memory. Can be NULL
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code
byte key[] = { // initialize with key };
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];
int ret = wc_HKDF_Expand_ex(WC_SHA512, key, sizeof(key), NULL, 0,
derivedKey, sizeof(derivedKey), NULL, INVALID_DEVID);
if ( ret != 0 ) {
// error generating derived key
}
\endcode
\sa wc_HKDF
\sa wc_HKDF_Extract
\sa wc_HKDF_Extract_ex
\sa wc_HKDF_Expand
*/
int wc_HKDF_Expand_ex(
int type,
const byte* inKey, word32 inKeySz,
const byte* info, word32 infoSz,
byte* out, word32 outSz,
void* heap, int devId);
/*!
\ingroup HMAC
\brief This function provides access to RFC 5869
HMAC-based Extract-and-Expand Key Derivation Function (HKDF) for TLS v1.3
key derivation
\return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
\return MEMORY_E Returned if there is an error allocating memory
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
and the key length specified is shorter than the minimum acceptable FIPS
standard
\param prk Generated pseudorandom key
\param salt salt.
\param saltLen length of the salt
\param ikm pointer to putput for keying material
\param ikmLen length of the input keying material buffer
\param digest hash type to use for the HKDF. Valid types are: WC_SHA256, WC_SHA384 or WC_SHA512
_Example_
\code
byte secret[] = { // initialize with random key };
byte salt[] = { // initialize with optional salt };
byte masterSecret[MAX_DIGEST_SIZE];
int ret = wc_Tls13_HKDF_Extract(secret, salt, sizeof(salt), 0,
masterSecret, sizeof(masterSecret), WC_SHA512);
if ( ret != 0 ) {
// error generating derived key
}
\endcode
\sa wc_HKDF
\sa wc_HKDF_Extract
\sa wc_HKDF_Extract_ex
\sa wc_HKDF_Expand
\sa wc_Tls13_HKDF_Extract_ex
*/
int wc_Tls13_HKDF_Extract(
byte* prk,
const byte* salt, word32 saltLen,
byte* ikm, word32 ikmLen, int digest);
/*!
\ingroup HMAC
\brief This function provides access to RFC 5869
HMAC-based Extract-and-Expand Key Derivation Function (HKDF) for TLS v1.3
key derivation. This is the _ex version adding heap hint and device identifier.
\return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
\return MEMORY_E Returned if there is an error allocating memory
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
and the key length specified is shorter than the minimum acceptable FIPS
standard
\param prk Generated pseudorandom key
\param salt Salt.
\param saltLen Length of the salt
\param ikm Pointer to output for keying material
\param ikmLen Length of the input keying material buffer
\param digest Hash type to use for the HKDF. Valid types are: WC_SHA256, WC_SHA384 or WC_SHA512
\param heap Heap hint to use for memory. Can be NULL
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code
byte secret[] = { // initialize with random key };
byte salt[] = { // initialize with optional salt };
byte masterSecret[MAX_DIGEST_SIZE];
int ret = wc_Tls13_HKDF_Extract_ex(secret, salt, sizeof(salt), 0,
masterSecret, sizeof(masterSecret), WC_SHA512, NULL, INVALID_DEVID);
if ( ret != 0 ) {
// error generating derived key
}
\endcode
\sa wc_HKDF
\sa wc_HKDF_Extract
\sa wc_HKDF_Extract_ex
\sa wc_HKDF_Expand
\sa wc_Tls13_HKDF_Extract
*/
int wc_Tls13_HKDF_Extract_ex(
byte* prk,
const byte* salt, word32 saltLen,
byte* ikm, word32 ikmLen, int digest,
void* heap, int devId);
/*!
\ingroup HMAC
\brief Expand data using HMAC, salt and label and info. TLS v1.3 defines
this function for key derivation. This is the _ex version adding heap hint
and device identifier.
\return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
\return MEMORY_E Returned if there is an error allocating memory
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
and the key length specified is shorter than the minimum acceptable FIPS
standard
\param okm Generated pseudorandom key - output key material.
\param okmLen Length of generated pseudorandom key - output key material.
\param prk Salt - pseudo-random key.
\param prkLen Length of the salt - pseudo-random key.
\param protocol TLS protocol label.
\param protocolLen Length of the TLS protocol label.
\param info Information to expand.
\param infoLen Length of the information.
\param digest Hash type to use for the HKDF. Valid types are: WC_SHA256, WC_SHA384 or WC_SHA512
\param heap Heap hint to use for memory. Can be NULL
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
\sa wc_HKDF
\sa wc_HKDF_Extract
\sa wc_HKDF_Extract_ex
\sa wc_HKDF_Expand
\sa wc_Tls13_HKDF_Expand_Label
\sa wc_Tls13_HKDF_Expand_Label_Alloc
*/
int wc_Tls13_HKDF_Expand_Label_ex(
byte* okm, word32 okmLen,
const byte* prk, word32 prkLen,
const byte* protocol, word32 protocolLen,
const byte* label, word32 labelLen,
const byte* info, word32 infoLen,
int digest,
void* heap, int devId);
/*!
\ingroup HMAC
\brief Expand data using HMAC, salt and label and info. TLS v1.3 defines
this function for key derivation. This is the _ex version adding heap hint
and device identifier.
\return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
\return MEMORY_E Returned if there is an error allocating memory
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
and the key length specified is shorter than the minimum acceptable FIPS
standard
\param okm Generated pseudorandom key - output key material.
\param okmLen Length of generated pseudorandom key - output key material.
\param prk Salt - pseudo-random key.
\param prkLen Length of the salt - pseudo-random key.
\param protocol TLS protocol label.
\param protocolLen Length of the TLS protocol label.
\param info Information to expand.
\param infoLen Length of the information.
\param digest Hash type to use for the HKDF. Valid types are: WC_SHA256, WC_SHA384 or WC_SHA512
\sa wc_HKDF
\sa wc_HKDF_Extract
\sa wc_HKDF_Extract_ex
\sa wc_HKDF_Expand
\sa wc_Tls13_HKDF_Expand_Label_ex
\sa wc_Tls13_HKDF_Expand_Label_Alloc
*/
int wc_Tls13_HKDF_Expand_Label(
byte* okm, word32 okmLen,
const byte* prk, word32 prkLen,
const byte* protocol, word32 protocolLen,
const byte* label, word32 labelLen,
const byte* info, word32 infoLen,
int digest);
/*!
\ingroup HMAC
\brief This functions is very similar to wc_Tls13_HKDF_Expand_Label(), but it
allocates memory if the stack space usually used isn't enough. Expand data
using HMAC, salt and label and info. TLS v1.3 defines this function for
key derivation. This is the _ex version adding heap hint and device identifier.
\return 0 Returned upon successfully generating a key with the given inputs
\return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
\return MEMORY_E Returned if there is an error allocating memory
\return HMAC_MIN_KEYLEN_E May be returned when using a FIPS implementation
and the key length specified is shorter than the minimum acceptable FIPS
standard
\param okm Generated pseudorandom key - output key material.
\param okmLen Length of generated pseudorandom key - output key material.
\param prk Salt - pseudo-random key.
\param prkLen Length of the salt - pseudo-random key.
\param protocol TLS protocol label.
\param protocolLen Length of the TLS protocol label.
\param info Information to expand.
\param infoLen Length of the information.
\param digest Hash type to use for the HKDF. Valid types are: WC_SHA256, WC_SHA384 or WC_SHA512
\param heap Heap hint to use for memory. Can be NULL
\sa wc_HKDF
\sa wc_HKDF_Extract
\sa wc_HKDF_Extract_ex
\sa wc_HKDF_Expand
\sa wc_Tls13_HKDF_Expand_Label
\sa wc_Tls13_HKDF_Expand_Label_ex
*/
int wc_Tls13_HKDF_Expand_Label_Alloc(
byte* okm, word32 okmLen,
const byte* prk, word32 prkLen,
const byte* protocol, word32 protocolLen,
const byte* label, word32 labelLen,
const byte* info, word32 infoLen,
int digest, void* heap);

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

@ -56,7 +56,7 @@ int wc_InitRsaKey(RsaKey* key, void* heap);
\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
\param devId ID to use with hardware device
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code
@ -1377,7 +1377,7 @@ int wc_RsaKeyToPublicDer(RsaKey* key, byte* output, word32 inLen);
\ingroup RSA
\brief Convert RSA Public key to DER format. Writes to output, and
returns count of bytes written. If with_header is 0 then only the
returns count of bytes written. If with_header is 0 then only the
( seq + n + e) is returned in ASN.1 DER format and will exclude the header.
\return >0 Success, number of bytes written.

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

@ -1063,12 +1063,12 @@ int wolfSSL_CTX_use_certificate_file(WOLFSSL_CTX* ctx, const char* file,
argument specifies the format type of the file - SSL_FILETYPE_ASN1or
SSL_FILETYPE_PEM. Please see the examples for proper usage.
If using an external key store and do not have the private key you can
instead provide the public key and register the crypro callback to handle
the signing. For this you can build with either build with crypto callbacks
If using an external key store and do not have the private key you can
instead provide the public key and register the crypro callback to handle
the signing. For this you can build with either build with crypto callbacks
or PK callbacks. To enable crypto callbacks use --enable-cryptocb
or WOLF_CRYPTO_CB and register a crypto callback using
wc_CryptoCb_RegisterDevice and set the associated devId using
or WOLF_CRYPTO_CB and register a crypto callback using
wc_CryptoCb_RegisterDevice and set the associated devId using
wolfSSL_CTX_SetDevId.
\return SSL_SUCCESS upon success.
@ -1554,12 +1554,12 @@ int wolfSSL_use_certificate_file(WOLFSSL* ssl, const char* file, int format);
The format argument specifies the format type of the file -
SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
If using an external key store and do not have the private key you can
instead provide the public key and register the crypro callback to handle
the signing. For this you can build with either build with crypto callbacks
If using an external key store and do not have the private key you can
instead provide the public key and register the crypro callback to handle
the signing. For this you can build with either build with crypto callbacks
or PK callbacks. To enable crypto callbacks use --enable-cryptocb or
WOLF_CRYPTO_CB and register a crypto callback using
wc_CryptoCb_RegisterDevice and set the associated devId using
WOLF_CRYPTO_CB and register a crypto callback using
wc_CryptoCb_RegisterDevice and set the associated devId using
wolfSSL_SetDevId.
\return SSL_SUCCESS upon success.
@ -3041,7 +3041,7 @@ int wolfSSL_library_init(void);
\return BAD_FUNC_ARG if ssl is NULL.
\param ssl pointer to a SSL object, created with wolfSSL_new().
\param devId ID to use with async hardware
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code
@ -3064,7 +3064,7 @@ int wolfSSL_SetDevId(WOLFSSL* ssl, int devId);
\return BAD_FUNC_ARG if ssl is NULL.
\param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
\param devId ID to use with async hardware
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
_Example_
\code
@ -6246,7 +6246,7 @@ int wolfSSL_set_timeout(WOLFSSL* ssl, unsigned int to);
\brief This function sets the timeout value for SSL sessions, in seconds,
for the specified SSL context.
\return the previous timeout value, if WOLFSSL_ERROR_CODE_OPENSSL is
\return the previous timeout value, if WOLFSSL_ERROR_CODE_OPENSSL is
\return defined on success. If not defined, SSL_SUCCESS will be returned.
\return BAD_FUNC_ARG will be returned when the input context (ctx) is null.
@ -7755,7 +7755,7 @@ int wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,
The buffer is provided by the in argument of size sz. format specifies
the format type of the buffer; SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
More than one CA certificate may be loaded per buffer as long as the
format is in PEM. The _ex version was added in PR 2413 and supports
format is in PEM. The _ex version was added in PR 2413 and supports
additional arguments for userChain and flags.
\return SSL_SUCCESS upon success
@ -14421,7 +14421,7 @@ int wolfSSL_set_ephemeral_key(WOLFSSL* ssl, int keyAlgo, const char* key, unsign
\param keySz key size pointer
\sa wolfSSL_CTX_set_ephemeral_key
*/
int wolfSSL_CTX_get_ephemeral_key(WOLFSSL_CTX* ctx, int keyAlgo,
int wolfSSL_CTX_get_ephemeral_key(WOLFSSL_CTX* ctx, int keyAlgo,
const unsigned char** key, unsigned int* keySz);
/*!
@ -14434,7 +14434,7 @@ int wolfSSL_CTX_get_ephemeral_key(WOLFSSL_CTX* ctx, int keyAlgo,
\param keySz key size pointer
\sa wolfSSL_set_ephemeral_key
*/
int wolfSSL_get_ephemeral_key(WOLFSSL* ssl, int keyAlgo,
int wolfSSL_get_ephemeral_key(WOLFSSL* ssl, int keyAlgo,
const unsigned char** key, unsigned int* keySz);
/*!
@ -14504,18 +14504,18 @@ unsigned int wolfSSL_SESSION_get_max_early_data(const WOLFSSL_SESSION *s);
int wolfSSL_CRYPTO_get_ex_new_index(int, void*, void*, void*, void*);
/*!
\ingroup Setup
\brief In case this function is called in a client side, set certificate types
\ingroup Setup
\brief In case this function is called in a client side, set certificate types
that can be sent to its peer. In case called in a server side,
set certificate types that can be acceptable from its peer. Put cert types in the
buffer with prioritised order. To reset the settings to default, pass NULL
for the buffer or pass zero for len. By default, certificate type is only X509.
for the buffer or pass zero for len. By default, certificate type is only X509.
In case both side intend to send or accept "Raw public key" cert,
WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
\return WOLFSSL_SUCCESS if cert types set successfully
\return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
cert type, buf size exceed MAX_CLIENT_CERT_TYPE_CNT was specified or
cert type, buf size exceed MAX_CLIENT_CERT_TYPE_CNT was specified or
a duplicate value is found in buf.
\param ctx WOLFSSL_CTX object pointer
@ -14540,18 +14540,18 @@ int wolfSSL_CRYPTO_get_ex_new_index(int, void*, void*, void*, void*);
int wolfSSL_CTX_set_client_cert_type(WOLFSSL_CTX* ctx, const char* buf, int len);
/*!
\ingroup Setup
\brief In case this function is called in a server side, set certificate types
\ingroup Setup
\brief In case this function is called in a server side, set certificate types
that can be sent to its peer. In case called in a client side,
set certificate types that can be acceptable from its peer. Put cert types in the
buffer with prioritised order. To reset the settings to default, pass NULL
for the buffer or pass zero for len. By default, certificate type is only X509.
for the buffer or pass zero for len. By default, certificate type is only X509.
In case both side intend to send or accept "Raw public key" cert,
WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
\return WOLFSSL_SUCCESS if cert types set successfully
\return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
cert type, buf size exceed MAX_SERVER_CERT_TYPE_CNT was specified or
cert type, buf size exceed MAX_SERVER_CERT_TYPE_CNT was specified or
a duplicate value is found in buf.
\param ctx WOLFSSL_CTX object pointer
@ -14576,18 +14576,18 @@ int wolfSSL_CTX_set_client_cert_type(WOLFSSL_CTX* ctx, const char* buf, int len)
int wolfSSL_CTX_set_server_cert_type(WOLFSSL_CTX* ctx, const char* buf, int len);
/*!
\ingroup Setup
\brief In case this function is called in a client side, set certificate types
\ingroup Setup
\brief In case this function is called in a client side, set certificate types
that can be sent to its peer. In case called in a server side,
set certificate types that can be acceptable from its peer. Put cert types in the
buffer with prioritised order. To reset the settings to default, pass NULL
for the buffer or pass zero for len. By default, certificate type is only X509.
for the buffer or pass zero for len. By default, certificate type is only X509.
In case both side intend to send or accept "Raw public key" cert,
WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
\return WOLFSSL_SUCCESS if cert types set successfully
\return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
cert type, buf size exceed MAX_CLIENT_CERT_TYPE_CNT was specified or
cert type, buf size exceed MAX_CLIENT_CERT_TYPE_CNT was specified or
a duplicate value is found in buf.
\param ssl WOLFSSL object pointer
@ -14612,18 +14612,18 @@ int wolfSSL_CTX_set_server_cert_type(WOLFSSL_CTX* ctx, const char* buf, int len)
int wolfSSL_set_client_cert_type(WOLFSSL* ssl, const char* buf, int len);
/*!
\ingroup Setup
\brief In case this function is called in a server side, set certificate types
\ingroup Setup
\brief In case this function is called in a server side, set certificate types
that can be sent to its peer. In case called in a client side,
set certificate types that can be acceptable from its peer. Put cert types in the
buffer with prioritised order. To reset the settings to default, pass NULL
for the buffer or pass zero for len. By default, certificate type is only X509.
for the buffer or pass zero for len. By default, certificate type is only X509.
In case both side intend to send or accept "Raw public key" cert,
WOLFSSL_CERT_TYPE_RPK should be included in the buffer to set.
\return WOLFSSL_SUCCESS if cert types set successfully
\return BAD_FUNC_ARG if NULL was passed for ctx, illegal value was specified as
cert type, buf size exceed MAX_SERVER_CERT_TYPE_CNT was specified or
cert type, buf size exceed MAX_SERVER_CERT_TYPE_CNT was specified or
a duplicate value is found in buf.
\param ctx WOLFSSL_CTX object pointer
@ -14648,17 +14648,17 @@ int wolfSSL_set_client_cert_type(WOLFSSL* ssl, const char* buf, int len);
int wolfSSL_set_server_cert_type(WOLFSSL* ssl, const char* buf, int len);
/*!
\ingroup SSL
\brief This function returns the result of the client certificate type
\ingroup SSL
\brief This function returns the result of the client certificate type
negotiation done in ClientHello and ServerHello. WOLFSSL_SUCCESS is returned as
a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is
a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is
returned as the certificate type.
\return WOLFSSL_SUCCESS if a negotiated certificate type could be got
\return BAD_FUNC_ARG if NULL was passed for ctx or tp
\param ssl WOLFSSL object pointer
\param tp A buffer where a certificate type is to be returned. One of three
certificate types will be returned: WOLFSSL_CERT_TYPE_RPK,
\param tp A buffer where a certificate type is to be returned. One of three
certificate types will be returned: WOLFSSL_CERT_TYPE_RPK,
WOLFSSL_CERT_TYPE_X509 or WOLFSSL_CERT_TYPE_UNKNOWN.
_Example_
@ -14679,17 +14679,17 @@ int wolfSSL_set_server_cert_type(WOLFSSL* ssl, const char* buf, int len);
int wolfSSL_get_negotiated_client_cert_type(WOLFSSL* ssl, int* tp);
/*!
\ingroup SSL
\brief This function returns the result of the server certificate type
\ingroup SSL
\brief This function returns the result of the server certificate type
negotiation done in ClientHello and ServerHello. WOLFSSL_SUCCESS is returned as
a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is
a return value if no negotiation occurs and WOLFSSL_CERT_TYPE_UNKNOWN is
returned as the certificate type.
\return WOLFSSL_SUCCESS if a negotiated certificate type could be got
\return BAD_FUNC_ARG if NULL was passed for ctx or tp
\param ssl WOLFSSL object pointer
\param tp A buffer where a certificate type is to be returned. One of three
certificate types will be returned: WOLFSSL_CERT_TYPE_RPK,
\param tp A buffer where a certificate type is to be returned. One of three
certificate types will be returned: WOLFSSL_CERT_TYPE_RPK,
WOLFSSL_CERT_TYPE_X509 or WOLFSSL_CERT_TYPE_UNKNOWN.
_Example_
\code

21
src/tls13.c
View File

@ -187,21 +187,7 @@ static WC_INLINE int GetMsgHash(WOLFSSL* ssl, byte* hash);
#endif
/* Expand data using HMAC, salt and label and info.
* TLS v1.3 defines this function. Use callback if available.
*
* ssl The SSL/TLS object.
* okm The generated pseudorandom key - output key material.
* okmLen The length of generated pseudorandom key -
* output key material.
* prk The salt - pseudo-random key.
* prkLen The length of the salt - pseudo-random key.
* protocol The TLS protocol label.
* protocolLen The length of the TLS protocol label.
* info The information to expand.
* infoLen The length of the information.
* digest The type of digest to use.
* returns 0 on success, otherwise failure.
*/
* TLS v1.3 defines this function. Use callback if available. */
static int Tls13HKDFExpandLabel(WOLFSSL* ssl, byte* okm, word32 okmLen,
const byte* prk, word32 prkLen,
const byte* protocol, word32 protocolLen,
@ -241,9 +227,8 @@ static int Tls13HKDFExpandLabel(WOLFSSL* ssl, byte* okm, word32 okmLen,
return ret;
}
/* Same as above, but pass in the side we are expanding for.
*
* side The side (WOLFSSL_CLIENT_END or WOLFSSL_SERVER_END).
/* Same as above, but pass in the side we are expanding for:
* side: either WOLFSSL_CLIENT_END or WOLFSSL_SERVER_END.
*/
static int Tls13HKDFExpandKeyLabel(WOLFSSL* ssl, byte* okm, word32 okmLen,
const byte* prk, word32 prkLen,

42
wolfcrypt/src/kdf.c
View File

@ -353,14 +353,6 @@ int wc_PRF_TLS(byte* digest, word32 digLen, const byte* secret, word32 secLen,
/* Extract data using HMAC, salt and input.
* RFC 5869 - HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
*
* prk The generated pseudorandom key.
* salt The salt.
* saltLen The length of the salt.
* ikm The input keying material.
* ikmLen The length of the input keying material.
* digest The type of digest to use.
* returns 0 on success, otherwise failure.
*/
int wc_Tls13_HKDF_Extract_ex(byte* prk, const byte* salt, word32 saltLen,
byte* ikm, word32 ikmLen, int digest, void* heap, int devId)
@ -436,20 +428,7 @@ int wc_PRF_TLS(byte* digest, word32 digLen, const byte* secret, word32 secLen,
}
/* Expand data using HMAC, salt and label and info.
* TLS v1.3 defines this function.
*
* okm The generated pseudorandom key - output key material.
* okmLen The length of generated pseudorandom key -
* output key material.
* prk The salt - pseudo-random key.
* prkLen The length of the salt - pseudo-random key.
* protocol The TLS protocol label.
* protocolLen The length of the TLS protocol label.
* info The information to expand.
* infoLen The length of the information.
* digest The type of digest to use.
* returns 0 on success, otherwise failure.
*/
* TLS v1.3 defines this function. */
int wc_Tls13_HKDF_Expand_Label_ex(byte* okm, word32 okmLen,
const byte* prk, word32 prkLen,
const byte* protocol, word32 protocolLen,
@ -556,24 +535,7 @@ int wc_PRF_TLS(byte* digest, word32 digLen, const byte* secret, word32 secLen,
#if defined(WOLFSSL_TICKET_NONCE_MALLOC) && \
(!defined(HAVE_FIPS) || (defined(FIPS_VERSION_GE) && FIPS_VERSION_GE(5,3)))
/* Expand data using HMAC, salt and label and info.
* TLS v1.3 defines this function.
*
* okm The generated pseudorandom key - output key material.
* okmLen The length of generated pseudorandom key -
* output key material.
* prk The salt - pseudo-random key.
* prkLen The length of the salt - pseudo-random key.
* protocol The TLS protocol label.
* protocolLen The length of the TLS protocol label.
* info The information to expand.
* infoLen The length of the information.
* digest The type of digest to use.
*
* This functions is very similar to wc_Tls13_HKDF_Expand_Label() but it
* allocate memory if the stack space usually used isn't enough.
*
* returns 0 on success, otherwise failure.
*/
* TLS v1.3 defines this function. */
int wc_Tls13_HKDF_Expand_Label_Alloc(byte* okm, word32 okmLen,
const byte* prk, word32 prkLen, const byte* protocol,
word32 protocolLen, const byte* label, word32 labelLen,