BCryptVerifySignature function (bcrypt.h)

The BCryptVerifySignature function verifies that the specified signature matches the specified data.

Syntax

NTSTATUS BCryptVerifySignature(
  [in]           BCRYPT_KEY_HANDLE hKey,
  [in, optional] VOID              *pPaddingInfo,
  [in, optional] PUCHAR            pbHash,
  [in]           ULONG             cbHash,
  [in]           PUCHAR            pbSignature,
  [in]           ULONG             cbSignature,
  [in]           ULONG             dwFlags
);

Parameters

[in] hKey

The handle of the key to use to verify the signature. This must contain the public key portion of the key pair used to sign the data with the BCryptSignHash function.

[in, optional] pPaddingInfo

A pointer to a structure that contains padding information. The actual type of structure this parameter points to depends on the value of the dwFlags parameter. When dwFlags is 0, this parameter must be NULL.

[in, optional] pbHash

The address of a buffer that contains the input to be verified. The cbHash parameter contains the size of this buffer.

Note: The parameter name pbHash is a misnomer due to the history of this API.

For many signature algorithms (DSA, RSA, ECDSA, HashML-DSA, etc.), the verification routine is defined to take the result of a hash function as input. In these algorithms, the original message to be verified must first be hashed, and the resultant hash value (pre-hash) is passed in the pbHash buffer.

However, some signature algorithms (pure ML-DSA, pure SLH-DSA, etc.) allow direct signing of arbitrary sized data. For these algorithms the pbHash buffer represents the input to be verified. Signer and verifier must agree on how to construct this input, but there is no requirement for a pre-hash to be involved.

In either case, the pbHash buffer represents the input to be verified.

[in] cbHash

The size, in bytes, of the pbHash buffer.

[in] pbSignature

The address of a buffer that contains the signature of the data. The BCryptSignHash function is used to create the signature. The cbSignature parameter contains the size of this buffer.

[in] cbSignature

The size, in bytes, of the pbSignature buffer. The BCryptSignHash function is used to create the signature.

[in] dwFlags

A set of flags that modify the behavior of this function. The allowed set of flags depends on the type of key specified by the hKey parameter.

This can be zero or one of the following values:

Return value

Returns a status code that indicates the success or failure of the function.

Possible return codes include, but are not limited to, the following:

Remarks

This function uses the public part of the provided key to calculate whether the provided data, and additional parameters specified by dwFlags and pPaddingInfo, matches the provided signature according to the signature algorithm specification.

If the signature algorithm takes a pre-hashed value as input, you must hash the original data by using the same hashing algorithm that was used to create the hash value that was signed. If applicable, you must also specify the same padding scheme that was specified when the signature was created.

When using a supported algorithm provider, BCryptVerifySignature can be called either from user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL, the handle provided in the hKey parameter must be derived from an algorithm handle returned by a provider that was opened by using the BCRYPT_PROV_DISPATCH flag, and any pointers passed to the BCryptVerifySignature function must refer to nonpaged (or locked) memory.

To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows Server 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

Requirements

See also

BCryptSignHash