[New - Windows NT]
[New - Windows 95, OEM Service Release 2]
The CryptGetHashParam function lets applications retrieve data that governs of the operations of a hash object. The actual hash value can also be retrieved using this function.
BOOL CRYPTFUNC CryptGetHashParam(
| HCRYPTHASH hHash, | |
| DWORD dwParam, | |
| BYTE *pbData, | |
| DWORD *pdwDataLen, | |
| DWORD dwFlags | |
| ); |
Parameters
hHash
[in] A handle to the hash object on which to query parameters.
dwParam
[in] The parameter number. See the "Remarks" section for a list of valid parameters.
pbData
[out] The parameter data buffer. The function copies the specified parameter data to this buffer. The form of this data will vary, depending on the parameter number.
This parameter can be NULL if all you are doing is determining the number of bytes required for the returned parameter data.
pdwDataLen
[in/out] The address of the parameter data length. Before calling this function, the caller should set this parameter to the length, in bytes, of the pbData buffer. Upon return, this address will contain the number of bytes of parameter data copied to the buffer.
If the buffer specified by pbData is not large enough to hold the data, the function returns the ERROR_MORE_DATA error code (through GetLastError), and stores the required buffer size, in bytes, in the variable pointed to by pdwDataLen.
If pbData is NULL, then no error is returned and the function stores the size of the data, in bytes, in the variable pointed to by pdwDataLen.
dwFlags
[in] The flag values. This parameter is reserved for future use and should always be zero.
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 a ALG_ID value indicating the algorithm that 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 digest 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.
Once this parameter has been retrieved, the hash object is marked "finished" and no more data can be added to it.
Note that some CSPs may add additional parameters that can be queried through this function.
Return Values
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.
The following table lists the error codes most commonly returned by the GetLastError function. The error codes tat prefaced by "NTE" are generated by the particular CSP you are using.
| Error | 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. |
| 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. |
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 handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
printf("Error %x during CryptAcquireContext!\n", GetLastError());
goto done;
}
// Create hash object.
if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {
printf("Error %x during CryptBeginHash!\n", GetLastError());
goto done;
}
// Fill buffer with test data.
for(i = 0 ; i < BUFFER_SIZE ; i++) {
pbBuffer[i] = (BYTE)i;
}
// Hash in buffer.
if(!CryptHashData(hHash, pbBuffer, BUFFER_SIZE, 0)) {
printf("Error %x during CryptHashData!\n", GetLastError());
goto done;
}
// Read 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 hash value.
if(!CryptGetHashParam(hHash, HP_HASHVAL, pbHash, &dwHashLen, 0)) {
printf("Error %x during reading hash value!\n", GetLastError());
goto done;
}
// Print hash value.
for(i = 0 ; i < dwHashLen ; i++) {
printf("%2.2x ",pbHash[i]);
}
printf("\n");
done:
// Free memory.
if(pbHash !=NULL) free(pbHash);
// Destroy hash object.
if(hHash) CryptDestroyHash(hHash);
// Release CSP handle.
if(hProv) CryptReleaseContext(hProv,0);
See Also
CryptCreateHash, CryptGetKeyParam, CryptHashData, CryptHashSessionKey, CryptSetHashParam