MAC_HexFromBytes

CryptoSys API Library Manual

MAC_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 MAC_HexFromBytes Lib "diCryptoSys.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 = MAC_HexFromBytes(strOutput, nOutChars, abMessage(0), nMsgLen, abKey(0), nKeyLen, nOptions)

C/C++ Syntax


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

Parameters

szOutput: [out] to receive output in hexadecimal format.
nMaxChars: [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:
HMAC algorithms:
API_HMAC_SHA1 (0) to use the SHA-1 hash algorithm (default)
API_HMAC_SHA224 to use the SHA-224 algorithm
API_HMAC_SHA256 to use the SHA-256 algorithm
API_HMAC_SHA384 to use the SHA-384 algorithm
API_HMAC_SHA512 to use the SHA-512 algorithm
API_HMAC_MD5 to use the MD5 algorithm
API_HMAC_RMD160 to use the RIPEMD-160 algorithm
API_HMAC_SHA3_224 to use the SHA-3-224 algorithm
API_HMAC_SHA3_256 to use the SHA-3-256 algorithm
API_HMAC_SHA3_384 to use the SHA-3-384 algorithm
API_HMAC_SHA3_512 to use the SHA-3-512 algorithm
CMAC algorithms:
API_CMAC_TDEA to use the Triple DES (DES-EDE) block cipher
API_CMAC_AES128 to use the AES-128 block cipher
API_CMAC_AES192 to use the AES-192 block cipher
API_CMAC_AES256 to use the AES-256 block cipher
Other:
API_MAC_POLY1305 to use the Poly1305 algorithm [New in v5.0]
API_KMAC_128 to use KMAC128 with a fixed-length output of 256 bits (32 bytes) [New in v5.3]
API_KMAC_256 to use KMAC256 with a fixed-length output of 512 bits (64 bytes) [New in v5.3]

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


Public Function macHexFromBytes(lpMessage() As Byte, lpKey() As Byte, nOptions As Long) As String

.NET Equivalent

Mac.HexFromBytes Method

Python Equivalent

static Mac.hex_from_data(data, key, alg=Alg.HMAC_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 of the output string. C/C++ users must add one to this value when allocating memory. The maximum number of characters is API_MAX_MAC_CHARS. The final digest will be truncated to the specified length if less than the expected size (except for KMAC which must not be truncated).

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(API_MAX_HASH_CHARS, " ")

' Compute default HMAC (HMAC-SHA-1)
nRet = MAC_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(API_MAX_HASH_CHARS, " ")
nRet = MAC_HexFromBytes(strDigest, Len(strDigest), abData(0), nDataLen, abKey(0), nKeyLen, API_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(API_MAX_HASH_CHARS, " ")
nRet = MAC_HexFromBytes(strDigest, Len(strDigest), abData(0), nDataLen, abKey(0), nKeyLen, API_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(API_MAX_HASH_CHARS, " ")
nRet = MAC_HexFromBytes(strDigest, Len(strDigest), abData(0), nDataLen, abKey(0), nKeyLen, API_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 lpMessage() As Byte
Dim lpKey() As Byte
lpMessage = StrConv("what do ya want for nothing?", vbFromUnicode)
lpKey = StrConv("Jefe", vbFromUnicode)

Debug.Print "OK:" & vbCrLf & "5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843"
Debug.Print macHexFromBytes(lpMessage, lpKey, API_HMAC_SHA256)
Debug.Print macHexFromHex(cnvHexStrFromBytes(lpMessage), cnvHexStrFromBytes(lpKey), API_HMAC_SHA256)
Debug.Print cnvHexStrFromBytes(macBytes(lpMessage, lpKey, API_HMAC_SHA256))