Fungsi DuplicateTokenEx (securitybaseapi.h)

Artikel
03/15/2023

Fungsi DuplicateTokenEx membuat token akses baru yang menduplikasi token yang ada. Fungsi ini dapat membuat token utama atau token peniruan.

Sintaks

BOOL DuplicateTokenEx(
  [in]           HANDLE                       hExistingToken,
  [in]           DWORD                        dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES        lpTokenAttributes,
  [in]           SECURITY_IMPERSONATION_LEVEL ImpersonationLevel,
  [in]           TOKEN_TYPE                   TokenType,
  [out]          PHANDLE                      phNewToken
);

Parameter

[in] hExistingToken

Handel ke token akses yang dibuka dengan akses TOKEN_DUPLICATE.

[in] dwDesiredAccess

Menentukan hak akses yang diminta untuk token baru. Fungsi DuplicateTokenEx membandingkan hak akses yang diminta dengan daftar kontrol akses diskresi (DACL) token yang ada untuk menentukan hak mana yang diberikan atau ditolak. Untuk meminta hak akses yang sama dengan token yang ada, tentukan nol. Untuk meminta semua hak akses yang valid untuk pemanggil, tentukan MAXIMUM_ALLOWED.

Untuk daftar hak akses untuk token akses, lihat Hak Akses untuk Objek Access-Token.

[in, optional] lpTokenAttributes

Penunjuk ke struktur SECURITY_ATTRIBUTES yang menentukan deskriptor keamanan untuk token baru dan menentukan apakah proses anak dapat mewarisi token. Jika lpTokenAttributes adalah NULL, token mendapatkan pendeskripsi keamanan default dan handel tidak dapat diwariskan. Jika deskriptor keamanan berisi daftar kontrol akses sistem (SACL), token akan ACCESS_SYSTEM_SECURITY hak akses, bahkan jika tidak diminta di dwDesiredAccess.

Untuk mengatur pemilik dalam pendeskripsi keamanan untuk token baru, token proses pemanggil harus memiliki hak istimewa SE_RESTORE_NAME yang ditetapkan.

[in] ImpersonationLevel

Menentukan nilai dari enumerasi SECURITY_IMPERSONATION_LEVEL yang menunjukkan tingkat peniruan token baru.

[in] TokenType

Menentukan salah satu nilai berikut dari enumerasi TOKEN_TYPE .

Nilai	Makna
TokenPrimary	Token baru adalah token utama yang dapat Anda gunakan dalam fungsi CreateProcessAsUser .
TokenImpersonation	Token baru adalah token peniruan.

[out] phNewToken

Penunjuk ke variabel HANDLE yang menerima token baru.

Setelah Anda selesai menggunakan token baru, panggil fungsi CloseHandle untuk menutup handel token.

Menampilkan nilai

Jika fungsi berhasil, fungsi mengembalikan nilai bukan nol.

Jika fungsi gagal, fungsi akan mengembalikan nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Fungsi DuplicateTokenEx memungkinkan Anda membuat token utama yang dapat Anda gunakan dalam fungsi CreateProcessAsUser . Ini memungkinkan aplikasi server yang meniru klien untuk membuat proses yang memiliki konteks keamanan klien. Perhatikan bahwa fungsi DuplicateToken hanya dapat membuat token peniruan identitas, yang tidak valid untuk CreateProcessAsUser.

Berikut ini adalah skenario umum untuk menggunakan DuplicateTokenEx untuk membuat token utama. Aplikasi server membuat utas yang memanggil salah satu fungsi peniruan, seperti ImpersonateNamedPipeClient, untuk meniru klien. Utas peniruan kemudian memanggil fungsi OpenThreadToken untuk mendapatkan tokennya sendiri, yang merupakan token peniruan yang memiliki konteks keamanan klien. Utas menentukan token peniruan ini dalam panggilan ke DuplicateTokenEx, menentukan bendera TokenPrimary. Fungsi DuplicateTokenEx membuat token utama yang memiliki konteks keamanan klien.

Persyaratan


Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	securitybaseapi.h (termasuk Windows.h)
Pustaka	Advapi32.lib
DLL	Advapi32.dll