Fungsi NtDuplicateToken (ntifs.h)
Fungsi NtDuplicateToken membuat handel ke token akses baru yang menduplikasi token yang ada. Fungsi ini dapat membuat token utama atau token peniruan.
Sintaks
__kernel_entry NTSYSCALLAPI NTSTATUS NtDuplicateToken(
[in] HANDLE ExistingTokenHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in] BOOLEAN EffectiveOnly,
[in] TOKEN_TYPE TokenType,
[out] PHANDLE NewTokenHandle
);
Parameter
[in] ExistingTokenHandle
Handel ke token akses yang ada yang dibuka dengan hak akses TOKEN_DUPLICATE. Parameter ini diperlukan dan tidak boleh NULL.
[in] DesiredAccess
Bitmask yang menentukan hak akses yang diminta untuk token baru. NtDuplicateToken membandingkan hak akses yang diminta dengan daftar kontrol akses diskresi (DACL) token yang ada untuk menentukan hak mana yang diberikan atau ditolak ke token baru. Untuk meminta hak akses yang sama dengan token yang ada, tentukan nol. Untuk meminta semua hak akses yang valid untuk pemanggil, tentukan MAXIMUM_ALLOWED. Parameter ini bersifat opsional dan dapat berupa nol, MAXIMUM_ALLOWED, atau kombinasi BITWISE OR dari satu atau beberapa nilai berikut:
| Nilai | Makna |
|---|---|
| DELETE | Diperlukan untuk menghapus objek. |
| READ_CONTROL | Diperlukan untuk membaca DACL dan informasi kepemilikan untuk objek . Untuk akses ke daftar kontrol akses sistem (SACL), lihat ACCESS_SYSTEM_SECURITY nanti dalam tabel ini. |
| WRITE_DAC | Diperlukan untuk mengubah informasi DACL untuk objek. |
| WRITE_OWNER | Diperlukan untuk mengubah informasi kepemilikan di deskriptor keamanan objek (SECURITY_DESCRIPTOR). |
| ACCESS_SYSTEM_SECURITY | Diperlukan untuk mendapatkan atau mengatur SACL dalam ACL objek. Sistem operasi memberikan hak ini ke token baru hanya jika hak istimewa SE_SECURITY_NAME diaktifkan dalam token akses utas panggilan. |
| STANDARD_RIGHTS_READ | Saat ini didefinisikan sama dengan READ_CONTROL. |
| STANDARD_RIGHTS_WRITE | Saat ini didefinisikan sama dengan READ_CONTROL. |
| STANDARD_RIGHTS_EXECUTE | Saat ini didefinisikan sama dengan READ_CONTROL. |
| STANDARD_RIGHTS_REQUIRED | Menggabungkan akses DELETE, READ_CONTROL, WRITE_DAC, dan WRITE_OWNER. |
| STANDARD_RIGHTS_ALL | Menggabungkan akses DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER, dan SYNCHRONIZE. Namun, nilai SYNCHRONIZE tidak berlaku untuk objek token. Dengan demikian, STANDARD_RIGHTS_ALL memiliki fungsi yang setara dengan STANDARD_RIGHTS_REQUIRED. |
| TOKEN_ADJUST_DEFAULT | Diperlukan untuk mengubah pemilik default, grup utama, atau DACL token akses. |
| TOKEN_ADJUST_GROUPS | Diperlukan untuk menyesuaikan atribut grup dalam token akses. |
| TOKEN_ADJUST_PRIVILEGES | Diperlukan untuk mengaktifkan atau menonaktifkan hak istimewa dalam token akses. |
| TOKEN_ADJUST_SESSIONID | Diperlukan untuk menyesuaikan ID sesi (SID) token akses. Sistem operasi memberikan hak ini ke token baru hanya jika hak istimewa SE_TCB_NAME diaktifkan dalam token akses utas panggilan. |
| TOKEN_ASSIGN_PRIMARY | Diperlukan untuk melampirkan token utama ke proses. Sistem operasi memberikan hak ini ke token baru hanya jika hak istimewa SE_ASSIGNPRIMARYTOKEN_NAME diaktifkan dalam token akses utas panggilan. |
| TOKEN_DUPLICATE | Diperlukan untuk menduplikasi token akses. Perhatikan bahwa token ExistingTokenHandle yang diberikan harus berisi hak ini agar berhasil menggunakan rutinitas ini. |
| TOKEN_EXECUTE | Menggabungkan STANDARD_RIGHTS_EXECUTE dan TOKEN_IMPERSONATE. |
| TOKEN_IMPERSONATE | Diperlukan untuk melampirkan token akses peniruan ke proses. |
| TOKEN_QUERY | Diperlukan untuk mengkueri token akses. |
| TOKEN_QUERY_SOURCE | Diperlukan untuk mengkueri sumber token akses. |
| TOKEN_READ | Menggabungkan STANDARD_RIGHTS_READ dan TOKEN_QUERY. |
| TOKEN_WRITE | Menggabungkan STANDARD_RIGHTS_WRITE, TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS, dan TOKEN_ADJUST_DEFAULT. |
| TOKEN_ALL_ACCESS | Menggabungkan semua kemungkinan izin akses token untuk token. |
Untuk informasi tambahan, lihat Hak Akses untuk Objek Access-Token. Perhatikan bahwa token akses tidak mendukung hak SYNCHRONIZE.
[in] ObjectAttributes
Arahkan ke struktur OBJECT_ATTRIBUTES yang menjelaskan properti yang diminta untuk token baru. Parameter ObjectAttributes bersifat opsional dan dapat berupa NULL. Jika parameter ObjectAttributes adalah NULL atau jika anggota SecurityDescriptor dari struktur yang ditunjukkan oleh parameter ObjectAttributes adalah NULL, token baru menerima pendeskripsi keamanan default dan handel token baru tidak dapat diwarisi. Dalam hal ini, deskriptor keamanan default ini dibuat dari grup pengguna, grup utama, dan informasi DACL yang disimpan dalam token pemanggil.
Ketika parameter TokenType diatur ke TokenImpersonation:
- Parameter ObjectAttributes dapat digunakan untuk menentukan tingkat peniruan token baru. Ini dapat dicapai dengan mengatur ObjectAttributes-SecurityQualityOfService.ImpersonationLevel >ke nilai enumerasi SECURITY_IMPERSONATION_LEVEL yang sesuai. Untuk informasi selengkapnya, lihat SECURITY_QUALITY_OF_SERVICE.
- Jika token yang ada adalah token peniruan identitas dan parameter ObjectAttributes tidak memberikan informasi peniruan identitas, tingkat peniruan token baru diatur ke tingkat peniruan token yang ada.
- Jika token yang ada adalah token utama dan tidak ada informasi tingkat peniruan yang disediakan, token peniruan baru akan memiliki tingkat peniruan SECURITY_IMPERSONATION_LEVEL .
[in] EffectiveOnly
Nilai Boolean yang menunjukkan apakah seluruh token yang ada harus diduplikasi ke dalam token baru atau hanya bagian token yang efektif (saat ini diaktifkan). Jika diatur ke TRUE, hanya bagian token sumber yang diaktifkan saat ini yang akan diduplikasi. Jika diatur ke FALSE, seluruh token yang ada akan diduplikasi. Ini menyediakan sarana bagi penelepon subsistem yang dilindungi untuk membatasi grup dan hak istimewa opsional mana yang tersedia untuk subsistem yang dilindungi. Misalnya, jika EffectiveOnlyTRUE, pemanggil dapat menduplikasi token tetapi menghapus grup Administrator dan hak SeTcbPrivilege. Token yang dihasilkan kemudian dapat diteruskan ke proses anak (CreateProcessAsUser), yang akan membatasi apa yang dapat dilakukan proses anak. Parameter ini diperlukan.
[in] TokenType
Menentukan salah satu nilai berikut dari enumerasi TOKEN_TYPE .
| Nilai | Makna |
|---|---|
| TokenPrimary | Token baru adalah token utama. Jika token yang ada adalah token peniruan identitas, token peniruan yang ada harus memiliki tingkat peniruan (sebagaimana disediakan oleh parameter ObjectAttributes ) dari SecurityImpersonation atau SecurityDelegation. Jika tidak, NtDuplicateToken mengembalikan STATUS_BAD_IMPERSONATION_LEVEL dikembalikan. |
| TokenImpersonation | Token baru adalah token peniruan. Jika token yang ada adalah token peniruan identitas, tingkat peniruan yang diminta (sebagaimana disediakan oleh parameter ObjectAttributes ) dari token baru tidak boleh lebih besar dari tingkat peniruan dari token yang ada. Jika tidak, NtDuplicateToken mengembalikan STATUS_BAD_IMPERSONATION_LEVEL. |
Parameter TokenType diperlukan dan tidak boleh NULL.
[out] NewTokenHandle
Penunjuk ke variabel yang dialokasikan pemanggil, dari jenis HANDLE, yang menerima handel ke token baru. Parameter ini diperlukan dan tidak boleh NULL.
Mengembalikan nilai
NtDuplicateToken mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan kode pengembalian kesalahan meliputi yang berikut ini:
| Menampilkan kode | Deskripsi |
|---|---|
| STATUS_ACCESS_VIOLATION | Terjadi pelanggaran akses memori. Misalnya, jika mode sebelumnya adalah mode pengguna dan memori mode pengguna yang tidak valid disediakan, NtDuplicateToken mengembalikan STATUS_ACCESS_VIOLATION. |
| STATUS_INSUFFICIENT_RESOURCES | Memori yang cukup tidak dapat dialokasikan untuk menduplikasi token baru. |
| STATUS_INVALID_PARAMETER | Parameter yang tidak valid terdeteksi. |
| STATUS_BAD_IMPERSONATION_LEVEL | Tingkat peniruan yang diminta untuk token baru lebih besar dari tingkat peniruan token yang ada. |
| STATUS_ACCESS_DENIED | NtDuplicateToken tidak dapat mengakses ExistingTokenHandle. Ini akan terjadi jika token yang ada tidak memiliki hak akses TOKEN_DUPLICATE. |
| STATUS_INVALID_HANDLE | ExistingTokenHandle mengacu pada handel yang tidak valid. |
Keterangan
Jika tidak ada informasi tingkat peniruan yang disediakan oleh parameter ObjectAttributes , tingkat peniruan token yang ada akan digunakan untuk token baru.
Sehubungan dengan struktur yang ditunjukkan oleh parameter ObjectAttributes opsional, anggota SecurityQualityOfServicedari OBJECT_ATTRIBUTES menunjuk ke struktur jenis SECURITY_QUALITY_OF_SERVICE. Lihat SECURITY_QUALITY_OF_SERVICE untuk informasi tentang anggota struktur ini.
Anggota SecurityQualityOfService harus diatur setelah memanggil makro InitializeObjectAttributes karena InitializeObjectAttributes saat ini mengatur SecurityQualityOfService ke NULL.
Untuk informasi tentang analog mode pengguna NtDuplicateToken, lihat DuplicateTokenEx dalam dokumentasi Windows SDK.
Setelah Anda selesai menggunakan token baru, panggil fungsi NtClose untuk menutup handel token.
Jika panggilan ke fungsi NtDuplicateToken terjadi dalam mode pengguna, Anda harus menggunakan nama "NtDuplicateToken" alih-alih "NtDuplicateToken".
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 2000 |
| Target Platform | Universal |
| Header | ntifs.h (termasuk Ntifs.h, FltKernel.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Aturan kepatuhan DDI | HwStorPortProhibitedDDIs, PowerIrpDDis |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk