createPrivateObjectSecurityEx 函数 (securitybaseapi.h)
CreatePrivateObjectSecurityEx 函数分配和初始化由资源管理器调用此函数创建的新私有对象的自相对安全描述符。
语法
BOOL CreatePrivateObjectSecurityEx(
[in, optional] PSECURITY_DESCRIPTOR ParentDescriptor,
[in, optional] PSECURITY_DESCRIPTOR CreatorDescriptor,
[out] PSECURITY_DESCRIPTOR *NewDescriptor,
[in, optional] GUID *ObjectType,
[in] BOOL IsContainerObject,
[in] ULONG AutoInheritFlags,
[in, optional] HANDLE Token,
[in] PGENERIC_MAPPING GenericMapping
);
参数
[in, optional] ParentDescriptor
指向对象的父容器 的安全描述符 的指针。 如果没有父容器，则此参数为 NULL。
[in, optional] CreatorDescriptor
指向对象创建者提供的安全描述符的指针。 如果对象的创建者未显式传递新对象的安全信息，则此参数可以为 NULL。 或者，此参数可以指向默认安全描述符。
[out] NewDescriptor
指向变量的指针，该变量接收指向新分配的自相对安全描述符的指针。 使用完安全描述符后，请通过调用
DestroyPrivateObjectSecurity 函数。
[in, optional] ObjectType
指向 GUID 结构的指针，该结构标识与 NewDescriptor 关联的对象类型。 如果对象没有 GUID，请将 ObjectType 设置为 NULL。
[in] IsContainerObject
指定新对象是否可以包含其他对象。 值为 TRUE 表示新对象是容器。 值为 FALSE 表示新对象不是容器。
[in] AutoInheritFlags
一组位标志，用于控制如何从 ParentDescriptor 继承访问控制项 (ACE) 。 此参数可以是以下值的组合。
| 值 | 含义 |
|---|---|
|
函数不会检查结果 NewDescriptor 中所有者的有效性，如下面的备注中所述。 如果还设置了SEF_AVOID_PRIVILEGE_CHECK标志，则 Token 参数可以为 NULL。 |
|
将忽略 ParentDescriptor 指定的任何限制，这些限制将限制调用方在 CreatorDescriptor 中指定 DACL 的能力。 |
|
函数不执行权限检查。 如果还设置了SEF_AVOID_OWNER_CHECK标志， 则 Token 参数可以为 NULL。 在实现自动继承时，此标志非常有用，以避免检查每个更新的子级的权限。 |
|
(DACL) 的新 自由访问控制列表 包含从 ParentDescriptor 的 DACL 继承的 ACE，以及在 CreatorDescriptor 的 DACL 中指定的任何显式 ACE。 如果未设置此标志，则新的 DACL 不会继承 ACE。 |
|
CreatorDescriptor 是由 ObjectType 指定的对象类型的默认描述符。 因此，如果 ParentDescriptor 针对 ObjectType 参数指定的对象类型具有任何特定于对象的 ACE，则忽略 CreatorDescriptor。 如果未继承此类 ACE，则 CreatorDescriptor 的处理方式与未指定此标志一样。 |
|
NewDescriptor 组默认为 ParentDescriptor 中的组。 如果未设置， 则 NewDescriptor 组默认为 Token 参数指定的令牌组。 令牌组在令牌本身中指定。 在任一情况下，如果 CreatorDescriptor 参数不为 NULL，则 NewDescriptor 组将设置为 CreatorDescriptor 中的组。 |
|
NewDescriptor 的所有者默认为 ParentDescriptor 中的所有者。 如果未设置， 则 NewDescriptor 的所有者默认为 Token 参数指定的令牌的所有者。 令牌的所有者在令牌本身中指定。 在任一情况下，如果 CreatorDescriptor 参数不为 NULL，则 NewDescriptor 所有者将从 CreatorDescriptor 设置为所有者。 |
|
设置此标志后， CreatorDescriptor 中的必需标签 ACE 不用于在 NewDescriptor 中创建强制标签 ACE。 而是将访问掩码为 SYSTEM_MANDATORY_LABEL_NO_EXECUTE_UP且令牌完整性 SID 中的 SID 的新SYSTEM_MANDATORY_LABEL_ACE添加到 NewDescriptor。 |
|
设置此标志后， CreatorDescriptor 中的必需标签 ACE 不用于在 NewDescriptor 中创建强制标签 ACE。 而是将访问掩码为 SYSTEM_MANDATORY_LABEL_NO_READ_UP且令牌完整性 SID 中的 SID 的新SYSTEM_MANDATORY_LABEL_ACE添加到 NewDescriptor。 |
|
设置此标志后， CreatorDescriptor 中的必需标签 ACE 不用于在 NewDescriptor 中创建强制标签 ACE。 而是将访问掩码为 SYSTEM_MANDATORY_LABEL_NO_WRITE_UP 且令牌完整性 SID 中的 SID 的新SYSTEM_MANDATORY_LABEL_ACE添加到 NewDescriptor。 |
|
新的 系统访问控制列表 (SACL) 包含从 ParentDescriptor 的 SACL 继承的 ACE，以及在 CreatorDescriptor 的 SACL 中指定的任何显式 ACE。 如果未设置此标志，则新的 SACL 不会继承 ACE。 |
[in, optional] Token
代表其创建对象的客户端进程的访问令牌的句柄。 如果这是 模拟令牌，则它必须处于 SecurityIdentification 级别或更高级别。 有关 SecurityIdentification 模拟级别的完整说明，请参阅 SECURITY_IMPERSONATION_LEVEL 枚举类型。
客户端令牌包含默认安全信息，例如默认所有者、主组和 DACL。 如果信息不在输入安全描述符中，则函数使用这些默认值。 令牌必须打开才能 TOKEN_QUERY 访问。
如果满足以下所有条件，则除了 TOKEN_QUERY 访问外，还必须打开句柄才能 进行TOKEN_DUPLICATE 访问。
- 令牌句柄引用主令牌。
- 令牌的安全描述符包含一个或多个具有 OwnerRights SID 的 ACE。
- 为 CreatorDescriptor 参数指定安全描述符。
- 此函数的调用方不会在 AutoInheritFlags 参数中设置SEF_AVOID_OWNER_RESTRICTION标志。
[in] GenericMapping
指向 GENERIC_MAPPING 结构的指针，该结构指定从每个泛型权限到对象特定权限的映射。
返回值
如果函数成功，则函数返回非零值。
如果函数失败，则返回零。 要获得更多的错误信息，请调用 GetLastError。 下表列出了一些扩展错误代码及其含义。
| 返回代码 | 说明 |
|---|---|
|
函数无法检索新安全描述符的所有者，或者无法将 SID 分配为所有者。 针对传入的令牌验证所有者 SID 时，会发生此情况。 |
|
函数无法检索新安全描述符的主组。 |
|
函数收到 NULL ，而不是用于所有者验证或权限检查的令牌。 |
|
正在设置 SACL，SEF_AVOID_PRIVILEGE_CHECK未传入，传入的令牌未启用SE_SECURITY_NAME。 |
注解
CreatePrivateObjectSecurity 函数与调用 CreatePrivateObjectSecurityEx 函数相同，其中 ObjectType 设置为 NULL，AutoInheritFlags 设置为零。
AutoInheritFlags 参数不同于 SECURITY_DESCRIPTOR 结构的 Control 成员中类似命名的位。 有关控制位的说明，请参阅 SECURITY_DESCRIPTOR_CONTROL。
如果 AutoInheritFlags 指定SEF_DACL_AUTO_INHERIT位，则函数会将以下规则应用于新安全描述符中的 DACL：
- SE_DACL_AUTO_INHERITED标志在新的安全描述符的 Control 成员中设置。
- 无论 CreatorDescriptor 是默认安全描述符还是由创建者显式指定，新安全描述符的 DACL 都会从 ParentDescriptor 继承 ACE。 新的 DACL 是继承规则定义的父和创建者 DACL 的组合。
- 继承的 ACE 标记为INHERITED_ACE。
对于 DACL 和 SCL，ParentDescriptor 和 CreatorDescriptor 中的某些类型的 ACE 将被操作，并可能被 NewDescriptor 中的两个 ACE 替换。 具体而言，至少包含以下一个可映射元素的可继承 ACE 可能会导致输出安全描述符中出现两个 ACE。 可映射元素包括：
- ACCESS_MASK中的一般访问权限
- 创建者所有者 SID 或创建者组 SID 作为 ACE 使用者标识符
- ACE，它是原始副本，但设置了INHERIT_ONLY标志。 但是，如果存在以下两个条件之一，则不会创建此 ACE：
- IsContainerObject 参数为 FALSE。 可继承 ACE 对非容器对象毫无意义。
- 原始 ACE 包含 NO_PROPAGATE_INHERIT 标志。 原始 ACE 旨在继承为子级的有效 ACE，但不能继承这些子级。
- 一个有效的 ACE，其中打开INHERITED_ACE位，泛型元素映射到特定元素，包括：
- 通用访问权限由输入 GenericMapping 中指示的相应标准和特定访问权限所取代。
- 创建者所有者 SID 将替换为生成的 NewDescriptor 中的所有者
- 创建者组 SID 替换为生成的 NewDescriptor 中的组
无权访问最终将设置所有者的客户端令牌的调用方可以选择跳过所有者验证检查。
若要为新对象创建安全描述符，请调用 CreatePrivateObjectSecurityEx ，其中 ParentDescriptor 设置为父容器的安全描述符， 将 CreatorDescriptor 设置为对象创建者提出的安全描述符。
如果 CreatorDescriptor 安全描述符包含 SACL， 则 Token 必须启用SE_SECURITY_NAME特权，或者调用方必须在 AutoInheritFlags 中指定SEF_AVOID_PRIVILEGE_CHECK标志。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows XP [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | securitybaseapi.h (包括 Windows.h) |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |