NtQueryInformationToken 函式 (ntifs.h)

NtQueryInformationToken常式會擷取存取權杖的指定類型資訊。 呼叫進程必須具有適當的存取權限,才能取得資訊。

語法

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationToken(
  [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 值,指出權杖的模擬層級。 如果存取權杖不是模擬權杖, 則對 NtQueryInformationToken 的呼叫會失敗。
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 會收到零。

ReturnLength 不可以是 Null。 如需詳細資訊,請參閱。

傳回值

NtQueryInformationToken 會傳回STATUS_SUCCESS或適當的錯誤狀態。 可能的錯誤狀態碼包括:

傳回碼 描述
STATUS_ACCESS_DENIED TokenHandle 沒有必要的存取權。
STATUS_BUFFER_TOO_SMALL 要求之權杖資訊結構的大小大於 TokenInformationLengthReturnLength中會傳回所需的位元組數目。
STATUS_ACCESS_VIOLATION ReturnLength 為 Null 或無法寫入,以接收 TokenInformation所指資訊的實際長度。
STATUS_INVALID_HANDLE TokenHandle 不是有效的控制碼。
STATUS_INVALID_INFO_CLASS TokenInformationClass 不是有效的權杖資訊類別。
STATUS_OBJECT_TYPE_MISMATCH TokenHandle 不是權杖控制碼。

備註

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

由於權杖屬性的本質 (,例如權杖使用者、權杖主要群組、許可權等,其內容可能會因每個權杖而有所不同) , ReturnLength 不是選擇性的;也就是說,它不能是 Null。 這是因為 SID 是可變長度的結構,而特定許可權可以存在於權杖中,但不能存在於另一個 (許可權計數可以針對每個權杖) 不同。 呼叫端必須負責先查詢必要的長度大小,才能配置記憶體以容納所要求的權杖資訊,再執行實際查詢。 也就是說,呼叫端也必須負責提供可寫入且不可為 Null 的有效 ReturnLength 變數。 在 Null 案例中,函式會引發存取違規例外狀況。

如需安全性和存取控制的詳細資訊,請參閱 Windows SDK 中有關這些主題的檔。

注意

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

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

規格需求

   
最低支援的用戶端 Windows XP
目標平臺 Universal
標頭 ntifs.h (包含 Ntifs.h)
程式庫 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 合規性規則 HwStorPortProhibitedDIS、 PowerIrpDDis

另請參閱

ACL

IRP_MJ_CREATE

SECURITY_IMPERSONATION_LEVEL

SID

SID_AND_ATTRIBUTES

SeQueryInformationToken

TOKEN_DEFAULT_DACL

TOKEN_GROUPS

TOKEN_INFORMATION_CLASS

TOKEN_OWNER

TOKEN_PRIMARY_GROUP

TOKEN_PRIVILEGES

TOKEN_SOURCE

TOKEN_STATISTICS

TOKEN_TYPE

TOKEN_USER

ZwSetInformationToken