NCryptEnumKeys-Funktion (ncrypt.h)

Artikel
03/04/2024

Die NCryptEnumKeys-Funktion ruft die Namen der Schlüssel ab, die vom Anbieter gespeichert werden.

Syntax

SECURITY_STATUS NCryptEnumKeys(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [in, optional] LPCWSTR            pszScope,
  [out]          NCryptKeyName      **ppKeyName,
  [in, out]      PVOID              *ppEnumState,
  [in]           DWORD              dwFlags
);

Parameter

[in] hProvider

Das Handle des Schlüsselspeicheranbieters, für den die Schlüssel aufgelistet werden sollen. Dieses Handle wird mit der Funktion NCryptOpenStorageProvider abgerufen.

[in, optional] pszScope

Dieser Parameter wird derzeit nicht verwendet und muss NULL sein.

[out] ppKeyName

Die Adresse eines Zeigers auf eine NCryptKeyName-Struktur , die den Namen des abgerufenen Schlüssels empfängt. Wenn die Anwendung diesen Arbeitsspeicher verwendet hat, geben Sie ihn frei, indem Sie die NCryptFreeBuffer-Funktion aufrufen.

[in, out] ppEnumState

Die Adresse eines VOID-Zeigers , der Enumerationsstatusinformationen empfängt, die in nachfolgenden Aufrufen dieser Funktion verwendet werden. Diese Informationen haben nur eine Bedeutung für den Schlüsselspeicheranbieter und sind für den Aufrufer undurchsichtig. Der Schlüsselspeicheranbieter verwendet diese Informationen, um zu bestimmen, welches Element als Nächstes in der Enumeration angezeigt wird. Wenn die Variable, auf die dieser Parameter verweist, NULL enthält, wird die Enumeration von Anfang an gestartet.

Wenn dieser Speicher nicht mehr benötigt wird, muss er durch Übergeben dieses Zeigers an die NCryptFreeBuffer-Funktion freigegeben werden.

[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	Listet die Schlüssel für den lokalen Computer auf. Wenn dieses Flag nicht vorhanden ist, werden die aktuellen Benutzerschlüssel aufgelistet.
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_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.
NTE_NO_MORE_ITEMS	Das Ende der Enumeration wurde erreicht.
NTE_SILENT_CONTEXT	Der dwFlags-Parameter enthält das NCRYPT_SILENT_FLAG-Flag , aber der aufgezählte Schlüssel erfordert eine Benutzerinteraktion.

Hinweise

Diese Funktion ruft bei jedem Aufruf nur ein Element ab. Der Zustand der Enumeration wird in der Variablen gespeichert, auf die der ppEnumState-Parameter verweist. Dies muss also zwischen Aufrufen dieser Funktion beibehalten werden. Wenn der letzte vom Anbieter gespeicherte Schlüssel abgerufen wurde, gibt diese Funktion beim nächsten Aufruf NTE_NO_MORE_ITEMS zurück. Um die Enumeration über zu starten, legen Sie die Variable, auf die der ppEnumState-Parameter verweist, auf NULL fest, geben Sie den Speicher frei, auf den der ppKeyName-Parameter verweist, wenn er nicht NULL ist, und rufen Sie diese Funktion erneut auf.

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.

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