共用方式為


NCryptCreatePersistedKey 函式 (ncrypt.h)

NCryptCreatePersistedKey 函式會建立新的密鑰,並將它儲存在指定的密鑰儲存提供者中。 使用此函式建立金鑰之後,您可以使用 NCryptSetProperty 函式 來設定其屬性;不過,在呼叫 NCryptFinalizeKey 函式之前,無法使用密鑰。

語法

SECURITY_STATUS NCryptCreatePersistedKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           LPCWSTR            pszAlgId,
  [in, optional] LPCWSTR            pszKeyName,
  [in]           DWORD              dwLegacyKeySpec,
  [in]           DWORD              dwFlags
);

參數

[in] hProvider

要用來建立金鑰的金鑰儲存提供者句柄。 此句柄是使用 NCryptOpenStorageProvider 函式取得。

[out] phKey

接收金鑰句柄 的NCRYPT_KEY_HANDLE 變數位址。 當您完成使用此句柄時,請將它傳遞至 NCryptFreeObject 函式來釋放它。 若要刪除磁碟上的密鑰檔案,請將句柄傳遞至 NCryptDeleteKey 函式。 這也會釋放句柄。 因此,應用程式可能會將句柄傳遞至 NCryptFreeObjectNCryptDeleteKey,但不能同時傳遞兩者。

[in] pszAlgId

Null 終止 Unicode 字串的指標,其中包含用來建立密鑰的密碼編譯演算法標識碼。 這可以是其中一個標準 CNG 演演算法標識碼 ,或是另一個已註冊演算法的標識碼。

[in, optional] pszKeyName

包含索引鍵名稱之 Null 終止 Unicode 字串的指標。 如果此參數為 NULL,此函式會建立未保存的暫時密鑰。

[in] dwLegacyKeySpec

指定金鑰類型的舊版識別碼。 這個值可以是下列其中一個值:

意義
AT_KEYEXCHANGE 金鑰是金鑰交換金鑰。
AT_SIGNATURE 金鑰是簽章金鑰。
0 索引鍵不是上述類型。

[in] dwFlags

一組旗標,可修改此函式的行為。 這可以是零或下列一或多個值的組合:

意義
NCRYPT_MACHINE_KEY_FLAG 金鑰適用於本機電腦。 如果此旗標不存在,金鑰會套用至目前的使用者。
NCRYPT_OVERWRITE_KEY_FLAG 如果金鑰已存在於具有指定名稱的容器中,將會覆寫現有的密鑰。 如果未指定此旗標,且具有指定名稱的索引鍵已經存在,則此函式會傳回 NTE_EXISTS
NCRYPT_REQUIRE_VBS_FLAG 表示密鑰必須受到虛擬化型安全性保護, (VBS) 。 根據預設,這會建立儲存在磁碟上的跨開機保存密鑰,以在重新啟動週期之間保存。

如果無法使用 VBS,作業將會失敗。 (*請參閱備註)
NCRYPT_PREFER_VBS_FLAG 表示應使用虛擬化型安全性 (VBS) 來保護密鑰。 根據預設,這會建立儲存在磁碟上的跨開機保存密鑰,以在重新啟動週期之間保存

如果無法使用 VBS,作業將會產生軟體隔離密鑰。 (*請參閱備註)
NCRYPT_USE_PER_BOOT_KEY_FLAG 可搭配 NCRYPT_REQUIRE_VBS_FLAGNCRYPT_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 無法使用。

備註

重要

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

如果您要建立 RSA 金鑰組,您也可以將金鑰儲存在舊版記憶體中,以便將 NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG 旗標傳遞至 NCryptFinalizeKey 函式,以便在金鑰完成時與 CryptoAPI 搭配使用。

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

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

另請參閱

NCryptDeleteKey

NCryptFinalizeKey

NCryptImportKey