ZwOpenThreadTokenEx 函式 (ntifs.h)

發行項
02/26/2024

ZwOpenThreadTokenEx 例程會開啟與線程相關聯的存取令牌。

語法

NTSYSAPI NTSTATUS ZwOpenThreadTokenEx(
  [in]  HANDLE      ThreadHandle,
  [in]  ACCESS_MASK DesiredAccess,
  [in]  BOOLEAN     OpenAsSelf,
  [in]  ULONG       HandleAttributes,
  [out] PHANDLE     TokenHandle
);

參數

[in] ThreadHandle

處理要開啟其存取令牌的線程。句柄必須具有THREAD_QUERY_INFORMATION存取權。使用 NtCurrentThread 宏來指定目前的線程。

[in] DesiredAccess

ACCESS_MASK 結構，指定存取令牌的要求存取類型。這些要求的存取類型會與令牌的任意訪問控制清單 (DACL) 進行比較，以判斷授與或拒絕哪些訪問許可權。

[in] OpenAsSelf

布爾值，指定存取檢查是要針對呼叫 ZwOpenThreadTokenEx 的線程安全性內容，還是針對呼叫線程的進程安全性內容進行。

如果此參數為 FALSE，則會使用呼叫線程的安全性內容來執行存取檢查。如果線程正在模擬用戶端，此安全性內容可以是客戶端進程的安全性內容。如果此參數為 TRUE，則會使用呼叫線程進程的安全性內容進行存取檢查。

[in] HandleAttributes

所建立句柄的屬性。目前僅支援OBJ_KERNEL_HANDLE。如果呼叫端未在系統進程內容中執行，則必須為此參數指定OBJ_KERNEL_HANDLE。

[out] TokenHandle

呼叫端配置的變數指標，該變數會接收新開啟存取令牌的句柄。

傳回值

ZwOpenThreadTokenEx 會傳回STATUS_SUCCESS或適當的錯誤狀態。可能的錯誤狀態代碼包括：

傳回碼	Description
STATUS_ACCESS_DENIED	ThreadHandle 沒有THREAD_QUERY_INFORMATION存取權。
STATUS_CANT_OPEN_ANONYMOUS	用戶端要求 SecurityAnonymous 模擬層級。不過，無法開啟匿名令牌。如需詳細資訊，請參閱 SECURITY_IMPERSONATION_LEVEL。
STATUS_INVALID_HANDLE	ThreadHandle 不是有效的句柄。
STATUS_INVALID_PARAMETER	指定的 HandleAttributes 不包含OBJ_KERNEL_HANDLE。
STATUS_NO_TOKEN	嘗試開啟與目前未模擬用戶端之線程相關聯的令牌。
STATUS_OBJECT_TYPE_MISMATCH	ThreadHandle 不是線程句柄。

備註

ZwOpenThreadTokenEx 會開啟與線程相關聯的存取令牌，並傳回該令牌的句柄。

當客戶端進程已指定SECURITY_IMPERSONATION_LEVEL列舉類型的 SecurityIdentification 模擬層級時，OpenAsSelf 參數可讓伺服器進程開啟客戶端進程的存取令牌。如果沒有此參數，呼叫進程就無法使用用戶端的安全性內容開啟用戶端的存取令牌，因為無法使用 SecurityIdentification 模擬層級開啟執行層級物件。

呼叫 ZwOpenThreadTokenEx 取得的任何句柄最終都必須藉由呼叫 ZwClose 來釋出。

在系統進程以外的進程內容中執行的驅動程式例程必須設定 ZwOpenThreadTokenEx之 HandleAttributes 參數的 OBJ_KERNEL_HANDLE 屬性。這會限制 使用 ZwOpenThreadTokenEx 所傳回的句柄，以核心模式執行的進程。否則，進程可以在其中執行驅動程序的內容中存取句柄。

如需安全性和訪問控制的詳細資訊，請參閱適用於驅動程序開發人員的 Windows 安全性模型，以及 Windows SDK 中有關這些主題的檔。

注意

如果在使用者模式中呼叫 ZwOpenThreadTokenEx 函 式，您應該使用名稱 “NtOpenThreadTokenEx”，而不是 “ZwOpenThreadTokenEx”。

對於核心模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本在處理和解譯輸入參數的方式可能會有不同的行為。如需例程 NtXxx 和 ZwXxx 版本之間的關聯性詳細資訊，請參閱使用 Nt 和 Zw 版本的原生系統服務例程。

規格需求

需求	值
最低支援的用戶端	Windows XP
目標平台	Universal
標頭	ntifs.h (包含 Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 PowerIrpDDis (wdm)