Fungsi AccessCheckByType (securitybaseapi.h)

Artikel
03/15/2023

Fungsi AccessCheckByType menentukan apakah deskriptor keamanan memberikan serangkaian hak akses tertentu kepada klien yang diidentifikasi oleh token akses. Fungsi ini dapat memeriksa akses klien ke hierarki objek, seperti objek, set propertinya, dan properti. Fungsi ini memberikan atau menolak akses ke hierarki secara keseluruhan. Biasanya, aplikasi server menggunakan fungsi ini untuk memeriksa akses ke objek privat.

Sintaks

BOOL AccessCheckByType(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPBOOL               AccessStatus
);

Parameter

[in] pSecurityDescriptor

Penunjuk ke struktur SECURITY_DESCRIPTOR tempat akses diperiksa.

[in, optional] PrincipalSelfSid

Penunjuk ke pengidentifikasi keamanan (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 dalam entri kontrol akses 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] ClientToken

Handel ke token peniruan yang mewakili klien yang mencoba mendapatkan akses. Handel harus memiliki akses TOKEN_QUERY ke token; jika tidak, fungsi gagal dengan ERROR_ACCESS_DENIED.

[in] DesiredAccess

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

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

[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, AccessCheckByType gagal dan GetLastError mengembalikan ERROR_INVALID_PARAMETER.

Jika ObjectTypeListNULL, AccessCheckByType sama dengan fungsi AccessCheck .

[in] ObjectTypeListLength

Menentukan jumlah elemen dalam array ObjectTypeList .

[in] GenericMapping

Penunjuk ke struktur GENERIC_MAPPING yang terkait dengan objek tempat akses sedang diperiksa. Anggota GenericAll dari struktur GENERIC_MAPPING harus berisi semua hak akses yang dapat diberikan oleh manajer sumber daya, termasuk STANDARD_RIGHTS_ALL dan semua hak yang ditetapkan dalam anggota GenericRead, GenericWrite, dan GenericExecute .

[out, optional] PrivilegeSet

Penunjuk ke struktur PRIVILEGE_SET yang menerima hak istimewa yang digunakan untuk melakukan validasi akses. Jika tidak ada hak istimewa yang digunakan, fungsi menetapkan anggota PrivilegeCount ke nol.

[in, out] PrivilegeSetLength

Menentukan ukuran, dalam byte, dari buffer yang diacu oleh parameter PrivilegeSet .

[out] GrantedAccess

Penunjuk ke masker akses yang menerima hak akses yang diberikan. Jika AccessStatus diatur ke FALSE, fungsi mengatur masker akses ke nol. Jika fungsi gagal, fungsi tidak mengatur masker akses.

[out] AccessStatus

Penunjuk ke variabel yang menerima hasil pemeriksaan akses. Jika deskriptor keamanan mengizinkan hak akses yang diminta ke klien yang diidentifikasi oleh token akses, AccessStatus diatur ke TRUE. Jika tidak, AccessStatus diatur ke FALSE, dan Anda dapat memanggil GetLastError untuk mendapatkan informasi kesalahan yang diperluas.

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.

Keterangan

Untuk informasi selengkapnya, lihat gambaran umum Cara Kerja AccessCheck .

Fungsi AccessCheckByType membandingkan deskriptor keamanan yang ditentukan dengan token akses yang ditentukan dan menunjukkan, dalam parameter AccessStatus , apakah akses diberikan atau ditolak.

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 AccessCheckByType 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 . Dengan demikian, hasil yang dikembalikan dalam parameter AccessStatus menunjukkan akses yang diizinkan ke subset objek yang ditentukan oleh parameter ObjectTypeList , bukan ke seluruh objek.

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

Jika DACL pendeskripsi keamanan ADALAH NULL, parameter AccessStatus mengembalikan TRUE, yang menunjukkan bahwa klien memiliki akses yang diminta.

Jika deskriptor keamanan tidak berisi SID pemilik dan grup, AccessCheckByType 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