Funzione NCryptCreatePersistedKey (ncrypt.h)

La funzione NCryptCreatePersistedKey crea una nuova chiave e la archivia nel provider di archiviazione chiavi specificato. Dopo aver creato una chiave usando questa funzione, è possibile usare la funzione NCryptSetProperty per impostarne le proprietà; Tuttavia, la chiave non può essere usata finché non viene chiamata la funzione NCryptFinalizeKey .

Sintassi

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

Parametri

[in] hProvider

Handle del provider di archiviazione delle chiavi in cui creare la chiave. Questo handle viene ottenuto usando la funzione NCryptOpenStorageProvider .

[out] phKey

Indirizzo di una variabile NCRYPT_KEY_HANDLE che riceve l'handle della chiave. Al termine dell'uso di questo handle, rilasciarlo passandolo alla funzione NCryptFreeObject . Per eliminare il file di chiave su disco, passare l'handle alla funzione NCryptDeleteKey . Verrà rilasciato anche l'handle. Le applicazioni possono quindi passare l'handle a NCryptFreeObject o NCryptDeleteKey, ma non a entrambe.

[in] pszAlgId

Puntatore a una stringa Unicode con terminazione Null contenente l'identificatore dell'algoritmo di crittografia per creare la chiave. Può trattarsi di uno degli identificatori di algoritmo CNG standard o dell'identificatore per un altro algoritmo registrato.

[in, optional] pszKeyName

Puntatore a una stringa Unicode con terminazione Null contenente il nome della chiave. Se questo parametro è NULL, questa funzione creerà una chiave temporanea che non è persistente.

[in] dwLegacyKeySpec

Identificatore legacy che specifica il tipo di chiave. I valori possibili sono i 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

Set di flag che modificano il comportamento di questa funzione. Può essere zero o una combinazione di uno o più dei valori seguenti:

Valore	Significato
NCRYPT_MACHINE_KEY_FLAG	La chiave si applica al computer locale. Se questo flag non è presente, la chiave viene applicata all'utente corrente.
NCRYPT_OVERWRITE_KEY_FLAG	Se nel contenitore esiste già una chiave con il nome specificato, la chiave esistente verrà sovrascritta. Se questo flag non viene specificato e esiste già una chiave con il nome specificato, questa funzione restituirà NTE_EXISTS.
NCRYPT_REQUIRE_VBS_FLAG	Indica che una chiave deve essere protetta con la sicurezza basata su virtualizzazione . Per impostazione predefinita, viene creata una chiave salvata in modo permanente tra avvio su disco che persiste tra i cicli di riavvio. L'operazione avrà esito negativo se la sicurezza basata su vbs non è disponibile. (*Vedere le osservazioni)
NCRYPT_PREFER_VBS_FLAG	Indica che una chiave deve essere protetta con la sicurezza basata su virtualizzazione . Per impostazione predefinita, viene creata una chiave salvata in modo permanente tra avvio su disco che persiste tra i cicli di riavvio L'operazione genererà una chiave isolata dal software se vbs non è disponibile. (*Vedere le osservazioni)
NCRYPT_USE_PER_BOOT_KEY_FLAG	Flag aggiuntivo che può essere usato insieme a NCRYPT_REQUIRE_VBS_FLAG o NCRYPT_PREFER_VBS_FLAG. Indica alla sicurezza basata su virtualizzazione (VBS) di proteggere la chiave client con una chiave di avvio archiviata su disco, ma non può essere riutilizzata tra i cicli di avvio. (*Vedere le osservazioni)

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_EXISTS	Esiste già una chiave con il nome specificato e il NCRYPT_OVERWRITE_KEY_FLAG non è stato specificato.
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_VBS_UNAVAILABLE	La sicurezza basata su vbs non è disponibile.

Commenti

Importante

Le informazioni sui flag VBS si riferiscono al prodotto in versione non definitiva che può essere modificato in modo sostanziale prima del rilascio commerciale. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Se si crea una coppia di chiavi RSA, è anche possibile archiviare la chiave nell'archiviazione legacy in modo che possa essere usata con CryptoAPI passando il flag NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG alla funzione NCryptFinalizeKey al termine della chiave.

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 hardware aggiuntivi per le chiavi VBS

Anche se nel computer potrebbe essere installato il sistema operativo appropriato, per generare e proteggere le chiavi è necessario soddisfare i requisiti hardware aggiuntivi seguenti.

• Virtualizzazione abilitata (vedere Sicurezza basata su virtualizzazione ))
• TPM abilitato
  • Per gli ambienti bare metal, è necessario TPM 2.0.
  • Per gli ambienti vm, vTPM (Virtual TPM) è supportato.
• Il BIOS deve essere aggiornato a UEFI con il profilo SecureBoot

Per altre informazioni sui requisiti hardware:

• VBS prevede diversi requisiti hardware da eseguire, tra cui Hyper-V (hypervisor Windows), architettura a 64 bit e supporto di IOMMU. L'elenco completo dei requisiti hardware vbs è disponibile qui.
• I requisiti per un dispositivo altamente sicuro sono disponibili qui.

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

Vedi anche

NCryptDeleteKey

NCryptFinalizeKey