BCryptCreateHash-Funktion (bcrypt.h)

  • Artikel

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 Funktion BCryptOpenAlgorithmProvider 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 das Hash- oder MAC-Objekt darstellt. Dieses Handle wird in nachfolgenden Hashing- oder MAC-Funktionen wie der BCryptHashData-Funktion verwendet. Wenn Sie mit der Verwendung dieses Handles fertig sind, geben Sie es frei, 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 Arbeitsspeicher kann erst freigegeben werden, nachdem das Handle, auf das der parameter phHash verweist, zerstört wurde.

Wenn der Wert dieses Parameters NULL und der Wert des cbHashObject-Parameters null ist, wird der Arbeitsspeicher 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 und der Wert des pbHashObject-ParametersNULL ist, wird der Arbeitsspeicher 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 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 flags BCRYPT_ALG_HANDLE_HMAC_FLAG geöffnet werden. Legen Sie andernfalls diesen Parameter auf NULL fest.

[in] cbSecret

Die Größe des pbSecret-Puffers in Bytes. 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 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.

Windows Server 2008 R2, Windows 7, Windows Server 2008 und Windows Vista: Dieses Flag wird nicht unterstützt.

Rückgabewert

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

Mögliche Rückgabecodes umfassen folgendes, sind aber nicht darauf beschränkt.

Rückgabecode Beschreibung
STATUS_SUCCESS
 Die Funktion war erfolgreich.
STATUS_BUFFER_TOO_SMALL
 Die Größe des durch den cbHashObject-Parameter angegebenen Hashobjekts ist nicht groß genug, um das Hashobjekt aufzunehmen.
STATUS_INVALID_HANDLE
 Das Algorithmushandle im Parameter hAlgorithm 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.

Hinweise

Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptCreateHash entweder im Benutzermodus oder im Kernelmodus aufgerufen werden. Kernelmodusaufrufer können entweder PASSIVE_LEVELIRQL oder DISPATCH_LEVEL IRQL ausführen. Wenn die aktuelle IRQL-Ebene DISPATCH_LEVEL ist, muss das im 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 ausgestellten (oder gesperrten) Arbeitsspeicher verweisen.

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

Anforderungen

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

Weitere Informationen

BCryptDestroyHash