CryptDuplicateKey-Funktion (wincrypt.h)
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 |
|---|---|
|
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. |
|
Einer der Parameter enthält einen ungültigen Wert. Dies ist in den meisten Fällen ein ungültiger Zeiger. |
|
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 |