CPGetHashParam

The CPGetHashParam function allows applications to retrieve data that governs the operations of a hash object. The actual hash value is also obtained via this function.

BOOL CPGetHashParam(
  HCRYPTPROV hProv,  // in
  HCRYPTHASH hHash,  // in
  DWORD dwParam,     // in
  BYTE *pbData,      // out
  DWORD *pdwDataLen, // in, out
  DWORD dwFlags      // in
);

Parameters

hProv
Handle to a particular key container (or "context") within the CSP. This handle is obtained via a call to CPAcquireContext.
hHash
Handle to the hash object on which to query parameters.
dwParam
Parameter number. See the "Remarks" section for the list of currently defined parameters.
pbData
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.

If this parameter is NULL, then no parameter data should be copied. Instead, the required buffer size (in bytes) should be returned in pdwDataLen. This is not an error.

pdwDataLen
Address of the parameter data length. Upon function entry, this contains the number of bytes in the pbData buffer. Upon exit, this must be set to the number of bytes of parameter data copied to the pbData buffer.

If the buffer specified by pbData is not large enough to hold the requested data, the ERROR_MORE_DATA error code should be returned via the SetLastError function. In this case, the required buffer size must be returned in pdwDataLen.

If this function fails with any error code other than ERROR_MORE_DATA, zero should be returned in this parameter.

dwFlags
Flag values. No flags are currently defined.

Return Values

If the function succeeds, TRUE should be returned; otherwise, return FALSE. When FALSE is returned, the appropriate error code (see the following table) must be set via SetLastError.

Error Description
ERROR_MORE_DATA The pbData buffer is not large enough to hold the requested data.
NTE_BAD_FLAGS The dwFlags parameter is non-zero.
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 now be found.

Remarks

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

HP_ALGID
The hash algorithm. An algorithm specifier (ALG_ID) indicating the algorithm used by this hash object should be placed in the pbData buffer. A value of 4 should be returned in pdwDataLen.
HP_HASHSIZE
The hash value size. A DWORD specifying the number of bytes in the hash value produced by this hash object should be placed in the pbData buffer. A value of 4 should be returned in pdwDataLen.
HP_HASHVAL
The hash value (or message digest). The hash value should be computed and placed in the pbData buffer. The length of the hash value should be returned in pdwDataLen.

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 (both in the CryptoAPI).

After this parameter has been retrieved, the application shouldn't be allowed to add more data to the hash object.

Additional parameters can be added as needed. If these are general-purpose in nature, rather than applying to a single provider type, you should define these in coordination with Microsoft. This will promote cross-vendor standardization, and allow the new parameter numbers to be added to the standard Win32 header files.

See Also

CPCreateHash, CPGetKeyParam, CPSetHashParam, CryptGetHashParam