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(abDigest(0), nDigLen, strFileName, nOptions)

C/C++ Syntax

Parameters

lpOutput

[out] array to receive the hash digest.

nOutLen

[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:
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 bytes in the hash digest array; otherwise it returns a negative error code.

VBA Wrapper Syntax

.NET Equivalent

Hash.BytesFromFile Method

Python Equivalent

Remarks

Specify a zero nDigLen parameter to find out the required length of the output array. The maximum size will be API_MAX_HASH_BYTES. The final digest will be truncated to the specified length if less than the expected size. Add the option API_HASH_MODE_TEXT to work in "text" mode where CR-LF pairs are treated as a single newline (LF) character. Use this option to pass hash digests of text file between Windows and Unix systems. 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 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 = "C:\Test\hello.txt"
    
    ' Pre-dimension digest array - do this each time
    ReDim abDigest(API_MAX_HASH_BYTES)
    
    ' Create default hash (SHA1) in binary mode
    nRet = HASH_File(abDigest(0), API_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(API_MAX_HASH_BYTES)
    nRet = HASH_File(abDigest(0), API_MAX_HASH_BYTES, sFileName, API_HASH_MODE_TEXT)
    If nRet > 0 Then ReDim Preserve abDigest(nRet - 1)
    Debug.Print nRet, cnvHexStrFromBytes(abDigest)
    
    ' Use MD5
    ReDim abDigest(API_MAX_HASH_BYTES)
    nRet = HASH_File(abDigest(0), API_MAX_HASH_BYTES, sFileName, API_HASH_MD5)
    If nRet > 0 Then ReDim Preserve abDigest(nRet - 1)
    Debug.Print nRet, cnvHexStrFromBytes(abDigest)
    
    ' Use MD5 in "text" mode
    ReDim abDigest(API_MAX_HASH_BYTES)
    nRet = HASH_File(abDigest(0), API_MAX_HASH_BYTES, sFileName, API_HASH_MD5 Or API_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 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))

See Also

HASH_HexFromFile

[Contents] [Index]