Funzione CryptSignHashA (wincrypt.h)

Sintassi

BOOL CryptSignHashA(
  [in]      HCRYPTHASH hHash,
  [in]      DWORD      dwKeySpec,
  [in]      LPCSTR     szDescription,
  [in]      DWORD      dwFlags,
  [out]     BYTE       *pbSignature,
  [in, out] DWORD      *pdwSigLen
);

Parametri

[in] hHash

Handle dell'oggetto hash da firmare.

[in] dwKeySpec

Identifica la chiave privata da usare dal contenitore del provider. Può essere AT_KEYEXCHANGE o AT_SIGNATURE.

L'algoritmo di firma usato viene specificato quando la coppia di chiavi viene originariamente creata.

L'unico algoritmo di firma supportato dal provider di crittografia di Base Microsoft è l'algoritmo RSA Public Key.

[in] szDescription

Questo parametro non viene più usato e deve essere impostato su NULL per evitare vulnerabilità di sicurezza. Tuttavia, è ancora supportato per la compatibilità con le versioni precedenti nel provider di crittografia di base Microsoft.

[in] dwFlags

I valori di flag seguenti sono definiti.

[out] pbSignature

Puntatore a un buffer che riceve i dati della firma.

Questo parametro può essere NULL per impostare le dimensioni del buffer a scopo di allocazione della memoria. Per altre informazioni, vedere Recupero dei dati di lunghezza sconosciuta.

[in, out] pdwSigLen

Puntatore a un valore DWORD che specifica le dimensioni, in byte, del buffer pbSignature . Quando la funzione restituisce, il valore DWORD contiene il numero di byte archiviati nel buffer.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce TRUE.

Se la funzione ha esito negativo, restituisce FALSE. Per informazioni sull'errore estese, chiamare GetLastError.

I codici di errore preceduti da "NTE" vengono generati dal particolare CSP usato. Alcuni codici di errore possibili seguono.

Commenti

Prima di chiamare questa funzione, la funzione CryptCreateHash deve essere chiamata per ottenere un handle a un oggetto hash. La funzione CryptHashData o CryptHashSessionKey viene quindi usata per aggiungere i dati o le chiavi di sessione all'oggetto hash. La funzione CryptSignHash completa l'hash.

Anche se il CSP DSS supporta l'hashing con gli algoritmi hash MD5 e SHA, il CSP DSS supporta solo gli hash SHA di firma.

Dopo aver chiamato questa funzione, non è possibile aggiungere altri dati all'hash. Le chiamate aggiuntive a CryptHashData o CryptHashSessionKey hanno esito negativo.

Al termine dell'applicazione usando l'hash, eliminare l'oggetto hash chiamando la funzione CryptDestroyHash .

Per impostazione predefinita, i provider MICROSOFT RSA usano il metodo di riempimento PKCS #1 per la firma. L'OID hash nell'elemento DigestInfo della firma viene impostato automaticamente sull'OID dell'algoritmo associato all'oggetto hash. L'uso del flag di CRYPT_NOHASHOID causerà l'omesso dell'OID dalla firma.

In alcuni casi, è necessario firmare un valore hash generato altrove. Questa operazione può essere eseguita usando la sequenza di operazioni seguente:

1. Creare un oggetto hash usando CryptCreateHash.
2. Impostare il valore hash nell'oggetto hash usando il valore HP_HASHVAL del parametro dwParam in CryptSetHashParam.
3. Firmare il valore hash usando CryptSignHash e ottenere un blocco di firma digitale.
4. Eliminare l'oggetto hash usando CryptDestroyHash.

Esempio

Nell'esempio seguente vengono illustrati i dati di firma eseguendo prima l'hashing dei dati da firmare e quindi firmando l'hash usando la funzione CryptSignHash .

//-------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV hProv;
BYTE *pbBuffer= (BYTE *)"Sample data that is to be signed.";
DWORD dwBufferLen = strlen((char *)pbBuffer)+1;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// This code assumes that a cryptographic context handle, hProv,
// and a hash handle, hHash, are available.
// For code needed to acquire the context, see "Example C Program: 
// Signing a Hash and Verifying the Hash Signature."

//--------------------------------------------------------------------
// Compute the cryptographic hash of the buffer.

if(CryptHashData(
   hHash, 
   pbBuffer, 
   dwBufferLen, 
   0)) 
{
     printf("The data buffer has been hashed.\n");
}
else
{
     printf("Error during CryptHashData.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Determine the size of the signature and allocate memory.

dwSigLen= 0;
if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   NULL, 
   &dwSigLen)) 
{
     printf("Signature length %d found.\n",dwSigLen);
}
else
{
     printf("Error during CryptSignHash\n");
     exit(1);
}
//--------------------------------------------------------------------
// Allocate memory for the signature buffer.

if(pbSignature = (BYTE *)malloc(dwSigLen))
{
     printf("Memory allocated for the signature.\n");
}
else
{
     printf("Out of memory\n");
     exit(1);
}
//--------------------------------------------------------------------
// Sign the hash object.

if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   pbSignature, 
   &dwSigLen)) 
{
     printf("pbSignature is the hash signature.\n");
}
else
{
     printf("Error during CryptSignHash.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Destroy the hash object.

if(hHash) 
  CryptDestroyHash(hHash);

Per un esempio completo, incluso il contesto per questo codice, vedere Esempio di programma C: firma di un hash e verifica della firma hash.

Requisiti

Vedi anche

CryptCreateHash

CryptDestroyHash

CryptHashData

CryptHashSessionKey

CryptVerifySignature

Funzioni hash e firma digitale