Edit

SYSTEM_AUDIT_ACE structure (winnt.h)

  • Article

The SYSTEM_AUDIT_ACE structure defines an access control entry (ACE) for the system access control list (SACL) that specifies what types of access cause system-level notifications. A system-audit ACE causes an audit message to be logged when a specified trustee attempts to gain access to an object. The trustee is identified by a security identifier (SID).

Syntax

typedef struct _SYSTEM_AUDIT_ACE {
  ACE_HEADER  Header;
  ACCESS_MASK Mask;
  DWORD       SidStart;
} SYSTEM_AUDIT_ACE;

Members

Header

ACE_HEADER structure that specifies the size and type of ACE. It also contains flags that control inheritance of the ACE by child objects. The AceType member of the ACE_HEADER structure should be set to SYSTEM_AUDIT_ACE_TYPE, and the AceSize member should be set to the total number of bytes allocated for the SYSTEM_AUDIT_ACE structure.

Mask

Specifies an ACCESS_MASK structure that gives the access rights that cause audit messages to be generated. The SUCCESSFUL_ACCESS_ACE_FLAG and FAILED_ACCESS_ACE_FLAG flags in the AceFlags member of the ACE_HEADER structure indicate whether messages are generated for successful access attempts, unsuccessful access attempts, or both.

SidStart

The first DWORD of a trustee's SID. The remaining bytes of the SID are stored in contiguous memory after the SidStart member. This SID can be appended with application data.

An access attempt of a kind specified by the Mask member by any trustee whose SID matches the SidStart member causes the system to generate an audit message. If an application does not specify a SID for this member, audit messages are generated for the specified access rights for all trustees.

Remarks

Audit messages are stored in an event log that can be manipulated by using the Windows API event-logging functions or by using the Event Viewer (Eventvwr.exe).

ACE structures should be aligned on DWORD boundaries. All Windows memory-management functions return DWORD-aligned handles to memory.

When a SYSTEM_AUDIT_ACE structure is created, sufficient memory must be allocated to accommodate the complete SID of the trustee in the SidStart member and the contiguous memory that follows it.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Header winnt.h (include Windows.h)

See also

ACL