AddAuditAccessObjectAce-Funktion (securitybaseapi.h)
Die AddAuditAccessObjectAce-Funktion fügt am Ende einer Systemzugriffssteuerungsliste (SACL) einen Systemüberwachungszugriffssteuerungseintrag (ACE) hinzu. Der neue ACE kann den Zugriff auf ein Objekt oder einen Eigenschaftssatz oder eine Eigenschaft für ein Objekt überwachen. Sie können auch AddAuditAccessObjectAce verwenden, um ein ACE hinzuzufügen, das nur ein angegebener Typ von untergeordneten Objekten erben kann.
Syntax
BOOL AddAuditAccessObjectAce(
[in, out] PACL pAcl,
[in] DWORD dwAceRevision,
[in] DWORD AceFlags,
[in] DWORD AccessMask,
[in, optional] GUID *ObjectTypeGuid,
[in, optional] GUID *InheritedObjectTypeGuid,
[in] PSID pSid,
[in] BOOL bAuditSuccess,
[in] BOOL bAuditFailure
);
Parameter
[in, out] pAcl
Ein Zeiger auf eine SACL. Die AddAuditAccessObjectAce-Funktion fügt am Ende dieser SACL eine Systemüberwachungs-ACE hinzu. Der ACE hat die Form einer SYSTEM_AUDIT_OBJECT_ACE-Struktur .
[in] dwAceRevision
Gibt die Revisionsebene der zu ändernden SACL an. Dieser Wert muss ACL_REVISION_DS sein. Wenn die Revisionsebene der SACL niedriger als ACL_REVISION_DS ist, ändert die Funktion sie in ACL_REVISION_DS.
[in] AceFlags
Eine Reihe von Bitflags, die die ACE-Vererbung und den Typ der Zu überwachenden Zugriffsversuche steuern. Die Funktion legt diese Flags im AceFlags-Member der ACE_HEADER-Struktur des neuen ACE fest. Für diesen Parameter ist eine Kombination der folgenden Werte gültig.
Wert | Bedeutung |
---|---|
|
Der ACE wird von Containerobjekten geerbt. |
|
Wenn Sie dieses Flag festlegen oder TRUE für den bAuditFailure-Parameter angeben, führen fehlgeschlagene Versuche, die angegebenen Zugriffsrechte zu verwenden, dazu, dass das System einen Überwachungsdatensatz im Sicherheitsereignisprotokoll generiert. |
|
Der ACE gilt nicht für das Objekt, dem die Zugriffssteuerungsliste (Access Control List , ACL) zugewiesen ist, aber es kann von untergeordneten Objekten geerbt werden. |
|
Gibt einen geerbten ACE an. Dieses Flag ermöglicht Es Vorgängen, die die Sicherheit für eine Struktur von Objekten ändern, geerbte ACEs zu ändern, während acEs, die direkt auf das Objekt angewendet wurden, nicht geändert werden. |
|
Die OBJECT_INHERIT_ACE und CONTAINER_INHERIT_ACE Bits werden nicht an eine geerbte ACE weitergegeben. |
|
Der ACE wird von Nichtcontainerobjekten geerbt. |
|
Wenn Sie dieses Flag festlegen oder TRUE für den bAuditSuccess-Parameter angeben, führt die erfolgreiche Verwendung der angegebenen Zugriffsrechte dazu, dass das System einen Überwachungsdatensatz im Sicherheitsereignisprotokoll generiert. |
[in] AccessMask
Eine ACCESS_MASK , die die Zugriffsrechte angibt, die vom neuen ACE für die angegebene Sicherheits-ID (SID) überwacht werden.
[in, optional] ObjectTypeGuid
Ein Zeiger auf eine GUID-Struktur , die den Typ des Objekts, des Eigenschaftensatzes oder der Eigenschaft identifiziert, der durch den neuen ACE geschützt wird. Wenn dieser Parameter NULL ist, schützt der neue ACE das Objekt, dem die ACL zugewiesen ist.
[in, optional] InheritedObjectTypeGuid
Ein Zeiger auf eine GUID-Struktur , die den Typ des Objekts angibt, das den neuen ACE erben kann. Wenn dieser Parameter nicht NULL ist, kann nur der angegebene Objekttyp den ACE erben. Wenn NULL, kann jeder Typ von untergeordneten Objekten den ACE erben. In beiden Fällen wird die Vererbung auch durch den Wert des AceFlags-Parameters sowie durch jeglichen Schutz vor Vererbung gesteuert, der auf die untergeordneten Objekte gesetzt wird.
[in] pSid
Ein Zeiger auf eine SID, die den Benutzer, die Gruppe oder die Anmeldesitzung identifiziert, für die der neue ACE den Zugriff überwacht.
[in] bAuditSuccess
Gibt an, ob die erfolgreiche Verwendung der angegebenen Zugriffsrechte dazu führt, dass das System einen Überwachungsdatensatz im Sicherheitsereignisprotokoll generiert. Wenn dieses Flag TRUE ist oder der AceFlags-Parameter das SUCCESSFUL_ACCESS_ACE_FLAG-Flag angibt, zeichnet das System erfolgreiche Zugriffsversuche auf. andernfalls ist dies nicht der Fall.
[in] bAuditFailure
Gibt an, ob fehlgeschlagene Versuche, die angegebenen Zugriffsrechte zu verwenden, dazu führen, dass das System einen Überwachungsdatensatz im Sicherheitsereignisprotokoll generiert. Wenn dieses Flag TRUE ist oder der AceFlags-Parameter das FAILED_ACCESS_ACE_FLAG-Flag angibt, zeichnet das System fehlgeschlagene Zugriffsversuche auf. andernfalls ist dies nicht der Fall.
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. Im Folgenden sind mögliche Fehlerwerte aufgeführt.
Rückgabecode | Beschreibung |
---|---|
|
Der neue ACE passt nicht in die ACL. Ein größerer ACL-Puffer ist erforderlich. |
|
Die angegebene ACL ist nicht ordnungsgemäß gebildet. |
|
Der AceFlags-Parameter ist ungültig. |
|
Die angegebene SID ist strukturell ungültig. |
|
Die angegebene Revision ist nicht bekannt oder nicht mit der der ACL kompatibel. |
|
Der ACE wurde erfolgreich hinzugefügt. |
Hinweise
Wenn sowohl ObjectTypeGuid als auch InheritedObjectTypeGuidNULL sind, verwenden Sie die AddAuditAccessAceEx-Funktion anstelle von AddAuditAccessObjectAce. Dies wird empfohlen, da ein SYSTEM_AUDIT_ACE kleiner und effizienter ist als ein SYSTEM_AUDIT_OBJECT_ACE.
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 |