MAC_HexFromHex

Creates a message authentication code (MAC) in hexadecimal format from hex-encoded data and a hex-encoded key. The MAC algorithm to use is passed in the options parameter.

VBA/VB6 Syntax

nRet = MAC_HexFromHex(strOutput, nOutChars, strMsgHex, strKeyHex, nOptions)


C/C++ Syntax

Parameters

szOutput

[out] to receive output in hexadecimal format.

nMaxChars

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

szMsgHex

[in] array containing the message data in hexadecimal-encoded format.

szKeyHex

[in] array containing the key in hexadecimal-encoded format.

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

.NET Equivalent

Mac.HexFromHex 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_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).

Example (VBA core function)

Dim strKeyHex As String
Dim strMsgHex As String
Dim strMAC As String
Dim nRet As Long

' SP800-38: compute CMAC_AES-128 on Example 2: Mlen = 128
strKeyHex = "2b7e151628aed2a6abf7158809cf4f3c"
strMsgHex = "6bc1bee22e409f96e93d7e117393172a"
' Output MAC size in hex is double the block length of the cipher
strMAC = String(API_BLK_AES_BYTES * 2, " ")
nRet = MAC_HexFromHex(strMAC, Len(strMAC), strMsgHex, strKeyHex, API_CMAC_AES128)
If nRet > 0 Then
    Debug.Print "CMAC-AES-128(K128, M128)=" & Left$(strMAC, nRet)
Else
    Debug.Print "Error code " & nRet
End If

This should produce the output

CMAC-AES-128(K128, M128)=070a16b46b4d4144f79bdd9dd04a287c

Example using Poly1305 algorithm.

' Ref: Test vector from `draft-irtf-cfrg-chacha20-poly1305-06.txt`
Dim nRet As Long
Dim strDigest As String
Dim strMsgHex As String

' Convert ASCII message string to hex format
strMsgHex = cnvHexStrFromString("Cryptographic Forum Research Group")
' Dimension digest string to receive 32 characters
strDigest = String(API_POLY1305_CHARS, " ")
' Create authentication tag using 256-bit key material
nRet = MAC_HexFromHex(strDigest, Len(strDigest), strMsgHex, _
    "85d6be7857556d337f4452fe42d506a80103808afb0db2fd4abff6af4149f51b", API_MAC_POLY1305)
Debug.Print "Poly1305 Tag: " & strDigest

This should produce the output

Poly1305 Tag: a8061dc1305136c6c22b8baf0c0127a9

Example using HMAC-SHA3-256.

' Ref: NIST Computer Security Division
' "Keyed-Hash Message Authentication Code (HMAC) - using SHA3-256"
' `HMAC_SHA3-256.pdf` 2016-03-28
Dim strText As String
Dim strKeyHex As String
Dim strMsgHex As String
Dim strMAC As String
Dim nLen As Long
'Sample #1 Block length = 136, Key length = 32, Tag length = 32
strText = "Sample message for keylen<blocklen"
strKeyHex = "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"
strMsgHex = cnvHexStrFromString(strText)
Debug.Print "Text is " & strMsgHex
Debug.Print "Key is " & strKeyHex
' Get required output length
nLen = MAC_HexFromHex("", 0, strMsgHex, strKeyHex, API_HASH_SHA3_256)
strMAC = String(nLen, " ")
nLen = MAC_HexFromHex(strMAC, Len(strMAC), strMsgHex, strKeyHex, API_HASH_SHA3_256)
Debug.Print "Mac is " & strMAC

Text is 53616D706C65206D65737361676520666F72206B65796C656E3C626C6F636B6C656E
Key is 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
Mac is 4fe8e202c4f058e8dddc23d8c34e467343e23555e24fc2f025d598f558f67205

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))

See Also

MAC_Bytes MAC_HexFromBytes

[Contents] [Index]