Share via

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 函式。 這也會釋放句柄。 因此，應用程式可能會將句柄傳遞至 NCryptFreeObject 或 NCryptDeleteKey，但不能同時傳遞兩者。

[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，作業將會產生軟體隔離密鑰。 (*請參閱備註)

傳回值

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

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

傳回碼 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