Функция AddAuditAccessAceEx (securitybaseapi.h)

Статья
03/05/2024

Функция AddAuditAccessAceEx добавляет запись управления доступом (ACE) системного аудита в конец списка управления доступом системы (SACL).

Синтаксис

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

Параметры

[in, out] pAcl

Указатель на sacl. Функция AddAuditAccessAceEx добавляет ACE системного аудита в этот список управления доступом. ACE имеет форму структуры SYSTEM_AUDIT_ACE .

[in] dwAceRevision

Указывает уровень редакции изменяемого списка SACL. Это значение может быть ACL_REVISION или ACL_REVISION_DS. Используйте ACL_REVISION_DS, если saCL содержит ACE для конкретных объектов.

[in] AceFlags

Набор битовых флагов, управляющих наследованием ACE и типом попыток аудита доступа. Функция задает эти флаги в элементе AceFlagsструктуры ACE_HEADER нового ACE. Этот параметр может быть сочетанием следующих значений.

Значение	Значение
CONTAINER_INHERIT_ACE	ACE наследуется объектами контейнера.
FAILED_ACCESS_ACE_FLAG	Если установить этот флаг или указать значение TRUE для параметра bAuditFailure , неудачные попытки использовать указанные права доступа приводят к тому, что система создаст запись аудита в журнале событий безопасности.
INHERIT_ONLY_ACE	ACE не применяется к объекту, которому назначен список управления доступом (ACL), но он может наследоваться дочерними объектами.
INHERITED_ACE	Указывает наследуемое ACE. Этот флаг позволяет операциям, изменяющим безопасность в дереве объектов, изменять унаследованные ACE, при этом не изменяя ACE, которые были непосредственно применены к объекту.
NO_PROPAGATE_INHERIT_ACE	Биты OBJECT_INHERIT_ACE и CONTAINER_INHERIT_ACE не распространяются на унаследованный элемент ACE.
OBJECT_INHERIT_ACE	ACE наследуется неконтейнерными объектами.
SUCCESSFUL_ACCESS_ACE_FLAG	Если установить этот флаг или указать значение TRUE для параметра bAuditSuccess , то успешное использование указанных прав доступа приведет к тому, что система создаст запись аудита в журнале событий безопасности.

[in] dwAccessMask

Набор битовых флагов, использующих формат ACCESS_MASK для указания прав доступа, которые новый ACE проверяет для указанного идентификатора безопасности (SID).

[in] pSid

Указатель на идентификатор безопасности, который идентифицирует пользователя, группу или сеанс входа , для которого новый ACE выполняет аудит доступа.

[in] bAuditSuccess

Указывает, приведет ли успешное использование указанных прав доступа к системе создать запись аудита в журнале событий безопасности. Если этот флаг имеет значение TRUE или параметр AceFlags указывает флаг SUCCESSFUL_ACCESS_ACE_FLAG, система записывает успешные попытки доступа. В противном случае — нет.

[in] bAuditFailure

Указывает, приводят ли неудачные попытки использовать указанные права доступа, чтобы система создавала запись аудита в журнале событий безопасности. Если этот флаг имеет значение TRUE или параметр AceFlags указывает флаг FAILED_ACCESS_ACE_FLAG, система записывает неудачные попытки доступа. В противном случае — нет.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Ниже приведены возможные значения ошибок.

Код возврата	Описание
ERROR_ALLOTTED_SPACE_EXCEEDED	Новый ACE не помещается в список ACL. Требуется больший буфер ACL.
ERROR_INVALID_ACL	Указанный список ACL неправильно сформирован.
ERROR_INVALID_FLAGS	Недопустимый параметр AceFlags .
ERROR_INVALID_SID	Указанный идентификатор безопасности не является структурно допустимым.
ERROR_REVISION_MISMATCH	Указанная редакция не известна или несовместима с редакцией ACL.
ERROR_SUCCESS	ACE успешно добавлен.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	securitybaseapi.h (включая Windows.h)
Библиотека	Advapi32.lib
DLL	Advapi32.dll