CryptCreateHash function (wincrypt.h)
Syntax
BOOL CryptCreateHash(
[in] HCRYPTPROV hProv,
[in] ALG_ID Algid,
[in] HCRYPTKEY hKey,
[in] DWORD dwFlags,
[out] HCRYPTHASH *phHash
);
Parameters
[in] hProv
A handle to a CSP created by a call to CryptAcquireContext.
[in] Algid
An ALG_ID value that identifies the hash algorithm to use.
Valid values for this parameter vary, depending on the CSP that is used. For a list of default algorithms, see Remarks.
[in] hKey
If the type of hash algorithm is a keyed hash, such as the Hash-Based Message Authentication Code (HMAC) or Message Authentication Code (MAC) algorithm, the key for the hash is passed in this parameter. For nonkeyed algorithms, this parameter must be set to zero.
For keyed algorithms, the key must be to a block cipher key, such as RC2, that has a cipher mode of Cipher Block Chaining (CBC).
[in] dwFlags
The following flag value is defined.
Value | Meaning |
---|---|
|
This flag is not used. |
[out] phHash
The address to which the function copies a handle to the new hash object. When you have finished using the hash object, release the handle by calling the CryptDestroyHash function.
Return value
If the function succeeds, the function returns TRUE.
If the function fails, it returns FALSE. For extended error information, call GetLastError.
The error codes prefaced by NTE are generated by the particular CSP you are using. The following table shows some of the possible error codes.
Return code | Description |
---|---|
|
One of the parameters specifies a handle that is not valid. |
|
One of the parameters contains a value that is not valid. This is most often a pointer that is not valid. |
|
The operating system ran out of memory during the operation. |
|
The Algid parameter specifies an algorithm that this CSP does not support. |
|
The dwFlags parameter is nonzero. |
|
A keyed hash algorithm, such as CALG_MAC, is specified by Algid, and the hKey parameter is either zero or it specifies a key handle that is not valid. This error code is also returned if the key is to a stream cipher or if the cipher mode is anything other than CBC. |
|
The CSP ran out of memory during the operation. |
Remarks
For a list of Microsoft service providers and the algorithms they implement, see Microsoft Cryptographic Service Providers.
The computation of the actual hash is done with the CryptHashData and CryptHashSessionKey functions. These require a handle to the hash object. After all the data has been added to the hash object, any of the following operations can be performed:
- The hash value can be retrieved by using CryptGetHashParam.
- A session key can be derived by using CryptDeriveKey.
- The hash can be signed by using CryptSignHash.
- A signature can be verified by using CryptVerifySignature.
Examples
The following example shows initiating the hashing of a stream of data. It creates and returns to the calling application a handle to a hash object. This handle is used in subsequent calls to CryptHashData and CryptHashSessionKey to hash any stream of data. For an example that includes the complete context for this example, see Example C Program: Creating and Hashing a Session Key. For another example that uses this function, see Example C Program: Signing a Hash and Verifying the Hash Signature.
//--------------------------------------------------------------------
// Declare variables.
HCRYPTPROV hCryptProv;
HCRYPTHASH hHash;
//--------------------------------------------------------------------
// Get a handle to a cryptography provider context.
if(CryptAcquireContext(
&hCryptProv,
NULL,
NULL,
PROV_RSA_FULL,
0))
{
printf("CryptAcquireContext complete. \n");
}
else
{
printf("Acquisition of context failed.\n");
exit(1);
}
//--------------------------------------------------------------------
// Acquire a hash object handle.
if(CryptCreateHash(
hCryptProv,
CALG_MD5,
0,
0,
&hHash))
{
printf("An empty hash object has been created. \n");
}
else
{
printf("Error during CryptBeginHash!\n");
exit(1);
}
// Insert code that uses the hash object here.
//--------------------------------------------------------------------
// After processing, hCryptProv and hHash must be released.
if(hHash)
CryptDestroyHash(hHash);
if(hCryptProv)
CryptReleaseContext(hCryptProv,0);
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | wincrypt.h |
Library | Advapi32.lib |
DLL | Advapi32.dll |