MAC_Bytes

Creates a keyed message authentication code (MAC) as a byte array from byte data. The MAC algorithm to use is passed in the options parameter.

VBA/VB6 Syntax

nRet = MAC_Bytes(lpOutput(0), nOutBytes, abMessage(0), nMsgLen, abKey(0), nKeyLen, nOptions) ' Note the "(0)" after the byte array parameters


C/C++ Syntax

Parameters

lpOutput

[out] byte buffer to receive the MAC value.

nOutBytes

[in] size of output buffer in bytes.

lpMessage

[in] byte array containing the message (input) data

nMsgLen

[in] length of the input data in bytes.

lpKey

[in] byte array containing the key

nKeyLen

[in] length of the key in bytes.

nOptions

[in] Option flags. Select one of:
HMAC algorithms:
API_HMAC_SHA1 (0) to use HMAC-SHA-1 (default)
API_HMAC_SHA224 to use HMAC-SHA-224
API_HMAC_SHA256 to use HMAC-SHA-256
API_HMAC_SHA384 to use HMAC-SHA-384
API_HMAC_SHA512 to use HMAC-SHA-512
API_HMAC_MD5 to use HMAC-MD5 (legacy)
API_HMAC_RMD160 to use HMAC-RIPEMD160
API_HMAC_SHA3_224 to use HMAC-SHA3-224
API_HMAC_SHA3_256 to use HMAC-SHA3-256
API_HMAC_SHA3_384 to use HMAC-SHA3-384
API_HMAC_SHA3_512 to use HMAC-SHA3-512
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 bytes in the output array; otherwise it returns a negative error code.

VBA Wrapper Syntax

.NET Equivalent

Mac.BytesFromBytes Method

Python Equivalent

Remarks

Specify a zero nOutBytes parameter to find out the required length of the output array. The maximum possible output length is API_MAX_MAC_BYTES. The final MAC value will be truncated to the specified length if less than the expected size (except for KMAC which must not be truncated).

To use KMAC with variable-length output or a customization string, use PRF_Bytes.

Example (VBA core function)

Dim abData() As Byte
Dim abKey() As Byte
Dim nDataLen As Long
Dim nKeyLen As Long
Dim abDigest() As Byte
Dim nDigLen As Long
Dim nRet As Long
Dim i As Long

' Test case 4 from RFC 2202 and RFC 4231
' key =           0x0102030405060708090a0b0c0d0e0f10111213141516171819
' key_len         25
' data =          0xcd repeated 50 times
' data_len =      50

nKeyLen = 25
ReDim abKey(nKeyLen - 1)
For i = 0 To nKeyLen - 1
    abKey(i) = CByte(i + 1)
Next
Debug.Print "Key=" & cnvHexStrFromBytes(abKey)
nDataLen = 50
ReDim abData(nDataLen - 1)
For i = 0 To nDataLen - 1
    abData(i) = &HCD
Next

' Compute default HMAC (HMAC-SHA-1)
nDigLen = API_SHA1_BYTES
ReDim abDigest(nDigLen - 1)
nRet = MAC_Bytes(abDigest(0), nDigLen, abData(0), nDataLen, abKey(0), nKeyLen, API_HASH_SHA1)
If nRet <= 0 Then Exit Sub ' ERROR
Debug.Print "HMAC-SHA-1  =" & cnvHexStrFromBytes(abDigest)
Debug.Print "CORRECT     =" & "4c9007f4026250c6bc8414f9bf50c86c2d7235da"

' Compute HMAC-MD5
nDigLen = API_MD5_BYTES
ReDim abDigest(nDigLen - 1)
nRet = MAC_Bytes(abDigest(0), nDigLen, abData(0), nDataLen, abKey(0), nKeyLen, API_HASH_MD5)
If nRet <= 0 Then Exit Sub ' ERROR
Debug.Print "HMAC-MD5    =" & cnvHexStrFromBytes(abDigest)
Debug.Print "CORRECT     =" & "697eaf0aca3a3aea3a75164746ffaa79"

' Compute HMAC-SHA-256
nDigLen = API_SHA256_BYTES
ReDim abDigest(nDigLen - 1)
nRet = MAC_Bytes(abDigest(0), nDigLen, abData(0), nDataLen, abKey(0), nKeyLen, API_HASH_SHA256)
If nRet <= 0 Then Exit Sub ' ERROR
Debug.Print "HMAC-SHA-256=" & cnvHexStrFromBytes(abDigest)
Debug.Print "CORRECT     =" & "82558a389a443c0ea4cc819899f2083a85f0faa3e578f8077a2e3ff46729665b"

The above example should produce the following output:

Key=0102030405060708090A0B0C0D0E0F10111213141516171819
HMAC-SHA-1  =4C9007F4026250C6BC8414F9BF50C86C2D7235DA
CORRECT     =4c9007f4026250c6bc8414f9bf50c86c2d7235da
HMAC-MD5    =697EAF0ACA3A3AEA3A75164746FFAA79
CORRECT     =697eaf0aca3a3aea3a75164746ffaa79
HMAC-SHA-256=82558A389A443C0EA4CC819899F2083A85F0FAA3E578F8077A2E3FF46729665B
CORRECT     =82558a389a443c0ea4cc819899f2083a85f0faa3e578f8077a2e3ff46729665b

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_HexFromBytes

[Contents] [Index]