Fungsi AccessCheck (securitybaseapi.h)

Artikel
25/08/2023

Fungsi AccessCheck menentukan apakah deskriptor keamanan memberikan serangkaian hak akses tertentu kepada klien yang diidentifikasi oleh token akses. Biasanya, aplikasi server menggunakan fungsi ini untuk memeriksa akses ke objek privat.

Sintaks

BOOL AccessCheck(
  [in]            PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]            HANDLE               ClientToken,
  [in]            DWORD                DesiredAccess,
  [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] 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] GenericMapping

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

[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 AccessCheck membandingkan deskriptor keamanan yang ditentukan dengan token akses yang ditentukan dan menunjukkan, dalam parameter AccessStatus , apakah akses diberikan atau ditolak. Jika akses diberikan, masker akses yang diminta menjadi masker akses yang diberikan objek.

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

Fungsi AccessCheck gagal dengan ERROR_INVALID_SECURITY_DESCR jika deskriptor keamanan tidak berisi SID pemilik dan grup.

Fungsi AccessCheck tidak menghasilkan audit. Jika aplikasi Anda memerlukan audit untuk pemeriksaan akses, gunakan fungsi seperti AccessCheckAndAuditAlarm, AccessCheckByTypeAndAuditAlarm, AccessCheckByTypeResultListAndAuditAlarm, atau AccessCheckByTypeResultListAnditAlarmByHandle, bukan AccessCheck.

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Memverifikasi Akses Klien dengan ACL.

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