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