Condividi tramite


Funzione CryptSignHashA (wincrypt.h)

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:

  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.

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

Vedi anche

CryptCreateHash

CryptDestroyHash

CryptHashData

CryptHashSessionKey

CryptVerifySignature

Funzioni hash e firma digitale