Fungsi CreateRestrictedToken (securitybaseapi.h)

Artikel
03/15/2023

Fungsi CreateRestrictedToken membuat token akses baru yang merupakan versi terbatas dari token akses yang ada. Token terbatas dapat menonaktifkan pengidentifikasi keamanan (SID), hak istimewa yang dihapus, dan daftar membatasi SID. Untuk informasi selengkapnya, lihat Token Terbatas.

Sintaks

BOOL CreateRestrictedToken(
  [in]           HANDLE               ExistingTokenHandle,
  [in]           DWORD                Flags,
  [in]           DWORD                DisableSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToDisable,
  [in]           DWORD                DeletePrivilegeCount,
  [in, optional] PLUID_AND_ATTRIBUTES PrivilegesToDelete,
  [in]           DWORD                RestrictedSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToRestrict,
  [out]          PHANDLE              NewTokenHandle
);

Parameter

[in] ExistingTokenHandle

Handel ke token utama atau peniruan. Token juga dapat menjadi token terbatas. Handel harus memiliki akses TOKEN_DUPLICATE ke token.

[in] Flags

Menentukan opsi hak istimewa tambahan. Parameter ini bisa nol atau kombinasi dari nilai berikut.

Nilai	Makna
DISABLE_MAX_PRIVILEGE 0x1	Menonaktifkan semua hak istimewa dalam token baru kecuali hak istimewa SeChangeNotifyPrivilege . Jika nilai ini ditentukan, parameter DeletePrivilegeCount dan PrivilegesToDelete diabaikan.
SANDBOX_INERT 0x2	Jika nilai ini digunakan, sistem tidak memeriksa aturan AppLocker atau menerapkan Kebijakan Pembatasan Perangkat Lunak. Untuk AppLocker, bendera ini menonaktifkan pemeriksaan untuk keempat koleksi aturan: Executable, Windows Installer, Script, dan DLL. Saat membuat program penyiapan yang harus menjalankan DLL yang diekstrak selama penginstalan, gunakan bendera SAFER_TOKEN_MAKE_INERT dalam fungsi SaferComputeTokenFromLevel . Token dapat dikueri untuk keberadaan bendera ini dengan menggunakan GetTokenInformation. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Pada sistem dengan KB2532445 terinstal, pemanggil harus berjalan sebagai LocalSystem atau TrustedInstaller atau sistem mengabaikan bendera ini. Untuk informasi selengkapnya, lihat "Anda dapat menghindari aturan AppLocker dengan menggunakan makro Office di komputer yang menjalankan Windows 7 atau Windows Server 2008 R2" di Pangkalan Pengetahuan Bantuan dan Dukungan di http://support.microsoft.com/kb/2532445. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: AppLocker tidak didukung. AppLocker diperkenalkan di Windows 7 dan Windows Server 2008 R2.
LUA_TOKEN 0x4	Token baru adalah token LUA. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
WRITE_RESTRICTED 0x8	Token baru berisi pembatasan SID yang hanya dipertimbangkan saat mengevaluasi akses tulis. Windows XP dengan SP2 dan yang lebih baru: Nilai konstanta ini 0x4. Agar aplikasi kompatibel dengan Windows XP dengan SP2 dan sistem operasi yang lebih baru, aplikasi harus meminta sistem operasi dengan memanggil fungsi GetVersionEx untuk menentukan nilai mana yang harus digunakan. Windows Server 2003 dan Windows XP dengan SP1 dan yang lebih lama: Nilai ini tidak didukung.

[in] DisableSidCount

Menentukan jumlah entri dalam array SidsToDisable .

[in, optional] SidsToDisable

Penunjuk ke array struktur SID_AND_ATTRIBUTES yang menentukan SID khusus tolak dalam token terbatas. Sistem menggunakan SID khusus tolak untuk menolak akses ke objek yang dapat diamankan. Tidak adanya SID khusus tolak tidak mengizinkan akses.

Menonaktifkan SID mengaktifkan SE_GROUP_USE_FOR_DENY_ONLY dan menonaktifkan SE_GROUP_ENABLED dan SE_GROUP_ENABLED_BY_DEFAULT. Semua atribut lainnya diabaikan.

Atribut tolak-saja berlaku untuk kombinasi SID token yang ada, termasuk SID pengguna dan SID grup yang memiliki atribut SE_GROUP_MANDATORY. Untuk mendapatkan SID yang terkait dengan token yang ada, gunakan fungsi GetTokenInformation dengan bendera TokenUser dan TokenGroups. Fungsi ini mengabaikan SID apa pun dalam array yang tidak juga ditemukan dalam token yang ada.

Fungsi mengabaikan anggota Atribut dari struktur SID_AND_ATTRIBUTES .

Parameter ini bisa NULL jika tidak ada SID yang akan dinonaktifkan.

[in] DeletePrivilegeCount

Menentukan jumlah entri dalam array PrivilegesToDelete .

[in, optional] PrivilegesToDelete

Penunjuk ke array struktur LUID_AND_ATTRIBUTES yang menentukan hak istimewa untuk dihapus dalam token terbatas.

Fungsi GetTokenInformation dapat digunakan dengan bendera TokenPrivileges untuk mengambil hak istimewa yang dipegang oleh token yang ada. Fungsi mengabaikan hak istimewa apa pun dalam array yang tidak dipegang oleh token yang ada.

Fungsi ini mengabaikan anggota Atribut dari struktur LUID_AND_ATTRIBUTES .

Parameter ini bisa NULL jika Anda tidak ingin menghapus hak istimewa apa pun.

Jika program panggilan melewati terlalu banyak hak istimewa dalam array ini, CreateRestrictedToken mengembalikan ERROR_INVALID_PARAMETER.

[in] RestrictedSidCount

Menentukan jumlah entri dalam array SidsToRestrict .

[in, optional] SidsToRestrict

Penunjuk ke array struktur SID_AND_ATTRIBUTES yang menentukan daftar SID pembatasan untuk token baru. Jika token yang ada adalah token terbatas, daftar membatasi SID untuk token baru adalah persimpangan array ini dan daftar membatasi SID untuk token yang ada. Tidak ada pemeriksaan yang dilakukan untuk menghapus SID duplikat yang ditempatkan pada parameter SidsToRestrict . SID duplikat memungkinkan token terbatas memiliki informasi redundan dalam daftar SID pembatasan.

Anggota Atribut dari struktur SID_AND_ATTRIBUTES harus nol. Membatasi SID selalu diaktifkan untuk pemeriksaan akses.

Parameter ini bisa NULL jika Anda tidak ingin menentukan SID pembatasan apa pun.

[out] NewTokenHandle

Penunjuk ke variabel yang menerima handel ke token terbatas baru. Handel ini memiliki hak akses yang sama dengan ExistingTokenHandle. Token baru adalah jenis yang sama, primer atau peniruan identitas, seperti token yang ada. Handel yang dikembalikan di NewTokenHandle dapat diduplikasi.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Fungsi CreateRestrictedToken dapat membatasi token dengan cara berikut:

Terapkan atribut tolak-saja ke SID dalam token sehingga tidak dapat digunakan untuk mengakses objek aman. Untuk informasi selengkapnya tentang atribut tolak-saja, lihat Atribut SID dalam Token Akses.
Hapus hak istimewa dari token.
Tentukan daftar SID pembatasan, yang digunakan sistem saat memeriksa akses token ke objek yang dapat diamankan. Sistem melakukan dua pemeriksaan akses: satu menggunakan SID yang diaktifkan token, dan yang lain menggunakan daftar membatasi SID. Akses diberikan hanya jika kedua pemeriksaan akses mengizinkan hak akses yang diminta.

Anda dapat menggunakan token terbatas dalam fungsi CreateProcessAsUser untuk membuat proses yang memiliki hak akses dan hak istimewa terbatas. Jika proses memanggil CreateProcessAsUser menggunakan versi terbatas dari tokennya sendiri, proses panggilan tidak perlu memiliki hak istimewa SE_ASSIGNPRIMARYTOKEN_NAME.

Anda dapat menggunakan token terbatas dalam fungsi ImpersonateLoggedOnUser .

Hati Aplikasi yang menggunakan token terbatas harus menjalankan aplikasi terbatas pada desktop selain desktop default. Ini diperlukan untuk mencegah serangan oleh aplikasi terbatas, menggunakan SendMessage atau PostMessage, untuk aplikasi yang tidak dibatasi pada desktop default. Jika perlu, beralih antar desktop untuk tujuan aplikasi Anda.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	securitybaseapi.h (termasuk Windows.h)
Pustaka	Advapi32.lib
DLL	Advapi32.dll