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 封包時所使用的值空白字串或 NULL。 PFXImportCertStore 函式會使用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