CryptSignHash

The CryptSignHash function is used to sign a piece of data. Because all signature algorithms are asymmetric and thus incredibly slow, the CryptoAPI will not let data be signed directly. Instead, you must first hash the data and then use CryptSignHash to sign the hash value.

#include <wincrypt.h>
BOOL WINAPI CryptSignHash(
  HCRYPTHASH hHash,     // in
  DWORD dwKeySpec,      // in
  LPCTSTR sDescription, // in
  DWORD dwFlags,        // in
  BYTE *pbSignature,    // out
  DWORD *pdwSigLen      // in/out
);

Parameters

hHash

Handle to the hash object to be signed.

dwKeySpec

Key pair to use to sign the hash. The following keys can be specified.

Value	Description
AT_KEYEXCHANGE	Exchange private key
AT_SIGNATURE	Signature private key

The signature algorithm used is specified when the key pair was originally created.

The only signature algorithm that the Microsoft Base Cryptographic Provider supports is the RSA Public-Key algorithm.

sDescription

This parameter should no longer be used, and should be set to NULL to prevent security vulnerabilities. However, it is still supported for backward compatibility in the Microsoft Base Cryptographic Provider.

dwFlags

Flag values. This parameter is reserved for future use and should always be zero.

pbSignature

Pointer to a buffer that receives the signature data.

This parameter can be NULL to set the size of this information for memory allocation purposes. For more information, see Common In/Out Parameter Conventions.

pdwSigLen

Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pdwSigLen parameter. When the function returns, the variable pointed to by the pdwSigLen parameter contains the number of bytes stored in the buffer. This parameter can be NULL, only if pbSignature is NULL.

Note that when processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to insure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

Return Values

If the function succeeds, the return value is TRUE. If it fails, the return value is FALSE. 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.

Error code	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.
ERROR_MORE_DATA	If the buffer specified by the pbSignature parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code and stores the required buffer size, in bytes, into the variable pointed to by pdwSigLen.
NTE_BAD_ALGID	The hHash handle specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
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 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

Before calling this function, the CryptCreateHash function must be called to get a handle to a hash object. The CryptHashData or CryptHashSessionKey function is then used to add the data or session keys to the hash object.

After this function has been completed, the only hash function that can be called using the hHash handle is the CryptDestroyHash function.

Example

#include <wincrypt.h>

HCRYPTPROV hProv = 0;
#define BUFFER_SIZE 256
BYTE pbBuffer[BUFFER_SIZE];
HCRYPTHASH hHash = 0;
BYTE *pbSignature = NULL;
DWORD dwSigLen;
LPTSTR szDescription = TEXT("Test Data");
DWORD i;

// Get a handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
    printf("Error %x during CryptAcquireContext!\n", GetLastError());
    goto done;
}

// Fill the buffer with test data.
for(i = 0 ; i < BUFFER_SIZE ; i++) {
    pbBuffer[i] = (BYTE)i;
}

// Create a hash object.
if(!CryptCreateHash(hProv, CALG_MD5, 0, 0, &hHash)) {
    printf("Error %x during CryptCreateHash!\n", GetLastError());
    goto done;
}

// Compute the cryptographic hash of the buffer.
if(!CryptHashData(hHash, pbBuffer, BUFFER_SIZE, 0)) {
    printf("Error %x during CryptHashData!\n", GetLastError());
    goto done;
}

// Determine the size of the signature and allocate memory.
dwSigLen= 0;
if(!CryptSignHash(hHash, AT_SIGNATURE, TEXT(""), 0, NULL, 
                        &dwSigLen)) {
    printf("Error %x during CryptSignHash!\n", GetLastError());
    if(GetLastError()!=NTE_BAD_LEN) goto done;
}
if((pbSignature = malloc(dwSigLen)) == NULL) {
    printf("Out of memory!\n");
    goto done;
}

// Sign the hash object.
if(!CryptSignHash(hHash, AT_SIGNATURE, szDescription, 0, pbSignature, 
                        &dwSigLen)) {
    printf("Error %x during CryptSignHash!\n", GetLastError());
    goto done;
}

// Store or transmit the signature, test buffer, and description string.
...

done:

// Free memory to be used to store signature.
if(pbSignature != NULL) free(pbSignature);

// Destroy the hash object.
if(hHash != 0) CryptDestroyHash(hHash);

// Release the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);

QuickInfo