Merge pull request #5454 from dgarske/docs_hashtype

Improve the documentation for HMAC hash types

doc/dox_comments/header_files/asn_public.h

@@ -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,
+    depending on build configuration, include: WC_MD5, WC_SHA, WC_SHA256,
-    SHA384, and SHA512.
+    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
     }

doc/dox_comments/header_files/hmac.h

@@ -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
+    \return BAD_FUNC_ARG Returned if the input type is invalid (see type param)
-    are: MD5, SHA, SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384,
-    SHA3-512
     \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,
+    should use. Valid options are: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384,
-    SHA3-256, SHA3-384, SHA3-512
+    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
+    \return BAD_FUNC_ARG Returned if an invalid hash type is given (see type param)
-    argument. Valid types are: MD5, SHA, SHA256, SHA384, SHA512, SHA3-224,
-    SHA3-256, SHA3-384, SHA3-512
     \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,
+    \param type hash type to use for the HKDF. Valid types are: WC_MD5, WC_SHA,
-    SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512
+    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

doc/dox_comments/header_files/pwdbased.h

@@ -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,
+    to select any of the supported HMAC hash functions, including: WC_MD5,
-    SHA256, SHA384, SHA512, and BLAKE2B
+    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,
+    \param hashType the hashing algorithm to use. Valid choices are: WC_MD5,
-    SHA, SHA256, SHA384, SHA512, and BLAKE2B
+    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,
+    \param hashType the hashing algorithm to use. Valid choices are: WC_MD5,
-    SHA, SHA256, SHA384, SHA512, and BLAKE2B
+    WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256,
-    \param id this is a byte indetifier indicating the purpose of key
+    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
     }