Export (0) Print
Expand All

CryptSignHash

Windows Mobile 6.5
A version of this page is also available for
4/8/2010

This function signs data. Because all signature algorithms are asymmetric and therefore slow, the CryptoAPI does not let data be signed directly. Instead, you must first hash the data and then use the CryptSignHash function to sign the hash value.


BOOL WINAPI CryptSignHash( 
  HCRYPTHASH hHash, 
  DWORD dwKeySpec, 
  LPCTSTR sDescription, 
  DWORD dwFlags,
  BYTE* pbSignature, 
  DWORD* pdwSigLen
);

hHash

[in] HCRYPTHASH handle to the hash object to be signed.

dwKeySpec

[in] Specifies the key pair to use to sign the hash. The following table shows the keys that are defined.

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 Microsoft Base Cryptographic Provider only supports the RSA public-key signature algorithm.

sDescription

[in] No longer used and must be set to NULL to prevent security vulnerabilities. However, it is still supported for backward compatibility in the Microsoft Base Cryptographic Provider.

dwFlags

[in] Reserved for future use and must be set to zero.

pbSignature

[out] Pointer to a buffer that receives the signature data.

This parameter can be NULL to set the buffer size for memory allocation purposes.

pdwSigLen

[in, out] On input, pointer to a DWORD value that specifies the size, in bytes, of the buffer pointed to by the pdwSigLen parameter. On output, the DWORD value contains the number of bytes stored in the buffer.

When processing the data returned in the buffer, applications must 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 ensure 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.

TRUE indicates success. FALSE indicates failure. To get extended error information, call the GetLastError function.

The following table shows the common values for the GetLastError function. The error values prefaced by NTE are generated by the particular cryptographic service provider (CSP) you are using.

Value 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.

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

After this function is called, no more data can be added to the hash. Additional calls to the CryptHashData or CryptHashSessionKey functions fail.

After the application finishes using the hash, the CryptDestroyHash function must be called to destroy the hash object.

Windows Embedded CE does not support the ANSI version of this function.

#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 using CryptAcquireContext.
// For sample code, see <A HREF="wce50lrfcryptacquirecontext.htm">CryptAcquireContext</A>.
...
...
// 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);
// Free the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);

Headerwincrypt.h
Librarycoredll.lib
Windows Embedded CEWindows CE 2.10 and later
Windows MobileWindows Mobile Version 5.0 and later

Community Additions

ADD
Show:
© 2014 Microsoft