BCryptCreateHash-Funktion (bcrypt.h)

Artikel
07/16/2024

Die BCryptCreateHash--Funktion wird aufgerufen, um ein Hash- oder Message Authentication Code (MAC)-Objekt zu erstellen.

Syntax

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
);

Parameter

[in, out] hAlgorithm

Das Handle eines Algorithmusanbieters, der mithilfe der BCryptOpenAlgorithmProvider-Funktion erstellt wurde. Der Algorithmus, der beim Erstellen des Anbieters angegeben wurde, muss die Hashschnittstelle unterstützen.

[out] phHash

Ein Zeiger auf einen BCRYPT_HASH_HANDLE Wert, der ein Handle empfängt, das den Hash- oder MAC-Objekt darstellt. Dieses Handle wird in nachfolgenden Hashing- oder MAC-Funktionen wie der BCryptHashData--Funktion verwendet. Wenn Sie diesen Handle verwendet haben, lassen Sie es los, indem Sie es an die BCryptDestroyHash--Funktion übergeben.

[out] pbHashObject

Ein Zeiger auf einen Puffer, der das Hash- oder MAC-Objekt empfängt. Der cbHashObject Parameter enthält die Größe dieses Puffers. Die erforderliche Größe dieses Puffers kann durch Aufrufen der BCryptGetProperty--Funktion abgerufen werden, um die BCRYPT_OBJECT_LENGTH-Eigenschaft abzurufen. Dadurch wird die Größe des Hash- oder MAC-Objekts für den angegebenen Algorithmus bereitgestellt.

Dieser Speicher kann nur freigegeben werden, nachdem der handle, auf den der phHash Parameter verweist, zerstört wird.

Wenn der Wert dieses Parameters NULL- ist und der Wert des cbHashObject Parameter null ist, wird der Speicher für das Hashobjekt zugewiesen und von dieser Funktion freigegeben. Windows 7: Diese Speicherverwaltungsfunktion ist ab Windows 7 verfügbar.

[in, optional] cbHashObject

Die Größe des pbHashObject- Puffers in Bytes.

Wenn der Wert dieses Parameters null ist und der Wert des pbHashObject Parameter NULList, wird der Speicher für das Schlüsselobjekt zugewiesen und von dieser Funktion freigegeben. Windows 7: Diese Speicherverwaltungsfunktion ist ab Windows 7 verfügbar.

[in, optional] pbSecret

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

[in] cbSecret

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

[in] dwFlags

Flags, die das Verhalten der Funktion ändern. Dies kann null oder der folgende Wert sein.

Wert	Bedeutung
BCRYPT_HASH_REUSABLE_FLAG	Erstellt ein wiederverwendbares Hashing-Objekt. Das Objekt kann sofort nach dem Aufrufen BCryptFinishHashfür einen neuen Hashingvorgang verwendet werden. Weitere Informationen finden Sie unter Creating a Hash with CNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 und Windows Vista: Dieses Flag wird nicht unterstützt.

Rückgabewert

Gibt einen Statuscode zurück, der den Erfolg oder Fehler der Funktion angibt.

Mögliche Rückgabecodes umfassen, aber nicht beschränkt auf Folgendes.

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die Funktion war erfolgreich.
STATUS_BUFFER_TOO_SMALL	Die Größe des vom cbHashObject Parameter angegebenen Hashobjekts ist nicht groß genug, um das Hashobjekt aufzunehmen.
STATUS_INVALID_HANDLE	Der Algorithmushandle im hAlgorithm Parameter ist ungültig.
STATUS_INVALID_PARAMETER	Mindestens ein Parameter ist ungültig.
STATUS_NOT_SUPPORTED	Der vom hAlgorithm Parameter angegebene Algorithmusanbieter unterstützt die Hashschnittstelle nicht.

Bemerkungen

Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptCreateHash entweder über den Benutzermodus oder den Kernelmodus aufgerufen werden. Kernelmodusaufrufer können entweder PASSIVE_LEVELIRQL- oder DISPATCH_LEVEL IRQL ausgeführt werden. Wenn die aktuelle IRQL-Ebene DISPATCH_LEVEList, muss das in der hAlgorithm Parameter bereitgestellte Handle mithilfe des BCRYPT_PROV_DISPATCH-Flags geöffnet worden sein, und alle Zeiger, die an die BCryptCreateHash--Funktion übergeben werden, müssen auf nicht seitenseitigen (oder gesperrten) Speicher verweisen.

Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Cng.lib, das Teil des Driver Development Kit (DDK) ist. Weitere Informationen finden Sie unter WDK und Developer Tools.Windows Server 2008 und Windows Vista: Verwenden Sie Ksecdd.lib, um diese Funktion im Kernelmodus aufzurufen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	bcrypt.h
Library	Bcrypt.lib
DLL-	Bcrypt.dll

Siehe auch

BCryptDestroyHash

Freigeben über