BCryptDuplicateKey-Funktion (bcrypt.h)

  • Artikel

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. Dieses Handle muss freigegeben 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 Objekt des doppelten Schlüssels 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 PhNewKey-Schlüsselhandle zerstört wurde.

[in] cbKeyObject

Die Größe des pbKeyObject-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 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.

Hinweise

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