CryptDuplicateKey-Funktion (wincrypt.h)

Artikel
08/27/2023

Wichtig Diese API ist veraltet. Neue und vorhandene Software sollte mit der Verwendung von Kryptografie-APIs der nächsten Generation beginnen. Microsoft kann diese API in zukünftigen Versionen entfernen.

Die CryptDuplicateKey-Funktion macht eine exakte Kopie eines Schlüssels und des Zustands des Schlüssels.

Syntax

BOOL CryptDuplicateKey(
  [in]  HCRYPTKEY hKey,
  [in]  DWORD     *pdwReserved,
  [in]  DWORD     dwFlags,
  [out] HCRYPTKEY *phKey
);

Parameter

[in] hKey

Ein Handle für den Schlüssel, der dupliziert werden soll.

[in] pdwReserved

Für die zukünftige Verwendung reserviert und muss NULL sein.

[in] dwFlags

Für die zukünftige Verwendung reserviert und muss null sein.

[out] phKey

Adresse des Handles für den doppelten Schlüssel. Wenn Sie die Verwendung des Schlüssels abgeschlossen haben, lassen Sie das Handle los, indem Sie die CryptDestroyKey-Funktion aufrufen.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich null (TRUE).

Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (FALSE). Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Der von "NTE" vorangestellte Fehlercode wird von dem jeweiligen verwendeten CSP generiert. Einige mögliche Fehlercodes sind in der folgenden Tabelle aufgeführt.

Rückgabecode	Beschreibung
ERROR_CALL_NOT_IMPLEMENTED	Da es sich um eine neue Funktion handelt, implementieren vorhandene CSPs sie möglicherweise nicht. Dieser Fehler wird zurückgegeben, wenn der CSP diese Funktion nicht unterstützt.
ERROR_INVALID_PARAMETER	Einer der Parameter enthält einen ungültigen Wert. Dies ist in den meisten Fällen ein ungültiger Zeiger.
NTE_BAD_KEY	Ein Handle für den ursprünglichen Schlüssel ist ungültig.

Hinweise

CryptDuplicateKey macht eine Kopie eines Schlüssels und des genauen Zustands des Schlüssels. Ein Szenario, in dem diese Funktion verwendet werden kann, ist, wenn eine Anwendung zwei separate Nachrichten mit demselben Schlüssel, aber mit unterschiedlichen Salt-Werten verschlüsseln muss. Der ursprüngliche Schlüssel wird generiert, und dann wird mit der CryptDuplicateKey-Funktion ein doppelter Schlüssel erstellt. Die verschiedenen Salt-Werte werden dann für den ursprünglichen und doppelten Schlüssel mit separaten Aufrufen der CryptSetKeyParam-Funktion festgelegt.

CryptDestroyKey muss aufgerufen werden, um alle Schlüssel zu zerstören, die mit CryptDuplicateKey erstellt werden. Das Zerstören des ursprünglichen Schlüssels führt nicht dazu, dass der doppelte Schlüssel zerstört wird. Nachdem ein doppelter Schlüssel erstellt wurde, wird er vom ursprünglichen Schlüssel getrennt. Es gibt keinen gemeinsamen Zustand zwischen den beiden Schlüsseln.

Beispiele

Das folgende Beispiel zeigt die Erstellung eines Sitzungsschlüssels, der ein Duplikat eines vorhandenen Sitzungsschlüssels ist. Ein Beispiel, das den vollständigen Kontext für dieses Beispiel enthält, finden Sie unter Beispiel-C-Programm: Duplizieren eines Sitzungsschlüssels.

//--------------------------------------------------------------------
// Declare and initialize variables.

HCRYPTKEY    hDuplicateKey;

// Duplicate the key. hOriginalKey is a previously 
// assigned HCRYPTKEY variable.

if (CryptDuplicateKey(
     hOriginalKey, 
     NULL, 
     0, 
     &hDuplicateKey))
{
   printf("The session key has been duplicated. \n");
}
else
{
   printf("Error using CryptDuplicateKey.\n");
   exit(1);
}

// Insert code that uses the duplicate key here.

// When you have finished using the key, the handle must be released.

if (CryptDestroyKey(hDuplicateKey))
{
  printf("The handle has been released.\n");
}
else
{
  printf("The handle could not be released.\n");
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wincrypt.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll

Weitere Informationen

CryptDestroyKey

CryptSetKeyParam

Schlüsselgenerierung und Exchange-Funktionen

Freigeben über