Expand Minimize

CryptCreateHash function

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 WINAPI CryptCreateHash(
  _In_   HCRYPTPROV hProv,
  _In_   ALG_ID Algid,
  _In_   HCRYPTKEY hKey,
  _In_   DWORD dwFlags,
  _Out_  HCRYPTHASH *phHash
);

Parameters

hProv [in]

A handle to a CSP created by a call to CryptAcquireContext.

Algid [in]

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.

hKey [in]

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).

dwFlags [in]

The following flag value is defined.

ValueMeaning
CRYPT_SECRETDIGEST
0x00000001

This flag is not used.

 

phHash [out]

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 codeDescription
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:

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

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Advapi32.lib

DLL

Advapi32.dll

See also

Hash and Digital Signature Functions
CryptAcquireContext
CryptDeriveKey
CryptDestroyHash
CryptGetHashParam
CryptHashData
CryptHashSessionKey
CryptSetHashParam
CryptSignHash
CryptVerifySignature

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.