AccessCheckByTypeResultListAndAuditAlarmByHandleA 函数 (winbase.h)

项目
03/03/2024

AccessCheckByTypeResultListAndAuditAlarmByHandle 函数确定是否向调用线程模拟的客户端授予一组指定的访问权限。此函数与 AccessCheckByTypeResultListAndAuditAlarm 的区别在于，此函数允许调用线程在模拟客户端之前执行访问检查。

函数可以检查访问对象的层次结构，例如对象、其属性集和属性。函数报告向层次结构中的每个对象类型授予或拒绝的访问权限。如果安全描述符具有系统访问控制列表 (SACL) ，其中包含适用于客户端的访问控制项 (ACE) ，则函数会在安全事件日志中生成任何必要的审核消息。当前不支持警报。

语法

BOOL AccessCheckByTypeResultListAndAuditAlarmByHandleA(
  [in]                LPCSTR               SubsystemName,
  [in]                LPVOID               HandleId,
  [in]                HANDLE               ClientToken,
  [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]               LPDWORD              AccessStatusList,
  [out]               LPBOOL               pfGenerateOnClose
);

参数

[in] SubsystemName

指向以 null 结尾的字符串的指针，该字符串指定调用函数的子系统的名称。此字符串显示在函数生成的任何审核消息中。

[in] HandleId

指向表示客户端对象句柄的唯一值的指针。如果拒绝访问，系统会忽略此值。

[in] ClientToken

令牌对象的句柄，该对象表示请求操作的客户端。必须通过通信会话层（例如本地命名管道）获取此句柄，以防止可能发生的安全策略冲突。调用方必须对指定令牌具有TOKEN_QUERY访问权限。

[in] ObjectTypeName

指向以 null 结尾的字符串的指针，该字符串指定要创建或访问的对象类型。此字符串显示在函数生成的任何审核消息中。

[in, optional] ObjectName

指向以 null 结尾的字符串的指针，该字符串指定要创建或访问的对象的名称。此字符串显示在函数生成的任何审核消息中。

[in] SecurityDescriptor

指向 SECURITY_DESCRIPTOR结构的指针，针对该结构检查访问。

[in, optional] PrincipalSelfSid

指向 SID 的指针。如果安全描述符与表示主体 (例如用户对象) 的对象相关联， 则 PrincipalSelfSid 参数应为对象的 SID。在评估访问时，此 SID 在逻辑上替换包含已知PRINCIPAL_SELF SID (S-1-5-10) 的任何 ACE 中的 SID。有关已知 SID 的信息，请参阅已知 SID。

如果受保护的对象不表示主体，请将此参数设置为 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}。如果对象类型列表不按顺序排列， AccessCheckByTypeResultListAndAuditAlarmByHandle 将失败， GetLastError 将返回ERROR_INVALID_PARAMETER。

[in] ObjectTypeListLength

ObjectTypeList 数组中的元素数。

[in] GenericMapping

指向与要检查其访问权限的对象关联的 GENERIC_MAPPING 结构的指针。

[in] ObjectCreation

一个标志，用于确定调用应用程序在授予访问权限时是否将创建新对象。值为 TRUE 表示应用程序将创建新对象。值为 FALSE 表示应用程序将打开现有对象。

[out] GrantedAccess

指向访问掩码数组的指针。函数设置每个访问掩码以指示授予对象类型列表中的相应元素的访问权限。如果函数失败，则它不会设置访问掩码。

[out] AccessStatusList

指向对象类型列表中相应元素的状态代码数组的指针。函数将元素设置为零以指示成功，将设置为非零值以指示访问检查期间的特定错误。如果函数失败，则它不会设置数组中的任何元素。

[out] pfGenerateOnClose

指向函数返回时由审核生成例程设置的标志的指针。关闭对象句柄时，将此标志传递给 ObjectCloseAuditAlarm 函数。

返回值

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

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

注解

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

与 AccessCheckByTypeResultListAndAuditAlarm 一样， AccessCheckByTypeResultListAndAuditAlarmByHandle 函数是 AccessCheckByTypeResultList 和 AccessCheckAndAuditAlarm 函数的组合。但是， AccessCheckByTypeResultListAndAuditAlarmByHandle 还需要客户端令牌句柄才能在客户端上提供安全信息。

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

AccessCheckByTypeResultListAndAuditAlarmByHandle 函数对应用于对象本身的 ACE 和 ObjectTypeList 数组中列出的对象类型评估特定于对象的 ACE。对于 ObjectTypeList 数组中未列出的对象类型，函数将忽略特定于对象的 ACE。

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

若要在安全事件日志中生成审核消息，调用进程必须启用SE_AUDIT_NAME特权。系统会在调用进程的主令牌（而不是线程的模拟令牌）中检查此特权。如果 Flags 参数包含 AUDIT_ALLOW_NO_PRIVILEGE 标志，则函数在未启用权限时执行访问检查而不生成审核消息。

如果调用线程未模拟客户端， AccessCheckByTypeResultListAndAuditAlarmByHandle 函数将失败。

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

要求

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