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 |