HASH_File

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

VBA/VB6 Syntax

nRet = HASH_File(lpDigest(0), nDigLen, strFileName, nOptions)

C/C++ Syntax

Parameters

lpOutput

[out] array to receive the hash digest.

nOutBytes

[in] specifying the length in bytes of the output array.

szFileName

[in] containing the name of the file.

nOptions

[in] Option flags. Select one of:
PKI_HASH_SHA1 (0) to use the SHA-1 algorithm (default)
PKI_HASH_SHA224 to use the SHA-224 algorithm
PKI_HASH_SHA256 to use the SHA-256 algorithm
PKI_HASH_SHA384 to use the SHA-384 algorithm
PKI_HASH_SHA512 to use the SHA-512 algorithm
PKI_HASH_SHA3_224 to use the SHA-3-224 algorithm
PKI_HASH_SHA3_256 to use the SHA-3-256 algorithm
PKI_HASH_SHA3_384 to use the SHA-3-384 algorithm
PKI_HASH_SHA3_512 to use the SHA-3-512 algorithm
PKI_HASH_MD5 to use the MD5 algorithm
PKI_HASH_MD2 to use the MD2 algorithm (legacy applications)
PKI_HASH_RMD160 to use the RIPEMD-160 algorithm
PKI_HASH_BTC160 to use the Bitcoin160 algorithm, RIPEMD160(SHA256(m))
and optionally add
PKI_HASH_DOUBLE to compute a double hash, HASH(HASH(m))
and add
PKI_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 bytes in the hash digest array; otherwise it returns a negative error code.

VBA Wrapper Syntax

.NET Equivalent

Hash.BytesFromFile Method

C++ (STL) Equivalent

Python Equivalent

Remarks

Specify a zero nOutBytes parameter to find out the required length of the output array. The maximum size will be PKI_MAX_HASH_BYTES. The final digest will be truncated to the specified length if less than the expected size. Add the option PKI_HASH_MODE_TEXT to work in "text" mode where CR-LF pairs are treated as a single newline (LF) character. (This option is provided if you need to pass hash digests of text files between Windows and Unix systems.) The default mode is "binary" where each byte is treated individually. Only ANSI characters are supported in file names and paths.

Examples

    Dim nRet As Long
    Dim abDigest() As Byte
    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 = "hello.txt"
    
    ' Pre-dimension digest array - do this each time
    ReDim abDigest(PKI_MAX_HASH_BYTES)
    
    ' Create default hash (SHA1) in binary mode
    nRet = HASH_File(abDigest(0), PKI_MAX_HASH_BYTES, sFileName, 0)
    If nRet > 0 Then ReDim Preserve abDigest(nRet - 1)
    Debug.Print nRet, cnvHexStrFromBytes(abDigest)
    
    ' Use SHA1 in "text" mode
    ReDim abDigest(PKI_MAX_HASH_BYTES)
    nRet = HASH_File(abDigest(0), PKI_MAX_HASH_BYTES, sFileName, PKI_HASH_MODE_TEXT)
    If nRet > 0 Then ReDim Preserve abDigest(nRet - 1)
    Debug.Print nRet, cnvHexStrFromBytes(abDigest)
    
    ' Use MD5
    ReDim abDigest(PKI_MAX_HASH_BYTES)
    nRet = HASH_File(abDigest(0), PKI_MAX_HASH_BYTES, sFileName, PKI_HASH_MD5)
    If nRet > 0 Then ReDim Preserve abDigest(nRet - 1)
    Debug.Print nRet, cnvHexStrFromBytes(abDigest)
    
    ' Use MD5 in "text" mode
    ReDim abDigest(PKI_MAX_HASH_BYTES)
    nRet = HASH_File(abDigest(0), PKI_MAX_HASH_BYTES, sFileName, PKI_HASH_MD5 Or PKI_HASH_MODE_TEXT)
    If nRet > 0 Then ReDim Preserve abDigest(nRet - 1)
    Debug.Print nRet, cnvHexStrFromBytes(abDigest)

This should produce the following output:

 20           88A5B867C3D110207786E66523CD1E4A484DA697
 20           22596363B3DE40B06F981FB85D82312E8C0ED511
 16           A0F2A3C1DCD5B1CAC71BF0C03F2FF1BD
 16           6F5902AC237024BDD0C176CB93063DC4

Example (VBA wrapper function)

Dim strDigest As String
Dim lpMessage() As Byte
Dim lpDigest() As Byte

' Hex <-- Hex
strDigest = hashHexFromHex("616263", PKI_HASH_SHA256)   ' "abc" in hex
Debug.Print strDigest
lpMessage = StrConv("abc", vbFromUnicode)   ' "abc" in a byte array
' Hex <-- Bytes
strDigest = hashHexFromBytes(lpMessage, PKI_HASH_SHA256)
Debug.Print strDigest
' Bytes <-- Bytes
lpDigest = hashBytes(lpMessage, PKI_HASH_SHA256)
Debug.Print cnvHexStrFromBytes(lpDigest)
' Hex <-- File
strDigest = hashHexFromFile("abc.txt", PKI_HASH_SHA256) ' "abc" in a text file
Debug.Print strDigest
' Bytes <-- File
lpDigest = hashFile("abc.txt", PKI_HASH_SHA256)
Debug.Print cnvHexStrFromBytes(lpDigest)

Debug.Print "OK=" & "BA7816BF8F01CFEA414140DE5DAE2223B00361A396177A9CB410FF61F20015AD"

See Also

HASH_HexFromFile

[Contents] [Index]