CryptVerifySignature
[New
- Windows NT]
[New
- Windows 95, OEM Service Release 2]
The CryptVerifySignature
function is used to verify a signature against a hash object.
Before
calling this function, the CryptCreateHash function must be called to get a handle to a
hash object. The CryptHashData and/or CryptHashSessionKey functions are then used to
add the data and/or session keys to the hash object.
Once this
function has been completed, the only hash function that can be called using
the hHash handle is the CryptDestroyHash function.
BOOL CRYPTFUNC CryptVerifySignature(
|
HCRYPTHASH hHash, |
|
|
BYTE *pbSignature, |
|
|
DWORD dwSigLen, |
|
|
HCRYPTKEY hPubKey, |
|
|
LPCTSTR sDescription, |
|
|
DWORD dwFlags |
|
|
); |
|
Parameters
hHash
[in] A handle
to the hash object to verify against.
pbSignature
[in] The
address of the signature data to be verified.
dwSigLen
[in] The
number of bytes in the pbSignature signature data.
hPubKey
[in] 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.
sDescription
[in] String
describing the signed data. This must be exactly the same string that was
passed in to the CryptSignHash function when the signature was created. If this string
does not match, the signature verification will fail.
When this
function is called, some CSPs (not the Microsoft RSA Base Provider) will
display this description string to the user, together with an indication of
whether the signature verified correctly. This provides the user with the
verification results in a way that is completely independent of the
application.
dwFlags
[in] The flag
values. This parameter is reserved for future use and should always be zero.
Return Values
If the
function succeeds, the return value is nonzero.
If the
function fails, the return value is zero. To retrieve extended error
information, use the GetLastError function.
The following
table lists the error codes most commonly returned by the GetLastError
function. The error codes prefaced by NTE are generated by the particular CSP
you are using.
|
|
Description |
|
ERROR_INVALID_HANDLE |
One of the
parameters specifies an invalid handle. |
|
ERROR_INVALID_PARAMETER |
One of the
parameters contains an invalid value. This is most often an illegal pointer. |
|
NTE_BAD_FLAGS |
The dwFlags
parameter is nonzero. |
|
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
can 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 be found. |
|
NTE_NO_MEMORY |
The CSP ran
out of memory during the operation. |
Example
#include <wincrypt.h>
HCRYPTPROV hProv = 0;
#define BUFFER_SIZE 256
BYTE pbBuffer[BUFFER_SIZE];
HCRYPTHASH hHash = 0;
HCRYPTKEY hPubKey = 0;
BYTE *pbSignature = NULL;
DWORD dwSigLen;
LPTSTR szDescription = NULL;
// Get handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL,
PROV_RSA_FULL, 0)) {
printf("Error %x during CryptAcquireContext!\n",
GetLastError());
goto done;
}
// Load pbBuffer with BUFFER_SIZE bytes of test
data. This must
// be the same data that was originally signed.
...
// Point pbSignature at the signature created by a
previous call
// to CryptSignHash. Set dwSigLen to the number of
bytes in the
// signature.
...
// Point szDescription at some text describing the
data being
// signed. This must be the same description text
that was originally
// passed to CryptSignHash.
...
// Get public key of the user that created the
digital signature
// and import it into the CSP using CryptImportKey.
This will return
// a handle to the public key in hPubKey .
...
// Create hash object.
if(!CryptCreateHash(hProv, CALG_MD5, 0, 0,
&hHash)) {
printf("Error %x during CryptCreateHash!\n", GetLastError());
goto done;
}
// Hash buffer.
if(!CryptHashData(hHash, pbBuffer, BUFFER_SIZE, 0))
{
printf("Error %x during CryptHashData!\n", GetLastError());
goto done;
}
// Validate digital signature.
if(!CryptVerifySignature(hHash, pbSignature, dwSigLen,
hPubKey, szDescription, 0)) {
if(GetLastError() == NTE_BAD_SIGNATURE) {
printf("Signature failed to validate!\n");
} else {
printf("Error %x during CryptSignHash!\n", GetLastError());
}
} else {
printf( Signature validated OK\n );
}
done:
...
// Release public key.
if(hPubKey != 0) CryptDestroyKey(hPubKey);
// Destroy hash object.
if(hHash != 0) CryptDestroyHash(hHash);
// Release provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);
See Also