HASH_HexFromBytes

Creates a message digest hash in hexadecimal format from byte (or string) data. The hash algorithm to use is passed in the options parameter.

VBA/VB6 Syntax

Alternative for Visual Basic (VB6/VBA) only:-
Public Declare Function HASH_HexFromString Lib "diCryptoSys.dll" Alias "HASH_HexFromBytes" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strMessage As String, ByVal nMsgLen As Long, ByVal nOptions As Long) As Long

nRet = HASH_HexFromBytes(strOutput, nOutChars, abMessage(0), nMsgLen, nOptions)
nRet = HASH_HexFromString(strOutput, nOutChars, strMessage, nMsgLen, nOptions)

C/C++ Syntax

Parameters

szOutput

[out] to receive hash digest in hexadecimal format.

nMaxChars

[in] specifying the maximum number of characters to be received.

lpMessage

[in] array containing the message data; or

nMsgLen

[in] specifying length of the message data in bytes.

nOptions

[in] Option flags. Select one of:
API_HASH_SHA1 (0) to use the SHA-1 algorithm (default)
API_HASH_SHA224 to use the SHA-224 algorithm
API_HASH_SHA256 to use the SHA-256 algorithm
API_HASH_SHA384 to use the SHA-384 algorithm
API_HASH_SHA512 to use the SHA-512 algorithm
API_HASH_MD5 to use the MD5 algorithm
API_HASH_MD2 to use the MD2 algorithm (legacy)
API_HASH_RMD160 to use the RIPEMD-160 algorithm
API_HASH_SHA3_224 to use the SHA-3-224 algorithm
API_HASH_SHA3_256 to use the SHA-3-256 algorithm
API_HASH_SHA3_384 to use the SHA-3-384 algorithm
API_HASH_SHA3_512 to use the SHA-3-512 algorithm
API_HASH_ASCON_HASH to use the ASCON-HASH algorithm
API_HASH_ASCON_HASHA to use the ASCON-HASHA algorithm

Returns (VBA/C)

If successful, the return value is the number of characters in the output string; otherwise it returns a negative error code.

VBA Wrapper Syntax

.NET Equivalent

Hash.HexFromBytes Method
Hash.HexFromString Method

Python Equivalent

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length of the output string. C/C++ users must add one to this value when allocating memory. The maximum number of characters is API_MAX_HASH_CHARS. The final digest will be truncated to the specified length if less than the expected size. Only lower-case letters [a-f] are used in the output string.

Examples

Dim nRet As Long
Dim sDigest As String
Dim abMessage() As Byte
' Set up message to be hashed in unambiguous Byte format
abMessage = StrConv("abc", vbFromUnicode)
' Pre-dimension digest string
sDigest = String(API_MAX_HASH_CHARS, " ")
' Create default hash (SHA1)
nRet = HASH_HexFromBytes(sDigest, Len(sDigest), abMessage(0), 3, 0)
Debug.Print nRet, Left(sDigest, nRet)
' Explicitly use SHA1
nRet = HASH_HexFromBytes(sDigest, Len(sDigest), abMessage(0), 3, API_HASH_SHA1)
Debug.Print nRet, Left(sDigest, nRet)
' Pre-dimension digest string and use MD5
sDigest = String(API_MD5_CHARS, " ")
nRet = HASH_HexFromBytes(sDigest, Len(sDigest), abMessage(0), 3, API_HASH_MD5)
Debug.Print nRet, sDigest
' Pre-dimension digest string and use MD2
sDigest = String(API_MD5_CHARS, " ")
nRet = HASH_HexFromBytes(sDigest, Len(sDigest), abMessage(0), 3, API_HASH_MD2)
Debug.Print nRet, sDigest
' Make output string shorter - only get back that many chars
sDigest = String(16, " ")
nRet = HASH_HexFromBytes(sDigest, Len(sDigest), abMessage(0), 3, API_HASH_SHA1)
Debug.Print nRet, sDigest

The above example should produce the following output:

 40 a9993e364706816aba3e25717850c26c9cd0d89d
 40 a9993e364706816aba3e25717850c26c9cd0d89d
 32 900150983cd24fb0d6963f7d28e17f72
 32 da853b0d3f88d99b30283a69e6ded6bb
 16 a9993e364706816a

Alternative using String type directly (assumes 8-bit ANSI characters in strMessage):

Dim nRet As Long
Dim sDigest As String
Dim strMessage As String

strMessage = "abc"
' Pre-dimension digest string
sDigest = String(40, " ")
' Create default hash (SHA1)
nRet = HASH_HexFromString(sDigest, Len(sDigest), strMessage, Len(strMessage), 0)
Debug.Print nRet, sDigest

Example in C code (in C we are less fussed about the distinction between char and unsigned char types when dealing with non-zero ANSI characters):

long lRet;
char szDigest[API_MAX_HASH_CHARS+1]; /* NB add one */
char message[] = "abc";

/* Compute default SHA-1 digest */
lRet = HASH_HexFromBytes(szDigest, sizeof(szDigest)-1, 
	(unsigned char*)message, strlen(message), 0);
assert(lRet > 0);
printf("SHA1('abc')=%s\n", szDigest);
/* Compute MD5 digest */
lRet = HASH_HexFromBytes(szDigest, sizeof(szDigest)-1, 
	(unsigned char*)message, strlen(message), API_HASH_MD5);
assert(lRet > 0);
printf("MD5('abc')=%s\n", szDigest);
/* Compute MD2 digest */
lRet = HASH_HexFromBytes(szDigest, sizeof(szDigest)-1, 
	(unsigned char*)message, strlen(message), API_HASH_MD2);
assert(lRet > 0);
printf("MD2('abc')=%s\n", szDigest);

This should produce the output

SHA1('abc')=a9993e364706816aba3e25717850c26c9cd0d89d
MD5('abc')=900150983cd24fb0d6963f7d28e17f72
MD2('abc')=da853b0d3f88d99b30283a69e6ded6bb

Example (VBA wrapper function)

Dim lpMessage() As Byte
lpMessage = StrConv("abc", vbFromUnicode)
Debug.Print "lpMessage=" & cnvHexStrFromBytes(lpMessage)

Debug.Print "OK:" & vbCrLf & "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
Debug.Print hashHexFromBytes(lpMessage, API_HASH_SHA256)
Debug.Print hashHexFromHex("616263", API_HASH_SHA256)
Debug.Print hashHexFromFile("abc.txt", API_HASH_SHA256)
Debug.Print cnvHexStrFromBytes(hashBytes(lpMessage, API_HASH_SHA256))
Debug.Print cnvHexStrFromBytes(hashFile("abc.txt", API_HASH_SHA256))

See Also

HASH_HexFromFile HASH_Bytes

[Contents] [Index]