CryptGetHashParam

Article
06/30/2006

This function retrieves data that governs the operations of a hash object. The actual hash value can also be retrieved by using this function.

BOOL CRYPTFUNC CryptGethashParam( 
HCRYPTHASH hHash,
DWORD dwParam, 
BYTE *pbData, 
DWORD *pdwDataLen, 
DWORD dwFlags);

Parameters

hHash
[in] Handle to the hash object on which to query parameters.
dwParam
[in] Specifies the parameter number. See the Remarks section for a list of valid parameters.
pbData
[out] Pointer to a buffer that receives the specified parameter data. The form of this data will vary, depending on the parameter number.

This parameter can be NULL to set the size of this information for memory allocation purposes.
pdwDataLen
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbData parameter. When the function returns, the variable pointed to by the pdwDataLen parameter contains the number of bytes stored in the buffer.

Note When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.
dwFlags
[in] Specifies a bitmask of flags. This parameter is reserved for future use; set to 0.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Value	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_MORE_DATA	If the buffer specified by the pbData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code, and stores the required buffer size, in bytes, into the variable pointed to by pdwDataLen.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_HASH	The hash object specified by the hHash parameter is invalid.
NTE_BAD_TYPE	The dwParam parameter specifies an unknown parameter number.
NTE_BAD_UID	The CSP context that was specified when the hash was created cannot be found.

Remarks

The dwParam value can be set to one of the following hash parameter types:

HP_ALGID. The hash algorithm. The pbData buffer will contain an ALG_ID value indicating that the algorithm was specified when the hash object was created. See the CryptCreateHash function for a list of hash algorithms.
HP_HASHSIZE. The hash value size. The pbData buffer will contain a DWORD value indicating the number of bytes in the hash value. This value will usually be 16 or 20, depending on the hash algorithm.
Applications should retrieve this parameter just before the HP_HASHVAL parameter so the correct amount of memory can be allocated.
HP_HASHVAL. The hash value. The pbData buffer will contain the hash value or message hash for the hash object specified by hHash. This value is generated based on the data supplied earlier to the hash object through the CryptHashData and CryptHashSessionKey functions.

After this parameter has been retrieved, the hash object is marked "finished" and no more data can be added to it.

Note Some CSPs may add additional parameters that can be queried through this function.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
HCRYPTHASH hHash = 0;
BYTE *pbHash = NULL;
DWORD dwHashLen;
#define BUFFER_SIZE 256
BYTE pbBuffer[BUFFER_SIZE];
DWORD dwCount;
DWORD i;

// Get a handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
 printf("Error %x during CryptAcquireContext!\n", GetLastError());
 goto done;
}
// Create a hash object.
if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {
 printf("Error %x during CryptBeginHash!\n", GetLastError());
 goto done;
}

// Fill the buffer with test data.
for(i = 0 ; i < BUFFER_SIZE ; i++) {
 pbBuffer[i] = (BYTE)i;
}

// Put the hash in buffer.
if(!CryptHashData(hHash, pbBuffer, BUFFER_SIZE, 0)) {
 printf("Error %x during CryptHashData!\n", GetLastError());
 goto done;
}

// Read the hash value size and allocate memory.
dwCount = sizeof(DWORD);
if(!CryptGetHashParam(hHash, HP_HASHSIZE, (BYTE *)&dwHashLen, 
 &dwCount, 0)) {
 printf("Error %x during reading hash size!\n", GetLastError());
 goto done;
}
if((pbHash = malloc(dwHashLen)) == NULL) {
 printf("Out of memory!\n");
 goto done;
}

// Read the hash value.
if(!CryptGetHashParam(hHash, HP_HASHVAL, pbHash, &dwHashLen, 0)) {
 printf("Error %x during reading hash value!\n", GetLastError());
 goto done;
}

// Print the hash value.
for(i = 0 ; i < dwHashLen ; i++) {
 printf("%2.2x ",pbHash[i]);
}
printf("\n");

done:

// Free memory.
if(pbHash !=NULL) free(pbHash);

// Destroy the hash object.
if(hHash) CryptDestroyHash(hHash);
// Release the CSP handle.
if(hProv) CryptReleaseContext(hProv,0);

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	2.10 and later	Wincrypt.h		Cryptapi.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

Last updated on Tuesday, July 13, 2004

CryptGetHashParam

Additional resources