ZwQueryInformationToken 函式 (ntifs.h)

發行項
03/01/2024

ZwQueryInformationToken 例程會擷取存取令牌的指定類型資訊。呼叫進程必須具有適當的訪問許可權，才能取得資訊。

語法

NTSYSAPI NTSTATUS ZwQueryInformationToken(
  [in]  HANDLE                  TokenHandle,
  [in]  TOKEN_INFORMATION_CLASS TokenInformationClass,
  [out] PVOID                   TokenInformation,
  [in]  ULONG                   TokenInformationLength,
  [out] PULONG                  ReturnLength
);

參數

[in] TokenHandle

要從中擷取資訊的存取令牌句柄。如果 TokenInformationClass 設定為 TokenSource，句柄必須具有TOKEN_QUERY_SOURCE存取權。對於所有其他 TokenInformationClass 值，句柄必須具有TOKEN_QUERY存取權。如需存取令牌對象訪問許可權的詳細資訊，請參閱 Windows SDK 檔的安全性一節。

[in] TokenInformationClass

來自 TOKEN_INFORMATION_CLASS 列舉型別的值，識別要擷取的信息類型。此參數的可能值列在 TokenInformationClass Value 數據行中，如 TokenInformation 參數的描述所示。

[out] TokenInformation

呼叫端配置的緩衝區指標，可接收令牌的要求資訊。放入此緩衝區的結構取決於 TokenInformationClass 的值，如下表所示。所有結構都必須對齊 32 位界限。

TokenInformationClass 值	對 TokenInformation 緩衝區的影響
TokenDefaultDacl	緩衝區會收到包含新建立物件之預設 DACL的TOKEN_DEFAULT_DACL結構。
TokenGroups	緩衝區會收到包含與令牌相關聯之群組帳戶的TOKEN_GROUPS 結構。
TokenImpersonationLevel	緩衝區會收到 SECURITY_IMPERSONATION_LEVEL 值，指出令牌的模擬層級。如果存取令牌不是模擬令牌，則對 ZwQueryInformationToken 的呼叫會失敗。
TokenOwner	緩衝區會收到包含新建立物件之預設擁有者 SID的TOKEN_OWNER結構。
TokenPrimaryGroup	緩衝區會接收 TOKEN_PRIMARY_GROUP 結構，其中包含新建立對象的預設主要群組 SID。
TokenPrivileges	緩衝區會收到包含令牌許可權的TOKEN_PRIVILEGES 結構。
TokenSessionId	緩衝區會收到 32 位值，指定與令牌相關聯的終端機服務會話標識碼。如果令牌與終端機伺服器控制台會話相關聯，會話標識碼為零。非零會話標識元表示終端機服務用戶端會話。在非終端機服務環境中，會話標識符為零。
TokenSource	緩衝區會接收包含令牌來源的TOKEN_SOURCE 結構。需要TOKEN_QUERY_SOURCE存取權才能擷取此資訊。
TokenStatistics	緩衝區會接收包含各種令牌統計數據的TOKEN_STATISTICS 結構。
TokenType	緩衝區會收到 TOKEN_TYPE 值，指出令牌是主要或模擬令牌。
TokenUser	緩衝區會接收包含令牌用戶帳戶的TOKEN_USER 結構。

[in] TokenInformationLength

呼叫端配置的 TokenInformation 緩衝區的長度，以位元組為單位。

[out] ReturnLength

呼叫端配置的變數指標，該變數會接收 TokenInformation 緩衝區中傳回之資訊的實際長度，以位元組為單位。如果下列任一條件為 true， 則 TokenInformation 緩衝區中不會傳回任何數據：

要求之令牌信息結構的大小大於 TokenInformationLength。在此情況下， ReturnLength 會接收儲存要求資訊所需的實際位元元組數目。
TokenInformationClass 的值是 TokenDefaultDacl，而且沒有為令牌建立的預設 DACL。在此情況下， ReturnLength 會收到零。

傳回值

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

傳回碼	Description
STATUS_ACCESS_DENIED	TokenHandle 沒有必要的存取權。
STATUS_BUFFER_TOO_SMALL	要求之令牌信息結構的大小大於 TokenInformationLength。 ReturnLength 中會傳回所需的位元組數目。
STATUS_INVALID_HANDLE	TokenHandle 不是有效的句柄。
STATUS_INVALID_INFO_CLASS	TokenInformationClass 不是有效的令牌信息類別。
STATUS_OBJECT_TYPE_MISMATCH	TokenHandle 不是令牌句柄。

備註

文件系統或文件系統篩選驅動程式可以使用 ZwQueryInformationToken 例程，以判斷在IRP_MJ_CREATE處理期間起始要求的呼叫端 SID。如果針對傳遞至 ZwQueryInformationToken 的 TokenInformationClass 參數指定 TokenUser，則會在 TokenInformation 參數指向的緩衝區中傳回TOKEN_USER結構。這個傳回的緩衝區包含具有使用者 SID的SID_AND_ATTRIBUTES結構。

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

注意

如果 對 ZwQueryInformationToken 函式的呼叫發生在使用者模式中，您應該使用名稱 “NtQueryInformationToken” 而不是 “ZwQueryInformationToken”。

對於核心模式驅動程式的呼叫，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)