CryptSetHashParam function (wincrypt.h)

  • Article
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:

  1. Create a hash object by using CryptCreateHash.
  2. Set the HP_HASHVAL value.
  3. Sign the hash value by using CryptSignHash and obtain a digital signature block.
  4. 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

See also

CryptCreateHash

CryptDestroyHash

CryptGetHashParam

CryptSetKeyParam

CryptSignHash

HMAC_INFO

Hash and Digital Signature Functions