Funzione BCryptCreateHash (bcrypt.h)

  • Articolo

La funzione BCryptCreateHash viene chiamata per creare un oggetto hash o 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'hash o l'oggetto 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 puntato al parametro phHash viene distrutto.

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 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 che contiene 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 di 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

Contrassegni che modificano il comportamento della funzione. Questo valore può essere zero o il valore seguente.

Valore Significato
BCRYPT_HASH_REUSABLE_FLAG
 Crea un oggetto hashing 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 sono limitati a, i seguenti.

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.

Commenti

A seconda delle modalità di processore supportate da un provider, È possibile chiamare BCryptCreateHash dalla modalità utente o dalla modalità 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 nel parametro hAlgorithm deve essere stato aperto usando il flag BCRYPT_PROV_DISPATCH e tutti i puntatori passati alla funzione BCryptCreateHash devono fare riferimento alla memoria non di pagina (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.

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [app desktop | App UWP]
Server minimo supportato Windows Server 2008 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione bcrypt.h
Libreria Bcrypt.lib
DLL Bcrypt.dll

Vedi anche

BCryptDestroyHash