CPSignHash

The CPSignHash function signs a hash object.

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 within the CSP. This handle is obtained by a call to CPAcquireContext.

hHash

Handle to the hash object to be signed.

dwKeySpec

Type of the key pair to be used to sign the hash. The following values are currently defined.

Value	Meaning
AT_KEYEXCHANGE	The key exchange public/private key pair is to be used.
AT_SIGNATURE	The digital signature public/private key pair is to be used.

sDescription

A NULL-terminated string with a description of the hash object to be signed. See the Remarks section for details.

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 use with RSA providers.

CRYPT_NOHASHOID

The hash OID is not placed into the RSA public key encryption. If this flag is not set, the hash OID in the default signature is as specified in the definition of DigestInfo in PKCS #7.

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.

pbSignature

Pointer to a data buffer into which the signature data is to be placed.

It is not an error if this parameter is NULL. If pbData is NULL, no parameter data is copied. Instead, the required buffer size (in bytes) is returned in pdwSigLen and a second call to the function with the correct number of bytes allocated for the pbData buffer is expected. For a detailed discussion and examples, see Retrieving Data of Unknown Length.

pdwSigLen

Address of a DWORD value of the signature data length. Upon function entry, this DWORD value contains the number of bytes allocated for the pbSignature buffer. Upon exit, it is set to the number of bytes required for the pbSignature buffer.

If memory allocated for the pbSignature buffer is not large enough to hold the signature, the ERROR_MORE_DATA error code is returned by the SetLastError function. The required buffer size is returned in pdwDataLen.

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

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.

Remarks

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

CPSignHash typically performs the following steps internally:

1. The hash object is "finished," and the hash value extracted.
2. The hash value is padded out as required by the signature algorithm.
3. The actual signing operation is performed.

The CPSignHash function completes the hash. After calling CPSignHash, 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.

See Also

CPCreateHash, CPHashData, CPVerifySignature, CryptSignHash