Funzione BCryptCreateHash (bcrypt.h)

Articolo
07/16/2024

Viene chiamata la funzione di BCryptCreateHash per creare un hash o oggetto Message Authentication Code (MAC).

Sintassi

NTSTATUS BCryptCreateHash(
  [in, out]      BCRYPT_ALG_HANDLE  hAlgorithm,
  [out]          BCRYPT_HASH_HANDLE *phHash,
  [out]          PUCHAR             pbHashObject,
  [in, optional] ULONG              cbHashObject,
  [in, optional] PUCHAR             pbSecret,
  [in]           ULONG              cbSecret,
  [in]           ULONG              dwFlags
);

Parametri

[in, out] hAlgorithm

Handle di un provider di algoritmi creato usando la funzione BCryptOpenAlgorithmProvider. L'algoritmo specificato al momento della creazione del provider deve supportare l'interfaccia hash.

[out] phHash

Puntatore a un valore BCRYPT_HASH_HANDLE che riceve un handle che rappresenta l'oggetto hash o MAC. Questo handle viene usato nelle funzioni hash o MAC successive, ad esempio la funzione BCryptHashData. Al termine dell'uso di questo handle, rilasciarlo passandolo alla funzione BCryptDestroyHash .

[out] pbHashObject

Puntatore a un buffer che riceve l'hash o l'oggetto MAC. Il parametro cbHashObject contiene le dimensioni di questo buffer. Le dimensioni necessarie di questo buffer possono essere ottenute chiamando la funzione BCryptGetProperty per ottenere la proprietà BCRYPT_OBJECT_LENGTH. In questo modo verranno fornite le dimensioni dell'oggetto hash o MAC per l'algoritmo specificato.

Questa memoria può essere liberata solo dopo che l'handle a cui punta il parametro phHash viene eliminato definitivamente.

Se il valore di questo parametro è null e il valore del parametro cbHashObject è zero, la memoria per l'oggetto hash viene allocata e liberata da questa funzione. Windows 7: Questa funzionalità di gestione della memoria è disponibile a partire da Windows 7.

[in, optional] cbHashObject

Dimensioni, in byte, del buffer di pbHashObject.

Se il valore di questo parametro è zero e il valore del parametro pbHashObject è NULL, la memoria per l'oggetto chiave viene allocata e liberata da questa funzione. Windows 7: Questa funzionalità di gestione della memoria è disponibile a partire da Windows 7.

[in, optional] pbSecret

Puntatore a un buffer contenente la chiave da usare per l'hash o MAC. Il parametro cbSecret contiene le dimensioni di questo buffer. Questa chiave si applica solo agli algoritmi hash aperti dalla funzione BCryptOpenAlgorithmProvider usando il flag BCRYPT_ALG_HANDLE_HMAC_FLAG . In caso contrario, impostare questo parametro su NULL.

[in] cbSecret

Dimensioni, in byte, del buffer pbSecret . Se non viene usata alcuna chiave, impostare questo parametro su zero.

[in] dwFlags

Flag che modificano il comportamento della funzione. Può essere zero o il valore seguente.

Valore	Significato
BCRYPT_HASH_REUSABLE_FLAG	Crea un oggetto hash riutilizzabile. L'oggetto può essere usato per una nuova operazione di hashing immediatamente dopo aver chiamato BCryptFinishHash. Per altre informazioni, vedere Creazione di un hash con CNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 e Windows Vista: Questo flag non è supportato.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.

I codici restituiti possibili includono, ma non solo, quanto segue.

Codice restituito	Descrizione
STATUS_SUCCESS	La funzione ha avuto esito positivo.
STATUS_BUFFER_TOO_SMALL	Le dimensioni dell'oggetto hash specificato dal parametro cbHashObject non sono sufficienti per contenere l'oggetto hash.
STATUS_INVALID_HANDLE	L'handle dell'algoritmo nel parametro hAlgorithm non è valido.
STATUS_INVALID_PARAMETER	Uno o più parametri non sono validi.
STATUS_NOT_SUPPORTED	Il provider di algoritmi specificato dal parametro hAlgorithm non supporta l'interfaccia hash.

Osservazioni

A seconda delle modalità del processore supportate da un provider, BCryptCreateHash può essere chiamato dalla modalità utente o dal kernel. I chiamanti in modalità kernel possono essere eseguiti in PASSIVE_LEVELirQL o DISPATCH_LEVEL IRQL. Se il livello IRQL corrente è DISPATCH_LEVEL, l'handle fornito nella parametro hAlgorithm deve essere stato aperto usando il flag BCRYPT_PROV_DISPATCH e qualsiasi puntatore passato alla funzione BCryptCreateHash deve fare riferimento alla memoria non di paging (o bloccata).

Per chiamare questa funzione in modalità kernel, usare Cng.lib, che fa parte del Driver Development Kit (DDK). Per altre informazioni, vedere WDK e Developer Tools.Windows Server 2008 e Windows Vista: Per chiamare questa funzione in modalità kernel, usare Ksecdd.lib.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	bcrypt.h
libreria	Bcrypt.lib
dll	Bcrypt.dll

Vedere anche

BCryptDestroyHash

Condividi tramite