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.
| Valore | Significato |
|---|---|
|
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. |
|
Questo flag non viene usato. |
|
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.
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 |
|---|---|
|
Uno dei parametri specifica un handle non valido. |
|
Uno dei parametri contiene un valore non valido. Questo è più spesso un puntatore che non è valido. |
|
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 . |
|
L'handle hHash specifica un algoritmo che questo CSP non supporta o il parametro dwKeySpec ha un valore non corretto. |
|
Il parametro dwFlags è diverso da zero. |
|
L'oggetto hash specificato dal parametro hHash non è valido. |
|
Impossibile trovare il contesto CSP specificato quando l'oggetto hash è stato creato. |
|
La chiave privata specificata da dwKeySpec non esiste. |
|
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 |