CryptVerifySignatureW function (wincrypt.h)

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 CryptVerifySignature function verifies the signature of a hash object.

Before calling this function, CryptCreateHash must be called to create the handle of a hash object. CryptHashData or CryptHashSessionKey is then used to add data or session keys to the hash object.

After CryptVerifySignature completes, only CryptDestroyHash can be called by using the hHash handle.

Syntax

BOOL CryptVerifySignatureW(
  [in] HCRYPTHASH hHash,
  [in] const BYTE *pbSignature,
  [in] DWORD      dwSigLen,
  [in] HCRYPTKEY  hPubKey,
  [in] LPCWSTR    szDescription,
  [in] DWORD      dwFlags
);

Parameters

[in] hHash

A handle to the hash object to verify.

[in] pbSignature

The address of the signature data to be verified.

[in] dwSigLen

The number of bytes in the pbSignature signature data.

[in] hPubKey

A handle to the public key to use to authenticate the signature. This public key must belong to the key pair that was originally used to create the digital signature.

[in] szDescription

This parameter should no longer be used and must be set to NULL to prevent security vulnerabilities. However, it is still supported for backward compatibility in the Microsoft Base Cryptographic Provider.

[in] dwFlags

The following flag values are defined.

Value Meaning
CRYPT_NOHASHOID
0x00000001
This flag is used with RSA providers. When verifying the signature, the hash object identifier (OID) is not expected to be present or checked. If this flag is not set, the hash OID in the default signature is verified as specified in the definition of DigestInfo in PKCS #7.
CRYPT_TYPE2_FORMAT
0x00000002
This flag is not used.
CRYPT_X931_FORMAT
0x00000004
Use X.931 support for the FIPS 186-2–compliant version of RSA (rDSA).

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.
NTE_BAD_FLAGS
The dwFlags parameter is nonzero.
NTE_BAD_HASH
The hash object specified by the hHash parameter is not valid.
NTE_BAD_KEY
The hPubKey parameter does not contain a handle to a valid public key.
NTE_BAD_SIGNATURE
The signature was not valid. This might be because the data itself has changed, the description string did not match, or the wrong public key was specified by hPubKey.

This error can also be returned if the hashing or signature algorithms do not match the ones used to create the signature.

NTE_BAD_UID
The cryptographic service provider (CSP) context that was specified when the hash object was created cannot be found.
NTE_NO_MEMORY
The CSP ran out of memory during the operation.

Remarks

The CryptVerifySignature function completes the hash. After this call, 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.

If you generate a signature by using the .NET Framework APIs and try to verify it by using the CryptVerifySignature function, the function will fail and GetLastError will return NTE_BAD_SIGNATURE. This is due to the different byte orders between the native Win32 API and the .NET Framework API.

The native cryptography API uses little-endian byte order while the .NET Framework API uses big-endian byte order. If you are verifying a signature generated by using a .NET Framework API, you must swap the order of signature bytes before calling the CryptVerifySignature function to verify the signature.

Examples

For an example that uses the CryptVerifySignature function, see Example C Program: Signing a Hash and Verifying the Hash Signature.

Note

The wincrypt.h header defines CryptVerifySignature as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

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

CryptHashData

CryptHashSessionKey

CryptSignHash

Hash and Digital Signature Functions