共用方式為

NCryptImportKey 函式 (ncrypt.h)

  • 發行項

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 Software KSP 會將密鑰視為暫時性，而且不會持續儲存密鑰。 針對 NCRYPT_OPAQUETRANSPORT_BLOB 類型，金鑰名稱會在匯出時儲存在 BLOB 中。 針對其他 BLOB 格式，名稱可以在 pParameterList 參數內的NCRYPTBUFFER_PKCS_KEY_NAME緩衝區參數中提供。

在 Windows Server 2008 和 Windows Vista 上，只有匯入為 PKCS #7 的密鑰， (才能使用上述方法來保存 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