NCryptImportKey 函式 (ncrypt.h)

發行項
06/12/2024

NCryptImportKey 函式會從記憶體 BLOB 匯入密碼編譯 API：新一代 (CNG) 密鑰。

語法

SECURITY_STATUS NCryptImportKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [in, optional] NCRYPT_KEY_HANDLE  hImportKey,
  [in]           LPCWSTR            pszBlobType,
  [in, optional] NCryptBufferDesc   *pParameterList,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           PBYTE              pbData,
  [in]           DWORD              cbData,
  [in]           DWORD              dwFlags
);

參數

[in] hProvider

金鑰儲存提供者的句柄。

[in, optional] hImportKey

已匯入金鑰 BLOB 內金鑰資料的加密金鑰句柄。這必須是 NCryptExportKey 函式之 hExportKey 參數中傳遞之相同密鑰的句柄。如果此參數為 NULL，則會假設金鑰 BLOB 不會加密。

[in] pszBlobType

以 Null 終止的 Unicode 字串，其中包含指定金鑰 BLOB 格式的識別碼。這些格式專屬於特定金鑰儲存提供者。如需 Microsoft 提供者支援的 BLOB 格式，請參閱。

[in, optional] pParameterList

NCryptBufferDesc 結構的位址，指向包含索引鍵之參數資訊的緩衝區陣列。

[out] phKey

接收金鑰句柄的 NCRYPT_KEY_HANDLE 變數位址。當您完成使用此句柄時，請將它傳遞給 NCryptFreeObject 函式來釋放它。

[in] pbData

緩衝區的位址，其中包含要匯入的金鑰 BLOB。 cbData 參數包含這個緩衝區的大小。

[in] cbData

pbData 緩衝區的大小，以位元組為單位。

[in] dwFlags

修改函式行為的旗標。這可以是零或下列一或多個值的組合。有效的旗標集專屬於每個金鑰儲存提供者。

值	意義
NCRYPT_SILENT_FLAG	要求金鑰服務提供者 (KSP) 不會顯示任何使用者介面。如果提供者必須顯示要運作的UI，呼叫會失敗，KSP應該將 NTE_SILENT_CONTEXT 錯誤碼設定為最後一個錯誤。
NCRYPT_REQUIRE_VBS_FLAG	表示密鑰必須受到虛擬式安全性保護， (VBS) 。根據預設，這會建立儲存在磁碟上的跨開機保存密鑰，以在重新啟動週期之間保存。如果無法使用 VBS，作業將會失敗。 (*請參閱備註)
NCRYPT_PREFER_VBS_FLAG	表示應使用虛擬式安全性 (VBS) 來保護密鑰。根據預設，這會建立儲存在磁碟上的跨開機保存密鑰，以在重新啟動週期之間保存。如果無法使用 VBS，作業將會產生軟體隔離密鑰。 (*請參閱備註)
NCRYPT_USE_PER_BOOT_KEY_FLAG	可搭配 NCRYPT_REQUIRE_VBS_FLAG 或 NCRYPT_PREFER_VBS_FLAG使用的額外旗標。指示虛擬式安全性 (VBS) 使用儲存在磁碟上的個別開機密鑰來保護用戶端密鑰，但無法在開機週期之間重複使用。 (*請參閱備註)

傳回值

傳回狀態代碼，指出函式的成功或失敗。

可能的傳回碼包括但不限於下列各項：

傳回碼	Description
ERROR_SUCCESS	函式成功。
NTE_BAD_FLAGS	dwFlags 參數包含無效的值。
NTE_EXISTS	具有指定名稱的索引鍵已經存在，且未指定 NCRYPT_OVERWRITE_KEY_FLAG 。
NTE_INVALID_HANDLE	hProvider 參數無效。
NTE_INVALID_PARAMETER	一或多個參數無效。
NTE_NO_MEMORY	發生記憶體配置失敗。
NTE_VBS_UNAVAILABLE	VBS 無法使用。
NTE_VBS_CANNOT_DECRYPT_KEY	VBS 解密作業失敗。

備註

重要

VBS 旗標的相關信息與發行前版本產品有關，在正式發行前可能會大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

服務不得從它的 StartService 函式呼叫此函式。如果服務從其 StartService 函式呼叫此函式，可能會發生死結，而且服務可能會停止回應。

下列各節說明 Microsoft 金鑰儲存提供者特有的行為：

Microsoft 軟體 KSP
Microsoft 智慧卡 KSP

Microsoft 軟體 KSP

pszBlobType 參數的 Microsoft 軟體 KSP 支援下列常數。

如果未提供金鑰名稱，Microsoft 軟體 KSP 會將金鑰視為暫時性，而且不會持續儲存密鑰。針對 NCRYPT_OPAQUETRANSPORT_BLOB 類型，金鑰名稱會在匯出時儲存在 BLOB 內。針對其他 BLOB 格式，可以在 pParameterList 參數內的NCRYPTBUFFER_PKCS_KEY_NAME緩衝區參數中提供名稱。

在 Windows Server 2008 和 Windows Vista 上，只有匯入為 PKCS #7 信封 BLOB 的密鑰 (NCRYPT_PKCS7_ENVELOPE_BLOB) 或 PKCS #8 私鑰 BLOB (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) 可以使用上述方法來保存。若要保存透過這些平臺上其他 BLOB 類型匯入的金鑰，請使用金鑰匯入和匯出中所述的方法。

此 KSP 支援下列旗標。

詞彙	描述
NCRYPT_NO_KEY_VALIDATION	請勿驗證金鑰組的公用部分。此旗標僅適用於公開/私鑰組。
NCRYPT_DO_NOT_FINALIZE_FLAG	請勿完成金鑰。當您需要在匯入金鑰之後新增或修改索引鍵的屬性時，此選項非常有用。您必須將金鑰句柄傳遞至 NCryptFinalizeKey 函式，才能使用密鑰。私鑰 PKCS #7 和 PKCS #8 支援此旗標，但不支援公鑰。
NCRYPT_MACHINE_KEY_FLAG	金鑰會套用至本機計算機。如果這個旗標不存在，金鑰會套用至目前的使用者。
NCRYPT_OVERWRITE_KEY_FLAG	如果金鑰已存在於具有指定名稱的容器中，則會覆寫現有的密鑰。如果未指定此旗標，且具有指定名稱的索引鍵已經存在，則此函式會傳回NTE_EXISTS。
NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG	同時將金鑰儲存在舊版記憶體中。這可讓金鑰與 CryptoAPI 搭配使用。此旗標僅適用於 RSA 金鑰。

Microsoft 智慧卡 KSP

此 KSP 所支援的金鑰 BLOB 格式和旗標集合與 Microsoft 軟體 KSP 所支援的集合相同。

在 Windows Server 2008 和 Windows Vista 上，Microsoft 智慧卡 KSP 會將所有密鑰匯入 Microsoft 軟體 KSP。因此，無法使用此 API 將密鑰保存在智慧卡上，而且在嘗試保存 Microsoft 軟體 KSP 內的密鑰時，適用上一節中的指引。

在 Windows Server 2008 R2 和 Windows 7 上，Microsoft 智慧卡密鑰儲存提供者可以將私鑰匯入智慧卡，前提是符合下列條件：

卡片上的金鑰容器名稱有效。
智慧卡支持匯入私鑰。
下列兩個登錄機碼會設定為的 0x1DWORD：
- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base 智慧卡加密提供者\AllowPrivateExchangeKeyImport
- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base 智慧卡加密提供者\AllowPrivateSignatureKeyImport

如果密鑰容器名稱為 NULL，Microsoft 智慧卡 KSP 會將密鑰視為暫時金鑰，並將其匯入 Microsoft 軟體 KSP。

VBS 金鑰的其他硬體需求

雖然您的計算機上可能已安裝適當的OS，但必須符合下列額外的硬體需求，才能使用 VBS來產生和保護密鑰。

已啟用 VBS (請參閱虛擬式安全性 (VBS) )
已啟用 TPM
- 針對裸機環境，需要 TPM 2.0。
- 針對 VM 環境，支援 vTPM (虛擬 TPM) 。
BIOS 應該使用 SecureBoot 配置檔升級至 UEFI

如需硬體需求的詳細資訊：

VBS 有數個硬體需求可執行，包括 Hyper-V (Windows Hypervisor) 、64 位架構和 IOMMU 支援。您可以在這裡找到 VBS 硬體需求的完整清單。
您可以在這裡找到高度安全裝置的需求。

規格需求

需求	值
最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	ncrypt.h
程式庫	Ncrypt.lib
Dll	Ncrypt.dll

另請參閱

NCryptBuffer

NCryptCreatePersistedKey

共用方式為