This topic has not yet been rated - Rate this topic

CPVerifySignature function

The CPVerifySignature function verifies the digital signature.

Syntax

Copy

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

Parameters

hProv [in]

A handle to a particular key container within the cryptographic service provider (CSP). This handle is obtained by a call to the CPAcquireContext function.

hHash [in]

A handle to the hash object to be verified.

pbSignature [in]

Buffer that contains the signature data.

dwSigLen [in]

Length, in bytes, of the signature data.

hPubKey [in]

A handle to the public key used to verify the signature.

sDescription [in]

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 [in]

The following value is defined for RSA providers.

Value	Meaning
CRYPT_NOHASHOID	The hash object identifier (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 webpage: http://www.rsasecurity.com.

Return value

If the function succeeds, the function returns TRUE.

If the function fails, it returns FALSE, and the appropriate error code from the following table must be set using SetLastError.

Return code	Description
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 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 as required by the signature algorithm.
The actual verification operation is performed by using the hPubKey public key. If the signed hash within the pbSignature buffer and the hash value in the hHash hash object do not match, the NTE_BAD_SIGNATURE error code is returned.

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

Requirements