HASH_HexFromBytes

CryptoSys PKI Pro Manual

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


Public Declare Function HASH_HexFromBytes Lib "diCrPKI.dll" 
(ByVal strOutput As String, ByVal nOutChars As Long, ByRef lpMessage As Byte, ByVal nMsgLen As Long, 
ByVal nOptions As Long) As Long

Alternative for VB6/VBA only:-
Public Declare Function HASH_HexFromString Lib "diCrPKI.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, lpMessage(0), nMsgLen, nOptions) nRet = HASH_HexFromString(strOutput, nOutChars, strMessage, nMsgLen, nOptions)

C/C++ Syntax


long __stdcall HASH_HexFromBytes(char *szOutput, long nOutChars, const void *lpMessage, long nMsgLen, long nOptions);

Parameters

szOutput: [out] to receive hash digest in hexadecimal format.
nOutChars: [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:
PKI_HASH_SHA1 (0) to use the SHA-1 algorithm (default)
PKI_HASH_SHA224 to use the SHA-224 algorithm
PKI_HASH_SHA256 to use the SHA-256 algorithm
PKI_HASH_SHA384 to use the SHA-384 algorithm
PKI_HASH_SHA512 to use the SHA-512 algorithm
PKI_HASH_SHA3_224 to use the SHA-3-224 algorithm
PKI_HASH_SHA3_256 to use the SHA-3-256 algorithm
PKI_HASH_SHA3_384 to use the SHA-3-384 algorithm
PKI_HASH_SHA3_512 to use the SHA-3-512 algorithm
PKI_HASH_MD5 to use the MD5 algorithm
PKI_HASH_MD2 to use the MD2 algorithm (legacy applications)
PKI_HASH_RMD160 to use the RIPEMD-160 algorithm
PKI_HASH_BTC160 to use the Bitcoin160 algorithm, RIPEMD160(SHA256(m))
and optionally add
PKI_HASH_DOUBLE to compute a double hash, HASH(HASH(m))

Returns (VBA/C)

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

VBA Wrapper Syntax

Public Function hashHexFromBytes (lpMessage() As Byte, nOptions As Long) As String

.NET Equivalent

Hash.HexFromBytes Method
Hash.HexFromString Method

C++ (STL) Equivalent

static std::string dipki::Hash::HexFromBytes (const bvec_t &data, Alg alg=Alg::Sha1)

Python Equivalent

static Hash.hex_from_data(data, alg=Alg.SHA1)

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. ANSI C users must add one to this value when allocating memory.

The maximum number of output characters is PKI_MAX_HASH_CHARS (C/C++ users add one). The final digest will be truncated to the specified length if less than the expected size.

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(PKI_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, PKI_HASH_SHA1)
Debug.Print nRet, Left(sDigest, nRet)
' Pre-dimension digest string and use MD5
sDigest = String(PKI_MD5_CHARS, " ")
nRet = HASH_HexFromBytes(sDigest, Len(sDigest), abMessage(0), 3, PKI_HASH_MD5)
Debug.Print nRet, sDigest
' Pre-dimension digest string and use MD2
sDigest = String(PKI_MD5_CHARS, " ")
nRet = HASH_HexFromBytes(sDigest, Len(sDigest), abMessage(0), 3, PKI_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, PKI_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 nonzero ANSI characters):

long lRet;
char szDigest[PKI_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), PKI_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), PKI_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 strDigest As String
Dim lpMessage() As Byte
Dim lpDigest() As Byte

' Hex <-- Hex
strDigest = hashHexFromHex("616263", PKI_HASH_SHA256)   ' "abc" in hex
Debug.Print strDigest
lpMessage = StrConv("abc", vbFromUnicode)   ' "abc" in a byte array
' Hex <-- Bytes
strDigest = hashHexFromBytes(lpMessage, PKI_HASH_SHA256)
Debug.Print strDigest
' Bytes <-- Bytes
lpDigest = hashBytes(lpMessage, PKI_HASH_SHA256)
Debug.Print cnvHexStrFromBytes(lpDigest)
' Hex <-- File
strDigest = hashHexFromFile("abc.txt", PKI_HASH_SHA256) ' "abc" in a text file
Debug.Print strDigest
' Bytes <-- File
lpDigest = hashFile("abc.txt", PKI_HASH_SHA256)
Debug.Print cnvHexStrFromBytes(lpDigest)
Debug.Print "OK=" & "BA7816BF8F01CFEA414140DE5DAE2223B00361A396177A9CB410FF61F20015AD"

Dim strData As String
Dim strDigest As String
' Our original string data
strData = "Estándares de Electrónica de México para mañana"
' Compute SHA-1 hash over UTF-8 encoded byte array
strDigest = hashHexFromBytes(cnvUTF8BytesFromLatin1(strData), PKI_HASH_SHA1)
Debug.Print "Digest=" & strDigest