HASH_HexFromFile

CryptoSys PKI Pro 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 "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)

C/C++ Syntax


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

Parameters

szOutput: [out] to receive hash digest in hexadecimal format.
nOutChars: [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:
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 characters in or required for 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
Hash.HexFromTextFile Method

C++ (STL) Equivalent

static std::string dipki::Hash::HexFromFile (const std::string &fileName, Alg alg=Alg::Sha1, FileMode mode=FileMode::Binary)

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. ANSI C users must add one to this value when allocating memory.

The maximum number of output characters will be PKI_MAX_HASH_CHARS (C/C++ users add one). 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 = "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

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"