Funzione PFXImportCertStore (wincrypt.h)

  • Articolo

La funzione PFXImportCertStore importa un BLOB PFX e restituisce l'handle di un archivio contenente certificati e chiavi private associate.

Sintassi

HCERTSTORE PFXImportCertStore(
  [in] CRYPT_DATA_BLOB *pPFX,
  [in] LPCWSTR         szPassword,
  [in] DWORD           dwFlags
);

Parametri

[in] pPFX

Puntatore a una struttura CRYPT_DATA_BLOB che contiene un pacchetto PFX con i certificati e le chiavi esportati e crittografati.

[in] szPassword

Password stringa usata per decrittografare e verificare il pacchetto PFX. Se impostata su una stringa di lunghezza maggiore di zero o impostata su una stringa vuota o su NULL, questo valore deve essere esattamente lo stesso del valore usato per crittografare il pacchetto.

A partire da Windows 8 e Windows Server 2012, se il pacchetto PFX è stato creato nella funzione PFXExportCertStoreExusando il flag PKCS12_PROTECT_TO_DOMAIN_SIDS, la funzione PFXImportCertStore tenta di decrittografare la password usando l'entità Active Directory (AD) usata per crittografarla. L'entità AD viene specificata nel parametro pvPara . Se il parametro szPassword nella funzione PFXExportCertStoreEx era una stringa vuota o NULL e il parametro dwFlags è stato impostato su PKCS12_PROTECT_TO_DOMAIN_SIDS, tale funzione ha generato in modo casuale una password e lo ha crittografato nell'entità AD specificata nel parametro pvPara . In tal caso, è necessario impostare la password sul valore, la stringa vuota o NULL, usata quando è stato creato il pacchetto PFX. La funzione PFXImportCertStore userà l'entità AD per decrittografare la password casuale e la password generata in modo casuale verrà usata per decrittografare il certificato PFX.

Al termine dell'uso della password, cancellarla dalla memoria chiamando la funzione SecureZeroMemory . Per altre informazioni sulla protezione delle password, vedere Gestione delle password.

[in] dwFlags

Il parametro dwFlags può essere uno dei valori seguenti:

Valore Significato
CRYPT_EXPORTABLE
0x00000001
 Le chiavi importate sono contrassegnate come esportabili. Se questo flag non viene usato, le chiamate alla funzione CryptExportKey hanno esito negativo.
CRYPT_USER_PROTECTED
0x00000002
 L'utente deve ricevere una notifica tramite una finestra di dialogo o un altro metodo quando vengono effettuati determinati tentativi di usare questa chiave. Il comportamento preciso viene specificato dal provider di servizi di crittografia (CSP) usato.

Prima di Internet Explorer 4.0, i provider di servizi di crittografia Microsoft ignoravano questo flag. A partire da Internet Explorer 4.0, i provider Microsoft supportano questo flag.

Se il contesto del provider è stato aperto con il flag CRYPT_SILENT impostato, l'uso di questo flag causa un errore e l'ultimo errore è impostato su NTE_SILENT_CONTEXT.
CRYPT_MACHINE_KEYSET
0x00000020
 Le chiavi private vengono archiviate nel computer locale e non nell'utente corrente.
CRYPT_USER_KEYSET
0x00001000
 Le chiavi private vengono archiviate nell'utente corrente e non nel computer locale anche se il BLOB PFX specifica che devono passare al computer locale.
PKCS12_PREFER_CNG_KSP
0x00000100
 Indica che il provider di archiviazione chiavi CNG (KSP) è preferibile. Se il CSP viene specificato nel file PFX, viene usato il CSP, in caso contrario, viene preferito il provider di servizi di dominio. Se il KSP CNG non è disponibile, la funzione PFXImportCertStore avrà esito negativo.

Windows Server 2003 e Windows XP: Questo valore non è supportato.
PKCS12_ALWAYS_CNG_KSP
0x00000200
 Indica che il KSP CNG viene sempre usato. Se specificato, PFXImportCertStore tenta di usare il KSP CNG indipendentemente dalle informazioni del provider nel file PFX. Se il KSP CNG non è disponibile, l'importazione non avrà esito negativo.

Windows Server 2003 e Windows XP: Questo valore non è supportato.
PKCS12_ALLOW_OVERWRITE_KEY
0x00004000
 Consenti sovrascrivere la chiave esistente. Specificare questo flag quando si verifica uno scenario in cui è necessario importare un file PFX contenente un nome chiave già esistente. Ad esempio, quando si importa un file PFX, è possibile che un contenitore dello stesso nome sia già presente perché non esiste uno spazio dei nomi univoco per i contenitori chiave. Se è stato creato un file PFX "TestKey" nel computer e quindi si importa un file PFX con "TestKey" come contenitore di chiavi, l'impostazione PKCS12_ALLOW_OVERWRITE_KEY consente di sovrascrivere la chiave.

Windows Server 2003 e Windows XP: Questo valore non è supportato.
PKCS12_NO_PERSIST_KEY
0x00008000
 Non mantenere la chiave. Specificare questo flag quando non si vuole mantenere la chiave. Ad esempio, se non è necessario archiviare la chiave dopo la verifica, invece di creare un contenitore e quindi eliminarlo, è possibile specificare questo flag per eliminare immediatamente la chiave.
Nota Se il flag di PKCS12_NO_PERSIST_KEY è *not* impostato, le chiavi vengono mantenute sul disco. Se non si vuole rendere persistenti le chiavi oltre l'utilizzo, è necessario eliminarle chiamando la funzione CryptAcquireContext con il flag CRYPT_DELETEKEYSET impostato nel parametro dwFlags .
Nota Alcune altre considerazioni:

  • Quando si usa PKCS12_NO_PERSIST_KEY, la proprietà CERT_KEY_CONTEXT_PROP_ID viene impostata internamente sul certificato e CERT_KEY_CONTEXT_PROP_ID contiene l'NCRYPT_KEY_HANDLE.

  • Se il PKCS12_NO_PERSIST_KEY non viene usato, la proprietà CERT_KEY_PROV_INFO_PROP_ID è impostata.

  • Se il certificato con la chiave non persistente viene eseguito il marshalling a un altro processo, la proprietà CERT_KEY_CONTEXT_PROP_ID non verrà eseguita.

  • Affinché NO_PERSIST funzioni, deve essere nello stesso processo e l'utente del PCCERT_CONTEXT deve supportare l'CERT_KEY_CONTEXT_PROP_ID. Questa operazione si applica in genere durante un handshake TLS: se l'handshake viene eseguito esternamente al processo di chiamata in LSASS.exe, non è possibile usare PKCS12_NO_PERSIST_KEY quando si passa dal processo chiamante a LSASS (perché l'NCRYPT_KEY_HANDLE è un puntatore a una struttura di dati e non un handle kernel).

 
Windows Server 2003 e Windows XP: Questo valore non è supportato.
PKCS12_INCLUDE_EXTENDED_PROPERTIES
0x0010
 Importare tutte le proprietà estese nel certificato salvato nel certificato quando è stato esportato.

Windows Server 2003 e Windows XP: Questo valore non è supportato.
0x10000000
 Decomprimere ma non rendere persistenti i risultati.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un handle a un archivio certificati contenente i certificati importati, incluse le chiavi private disponibili.

Se la funzione ha esito negativo, ovvero, se il parametro password non contiene una corrispondenza esatta con la password usata per crittografare il pacchetto esportato o se si verificano altri problemi di decodifica del BLOB PFX, la funzione restituisce NULL e un codice di errore può essere trovato chiamando la funzione GetLastError .

Commenti

La funzione PFXImportCertStore apre un archivio temporaneo. Se la funzione ha esito positivo, è necessario chiudere l'handle all'archivio chiamando la funzione CertCloseStore .

Quando si importa un certificato dal pacchetto PFX, il nome del contenitore CSP/KSP viene determinato usando l'attributoId con OID 1.3.6.1.4.1.311.17.1 dell'oggetto PKCS8ShroudedKeyBag SafeBag [bagId: 1.2.840.113549.1.12.10.1.2] (vedere PKCS #12 per informazioni dettagliate sulla struttura ASN.1 di questo).

  • AttributeId: 1.3.6.1.4.1.311.17.1
  • Valore: Nome KSP o nome CSP

Se l'attributoId non è presente e il flag di PREFER_CNG viene passato, MS_KEY_STORAGE_PROVIDER viene selezionato. Se l'attributoId non è presente e il flag di PREFER_CNG non viene passato, il nome del provider viene determinato in base all'algoritmo di chiave pubblica , ovvero l'algoritmo di chiave pubblica è determinato dall'algoritmo AlgorithmIdentifier in PKCS #8):

  • RSA: MS_ENHANCED_PROV_W
  • DSA: MS_DEF_DSS_DH_PROV_W

Analogamente, la specifica della chiave viene determinata usando AttributeId con OID 2.5.29.15 (szOID_KEY_USAGE) come indicato di seguito:

Se viene usata una chiave CAPI:

  • Se KEY_ENCIPHERMENT o DATA_ENCIPHERMENT è impostato, la specifica della chiave è impostata su AT_KEYEXCHANGE.
  • Se DIGITAL_SIGNATURE o CERT_SIGN o CRL_SIGN è impostato, la specifica della chiave è impostata su AT_SIGNATURE.

Se viene usata una chiave CNG:

  • Se KEY_ENCIPHERMENT o DATA_ENCIPHERMENT o ENCIPHER_ONLY o DECIPHER_ONLY è impostato, l'utilizzo della chiave ncrypt è impostato su ALLOW_DECRYPT.
  • Se DIGITAL_SIGNATURE o CERT_SIGN o CRL_SIGN è impostato, l'utilizzo della chiave ncrypt è impostato su ALLOW_SIGN.
  • Se KEY_AGREEMENT è impostato, l'utilizzo della chiave ncrypt è impostato su ALLOW_KEY_AGREEMENT.

Se l'attributoId non è presente, il valore della chiave CAPI è impostato su AT_KEYEXCHANGE per RSA o DH e l'algoritmo è determinato dall'algoritmoIdentifier in PKCS #8; in caso contrario, l'algoritmo è impostato su AT_SIGNATURE. Per il valore della chiave CNG, viene impostato l'utilizzo di tutte le chiavi ncrypt.

Nota

Se nel pacchetto PFX è presente un nome del provider non valido oppure il provider di crittografia base o avanzato non è presente in questa chiave del Registro di sistema: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider, viene eseguita una ricerca del provider dal tipo di provider usando questa sottochiave del Registro di sistema: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types.

Microsoft supporta solo due algoritmi di crittografia/hash per l'importazione di un PFX:

  • TripleDES-SHA1
  • AES256-SHA256

Per uno degli algoritmi precedenti, la crittografia dei certificati è facoltativa.

Microsoft può esportare un PFX da un archivio certificati tramite la All Tasks>Yes, export the private key selezione. È possibile selezionare l'algoritmo di crittografia/hash in modo che corrisponda a una di queste due opzioni.

È possibile usare PowerShell per esportare un PFX tramite quanto segue:

Export-PfxCertificate
[-CryptoAlgorithmOption <CryptoAlgorithmOptions>]

-CryptoAlgorithmOption specifica l'algoritmo per crittografare le chiavi private all'interno del file PFX. Se questo parametro non è specificato, il valore predefinito è TripleDES_SHA1. I valori validi per questo parametro sono:

Valore Descrizione
TripleDES_SHA1 Le chiavi private verranno crittografate nel file PFX usando la crittografia Triple DES.
AES256_SHA256 Le chiavi private verranno crittografate nel file PFX usando la crittografia AES-256.

OpenSSL supporta i due algoritmi precedenti tramite i comandi seguenti:

  • openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt
  • openssl pkcs12 -keypbe AES-256-CBC -certpbe AES-256-CBC -macalg sha256 -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt

I comandi seguenti sono equivalenti ai due precedenti, ma non crittografano i certificati:

  • openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe NONE -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt
  • openssl pkcs12 -keypbe AES-256-CBC -certpbe NONE -macalg sha256 -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt

Requisiti

Requisito Valore
Client minimo supportato Windows XP [app desktop | App UWP]
Server minimo supportato Windows Server 2003 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione wincrypt.h
Libreria Crypt32.lib
DLL Crypt32.dll

Vedi anche

PFXExportCertStore

PFXExportCertStoreEx