Funzione NCryptImportKey (ncrypt.h)
La funzione NCryptImportKey importa un'API di crittografia: chiave CNG (Next Generation) 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 delle chiavi all'interno del BLOB della chiave importata. Questo deve essere un handle alla stessa chiave passata nel parametro hExportKey della funzione NCryptExportKey. Se questo parametro è NULL, si presuppone che il BLOB della chiave non venga crittografato.
[in] pszBlobType
Stringa Unicode con terminazione null contenente un identificatore che specifica il formato del BLOB della chiave. Questi formati sono specifici di un provider di archiviazione delle chiavi specifico. 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 contenente il BLOB della chiave da importare. Il parametro cbData contiene le dimensioni di questo buffer.
[in] cbData
Dimensioni, in byte, del buffer pbData .
[in] dwFlags
Contrassegni che modificano il comportamento della funzione. Questo 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 da operare, la chiamata ha esito negativo e il KSP 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 (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. |
| NTE_VBS_CANNOT_DECRYPT_KEY | Operazione di decrittografia non riuscita di VBS. |
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.
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.
Le sezioni seguenti descrivono comportamenti specifici per i provider di archiviazione delle chiavi Microsoft:
- Microsoft Software KSP
- Microsoft Smart Card KSP
Microsoft Software KSP
Le costanti seguenti sono supportate dal software Microsoft KSP per il parametro pszBlobType .
Se non viene specificato un nome di chiave, Microsoft Software KSP considera la chiave come effimero e non lo archivia in modo permanente. Per il tipo NCRYPT_OPAQUETRANSPORT_BLOB , il nome della chiave viene archiviato all'interno del BLOB quando viene esportato. Per altri formati BLOB, il nome può essere fornito 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 di busta PKCS #7 (NCRYPT_PKCS7_ENVELOPE_BLOB) o PKCS #8 private key BLOBs (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) possono essere mantenute usando il metodo precedente. Per rendere persistenti le chiavi importate tramite altri tipi BLOB in queste piattaforme, usare il metodo documentato in Importazione chiave ed esportazione.
I flag seguenti sono supportati da questo KSP.
| 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 della 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 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_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 valore 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 della chiave è NULL, il provider di servizi di configurazione della smart card Microsoft considera la chiave come temporanea e la importa nel KSP del software Microsoft.
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
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per