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

Статья
08/25/2023

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

Синтаксис

BOOL AccessCheck(
  [in]            PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]            HANDLE               ClientToken,
  [in]            DWORD                DesiredAccess,
  [in]            PGENERIC_MAPPING     GenericMapping,
  [out, optional] PPRIVILEGE_SET       PrivilegeSet,
  [in, out]       LPDWORD              PrivilegeSetLength,
  [out]           LPDWORD              GrantedAccess,
  [out]           LPBOOL               AccessStatus
);

Параметры

[in] pSecurityDescriptor

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

[in] ClientToken

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

[in] DesiredAccess

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

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

[in] GenericMapping

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

[out, optional] PrivilegeSet

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

[in, out] PrivilegeSetLength

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

[out] GrantedAccess

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

[out] AccessStatus

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

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

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

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

Функция AccessCheck сравнивает указанный дескриптор безопасности с указанным маркером доступа и указывает в параметре AccessStatus , предоставлен или запрещен доступ. Если доступ предоставлен, запрошенная маска доступа становится маской доступа, предоставленной объекту.

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

Функция AccessCheck завершается сбоем с ERROR_INVALID_SECURITY_DESCR, если дескриптор безопасности не содержит идентификаторы БЕЗОПАСНОСТИ владельца и группы.

Функция AccessCheck не создает аудит. Если приложению требуется аудит для проверок доступа, используйте такие функции, как AccessCheckAndAuditAlarm, AccessCheckByTypeAndAuditAlarm, AccessCheckByTypeResultListAndAuditAlarm или AccessCheckByTypeResultListAndAuditAlarmByHandle вместо AccessCheckCheck.

Примеры

Пример использования этой функции см. в разделе Проверка клиентского доступа с помощью списков управления доступом.

Требования

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