BCryptGenerateSymmetricKey-Funktion (bcrypt.h)

Artikel
07/16/2024

Die BCryptGenerateSymmetricKey-Funktion erstellt ein Schlüsselobjekt zur Verwendung mit einem symmetrischen Schlüsselverschlüsselungsalgorithmus aus einem bereitgestellten Schlüssel.

Syntax

NTSTATUS BCryptGenerateSymmetricKey(
  [in, out]       BCRYPT_ALG_HANDLE hAlgorithm,
  [out]           BCRYPT_KEY_HANDLE *phKey,
  [out, optional] PUCHAR            pbKeyObject,
  [in]            ULONG             cbKeyObject,
  [in]            PUCHAR            pbSecret,
  [in]            ULONG             cbSecret,
  [in]            ULONG             dwFlags
);

Parameter

[in, out] hAlgorithm

Das Handle eines Algorithmusanbieters, der mit der BCryptOpenAlgorithmProvider-Funktion erstellt wurde. Der Algorithmus, der beim Erstellen des Anbieters angegeben wurde, muss die symmetrische Schlüsselverschlüsselung unterstützen.

[out] phKey

Ein Zeiger auf eine BCRYPT_KEY_HANDLE, die das Handle des Schlüssels empfängt. Dieses Handle wird in nachfolgenden Funktionen verwendet, die einen Schlüssel erfordern, z. B. BCryptEncrypt. Dieser Handle muss losgelassen werden, wenn es nicht mehr benötigt wird, indem es an die BCryptDestroyKey--Funktion übergeben wird.

[out, optional] pbKeyObject

Ein Zeiger auf einen Puffer, der das Schlüsselobjekt empfängt. Der cbKeyObject 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 Schlüsselobjekts für den angegebenen Algorithmus bereitgestellt.

Dieser Speicher kann nur freigegeben werden, nachdem der phKey- Tastenziehpunkt zerstört wurde.

Wenn der Wert dieses Parameters NULL- ist und der Wert des cbKeyObject Parameter null ist, 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] cbKeyObject

Die Größe des pbKeyObject- Puffers in Byte.

Wenn der Wert dieses Parameters null ist und der Wert des pbKeyObject 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] pbSecret

Zeigen Sie auf einen Puffer, der den Schlüssel enthält, aus dem das Schlüsselobjekt erstellt werden soll. Der cbSecret Parameter enthält die Größe dieses Puffers. Dies ist normalerweise ein Hash eines Kennworts oder einige andere reproduzierbare Daten. Wenn die übergebenen Daten die Zielschlüsselgröße überschreiten, werden die Daten abgeschnitten, und der Überschuss wird ignoriert.

Hinweis Es wird dringend empfohlen, dass Anwendungen die genaue Anzahl von Byte übergeben, die vom Zielschlüssel benötigt werden.

[in] cbSecret

Die Größe des pbSecret- Puffers in Byte.

[in] dwFlags

Eine Reihe von Flags, die das Verhalten dieser Funktion ändern. Derzeit sind keine Flags definiert, daher sollte dieser Parameter null 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.

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die Funktion war erfolgreich.
STATUS_BUFFER_TOO_SMALL	Die Größe des schlüsselobjekts, das vom cbKeyObject Parameter angegeben wird, ist nicht groß genug, um das Schlüsselobjekt aufzunehmen.
STATUS_INVALID_HANDLE	Der Algorithmushandle im hAlgorithm Parameter ist ungültig.
STATUS_INVALID_PARAMETER	Mindestens ein Parameter ist ungültig.

Bemerkungen

Je nachdem, welche Prozessormodi ein Anbieter unterstützt, können BCryptGenerateSymmetricKey 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 BCryptGenerateSymmetricKey--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. 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

BCryptDestroyKey

Freigeben über