BCryptCreateMultiHash-Funktion (bcrypt.h)

Artikel
02/26/2024

Die BCryptCreateMultiHash-Funktion erstellt einen Zustand mit mehreren Hashs, der die parallele Berechnung mehrerer Hashvorgänge ermöglicht. Dieser Zustand mit mehreren Hashs wird von der BCryptProcessMultiOperations-Funktion verwendet. Der Zustand mit mehreren Hashs kann als Array von Hashobjekten betrachtet werden, die jeweils einem von BCryptCreateHash erstellten entspricht.

Parallele Berechnungen können den Gesamtdurchsatz auf Kosten einer erhöhten Latenz für einzelne Berechnungen erheblich erhöhen.

Parallele Hashberechnungen werden derzeit nur für SHA-256, SHA-384 und SHA-512 implementiert. Andere Hashalgorithmen können mit der parallelen Berechnungs-API verwendet werden, aber sie werden mit dem Durchsatz der sequenziellen Hashvorgänge ausgeführt. Der Satz von Hashalgorithmen, die von parallelen Berechnungen profitieren können, kann sich in zukünftigen Updates ändern.

Syntax

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

Parameter

hAlgorithm

BCRYPT_ALG_HANDLE[in, out]

Das Algorithmushandle, das für alle Hashzustände im Multihasharray verwendet wird. Das Algorithmushandle muss mit der BCYRPT_MULTI_FLAG geöffnet worden sein, die an die Funktion BCryptOpenAlgorithmProvider übergeben wurde. Alternativ kann der Aufrufer die Pseudohandles verwenden.

phHash

BCRYPT_HASH_HANDLE* [out]

Ein Zeiger auf einen BCRYPT_HASH_HANDLE-Wert , der ein Handle empfängt, das den Zustand mit mehreren Hashs darstellt. Dieses Handle wird in nachfolgenden Vorgängen wie BCryptProcessMultiOperations verwendet. Wenn Sie mit der Verwendung dieses Handles fertig sind, geben Sie es frei, indem Sie es an die BCryptDestroyHash-Funktion übergeben.

nHashes

ULONG[in]

Die Anzahl der Elemente im Array. Der multihash-Zustand, den diese Funktion erstellt, ist in der Lage, parallele Berechnungen für nHashes unterschiedlichen Hashzuständen durchzuführen.

pbHashObject

PUCHAR[out]

Ein Zeiger auf einen Puffer, der den Zustand mit mehreren Hashs empfängt.

Die Größe kann aus den Elementen cbPerObject und cbPerElement der BCRYPT_MULTI_OBJECT_LENGTH_STRUCT-Struktur berechnet werden. Der Wert ist wie folgt: cbPerObject + (number of hash states) * cbPerElement.

Wenn pbHashObject ist NULL und cbHashObject den Wert 0 (0) aufweist, wird der Objektpuffer automatisch zugeordnet.

cbHashObject

ULONG[in]

Die Größe des pbHashObject-Puffers oder null (0), wenn pbHashObject ist NULL.

pbSecret

PUCHAR[in]

Ein Zeiger auf einen Puffer, der den Schlüssel enthält, der für den Hash oder MAC verwendet werden soll. Der cbSecret-Parameter enthält die Größe dieses Puffers. Dieser Schlüssel gilt nur für Hashalgorithmen, die von der BCryptOpenAlgorithmProvider-Funktion mithilfe des BCRYPT_ALG_HANDLE_HMAC-Flags geöffnet werden. Legen Sie andernfalls diesen Parameter auf fest NULL.

Derselbe Schlüssel wird für alle Elemente des Arrays verwendet.

cbSecret

ULONG[in]

Die Größe des pbSecret-Puffers in Bytes. Wenn kein Schlüssel verwendet wird, legen Sie diesen Parameter auf Null (0) fest.

dwFlags

ULONG[in]

Flags, die das Verhalten der Funktion ändern. Dies kann null oder die folgenden Werte sein. Objekte mit mehreren Hashs sind immer wiederverwendbar und verhalten sich immer so, als ob die BCRYPT_HASH_REUSABLE_FLAG übergeben wurde. Dieses Flag wird hier aus Gründen der Konsistenz unterstützt.

Wert	Bedeutung
BCRYPT_HASH_REUSABLE_FLAG	Erstellt ein wiederverwendbares Hashingobjekt. Das -Objekt kann unmittelbar nach dem Aufrufen von BCryptFinishHash für einen neuen Hashvorgang verwendet werden. Weitere Informationen finden Sie unter Erstellen eines Hashs mit CNG.

Rückgabewert

Gibt einen status Code zurück, der den Erfolg oder Fehler der Funktion angibt. Wenn die Methode erfolgreich ist, wird zurückgegeben STATUS_SUCCESS. Weitere NTSTATUS-Werte finden Sie unter NTSTATUS-Werte.

Hinweise

Intern werden parallele Hashberechnungen mithilfe von SimD-Anweisungen (Single-Instruction Multiple-Data) mit bis zu 8 parallelen Berechnungen gleichzeitig durchgeführt, abhängig vom Hashalgorithmus und den verfügbaren CPU-Features. Um die Leistung zu maximieren, wird empfohlen, dass der Aufrufer mindestens acht Berechnungen bereitstellt, die parallel verarbeitet werden können.

Bei Berechnungen ungleicher Länge ermöglicht die Bereitstellung von mehr Berechnungen parallel dazu, dass die Implementierung die Berechnungen für die CPU-Register besser planen kann. Dies kann einen Durchsatzvorteil bieten. Für einen optimalen Durchsatz wird empfohlen, dass der Aufrufer zwischen acht und 100 Berechnungen bereitstellt. Wählen Sie in diesem Bereich nur dann einen niedrigeren Wert aus, wenn alle Hashberechnungen dieselbe Länge aufweisen.

Multihashing wird für HMAC-MD2, HMAC-MD4 und GMAC nicht unterstützt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8.1 Update [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 Update [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	bcrypt.h
Bibliothek	Bcrypt.lib
DLL	Bcrypt.dll