Funzione CryptSignHashA (wincrypt.h)

Articolo
08/27/2023

Importante Questa API è deprecata. Il software nuovo e esistente deve iniziare a usare le API di nuova generazione di crittografia. Microsoft può rimuovere questa API nelle versioni future.

La funzione CryptSignHash firma i dati. Poiché tutti gli algoritmi di firma sono asimmetrici e quindi lenti, CryptoAPI non consente la firma diretta dei dati. I dati vengono invece prima hashati e CryptSignHash viene usato per firmare l'hash.

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.

Valore	Significato
CRYPT_NOHASHOID 0x00000001	Usato con provider RSA. L'identificatore dell'oggetto hash (OID) non viene inserito nella crittografia della chiave pubblica RSA. Se questo flag non è impostato, l'OID hash nella firma predefinita è come specificato nella definizione di DigestInfo in PKCS #1.
CRYPT_TYPE2_FORMAT 0x00000002	Questo flag non viene usato.
CRYPT_X931_FORMAT 0x00000004	Usare il metodo di riempimento della firma RSA specificato nello standard ANSI X9.31.

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

Nota Quando si elaborano i dati restituiti nel buffer, le applicazioni devono usare le dimensioni effettive dei dati restituiti. Le dimensioni effettive possono essere leggermente inferiori rispetto alle dimensioni del buffer specificato nell'input. In base all'input, le dimensioni del buffer vengono in genere specificate abbastanza grandi per garantire che i dati di output più grandi siano adatti al buffer. Nell'output la variabile a cui punta questo parametro viene aggiornata per riflettere le dimensioni effettive dei dati copiati 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.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	Uno dei parametri specifica un handle non valido.
ERROR_INVALID_PARAMETER	Uno dei parametri contiene un valore non valido. Questo è più spesso un puntatore che non è valido.
ERROR_MORE_DATA	Il buffer specificato dal parametro pbSignature non è sufficiente per contenere i dati restituiti. Le dimensioni del buffer necessarie, in byte, si trovano nel valore pdwSigLenDWORD .
NTE_BAD_ALGID	L'handle hHash specifica un algoritmo che questo CSP non supporta o il parametro dwKeySpec ha un valore non corretto.
NTE_BAD_FLAGS	Il parametro dwFlags è diverso da zero.
NTE_BAD_HASH	L'oggetto hash specificato dal parametro hHash non è valido.
NTE_BAD_UID	Impossibile trovare il contesto CSP specificato quando l'oggetto hash è stato creato.
NTE_NO_KEY	La chiave privata specificata da dwKeySpec non esiste.
NTE_NO_MEMORY	Il provider di servizi di rete ha esaurito la memoria durante l'operazione.

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:

Creare un oggetto hash usando CryptCreateHash.
Impostare il valore hash nell'oggetto hash usando il valore HP_HASHVAL del parametro dwParam in CryptSetHashParam.
Firmare il valore hash usando CryptSignHash e ottenere un blocco di firma digitale.
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.

Nota

L'intestazione wincrypt.h definisce CryptSignHash come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wincrypt.h
Libreria	Advapi32.lib
DLL	Advapi32.dll