BCryptGenerateSymmetricKey-Funktion (bcrypt.h)

Die BCryptGenerateSymmetricKey-Funktion erstellt ein Schlüsselobjekt zur Verwendung mit einem symmetrischen Schlüsselverschlüsselungsalgorithmus aus einem angegebenen 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 Funktion BCryptOpenAlgorithmProvider erstellt wurde. Der algorithmus, der bei der Erstellung 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. Dieses Handle muss freigegeben 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 angegeben.

Dieser Arbeitsspeicher kann erst freigegeben werden, nachdem das phKey-Schlüsselhandle zerstört wurde.

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

[in] cbKeyObject

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

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

Zeiger 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 anderer reproduzierbarer 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 Bytes übergeben, die für den Zielschlüssel erforderlich sind.

 

[in] cbSecret

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

[in] dwFlags

Eine Reihe von Flags, die das Verhalten dieser Funktion ändern. Derzeit sind keine Flags definiert, daher sollte dieser Parameter 0 sein.

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 cbKeyObject-Parameter angegebenen Schlüsselobjekts ist nicht groß genug, um das Schlüsselobjekt aufzunehmen.
STATUS_INVALID_HANDLE	Das Algorithmushandle im Parameter hAlgorithm ist ungültig.
STATUS_INVALID_PARAMETER	Mindestens ein Parameter ist ungültig.

Hinweise

Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptGenerateSymmetricKey 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 flags BCRYPT_PROV_DISPATCH geöffnet worden sein, und alle zeiger, die an die BCryptGenerateSymmetricKey-Funktion übergeben werden, müssen auf nicht auspageten (oder gesperrten) Arbeitsspeicher verweisen.

Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Cng.lib, die Teil des Driver Development Kit (DDK) ist. 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

BCryptDestroyKey