Funzione CryptCreateHash (wincrypt.h)

Articolo
03/09/2024

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 CryptCreateHash avvia l'hashing di un flusso di dati. Crea e restituisce all'applicazione chiamante un handle a un oggetto hash del provider di servizi di crittografia .CSP. Questo handle viene usato nelle chiamate successive a CryptHashData e CryptHashSessionKey per hashare le chiavi di sessione e altri flussi di dati.

Sintassi

BOOL CryptCreateHash(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  HCRYPTKEY  hKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTHASH *phHash
);

Parametri

[in] hProv

Handle a un CSP creato da una chiamata a CryptAcquireContext.

[in] Algid

Valore ALG_ID che identifica l'algoritmo hash da usare.

I valori validi per questo parametro variano a seconda del CSP usato. Per un elenco di algoritmi predefiniti, vedere Osservazioni.

[in] hKey

Se il tipo di algoritmo hash è un hash chiave, ad esempio l'algoritmo HMAC ( Hash-Based Message Authentication Code ) o Message Authentication Code (MAC), la chiave per l'hash viene passata in questo parametro. Per gli algoritmi non con chiave, questo parametro deve essere impostato su zero.

Per gli algoritmi chiave, la chiave deve essere in una chiave di crittografia a blocchi , ad esempio RC2, che ha una modalità di crittografia della catena a blocchi di crittografia (CBC).

[in] dwFlags

Il valore del flag seguente è definito.

Valore	Significato
CRYPT_SECRETDIGEST 0x00000001	Questo flag non viene usato.

[out] phHash

Indirizzo a cui la funzione copia un handle nel nuovo oggetto hash. Al termine dell'uso dell'oggetto hash, rilasciare l'handle chiamando la funzione CryptDestroyHash .

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 dall'NTE vengono generati dal particolare CSP in uso. La tabella seguente mostra alcuni dei possibili codici di errore.

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_NOT_ENOUGH_MEMORY	Il sistema operativo ha esaurito la memoria durante l'operazione.
NTE_BAD_ALGID	Il parametro Algid specifica un algoritmo che questo CSP non supporta.
NTE_BAD_FLAGS	Il parametro dwFlags è diverso da zero.
NTE_BAD_KEY	Un algoritmo hash con chiave, ad esempio CALG_MAC, viene specificato da Algid e il parametro hKey è zero o specifica un handle di chiave non valido. Questo codice di errore viene restituito anche se la chiave è in una crittografia di flusso o se la modalità di crittografia è diversa da CBC.
NTE_NO_MEMORY	Il provider di servizi di rete ha esaurito la memoria durante l'operazione.

Commenti

Per un elenco dei provider di servizi Microsoft e degli algoritmi implementati, vedere Provider di servizi di crittografia Microsoft.

Il calcolo dell'hash effettivo viene eseguito con le funzioni CryptHashData e CryptHashSessionKey. Questi richiedono un handle per l'oggetto hash. Dopo aver aggiunto tutti i dati all'oggetto hash, è possibile eseguire una delle operazioni seguenti:

Il valore hash può essere recuperato usando CryptGetHashParam.
Una chiave di sessione può essere derivata usando CryptDeriveKey.
L'hash può essere firmato usando CryptSignHash.
Una firma può essere verificata usando CryptVerifySignature.

Dopo aver chiamato una delle funzioni di questo elenco, non è possibile chiamare CryptHashData e CryptHashSessionKey.

Esempio

Nell'esempio seguente viene illustrato l'avvio dell'hashing di un flusso di dati. Crea e restituisce all'applicazione chiamante un handle in un oggetto hash. Questo handle viene usato nelle chiamate successive a CryptHashData e CryptHashSessionKey per hashare qualsiasi flusso di dati. Per un esempio che include il contesto completo per questo esempio, vedere Esempio di programma C: Creazione e hashing di una chiave di sessione. Per un altro esempio che usa questa funzione, vedere Esempio di programma C: firma di un hash e verifica della firma hash.

//--------------------------------------------------------------------
//  Declare variables.

HCRYPTPROV hCryptProv;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// Get a handle to a cryptography provider context.


if(CryptAcquireContext(
   &hCryptProv, 
   NULL, 
   NULL, 
   PROV_RSA_FULL, 
   0)) 
{
    printf("CryptAcquireContext complete. \n");
}
else
{
     printf("Acquisition of context failed.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Acquire a hash object handle.

if(CryptCreateHash(
   hCryptProv, 
   CALG_MD5, 
   0, 
   0, 
   &hHash)) 
{
    printf("An empty hash object has been created. \n");
}
else
{
    printf("Error during CryptBeginHash!\n");
    exit(1);
}

// Insert code that uses the hash object here.

//--------------------------------------------------------------------
// After processing, hCryptProv and hHash must be released.

if(hHash) 
   CryptDestroyHash(hHash);
if(hCryptProv) 
   CryptReleaseContext(hCryptProv,0);

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