MAC_HexFromBytes

CryptoSys API Library Manual

MAC_HexFromBytes

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.

VB6/VBA Syntax


Public Declare Function MAC_HexFromBytes Lib "diCryptoSys.dll" 
(ByVal strOutput As String, ByVal nOutChars As Long, ByRef abMessage As Byte, 
ByVal nMsgLen As Long, ByRef abKey As Byte, ByVal nKeyLen As Long, ByVal nOptions As Long) As Long

nRet = MAC_HexFromBytes(strOutput, nOutChars, abMessage(0), nMsgLen, abKey(0), nKeyLen, nOptions)

Parameters

strOutput: [out] String to receive output in hexadecimal format.
nOutChars: [in] Long specifying the maximum number of characters to be received.
abMessage: [in] Byte array containing the message data in a byte array
nMsgLen: [in] Long specifying length of the message data in bytes.
abKey: [in] Byte array containing the key in a byte array
nKeyLen: [in] Long specifying length of the key in bytes.
nOptions: [in] Long Option flags. Select one of:
HMAC algorithms:
API_HASH_SHA1 (0) to use the SHA-1 hash algorithm (default)
API_HASH_MD5 to use the MD5 algorithm
API_HASH_RMD160 to use the RIPEMD-160 algorithm
API_HASH_SHA224 to use the SHA-224 algorithm
API_HASH_SHA256 to use the SHA-256 algorithm
API_HASH_SHA384 to use the SHA-384 algorithm
API_HASH_SHA512 to use the SHA-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

C/C++ Syntax


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

Returns (VB6/C)

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

.NET Equivalent

Mac.HexFromBytes Method

Remarks

Specify a zero nOutChars or an empty ("") or NULL strOutput parameter to find out the required length of the output string. The maximum number of characters is API_MAX_HASH_CHARS. Hint: SHA-1 requires 40 characters. C/C++ users should add one to this value before allocating memory. The final digest will be truncated to the specified length if less than the expected size. Only lower-case letters [a-f] are used. 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(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