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, optional] PUCHAR             pbHashObject,
  [in]            ULONG              cbHashObject,
  [in, optional]  PUCHAR             pbSecret,
  [in]            ULONG              cbSecret,
  [in]            ULONG              dwFlags
);

Parameter

[in, out] hAlgorithm

Das Handle eines Algorithmusanbieters, der die Hash- oder MAC-Schnittstelle unterstützt. Dieses Handle wird durch Aufrufen der BCryptOpenAlgorithmProvider-Funktion abgerufen oder kann ein CNG-Algorithmus-Pseudohandle sein.

[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 diesen Handle verwendet haben, lassen Sie es los, indem Sie es an die BCryptDestroyHash-Funktion übergeben.

[out, optional] 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 aus dem Algorithmushandle abzurufen. Dadurch wird die Größe des Hash- oder MAC-Objekts für den angegebenen Algorithmus bereitgestellt.

Dieser Speicher kann nur freigegeben werden, nachdem das handle, auf das der PhHash-Parameter verweist, zerstört wird.

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

[in] cbHashObject

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

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

[in, optional] pbSecret

Ein Zeiger auf einen Puffer, der den für einen MAC zu verwendenden Schlüssel enthält. Der cbSecret-Parameter enthält die Größe dieses Puffers. Bei Verwendung mit einem Hashalgorithmus muss der Algorithmus mithilfe des BCRYPT_ALG_HANDLE_HMAC Flags in BCryptOpenAlgorithmProvider zu HMAC heraufgestuft worden sein.

Um einen Hash zu berechnen, legen Sie diesen Parameter auf NULL.

[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:

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

Bei Verwendung eines unterstützten Algorithmusanbieters kann BCryptCreateHash entweder über den Benutzermodus oder den Kernelmodus aufgerufen werden. Kernelmodusaufrufer können entweder bei PASSIVE_LEVELIRQL oder DISPATCH_LEVEL IRQL ausgeführt werden. Wenn die aktuelle IRQL-Ebene DISPATCH_LEVEL ist, muss das im hAlgorithm-Parameter angegebene 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.

Der Aufrufer sollte phHash mit BCryptDestroyHash freigeben, wenn das Objekt nicht mehr verwendet wird.

Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Cng.libdas Driver Development Kit (DDK). Windows Server 2008 und Windows Vista: Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Ksecdd.lib.

Anforderungen

Siehe auch

BCryptDuplicateHash

BCryptHashData

BCryptFinishHash

BCryptDestroyHash