AccessCheckByTypeResultList-Funktion (securitybaseapi.h)

Artikel
08/25/2023

Die AccessCheckByTypeResultList-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 meldet die Zugriffsrechte, die jedem Objekttyp in der Hierarchie gewährt oder verweigert werden. In der Regel verwenden Serveranwendungen diese Funktion, um den Zugriff auf ein privates Objekt zu überprüfen.

Syntax

BOOL AccessCheckByTypeResultList(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [out]               PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccessList,
  [out]               LPDWORD              AccessStatusList
);

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 (Access Control Entry , ACE), der die bekannte PRINCIPAL_SELF SID (S-1-5-10) enthält. Informationen zu bekannten SIDs finden Sie unter Bekannte SIDs.

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

[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

Eine 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 Zugriffsmasken im GrantedAccess-Array fest, um die maximalen Zugriffsrechte des Clients für jedes Element in der Objekttypliste anzugeben.

[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 AccessCheckByTypeResultList fehl, und GetLastError gibt ERROR_INVALID_PARAMETER zurück.

[in] ObjectTypeListLength

Die Anzahl der Elemente im ObjectTypeList-Array . Dies ist auch die Anzahl der Elemente in den Arrays, auf die durch die Parameter GrantedAccessList und AccessStatusList verwiesen wird.

[out] 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

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

[out] GrantedAccessList

Ein Zeiger auf ein Array von Zugriffsmasken. Die Funktion legt jede Zugriffsmaske fest, um die Zugriffsrechte anzugeben, die dem entsprechenden Element in der Objekttypliste gewährt werden. Wenn die Funktion fehlschlägt, werden die Zugriffsmasken nicht festgelegt.

[out] AccessStatusList

Ein Zeiger auf ein Array von status Codes für die entsprechenden Elemente in der Objekttypliste. Die Funktion legt ein Element auf Null fest, um den Erfolg anzugeben, oder einen Wert ungleich null, um den spezifischen Fehler während der Zugriffsüberprüfung anzugeben. Wenn die Funktion fehlschlägt, wird keines der Elemente im Array festgelegt.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion ungleich null zurück.

Wenn die Funktion fehlschlägt, wird null zurückgegeben. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

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

Die AccessCheckByTypeResultList-Funktion vergleicht den angegebenen Sicherheitsdeskriptor mit dem angegebenen Zugriffstoken und gibt im Parameter AccessStatusList an, ob der Zugriff für jedes Element in der Objekttypenliste 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 AccessCheckByTypeResultList-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 für Element 0 im AccessStatusList-Parameter zurückgegebenen Ergebnisse den Zugriff auf die Teilmenge des Objekts an, die 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 (Discretionary Access Control List ) des Sicherheitsdeskriptors NULL ist, gewährt die Funktion dem angeforderten Zugriff auf alle Elemente in der Objekttypliste.

Wenn der Sicherheitsdeskriptor keine Besitzer- und Gruppen-SIDs enthält, schlägt AccessCheckByTypeResultList 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