NCryptOpenKey-Funktion (ncrypt.h)

Artikel
08/25/2023

Die NCryptOpenKey-Funktion öffnet einen Schlüssel, der im angegebenen CNG-Schlüsselspeicheranbieter vorhanden ist.

Syntax

SECURITY_STATUS NCryptOpenKey(
  [in]  NCRYPT_PROV_HANDLE hProvider,
  [out] NCRYPT_KEY_HANDLE  *phKey,
  [in]  LPCWSTR            pszKeyName,
  [in]  DWORD              dwLegacyKeySpec,
  [in]  DWORD              dwFlags
);

Parameter

[in] hProvider

Das Handle des Schlüsselspeicheranbieters, aus dem der Schlüssel geöffnet werden soll.

[out] phKey

Ein Zeiger auf eine NCRYPT_KEY_HANDLE Variable, die das Schlüsselhandle empfängt. Wenn Sie mit der Verwendung dieses Handle fertig sind, geben Sie es frei, indem Sie es an die NCryptFreeObject-Funktion übergeben.

[in] pszKeyName

Ein Zeiger auf eine Unicode-Zeichenfolge mit NULL-Beendigung, die den Namen des abzurufenden Schlüssels enthält.

[in] dwLegacyKeySpec

Ein Legacybezeichner, der den Schlüsseltyp angibt. Dies kann einer der folgenden Werte sein.

Wert	Bedeutung
AT_KEYEXCHANGE	Der Schlüssel ist ein Schlüsselaustauschschlüssel.
AT_SIGNATURE	Der Schlüssel ist ein Signaturschlüssel.
0	Der Schlüssel ist keiner der oben genannten Typen.

[in] dwFlags

Flags, die das Funktionsverhalten ändern. Dies kann null oder eine Kombination aus einem oder mehreren der folgenden Werte sein.

Wert	Bedeutung
NCRYPT_MACHINE_KEY_FLAG	Öffnen Sie den Schlüssel für den lokalen Computer. Wenn dieses Flag nicht vorhanden ist, wird der aktuelle Benutzerschlüssel geöffnet.
NCRYPT_SILENT_FLAG	Fordert an, dass der Schlüsseldienstanbieter (Key Service Provider, KSP) keine Benutzeroberfläche anzeigt. Wenn der Anbieter die Benutzeroberfläche anzeigen muss, um zu funktionieren, schlägt der Aufruf fehl, und der KSP sollte den NTE_SILENT_CONTEXT Fehlercode als letzten Fehler festlegen.

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
ERROR_SUCCESS	Die Funktion war erfolgreich.
NTE_BAD_FLAGS	Der dwFlags-Parameter enthält einen wert, der ungültig ist.
NTE_BAD_KEYSET	Der angegebene Schlüssel wurde nicht gefunden.
NTE_INVALID_HANDLE	Der hProvider-Parameter ist ungültig.
NTE_INVALID_PARAMETER	Mindestens ein Parameter ist ungültig.
NTE_NO_MEMORY	Ein Fehler bei der Speicherzuordnung ist aufgetreten.

Hinweise

Ein Dienst darf diese Funktion nicht über seine StartService-Funktion aufrufen. Wenn ein Dienst diese Funktion über seine StartService-Funktion aufruft, kann ein Deadlock auftreten, und der Dienst reagiert möglicherweise nicht mehr.

Aus Leistungsgründen zwischenspeichern softwarebasierte Microsoft-KSPs private Schlüsselmaterial in der lokalen Sicherheitsbehörde (Local Security Authority, LSA), solange ein Handle für den Schlüssel geöffnet ist. Der LSA ist ein privilegierter Systemprozess. Daher können andere Benutzer nicht auf diese zwischengespeicherte Kopie des Schlüssels zugreifen, es sei denn, der Benutzer verfügt über Administratorrechte auf dem System. Dieses Verhalten kann nicht durch die Konfiguration geändert werden.

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	ncrypt.h
Bibliothek	Ncrypt.lib
DLL	Ncrypt.dll

Freigeben über