AccessCheckByType-Funktion (securitybaseapi.h)

Artikel
03/01/2024

Die AccessCheckByType-Funktion bestimmt, ob ein Sicherheitsdeskriptor dem Client, der durch ein Zugriffstoken identifiziert wird, einen angegebenen Satz von Zugriffsrechten gewährt. Die Funktion kann den Zugriff des Clients auf eine Hierarchie von Objekten überprüfen, z. B. ein Objekt, dessen Eigenschaftensätze und Eigenschaften. Die Funktion gewährt oder verweigert den Zugriff auf die Hierarchie als Ganzes. In der Regel verwenden Serveranwendungen diese Funktion, um den Zugriff auf ein privates Objekt zu überprüfen.

Syntax

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

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

[in, optional] PrincipalSelfSid

Ein Zeiger auf eine Sicherheits-ID (SID). Wenn der Sicherheitsdeskriptor einem Objekt zugeordnet ist, das einen Prinzipal darstellt (z. B. ein Benutzerobjekt), sollte der PrincipalSelfSid-Parameter die SID des Objekts sein. Beim Auswerten des Zugriffs ersetzt diese SID logisch die SID in jedem Zugriffssteuerungseintrag , der die bekannte PRINCIPAL_SELF SID (S-1-5-10) enthält. Informationen zu bekannten SIDs finden Sie unter Bekannte SIDs.

Legen Sie diesen Parameter auf NULL fest, wenn das geschützte Objekt keinen Prinzipal darstellt.

[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, out, optional] ObjectTypeList

Ein Zeiger auf ein Array von OBJECT_TYPE_LIST Strukturen, die die Hierarchie der Objekttypen identifizieren, für die der Zugriff überprüft werden soll. Jedes Element im Array gibt eine GUID an, die den Objekttyp identifiziert, und einen Wert, der die Ebene des Objekttyps in der Hierarchie der Objekttypen angibt. Das Array sollte nicht über zwei Elemente mit derselben GUID verfügen.

Das Array muss mindestens ein Element aufweisen. Das erste Element im Array muss sich auf ebene 0 befinden und das Objekt selbst identifizieren. Das Array kann nur ein Nullelement der Ebene aufweisen. Das zweite Element ist ein Unterobjekt, z. B. ein Eigenschaftssatz, auf Ebene 1. Jedem Eintrag der Ebene 1 folgen untergeordnete Einträge für die Unterobjekte der Ebene 2 bis 4. Daher können die Ebenen für die Elemente im Array {0, 1, 2, 2, 1, 2, 3} sein. Wenn die Objekttypliste nicht ordnungsgemäß ist, schlägt AccessCheckByType fehl, und GetLastError gibt ERROR_INVALID_PARAMETER zurück.

Wenn ObjectTypeListNULL ist, ist AccessCheckByType identisch mit der AccessCheck-Funktion .

[in] ObjectTypeListLength

Gibt die Anzahl der Elemente im ObjectTypeList-Array an.

[in] GenericMapping

Ein Zeiger auf die GENERIC_MAPPING Struktur, die dem Objekt zugeordnet ist, für das der Zugriff überprüft wird. Das GenericAll-Element der GENERIC_MAPPING-Struktur sollte alle Zugriffsrechte enthalten, die vom Ressourcen-Manager gewährt werden können, einschließlich STANDARD_RIGHTS_ALL und aller Rechte, die in den Membern GenericRead, GenericWrite und GenericExecute festgelegt sind.

[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 AccessCheckByType-Funktion vergleicht den angegebenen Sicherheitsdeskriptor mit dem angegebenen Zugriffstoken und gibt im Parameter AccessStatus an, ob der Zugriff gewährt oder verweigert wird.

Das ObjectTypeList-Array stellt nicht notwendigerweise das gesamte definierte Objekt dar. Stattdessen stellt sie die Teilmenge des Objekts dar, auf das der Zugriff überprüft werden soll. Um den Zugriff auf zwei Eigenschaften in einem Eigenschaftensatz zu überprüfen, geben Sie für instance eine Objekttypliste mit vier Elementen an: das Objekt selbst auf Ebene 0, die auf Ebene 1 festgelegte Eigenschaft und die beiden Eigenschaften auf Ebene 2.

Die AccessCheckByType-Funktion wertet ACEs aus, die für das Objekt selbst gelten, und objektspezifische ACEs für die im ObjectTypeList-Array aufgeführten Objekttypen. Die Funktion ignoriert objektspezifische ACEs für Objekttypen, die nicht im ObjectTypeList-Array aufgeführt sind. Daher geben die im AccessStatus-Parameter zurückgegebenen Ergebnisse den Zugriff auf die Teilmenge des Objekts an, das durch den ObjectTypeList-Parameter definiert wird, nicht auf das gesamte Objekt.

Weitere Informationen dazu, wie eine Hierarchie von ACEs den Zugriff auf ein Objekt und dessen Unterobjekte steuert, finden Sie unter ACEs zum Steuern des Zugriffs auf die Eigenschaften eines 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.

Wenn der Sicherheitsdeskriptor keine Besitzer- und Gruppen-SIDs enthält, schlägt AccessCheckByType mit ERROR_INVALID_SECURITY_DESCR fehl.

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