Fungsi PsImpersonateClient (ntifs.h)

Artikel
02/29/2024

Rutinitas PsImpersonateClient menyebabkan utas server meniru klien.

Sintaks

NTSTATUS PsImpersonateClient(
  [in, out] PETHREAD                     Thread,
  [in]      PACCESS_TOKEN                Token,
  [in]      BOOLEAN                      CopyOnOpen,
  [in]      BOOLEAN                      EffectiveOnly,
  [in]      SECURITY_IMPERSONATION_LEVEL ImpersonationLevel
);

Parameter

[in, out] Thread

Arahkan ke utas server yang akan meniru klien.

[in] Token

Arahkan ke token yang akan ditetapkan sebagai token peniruan. Token ini dapat menjadi token utama atau token peniruan. Atur ke NULL untuk mengakhiri peniruan.

[in] CopyOnOpen

Menentukan apakah token dapat dibuka secara langsung. Atur ke TRUE untuk menentukan bahwa token tidak dapat dibuka secara langsung. Dalam hal ini, token harus diduplikasi, dan token duplikat yang digunakan sebagai gantinya. Atur ke FALSE untuk memungkinkan token dibuka secara langsung.

[in] EffectiveOnly

Atur ke FALSE untuk memungkinkan server mengaktifkan grup dan hak istimewa yang saat ini dinonaktifkan dalam konteks keamanan klien, TRUE jika tidak.

[in] ImpersonationLevel

Nilai SECURITY_IMPERSONATION_LEVEL yang menentukan tingkat peniruan tempat server mengakses token.

Nilai kembali

PsImpersonateClient mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai, seperti berikut ini:

Menampilkan kode	Deskripsi
STATUS_ACCESS_DENIED	Tidak mungkin untuk meniru klien karena pembatasan pekerjaan.
STATUS_NO_MEMORY	Memori tidak cukup untuk menyelesaikan operasi.

Keterangan

PsImpersonateClient menyebabkan utas server yang ditentukan meniru klien yang ditentukan.

Utas server sudah bisa meniru klien ketika PsImpersonateClient dipanggil. Jika demikian, referensi mengandalkan token yang mewakili klien tersebut dikurangi. Untuk mempertahankan token ini untuk digunakan nanti, driver harus memanggil PsReferenceImpersonationToken sebelum memanggil PsImpersonateClient dan menyimpan pointer yang dikembalikan oleh PsReferenceImpersonationToken.

Untuk mengakhiri peniruan dan mengembalikan utas server ke peniruan sebelumnya, panggil PsImpersonateClient lagi, lewati pointer yang disimpan untuk parameter Token . Untuk mengakhiri semua peniruan, panggil rutinitas PsRevertToSelf .

Jika tidak, untuk mengakhiri peniruan dan mengembalikan utas server ke konteks keamanan aslinya (yaitu, yang diwakili oleh token utamanya), panggil PsImpersonateClient lagi, melewati pointer NULL untuk parameter Token .

Rutinitas PsImpersonateClient dapat gagal mengembalikan utas server ke peniruan sebelumnya jika utas sudah meniru atau ada batasan pekerjaan.

Rutinitas memastikan apakah peniruan klien benar-benar dapat terjadi dengan memeriksa berbagai kondisi, termasuk yang berikut:

Token yang diteruskan oleh penelepon tidak memiliki ID autentikasi anonim
Token proses yang dirujuk dari utas server dan token yang diberikan memiliki pengidentifikasi keamanan (SID) yang sama
Tidak ada token yang dibatasi

Jika tidak ada kondisi yang terpenuhi, rutinitas membuat salinan token yang ada diteruskan ke panggilan dan menetapkan token yang baru disalin sebagai token peniruan meskipun dengan tingkat peniruan keamanan terbatas; artinya, utas server hanya dapat memperoleh informasi tentang klien. Jika penyalinan token tidak dimungkinkan, rutinitas gagal dengan kode NTSTATUS.

Sangat tidak aman untuk menaikkan status hak istimewa dari utas pengguna yang tidak tepercaya (ambil utas pengguna dan meniru LocalSystem, misalnya). Jika utas pengguna yang tidak tepercaya memiliki hak istimewanya yang dinaikkan, pengguna dapat mengambil token utas setelah ditinggikan dan ditumbangkan keamanan seluruh sistem.

Dalam kasus di mana status hak istimewa yang lebih tinggi diperlukan, tugas harus dikirim ke antrean kerja di mana tugas dapat ditangani dengan aman oleh utas pekerja sistem . Dengan cara ini tidak diperlukan peniruan.

Rutinitas SeImpersonateClientEx dapat digunakan untuk menyebabkan utas meniru pengguna.

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

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(storport), PowerIrpDDis(wdm)