Fungsi AddAuditAccessObjectAce (securitybaseapi.h)

Artikel
08/25/2023

Fungsi AddAuditAccessObjectAce menambahkan entri kontrol akses audit sistem (ACE) ke akhir daftar kontrol akses sistem (SACL). ACE baru dapat mengaudit akses ke objek, atau ke set properti atau properti pada objek. Anda juga dapat menggunakan AddAuditAccessObjectAce untuk menambahkan ACE yang hanya dapat diwarisi oleh tipe objek anak tertentu.

Sintaks

BOOL AddAuditAccessObjectAce(
  [in, out]      PACL  pAcl,
  [in]           DWORD dwAceRevision,
  [in]           DWORD AceFlags,
  [in]           DWORD AccessMask,
  [in, optional] GUID  *ObjectTypeGuid,
  [in, optional] GUID  *InheritedObjectTypeGuid,
  [in]           PSID  pSid,
  [in]           BOOL  bAuditSuccess,
  [in]           BOOL  bAuditFailure
);

Parameter

[in, out] pAcl

Penunjuk ke SACL. Fungsi AddAuditAccessObjectAce menambahkan ACE audit sistem ke akhir SACL ini. ACE dalam bentuk struktur SYSTEM_AUDIT_OBJECT_ACE .

[in] dwAceRevision

Menentukan tingkat revisi SACL yang sedang dimodifikasi. Nilai ini harus ACL_REVISION_DS. Jika tingkat revisi SACL lebih rendah dari ACL_REVISION_DS, fungsi mengubahnya menjadi ACL_REVISION_DS.

[in] AceFlags

Sekumpulan bendera bit yang mengontrol pewarisan ACE dan jenis upaya akses untuk diaudit. Fungsi ini menetapkan bendera ini di anggota AceFlags dari struktur ACE_HEADER ACE baru. Parameter ini bisa menjadi kombinasi dari nilai berikut.

Nilai	Makna
CONTAINER_INHERIT_ACE	ACE diwarisi oleh objek kontainer.
FAILED_ACCESS_ACE_FLAG	Jika Anda mengatur bendera ini atau menentukan TRUE untuk parameter bAuditFailure , upaya yang gagal untuk menggunakan hak akses yang ditentukan menyebabkan sistem menghasilkan catatan audit di log peristiwa keamanan.
INHERIT_ONLY_ACE	ACE tidak berlaku untuk objek tempat daftar kontrol akses (ACL) ditetapkan, tetapi dapat diwarisi oleh objek anak.
INHERITED_ACE	Menunjukkan ACE yang diwariskan. Bendera ini memungkinkan operasi yang mengubah keamanan pada pohon objek untuk memodifikasi ACE yang diwariskan, sambil tidak mengubah ACE yang langsung diterapkan ke objek.
NO_PROPAGATE_INHERIT_ACE	Bit OBJECT_INHERIT_ACE dan CONTAINER_INHERIT_ACE tidak disebarkan ke ACE yang diwariskan.
OBJECT_INHERIT_ACE	ACE diwarisi oleh objek nonkontainer.
SUCCESSFUL_ACCESS_ACE_FLAG	Jika Anda mengatur bendera ini atau menentukan TRUE untuk parameter bAuditSuccess , keberhasilan penggunaan hak akses yang ditentukan menyebabkan sistem menghasilkan catatan audit di log peristiwa keamanan.

[in] AccessMask

ACCESS_MASK yang menentukan hak akses yang diaudit ACE baru untuk pengidentifikasi keamanan (SID) yang ditentukan.

[in, optional] ObjectTypeGuid

Penunjuk ke struktur GUID yang mengidentifikasi jenis objek, kumpulan properti, atau properti yang dilindungi oleh ACE baru. Jika parameter ini NULL, ACE baru melindungi objek tempat ACL ditetapkan.

[in, optional] InheritedObjectTypeGuid

Penunjuk ke struktur GUID yang mengidentifikasi jenis objek yang dapat mewarisi ACE baru. Jika parameter ini non-NULL, hanya jenis objek yang ditentukan yang dapat mewarisi ACE. Jika NULL, semua jenis objek anak dapat mewarisi ACE. Dalam kedua kasus, pewarisan juga dikendalikan oleh nilai parameter AceFlags , serta dengan perlindungan apa pun terhadap pewarisan yang ditempatkan pada objek anak.

[in] pSid

Penunjuk ke SID yang mengidentifikasi pengguna, grup, atau sesi masuk yang diakses audit ACE baru.

[in] bAuditSuccess

Menentukan apakah keberhasilan penggunaan hak akses yang ditentukan menyebabkan sistem menghasilkan catatan audit di log peristiwa keamanan. Jika bendera ini TRUE atau jika parameter AceFlags menentukan bendera SUCCESSFUL_ACCESS_ACE_FLAG, sistem mencatat upaya akses yang berhasil; jika tidak, itu tidak.

[in] bAuditFailure

Menentukan apakah upaya yang gagal untuk menggunakan hak akses yang ditentukan menyebabkan sistem menghasilkan rekaman audit di log peristiwa keamanan. Jika bendera ini TRUE atau jika parameter AceFlags menentukan bendera FAILED_ACCESS_ACE_FLAG, sistem mencatat upaya akses yang gagal; jika tidak, itu tidak.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError. Berikut ini adalah kemungkinan nilai kesalahan.

Menampilkan kode	Deskripsi
ERROR_ALLOTTED_SPACE_EXCEEDED	ACE baru tidak cocok dengan ACL. Diperlukan buffer ACL yang lebih besar.
ERROR_INVALID_ACL	ACL yang ditentukan tidak terbentuk dengan benar.
ERROR_INVALID_FLAGS	Parameter AceFlags tidak valid.
ERROR_INVALID_SID	SID yang ditentukan tidak valid secara struktural.
ERROR_REVISION_MISMATCH	Revisi yang ditentukan tidak diketahui atau tidak kompatibel dengan ACL.
ERROR_SUCCESS	ACE berhasil ditambahkan.

Keterangan

Jika ObjectTypeGuid dan InheritedObjectTypeGuid adalah NULL, gunakan fungsi AddAuditAccessAceEx daripada AddAuditAccessObjectAce. Ini disarankan karena SYSTEM_AUDIT_ACE lebih kecil dan lebih efisien daripada SYSTEM_AUDIT_OBJECT_ACE.

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