AccessCheckByTypeAndAuditAlarmA-Funktion (winbase.h)

Artikel
08/27/2023

Die AccessCheckByTypeAndAuditAlarm-Funktion bestimmt, ob ein Sicherheitsdeskriptor dem Client, der vom aufrufenden Thread identitätswechselt 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, seine Eigenschaftensätze und Eigenschaften. Die Funktion gewährt oder verweigert den Zugriff auf die gesamte Hierarchie. 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 AccessCheckByTypeAndAuditAlarmA(
  [in]                LPCSTR               SubsystemName,
  [in]                LPVOID               HandleId,
  [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]               LPBOOL               AccessStatus,
  [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] 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 einen Sicherheitsbezeichner (Security Identifier , 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.

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

[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 Zugriffsmaske 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 Objekttypliste nicht ordnungsgemäß ist, schlägt AccessCheckByTypeAndAuditAlarm 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 eine Zugriffsmaske, die die gewährten Zugriffsrechte empfängt. Wenn AccessStatus auf FALSE festgelegt ist, legt die Funktion die Zugriffsmaske auf Null fest. Wenn die Funktion fehlschlägt, wird die Zugriffsmaske nicht festgelegt.

[out] AccessStatus

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

[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 .

Wenn die Parameter PrincipalSelfSid und ObjectTypeListNULL sind, der AuditType-ParameterAuditEventObjectAccess und der Flags-Parameter null ist, wird AccessCheckByTypeAndAuditAlarm auf die gleiche Weise wie die AccessCheckAndAuditAlarm-Funktion ausgeführt.

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 AccessCheckByTypeAndAuditAlarm-Funktion wertet ACEs aus, die auf das Objekt selbst und objektspezifische ACEs für die im ObjectTypeList-Array aufgeführten Objekttypen angewendet werden. 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 durch den ObjectTypeList-Parameter definierten Objekts und nicht auf das gesamte Objekt an.

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 AccessCheckByTypeAndAuditAlarm-Funktion schlägt fehl, wenn der aufrufende Thread die Identität eines Clients nicht anniert.

Wenn die Sicherheitsbeschreibung keine Besitzer- und Gruppen-SIDs enthält, schlägt AccessCheckByTypeAndAuditAlarm mit ERROR_INVALID_SECURITY_DESCR fehl.

Anforderungen


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