AccessCheckByTypeResultListAndAuditAlarmByHandleA-Funktion (winbase.h)

Artikel
08/27/2023

Die AccessCheckByTypeResultListAndAuditAlarmByHandle-Funktion bestimmt, ob ein Sicherheitsdeskriptor dem Client, den der aufrufende Thread identitätswechselt, einen angegebenen Satz von Zugriffsrechten gewährt. Der Unterschied zwischen dieser Funktion und AccessCheckByTypeResultListAndAuditAlarm besteht darin, dass diese Funktion es dem aufrufenden Thread ermöglicht, die Zugriffsüberprüfung vor dem Identitätswechsel des Clients durchzuführen.

Die Funktion kann den Zugriff auf eine Hierarchie von Objekten überprüfen, z. B. auf ein Objekt, seine Eigenschaftensätze und Eigenschaften. Die Funktion meldet die Zugriffsrechte, die jedem Objekttyp in der Hierarchie gewährt oder verweigert werden. Wenn die Sicherheitsbeschreibung über eine SACL (System Access Control List ) mit Zugriffssteuerungseinträgen (ACEs ) verfügt, die für den Client gelten, generiert die Funktion alle erforderlichen Überwachungsmeldungen im Sicherheitsereignisprotokoll. Alarme werden derzeit nicht unterstützt.

Syntax

BOOL AccessCheckByTypeResultListAndAuditAlarmByHandleA(
  [in]                LPCSTR               SubsystemName,
  [in]                LPVOID               HandleId,
  [in]                HANDLE               ClientToken,
  [in]                LPCSTR               ObjectTypeName,
  [in, optional]      LPCSTR               ObjectName,
  [in]                PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                DWORD                DesiredAccess,
  [in]                AUDIT_EVENT_TYPE     AuditType,
  [in]                DWORD                Flags,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [in]                BOOL                 ObjectCreation,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPDWORD              AccessStatusList,
  [out]               LPBOOL               pfGenerateOnClose
);

Parameter

[in] SubsystemName

Ein Zeiger auf eine NULL-Zeichenfolge, die den Namen des Subsystems angibt, das die Funktion aufruft. Diese Zeichenfolge wird in jeder Überwachungsmeldung angezeigt, die von der Funktion generiert wird.

[in] HandleId

Ein Zeiger auf einen eindeutigen Wert, der das Handle des Clients für das -Objekt darstellt. Wenn der Zugriff verweigert wird, ignoriert das System diesen Wert.

[in] ClientToken

Ein Handle für ein Tokenobjekt, das den Client darstellt, der den Vorgang angefordert hat. Dieses Handle muss über eine Kommunikationssitzungsebene abgerufen werden, z. B. eine lokale benannte Pipe, um mögliche Verstöße gegen Sicherheitsrichtlinien zu verhindern. Der Aufrufer muss über TOKEN_QUERY Zugriff für das angegebene Token verfügen.

[in] ObjectTypeName

Ein Zeiger auf eine NULL-beendete Zeichenfolge, die den Typ des Objekts angibt, auf das erstellt oder zugegriffen wird. Diese Zeichenfolge wird in jeder Überwachungsmeldung angezeigt, die von der Funktion generiert wird.

[in, optional] ObjectName

Ein Zeiger auf eine NULL-Zeichenfolge, die den Namen des Objekts angibt, auf das erstellt oder zugegriffen wird. Diese Zeichenfolge wird in jeder Überwachungsmeldung angezeigt, die von der Funktion generiert wird.

[in] SecurityDescriptor

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

[in, optional] PrincipalSelfSid

Ein Zeiger auf eine 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. Bei der Auswertung des Zugriffs ersetzt diese SID logisch die SID in jedem ACE, 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] DesiredAccess

Eine Zugriffsmaske , die die zu überprüfenden Zugriffsrechte angibt. Diese Maske muss von der MapGenericMask-Funktion zugeordnet worden sein, sodass sie keine generischen Zugriffsrechte enthält.

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

[in] AuditType

Der Typ der zu generierenden Überwachung. Dies kann einer der Werte aus dem AUDIT_EVENT_TYPE Enumerationstyp sein.

[in] Flags

Ein Flag, das das Verhalten der Funktion steuert, wenn für den aufrufenden Prozess die SE_AUDIT_NAME-Berechtigung nicht aktiviert ist. Wenn das AUDIT_ALLOW_NO_PRIVILEGE-Flag festgelegt ist, führt die Funktion die Zugriffsüberprüfung durch, ohne Überwachungsmeldungen zu generieren, wenn die Berechtigung nicht aktiviert ist. Wenn dieser Parameter 0 ist, schlägt die Funktion fehl, wenn die Berechtigung nicht aktiviert ist.

[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 auf der Ebene 0 liegen 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, 2, 3} sein. Wenn die Liste des Objekttyps fehlerhaft ist, schlägt AccessCheckByTypeResultListAndAuditAlarmByHandle fehl, und GetLastError gibt ERROR_INVALID_PARAMETER zurück.

[in] ObjectTypeListLength

Die Anzahl der Elemente im ObjectTypeList-Array .

[in] GenericMapping

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

[in] ObjectCreation

Ein Flag, das bestimmt, ob die aufrufende Anwendung ein neues Objekt erstellt, wenn der Zugriff gewährt wird. Der Wert TRUE gibt an, dass die Anwendung ein neues Objekt erstellt. Der Wert FALSE gibt an, dass die Anwendung ein vorhandenes Objekt öffnet.

[out] GrantedAccess

Ein Zeiger auf ein Array von Zugriffsmasken. Die Funktion legt jede Zugriffsmaske so fest, dass sie die Zugriffsrechte angibt, 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 0 fest, um den Erfolg anzugeben, oder auf einen Wert ohne Zero, um den spezifischen Fehler während der Zugriffsprüfung anzugeben. Wenn die Funktion fehlschlägt, legt sie keines der Elemente im Array fest.

[out] pfGenerateOnClose

Ein Zeiger auf ein Flag, das von der Überwachungsgenerierungsroutine festgelegt wird, wenn die Funktion zurückgibt. Übergeben Sie dieses Flag an die ObjectCloseAuditAlarm-Funktion , wenn das Objekthandle geschlossen ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero zurück.

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

Hinweise

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

Wie AccessCheckByTypeResultListAndAuditAlarm ist die AccessCheckByTypeResultListAndAuditAlarmByHandle-Funktion eine Kombination aus den Funktionen AccessCheckByTypeResultList und AccessCheckAndAuditAlarm . AccessCheckByTypeResultListAndAuditAlarmByHandle erfordert jedoch auch ein Clienttokenhandle, um Sicherheitsinformationen auf dem Client bereitzustellen.

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

Die AccessCheckByTypeResultListAndAuditAlarmByHandle-Funktion wertet ACEs aus, die für das Objekt selbst und objektspezifische ACEs für die im ObjectTypeList-Array aufgeführten Objekttypen gelten. Die Funktion ignoriert objektspezifische ACEs für Objekttypen, die nicht im ObjectTypeList-Array aufgeführt sind.

Weitere Informationen dazu, wie eine Hierarchie von ACEs den Zugriff auf ein Objekt und seine Unterobjekte steuert, finden Sie unter ACEs zum Steuern des Zugriffs auf die Eigenschaften eines Objekts.

Um Überwachungsmeldungen im Sicherheitsereignisprotokoll zu generieren, muss für den aufrufenden Prozess die berechtigung SE_AUDIT_NAME aktiviert sein. Das System überprüft diese Berechtigung im primären Token des aufrufenden Prozesses, nicht im Identitätswechseltoken des Threads. Wenn der Flags-Parameter das flag AUDIT_ALLOW_NO_PRIVILEGE enthält, führt die Funktion die Zugriffsüberprüfung durch, ohne Überwachungsmeldungen zu generieren, wenn die Berechtigung nicht aktiviert ist.

Die AccessCheckByTypeResultListAndAuditAlarmByHandle-Funktion schlägt fehl, wenn der aufrufende Thread nicht die Identität eines Clients imitiert.

Wenn der Sicherheitsdeskriptor keine Besitzer- und Gruppen-SIDs enthält, schlägt AccessCheckByTypeResultListAndAuditAlarmByHandle 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	winbase.h (einschließlich Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll