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

Merge pull request #5454 from dgarske/docs_hashtype

Browse Source 
Improve the documentation for HMAC hash types
This commit is contained in:
Sean Parkinson
2022-08-11 16:50:55 +10:00
committed by GitHub
parent 87d96c9c96 c707186b9f
commit dd2a6410d1
3 changed files with 34 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -133,7 +133,7 @@ int wc_MakeCertReq(Cert* cert, byte* derBuffer, word32 derSz,
\param requestSz the size of the certificate body we’re requesting
to have signed
\param sType Type of signature to create. Valid options are: CTC_MD5wRSA,
CTC_SHAwRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, andCTC_SHA256wRSA
CTC_SHAwRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, and CTC_SHA256wRSA
\param buffer pointer to the buffer containing the certificate to be
signed. On success: will hold the newly signed certificate
\param buffSz the (total) size of the buffer in which to store the newly
@ -903,7 +903,7 @@ int wc_SetAuthKeyId(Cert *cert, const char* file);
\brief Set SKID from RSA or ECC public key.
\return 0 Success
\return BAD_FUNC_ARG Returned if cert or rsakey and eckey is null.
\return BAD_FUNC_ARG Returned if cert or rsakey and eckey are null.
\return MEMORY_E Returned if there is an error allocating memory.
\return PUBLIC_KEY_E Returned if there is an error getting the public key.
@ -1522,10 +1522,10 @@ int wc_EccPublicKeyToDer_ex(ecc_key* key, byte* output,
Sha256 sha256;
// initialize sha256 for hashing
byte* dig = = (byte*)malloc(SHA256_DIGEST_SIZE);
byte* dig = = (byte*)malloc(WC_SHA256_DIGEST_SIZE);
// perform hashing and hash updating so dig stores SHA-256 hash
// (see wc_InitSha256, wc_Sha256Update and wc_Sha256Final)
signSz = wc_EncodeSignature(encodedSig, dig, SHA256_DIGEST_SIZE,SHA256h);
signSz = wc_EncodeSignature(encodedSig, dig, WC_SHA256_DIGEST_SIZE, SHA256h);
\endcode
\sa none
@ -1537,7 +1537,7 @@ word32 wc_EncodeSignature(byte* out, const byte* digest,
\ingroup ASN
\brief This function returns the hash OID that corresponds to a hashing
type. For example, when given the type: SHA512, this function returns the
type. For example, when given the type: WC_SHA512, this function returns the
identifier corresponding to a SHA512 hash, SHA512h.
\return Success On success, returns the OID corresponding to the
@ -1545,14 +1545,14 @@ word32 wc_EncodeSignature(byte* out, const byte* digest,
\return 0 Returned if an unrecognized hash type is passed in as argument.
\param type the hash type for which to find the OID. Valid options,
depending on build configuration, include: MD2, MD5, SHA, SHA256, SHA512,
SHA384, and SHA512.
depending on build configuration, include: WC_MD5, WC_SHA, WC_SHA256,
WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
_Example_
\code
int hashOID;
hashOID = wc_GetCTC_HashOID(SHA512);
hashOID = wc_GetCTC_HashOID(WC_SHA512);
if (hashOID == 0) {
// WOLFSSL_SHA512 not defined
}

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

@ -5,9 +5,7 @@
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
are: MD5, SHA, SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384,
SHA3-512
\return BAD_FUNC_ARG Returned if the input type is invalid (see type param)
\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
@ -16,8 +14,8 @@
\param hmac pointer to the Hmac object to initialize
\param type type specifying which encryption method the Hmac object
should use. Valid options are: MD5, SHA, SHA256, SHA384, SHA512, SHA3-224,
SHA3-256, SHA3-384, SHA3-512
should use. Valid options 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 key pointer to a buffer containing the key with which to
initialize the Hmac object
\param length length of the key
@ -26,7 +24,7 @@
\code
Hmac hmac;
byte key[] = { // initialize with key to use for encryption };
if (wc_HmacSetKey(&hmac, MD5, key, sizeof(key)) != 0) {
if (wc_HmacSetKey(&hmac, WC_MD5, key, sizeof(key)) != 0) {
// error initializing Hmac object
}
\endcode
@ -132,16 +130,15 @@ int wolfSSL_GetHmacMaxSize(void);
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
argument. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, SHA3-224,
SHA3-256, SHA3-384, SHA3-512
\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: MD5, SHA,
SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512
\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 salt pointer to a buffer containing an optional salt. Use NULL
@ -160,7 +157,7 @@ int wolfSSL_GetHmacMaxSize(void);
byte salt[] = { // initialize with salt };
byte derivedKey[MAX_DIGEST_SIZE];
int ret = wc_HKDF(SHA512, key, sizeof(key), salt, sizeof(salt),
int ret = wc_HKDF(WC_SHA512, key, sizeof(key), salt, sizeof(salt),
NULL, 0, derivedKey, sizeof(derivedKey));
if ( ret != 0 ) {
// error generating derived key

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

@ -24,17 +24,17 @@
\param iterations number of times to process the hash
\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
\param hashType the hashing algorithm to use. Valid choices are WC_MD5 and WC_SHA
_Example_
\code
int ret;
byte key[MD5_DIGEST_SIZE];
byte key[WC_MD5_DIGEST_SIZE];
byte pass[] = { }; // initialize with password
byte salt[] = { }; // initialize with salt
ret = wc_PBKDF1(key, pass, sizeof(pass), salt, sizeof(salt), 1000,
sizeof(key), MD5);
sizeof(key), WC_MD5);
if ( ret != 0 ) {
// error deriving key from password
}
@ -53,8 +53,9 @@ int wc_PBKDF1(byte* output, const byte* passwd, int pLen,
\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
to select any of the supported HMAC hash functions, including: WC_MD5,
WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256,
WC_SHA3_384 or WC_SHA3_512
\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
@ -72,8 +73,9 @@ int wc_PBKDF1(byte* output, const byte* passwd, int pLen,
\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,
SHA, SHA256, SHA384, SHA512, and BLAKE2B
\param hashType the hashing algorithm to use. Valid choices are: WC_MD5,
WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256,
WC_SHA3_384 or WC_SHA3_512
_Example_
\code
@ -83,7 +85,7 @@ int wc_PBKDF1(byte* output, const byte* passwd, int pLen,
byte salt[] = { }; // initialize with salt
ret = wc_PBKDF2(key, pass, sizeof(pass), salt, sizeof(salt), 2048, sizeof(key),
SHA512);
WC_SHA512);
if ( ret != 0 ) {
// error deriving key from password
}
@ -103,7 +105,8 @@ int wc_PBKDF2(byte* output, const byte* passwd, int pLen,
(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.
functions, including: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512,
WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512
\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,
@ -135,9 +138,10 @@ int wc_PBKDF2(byte* output, const byte* passwd, int pLen,
\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,
SHA, SHA256, SHA384, SHA512, and BLAKE2B
\param id this is a byte indetifier indicating the purpose of key
\param hashType the hashing algorithm to use. Valid choices 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 id this is a byte identifier 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
@ -152,7 +156,7 @@ int wc_PBKDF2(byte* output, const byte* passwd, int pLen,
byte salt[] = { }; // initialize with salt
ret = wc_PKCS512_PBKDF(key, pass, sizeof(pass), salt, sizeof(salt), 2048,
sizeof(key), SHA512, 1);
sizeof(key), WC_SHA512, 1);
if ( ret != 0 ) {
// error deriving key from password
}