HashCryptStreams HashObject object
 
1. Creation and ProgID
2. Overview
3. Members reference
See also: Using Hash and Cryptography objects, Implemented algorithms list

Creation and ID-s

Threading model: Both
Program ID: newObjects.crypt.HashObject
ClassID: {9C2A07F4-FB73-442A-8932-4B2916D85576}
Threading model: Free
ProgramID: newObjects.crypt.HashObject.free
ClassID: {6ED3C86E-091A-4449-891C-D99C99690A28} 

Overview

This object implements both hash and HMAC functions. When the Key property is empty (default) it functions as hash function, when the Key property is set it functions as HMAC function over the same hash algorithm (selected using InitHash).

The object can be used to hash/HMAC data both in a single step or in a number of chunks. The HashData method performs Hash/HMAC over the passed data in single step, while series of HashUpdate followed by final call to HashFinalize do the same for a set of data chunks. Depending on the data size and the way the data becomes available one of these techniques would be more convenient. For example hash values for passwords are obviously candidate for single step HashData, while hashing a large file should be read in a cycle and hashed through HashUpdate and finalized with HashFinalize after the last chunk is read and passed to HashUpdate.

No matter which technique is used the resulting hash/HMAC is obtained through reading the Value or the BinaryValue property. They both return the calculated Hash/HMAC, but in different formats. Value returns it in a hexdecimal string, while BinaryValue returns it as binary data (array of bytes - VT_UI1 | VT_ARRAY) which can be passed to other components that work with binary data directly. These are the two most popular forms of the hash values thus almost always you would be able to obtain the result in the form best for the particular application needs.

What kind of data can be passed to HashData and HashUpdate? Textual or binary. When strings are passed as argument they are first converted to the code page specified by the CodePage argument or if it is omitted the CodePage property is used. The converted string is then hash-ed/HMAC-ed. When binary data is passed it is processed "as is" without further conversions. For example you can use SFStream.ReadBin to read from a file and pass the result from that call directly to HashUpdate (or HashData if that is all the data you want to hash/HMAC).

Notice about hashing texts. Almost all the standard applications for hash/HMAC functions over textual data are restricted to ASCII characters or alternatively they assume the text is encoded in some safe manner (most often UTF-8). This is for a reason - if UNICODE text is hash/HMAC-ed directly the system's byte order is important. For example the x86 compatible processors use little endian while PowerPC processors use big endian formats. For instance this means that on x86 machines the Cyrillic letter "A" will be represented as 10 40 while on Power PC systems it will be represented as 40 10. Consequently the Hash/HMAC result will differ despite the fact that you are hashing the same text. 

Reference

method.gif (107 bytes) InitHash Syntax:
object.InitHash "hash_function_name"
Initializes the object with the specified hash algorithm (function). This also effectively resets the object for a new use. The hash_function_name parameter is the hash algorithm name. Currently supported are:
MD5 - MD5 algorithm
SHA1 - SHA-1 algorithm
SHA256 - SHA-256 algorithm 
method.gif (107 bytes) HashData Syntax:
object.HashData data [,codePage]
Generates the hash or HMAC digest of the data. The data parameter can be binary data (byte array - a Variant VT_UI1 | VT_ARRAY) or a string. The codePage parameter is used when data is string. It specifies the code page which is used for conversion before processing the data. If omitted the code page set by the CodePage property is used.
The generated Hash/HMAC digest can be obtained from the Value or the BinaryValue (whichever offers more appropriate format for your purposes).
All the data passed to the method is processed and the process is finalized - i.e. each call to this method completes the digest generation in single step. For hashing data in chunks see HashUpdate/HashFinalize.
method.gif (107 bytes) HashUpdate Syntax:
object.HashUpdate data [,codePage]
Together with HashFinalize enables the application to generate Hash/HMAC digest of huge amount of data passing it as a number of chunks. After calling the HashUpdate as many times as needed to pass all the data you need to call HashFinalize to complete the operation. 
The data parameter is the data as binary (byte array VT_UI1 | VT_ARRAY) or a string. The codePage parameter is used when data is string. It specifies the code page which is used for conversion before processing the data. If omitted the code page set by the CodePage property is used.
method.gif (107 bytes) HashFinalize Syntax:
object.HashFinalize
Finalizes the operation if HashUpdate is used to process huge amount of data in chunks (sequential calls to HashUpdate to pass all the data). The generated Hash/HMAC digest can be obtained from the Value or BinaryValue property.
method.gif (107 bytes) Reset Syntax:
object.Reset
Resets the object state and buffers, but leaves the selected algorithm and HMAC key (if present) intact. Used mostly to cancel HashUpdata/HashFinalize operation and prepare the object for reuse.
method.gif (107 bytes) ResetKey Syntax:
object.ResetKey
Resets the object state, HMAC key and the buffers, but leaves the selected algorithm intact. Used mostly to cancel HashUpdata/HashFinalize operation and prepare the object for reuse.
Value Syntax:
hash = object.Value
Returns the generated Hash/HMAC digest from the last operation as hexdecimal string.
Query this property after calling HashData or after calling several times HashUpdate and finially HashFinalize. The Reset and ResetKey methods clear this value. It is recommended to call one of them (whichever is more appropriate for what you are doing) between the operations in order to avoid mess up with digests generated during previous operations.
BinaryValue Syntax:
hashedData = object.BinaryValue
Returns the generated Hash/HMAC digest from the last operation as binary data (byte array - VT_UI1 | VT_ARRAY).
Query this property after calling HashData or after calling several times HashUpdate and finially HashFinalize. The Reset and ResetKey methods clear this value. It is recommended to call one of them (whichever is more appropriate for what you are doing) between the operations in order to avoid mess up with digests generated during previous operations.
HashSize Syntax:
sizeinbytes = object.HashSize
Returns the size (in bytes) of the digest generated by the selected algorithm. This value is a constant for each algorithm:
MD5 - 16 bytes
SHA1 - 20 bytes
SHA256 - 32 bytes
BlockSize Syntax:
sizeinbytes = object.BlockSize
Returns the size (in bytes) of the selected algorithm's block size. Each hash function processes the data in blocks with size specific for the particular algorithm. When the last remaining data is processed it is padded to the block size. The padding is standard and is done by automatically by the HashData or HashFinalize methods repspectively.
CodePage Syntax:
object.CodePage = cp
cp = object.CodePage

Specifies the code page which is used whenever a string is passed as data to the HashData or HashUpdate methods. Usually textual data is hashed not as UNICODE (which is the internal string format used in COM) but in ASCII or multibyte format. Value of -1 will cause the data to be processed as UNICODE, 0 or greater value specify a code page. 
Key Syntax:
object.Key = keyforHMAC
keyforHMAC = object.Key

HMAC is actually a simple standard that defines how to generate digest of a data combined with a secret key (another small chunk of data). I.e. the digest can be verified only if you know the key.  The implementation is according to RFC2104.
If the key is not set the object generates hash (and not HMAC). If the Key is set the object generates HMAC over the processed data. Thus the same object serves the both cases.

...

newObjects Copyright 2001-2006 newObjects [ ]