HASH_HexFromFile

CryptoSys PKI Toolkit 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.

VB6/VBA Syntax


Public Declare Function HASH_HexFromFile Lib "diCrPKI.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)

Parameters

strOutput: [out] String to receive hash digest in hexadecimal format.
nOutChars: [in] Long specifying the maximum number of characters to be received in characters.
strFileName: [in] String containing the name of the file.
nOptions: [in] Long Option flags. Select one of:
PKI_HASH_SHA1 (0) to use the SHA-1 algorithm (default)
PKI_HASH_MD5 to use the MD5 algorithm
PKI_HASH_MD2 to use the MD2 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_SHA224 to use the SHA-224 algorithm
and add
PKI_HASH_MODE_TEXT to hash in "text" mode instead of default "binary" mode

C/C++ Syntax


long _stdcall HASH_HexFromFile(char *szOutput, long nOutChars, const char *szFileName, 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

Hash.HexFromFile Method

Remarks

Specify a zero nOutChars or a NULL strOutput parameter to find out the required length of the output string, or use the appropriate PKI_xxx_CHARS constant. The maximum number of characters will be PKI_MAX_HASH_CHARS. C/C++ users should add one to this value when allocating memory. 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 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(PKI_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, PKI_HASH_MODE_TEXT)
Debug.Print nRet, Left(sDigest, nRet)
' Use MD5
nRet = HASH_HexFromFile(sDigest, Len(sDigest), sFileName, PKI_HASH_MD5)
Debug.Print nRet, Left(sDigest, nRet)
' Use MD5 in "text" mode
nRet = HASH_HexFromFile(sDigest, Len(sDigest), sFileName, PKI_HASH_MD5 Or PKI_HASH_MODE_TEXT)
Debug.Print nRet, Left(sDigest, nRet)

This should produce the following output:

 40           88a5b867c3d110207786e66523cd1e4a484da697
 40           22596363b3de40b06f981fb85d82312e8c0ed511
 32           a0f2a3c1dcd5b1cac71bf0c03f2ff1bd
 32           6f5902ac237024bdd0c176cb93063dc4