Fungsi CreatePrivateObjectSecurityEx (securitybaseapi.h)

Artikel
03/08/2023

Fungsi CreatePrivateObjectSecurityEx mengalokasikan dan menginisialisasi deskriptor keamanan relatif mandiri untuk objek privat baru yang dibuat oleh manajer sumber daya yang memanggil fungsi ini.

Sintaks

BOOL CreatePrivateObjectSecurityEx(
  [in, optional] PSECURITY_DESCRIPTOR ParentDescriptor,
  [in, optional] PSECURITY_DESCRIPTOR CreatorDescriptor,
  [out]          PSECURITY_DESCRIPTOR *NewDescriptor,
  [in, optional] GUID                 *ObjectType,
  [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 pendeskripsi keamanan default.

[out] NewDescriptor

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

[in, optional] ObjectType

Penunjuk ke struktur GUID yang mengidentifikasi jenis objek yang terkait dengan NewDescriptor. Jika objek tidak memiliki GUID, atur ObjectType ke NULL.

[in] IsContainerObject

Menentukan apakah objek baru bisa memuat 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_AVOID_OWNER_CHECK 0x10	Fungsi ini tidak memeriksa validitas pemilik di NewDescriptor yang dihasilkan seperti yang dijelaskan dalam Keterangan di bawah ini. Jika bendera SEF_AVOID_PRIVILEGE_CHECK juga diatur, parameter Token dapat berupa NULL.
SEF_AVOID_OWNER_RESTRICTION 0x1000	Batasan apa pun yang ditentukan oleh ParentDescriptor yang akan membatasi kemampuan pemanggil untuk menentukan DACL di CreatorDescriptor diabaikan.
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_DACL_AUTO_INHERIT 0x01	Daftar kontrol akses diskresi (DACL) baru berisi ACE yang diwarisi dari DACL ParentDescriptor, serta ACE eksplisit yang ditentukan dalam DACL CreatorDescriptor. Jika bendera ini tidak diatur, DACL baru tidak mewarisi ACE.
SEF_DEFAULT_DESCRIPTOR_FOR_OBJECT 0x04	CreatorDescriptor adalah deskriptor default untuk jenis objek yang ditentukan oleh ObjectType. Dengan demikian, CreatorDescriptor diabaikan jika ParentDescriptor memiliki ACE khusus objek untuk jenis objek yang ditentukan oleh parameter ObjectType . Jika tidak ada ACE seperti itu yang diwarisi, CreatorDescriptor ditangani seolah-olah bendera ini tidak ditentukan.
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_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_MACL_NO_EXECUTE_UP 0x400	Ketika bendera ini diatur, label wajib ACE di CreatorDescriptor tidak digunakan untuk membuat label wajib ACE di NewDescriptor. Sebagai gantinya, SYSTEM_MANDATORY_LABEL_ACE baru dengan masker akses SYSTEM_MANDATORY_LABEL_NO_EXECUTE_UP dan SID dari SID integritas token ditambahkan ke NewDescriptor.
SEF_MACL_NO_READ_UP 0x200	Ketika bendera ini diatur, label wajib ACE di CreatorDescriptor tidak digunakan untuk membuat label wajib ACE di NewDescriptor. Sebagai gantinya, SYSTEM_MANDATORY_LABEL_ACE baru dengan masker akses SYSTEM_MANDATORY_LABEL_NO_READ_UP dan SID dari SID integritas token ditambahkan ke NewDescriptor.
SEF_MACL_NO_WRITE_UP 0x100	Ketika bendera ini diatur, label wajib ACE di CreatorDescriptor tidak digunakan untuk membuat label wajib ACE di NewDescriptor. Sebagai gantinya, SYSTEM_MANDATORY_LABEL_ACE baru dengan masker akses SYSTEM_MANDATORY_LABEL_NO_WRITE_UP dan SID dari SID integritas token ditambahkan ke NewDescriptor.
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.

[in, optional] Token

Handel ke token akses untuk proses klien yang atas nama 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 yang dijumlahkan.

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 ini 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 bukan nol.

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

Menampilkan kode	Deskripsi
ERROR_INVALID_OWNER	Fungsi tidak dapat mengambil pemilik untuk deskriptor keamanan baru atau SID tidak dapat ditetapkan sebagai pemilik. Ini terjadi ketika memvalidasi SID pemilik terhadap token yang diteruskan.
ERROR_INVALID_PRIMARY_GROUP	Fungsi tidak dapat mengambil grup utama untuk deskriptor keamanan baru.
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 CreatePrivateObjectSecurity identik dengan memanggil fungsi CreatePrivateObjectSecurityEx dengan ObjectType diatur ke NULL dan AutoInheritFlags diatur ke nol.

Parameter AutoInheritFlags berbeda dari bit bernama serupa di anggota Kontrol dari 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.
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 yang disebutkan sebelumnya akan menghasilkan 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, termasuk:
- 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. Pemilik dalam NewDescriptor yang dihasilkan harus berupa SID yang dibentuk secara hukum, dan harus cocok dengan TokenUser di Token atau mencocokkan grup di TokenGroups di Token di mana atribut pada grup harus menyertakan SE_GROUP_OWNER, dan 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 CreatePrivateObjectSecurityEx dengan ParentDescriptor yang diatur ke deskriptor keamanan kontainer induk dan CreatorDescriptor yang diatur ke deskriptor keamanan yang diusulkan oleh pembuat objek.

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