Funzione NCryptCreatePersistedKey (ncrypt.h)

  • Articolo

La funzione NCryptCreatePersistedKey crea una nuova chiave e la archivia nel provider di archiviazione delle chiavi specificato. Dopo aver creato una chiave usando questa funzione, è possibile usare la funzione NCryptSetProperty per impostare le relative 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 sul disco, passare l'handle alla funzione NCryptDeleteKey . In questo modo verrà rilasciato anche l'handle. Le applicazioni possono quindi passare l'handle a NCryptFreeObject o NCryptDeleteKey, ma non entrambi.

[in] pszAlgId

Puntatore a una stringa Unicode con terminazione null contenente l'identificatore dell'algoritmo di crittografia per creare la chiave. Questo può essere uno degli identificatori di algoritmo CNG standard o l'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 temporaneo 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 delle chiavi.
AT_SIGNATURE La chiave è una chiave di firma.
0 La chiave non è nessuno dei tipi precedenti.

[in] dwFlags

Set di flag che modificano il comportamento di questa funzione. Questo 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 si applica all'utente corrente.
NCRYPT_OVERWRITE_KEY_FLAG Se una chiave esiste già nel contenitore con il nome specificato, la chiave esistente verrà sovrascritta. Se questo flag non è specificato e una chiave con il nome specificato esiste già, questa funzione restituirà NTE_EXISTS.
NCRYPT_REQUIRE_VBS_FLAG Indica che una chiave deve essere protetta con la sicurezza basata su virtualizzazione (VBS).

L'operazione avrà esito negativo se VBS non è disponibile. (*Vedere osservazioni)
NCRYPT_PREFER_VBS_FLAG Indica che una chiave deve essere protetta con la sicurezza basata su virtualizzazione (VBS).

L'operazione genererà una chiave isolata dal software se VBS non è disponibile. (*Vedere osservazioni)

Valore restituito

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

I possibili codici restituiti includono, ma non sono limitati a, i seguenti:

Codice restituito Descrizione
ERROR_SUCCESS La funzione ha avuto esito positivo.
NTE_BAD_FLAGS Il parametro dwFlags contiene un valore non valido.
NTE_EXISTS Una chiave con il nome specificato esiste già e la NCRYPT_OVERWRITE_KEY_FLAG non è stata specificata.
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 VBS non è disponibile.

Commenti

Importante

Le informazioni relative ai flag VBS si riferiscono al prodotto di versione preliminare che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

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

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 interrompere la risposta.

Requisiti hardware aggiuntivi per le chiavi VBS

Sebbene nel computer sia installato il sistema operativo appropriato, è necessario soddisfare i seguenti requisiti hardware aggiuntivi per l'uso di VBS per generare e proteggere le chiavi.

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

Per altre informazioni sui requisiti hardware:

  • VBS ha diversi requisiti hardware da eseguire, tra cui il supporto di Hyper-V (Hypervisor Windows), l'architettura a 64 bit e il 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