PFXImportCertStore function (wincrypt.h)
The PFXImportCertStore function imports a PFX BLOB and returns the handle of a store that contains certificates and any associated private keys.
HCERTSTORE PFXImportCertStore(
[in] CRYPT_DATA_BLOB *pPFX,
[in] LPCWSTR szPassword,
[in] DWORD dwFlags
);
[in] pPFX
A pointer to a CRYPT_DATA_BLOB structure that contains a PFX packet with the exported and encrypted certificates and keys.
[in] szPassword
A string password used to decrypt and verify the PFX packet. Whether set to a string of length greater than zero or set to an empty string or to NULL, this value must be exactly the same as the value that was used to encrypt the packet.
Beginning with Windows 8 and Windows Server 2012, if the PFX packet was created in the PFXExportCertStoreEx function by using the PKCS12_PROTECT_TO_DOMAIN_SIDS flag, the PFXImportCertStore function attempts to decrypt the password by using the Active Directory (AD) principal that was used to encrypt it. The AD principal is specified in the pvPara parameter. If the szPassword parameter in the PFXExportCertStoreEx function was an empty string or NULL and the dwFlags parameter was set to PKCS12_PROTECT_TO_DOMAIN_SIDS, that function randomly generated a password and encrypted it to the AD principal specified in the pvPara parameter. In that case you should set the password to the value, empty string or NULL, that was used when the PFX packet was created. The PFXImportCertStore function will use the AD principal to decrypt the random password, and the randomly generated password will be used to decrypt the PFX certificate.
When you have finished using the password, clear it from memory by calling the SecureZeroMemory function. For more information about protecting passwords, see Handling Passwords.
[in] dwFlags
The dwFlags parameter can be one of the following values:
Value | Meaning |
---|---|
|
Imported keys are marked as exportable. If this flag is not used, calls to the CryptExportKey function with the key handle fail. |
|
The user is to be notified through a dialog box or other method when certain attempts to use this key are made. The precise behavior is specified by the cryptographic service provider (CSP) being used.
Prior to Internet Explorer 4.0, Microsoft cryptographic service providers ignored this flag. Starting with Internet Explorer 4.0, Microsoft providers support this flag. If the provider context was opened with the CRYPT_SILENT flag set, using this flag causes a failure and the last error is set to NTE_SILENT_CONTEXT. |
|
The private keys are stored under the local computer and not under the current user. |
|
The private keys are stored under the current user and not under the local computer even if the PFX BLOB specifies that they should go into the local computer. |
|
Indicates that the CNG key storage provider (KSP) is preferred. If the CSP is specified in the PFX file, then the CSP is used, otherwise the KSP is preferred. If the CNG KSP is unavailable, the PFXImportCertStore function will fail.
Windows Server 2003 and Windows XP: This value is not supported. |
|
Indicates that the CNG KSP is always used. When specified, PFXImportCertStore attempts to use the CNG KSP irrespective of provider information in the PFX file. If the CNG KSP is unavailable, the import will not fail.
Windows Server 2003 and Windows XP: This value is not supported. |
|
Allow overwrite of the existing key. Specify this flag when you encounter a scenario in which you must import a PFX file that contains a key name that already exists. For example, when you import a PFX file, it is possible that a container of the same name is already present because there is no unique namespace for key containers. If you have created a "TestKey" on your computer, and then you import a PFX file that also has "TestKey" as the key container, the PKCS12_ALLOW_OVERWRITE_KEY setting allows the key to be overwritten.
Windows Server 2003 and Windows XP: This value is not supported. |
|
Do not persist the key. Specify this flag when you do not want to persist the key. For example, if it is not necessary to store the key after verification, then instead of creating a container and then deleting it, you can specify this flag to dispose of the key immediately.
Note If the PKCS12_NO_PERSIST_KEY flag is *not* set, keys are persisted on disk. If you do not want to persist the keys beyond their usage, you must delete them by calling the CryptAcquireContext function with the CRYPT_DELETEKEYSET flag set in the dwFlags parameter.
Note Some other considerations:
|
|
Import all extended
properties on the certificate that were saved on the certificate when it was exported.
Windows Server 2003 and Windows XP: This value is not supported. |
|
Unpack but do not persist the results. |
If the function succeeds, the function returns a handle to a certificate store that contains the imported certificates, including available private keys.
If the function fails, that is, if the password parameter does not contain an exact match with the password used to encrypt the exported packet or if there were any other problems decoding the PFX BLOB, the function returns NULL, and an error code can be found by calling the GetLastError function.
The PFXImportCertStore function opens a temporary store. If the function succeeds, you should close the handle to the store by calling the CertCloseStore function.
When you import a certificate from the PFX packet, the CSP/KSP container name is determined by using the AttributeId with OID 1.3.6.1.4.1.311.17.1 of the PKCS8ShroudedKeyBag SafeBag [bagId: 1.2.840.113549.1.12.10.1.2] (see PKCS #12 for details about the ASN.1 structure of this).
- AttributeId: 1.3.6.1.4.1.311.17.1
- Value: The KSP name or CSP name
If the AttributeId is not present and the PREFER_CNG flag is passed, MS_KEY_STORAGE_PROVIDER is picked. If the AttributeId is not present and the PREFER_CNG flag is not passed, the provider name is determined based on the public key algorithm (that is, the public key algorithm is determined by the AlgorithmIdentifier in PKCS #8):
- RSA: MS_ENHANCED_PROV_W
- DSA: MS_DEF_DSS_DH_PROV_W
Similarly, the key specification is determined by using the AttributeId with OID 2.5.29.15 (szOID_KEY_USAGE) as follows:
If a CAPI key is used:
- If KEY_ENCIPHERMENT or DATA_ENCIPHERMENT is set, then the key specification is set to AT_KEYEXCHANGE.
- If DIGITAL_SIGNATURE or CERT_SIGN or CRL_SIGN is set, then the key specification is set to AT_SIGNATURE.
If a CNG key is used:
- If KEY_ENCIPHERMENT or DATA_ENCIPHERMENT or ENCIPHER_ONLY or DECIPHER_ONLY is set, then ncrypt key usage is set to ALLOW_DECRYPT.
- If DIGITAL_SIGNATURE or CERT_SIGN or CRL_SIGN is set, ncrypt key usage is set to ALLOW_SIGN.
- If KEY_AGREEMENT is set, then ncrypt key usage is set to ALLOW_KEY_AGREEMENT.
If the AttributeId is not present, then the CAPI key value is set to AT_KEYEXCHANGE for RSA or DH and the algorithm is determined by the AlgorithmIdentifier in PKCS #8; otherwise, the algorithm is set to AT_SIGNATURE. For the CNG key value, all ncrypt key usage is set.
Note
If an invalid provider name is present in the PFX packet, or the base or enhanced cryptography provider is not present in this registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider, then a provider lookup is performed by the provider type using this registry subkey: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types.
Microsoft only supports two encryption/hash algorithms for importing a PFX:
- TripleDES-SHA1
- AES256-SHA256
For either of the above algorithms, encryption of the certificates is optional.
Microsoft can export a PFX from a certificate store via the All Tasks
> Yes, export the private key
selection. There you can select the encryption/hash algorithm to match one of these two choices.
You can use PowerShell to export a PFX via the following:
Export-PfxCertificate
[-CryptoAlgorithmOption <CryptoAlgorithmOptions>]
-CryptoAlgorithmOption
specifies the algorithm for encrypting private keys within the PFX file. If this parameter is not specified, the default is TripleDES_SHA1
. The acceptable values for this parameter are:
Value | Description |
---|---|
TripleDES_SHA1 |
Private keys will be encrypted in the PFX file using Triple DES encryption. |
AES256_SHA256 |
Private keys will be encrypted in the PFX file using AES-256 encryption. |
OpenSSL supports the above two algorithms via the following commands:
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
The following commands are equivalent to the previous two, but they do not encrypt the certificates:
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
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps | UWP apps] |
Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
Target Platform | Windows |
Header | wincrypt.h |
Library | Crypt32.lib |
DLL | Crypt32.dll |