CryptDestroyKey-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 CryptDestroyKey-Funktion gibt das Handle frei, auf das vom hKey-Parameter verwiesen wird. Nachdem ein Schlüsselhandle freigegeben wurde, ist es nicht mehr gültig und kann nicht mehr verwendet werden.

Wenn sich das Handle auf einen Sitzungsschlüssel oder einen öffentlichen Schlüssel bezieht, der über CryptImportKey in den Kryptografiedienstanbieter (CSP) importiert wurde, zerstört diese Funktion den Schlüssel und gibt den vom Schlüssel verwendeten Arbeitsspeicher frei. Viele CSPs überschreiben den Speicher, in dem der Schlüssel gespeichert wurde, bevor er freigegeben wurde. Das zugrunde liegende öffentliche/private Schlüsselpaar wird jedoch nicht durch diese Funktion zerstört. Nur das Handle wird zerstört.

Syntax

BOOL CryptDestroyKey(
  [in] HCRYPTKEY hKey
);

Parameter

[in] hKey

Das Handle des zu zerstörenden Schlüssels.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Die von "NTE" vorangestellten Fehlercodes werden von dem jeweiligen verwendeten CSP generiert. Einige mögliche Fehlercodes sind in der folgenden Tabelle aufgeführt.

Rückgabecode	Beschreibung
ERROR_BUSY	Das von hKey angegebene Schlüsselobjekt wird derzeit verwendet und kann nicht zerstört werden.
ERROR_INVALID_HANDLE	Der Parameter hKey gibt ein ungültiges Handle an.
ERROR_INVALID_PARAMETER	Der hKey-Parameter enthält einen ungültigen Wert.
NTE_BAD_KEY	Der hKey-Parameter enthält kein gültiges Handle für einen Schlüssel.
NTE_BAD_UID	Der CSP-Kontext, der beim Erstellen des Schlüssels angegeben wurde, kann nicht gefunden werden.

Hinweise

Schlüssel belegen sowohl den Speicherplatz des Betriebssystems als auch den Speicherplatz des CSP. Einige CSPs werden in Hardware mit eingeschränkten Arbeitsspeicherressourcen implementiert. Anwendungen müssen alle Schlüssel mit der CryptDestroyKey-Funktion zerstören, wenn sie mit ihnen fertig sind.

Alle Schlüsselhandles, die mit einem bestimmten CSP erstellt oder importiert wurden, müssen zerstört werden, bevor dieses CSP-Handle mit der CryptReleaseContext-Funktion freigegeben wird.

Beispiele

Ein Beispiel, das die CryptDestroyKey-Funktion verwendet, finden Sie unter Beispiel-C-Programm: Erstellen und Hashen eines Sitzungsschlüssels.

Anforderungen


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