accessCheckByType 函数 (securitybaseapi.h)

项目
03/13/2024

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 参数应为对象的 SID。评估访问权限时，此 SID 以逻辑方式替换包含已知PRINCIPAL_SELF SID (S-1-5-10) 的任何访问控制条目中的 SID。有关已知 SID 的信息，请参阅已知 SID。

如果受保护的对象不表示主体，请将此参数设置为 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 结构的指针。 GENERIC_MAPPING 结构的 GenericAll 成员应包含资源管理器可以授予的所有访问权限，包括STANDARD_RIGHTS_ALL以及 GenericRead、GenericWrite 和 GenericExecute 成员中设置的所有权限。

[out, optional] PrivilegeSet

指向 PRIVILEGE_SET 结构的指针，该结构接收用于执行访问验证的权限。如果未使用任何特权，该函数会将 PrivilegeCount 成员设置为零。

[in, out] PrivilegeSetLength

指定 PrivilegeSet 参数指向的缓冲区的大小（以字节为单位）。

[out] GrantedAccess

指向接收已授予访问权限的访问掩码的指针。如果 AccessStatus 设置为 FALSE，则函数会将访问掩码设置为零。如果函数失败，则不会设置访问掩码。

[out] AccessStatus

指向接收访问检查结果的变量的指针。如果安全描述符允许请求的访问权限访问令牌标识的客户端， 则 AccessStatus 设置为 TRUE。否则， AccessStatus 设置为 FALSE，你可以调用 GetLastError 以获取扩展的错误信息。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

有关详细信息，请参阅 AccessCheck 的工作原理概述。

AccessCheckByType 函数将指定的安全描述符与指定的访问令牌进行比较，并在 AccessStatus 参数中指示是授予访问权限还是拒绝访问。

ObjectTypeList 数组不一定表示整个定义的对象。相反，它表示要为其检查访问的对象子集。例如，若要检查访问属性集中的两个属性，请指定具有四个元素的对象类型列表：对象本身位于级别 0、在级别 1 处设置的属性和级别 2 中的两个属性。

AccessCheckByType 函数计算应用于对象本身的 ACE，以及 ObjectTypeList 数组中列出的对象类型特定于对象的 ACE。对于 ObjectTypeList 数组中未列出的对象类型，函数将忽略特定于对象的 ACE。因此， AccessStatus 参数中返回的结果指示允许访问 ObjectTypeList 参数定义的对象的子集，而不是整个对象。

有关 ACE 层次结构如何控制对对象及其子对象的访问的详细信息，请参阅用于控制对对象属性的访问的 ACE。

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

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

要求

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