Platform SDK: Cryptography

CPGetHashParam

The CPGetHashParam function retrieves data about the operations of a hash object. The actual hash value can be obtained using 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 within the CSP. This handle is obtained by a call to CPAcquireContext.
hHash
Handle to the target hash object on which a query is being made.
dwParam
Parameter number. The following table lists currently defined dwParam values and their meanings.
Value Return contents of the pbData buffer
HP_ALGID An algorithm specifier (ALG_ID) indicating the algorithm used by this hash object is copied to the pbData buffer. A value 4 is returned in pdwDataLen.
HP_HASHSIZE A DWORD specifying the number of bytes in the hash value produced by this hash object is returned in the pbData buffer. A value 4 is returned in pdwDataLen.
HP_HASHVALUE The hash computed value for the hash object specified by hHash is returned in the pbData buffer. The length of the hash value should be returned in pdwDataLen.

The call to CPGetHashParam function completes the hash. After this call, no more data can be added to the hash. Additional calls to CPHashData or CPHashSessionKey must fail. However, additional calls to CPDeriveKey, CPGetHashParam, CPSignHash, and CPVerifySignature succeed and use the completed hash object.


Parameters can be added as needed. General-purpose parameters can be define in coordination with Microsoft to promote cross-vendor standardization and allow the new parameter numbers to be added to the standard Microsoft Win32® header files.

pbData
Pointer to a data buffer. The dwParam parameter specifies the type of data to be copied to this buffer.

It is not an error if this parameter is NULL. If pbData is NULL, no parameter data is copied. Instead, the required buffer size (in bytes) is returned in pdwDataLen and a second call to the function with the correct number of bytes allocated for the pbData buffer is expected. See Retrieving Data of Unknown Length for a detailed discussion and examples.

pdwDataLen
Address of a DWORD. Upon function entry, this DWORD contains the number of bytes allocated in the pbData buffer. Upon exit, this must be set to the number of bytes need for the pbData buffer.

If the buffer specified by pbData is not large enough to hold the requested data, the ERROR_MORE_DATA error code is returned by 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 is returned in this parameter.

dwFlags
No flags are currently defined.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using 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.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer 3.02 or later).
  Header: Declared in Wincrypt.h.

See Also

CPCreateHash, CPGetKeyParam, CPSetHashParam, CryptGetHashParam