NCryptTranslateHandle 函式 (ncrypt.h)

NCryptTranslateHandle 函式會將 CryptoAPI 句柄轉譯成 CNG 密鑰句柄。

語法

SECURITY_STATUS NCryptTranslateHandle(
  [out, optional] NCRYPT_PROV_HANDLE *phProvider,
  [out]           NCRYPT_KEY_HANDLE  *phKey,
  [in]            HCRYPTPROV         hLegacyProv,
  [in, optional]  HCRYPTKEY          hLegacyKey,
  [in, optional]  DWORD              dwLegacyKeySpec,
  [in]            DWORD              dwFlags
);

參數

[out, optional] phProvider

NCRYPT_PROV_HANDLE變數的指標，該變數會接收擁有 phKey 參數中放置 CNG 金鑰之 CNG 金鑰的 CNG 金鑰儲存提供者句柄。 如果不需要此句柄，這個參數可以是 NULL 。

[out] phKey

接收 CNG 金鑰句柄 之NCRYPT_KEY_HANDLE 變數的指標。

[in] hLegacyProv

CryptoAPI 提供者的句柄，其中包含要轉譯的密鑰。 此函式會轉譯此提供者中容器中的 CryptoAPI 金鑰。

[in, optional] hLegacyKey

用來協助判斷所傳回密鑰之金鑰規格的 CryptoAPI 金鑰句柄。 如果 dwLegacyKeySpec 參數包含零以外的值，則會忽略此參數。

如果 hLegacyKey 為 NULL 且 dwLegacyKeySpec 為零，此函式會嘗試從 hLegacyProv 句柄判斷密鑰規格。

[in, optional] dwLegacyKeySpec

指定金鑰的金鑰規格。 這可以是下列其中一個值。

值 意義
0
 索引鍵不是下列任何類型。
AT_KEYEXCHANGE
1
 金鑰是金鑰交換金鑰。
AT_SIGNATURE
2
 金鑰是簽章金鑰。
 

如果 hLegacyKey 為 NULL 且 dwLegacyKeySpec 為零，此函式會嘗試從 hLegacyProv 句柄判斷密鑰規格。

[in] dwFlags

一組旗標，可修改此函式的行為。 此函式未定義任何旗標。

傳回值

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

可能的傳回碼包括但不限於下列專案。

傳回碼 Description
ERROR_SUCCESS
 函式成功。
NTE_BAD_FLAGS
 dwFlags 參數包含無效的值。
NTE_INVALID_PARAMETER
 一或多個參數無效。
NTE_NO_MEMORY
 發生記憶體配置失敗。

備註

這是協助程式函式，旨在協助目前使用 CryptoAPI 的應用程式和系統元件，以正常轉換至使用 CNG。

只有當 CNG 金鑰儲存提供者註冊的名稱或別名與 hLegacyProv 參數所參考的密碼編譯服務提供者名稱 (CSP) 相同時，此函式才會成功。

此函式會執行下列步驟，將 CSP 句柄轉譯成 CNG 密鑰句柄：

  1. 從 hLegacyProv 句柄取得 CSP 的名稱。
  2. 開啟名稱或別名與 CSP 名稱相同的 CNG 提供者。
  3. 取得 CSP 中目前金鑰容器的名稱。
  4. 取得 CryptoAPI 金鑰、將它轉譯成 CNG 金鑰，然後在 phKey 參數中傳回它。
服務不得從它的 StartService 函式呼叫此函式。 如果服務從其 StartService 函式呼叫此函式，可能會發生死結，而且服務可能會停止回應。

規格需求

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