Edit

Share via

CryptGetHashParam 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 CryptGetHashParam function retrieves data that governs the operations of a hash object. The actual hash value can be retrieved by using this function.

Syntax

BOOL CryptGetHashParam(
  [in]      HCRYPTHASH hHash,
  [in]      DWORD      dwParam,
  [out]     BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwFlags
);

Parameters

[in] hHash

Handle of the hash object to be queried.

[in] dwParam

Query type. This parameter can be set to one of the following queries.

Value Meaning
HP_ALGID
Hash algorithm
 An ALG_ID that indicates the algorithm specified when the hash object was created. For a list of hash algorithms, see CryptCreateHash.
HP_HASHSIZE
Hash value size
 DWORD value indicating the number of bytes in the hash value. This value will vary depending on the hash algorithm. Applications must retrieve this value just before the HP_HASHVAL value so the correct amount of memory can be allocated.
HP_HASHVAL
Hash value
 The hash value or message hash for the hash object specified by hHash. This value is generated based on the data supplied to the hash object earlier through the CryptHashData and CryptHashSessionKey functions.

The CryptGetHashParam function completes the hash. After CryptGetHashParam has been called, no more data can be added to the hash. Additional calls to CryptHashData or CryptHashSessionKey fail. After the application is done with the hash, CryptDestroyHash should be called to destroy the hash object.
 
Note  CSPs can add more values that this function can query.
 

[out] pbData

A pointer to a buffer that receives the specified value data. The form of this data varies, depending on the value number.

This parameter can be NULL to determine the memory size required.

[in, out] pdwDataLen

A pointer to a DWORD value specifying the size, in bytes, of the pbData buffer. When the function returns, the DWORD value contains the number of bytes stored in the buffer.

If pbData is NULL, set the value of pdwDataLen to zero.

Note  When processing the data returned in the buffer, applications must use the actual size of the data returned. The actual size can be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data fits in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.
 

[in] dwFlags

Reserved for future use and must be zero.

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is 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_INVALID_PARAMETER
 One of the parameters contains a value that is not valid. This is most often a pointer that is not valid.
ERROR_MORE_DATA
 If the buffer specified by the pbData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code and stores the required buffer size, in bytes, in the variable pointed to by pdwDataLen.
NTE_BAD_FLAGS
 The dwFlags parameter is nonzero.
NTE_BAD_HASH
 The hash object specified by the hHash parameter is not valid.
NTE_BAD_TYPE
 The dwParam parameter specifies an unknown value number.
NTE_BAD_UID
 The CSP context that was specified when the hash was created cannot be found.

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

ALG_ID

CryptCreateHash

CryptDestroyHash

CryptGetKeyParam

CryptHashData

CryptHashSessionKey

CryptSetHashParam

Hash and Digital Signature Functions