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 的工作原理概述。

AccessCheck 函数将指定的安全描述符与指定的访问令牌进行比较，并在 AccessStatus 参数中指示是授予访问权限还是拒绝访问。如果授予访问权限，则请求的访问掩码将成为对象的已授权访问掩码。

如果安全描述符的 DACL 为 NULL， 则 AccessStatus 参数返回 TRUE，指示客户端具有请求的访问权限。

如果安全描述符不包含所有者和组 SID，AccessCheck 函数将失败并ERROR_INVALID_SECURITY_DESCR。

AccessCheck 函数不会生成审核。如果应用程序需要审核访问检查，请使用 AccessCheckAndAuditAlarm、 AccessCheckByTypeAndAuditAlarm、 AccessCheckByTypeResultListAndAuditAlarm 或 AccessCheckByTypeResultListAndAuditAlarmByHandle 等函数，而不是 AccessCheck。

示例

有关使用此函数的示例，请参阅使用 ACL 验证客户端访问。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	securitybaseapi.h (包括 Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll