NCryptOpenKey-Funktion (ncrypt.h)

  • Artikel

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