diff --git a/doc/dox_comments/header_files/aes.h b/doc/dox_comments/header_files/aes.h index 997bc58c0..764c4d5f2 100644 --- a/doc/dox_comments/header_files/aes.h +++ b/doc/dox_comments/header_files/aes.h @@ -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 diff --git a/doc/dox_comments/header_files/cmac.h b/doc/dox_comments/header_files/cmac.h index 96d5bc8cc..58ea35ea4 100644 --- a/doc/dox_comments/header_files/cmac.h +++ b/doc/dox_comments/header_files/cmac.h @@ -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 diff --git a/doc/dox_comments/header_files/ecc.h b/doc/dox_comments/header_files/ecc.h index 24e888efb..49de5aa02 100644 --- a/doc/dox_comments/header_files/ecc.h +++ b/doc/dox_comments/header_files/ecc.h @@ -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); diff --git a/doc/dox_comments/header_files/hmac.h b/doc/dox_comments/header_files/hmac.h index ca6dcd325..a7c416828 100644 --- a/doc/dox_comments/header_files/hmac.h +++ b/doc/dox_comments/header_files/hmac.h @@ -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); diff --git a/doc/dox_comments/header_files/rsa.h b/doc/dox_comments/header_files/rsa.h index 6e8c75268..f62e1686c 100644 --- a/doc/dox_comments/header_files/rsa.h +++ b/doc/dox_comments/header_files/rsa.h @@ -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. diff --git a/doc/dox_comments/header_files/ssl.h b/doc/dox_comments/header_files/ssl.h index 5965f11d3..a96b3888f 100644 --- a/doc/dox_comments/header_files/ssl.h +++ b/doc/dox_comments/header_files/ssl.h @@ -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 diff --git a/src/tls13.c b/src/tls13.c index 432eb2a96..eb4618075 100644 --- a/src/tls13.c +++ b/src/tls13.c @@ -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, diff --git a/wolfcrypt/src/kdf.c b/wolfcrypt/src/kdf.c index 9dcb12076..2bda46ef7 100644 --- a/wolfcrypt/src/kdf.c +++ b/wolfcrypt/src/kdf.c @@ -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,