Fungsi GetSecurityInfo (aclapi.h)

Artikel
08/22/2023

Fungsi GetSecurityInfo mengambil salinan deskriptor keamanan untuk objek yang ditentukan oleh handel.

Sintaks

DWORD GetSecurityInfo(
  [in]            HANDLE               handle,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Parameter

[in] handle

Handel ke objek untuk mengambil informasi keamanan.

[in] ObjectType

SE_OBJECT_TYPE nilai enumerasi yang menunjukkan jenis objek.

[in] SecurityInfo

Sekumpulan bendera bit yang menunjukkan jenis informasi keamanan yang akan diambil. Parameter ini dapat menjadi kombinasi dari bendera bit SECURITY_INFORMATION .

[out, optional] ppsidOwner

Penunjuk ke variabel yang menerima pointer ke SID pemilik di deskriptor keamanan yang dikembalikan dalam ppSecurityDescriptor. Penunjuk yang dikembalikan hanya valid jika Anda mengatur bendera OWNER_SECURITY_INFORMATION. Parameter ini bisa NULL jika Anda tidak memerlukan SID pemilik.

[out, optional] ppsidGroup

Penunjuk ke variabel yang menerima penunjuk ke SID grup utama di deskriptor keamanan yang dikembalikan. Penunjuk yang dikembalikan hanya valid jika Anda mengatur bendera GROUP_SECURITY_INFORMATION. Parameter ini bisa NULL jika Anda tidak memerlukan SID grup.

[out, optional] ppDacl

Penunjuk ke variabel yang menerima penunjuk ke DACL di deskriptor keamanan yang dikembalikan. Penunjuk yang dikembalikan hanya valid jika Anda mengatur bendera DACL_SECURITY_INFORMATION. Parameter ini bisa NULL jika Anda tidak memerlukan DACL.

[out, optional] ppSacl

Penunjuk ke variabel yang menerima penunjuk ke SACL di deskriptor keamanan yang dikembalikan. Penunjuk yang dikembalikan hanya valid jika Anda mengatur bendera SACL_SECURITY_INFORMATION. Parameter ini bisa NULL jika Anda tidak memerlukan SACL.

[out, optional] ppSecurityDescriptor

Penunjuk ke variabel yang menerima penunjuk ke pendeskripsi keamanan objek. Setelah Anda selesai menggunakan penunjuk, bebaskan buffer yang dikembalikan dengan memanggil fungsi LocalFree .

Parameter ini diperlukan jika salah satu parameter ppsidOwner, ppsidGroup, ppDacl, atau ppSacl bukan NULL.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan bukan nol yang ditentukan dalam WinError.h.

Keterangan

Jika parameter ppsidOwner, ppsidGroup, ppDacl, dan ppSaclnon-NULL, dan parameter SecurityInfo menentukan bahwa parameter tersebut diambil dari objek, parameter tersebut akan menunjuk ke parameter yang sesuai dalam deskriptor keamanan yang dikembalikan dalam ppSecurityDescriptor.

Untuk membaca pemilik, grup, atau DACL dari pendeskripsi keamanan objek, proses panggilan harus diberikan READ_CONTROL akses saat handel dibuka. Untuk mendapatkan akses READ_CONTROL, pemanggil harus menjadi pemilik objek atau DACL objek harus memberikan akses.

Untuk membaca SACL dari deskriptor keamanan, proses panggilan harus diberikan ACCESS_SYSTEM_SECURITY akses ketika handel dibuka. Cara yang tepat untuk mendapatkan akses ini adalah dengan mengaktifkan hak istimewa SE_SECURITY_NAME dalam token pemanggil saat ini, buka handel untuk akses ACCESS_SYSTEM_SECURITY, lalu nonaktifkan hak istimewa. Untuk informasi tentang implikasi keamanan untuk mengaktifkan hak istimewa, lihat Menjalankan dengan Hak Istimewa Khusus.

Anda dapat menggunakan fungsi GetSecurityInfo dengan jenis objek berikut:

File atau direktori lokal atau jarak jauh pada sistem file NTFS
Saluran bernama
Printer lokal atau jarak jauh
Layanan Windows lokal atau jarak jauh
Berbagi jaringan
Kunci registri
Semaphores, peristiwa, mutex, dan timer yang dapat diantrekan
Proses, utas, pekerjaan, dan objek pemetaan file
Stasiun jendela layanan interaktif dan desktop
Objek layanan direktori

Fungsi ini tidak menangani kondisi balapan. Jika utas Anda memanggil fungsi ini pada perkiraan waktu alur lain mengubah deskriptor keamanan objek, maka fungsi ini bisa gagal.

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Menemukan Pemilik Objek File.

Persyaratan

Persyaratan	Nilai
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	aclapi.h
Pustaka	Advapi32.lib
DLL	Advapi32.dll