CPSetHashParam

The CPSetHashParam function allows applications to customize various aspects of the operations of a hash object.

BOOL CPSetHashParam(
  HCRYPTPROV hProv,  // in
  HCRYPTHASH hHash,  // in
  DWORD dwParam,     // in
  BYTE *pbData,      // in
  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 set parameters.
dwParam
Parameter number. See the "Remarks" section for the list of currently defined parameters.
pbData
Parameter data buffer. Upon entry to the function, this buffer will contain the data that corresponds to the dwParam parameter number. Notice that the length of this data is not specified explicitly, but instead is implied by the dwParam parameter number.
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
NTE_BAD_FLAGS The dwFlags parameter is non-zero or the pbData buffer contains an invalid value.
NTE_BAD_HASH The hash object specified by the hHash parameter is invalid.
NTE_BAD_TYPE The dwParam parameter specifies an unknown parameter.
NTE_BAD_UID The CSP context that was specified when the hKey key was created cannot now be found.
NTE_FAIL The function failed in some unexpected way.

Remarks

The dwParam parameter can be set to one of the following values:

HP_HASHVAL
Hash value. The pbData buffer should contain a byte array containing a hash value. This data should be of the same size and format as the hash value returned by the CPGetHashParam function. This data is placed directly into the hash object.

Typically, the hash object specified by hHash will have just been created. If this isn't the case (that is, data has already been added to the hash object), an error may be returned.

This parameter was defined to give applications the ability to sign hash values, without having access to the base data. Because the application (much less the user) can have no idea what is being signed, this operation is intrinsically risky. It is envisioned that many CSPs will not support this parameter.

Additional parameters can be added as needed. If these are general-purpose in nature, rather than just 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, CPGetHashParam, CPSignHash, CryptSetHashParam