BCryptDuplicateKey-Funktion (bcrypt.h)

Artikel
07/16/2024

Die BCryptDuplicateKey--Funktion erstellt ein Duplikat eines symmetrischen Schlüssels.

Syntax

NTSTATUS BCryptDuplicateKey(
  [in]  BCRYPT_KEY_HANDLE hKey,
  [out] BCRYPT_KEY_HANDLE *phNewKey,
  [out] PUCHAR            pbKeyObject,
  [in]  ULONG             cbKeyObject,
  [in]  ULONG             dwFlags
);

Parameter

[in] hKey

Das Handle des zu duplizierenden Schlüssels. Dies muss ein Handle für einen symmetrischen Schlüssel sein.

[out] phNewKey

Ein Zeiger auf eine BCRYPT_KEY_HANDLE Variable, die das Handle des doppelten 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] pbKeyObject

Ein Zeiger auf einen Puffer, der das doppelte 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 phNewKey Tastenhandle zerstört wurde.

[in] cbKeyObject

Die Größe des pbKeyObject- 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	Das Schlüsselhandle im hKey--Parameter ist ungültig. Dieser Wert wird auch zurückgegeben, wenn der zu duplizierende Schlüssel kein symmetrischer Schlüssel ist.
STATUS_INVALID_PARAMETER	Mindestens ein Parameter ist ungültig.

Bemerkungen

Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptDuplicateKey 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 hKey Parameter bereitgestellte Handle von einem Algorithmushandle abgeleitet werden, das von einem Anbieter zurückgegeben wird, der mit dem BCRYPT_PROV_DISPATCH Flag geöffnet wurde, und alle Zeiger, die an den BCryptDuplicateKey-Funktion übergeben wurden, 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

Freigeben über