共用方式為


PFXImportCertStore 函式 (wincrypt.h)

PFXImportCertStore 函式會匯入 PFX BLOB,並傳回存放區句柄,其中包含憑證和任何相關聯的私鑰

語法

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

參數

[in] pPFX

包含已匯出和加密憑證和金鑰之 PFX 封包之 CRYPT_DATA_BLOB 結構的指標。

[in] szPassword

用來解密和驗證 PFX 封包的字串密碼。 不論設定為長度大於零的字串或設定為空字串或 NULL,這個值必須與用來加密封包的值完全相同。

從 Windows 8 和 Windows Server 2012 開始,如果使用 PKCS12_PROTECT_TO_DOMAIN_SIDS 旗標在 PFXExportCertStoreEx 函式中建立 PFX 封包,PFXImportCertStore 函式會嘗試使用 Active Directory (AD) 主體來解密密碼。 AD 主體是在 pvPara 參數中指定。 如果 PFXExportCertStoreEx 函式中的 szPassword 參數是空字串或 NULL,且 dwFlags 參數已設定為 PKCS12_PROTECT_TO_DOMAIN_SIDS,該函式會隨機產生密碼,並將其加密至 pvPara 參數中指定的 AD 主體。 在此情況下,您應該將密碼設定為建立 PFX 封包時所使用的值空白字串或 NULLPFXImportCertStore 函式會使用AD主體來解密隨機密碼,而隨機產生的密碼將用來解密 PFX 憑證。

當您完成使用密碼時,請呼叫 SecureZeroMemory 函式 ,從記憶體中清除密碼。 如需保護密碼的詳細資訊,請參閱 處理密碼

[in] dwFlags

dwFlags 參數可以是下列其中一個值:

意義
CRYPT_EXPORTABLE
0x00000001
匯入的金鑰會標記為可匯出。 如果未使用此旗標,呼叫具有密鑰句柄的 CryptExportKey 函式會失敗。
CRYPT_USER_PROTECTED
0x00000002
當用戶嘗試使用此金鑰時,會透過對話方塊或其他方法收到通知。 精確的行為是由使用 (CSP) 的密碼編譯服務提供者 所指定。

在 Internet Explorer 4.0 之前,Microsoft 密碼編譯服務提供者會忽略此旗標。 從 Internet Explorer 4.0 開始,Microsoft 提供者支援此旗標。

如果提供者內容是以CRYPT_SILENT旗標集開啟,則使用此旗標會導致失敗,並將最後一個錯誤設定為NTE_SILENT_CONTEXT。

CRYPT_MACHINE_KEYSET
0x00000020
私鑰會儲存在本機計算機底下,而不是儲存在目前使用者之下。
CRYPT_USER_KEYSET
0x00001000
私鑰會儲存在目前使用者底下,而不是儲存在本機計算機下,即使 PFX BLOB 指定應該進入本機計算機也一樣。
PKCS12_PREFER_CNG_KSP
0x00000100
表示偏好使用 CNG 金鑰儲存提供者 (KSP) 。 如果在 PFX 檔案中指定 CSP,則會使用 CSP,否則會偏好使用 KSP。 如果 CNG KSP 無法使用, PFXImportCertStore 函式將會失敗。

Windows Server 2003 和 Windows XP: 不支援此值。

PKCS12_ALWAYS_CNG_KSP
0x00000200
表示一律使用 CNG KSP。 指定時,不論 PFX 檔案中的提供者信息為何, PFXImportCertStore 會嘗試使用 CNG KSP。 如果 CNG KSP 無法使用,匯入將不會失敗。

Windows Server 2003 和 Windows XP: 不支援此值。

PKCS12_ALLOW_OVERWRITE_KEY
0x00004000
允許覆寫現有的金鑰。 當您遇到案例時,必須匯入包含已存在索引鍵名稱的 PFX 檔案時,請指定此旗標。 例如,當您匯入 PFX 檔案時,可能已經有相同名稱的容器,因為索引鍵容器沒有唯一的命名空間。 如果您已在計算機上建立 「TestKey」,然後匯入 PFX 檔案也具有 「TestKey」 做為密鑰容器, 則PKCS12_ALLOW_OVERWRITE_KEY 設定可覆寫密鑰。

Windows Server 2003 和 Windows XP: 不支援此值。

PKCS12_NO_PERSIST_KEY
0x00008000
請勿保存金鑰。 當您不想儲存金鑰時,請指定此旗標。 例如,如果不需要在驗證之後儲存密鑰,而不是建立容器,然後刪除它,您可以指定此旗標立即處置密鑰。
注意 如果 PKCS12_NO_PERSIST_KEY 旗標是 *not* 設定,則密鑰會保存在磁碟上。 如果您不想在金鑰使用範圍之外保存金鑰,您必須呼叫 CryptAcquireContext 函式,並在 dwFlags 參數中設定CRYPT_DELETEKEYSET旗標來刪除密鑰。
注意 其他一些考慮:
  • 使用 PKCS12_NO_PERSIST_KEY 時,屬性CERT_KEY_CONTEXT_PROP_ID會在憑證內部設定,而且CERT_KEY_CONTEXT_PROP_ID包含NCRYPT_KEY_HANDLE。

  • 如果未使用PKCS12_NO_PERSIST_KEY,則會設定CERT_KEY_PROV_INFO_PROP_ID屬性。

  • 如果具有非保存金鑰的憑證封送處理至另一個進程,則不會封送處理CERT_KEY_CONTEXT_PROP_ID屬性。

  • 若要讓NO_PERSIST運作,它必須處於相同的程式, 而且 PCCERT_CONTEXT的用戶必須支援CERT_KEY_CONTEXT_PROP_ID。 這通常會在 TLS 交握期間套用:如果在 LSASS.exe 中的呼叫進程外部執行交握,則從呼叫進程移至 LSASS (時,無法使用PKCS12_NO_PERSIST_KEY,因為NCRYPT_KEY_HANDLE是數據結構的指標,而不是核心句柄) 。

 
Windows Server 2003 和 Windows XP: 不支援此值。
PKCS12_INCLUDE_EXTENDED_PROPERTIES
0x0010
匯入匯出憑證時儲存在憑證上的所有擴充屬性。

Windows Server 2003 和 Windows XP: 不支援此值。

0x10000000
解壓縮,但不會保存結果。

傳回值

如果函式成功,函式會傳回包含匯入憑證的證書存儲句柄,包括可用的私鑰。

如果函式失敗,也就是說,如果password參數未包含與用來加密匯出封包的密碼完全相符,或者如果有任何其他問題譯碼 PFX BLOB,則函式會傳回 NULL,而且呼叫 GetLastError 函式即可找到錯誤碼。

備註

PFXImportCertStore 函式會開啟暫存存放區。 如果函式成功,您應該呼叫 CertCloseStore 函式來關閉存放區的句柄。

當您從 PFX 封包匯入憑證時,CSP/KSP 容器名稱是使用具有 PKCS8ShroudedKeyBag 之 OID 1.3.6.1.1.4.1.311.17.1 的 AttributeId 來決定 SafeBag [bagId: 1.2.840.113549.1.1.12.10.1.2] (請參閱 PKCS #12 ,以取得此) ASN.1 結構的詳細數據。

  • AttributeId: 1.3.6.1.4.1.311.17.1
  • 價值: KSP 名稱或 CSP 名稱

如果 AttributeId 不存在且傳遞PREFER_CNG旗標,則會挑選MS_KEY_STORAGE_PROVIDER。 如果 AttributeId 不存在且未傳遞PREFER_CNG旗標,則提供者名稱會根據公鑰演演算法 (決定,公鑰演演算法是由 PKCS 中的 AlgorithmIdentifier #8) 所決定:

  • Rsa: MS_ENHANCED_PROV_W
  • Dsa: MS_DEF_DSS_DH_PROV_W

同樣地,索引鍵規格是使用 AttributeId 搭配 OID 2.5.29.15 (szOID_KEY_USAGE) ,如下所示:

如果使用 CAPI 金鑰:

  • 如果已設定KEY_ENCIPHERMENT或DATA_ENCIPHERMENT,則索引鍵規格會設定為 AT_KEYEXCHANGE。
  • 如果已設定DIGITAL_SIGNATURE或CERT_SIGN或CRL_SIGN,則索引鍵規格會設定為 AT_SIGNATURE。

如果使用 CNG 金鑰:

  • 如果已設定KEY_ENCIPHERMENT或DATA_ENCIPHERMENT或ENCIPHER_ONLY或DECIPHER_ONLY,則 ncrypt 金鑰使用方式會設定為 ALLOW_DECRYPT。
  • 如果已設定DIGITAL_SIGNATURE或CERT_SIGN或CRL_SIGN,ncrypt 金鑰使用方式會設定為 ALLOW_SIGN。
  • 如果已設定KEY_AGREEMENT,則 ncrypt 金鑰使用方式會設定為 ALLOW_KEY_AGREEMENT。

如果 AttributeId 不存在,則 CAPI 索引鍵值會設定為 RSA 或 DH AT_KEYEXCHANGE,且演算法是由 PKCS 中的 AlgorithmIdentifier #8 所決定;否則,演算法會設定為 AT_SIGNATURE。 針對 CNG 金鑰值,會設定所有 ncrypt 金鑰使用方式。

注意

如果 PFX 封包中存在無效的提供者名稱,或基底或增強型密碼編譯提供者不存在於此登入機碼中: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider,則提供者查閱是由提供者類型使用此登入子機碼來執行: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types

Microsoft 僅支援兩種加密/哈希演算法來匯入 PFX:

  • TripleDES-SHA1
  • AES256-SHA256

針對上述任一演算法,憑證的加密是選擇性的。

Microsoft 可以透過 All Tasks>Yes, export the private key 選取專案,從證書存儲匯出 PFX。 您可以在該處選取加密/哈希演算法,以符合這兩個選項之一。

您可以使用 PowerShell 透過下列項目匯出 PFX:

Export-PfxCertificate
[-CryptoAlgorithmOption <CryptoAlgorithmOptions>]

-CryptoAlgorithmOption 指定在 PFX 檔案中加密私鑰的演算法。 如果未指定此參數,則預設值為 TripleDES_SHA1。 此參數可接受的值為:

Description
TripleDES_SHA1 私鑰將會使用三重 DES 加密在 PFX 檔案中加密。
AES256_SHA256 私鑰將會使用 AES-256 加密在 PFX 檔案中加密。

OpenSSL 透過下列命令支援上述兩種演算法:

  • 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

下列命令相當於前兩個命令,但不會加密憑證:

  • 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

規格需求

需求
最低支援的用戶端 Windows XP [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 wincrypt.h
程式庫 Crypt32.lib
Dll Crypt32.dll

另請參閱

PFXExportCertStore

PFXExportCertStoreEx