Fungsi NtQueryInformationToken (ntifs.h)

Artikel
03/08/2023

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

Sintaks

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationToken(
  [in]  HANDLE                  TokenHandle,
  [in]  TOKEN_INFORMATION_CLASS TokenInformationClass,
  [out] PVOID                   TokenInformation,
  [in]  ULONG                   TokenInformationLength,
  [out] PULONG                  ReturnLength
);

Parameter

[in] TokenHandle

Tangani 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 dari dokumentasi Windows SDK.

[in] TokenInformationClass

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

[out] TokenInformation

Pointer ke buffer yang dialokasikan penelepon 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 identitas, panggilan ke NtQueryInformationToken gagal.
TokenOwner	Buffer menerima struktur TOKEN_OWNER yang berisi SID pemilik default 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 bukan nol 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 buffer TokenInformation . 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 adalah TokenDefaultDacl, dan tidak ada DACL default yang ditetapkan untuk token. Dalam hal ini, ReturnLength menerima nol.

ReturnLength tidak boleh NULL. Lihat Keterangan untuk informasi lebih lanjut.

Mengembalikan nilai

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

Menampilkan 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 di ReturnLength.
STATUS_ACCESS_VIOLATION	ReturnLength adalah NULL atau tidak dapat ditulis untuk menerima panjang aktual informasi yang ditujukkan oleh TokenInformation.
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.

Keterangan

Rutinitas NtQueryInformationToken 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 NtQueryInformationToken, struktur TOKEN_USER dikembalikan dalam buffer yang diarahkan oleh parameter TokenInformation . Buffer yang dikembalikan ini berisi struktur SID_AND_ATTRIBUTES dengan SID pengguna.

Karena sifat properti token (seperti pengguna token, grup utama token, hak istimewa, dll, di mana kontennya dapat bervariasi pada setiap token), ReturnLength tidak opsional; artinya, tidak boleh NULL. Ini karena SID adalah struktur panjang variabel sedangkan hak istimewa tertentu dapat ada dalam token tetapi tidak di token lain (jumlah hak istimewa dapat berbeda untuk setiap token). Pemanggil bertanggung jawab untuk terlebih dahulu mengkueri ukuran panjang yang diperlukan untuk mengalokasikan memori untuk mengakomodasi informasi token yang diminta sebelum melakukan kueri aktual. Meskipun demikian, pemanggil juga bertanggung jawab untuk memberikan variabel ReturnLength yang valid yang dapat ditulis dan bukan NULL. Pada skenario kasus NULL, fungsi meningkatkan pengecualian pelanggaran akses.

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

Catatan

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

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP
Target Platform	Universal
Header	ntifs.h (termasuk Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs, PowerIrpDDis