CryptSetHashParam function (wincrypt.h)

Article
10/13/2021

Important This API is deprecated. New and existing software should start using Cryptography Next Generation APIs. Microsoft may remove this API in future releases.

The CryptSetHashParam function customizes the operations of a hash object, including setting up initial hash contents and selecting a specific hashing algorithm.

Syntax

BOOL CryptSetHashParam(
  [in] HCRYPTHASH hHash,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

Parameters

[in] hHash

A handle to the hash object on which to set parameters.

[in] dwParam

This parameter can be one of the following values.

Value	Meaning
HP_HMAC_INFO.	A pointer to an HMAC_INFO structure that specifies the cryptographic hash algorithm and the inner and outer strings to be used.
HP_HASHVAL.	A byte array that contains a hash value to place directly into the hash object. Before setting this value, the size of the hash value must be determined by using the CryptGetHashParam function to read the HP_HASHSIZE value. Some cryptographic service providers (CSPs) do not support this capability.

Note Some CSP types can add additional values that can be set by using this function.

[in] pbData

A value data buffer. Place the value data in this buffer before calling CryptSetHashParam. The form of this data varies, depending on the value number.

[in] dwFlags

This parameter is reserved for future use and must be set to zero.

Return value

If the function succeeds, the function returns TRUE.

If the function fails, it returns FALSE. For extended error information, call GetLastError.

The error codes prefaced by "NTE" are generated by the particular CSP you are using. Some possible error codes follow.

Return code	Description
ERROR_INVALID_HANDLE	One of the parameters specifies a handle that is not valid.
ERROR_BUSY	The CSP context is currently being used by another process.
ERROR_INVALID_PARAMETER	One of the parameters contains a value that is not valid. This is most often a pointer that is not valid.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero or the pbData buffer contains a value that is not valid.
NTE_BAD_HASH	The hash object specified by the hHash parameter is not valid.
NTE_BAD_TYPE	The dwParam parameter specifies an unknown value.
NTE_BAD_UID	The CSP context that was specified when the hKey key was created cannot be found.
NTE_FAIL	The function failed in some unexpected way.

Remarks

Occasionally, a hash value that has been generated elsewhere must be signed. This can be done by using the following sequence of operations:

Create a hash object by using CryptCreateHash.
Set the HP_HASHVAL value.
Sign the hash value by using CryptSignHash and obtain a digital signature block.
Destroy the hash object by using CryptDestroyHash.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	wincrypt.h
Library	Advapi32.lib
DLL	Advapi32.dll