BCryptGenerateKeyPair-Funktion (bcrypt.h)

Artikel
07/16/2024

Die BCryptGenerateKeyPair-Funktion erstellt ein leeres öffentliches/privates Schlüsselpaar. Nachdem Sie mithilfe dieser Funktion einen Schlüssel erstellt haben, können Sie die BCryptSetProperty--Funktion verwenden, um dessen Eigenschaften festzulegen; Der Schlüssel kann jedoch erst verwendet werden, wenn die BCryptFinalizeKeyPair Funktion aufgerufen wird.

Syntax

NTSTATUS BCryptGenerateKeyPair(
  [in, out] BCRYPT_ALG_HANDLE hAlgorithm,
  [out]     BCRYPT_KEY_HANDLE *phKey,
  [in]      ULONG             dwLength,
  [in]      ULONG             dwFlags
);

Parameter

[in, out] hAlgorithm

Handle eines Algorithmusanbieters, der signieren, asymmetrische Verschlüsselung oder Schlüsselvereinbarung unterstützt. Dieses Handle muss mithilfe der funktion BCryptOpenAlgorithmProvider erstellt worden sein.

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

[in] dwLength

Die Länge des Schlüssels in Bits. Algorithmusanbieter haben unterschiedliche Größenbeschränkungen für jeden asymmetrischen Standardalgorithmus.

Algorithmusbezeichner	Bedeutung
BCRYPT_DH_ALGORITHM	Die Schlüsselgröße muss größer oder gleich 512 Bit sein, kleiner oder gleich 4096 Bit und muss ein Vielfaches von 64 sein.
BCRYPT_DSA_ALGORITHM	Vor Windows 8 muss die Schlüsselgröße größer oder gleich 512 Bit sein, kleiner oder gleich 1024 Bit und muss ein Vielfaches von 64 sein. Ab Windows 8 muss die Schlüsselgröße größer oder gleich 512 Bit sein, kleiner oder gleich 3072 Bit und muss ein Vielfaches von 64 sein. Die Verarbeitung für Schlüsselgrößen kleiner oder gleich 1024 Bit entspricht FIPS 186-2. Die Verarbeitung für Schlüsselgrößen größer als 1024 und kleiner oder gleich 3072 entspricht FIPS 186-3.
BCRYPT_ECDH_P256_ALGORITHM	Die Schlüsselgröße muss 256 Bit groß sein.
BCRYPT_ECDH_P384_ALGORITHM	Die Schlüsselgröße muss 384 Bit sein.
BCRYPT_ECDH_P521_ALGORITHM	Die Schlüsselgröße muss 521 Bit sein.
BCRYPT_ECDSA_P256_ALGORITHM	Die Schlüsselgröße muss 256 Bit groß sein.
BCRYPT_ECDSA_P384_ALGORITHM	Die Schlüsselgröße muss 384 Bit sein.
BCRYPT_ECDSA_P521_ALGORITHM	Die Schlüsselgröße muss 521 Bit sein.
BCRYPT_RSA_ALGORITHM	Die Schlüsselgröße muss größer oder gleich 512 Bit sein, kleiner oder gleich 16384 Bit und muss ein Vielfaches von 64 sein.

[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_INVALID_HANDLE	Der Algorithmushandle im hAlgorithm Parameter ist ungültig.
STATUS_INVALID_PARAMETER	Mindestens ein Parameter ist ungültig.
STATUS_NOT_SUPPORTED	Der angegebene Anbieter unterstützt keine asymmetrische Schlüsselverschlüsselung.

Bemerkungen

Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptGenerateKeyPair 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 im hAlgorithm Parameter bereitgestellte Handle mithilfe des BCRYPT_PROV_DISPATCH-Flags geöffnet worden sein, und alle Zeiger, die an die BCryptGenerateKeyPair--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