Fungsi ZwQueryInformationToken (ntifs.h)

Artikel
12/22/2024

Rutinitas ZwQueryInformationToken mengambil jenis informasi tertentu tentang token akses. Proses panggilan harus memiliki hak akses yang sesuai untuk mendapatkan informasi.

Sintaksis

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

Parameter

[in] TokenHandle

Menangani token akses dari mana informasi akan diambil. Jika TokenInformationClass diatur ke TokenSource, handel harus memiliki akses TOKEN_QUERY_SOURCE. Untuk semua nilai TokenInformationClass lainnya, handel harus memiliki akses TOKEN_QUERY. Untuk informasi selengkapnya tentang hak akses untuk objek token akses, lihat bagian Keamanan dokumentasi Windows SDK.

[in] TokenInformationClass

Nilai dari jenis enumerasi TOKEN_INFORMATION_CLASS yang mengidentifikasi jenis informasi yang akan diambil. Nilai yang mungkin untuk parameter ini tercantum dalam kolom TokenInformationClass Value tabel yang diperlihatkan dalam deskripsi parameter TokenInformation .

[out] TokenInformation

Penunjuk ke buffer yang dialokasikan pemanggil yang menerima informasi yang diminta tentang token. Struktur yang dimasukkan ke dalam buffer ini tergantung pada nilai TokenInformationClass, seperti yang ditunjukkan dalam tabel berikut. Semua struktur harus diselaraskan pada batas 32-bit.

Nilai TokenInformationClass	Efek pada buffer TokenInformation
TokenDefaultDacl	Buffer menerima struktur TOKEN_DEFAULT_DACL yang berisi DACL default untuk objek yang baru dibuat.
TokenGroups	Buffer menerima struktur TOKEN_GROUPS yang berisi akun grup yang terkait dengan token.
TokenImpersonationLevel	Buffer menerima nilai SECURITY_IMPERSONATION_LEVEL yang menunjukkan tingkat peniruan token. Jika token akses bukan token peniruan, panggilan ke ZwQueryInformationToken gagal.
TokenOwner	Buffer menerima struktur TOKEN_OWNER yang berisi pemilik default SID untuk objek yang baru dibuat.
TokenPrimaryGroup	Buffer menerima struktur TOKEN_PRIMARY_GROUP yang berisi SID grup utama default untuk objek yang baru dibuat.
TokenPrivileges	Buffer menerima struktur TOKEN_PRIVILEGES yang berisi hak istimewa token.
TokenSessionId	Buffer menerima nilai 32-bit yang menentukan pengidentifikasi sesi Layanan Terminal yang terkait dengan token. Jika token dikaitkan dengan sesi konsol Terminal Server, pengidentifikasi sesi adalah nol. Pengidentifikasi sesi nonzero menunjukkan sesi klien Layanan Terminal. Di lingkungan Layanan non-Terminal, pengidentifikasi sesi adalah nol.
TokenSource	Buffer menerima struktur TOKEN_SOURCE yang berisi sumber token. TOKEN_QUERY_SOURCE akses diperlukan untuk mengambil informasi ini.
TokenStatistics	Buffer menerima struktur TOKEN_STATISTICS yang berisi berbagai statistik token.
TokenType	Buffer menerima nilai TOKEN_TYPE yang menunjukkan apakah token adalah token utama atau peniruan.
TokenUser	Buffer menerima struktur TOKEN_USER yang berisi akun pengguna token.

[in] TokenInformationLength

Panjang, dalam byte, dari buffer TokenInformation yang dialokasikan pemanggil.

[out] ReturnLength

Penunjuk ke variabel yang dialokasikan pemanggil yang menerima panjang aktual, dalam byte, dari informasi yang dikembalikan dalam tokenInformation buffer. Jika salah satu kondisi berikut ini benar, tidak ada data yang dikembalikan dalam buffer TokenInformation :

Ukuran struktur informasi token yang diminta lebih besar dari TokenInformationLength. Dalam hal ini, ReturnLength menerima jumlah byte aktual yang diperlukan untuk menyimpan informasi yang diminta.
Nilai TokenInformationClass TokenDefaultDacl, dan tidak ada DACL default yang ditetapkan untuk token. Dalam hal ini, ReturnLength menerima nol.

Mengembalikan nilai

ZwQueryInformationToken mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai. Kemungkinan kode status kesalahan meliputi yang berikut ini:

Mengembalikan kode	Deskripsi
STATUS_ACCESS_DENIED	TokenHandle tidak memiliki akses yang diperlukan.
STATUS_BUFFER_TOO_SMALL	Ukuran struktur informasi token yang diminta lebih besar dari TokenInformationLength. Jumlah byte yang diperlukan dikembalikan dalam ReturnLength.
STATUS_INVALID_HANDLE	TokenHandle bukan handel yang valid.
STATUS_INVALID_INFO_CLASS	TokenInformationClass bukan kelas informasi token yang valid.
STATUS_OBJECT_TYPE_MISMATCH	TokenHandle bukan handel token.

Komentar

Rutinitas ZwQueryInformationToken dapat digunakan oleh sistem file atau driver filter sistem file untuk menentukan SID pemanggil yang memulai permintaan selama pemrosesan IRP_MJ_CREATE. Jika TokenUser ditentukan untuk parameter TokenInformationClass yang diteruskan ke ZwQueryInformationToken , struktur TOKEN_USER dikembalikan dalam buffer yang ditujukkan oleh parameter TokenInformation . Buffer yang dikembalikan ini berisi struktur SID_AND_ATTRIBUTES dengan pengguna SID.

Untuk informasi selengkapnya tentang keamanan dan kontrol akses, lihat model keamanan Windows untuk pengembang driver dan dokumentasi tentang topik ini di Windows SDK.

Nota

Jika panggilan ke fungsi ZwQueryInformationToken terjadi dalam mode pengguna, Anda harus menggunakan nama "NtQueryInformationToken" alih-alih "ZwQueryInformationToken".

Untuk panggilan dari driver mode kernel, NtXxx dan ZwXxx versi rutin Windows Native System Services dapat berperilaku berbeda dalam cara mereka menangani dan menginterpretasikan parameter input. Untuk informasi selengkapnya tentang hubungan antara NtXxx dan versi ZwXxx rutin, lihat Menggunakan Versi Nt dan Zw dari Rutinitas Layanan Sistem Asli.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows XP
Platform Target	Universal
Header	ntifs.h (termasuk Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
aturan kepatuhan DDI	HwStorPortProhibitedDIs (storport), PowerIrpDDis(wdm)