Fungsi SetPrivateObjectSecurityEx (securitybaseapi.h)

Artikel
03/08/2023

Fungsi SetPrivateObjectSecurityEx memodifikasi pendeskripsi keamanan objek privat yang dikelola oleh manajer sumber daya yang memanggil fungsi ini. Fungsi SetPrivateObjectSecurityEx memiliki parameter bendera yang menentukan apakah manajer sumber daya mendukung pewarisan otomatis entri kontrol akses (ACE).

Sintaks

BOOL SetPrivateObjectSecurityEx(
  [in]           SECURITY_INFORMATION SecurityInformation,
  [in]           PSECURITY_DESCRIPTOR ModificationDescriptor,
  [in, out]      PSECURITY_DESCRIPTOR *ObjectsSecurityDescriptor,
  [in]           ULONG                AutoInheritFlags,
  [in]           PGENERIC_MAPPING     GenericMapping,
  [in, optional] HANDLE               Token
);

Parameter

[in] SecurityInformation

Bagian dari deskriptor keamanan yang akan diatur. Nilai ini bisa menjadi kombinasi dari bendera bit SECURITY_INFORMATION .

[in] ModificationDescriptor

Penunjuk ke struktur SECURITY_DESCRIPTOR . Bagian dari deskriptor keamanan ini yang ditunjukkan oleh parameter SecurityInformation diterapkan ke deskriptor keamanan ObjectsSecurityDescriptor .

[in, out] ObjectsSecurityDescriptor

Penunjuk ke penunjuk ke struktur SECURITY_DESCRIPTOR . Deskriptor keamanan ini harus dalam bentuk relatif mandiri . Memori untuk deskriptor keamanan harus dialokasikan dari timbunan proses (GetProcessHeap) dengan fungsi HeapAlloc.

Pada input, ini adalah pendeskripsi keamanan objek privat saat ini. Fungsi memodifikasinya untuk menghasilkan deskriptor keamanan baru. Jika perlu, fungsi SetPrivateObjectSecurityEx mengalokasikan memori tambahan untuk menghasilkan deskriptor keamanan yang lebih besar.

[in] AutoInheritFlags

Menentukan pewarisan otomatis ACE. Jika server yang dilindungi tidak menerapkan pewarisan otomatis, server harus menentukan nol; jika tidak, ini dapat menentukan kombinasi nilai berikut, yang ditentukan dalam Winnt.h.

Nilai	Makna
SEF_DACL_AUTO_INHERIT 0x01	Daftar kontrol akses diskresi (DACL) baru berisi ACE yang diwarisi dari DACL induk objek, serta ACE eksplisit apa pun yang ditentukan dalam DACL ModificationDescriptor. Jika bendera ini tidak diatur, DACL baru tidak mewarisi ACE.
SEF_SACL_AUTO_INHERIT 0x02	Daftar kontrol akses sistem (SACL) baru berisi ACE yang diwarisi dari SACL deskriptor keamanan yang terkait dengan induk objek, serta ACE eksplisit apa pun yang ditentukan dalam SACL ModificationDescriptor. Jika bendera ini tidak diatur, SACL baru tidak mewarisi ACE.
SEF_AVOID_PRIVILEGE_CHECK 0x08	Fungsi ini tidak melakukan pemeriksaan hak istimewa. Jika bendera SEF_AVOID_OWNER_CHECK juga diatur, parameter Token dapat berupa NULL. Gunakan bendera ini saat menerapkan pewarisan otomatis untuk menghindari pemeriksaan hak istimewa pada setiap anak yang diperbarui.
SEF_AVOID_OWNER_CHECK 0x10	Fungsi ini tidak memeriksa validitas pemilik dalam ObjectsSecurityDescriptor yang dihasilkan seperti yang dijelaskan dalam Keterangan. Jika bendera SEF_AVOID_PRIVILEGE_CHECK juga diatur, parameter Token dapat berupa NULL.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	Pemilik ObjectsSecurityDescriptor default ke pemilik induk objek. Jika bendera ini tidak diatur, pemilik ObjectsSecurityDescriptor default ke pemilik token yang ditentukan oleh parameter Token . Pemilik token ditentukan dalam token itu sendiri. Dalam kedua kasus, jika parameter ModificationDescriptor bukan NULL, pemilik ObjectsSecurityDescriptor diatur ke pemilik dari ModificationDescriptor.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	Grup ObjectsSecurityDescriptor default ke grup dari pemilik induk objek. Jika bendera ini tidak diatur, grup ObjectsSecurityDescriptor default ke grup token yang ditentukan oleh parameter Token . Grup token ditentukan dalam token itu sendiri. Dalam kedua kasus, jika parameter ModificationDescriptor bukan NULL, grup ObjectsSecurityDescriptor diatur ke grup dari ModificationDescriptor.
SEF_MACL_NO_WRITE_UP 0x100	Prinsipal dengan tingkat wajib yang lebih rendah dari objek tidak dapat menulis ke objek.
SEF_MACL_NO_READ_UP 0x200	Prinsipal dengan tingkat wajib yang lebih rendah dari objek tidak dapat membaca objek.
SEF_MACL_NO_EXECUTE_UP 0x400	Prinsipal dengan tingkat wajib yang lebih rendah dari objek tidak dapat mengeksekusi objek.
SEF_AVOID_OWNER_RESTRICTION 0x1000	Batasan apa pun yang ditentukan oleh pemilik induk objek yang akan membatasi kemampuan pemanggil untuk menentukan DACL di ObjectsSecurityDescriptor diabaikan.

[in] GenericMapping

Penunjuk ke struktur GENERIC_MAPPING yang menentukan hak akses spesifik dan standar yang sesuai dengan setiap hak akses generik.

[in, optional] Token

Mengidentifikasi token akses untuk klien yang atas nama keamanan objek privat sedang dimodifikasi. Parameter ini diperlukan untuk memastikan bahwa klien telah memberikan nilai yang sah untuk pengidentifikasi keamanan pemilik (SID) baru. Token harus terbuka untuk akses TOKEN_QUERY.

Mengembalikan nilai

Jika fungsi berhasil, fungsi mengembalikan bukan nol.

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

Keterangan

Jika parameter AutoInheritFlags adalah nol, SetPrivateObjectSecurityEx identik dengan fungsi SetPrivateObjectSecurity .

Fungsi ini hanya ditujukan untuk digunakan oleh manajer sumber daya. Untuk menerapkan semantik kontrol akses Windows standar untuk memperbarui deskriptor keamanan, manajer sumber daya harus memverifikasi bahwa kondisi berikut terpenuhi sebelum memanggil SetPrivateObjectSecurityEx:

Jika pemilik objek sedang diatur, proses panggilan harus memiliki izin WRITE_OWNER atau menjadi pemilik objek.
Jika DACL objek sedang diatur, proses panggilan harus memiliki izin WRITE_DAC atau menjadi pemilik objek.
Jika SACL objek sedang diatur, hak istimewa SE_SECURITY_NAME harus diaktifkan untuk proses panggilan.

Jika kondisi sebelumnya tidak terpenuhi, panggilan ke fungsi ini tidak gagal, namun, kebijakan akses Windows standar tidak diberlakukan.

Proses yang memanggil fungsi ini tidak boleh meniru klien karena klien biasanya tidak memiliki hak istimewa yang sesuai yang diperlukan untuk operasi token yang mendasar.

Jika AutoInheritFlags menentukan bit SEF_DACL_AUTO_INHERIT, fungsi menerapkan aturan berikut ke DACL untuk membuat deskriptor keamanan baru dari deskriptor saat ini:

Jika bendera SE_DACL_PROTECTED tidak diatur dalam bit kontrol pendeskripsi keamanan saat ini atau ModificationDescriptor, fungsi membuat deskriptor keamanan output dari ACE yang diwariskan dari deskriptor keamanan saat ini dan ACE ModificationDescriptor yang tidak diwariskan. Artinya, tidak mungkin untuk mengubah ACE yang diwariskan dengan mengubah daftar kontrol akses (ACL) pada objek. Perilaku ini mempertahankan ACE yang diwariskan saat diwarisi dari kontainer induk.
Editor ACL harus membuat ACE yang diwariskan tidak tersedia untuk mencegahnya dimodifikasi.
Jika SE_DACL_PROTECTED diatur dalam ModificationDescriptor, deskriptor keamanan saat ini diabaikan. Deskriptor keamanan output dibangun sebagai salinan ModificationDescriptor dengan bit INHERITED_ACE dimatikan.
Idealnya editor ACL harus menonaktifkan bit INHERITED_ACE yang menunjukkan kepada pemanggilnya bahwa ACE yang diwarisi dari induk objek sekarang sedang diatur secara eksplisit pada objek.
Jika SE_DACL_PROTECTED diatur dalam deskriptor keamanan saat ini dan bukan di ModificationDescriptor, deskriptor keamanan saat ini diabaikan. Deskriptor keamanan output dibuat sebagai salinan ModificationDescriptor. Adalah tanggung jawab pemanggil untuk memastikan bahwa ACE yang benar mengaktifkan bit INHERITED_ACE.

Jika AutoInheritFlags menentukan bit SEF_SACL_AUTO_INHERIT, fungsi menerapkan aturan serupa ke SACL baru.

Untuk DACL dan SACL, jenis ACE tertentu di ObjectsSecurityDescriptor input dan di ModificationDescriptor akan digantikan oleh dua ACE dalam ObjectsSecurityDescriptor output. Secara khusus, ACE yang dapat diwariskan yang berisi setidaknya salah satu elemen yang dapat dipetakan berikut akan menghasilkan dua ACE dalam output ObjectsSecurityDescriptor. Elemen yang dapat dipetakan meliputi:

Hak akses generik dalam struktur ACCESS_MASK
Creator Owner SID atau Creator Group SID sebagai pengidentifikasi subjek ACE

ACE dengan salah satu elemen yang dapat dipetakan ini akan menghasilkan dua ACE berikut dalam output ObjectsSecurityDescriptor:

ACE yang merupakan salinan aslinya, tetapi dengan bendera INHERIT_ONLY diatur
ACE di mana bit INHERITED_ACE diaktifkan dan elemen generik dipetakan ke elemen tertentu:
- Hak akses generik digantikan oleh hak akses standar dan spesifik yang sesuai yang ditunjukkan dalam input GenericMapping.
- SID Pemilik Pembuat diganti dengan Pemilik dalam output SecurityDescriptor
- Creator Group SID diganti dengan Grup dalam output SecurityDescriptor

Jika AutoInheritFlags tidak menentukan bit SEF_AVOID_PRIVILEGE_CHECK, pemeriksaan validitas pemilik dilakukan sesuai dengan aturan berikut. Pemilik di ModificationDescriptor:

Harus berupa SID yang dibentuk secara hukum
Harus cocok dengan TokenUser di Token

Atau

Harus cocok dengan grup di TokenGroups di Token tempat atribut pada grup:
- Sertakan SE_GROUP_OWNER
- Sertakan SE_GROUP_USE_FOR_DENY_ONLY

Manajer sumber daya yang mengatur Pemilik pada subtree objek dapat menghindari overhead pemeriksaan validitas pemilik yang berlebihan. Jika Pemilik di ModificationDescriptor dan Token tetap sama untuk panggilan berulang ke fungsi ini, bit SEF_AVOID_PRIVILEGE_CHECK dapat diatur dalam AutoInheritFlags untuk panggilan berikutnya ke panggilan awal di mana pemeriksaan validitas pemilik dilakukan. Pemanggil yang tidak memiliki akses ke token klien yang pada akhirnya akan mengatur pemilik juga harus memilih untuk melewati pemeriksaan validasi pemilik.

Catatan Bit SEF_AVOID_PRIVILEGE_CHECK seperti yang digunakan dalam fungsi SetPrivateObjectSecurityEx setara dengan bit SEF_AVOID_OWNER_CHECK yang digunakan dalam fungsi CreatePrivateObjectSecurityEx .

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