AddAuditAccessAceEx-Funktion (securitybaseapi.h)

Artikel
08/25/2023

Die AddAuditAccessAceEx-Funktion fügt am Ende einer Systemzugriffssteuerungsliste (SACL) einen Systemüberwachungszugriffssteuerungseintrag (Ace) hinzu.

Syntax

BOOL AddAuditAccessAceEx(
  [in, out] PACL  pAcl,
  [in]      DWORD dwAceRevision,
  [in]      DWORD AceFlags,
  [in]      DWORD dwAccessMask,
  [in]      PSID  pSid,
  [in]      BOOL  bAuditSuccess,
  [in]      BOOL  bAuditFailure
);

Parameter

[in, out] pAcl

Ein Zeiger auf eine SACL. Die AddAuditAccessAceEx-Funktion fügt dieser SACL ein Systemüberwachungs-ACE hinzu. Der ACE hat die Form einer SYSTEM_AUDIT_ACE Struktur.

[in] dwAceRevision

Gibt die Revisionsebene der ZU ändernden SACL an. Dieser Wert kann ACL_REVISION oder ACL_REVISION_DS sein. Verwenden Sie ACL_REVISION_DS, wenn die SACL objektspezifische ACEs enthält.

[in] AceFlags

Eine Reihe von Bitflags, die die ACE-Vererbung und die Art des Zugriffs steuern, die überwacht werden sollen. 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
CONTAINER_INHERIT_ACE	Der ACE wird von Containerobjekten geerbt.
FAILED_ACCESS_ACE_FLAG	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.
INHERIT_ONLY_ACE	Der ACE gilt nicht für das Objekt, dem die Zugriffssteuerungsliste (Access Control List , ACL) zugewiesen ist, sondern kann von untergeordneten Objekten geerbt werden.
INHERITED_ACE	Gibt einen geerbten ACE an. Dieses Flag ermöglicht Vorgängen, die die Sicherheit für eine Struktur von -Objekten ändern, geerbte ACEs zu ändern, ohne ACEs zu ändern, die direkt auf das Objekt angewendet wurden.
NO_PROPAGATE_INHERIT_ACE	Die OBJECT_INHERIT_ACE und CONTAINER_INHERIT_ACE Bits werden nicht an ein geerbtes ACE weitergegeben.
OBJECT_INHERIT_ACE	Der ACE wird von Nichtcontainerobjekten geerbt.
SUCCESSFUL_ACCESS_ACE_FLAG	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] dwAccessMask

Eine Reihe von Bitflags, die das ACCESS_MASK-Format verwenden, um die Zugriffsrechte anzugeben, die vom neuen ACE für den angegebenen Sicherheitsbezeichner (SID) überwacht werden.

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

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

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
ERROR_ALLOTTED_SPACE_EXCEEDED	Der neue ACE passt nicht in die ACL. Ein größerer ACL-Puffer ist erforderlich.
ERROR_INVALID_ACL	Die angegebene ACL ist nicht ordnungsgemäß gebildet.
ERROR_INVALID_FLAGS	Der AceFlags-Parameter ist ungültig.
ERROR_INVALID_SID	Die angegebene SID ist strukturell ungültig.
ERROR_REVISION_MISMATCH	Die angegebene Revision ist nicht bekannt oder mit der der ACL nicht kompatibel.
ERROR_SUCCESS	Der ACE wurde erfolgreich hinzugefügt.

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ßlich Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll