Funzione CryptSignHashW (wincrypt.h)
Sintassi
BOOL CryptSignHashW(
[in] HCRYPTHASH hHash,
[in] DWORD dwKeySpec,
[in] LPCWSTR 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 creata in origine.
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
Vengono definiti i valori di flag seguenti.
| Valore | Significato |
|---|---|
|
Usato con i provider RSA. L'hash identificatore di oggetto (OID) non viene inserito nella crittografia della chiave pubblica RSA. Se questo flag non è impostato, l'OID hash nella firma predefinita viene specificato nella definizione di DigestInfo in PKCS #1. |
|
Questo flag non viene utilizzato. |
|
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 di dati di lunghezza sconosciuta.
[in, out] pdwSigLen
Puntatore a un valore DWORD
Valore restituito
Se la funzione ha esito positivo, la funzione restituisce TRUE.
Se la funzione non riesce, restituisce FALSE. Per informazioni sugli errori estesi, chiamare GetLastError.
I codici di errore preceduti da "NTE" vengono generati dal CSP specifico in uso. Di seguito sono riportati alcuni possibili codici di errore.
| Codice restituito | Descrizione |
|---|---|
|
Uno dei parametri specifica un handle non valido. |
|
Uno dei parametri contiene un valore non valido. Si tratta più spesso di un puntatore non valido. |
|
Il buffer specificato dal parametro pbSignature non è sufficientemente grande da contenere i dati restituiti. Le dimensioni del buffer richieste, in byte, si trovano nel valore pdwSigLenDWORD. |
|
L'handle di hHash |
|
Il parametro dwFlags è diverso da zero. |
|
L'oggetto hash specificato dal parametro hHash non è valido. |
|
Impossibile trovare il contesto CSP specificato quando è stato creato l'oggetto hash. |
|
La chiave privata specificata da dwKeySpec non esiste. |
|
Il provider di servizi di configurazione ha esaurito la memoria durante l'operazione. |
Osservazioni
Prima di chiamare questa funzione, è necessario chiamare la funzione
Mentre il provider di servizi di configurazione DSS supporta l'hashing con gli algoritmi hash MD5 e SHA, il provider di servizi di configurazione DSS supporta solo gli hash SHA di firma.
Dopo aver chiamato questa funzione, non è possibile aggiungere altri dati all'hash. Chiamate aggiuntive a CryptHashData o CryptHashSessionKey esito negativo.
Al termine dell'uso dell'hash, eliminare definitivamente 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 algoritmo associato all'oggetto hash. Se si usa il flag CRYPT_NOHASHOID, questo OID verrà omesso 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 definitivamente l'oggetto hash usando CryptDestroyHash.
Esempi
L'esempio seguente illustra la firma dei dati 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [solo app desktop] |
| server minimo supportato | Windows Server 2003 [solo app desktop] |
| piattaforma di destinazione | Finestre |
| intestazione |
wincrypt.h |
| libreria |
Advapi32.lib |
| dll | Advapi32.dll |