Condividi tramite

Funzione NCryptImportKey (ncrypt.h)

  • Articolo

La funzione NCryptImportKey importa una chiave Cryptography API: Next Generation (CNG) da un BLOB di memoria.

Sintassi

SECURITY_STATUS NCryptImportKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [in, optional] NCRYPT_KEY_HANDLE  hImportKey,
  [in]           LPCWSTR            pszBlobType,
  [in, optional] NCryptBufferDesc   *pParameterList,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           PBYTE              pbData,
  [in]           DWORD              cbData,
  [in]           DWORD              dwFlags
);

Parametri

[in] hProvider

Handle del provider di archiviazione delle chiavi.

[in, optional] hImportKey

Handle della chiave crittografica con cui sono stati crittografati i dati della chiave all'interno del BLOB della chiave importata. Deve trattarsi di un handle per la stessa chiave passata nel parametro hExportKey della funzione NCryptExportKey . Se questo parametro è NULL, si presuppone che il BLOB della chiave non sia crittografato.

[in] pszBlobType

Stringa Unicode con terminazione Null che contiene un identificatore che specifica il formato del BLOB della chiave. Questi formati sono specifici di un determinato provider di archiviazione delle chiavi. Per i formati BLOB supportati dai provider Microsoft, vedere Osservazioni.

[in, optional] pParameterList

Indirizzo di una struttura NCryptBufferDesc che punta a una matrice di buffer che contengono informazioni sui parametri per la chiave.

[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 .

[in] pbData

Indirizzo di un buffer che contiene il BLOB della chiave da importare. Il parametro cbData contiene le dimensioni di questo buffer.

[in] cbData

Dimensione, in byte, del buffer pbData .

[in] dwFlags

Flag che modificano il comportamento della funzione. Può essere zero o una combinazione di uno o più dei valori seguenti. Il set di flag validi è specifico per ogni provider di archiviazione delle chiavi.

Valore Significato
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.
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.
NTE_VBS_CANNOT_DECRYPT_KEY Operazione di decrittografia non riuscita della sicurezza basata su vbs.

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.

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.

Le sezioni seguenti descrivono i comportamenti specifici per i provider di archiviazione chiavi Microsoft:

  • Provider di servizi di configurazione software Microsoft
  • Microsoft Smart Card KSP

Provider di servizi di configurazione software Microsoft

Le costanti seguenti sono supportate dal KSP del software Microsoft per il parametro pszBlobType .

Se non viene specificato un nome di chiave, microsoft Software KSP considera la chiave temporanea e non la archivia in modo permanente. Per il tipo di NCRYPT_OPAQUETRANSPORT_BLOB , il nome della chiave viene archiviato all'interno del BLOB quando viene esportato. Per altri formati BLOB, è possibile specificare il nome in un parametro buffer NCRYPTBUFFER_PKCS_KEY_NAME all'interno del parametro pParameterList .

In Windows Server 2008 e Windows Vista, solo le chiavi importate come BLOB busta PKCS #7 (NCRYPT_PKCS7_ENVELOPE_BLOB) o BLOB a chiave privata PKCS #8 (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) possono essere mantenute usando il metodo precedente. Per rendere persistenti le chiavi importate tramite altri tipi DI BLOB in queste piattaforme, usare il metodo documentato in Importazione ed esportazione chiavi.

I flag seguenti sono supportati da questo provider di servizi di configurazione.

Termine Descrizione
NCRYPT_NO_KEY_VALIDATION Non convalidare la parte pubblica della coppia di chiavi. Questo flag si applica solo alle coppie di chiavi pubbliche/private.
NCRYPT_DO_NOT_FINALIZE_FLAG Non finalizzare la chiave. Questa opzione è utile quando è necessario aggiungere o modificare le proprietà della chiave dopo l'importazione. È necessario finalizzare la chiave prima che possa essere usata passando l'handle di chiave alla funzione NCryptFinalizeKey . Questo flag è supportato per le chiavi private PKCS #7 e PKCS #8, ma non per le chiavi pubbliche.
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_WRITE_KEY_TO_LEGACY_STORE_FLAG Salvare anche la chiave nell'archiviazione legacy. In questo modo la chiave può essere usata con CryptoAPI. Questo flag si applica solo alle chiavi RSA.

Microsoft Smart Card KSP

Il set di formati e flag BLOB chiave supportati da questo KSP è identico al set supportato da Microsoft Software KSP.

In Windows Server 2008 e Windows Vista, Microsoft Smart Card KSP importa tutte le chiavi nel KSP Software Microsoft. Pertanto, le chiavi non possono essere mantenute in una smart card usando questa API e le indicazioni nella sezione precedente si applicano quando si tenta di rendere persistenti le chiavi all'interno di Microsoft Software KSP.

In Windows Server 2008 R2 e Windows 7, il provider di archiviazione chiavi smart card Microsoft può importare una chiave privata in una smart card, purché siano soddisfatte le condizioni seguenti:

  • Il nome del contenitore chiave nella scheda è valido.
  • L'importazione di chiavi private è supportata dalla smart card.
  • Le due chiavi del Registro di sistema seguenti sono impostate su un DWORD di 0x1:
    • HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateExchangeKeyImport
    • HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateSignatureKeyImport

Se il nome del contenitore chiave è NULL, Microsoft Smart Card KSP considera la chiave come effimero e la importa nel KSP Software Microsoft.

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

NCryptBuffer

NCryptCreatePersistedKey