BCryptGenerateKeyPair-Funktion (bcrypt.h)

Die Funktion BCryptGenerateKeyPair erstellt ein leeres Paar für öffentliche/private Schlüssel. Nachdem Sie mit dieser Funktion einen Schlüssel erstellt haben, können Sie die BCryptSetProperty-Funktion verwenden, um die zugehörigen Eigenschaften festzulegen. Der Schlüssel kann jedoch erst verwendet werden, wenn die Funktion BCryptFinalizeKeyPair 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 Signatur, asymmetrische Verschlüsselung oder Schlüsselvereinbarung unterstützt. Dieses Handle muss mit 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. Dieses Handle muss freigegeben werden, wenn es nicht mehr benötigt wird, indem es an die Funktion BCryptDestroyKey übergeben wird.

[in] dwLength

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

Algorithmusbezeichner	Bedeutung
BCRYPT_DH_ALGORITHM	Die Schlüsselgröße muss größer oder gleich 512 Bit, kleiner oder gleich 4096 Bits und ein Vielfaches von 64 Sein.
BCRYPT_DSA_ALGORITHM	Vor Windows 8 muss die Schlüsselgröße größer oder gleich 512 Bit, kleiner oder gleich 1024 Bits und ein Vielfaches von 64 Bit sein. Ab Windows 8 muss die Schlüsselgröße größer oder gleich 512 Bit, kleiner oder gleich 3072 Bit und ein Vielfaches von 64 Bit sein. Die Verarbeitung von Schlüsselgrößen kleiner oder gleich 1024 Bits 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 Bits sein.
BCRYPT_ECDH_P384_ALGORITHM	Die Schlüsselgröße muss 384 Bits sein.
BCRYPT_ECDH_P521_ALGORITHM	Die Schlüsselgröße muss 521 Bits sein.
BCRYPT_ECDSA_P256_ALGORITHM	Die Schlüsselgröße muss 256 Bits sein.
BCRYPT_ECDSA_P384_ALGORITHM	Die Schlüsselgröße muss 384 Bits sein.
BCRYPT_ECDSA_P521_ALGORITHM	Die Schlüsselgröße muss 521 Bits sein.
BCRYPT_RSA_ALGORITHM	Die Schlüsselgröße muss größer oder gleich 512 Bit, kleiner oder gleich 16384 Bit und ein Vielfaches von 64 Bit sein.

[in] dwFlags

Ein Satz von Flags, die das Verhalten dieser Funktion ändern. Es sind derzeit keine Flags definiert, sodass dieser Parameter 0 (null) sein sollte.

Rückgabewert

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

Mögliche Rückgabecodes sind u. a. die folgenden:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die Funktion war erfolgreich.
STATUS_INVALID_HANDLE	Das 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.

Hinweise

Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptGenerateKeyPair entweder aus dem Benutzermodus oder dem Kernelmodus aufgerufen werden. Aufrufer im Kernelmodus können entweder am PASSIVE_LEVELIRQL oder DISPATCH_LEVEL IRQL ausgeführt werden. Wenn die aktuelle IRQL-Ebene DISPATCH_LEVEL ist, muss das im hAlgorithm-Parameter bereitgestellte Handle mit dem flag BCRYPT_PROV_DISPATCH geöffnet worden sein, und alle an die BCryptGenerateKeyPair-Funktion übergebenen Zeiger müssen auf nicht ausgestellten (oder gesperrten) Speicher 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: Verwenden Sie Ksecdd.lib, um diese Funktion im Kernelmodus aufzurufen.

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