HASH_HexFromBits

CryptoSys API Library Manual

HASH_HexFromBits

Creates a message digest hash in hexadecimal format from bit-oriented input. The hash algorithm to use is passed in the options parameter.

VBA/VB6 Syntax


Public Declare Function HASH_HexFromBits Lib "diCryptoSys.dll" (ByVal strOutput As String, ByVal nMaxChars As Long, ByRef lpData As Byte, 
ByVal nDataBitLen As Long, ByVal nOptions As Long) As Long

nRet = HASH_HexFromBits(strOutput, nOutChars, abData(0), nDataBitLen, nOptions)

C/C++ Syntax


long __stdcall  HASH_HexFromBits(char *szOutput, long nMaxChars, const unsigned char *lpData, long nDataBitLen, long nOptions);

Parameters

szOutput: [out] to receive hash digest in hexadecimal format.
nMaxChars: [in] specifying the maximum number of characters to be received.
lpData: [in] array containing the message data
nDataBitLen: [in] specifying length of the message data in bits.
nOptions: [in] Option flags. Select one of:
API_HASH_SHA1 (0) to use the SHA-1 algorithm (default)
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
API_HASH_SHA3_224 to use the SHA-3-224 algorithm
API_HASH_SHA3_256 to use the SHA-3-256 algorithm
API_HASH_SHA3_384 to use the SHA-3-384 algorithm
API_HASH_SHA3_512 to use the SHA-3-512 algorithm

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 hashHexFromBits(lpData() As Byte, nDataBitLen As Long, nOptions As Long) As String

.NET Equivalent

Hash.HexFromBits Method

Python Equivalent

static Hash.hex_from_bits(data, databitlen, alg=Alg.SHA1)

Remarks

Pass a bitstring as an array of bytes in lpData in big-endian order with the most-significant bit first. The bitstring will be truncated to the number of bits specified in nDataBitlen and extraneous bits on the right will be ignored.

For example, the byte array (0x)717F8C with nDataBitLen=23 represents the 23-bit bitstring 0111 0001 0111 1111 1000 110, and the byte array (0x)5180 with nDataBitLen=9 represents the 9-bit bitstring 0101 0001 1.

The number of bytes in the array lpData must be at least ceil(nDataBitLen / 8). Only the SHA family of hash functions is supported in bit-oriented mode.

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 ("") or NULL szOutput parameter to find out the required length of the output string (or use the appropriate API_SHAnnn_CHARS constant). C/C++ users must add one to this value when allocating memory.

Example (VBA core function)

Dim strDigest As String
Dim nRet As Long
Dim abData() As Byte
Dim nDataBitLen As Long

' SHA-1
strDigest = String(API_SHA1_CHARS, " ")
abData = cnvBytesFromHexStr("5180")
nDataBitLen = 9
Debug.Print "[SHA-1]"
Debug.Print "[L = " & API_SHA1_BYTES & "]"
Debug.Print "Len = " & nDataBitLen
Debug.Print "Msg = " & cnvHexStrFromBytes(abData)
nRet = HASH_HexFromBits(strDigest, Len(strDigest), abData(0), nDataBitLen, API_HASH_SHA1)
Debug.Print "MD = " & strDigest

The above example should produce the following output:

[SHA-1]
[L = 20]
Len = 9
Msg = 5180
MD = 0f582fa68b71ecdf1dcfc4946019cf5a18225bd2

This example uses SHA-3-256 on a 22-bit message from the NIST SHAVS-SHA3 test vectors. Note that the convention for representing bit strings in hex used by NIST is different from our big-endian convention. For more details see Notes on SHA-3.

' Ref: SHAVS-SHA3 CAVS 19.0 "SHA3-256 ShortMsg" information for "SHA3AllBits1-28-16"
' Len = 22
' Msg = 259028*
' MD = d5863d4b1ff41551c92a9e08c52177e32376c9bd100c611c607db840096eb22f

' * NB NIST convention for bit strings is different from CryptoSys API
' NIST "259028" => API "2590A0"

Dim strDigest As String
Dim nRet As Long
Dim abData() As Byte
Dim nDataBitLen As Long

strDigest = String(API_SHA256_CHARS, " ")
abData = cnvBytesFromHexStr("2590A0")
nDataBitLen = 22
Debug.Print "[L = " & API_SHA256_BYTES * 8 & "]"
Debug.Print "Len = " & nDataBitLen
Debug.Print "Msg = " & cnvHexStrFromBytes(abData)
nRet = HASH_HexFromBits(strDigest, Len(strDigest), abData(0), nDataBitLen, API_HASH_SHA3_256)
Debug.Print "MD = " & strDigest

[L = 256]
Len = 22
Msg = 2590A0
MD = d5863d4b1ff41551c92a9e08c52177e32376c9bd100c611c607db840096eb22f

Example (VBA wrapper function)

Dim strDigest As String
Dim lpData() As Byte

' SHA-1
lpData = cnvBytesFromHexStr("5180")
strDigest = hashHexFromBits(lpData, 9, API_HASH_SHA1)
Debug.Print "MD = " & strDigest
Debug.Print "OK = 0f582fa68b71ecdf1dcfc4946019cf5a18225bd2"

' SHAVS-SHA3 CAVS 19.0 "SHA3-256 ShortMsg"
lpData = cnvBytesFromHexStr("2590A0")
strDigest = hashHexFromBits(lpData, 22, API_HASH_SHA3_256)
Debug.Print "MD = " & strDigest
Debug.Print "OK = d5863d4b1ff41551c92a9e08c52177e32376c9bd100c611c607db840096eb22f"