Функция AccessCheckByTypeAndAuditAlarmA (winbase.h)

Статья
08/27/2023

Функция AccessCheckByTypeAndAuditAlarm определяет, предоставляет ли дескриптор безопасности указанный набор прав доступа клиенту, олицетворяемого вызывающим потоком. Функция может проверка доступ клиента к иерархии объектов, таких как объект, его наборы свойств и свойства. Функция предоставляет или запрещает доступ к иерархии в целом. Если дескриптор безопасности имеет системный список управления доступом (SACL) с записями управления доступом (ACE), которые применяются к клиенту, функция создает все необходимые сообщения аудита в журнале событий безопасности.

Будильники в настоящее время не поддерживаются.

Синтаксис

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
);

Параметры

[in] SubsystemName

Указатель на строку, завершающуюся значением NULL, которая указывает имя подсистемы, вызывающей функцию. Эта строка отображается в любом сообщении аудита, которое создает функция.

[in] HandleId

Указатель на уникальное значение, представляющее дескриптор клиента для объекта . Если доступ запрещен, система игнорирует это значение.

[in] ObjectTypeName

Указатель на строку, завершающуюся значением NULL, которая указывает тип создаваемого или доступного объекта. Эта строка отображается в любом сообщении аудита, которое создает функция.

[in, optional] ObjectName

Указатель на строку, завершающуюся значением NULL, которая указывает имя создаваемого или доступного объекта. Эта строка отображается в любом сообщении аудита, которое создает функция.

[in] SecurityDescriptor

Указатель на структуру SECURITY_DESCRIPTOR , для которой проверяется доступ.

[in, optional] PrincipalSelfSid

Указатель на идентификатор безопасности (SID). Если дескриптор безопасности связан с объектом, представляющим субъект (например, объект пользователя), параметр PrincipalSelfSid должен быть идентификатором безопасности объекта. При оценке доступа этот идентификатор безопасности логически заменяет идентификатор безопасности в любом элементе управления доступом, содержающем известный идентификатор безопасности PRINCIPAL_SELF (S-1-5-10). Сведения об известных идентификаторах безопасности см. в разделе Известные идентификаторы БЕЗОПАСНОСТИ.

Если защищенный объект не представляет участника, задайте для этого параметра значение NULL.

[in] DesiredAccess

Маска доступа, указывающая права доступа для проверка. Эта маска должна быть сопоставлена функцией MapGenericMask , чтобы она не содержала универсальных прав доступа.

Если этот параметр MAXIMUM_ALLOWED, функция задает маску доступа GrantedAccess , чтобы указать максимальные права доступа, которые дескриптор безопасности разрешает клиенту.

[in] AuditType

Тип создаваемого аудита. Это может быть одно из значений из типа перечисления AUDIT_EVENT_TYPE .

[in] Flags

Флаг, который управляет поведением функции, если вызывающий процесс не имеет привилегии SE_AUDIT_NAME. Если установлен флаг AUDIT_ALLOW_NO_PRIVILEGE, функция выполняет проверка доступа без создания сообщений аудита, если привилегия не включена. Если этот параметр равен нулю, функция завершается ошибкой, если привилегия не включена.

[in, out, optional] ObjectTypeList

Указатель на массив OBJECT_TYPE_LIST структур, определяющих иерархию типов объектов, к которым проверка доступ. Каждый элемент в массиве задает GUID, определяющий тип объекта, и значение, указывающее уровень типа объекта в иерархии типов объектов. Массив не должен содержать два элемента с одинаковым ИДЕНТИФИКАТОРом GUID.

Массив должен содержать по крайней мере один элемент. Первый элемент в массиве должен находиться на нулевом уровне и определять сам объект. Массив может иметь только один нулевой элемент уровня. Второй элемент является подобъектом, например набором свойств, на уровне 1. После каждой записи уровня 1 находятся подчиненные записи для подобъектов уровня 2–4. Таким образом, уровни для элементов в массиве могут быть {0, 1, 2, 2, 1, 2, 3}. Если список типов объектов не по порядку, AccessCheckByTypeAndAuditAlarm завершается ошибкой , и GetLastError возвращает ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

Количество элементов в массиве ObjectTypeList .

[in] GenericMapping

Указатель на структуру GENERIC_MAPPING , связанную с объектом, для которого проверяется доступ.

[in] ObjectCreation

Флаг, определяющий, будет ли вызывающее приложение создавать новый объект при предоставлении доступа. Значение TRUE указывает, что приложение создаст новый объект. Значение FALSE указывает, что приложение откроет существующий объект.

[out] GrantedAccess

Указатель на маску доступа, которая получает предоставленные права доступа. Если параметр AccessStatus имеет значение FALSE, функция устанавливает для маски доступа нулевое значение. Если функция завершается сбоем, она не устанавливает маску доступа.

[out] AccessStatus

Указатель на переменную, получающую результаты проверка доступа. Если дескриптор безопасности разрешает клиенту запрашиваемые права доступа, accessStatus имеет значение TRUE. В противном случае accessStatus имеет значение FALSE , и вы можете вызвать GetLastError , чтобы получить расширенные сведения об ошибке.

[out] pfGenerateOnClose

Указатель на флаг, заданный подпрограммой создания аудита при возврате функции. Передайте этот флаг функции ObjectCloseAuditAlarm при закрытии дескриптора объекта.

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

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

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

Если параметры PrincipalSelfSid и ObjectTypeList имеют значение NULL, параметр AuditType — AuditEventObjectAccess, а параметр Flags равен нулю, AccessCheckByTypeAndAuditAlarm выполняется так же, как функция AccessCheckAndAuditAlarm .

Массив ObjectTypeList не обязательно представляет весь определенный объект. Скорее, он представляет подмножество объекта, для которого проверка доступ. Например, чтобы проверка доступ к двум свойствам в наборе свойств, укажите список типов объектов с четырьмя элементами: сам объект на нулевом уровне, свойство, заданное на уровне 1, и два свойства на уровне 2.

Функция AccessCheckByTypeAndAuditAlarm оценивает ACE, которые применяются к самому объекту, и к определенным объектам ACE для типов объектов, перечисленных в массиве ObjectTypeList . Функция игнорирует объекты ACE для типов объектов, не перечисленных в массиве ObjectTypeList . Таким образом, результаты, возвращаемые в параметре AccessStatus , указывают на разрешенный доступ к подмножеств объекта, определенного параметром ObjectTypeList , а не ко всему объекту.

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

Чтобы создавать сообщения аудита в журнале событий безопасности, вызывающий процесс должен иметь разрешение SE_AUDIT_NAME. Система проверяет наличие этой привилегии в основном маркере вызывающего процесса, а не в маркере олицетворения потока. Если параметр Flags содержит флаг AUDIT_ALLOW_NO_PRIVILEGE, функция выполняет проверка доступа без создания сообщений аудита, если привилегия не включена.

Функция AccessCheckByTypeAndAuditAlarm завершается сбоем, если вызывающий поток не олицетворяет клиента.

Если дескриптор безопасности не содержит идентификаторы безопасности владельца и группы, AccessCheckByTypeAndAuditAlarm завершается сбоем с ERROR_INVALID_SECURITY_DESCR.

Требования


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