CryptCreateHash function (wincrypt.h)

Article
10/13/2021

Important This API is deprecated. New and existing software should start using Cryptography Next Generation APIs. Microsoft may remove this API in future releases.

The CryptCreateHash function initiates the hashing of a stream of data. It creates and returns to the calling application a handle to a cryptographic service provider (CSP) hash object. This handle is used in subsequent calls to CryptHashData and CryptHashSessionKey to hash session keys and other streams of data.

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
CRYPT_SECRETDIGEST 0x00000001	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
ERROR_INVALID_HANDLE	One of the parameters specifies a handle that is not valid.
ERROR_INVALID_PARAMETER	One of the parameters contains a value that is not valid. This is most often a pointer that is not valid.
ERROR_NOT_ENOUGH_MEMORY	The operating system ran out of memory during the operation.
NTE_BAD_ALGID	The Algid parameter specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_KEY	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.
NTE_NO_MEMORY	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.

After one of the functions from this list has been called, CryptHashData and CryptHashSessionKey cannot be called.

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