Funzione NCryptEnumKeys (ncrypt.h)

Articolo
02/29/2024

La funzione NCryptEnumKeys ottiene i nomi delle chiavi archiviate dal provider.

Sintassi

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

Parametri

[in] hProvider

Handle del provider di archiviazione delle chiavi per cui enumerare le chiavi. Questo handle viene ottenuto con la funzione NCryptOpenStorageProvider .

[in, optional] pszScope

Questo parametro non è attualmente utilizzato e deve essere NULL.

[out] ppKeyName

Indirizzo di un puntatore a una struttura NCryptKeyName che riceve il nome della chiave recuperata. Al termine dell'uso della memoria, liberarla chiamando la funzione NCryptFreeBuffer .

[in, out] ppEnumState

Indirizzo di un puntatore VOID che riceve le informazioni sullo stato di enumerazione utilizzate nelle chiamate successive a questa funzione. Queste informazioni hanno significato solo per il provider di archiviazione delle chiavi e sono opache per il chiamante. Il provider di archiviazione chiavi usa queste informazioni per determinare l'elemento successivo nell'enumerazione . Se la variabile a cui punta questo parametro contiene NULL, l'enumerazione viene avviata dall'inizio.

Quando questa memoria non è più necessaria, deve essere liberata passando questo puntatore alla funzione NCryptFreeBuffer .

[in] dwFlags

Flag che modificano il comportamento della funzione. Può essere zero o una combinazione di uno o più dei valori seguenti.

Valore	Significato
NCRYPT_MACHINE_KEY_FLAG	Enumerare le chiavi per il computer locale. Se questo flag non è presente, le chiavi utente correnti vengono enumerate.
NCRYPT_SILENT_FLAG	Richiede che il provider di servizi chiave (KSP) non visualizzi alcuna interfaccia utente. Se il provider deve visualizzare l'interfaccia utente per il funzionamento, la chiamata ha esito negativo e il provider di servizi di configurazione deve impostare il codice di errore NTE_SILENT_CONTEXT come ultimo errore.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.

I codici restituiti possibili includono, a titolo esemplificativo, quanto segue.

Codice restituito	Descrizione
ERROR_SUCCESS	La funzione ha avuto esito positivo.
NTE_BAD_FLAGS	Il parametro dwFlags contiene un valore non valido.
NTE_INVALID_HANDLE	Il parametro hProvider non è valido.
NTE_INVALID_PARAMETER	Uno o più parametri non sono validi.
NTE_NO_MEMORY	Si è verificato un errore di allocazione della memoria.
NTE_NO_MORE_ITEMS	È stata raggiunta la fine dell'enumerazione.
NTE_SILENT_CONTEXT	Il parametro dwFlags contiene il flag NCRYPT_SILENT_FLAG , ma la chiave enumerata richiede l'interazione dell'utente.

Commenti

Questa funzione recupera un solo elemento ogni volta che viene chiamato. Lo stato dell'enumerazione viene archiviato nella variabile a cui punta il parametro ppEnumState , pertanto deve essere mantenuto tra le chiamate a questa funzione. Quando l'ultima chiave archiviata dal provider è stata recuperata, questa funzione restituirà NTE_NO_MORE_ITEMS la successiva chiamata. Per avviare l'enumerazione, impostare la variabile a cui punta il parametro ppEnumState su NULL, liberare la memoria a cui punta il parametro ppKeyName , se non è NULL e chiamare di nuovo questa funzione.

Un servizio non deve chiamare questa funzione dalla funzione StartService. Se un servizio chiama questa funzione dalla funzione StartService, può verificarsi un deadlock e il servizio potrebbe smettere di rispondere.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	ncrypt.h
Libreria	Ncrypt.lib
DLL	Ncrypt.dll