CPSignHash

The CPSignHash function is used by applications to sign hash values.

BOOL CPSignHash(
  HCRYPTPROV hProv,      // in
  HCRYPTHASH hHash,      // in
  DWORD dwKeySpec,       // in
  LPCWSTR sDescription,  // in
  DWORD dwFlags,         // in
  BYTE *pbSignature,     // out
  DWORD *pdwSigLen       // in, out
);
 

Parameters

hProv
Handle to a particular key container (or "context") within the CSP. This handle is obtained via a call to CPAcquireContext.
hHash
Handle to the hash object to be signed.
dwKeySpec
Key pair that is to be used to sign the hash. The following values are currently defined:
sDescription
Applications should no longer be using this parameter and should be set to NULL to prevent security vulnerabilities. However, CSPs may prefer to keep supporting it for backward compatibility with the Microsoft Providers.
dwFlags
Flag values. No flags are currently defined.
pbSignature
Buffer into which the signature data is to be placed.

If this parameter is NULL, then the signature operation is not performed. Instead, the required buffer size (in bytes) should be returned in pdwSigLen. This is not an error.

pdwSigLen
Address of the signature data length. Upon function entry, this contains the number of bytes in the pbSignature buffer. Upon exit, this must be set to the number of bytes of data copied to the pbSignature buffer.

If the buffer specified by pbSignature is not large enough to hold the signature, the ERROR_MORE_DATA error code should be returned via the SetLastError function. In this case, the required buffer size must be returned in pdwDataLen.

If this function fails with any error code other than ERROR_MORE_DATA, zero should be returned in this parameter.

Return Values

If the function succeeds, TRUE should be returned; otherwise, return FALSE. When FALSE is returned, the appropriate error code (see the following table) must be set via SetLastError.

Error Description
ERROR_MORE_DATA The pbData buffer is not large enough to hold the requested data.
NTE_BAD_ALGID The hHash handle specifies a hash algorithm that this function does not support.
NTE_BAD_FLAGS The dwFlags parameter is non-zero.
NTE_BAD_HASH The hash object specified by the hHash parameter is invalid.
NTE_BAD_UID The CSP context that was specified when the hash object was created cannot now be found.
NTE_NO_KEY The private key specified by dwKeySpec does not exist.
NTE_NO_MEMORY The CSP ran out of memory during the operation.

Remarks

Depending on the key pair that is to be used, many CSPs will ask the user directly before performing the signature operation. When this is the case, the sDescription string, if supported, should be displayed to the user so that he or she knows what is being signed.

The CPSignHash function typically performs the following steps internally:

The application should not be allowed to add more data to the hash object after it has been signed. However, the application is still responsible for calling the CPDestroyHash function.

See Also

CPCreateHash, CPHashData, CPVerifySignature, CryptSignHash