SetPrivateObjectSecurityEx function (securitybaseapi.h)

The SetPrivateObjectSecurityEx function modifies the security descriptor of a private object maintained by the resource manager calling this function. The SetPrivateObjectSecurityEx function has a flags parameter that specifies whether the resource manager supports automatic inheritance of access control entries (ACEs).

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

The parts of the security descriptor to set. This value can be a combination of the SECURITY_INFORMATION bit flags.

[in] ModificationDescriptor

A pointer to a SECURITY_DESCRIPTOR structure. The parts of this security descriptor indicated by the SecurityInformation parameter are applied to the ObjectsSecurityDescriptor security descriptor.

[in, out] ObjectsSecurityDescriptor

A pointer to a pointer to a SECURITY_DESCRIPTOR structure. This security descriptor must be in self-relative form. The memory for the security descriptor must be allocated from the process heap (GetProcessHeap) with the HeapAlloc function.

On input, this is the current security descriptor of the private object. The function modifies it to produce the new security descriptor. If necessary, the SetPrivateObjectSecurityEx function allocates additional memory to produce a larger security descriptor.

[in] AutoInheritFlags

Specifies automatic inheritance of ACEs. If the protected server does not implement automatic inheritance, it should specify zero; otherwise, it can specify a combination of the following values, defined in Winnt.h.

[in] GenericMapping

A pointer to a GENERIC_MAPPING structure that specifies the specific and standard access rights that correspond to each of the generic access rights.

[in, optional] Token

Identifies the access token for the client on whose behalf the private object's security is being modified. This parameter is required to ensure that the client has provided a legitimate value for a new owner security identifier (SID). The token must be open for TOKEN_QUERY access.

If the function succeeds, the function returns nonzero.

If the function fails, it returns zero. To get extended error information, call GetLastError.

If the AutoInheritFlags parameter is zero, SetPrivateObjectSecurityEx is identical to the SetPrivateObjectSecurity function.

This function is intended for use by resource managers only. To implement the standard Windows access control semantics for updating security descriptors, a resource manager should verify that the following conditions are met before calling SetPrivateObjectSecurityEx:

• If the object's owner is being set, the calling process must have either WRITE_OWNER permission or be the object's owner.
• If the object's DACL is being set, the calling process must have either WRITE_DAC permission or be the object's owner.
• If the object's SACL is being set, the SE_SECURITY_NAME privilege must be enabled for the calling process.

The process calling this function should not be impersonating a client because clients do not typically have appropriate privileges required for underlying token operations.

If AutoInheritFlags specifies the SEF_DACL_AUTO_INHERIT bit, the function applies the following rules to the DACL to create the new security descriptor from the current descriptor:

• If the SE_DACL_PROTECTED flag is not set in the control bits of either the current security descriptor or the ModificationDescriptor, the function constructs the output security descriptor from the inherited ACEs of the current security descriptor and noninherited ACEs of ModificationDescriptor. That is, it is impossible to change an inherited ACE by changing the access control list (ACL) on an object. This behavior preserves the inherited ACEs as they were inherited from the parent container.

  An ACL editor should make inherited ACEs unavailable to prevent them from being modified.

• If SE_DACL_PROTECTED is set in ModificationDescriptor, the current security descriptor is ignored. The output security descriptor is built as a copy of ModificationDescriptor with any INHERITED_ACE bits turned off.

  Ideally an ACL editor should turn off the INHERITED_ACE bits that indicate to its caller that the ACEs inherited from the object's parent are now being explicitly set on the object.

• If SE_DACL_PROTECTED is set in the current security descriptor and not in ModificationDescriptor, the current security descriptor is ignored. The output security descriptor is built as a copy of ModificationDescriptor. It is the caller's responsibility to ensure that the correct ACEs have the INHERITED_ACE bit turned on.

For both DACLs and SACLs, certain types of ACEs in the input ObjectsSecurityDescriptor and in ModificationDescriptor will be replaced by two ACEs in the output ObjectsSecurityDescriptor. Specifically, an inheritable ACE that contains at least one of the following mappable elements will result in two ACEs in the output ObjectsSecurityDescriptor. Mappable elements include:

• Generic access rights in the ACCESS_MASK structure
• Creator Owner SID or Creator Group SID as the ACE subject identifier

• An ACE that is a copy of the original, but with the INHERIT_ONLY flag set
• An ACE in which the INHERITED_ACE bit is turned on and the generic elements are mapped to specific elements:
  • Generic access rights are replaced by the corresponding standard and specific access rights indicated in the input GenericMapping.
  • Creator Owner SID is replaced with the Owner in the output SecurityDescriptor
  • Creator Group SID is replaced with the Group in the output SecurityDescriptor

• Must be a legally formed SID
• Must match the TokenUser in Token

• Must match a group in the TokenGroups in Token where the attributes on the group:
  • Include SE_GROUP_OWNER
  • Include SE_GROUP_USE_FOR_DENY_ONLY

ACCESS_MASK

Client/Server Access Control Functions

Client/Server Access Control Overview

CreatePrivateObjectSecurityEx

DestroyPrivateObjectSecurity

GENERIC_MAPPING

GetPrivateObjectSecurity

SECURITY_DESCRIPTOR

SECURITY_INFORMATION

SetFileSecurity

SetKernelObjectSecurity

SetPrivateObjectSecurity

SetUserObjectSecurity