EN
Ce contenu n’est pas disponible dans votre langue. Voici la version anglaise.

PFXImportCertStore function

The PFXImportCertStore function imports a PFX BLOB and returns the handle of a store that contains certificates and any associated private keys.

Syntax


HCERTSTORE WINAPI PFXImportCertStore(
  _In_  CRYPT_DATA_BLOB *pPFX,
  _In_  LPCWSTR szPassword,
  _In_  DWORD dwFlags
);

Parameters

pPFX [in]

A pointer to a CRYPT_DATA_BLOB structure that contains a PFX packet with the exported and encrypted certificates and keys.

szPassword [in]

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.

dwFlags [in]

This parameter can be one of the following values.

ValueMeaning
CRYPT_EXPORTABLE
0x00000001

Imported keys are marked as exportable. If this flag is not used, calls to the CryptExportKey function with the key handle fail.

CRYPT_USER_PROTECTED
0x00000002

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.

CRYPT_MACHINE_KEYSET
0x00000020

The private keys are stored under the local computer and not under the current user.

CRYPT_USER_KEYSET
0x00001000

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.

PKCS12_PREFER_CNG_KSP
0x00000100

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.

PKCS12_ALWAYS_CNG_KSP
0x00000200

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.

PKCS12_ALLOW_OVERWRITE_KEY
0x00004000

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.

PKCS12_NO_PERSIST_KEY
0x00008000

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.

Windows Server 2003 and Windows XP:  This value is not supported.

PKCS12_INCLUDE_EXTENDED_PROPERTIES
0x0010

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.

0x10000000

Unpack but do not persist the results.

 

Return value

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.

Remarks

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.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Crypt32.lib

DLL

Crypt32.dll

See also

PFXExportCertStore
PFXExportCertStoreEx

 

 

Ajouts de la communauté

AJOUTER
Afficher:
© 2014 Microsoft