BCryptHash function (bcrypt.h)

Performs a single cryptographic hash or Message Authentication Code (MAC) computation. This is a convenience function that wraps calls to BCryptCreateHash, BCryptHashData, BCryptFinishHash, and BCryptDestroyHash.

Syntax

NTSTATUS BCryptHash(
  [in, out]      BCRYPT_ALG_HANDLE hAlgorithm,
  [in, optional] PUCHAR            pbSecret,
  [in]           ULONG             cbSecret,
  [in]           PUCHAR            pbInput,
  [in]           ULONG             cbInput,
  [out]          PUCHAR            pbOutput,
  [in]           ULONG             cbOutput
);

Parameters

[in, out] hAlgorithm

The handle of an algorithm provider that supports the hash or MAC interface. This handle is obtained by calling the BCryptOpenAlgorithmProvider function, or may be a CNG Algorithm Pseudo-handle.

[in, optional] pbSecret

A pointer to a buffer that contains the key to use for a MAC. The cbSecret parameter contains the size of this buffer. If used with a hash algorithm, the algorithm must have been promoted to HMAC by using the BCRYPT_ALG_HANDLE_HMAC flag in BCryptOpenAlgorithmProvider.

To compute a hash, set this parameter to NULL.

[in] cbSecret

The size, in bytes, of the pbSecret buffer. If no key is used, set this parameter to zero.

[in] pbInput

A pointer to a buffer that contains the data to process. The cbInput parameter contains the number of bytes in this buffer. This function does not modify the contents of this buffer.

[in] cbInput

The size, in bytes, of the pbInput buffer.

[out] pbOutput

A pointer to a buffer that receives the hash or MAC value. The cbOutput parameter contains the size of this buffer.

[in] cbOutput

The size, in bytes, of the pbOutput buffer. This size must exactly match the size of the hash or MAC value if it has a fixed size.

The size can be obtained by calling the BCryptGetProperty function to get the BCRYPT_HASH_LENGTH property. This will provide the size of the hash or MAC value for the specified algorithm. Extendable-output functions (XOFs), such as SHAKE256 may support a variable output size, but a default size which maintains full security of the XOF can be queried using BCRYPT_HASH_LENGTH.

Return value

A status code indicating success or failure.

Requirements

See also

BCryptCreateHash

BCryptHashData

BCryptFinishHash

BCryptDestroyHash