AccessCheck-Funktion (securitybaseapi.h)

Artikel
03/06/2024

Die AccessCheck-Funktion bestimmt, ob ein Sicherheitsdeskriptor dem Client, der durch ein Zugriffstoken identifiziert wird, einen angegebenen Satz von Zugriffsrechten gewährt. In der Regel verwenden Serveranwendungen diese Funktion, um den Zugriff auf ein privates Objekt zu überprüfen.

Syntax

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

Ein Zeiger auf eine SECURITY_DESCRIPTOR Struktur, für die der Zugriff überprüft wird.

[in] ClientToken

Ein Handle für ein Identitätswechseltoken , das den Client darstellt, der versucht, Zugriff zu erhalten. Das Handle muss über TOKEN_QUERY Zugriff auf das Token verfügen. Andernfalls schlägt die Funktion mit ERROR_ACCESS_DENIED fehl.

[in] DesiredAccess

Zugriffsmaske , die die zu überprüfenden Zugriffsrechte angibt. Diese Maske muss von der MapGenericMask-Funktion zugeordnet worden sein, um keine generischen Zugriffsrechte zu enthalten.

Wenn dieser Parameter MAXIMUM_ALLOWED ist, legt die Funktion die GrantedAccess-Zugriffsmaske fest, um die maximalen Zugriffsrechte anzugeben, die der Sicherheitsdeskriptor dem Client zulässt.

[in] GenericMapping

Ein Zeiger auf die GENERIC_MAPPING Struktur, die dem Objekt zugeordnet ist, für das der Zugriff überprüft wird.

[out, optional] PrivilegeSet

Ein Zeiger auf eine PRIVILEGE_SET-Struktur , die die Berechtigungen empfängt , die zum Durchführen der Zugriffsüberprüfung verwendet werden. Wenn keine Berechtigungen verwendet wurden, legt die Funktion das PrivilegeCount-Element auf 0 (null) fest.

[in, out] PrivilegeSetLength

Gibt die Größe des Puffers in Bytes an, auf den der PrivilegeSet-Parameter verweist.

[out] GrantedAccess

Ein Zeiger auf eine Zugriffsmaske , die die gewährten Zugriffsrechte empfängt. Wenn AccessStatus auf FALSE festgelegt ist, legt die Funktion die Zugriffsmaske auf 0 (null) fest. Wenn die Funktion fehlschlägt, wird die Zugriffsmaske nicht festgelegt.

[out] AccessStatus

Ein Zeiger auf eine Variable, die die Ergebnisse der Zugriffsüberprüfung empfängt. Wenn der Sicherheitsdeskriptor die angeforderten Zugriffsrechte für den Client zulässt, der durch das Zugriffstoken identifiziert wird, wird AccessStatus auf TRUE festgelegt. Andernfalls ist AccessStatus auf FALSE festgelegt, und Sie können GetLastError aufrufen, um erweiterte Fehlerinformationen zu erhalten.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Weitere Informationen finden Sie in der Übersicht über die Funktionsweise von AccessCheck .

Die AccessCheck-Funktion vergleicht den angegebenen Sicherheitsdeskriptor mit dem angegebenen Zugriffstoken und gibt im AccessStatus-Parameter an, ob der Zugriff gewährt oder verweigert wird. Wenn der Zugriff gewährt wird, wird die angeforderte Zugriffsmaske zur gewährten Zugriffsmaske des Objekts.

Wenn die DACL des Sicherheitsdeskriptors NULL ist, gibt der AccessStatus-ParameterTRUE zurück, was angibt, dass der Client über den angeforderten Zugriff verfügt.

Die AccessCheck-Funktion schlägt mit ERROR_INVALID_SECURITY_DESCR fehl, wenn der Sicherheitsdeskriptor keine Besitzer- und Gruppen-SIDs enthält.

Die AccessCheck-Funktion generiert keine Überwachung. Wenn Ihre Anwendung Überwachungen für Zugriffsprüfungen erfordert, verwenden Sie Anstelle von AccessCheck Funktionen wie AccessCheckAndAuditAlarm, AccessCheckByTypeAndAuditAlarm, AccessCheckByTypeResultListAndAuditAlarm oder AccessCheckByTypeResultListAndAuditAlarmByHandle.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Überprüfen des Clientzugriffs mit ACLs.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	securitybaseapi.h (Einschließen von Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll