Funzione BCryptCreateMultiHash (bcrypt.h)

Articolo
02/23/2024

La funzione BCryptCreateMultiHash crea uno stato multi-hash che consente il calcolo parallelo di più operazioni hash. Questo stato multi-hash viene usato dalla funzione BCryptProcessMultiOperations . Lo stato multi-hash può essere considerato come una matrice di oggetti hash, ognuno dei quali equivale a uno creato da BCryptCreateHash.

I calcoli paralleli possono aumentare notevolmente la velocità effettiva complessiva, a spese di una maggiore latenza per i singoli calcoli.

I calcoli hash paralleli sono attualmente implementati solo per SHA-256, SHA-384 e SHA-512. Altri algoritmi hash possono essere usati con l'API di calcolo parallelo, ma vengono eseguiti alla velocità effettiva delle operazioni hash sequenziali. Il set di algoritmi hash che possono trarre vantaggio dai calcoli paralleli potrebbe cambiare negli aggiornamenti futuri.

Sintassi

NTSTATUS BCryptCreateMultiHash(
  BCRYPT_ALG_HANDLE  hAlgorithm,
  BCRYPT_HASH_HANDLE *phHash,
  ULONG              nHashes,
  PUCHAR             pbHashObject,
  ULONG              cbHashObject,
  PUCHAR             pbSecret,
  ULONG              cbSecret,
  ULONG              dwFlags
);

Parametri

hAlgorithm

BCRYPT_ALG_HANDLE[in, out]

Handle dell'algoritmo usato per tutti gli stati hash nella matrice multi-hash. L'handle dell'algoritmo deve essere stato aperto con il BCYRPT_MULTI_FLAG passato alla funzione BCryptOpenAlgorithmProvider . In alternativa, il chiamante può usare gli pseudo-handle.

phHash

BCRYPT_HASH_HANDLE* [out]

Puntatore a un valore BCRYPT_HASH_HANDLE che riceve un handle che rappresenta lo stato multi-hash. Questo handle viene usato nelle operazioni successive, ad esempio BCryptProcessMultiOperations. Al termine dell'uso di questo handle, rilasciarlo passandolo alla funzione BCryptDestroyHash .

nHashes

ULONG[in]

Numero di elementi nella matrice. Lo stato multi-hash creato da questa funzione è in grado di eseguire calcoli paralleli in nHashes diversi stati hash.

pbHashObject

PUCHAR[out]

Puntatore a un buffer che riceve lo stato multi-hash.

Le dimensioni possono essere calcolate dai membri cbPerObject e cbPerElement della struttura BCRYPT_MULTI_OBJECT_LENGTH_STRUCT. Il valore è il seguente: cbPerObject + (number of hash states) * cbPerElement.

Se pbHashObject è e cbHashObject ha NULL un valore pari a zero (0), il buffer dell'oggetto viene allocato automaticamente.

cbHashObject

ULONG[in]

Dimensioni del buffer pbHashObject o zero (0) se pbHashObject è NULL.

pbSecret

PUCHAR[in]

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 BCRYPT_ALG_HANDLE_HMAC . In caso contrario, impostare questo parametro su NULL.

La stessa chiave viene usata per tutti gli elementi della matrice.

cbSecret

ULONG[in]

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

dwFlags

ULONG[in]

Contrassegni che modificano il comportamento della funzione. Questo può essere zero o i valori seguenti. Gli oggetti multi-hash sono sempre riutilizzabili e si comportano sempre come se il BCRYPT_HASH_REUSABLE_FLAG fosse passato. Questo flag è supportato qui per la coerenza.

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.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione. Se il metodo ha esito positivo, restituirà STATUS_SUCCESS. Per altri valori NTSTATUS, vedere Valori NTSTATUS.

Commenti

Internamente, i calcoli hash paralleli vengono eseguiti usando istruzioni simD (Single-Instruction Multiple-Data) con un massimo di 8 calcoli paralleli alla volta, a seconda dell'algoritmo hash e delle funzionalità della CPU disponibili. Per ottimizzare le prestazioni, è consigliabile che il chiamante fornisca almeno otto calcoli che possono essere elaborati in parallelo.

Per i calcoli di lunghezza non uguale, fornendo più calcoli in parallelo consente all'implementazione di pianificare meglio i calcoli nei registri della CPU. Ciò può offrire un vantaggio di velocità effettiva. Per una velocità effettiva ottimale, è consigliabile che il chiamante fornisca tra otto e 100 calcoli. Selezionare un valore inferiore in tale intervallo solo se tutti i calcoli hash sono la stessa lunghezza.

Il multi-hashing non è supportato per HMAC-MD2, HMAC-MD4 e GMAC.

Requisiti

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