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:

AT_KEYEXCHANGE—key exchange key pair
AT_SIGNATURE—digital signature key pair

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 hash object is "finished," and the hash value extracted.
The hash value is padded out as required by the signature algorithm.
The actual signing operation is performed.

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.

CPSignHash

Parameters

Return Values

Remarks

See Also