Funzione NCryptOpenKey (ncrypt.h)

Articolo
02/29/2024

La funzione NCryptOpenKey apre una chiave presente nel provider di archiviazione chiavi CNG specificato.

Sintassi

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

Parametri

[in] hProvider

Handle del provider di archiviazione delle chiavi da cui aprire la chiave.

[out] phKey

Puntatore a una variabile NCRYPT_KEY_HANDLE che riceve l'handle della chiave. Al termine dell'uso di questo handle, rilasciarlo passandolo alla funzione NCryptFreeObject .

[in] pszKeyName

Puntatore a una stringa Unicode con terminazione Null contenente il nome della chiave da recuperare.

[in] dwLegacyKeySpec

Identificatore legacy che specifica il tipo di chiave. Può trattarsi di uno dei valori seguenti.

Valore	Significato
AT_KEYEXCHANGE	La chiave è una chiave di scambio di chiavi.
AT_SIGNATURE	La chiave è una chiave di firma.
0	La chiave non è uno dei tipi precedenti.

[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	Aprire la chiave per il computer locale. Se questo flag non è presente, viene aperta la chiave utente corrente.
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_BAD_KEYSET	La chiave specificata non è stata trovata.
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.

Commenti

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.

Per motivi di prestazioni, i KSP basati su software Microsoft memorizzano nella cache il materiale della chiave privata nell'Autorità di sicurezza locale (LSA) purché sia aperto un handle per la chiave. LSA è un processo di sistema con privilegi. Pertanto, altri utenti non possono accedere a questa copia memorizzata nella cache della chiave, a meno che l'utente non abbia privilegi di amministratore nel sistema. Questo comportamento non può essere modificato tramite la configurazione.

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