Funzione BCryptCreateHash (bcrypt.h)

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 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.

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

Vedere anche

BCryptDestroyHash