BCryptCreateHash-Funktion (bcrypt.h)

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.

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.

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

Siehe auch

BCryptDestroyHash