SetPrivateObjectSecurityEx

[This is preliminary documentation and subject to change.]

The SetPrivateObjectSecurityEx function modifies the security descriptor of a private object. SetPrivateObjectSecurityEx has a flags parameter that allows you to specify whether the protected server supports automatic inheritance of ACEs.

BOOL SetPrivateObjectSecurityEx (
  SECURITY_INFORMATION SecurityInformation, 
                            // type of security information
  PSECURITY_DESCRIPTOR ModificationDescriptor, 
                            // security descriptor with new information
  PSECURITY_DESCRIPTOR *ObjectsSecurityDescriptor, 
                            // object's security descriptor
  ULONG AutoInheritFlags,   // flags that control inheritance of ACEs
  PGENERIC_MAPPING GenericMapping,  // map generic to specific rights
  HANDLE Token                      // handle of client access token
);
 

Parameters

SecurityInformation

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

ModificationDescriptor

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

ObjectsSecurityDescriptor

Pointer to a pointer to a SECURITY_DESCRIPTOR structure. This security descriptor must be in self-relative form.

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.

AutoInheritFlags

A set of bit flags that control 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 flags.

Value	Meaning
SEF_DACL_AUTO_INHERIT	If this flag is set, the DACL is treated as an auto-inherit DACL and is processed as described in the following Remarks section. This bit is ignored if DACL_SECURITY_INFORMATION is not set in the SecurityInformation parameter.
SEF_SACL_AUTO_INHERIT	If this flag is set, the SACL is treated as an auto-inherit SACL and is processed as described in the following Remarks section. This bit is ignored if SACL_SECURITY_INFORMATION is not set in the SecurityInformation parameter.
SEF_AVOID_PRIVILEGE_CHECK	If this flag is set, the Token parameter can be NULL, and the token is not checked to determine if the ModificationDescriptor is valid. This flag is useful while implementing automatic inheritance to avoid checking privileges on each child updated.

GenericMapping

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

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 SID. The token must be open for TOKEN_QUERY access.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

The SetPrivateObjectSecurityEx function is successful only if the following conditions are met:

• 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 must not be impersonating a client.

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 the 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 non-inherited ACEs of ModificationDescriptor. That is, it is impossible to change an inherited ACE by changing the ACL on an object. This behavior preserves the inherited ACEs as they were inherited from the parent container.

  An ACL editor should "gray" inherited ACEs to prevent them from being modified.

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

  Ideally an ACL editor should turn off the INHERITED_ACE bits indicating 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 the ModificationDescriptor, the current security descriptor is ignored. The output security descriptor is built as a copy of the ModificationDescriptor.

  It is the caller's responsibility to ensure that the correct ACEs have the INHERITED_ACE bit turned on and to properly set the SE_DACL_AUTO_INHERITED bit on the ModificationDescriptor.

If AutoInheritFlags specifies the SEF_SACL_AUTO_INHERIT bit, the function applies similar rules to the new SACL.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use advapi32.lib.

See Also

Client/Server Access Control Overview, Client/Server Access Control Functions, CreatePrivateObjectSecurity, DestroyPrivateObjectSecurity, GENERIC_MAPPING, GetPrivateObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetFileSecurity, SetKernelObjectSecurity, SetPrivateObjectSecurity, SetUserObjectSecurity