Share via

SetPrivateObjectSecurityEx 函数 (securitybaseapi.h)

  • 项目

SetPrivateObjectSecurityEx 函数修改由调用此函数的资源管理器维护的专用对象的安全描述符。 SetPrivateObjectSecurityEx 函数具有一个 flags 参数，该参数指定资源管理器是否支持自动继承访问控制项 (ACE) 。

语法

BOOL SetPrivateObjectSecurityEx(
  [in]           SECURITY_INFORMATION SecurityInformation,
  [in]           PSECURITY_DESCRIPTOR ModificationDescriptor,
  [in, out]      PSECURITY_DESCRIPTOR *ObjectsSecurityDescriptor,
  [in]           ULONG                AutoInheritFlags,
  [in]           PGENERIC_MAPPING     GenericMapping,
  [in, optional] HANDLE               Token
);

参数

[in] SecurityInformation

要设置的安全描述符的各个部分。 此值可以是 SECURITY_INFORMATION 位标志的组合。

[in] ModificationDescriptor

指向 SECURITY_DESCRIPTOR 结构的指针。 SecurityInformation 参数指示的此安全描述符的各个部分将应用于 ObjectsSecurityDescriptor 安全描述符。

[in, out] ObjectsSecurityDescriptor

指向 指向SECURITY_DESCRIPTOR 结构的指针的指针。 此安全描述符必须采用 自相对 形式。 必须使用 HeapAlloc 函数从进程堆 (GetProcessHeap) 分配安全描述符的内存。

输入时，这是专用对象的当前安全描述符。 函数对其进行修改以生成新的安全描述符。 如有必要， SetPrivateObjectSecurityEx 函数会分配额外的内存，以生成更大的安全描述符。

[in] AutoInheritFlags

指定 ACE 的自动继承。 如果受保护的服务器不实现自动继承，则应指定零;否则，它可以指定以下值的组合，在 Winnt.h 中定义。

值 含义
SEF_DACL_AUTO_INHERIT
0x01
 (DACL) 的新 可自由访问控制列表 包含从对象的父对象的 DACL 继承的 ACE，以及 ModificationDescriptor DACL 中指定的任何显式 ACE。 如果未设置此标志，则新的 DACL 不会继承 ACE。
SEF_SACL_AUTO_INHERIT
0x02
 (SACL) 的新 系统访问控制列表 包含从与对象的父级关联的安全描述符的 SACL 继承的 ACE，以及在 修改描述符的 SACL 中指定的任何显式 ACE。 如果未设置此标志，则新的 SACL 不会继承 ACE。
SEF_AVOID_PRIVILEGE_CHECK
0x08
 函数不执行权限检查。 如果还设置了 SEF_AVOID_OWNER_CHECK 标志， 则 Token 参数可以为 NULL。 实现自动继承时使用此标志，以避免检查每个更新的子级的权限。
SEF_AVOID_OWNER_CHECK
0x10
 函数不检查结果 ObjectsSecurityDescriptor 中所有者的有效性，如备注中所述。 如果还设置了 SEF_AVOID_PRIVILEGE_CHECK 标志， 则 Token 参数可以为 NULL。
SEF_DEFAULT_OWNER_FROM_PARENT
0x20
 ObjectsSecurityDescriptor 的所有者默认为对象的父对象的所有者。 如果未设置此标志， 则 ObjectsSecurityDescriptor 的所有者默认为 Token 参数指定的令牌的所有者。 令牌的所有者在令牌本身中指定。 在任一情况下，如果 ModificationDescriptor 参数不是 NULL，则 ObjectsSecurityDescriptor 所有者将从 ModificationDescriptor 设置为所有者。
SEF_DEFAULT_GROUP_FROM_PARENT
0x40
 ObjectSecurityDescriptor 组默认为对象父级所有者的组。 如果未设置此标志， 则 ObjectsSecurityDescriptor 组默认为 Token 参数指定的令牌组。 令牌组在令牌本身中指定。 在任一情况下，如果 ModificationDescriptor 参数不为 NULL，则 ObjectsSecurityDescriptor 组将设置为 ModificationDescriptor 中的组。
SEF_MACL_NO_WRITE_UP
0x100
 强制级别低于 对象的主体无法写入对象。
SEF_MACL_NO_READ_UP
0x200
 强制级别低于 对象的主体无法读取对象。
SEF_MACL_NO_EXECUTE_UP
0x400
 强制级别低于 对象的主体无法执行对象。
SEF_AVOID_OWNER_RESTRICTION
0x1000
 将忽略对象父级所有者指定的任何限制，这些限制将限制调用方在 ObjectsSecurityDescriptor 中指定 DACL 的能力。

[in] GenericMapping

指向 GENERIC_MAPPING 结构的指针，该结构指定与每个通用访问权限对应的特定和标准访问权限。

[in, optional] Token

标识要代表其修改专用对象安全性的客户端 的访问令牌 。 若要确保客户端已为新的所有者 安全标识符 提供合法值 (SID) ，此参数是必需的。 令牌必须打开才能TOKEN_QUERY访问。

返回值

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

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

注解

如果 AutoInheritFlags 参数为零， 则 SetPrivateObjectSecurityEx 与 SetPrivateObjectSecurity 函数相同。

此函数仅供资源管理器使用。 若要实现用于更新安全描述符的标准 Windows 访问控制语义，资源管理器应在调用 SetPrivateObjectSecurityEx 之前验证是否满足以下条件：

  • 如果正在设置对象的所有者，则调用 进程 必须具有WRITE_OWNER权限或对象的所有者。
  • 如果正在设置对象的 DACL，则调用进程必须具有WRITE_DAC权限或对象的所有者。
  • 如果正在设置对象的 SACL，则必须为调用进程启用SE_SECURITY_NAME特权。
如果不满足上述条件，则对此函数的调用不会失败，但不会强制实施标准 Windows 访问策略。

调用此函数的进程不应模拟客户端，因为客户端通常没有基础令牌操作所需的适当权限。

如果 AutoInheritFlags 指定SEF_DACL_AUTO_INHERIT位，则函数会将以下规则应用于 DACL，以从当前描述符创建新的安全描述符：

  • 如果未在当前安全描述符或 ModificationDescriptor 的控制位中设置SE_DACL_PROTECTED标志，则函数将从继承的当前安全描述符的 ACE 和 ModificationDescriptor 的非继承 ACE 构造输出安全描述符。 也就是说，无法通过更改对象上的 ACL) (访问控制列表 来更改继承的 ACE。 此行为会保留继承的 ACE，因为它们是从父容器继承的。

    ACL 编辑器应使继承的 ACE 不可用，以防止对其进行修改。

  • 如果在 ModificationDescriptor 中设置了SE_DACL_PROTECTED，则忽略当前安全描述符。 输出安全描述符生成为 ModificationDescriptor 的副本，并关闭任何INHERITED_ACE位。

    理想情况下，ACL 编辑器应关闭向调用方指示从对象的父级继承的 ACE 现在正在对象上显式设置的INHERITED_ACE位。

  • 如果在当前安全描述符中设置了SE_DACL_PROTECTED，而不是在 ModificationDescriptor 中设置，则忽略当前安全描述符。 输出安全描述符生成为 ModificationDescriptor 的副本。 调用方负责确保正确的 ACE 已打开INHERITED_ACE位。
如果 AutoInheritFlags 指定SEF_SACL_AUTO_INHERIT位，则函数会将类似的规则应用于新的 SACL。

对于 DACL 和 SCL，输入 ObjectsSecurityDescriptor 和 ModificationDescriptor 中的某些类型的 ACE 将被替换为输出 ObjectsSecurityDescriptor 中的两个 ACE。 具体而言，至少包含以下一个可映射元素的可继承 ACE 将在输出 ObjectsSecurityDescriptor 中生成两个 ACE。 可映射元素包括：

  • ACCESS_MASK结构中的泛型访问权限
  • 创建者所有者 SID 或创建者组 SID 作为 ACE 使用者标识符
具有其中任何一个可映射元素的 ACE 将导致输出 ObjectsSecurityDescriptor 中出现以下两个 ACE：
  • 一个 ACE，它是原始副本，但设置了INHERIT_ONLY标志
  • 一个 ACE，其中打开INHERITED_ACE位，泛型元素映射到特定元素：
    • 通用访问权限由输入 GenericMapping 中指示的相应标准和特定访问权限取代。
    • 创建者所有者 SID 替换为输出 SecurityDescriptor 中的所有者
    • 创建者组 SID 将替换为输出 SecurityDescriptor 中的组
如果 AutoInheritFlags 未指定SEF_AVOID_PRIVILEGE_CHECK位，则会根据以下规则执行所有者有效性检查。 ModificationDescriptor 中的所有者：
  • 必须是合法格式的 SID
  • 必须与 Token 中的 TokenUser 匹配
或
  • 必须与 Token 中的 TokenGroups 中的组 匹配，其中组的属性：
    • 包括SE_GROUP_OWNER
    • 包括SE_GROUP_USE_FOR_DENY_ONLY
在对象的子树上设置所有者的资源管理器可以避免冗余所有者有效性检查的开销。 如果 ModificationDescriptor 和 Token 中的 Owner 对于对此函数的迭代调用保持不变，则可能会在 AutoInheritFlags 中为执行所有者有效性检查的初始调用之后的调用设置SEF_AVOID_PRIVILEGE_CHECK位。 无权访问最终将设置所有者的客户端令牌的调用方也应选择跳过所有者验证检查。
注意SetPrivateObjectSecurityEx 函数中使用的SEF_AVOID_PRIVILEGE_CHECK位等效于 CreatePrivateObjectSecurityEx 函数中使用的SEF_AVOID_OWNER_CHECK位。
 

要求

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

另请参阅

ACCESS_MASK

客户端/服务器访问控制函数

客户端/服务器访问控制概述

CreatePrivateObjectSecurityEx

DestroyPrivateObjectSecurity

GENERIC_MAPPING

GetPrivateObjectSecurity

SECURITY_DESCRIPTOR

SECURITY_INFORMATION

SetFileSecurity

SetKernelObjectSecurity

SetPrivateObjectSecurity

SetUserObjectSecurity