Fungsi NtQueryInformationToken (ntifs.h)

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 yang dijumlahkan yang mengidentifikasi jenis informasi yang akan diambil. Nilai yang mungkin untuk parameter ini tercantum di kolom Nilai TokenInformationClass dari tabel yang ditunjukkan dalam deskripsi parameter TokenInformation .

[out] TokenInformation

Arahkan 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 penelepon 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 ditujukan 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 menaikkan pengecualian pelanggaran akses.

Untuk informasi selengkapnya tentang keamanan dan kontrol akses, lihat dokumentasi tentang topik-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 menafsirkan 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

   
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

Lihat juga

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