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

Статья
08/25/2023

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

Синтаксис

BOOL AccessCheckByType(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPBOOL               AccessStatus
);

Параметры

[in] pSecurityDescriptor

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

[in, optional] PrincipalSelfSid

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

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

[in] ClientToken

Дескриптор маркера олицетворения , который представляет клиент, пытающийся получить доступ. Дескриптор должен иметь TOKEN_QUERY доступ к маркеру; В противном случае функция завершается сбоем с ERROR_ACCESS_DENIED.

[in] DesiredAccess

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

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

[in, out, optional] ObjectTypeList

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

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

Если ObjectTypeList имеет значение NULL, AccessCheckByType совпадает с функцией AccessCheck .

[in] ObjectTypeListLength

Указывает количество элементов в массиве ObjectTypeList .

[in] GenericMapping

Указатель на структуру GENERIC_MAPPING , связанную с объектом, для которого проверяется доступ. Элемент GenericAll структуры GENERIC_MAPPING должен содержать все права доступа, которые могут быть предоставлены диспетчером ресурсов, включая STANDARD_RIGHTS_ALL и все права, заданные в элементах GenericRead, GenericWrite и GenericExecute .

[out, optional] PrivilegeSet

Указатель на структуру PRIVILEGE_SET , которая получает привилегии , используемые для проверки доступа. Если привилегии не использовались, функция устанавливает для элемента PrivilegeCount значение 0.

[in, out] PrivilegeSetLength

Указывает размер (в байтах) буфера, на который указывает параметр PrivilegeSet .

[out] GrantedAccess

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

[out] AccessStatus

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

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

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

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

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

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

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

Если DACL дескриптора безопасности имеет значение NULL, параметр AccessStatus возвращает значение TRUE, указывающее, что у клиента есть запрошенный доступ.

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

Требования

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