Funzione BCryptCreateMultiHash (bcrypt.h)
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 |