Fungsi CreatePrivateObjectSecurityWithMultipleInheritance (securitybaseapi.h)

Artikel
03/15/2023

Fungsi CreatePrivateObjectSecurityWithMultipleInheritance mengalokasikan dan menginisialisasi deskriptor keamanan relatif mandiri untuk objek privat baru yang dibuat oleh manajer sumber daya yang memanggil fungsi ini. Fungsi ini mendukung objek privat (seperti objek Layanan Direktori dengan kelas tambahan terlampir) yang terdiri dari beberapa jenis atau kelas objek.

Sintaks

BOOL CreatePrivateObjectSecurityWithMultipleInheritance(
  [in, optional] PSECURITY_DESCRIPTOR ParentDescriptor,
  [in, optional] PSECURITY_DESCRIPTOR CreatorDescriptor,
  [out]          PSECURITY_DESCRIPTOR *NewDescriptor,
  [in, optional] GUID                 **ObjectTypes,
  [in]           ULONG                GuidCount,
  [in]           BOOL                 IsContainerObject,
  [in]           ULONG                AutoInheritFlags,
  [in, optional] HANDLE               Token,
  [in]           PGENERIC_MAPPING     GenericMapping
);

Parameter

[in, optional] ParentDescriptor

Penunjuk ke deskriptor keamanan untuk kontainer induk objek. Jika tidak ada kontainer induk, parameter ini adalah NULL.

[in, optional] CreatorDescriptor

Penunjuk ke deskriptor keamanan yang disediakan oleh pembuat objek. Jika pembuat objek tidak secara eksplisit meneruskan informasi keamanan untuk objek baru, parameter ini bisa NULL. Atau, parameter ini dapat menunjuk ke deskriptor keamanan default.

[out] NewDescriptor

Penunjuk ke variabel untuk menerima penunjuk ke deskriptor keamanan relatif mandiri yang baru dialokasikan. Setelah Anda selesai menggunakan pendeskripsi keamanan, bebaskan dengan memanggil
Fungsi DestroyPrivateObjectSecurity .

[in, optional] ObjectTypes

Array pointer ke struktur GUID yang mengidentifikasi jenis objek atau kelas objek yang terkait dengan NewDescriptor. Untuk objek Direktori Aktif, array ini berisi penunjuk ke GUID kelas dari kelas struktural objek dan semua kelas tambahan yang terpasang. Atur ObjectTypes ke NULL jika objek tidak memiliki GUID.

[in] GuidCount

Jumlah GUID yang ada dalam parameter ObjectTypes .

[in] IsContainerObject

Menentukan apakah objek baru dapat berisi objek lain. Nilai TRUE menunjukkan bahwa objek baru adalah kontainer. Nilai FALSE menunjukkan bahwa objek baru bukan kontainer.

[in] AutoInheritFlags

Sekumpulan bendera bit yang mengontrol bagaimana entri kontrol akses (ASE) diwarisi dari ParentDescriptor. Parameter ini bisa menjadi kombinasi dari nilai berikut.

Nilai	Makna
SEF_DACL_AUTO_INHERIT 0x01	Daftar kontrol akses diskresi (DACL) baru berisi ACE yang diwarisi dari DACL ParentDescriptor, serta ACE eksplisit apa pun yang ditentukan dalam DACL CreatorDescriptor. 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 ParentDescriptor, serta ACE eksplisit apa pun yang ditentukan dalam SACL CreatorDescriptor. Jika bendera ini tidak diatur, SACL baru tidak mewarisi ACE.
SEF_DEFAULT_DESCRIPTOR_FOR_OBJECT 0x04	CreatorDescriptor adalah deskriptor default untuk jenis objek yang ditentukan oleh ObjectTypes. Dengan demikian, CreatorDescriptor diabaikan jika ParentDescriptor memiliki ACE khusus objek untuk jenis objek yang ditentukan oleh parameter ObjectTypes . Jika tidak ada ACE seperti itu yang diwarisi, CreatorDescriptor ditangani seolah-olah bendera ini tidak ditentukan.
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. Bendera ini berguna 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 di NewDescriptor yang dihasilkan seperti yang dijelaskan di bagian Keterangan. Jika bendera SEF_AVOID_PRIVILEGE_CHECK juga diatur, parameter Token bisa NULL.
SEF_DEFAULT_OWNER_FROM_PARENT 0x20	Pemilik NewDescriptor default ke pemilik dari ParentDescriptor. Jika tidak diatur, pemilik NewDescriptor default ke pemilik token yang ditentukan oleh parameter Token . Pemilik token ditentukan dalam token itu sendiri. Dalam kedua kasus, jika parameter CreatorDescriptor bukan NULL, pemilik NewDescriptor diatur ke pemilik dari CreatorDescriptor.
SEF_DEFAULT_GROUP_FROM_PARENT 0x40	Grup NewDescriptor default ke grup dari ParentDescriptor. Jika tidak diatur, grup NewDescriptor default ke grup token yang ditentukan oleh parameter Token . Grup token ditentukan dalam token itu sendiri. Dalam kedua kasus, jika parameter CreatorDescriptor bukan NULL, grup NewDescriptor diatur ke grup dari CreatorDescriptor.
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 menjalankan objek.
SEF_AVOID_OWNER_RESTRICTION 0x1000	Batasan apa pun yang ditentukan oleh parameter ParentDescriptor yang akan membatasi kemampuan pemanggil untuk menentukan DACL di CreatorDescriptor diabaikan.

[in, optional] Token

Handel ke token akses untuk proses klien atas nama siapa objek sedang dibuat. Jika ini adalah token peniruan identitas, token tersebut harus berada di tingkat SecurityIdentification atau yang lebih tinggi. Untuk deskripsi lengkap tingkat peniruan Identitas Keamanan, lihat jenis SECURITY_IMPERSONATION_LEVEL enumerasi.

Token klien berisi informasi keamanan default, seperti pemilik default, grup utama, dan DACL. Fungsi ini menggunakan default ini jika informasi tidak ada dalam deskriptor keamanan input. Token harus terbuka untuk akses TOKEN_QUERY .

Jika semua kondisi berikut benar, maka handel harus dibuka untuk akses TOKEN_DUPLICATE selain akses TOKEN_QUERY .

Handel token mengacu pada token utama.
Deskriptor keamanan token berisi satu atau beberapa ACE dengan OwnerRights SID.
Deskriptor keamanan ditentukan untuk parameter CreatorDescriptor .
Pemanggil fungsi ini tidak mengatur bendera SEF_AVOID_OWNER_RESTRICTION dalam parameter AutoInheritFlags .

[in] GenericMapping

Penunjuk ke struktur GENERIC_MAPPING yang menentukan pemetaan dari setiap hak generik ke hak tertentu untuk objek.

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan nilai bukan nol.

Jika fungsi gagal, fungsi akan mengembalikan nol. Panggil GetLastError untuk informasi kesalahan yang diperluas. Beberapa kode kesalahan yang diperluas dan maknanya tercantum dalam tabel berikut.

Menampilkan kode	Deskripsi
ERROR_INVALID_PRIMARY_GROUP	Fungsi tidak dapat mengambil grup utama untuk deskriptor keamanan baru.
ERROR_INVALID_OWNER	Fungsi tidak dapat mengambil pemilik untuk deskriptor keamanan baru atau pengidentifikasi keamanan (SID) tidak dapat ditetapkan sebagai pemilik. Ini terjadi ketika memvalidasi SID pemilik terhadap token yang diteruskan.
ERROR_NO_TOKEN	Fungsi menerima NULL alih-alih token untuk validasi pemilik atau pemeriksaan hak istimewa .
ERROR_PRIVILEGE_NOT_HELD	SACL sedang diatur, SEF_AVOID_PRIVILEGE_CHECK tidak diteruskan, dan token yang diteruskan tidak mengaktifkan SE_SECURITY_NAME.

Keterangan

Fungsi CreatePrivateObjectSecurityEx identik dengan memanggil fungsi CreatePrivateObjectSecurityWithMultipleInheritance dengan satu GUID di ObjectTypes.

AutoInheritFlags berbeda dari bit bernama serupa di anggota Kontrol struktur SECURITY_DESCRIPTOR. Untuk penjelasan tentang bit kontrol, lihat SECURITY_DESCRIPTOR_CONTROL.

Jika AutoInheritFlags menentukan bit SEF_DACL_AUTO_INHERIT, fungsi menerapkan aturan berikut ke DACL di deskriptor keamanan baru:

Bendera SE_DACL_AUTO_INHERITED diatur di anggota Kontrol pendeskripsi keamanan baru.
DACL deskriptor keamanan baru mewarisi ACE dari ParentDescriptor terlepas dari apakah CreatorDescriptor adalah deskriptor keamanan default atau secara eksplisit ditentukan oleh pembuat. DACL baru adalah kombinasi dari DACL induk dan pembuat seperti yang didefinisikan oleh aturan pewarisan. Secara khusus, setiap ACE di ParentDescriptor yang dapat diwariskan baik ke semua objek turunan atau ke kelas objek apa pun yang tercantum dalam ObjectTypes akan diterapkan ke DACL baru.
ACE yang diwariskan ditandai sebagai 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 ParentDescriptor dan CreatorDescriptor akan dimanipulasi dan mungkin digantikan oleh dua ACE di NewDescriptor. Secara khusus, ACE yang dapat diwariskan yang berisi setidaknya salah satu elemen yang dapat dipetakan berikut dapat mengakibatkan dua ACE dalam deskriptor keamanan output. Elemen yang dapat dipetakan meliputi:

Hak akses generik dalam 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 di NewDescriptor:

ACE yang merupakan salinan aslinya, tetapi dengan bendera INHERIT_ONLY diatur. Namun, ACE ini tidak akan dibuat jika salah satu dari dua kondisi berikut ada:
- Parameter IsContainerObject adalah FALSE. ACE yang dapat diwariskan tidak berarti pada objek nonkontainer.
- ACE asli berisi bendera NO_PROPAGATE_INHERIT. ACE asli dimaksudkan untuk diwariskan sebagai ACE yang efektif pada anak-anak, tetapi tidak dapat diwariskan di bawah anak-anak tersebut.
ACE yang efektif 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 di NewDescriptor yang dihasilkan
- Creator Group SID diganti dengan Grup di NewDescriptor yang dihasilkan

Jika AutoInheritFlags tidak menentukan bit SEF_AVOID_OWNER_CHECK, pemeriksaan validitas pemilik dilakukan sesuai dengan aturan berikut. Pemilik dalam NewDescriptor yang dihasilkan harus berupa SID yang dibentuk secara hukum, dan harus cocok dengan TokenUser di Token atau harus cocok dengan grup di TokenGroups di Token. Atribut pada grup:

Harus menyertakan SE_GROUP_OWNER
Tidak boleh menyertakan SE_GROUP_USE_FOR_DENY_ONLY

Pemanggil yang tidak memiliki akses ke token klien yang pada akhirnya akan mengatur pemilik dapat memilih untuk melewati pemeriksaan validasi pemilik.

Untuk membuat deskriptor keamanan untuk objek baru, panggil CreatePrivateObjectSecurityWithMultipleInheritance dengan ParentDescriptor yang diatur ke deskriptor keamanan kontainer induk dan CreatorDescriptor yang diatur ke deskriptor keamanan yang diusulkan oleh pembuat objek.

Untuk memverifikasi deskriptor keamanan saat ini pada objek, panggil CreatePrivateObjectSecurityWithMultipleInheritance dengan ParentDescriptor yang diatur ke deskriptor keamanan kontainer induk dan CreatorDescriptor yang diatur ke deskriptor keamanan objek saat ini. Panggilan ini memastikan bahwa ACE diwarisi dengan tepat dari deskriptor keamanan induk ke anak.

Jika deskriptor keamanan CreatorDescriptor berisi SACL, Token harus mengaktifkan hak istimewa SE_SECURITY_NAME atau pemanggil harus menentukan bendera SEF_AVOID_PRIVILEGE_CHECK di AutoInheritFlags.

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