Platform SDK: Cryptography

CPVerifySignature

The CPVerifySignature function verifies the digital signature.

BOOL CPVerifySignature(
  HCRYPTPROV hProv,         // in
  HCRYPTHASH hHash,         // in
  CONST BYTE *pbSignature,  // in
  DWORD dwSigLen,           // in
  HCRYPTKEY hPubKey,        // in
  LPCWSTR sDescription,     // in
  DWORD dwFlags             // in
);

Parameters

hProv

Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext.

hHash

Handle to the hash object to be verified.

pbSignature

Buffer containing the signature data.

dwSigLen

Length (in bytes) of the signature data.

hPubKey

Handle to the public key used to verify the signature.

sDescription

A NULL-terminated string with a description of the hash object.

The use of this parameter is not recommended because of security vulnerabilities. It is recommended that it always be interpreted as set to NULL. Some CSPs might prefer to keep supporting it for backward compatibility with the Microsoft Cryptographic Service Providers.

dwFlags

The following value is defined for RSA providers:

CRYPT_NOHASHOID: The hash OID is not expected to be present and is not 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. Details of the PKCS standards can be found on the RSA Security Standards Web page, www.rsasecurity.com.
The Microsoft cryptographic providers support this flag in Windows 2000. This support is not included with Windows 98 or Internet Explorer 5.0 or later.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError.

Error	Description
NTE_BAD_FLAGS	The dwFlags parameter is non-zero.
NTE_BAD_HASH	The hash object specified by the hHash parameter is invalid.
NTE_BAD_KEY	The hPubKey parameter does not contain a handle to a valid public key.
NTE_BAD_SIGNATURE	The signature failed to verify. This could be because the data itself has changed, the description string did not match, or the wrong public key was specified by hPubKey. This error might also be returned if the hashing or signature algorithms do not match the ones used to create the signature.
NTE_BAD_UID	The CSP context that was specified when the hash object was created cannot now be found.
NTE_NO_MEMORY	The CSP ran out of memory during the operation.

Remarks

The CPVerifySignature function typically performs the following steps internally:

The sDescription description string, if supported, is added to the hash object.
The hash object is "finished," and the hash value extracted.
The hash value is padded out as required by the signature algorithm.
The actual verification operation is performed by using the hPubKey public key. The NTE_BAD_SIGNATURE error code is returned if the signed hash within the pbSignature buffer and the hash value in the hHash hash object do not match.

CPVerifySignature completes a hash. After CPVerifySignature has been called, no more data can be added to the hash. Additional calls to CPHashData or CPHashSessionKey fail. However, additional calls to CPDeriveKey, CPGetHashParam, CPSignHash, and CPVerifySignature succeed and use the finished hash object.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer 3.02 or later).
  Header: Declared in Wincrypt.h.

CPVerifySignature

Parameters

Return Values

Remarks

Requirements

See Also