HMAC_HexFromBytes

CryptoSys PKI Pro Manual

HMAC_HexFromBytes

Creates a keyed-hash based message authentication code (HMAC) in hexadecimal format from byte data. The hash algorithm to use is passed in the options parameter.

VBA/VB6 Syntax


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

nRet = HMAC_HexFromBytes(strOutput, nOutChars, lpMessage(0), nMsgLen, lpKey(0), nKeyLen, nOptions)

C/C++ Syntax


long __stdcall HMAC_HexFromBytes(char *szOutput, long nOutChars, const void *lpMessage, long nMsgLen, const void *lpKey, long nKeyLen, long nOptions);

Parameters

szOutput: [out] to receive output in hexadecimal format.
nOutChars: [in] specifying the maximum number of characters to be received.
lpMessage: [in] array containing the message data in a byte array
nMsgLen: [in] specifying length of the message data in bytes.
lpKey: [in] array containing the key in a byte array
nKeyLen: [in] specifying length of the key 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

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 hmacHexFromBytes (lpMessage() As Byte, lpKey() As Byte, nOptions As Long) As String

.NET Equivalent

Hmac.HexFromBytes Method

C++ (STL) Equivalent

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

Python Equivalent

static Hmac.hex_from_data(data, key, 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). C/C++ users should add one to this value when allocating memory. The final digest will be truncated to the specified length if less than the expected size. MD2 is not available with the HMAC functions.

Examples

Dim strData As String
Dim strKey As String
Dim abData() As Byte
Dim abKey() As Byte
Dim nDataLen As Long
Dim nKeyLen As Long
Dim strDigest As String
Dim nRet As Long

' Test case 2 from RFC 2202 and RFC 4231
strData = "what do ya want for nothing?"
strKey = "Jefe"

' Convert message and key into Byte format
abData = StrConv(strData, vbFromUnicode)
abKey = StrConv(strKey, vbFromUnicode)
nDataLen = UBound(abData) - LBound(abData) + 1
nKeyLen = UBound(abKey) - LBound(abKey) + 1

' Dimension the output string to receive the digest
strDigest = String(PKI_MAX_HASH_CHARS, " ")

' Compute default HMAC (HMAC-SHA-1)
nRet = HMAC_HexFromBytes(strDigest, Len(strDigest), abData(0), nDataLen, abKey(0), nKeyLen, 0)
If nRet <= 0 Then Exit Sub ' ERROR
strDigest = Left(strDigest, nRet)
Debug.Print "HMAC-SHA-1  =" & strDigest
Debug.Print "CORRECT     =" & "effcdf6ae5eb2fa2d27416d5f184df9c259a7c79"

' Compute HMAC-MD5
strDigest = String(PKI_MAX_HASH_CHARS, " ")
nRet = HMAC_HexFromBytes(strDigest, Len(strDigest), abData(0), nDataLen, abKey(0), nKeyLen, PKI_HASH_MD5)
If nRet <= 0 Then Exit Sub ' ERROR
strDigest = Left(strDigest, nRet)
Debug.Print "HMAC-MD5    =" & strDigest
Debug.Print "CORRECT     =" & "750c783e6ab0b503eaa86e310a5db738"

' Compute HMAC-SHA-256
strDigest = String(PKI_MAX_HASH_CHARS, " ")
nRet = HMAC_HexFromBytes(strDigest, Len(strDigest), abData(0), nDataLen, abKey(0), nKeyLen, PKI_HASH_SHA256)
If nRet <= 0 Then Exit Sub ' ERROR
strDigest = Left(strDigest, nRet)
Debug.Print "HMAC-SHA-256=" & strDigest
Debug.Print "CORRECT     =" & "5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843"

' Compute HMAC-SHA-512
strDigest = String(PKI_MAX_HASH_CHARS, " ")
nRet = HMAC_HexFromBytes(strDigest, Len(strDigest), abData(0), nDataLen, abKey(0), nKeyLen, PKI_HASH_SHA512)
If nRet <= 0 Then Exit Sub ' ERROR
strDigest = Left(strDigest, nRet)
Debug.Print "HMAC-SHA-512=" & strDigest
Debug.Print "CORRECT     =" _
& "164b7a7bfcf819e2e395fbe73b56e0a387bd64222e831fd610270cd7ea250554" _
& "9758bf75c05a994a6d034f65f8f0e6fdcaeab1a34d4a6b4b636e070a38bce737" _

The above example should produce the following output:

HMAC-SHA-1  =effcdf6ae5eb2fa2d27416d5f184df9c259a7c79
CORRECT     =effcdf6ae5eb2fa2d27416d5f184df9c259a7c79
HMAC-MD5    =750c783e6ab0b503eaa86e310a5db738
CORRECT     =750c783e6ab0b503eaa86e310a5db738
HMAC-SHA-256=5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843
CORRECT     =5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843
HMAC-SHA-512=164b7a7bfcf819e2e395fbe73b56e0a387bd64222e831fd610270cd7ea250554
9758bf75c05a994a6d034f65f8f0e6fdcaeab1a34d4a6b4b636e070a38bce737
CORRECT     =164b7a7bfcf819e2e395fbe73b56e0a387bd64222e831fd610270cd7ea250554
9758bf75c05a994a6d034f65f8f0e6fdcaeab1a34d4a6b4b636e070a38bce737

Example (VBA wrapper function)

Dim strDigest As String
Dim lpMessage() As Byte
Dim lpDigest() As Byte
Dim lpKey() As Byte
lpKey = cnvBytesFromHexStr("0102030405060708090a0b0c0d0e0f10111213141516171819")
lpDigest = hmacBytes(lpMessage, lpKey, PKI_HASH_SHA256)
Debug.Print cnvHexStrFromBytes(lpDigest)
lpDigest = hmacBytes(lpMessage, lpKey, PKI_HASH_SHA256)
Debug.Print cnvHexStrFromBytes(lpDigest)
strDigest = hmacHexFromBytes(lpMessage, lpKey, PKI_HASH_SHA256)
Debug.Print strDigest
strDigest = hmacHexFromBytes(lpMessage, lpKey, PKI_HASH_SHA512)
Debug.Print strDigest
strDigest = hmacHexFromBytes(lpMessage, lpKey, PKI_HASH_SHA512)
Debug.Print strDigest