Bagikan melalui


Fungsi AccessCheckByTypeResultListAndItAlarmByHandleW (securitybaseapi.h)

Fungsi AccessCheckByTypeResultListAnditAlarmByHandle menentukan apakah deskriptor keamanan memberikan serangkaian hak akses tertentu kepada klien yang ditiru oleh utas panggilan. Perbedaan antara fungsi ini dan AccessCheckByTypeResultListAndAuditAlarm adalah bahwa fungsi ini memungkinkan utas panggilan untuk melakukan pemeriksaan akses sebelum meniru klien.

Fungsi ini dapat memeriksa akses ke hierarki objek, seperti objek, set propertinya, dan propertinya. Fungsi melaporkan hak akses yang diberikan atau ditolak untuk setiap jenis objek dalam hierarki. Jika deskriptor keamanan memiliki daftar kontrol akses sistem (SACL) dengan entri kontrol akses (ACE) yang berlaku untuk klien, fungsi menghasilkan pesan audit yang diperlukan dalam log peristiwa keamanan. Alarm saat ini tidak didukung.

Sintaks

BOOL AccessCheckByTypeResultListAndAuditAlarmByHandleW(
  [in]                LPCWSTR              SubsystemName,
  [in]                LPVOID               HandleId,
  [in]                HANDLE               ClientToken,
  [in]                LPCWSTR              ObjectTypeName,
  [in, optional]      LPCWSTR              ObjectName,
  [in]                PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                DWORD                DesiredAccess,
  [in]                AUDIT_EVENT_TYPE     AuditType,
  [in]                DWORD                Flags,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [in]                BOOL                 ObjectCreation,
                      LPDWORD              GrantedAccessList,
  [out]               LPDWORD              AccessStatusList,
  [out]               LPBOOL               pfGenerateOnClose
);

Parameter

[in] SubsystemName

Penunjuk ke string yang dihentikan null yang menentukan nama subsistem yang memanggil fungsi. String ini muncul dalam pesan audit apa pun yang dihasilkan fungsi.

[in] HandleId

Penunjuk ke nilai unik yang mewakili handel klien ke objek . Jika akses ditolak, sistem mengabaikan nilai ini.

[in] ClientToken

Handel ke objek token yang mewakili klien yang meminta operasi. Handel ini harus diperoleh melalui lapisan sesi komunikasi, seperti pipa bernama lokal, untuk mencegah kemungkinan pelanggaran kebijakan keamanan. Pemanggil harus memiliki akses TOKEN_QUERY untuk token yang ditentukan.

[in] ObjectTypeName

Penunjuk ke string yang dihentikan null yang menentukan jenis objek yang dibuat atau diakses. String ini muncul dalam pesan audit apa pun yang dihasilkan fungsi.

[in, optional] ObjectName

Penunjuk ke string yang dihentikan null yang menentukan nama objek yang dibuat atau diakses. String ini muncul dalam pesan audit apa pun yang dihasilkan fungsi.

[in] SecurityDescriptor

Penunjuk ke struktur SECURITY_DESCRIPTOR tempat akses diperiksa.

[in, optional] PrincipalSelfSid

Penunjuk ke SID. Jika deskriptor keamanan dikaitkan dengan objek yang mewakili prinsipal (misalnya, objek pengguna), parameter PrincipalSelfSid harus menjadi SID objek. Saat mengevaluasi akses, SID ini secara logis menggantikan SID di ACE apa pun yang berisi SID PRINCIPAL_SELF terkenal (S-1-5-10). Untuk informasi tentang SID terkenal, lihat SID terkenal.

Atur parameter ini ke NULL jika objek yang dilindungi tidak mewakili prinsipal.

[in] DesiredAccess

Masker akses yang menentukan hak akses untuk diperiksa. Masker ini harus telah dipetakan oleh fungsi MapGenericMask sehingga tidak berisi hak akses generik.

Jika parameter ini MAXIMUM_ALLOWED, fungsi mengatur masker akses di GrantedAccess untuk menunjukkan hak akses maksimum yang diizinkan deskriptor keamanan kepada klien.

[in] AuditType

Jenis audit yang akan dihasilkan. Ini bisa menjadi salah satu nilai dari jenis enumerasi AUDIT_EVENT_TYPE .

[in] Flags

Bendera yang mengontrol perilaku fungsi jika proses panggilan tidak mengaktifkan hak istimewa SE_AUDIT_NAME. Jika bendera AUDIT_ALLOW_NO_PRIVILEGE diatur, fungsi melakukan pemeriksaan akses tanpa menghasilkan pesan audit saat hak istimewa tidak diaktifkan. Jika parameter ini nol, fungsi gagal jika hak istimewa tidak diaktifkan.

[in, out, optional] ObjectTypeList

Penunjuk ke array struktur OBJECT_TYPE_LIST yang mengidentifikasi hierarki jenis objek untuk memeriksa akses. Setiap elemen dalam array menentukan GUID yang mengidentifikasi jenis objek dan nilai yang menunjukkan tingkat jenis objek dalam hierarki jenis objek. Array tidak boleh memiliki dua elemen dengan GUID yang sama.

Array harus memiliki setidaknya satu elemen. Elemen pertama dalam array harus berada pada tingkat nol dan mengidentifikasi objek itu sendiri. Array hanya dapat memiliki satu tingkat elemen nol. Elemen kedua adalah subobject, seperti set properti, pada tingkat 1. Mengikuti setiap entri tingkat 1 adalah entri subordinat untuk subobject tingkat 2 hingga 4. Dengan demikian, tingkat untuk elemen dalam array mungkin {0, 1, 2, 2, 1, 2, 2, 3}. Jika daftar jenis objek tidak berurutan, AccessCheckByTypeResultListAndAuditAlarmByHandle gagal, dan GetLastError mengembalikan ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

Jumlah elemen dalam array ObjectTypeList .

[in] GenericMapping

Penunjuk ke struktur GENERIC_MAPPING yang terkait dengan objek tempat akses sedang diperiksa.

[in] ObjectCreation

Bendera yang menentukan apakah aplikasi panggilan akan membuat objek baru saat akses diberikan. Nilai TRUE menunjukkan aplikasi akan membuat objek baru. Nilai FALSE menunjukkan aplikasi akan membuka objek yang ada.

GrantedAccessList

[out] AccessStatusList

Penunjuk ke array kode status untuk elemen terkait dalam daftar jenis objek. Fungsi ini mengatur elemen ke nol untuk menunjukkan keberhasilan atau ke nilai bukan nol untuk menunjukkan kesalahan tertentu selama pemeriksaan akses. Jika fungsi gagal, fungsi tidak mengatur salah satu elemen dalam array.

[out] pfGenerateOnClose

Penunjuk ke bendera yang ditetapkan oleh rutinitas pembuatan audit saat fungsi kembali. Teruskan bendera ini ke fungsi ObjectCloseAuditAlarm saat handel objek ditutup.

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan bukan nol.

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

Keterangan

Untuk informasi selengkapnya, lihat gambaran umum Cara Kerja AccessCheck .

Seperti fungsi AccessCheckByTypeResultListAndAuditAlarm, fungsi AccessCheckByTypeResultListAnditAlarmByHandle adalah kombinasi dari fungsi AccessCheckByTypeResultList dan AccessCheckAndAuditAlarm . Namun, AccessCheckByTypeResultListAndAuditAlarmByHandle juga memerlukan handel token klien untuk memberikan informasi keamanan pada klien.

Array ObjectTypeList tidak selalu mewakili seluruh objek yang ditentukan. Sebaliknya, ini mewakili subset objek yang akan diperiksa aksesnya. Misalnya, untuk memeriksa akses ke dua properti dalam kumpulan properti, tentukan daftar jenis objek dengan empat elemen: objek itu sendiri pada tingkat nol, properti yang diatur pada tingkat 1, dan dua properti di tingkat 2.

Fungsi AccessCheckByTypeResultListAndItAlarmByHandle mengevaluasi ACE yang berlaku untuk objek itu sendiri dan ACE khusus objek untuk jenis objek yang tercantum dalam array ObjectTypeList . Fungsi mengabaikan ACE khusus objek untuk jenis objek yang tidak tercantum dalam array ObjectTypeList .

Untuk informasi selengkapnya tentang bagaimana hierarki ACE mengontrol akses ke objek dan subobjeknya, lihat ACE untuk Mengontrol Akses ke Properti Objek.

Untuk menghasilkan pesan audit di log peristiwa keamanan, proses panggilan harus mengaktifkan hak istimewa SE_AUDIT_NAME. Sistem memeriksa hak istimewa ini dalam token utama proses panggilan, bukan token peniruan utas. Jika parameter Bendera menyertakan bendera AUDIT_ALLOW_NO_PRIVILEGE, fungsi melakukan pemeriksaan akses tanpa menghasilkan pesan audit saat hak istimewa tidak diaktifkan.

Fungsi AccessCheckByTypeResultListAnditAlarmByHandle gagal jika utas panggilan tidak meniru klien.

Jika deskriptor keamanan tidak berisi SID pemilik dan grup, AccessCheckByTypeResultListAndAuditAlarmByHandle gagal dengan ERROR_INVALID_SECURITY_DESCR.

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

Lihat juga

AUDIT_EVENT_TYPE
AccessCheck
AccessCheckAndAuditAlarm
AccessCheckByType
AccessCheckByTypeResultList
AccessCheckByTypeResultListAndAuditAlarmClient/Server Access Control
Fungsi Access Control Klien/Server
GENERIC_MAPPING
Cara Kerja AccessCheck
MakeAbsoluteSD
MapGenericMask
OBJECT_TYPE_LIST
ObjectCloseAuditAlarm
PRIVILEGE_SET
SECURITY_DESCRIPTOR