HASH_HexFromFile

CryptoSys API Library Manual

HASH_HexFromFile

Creates a message digest hash in hexadecimal format for a file. The hash algorithm to use is passed in the options parameter.

VBA/VB6 Syntax


Public Declare Function HASH_HexFromFile Lib "diCryptoSys.dll" 
(ByVal strOutput As String, ByVal nOutChars As Long, ByVal strFileName As String, 
ByVal nOptions As Long) As Long

nRet = HASH_HexFromFile(strOutput, nOutChars, strFileName, nOptions)

C/C++ Syntax


long __stdcall  HASH_HexFromFile(char *szOutput, long nMaxChars, const char *szFileName, long nOptions);

Parameters

szOutput: [out] to receive hash digest in hexadecimal format.
nMaxChars: [in] specifying the maximum number of characters to be received in characters.
szFileName: [in] containing the name of the file.
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_MD5 to use the MD5 algorithm
API_HASH_MD2 to use the MD2 algorithm (legacy)
API_HASH_RMD160 to use the RIPEMD-160 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
and add
API_HASH_MODE_TEXT to hash in "text" mode instead of default "binary" mode

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 hashHexFromFile(szFileName As String, nOptions As Long) As String

.NET Equivalent

Hash.HexFromFile Method

Python Equivalent

static Hash.hex_from_file(filename, alg=Alg.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 will be API_MAX_HASH_CHARS. 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.

Add the option API_HASH_MODE_TEXT to work in "text" mode where CR-LF pairs are treated as a single newline character. The default mode is "binary" where each byte is treated individually. Only ANSI file names and paths are supported (but see CNV_ShortPathName as a work around). Note that Ascon-Hash is not available with this function.

Examples

Dim nRet As Long
Dim sDigest As String
Dim sFileName As String

' File to be hashed contains a total of 13 bytes: "hello world" plus CR-LF
' 68 65 6c 6c 6f 20 77 6f 72 6c 64 0d 0a   hello world..

sFileName = "C:\Test\hello.txt"

' Pre-dimension digest string
sDigest = String(API_MAX_HASH_CHARS, " ")

' Create default hash (SHA1) in binary mode
nRet = HASH_HexFromFile(sDigest, Len(sDigest), sFileName, 0)
Debug.Print nRet, Left(sDigest, nRet)
' Use SHA1 in "text" mode
nRet = HASH_HexFromFile(sDigest, Len(sDigest), sFileName, API_HASH_MODE_TEXT)
Debug.Print nRet, Left(sDigest, nRet)
' Use MD5
nRet = HASH_HexFromFile(sDigest, Len(sDigest), sFileName, API_HASH_MD5)
Debug.Print nRet, Left(sDigest, nRet)
' Use MD5 in "text" mode
nRet = HASH_HexFromFile(sDigest, Len(sDigest), sFileName, API_HASH_MD5 Or API_HASH_MODE_TEXT)
Debug.Print nRet, Left(sDigest, nRet)

This should produce the following output:

 40           88a5b867c3d110207786e66523cd1e4a484da697
 40           22596363b3de40b06f981fb85d82312e8c0ed511
 32           a0f2a3c1dcd5b1cac71bf0c03f2ff1bd
 32           6f5902ac237024bdd0c176cb93063dc4

Example (VBA wrapper function)

Dim lpMessage() As Byte
lpMessage = StrConv("abc", vbFromUnicode)
Debug.Print "lpMessage=" & cnvHexStrFromBytes(lpMessage)

Debug.Print "OK:" & vbCrLf & "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
Debug.Print hashHexFromBytes(lpMessage, API_HASH_SHA256)
Debug.Print hashHexFromHex("616263", API_HASH_SHA256)
Debug.Print hashHexFromFile("abc.txt", API_HASH_SHA256)
Debug.Print cnvHexStrFromBytes(hashBytes(lpMessage, API_HASH_SHA256))
Debug.Print cnvHexStrFromBytes(hashFile("abc.txt", API_HASH_SHA256))