ConvertToAutoInheritPrivateObjectSecurity

[This is preliminary documentation and subject to change.]

The ConvertToAutoInheritPrivateObjectSecurity function converts a security descriptor and its ACLs to a format that supports automatic propagation of inheritable ACEs.

BOOL ConvertToAutoInheritPrivateObjectSecurity(
  PSECURITY_DESCRIPTOR ParentDescriptor, 
                            // security descriptor of parent object
  PSECURITY_DESCRIPTOR CurrentSecurityDescriptor, 
                            // current security descriptor of object
  PSECURITY_DESCRIPTOR * NewSecurityDescriptor, 
                            // receives new security descriptor
  GUID * ObjectType,        // type of object
  BOOLEAN IsDirectoryObject,       // identifies container objects
  PGENERIC_MAPPING GenericMapping  // map generic to specific rights
);
 

Parameters

ParentDescriptor

Pointer to the security descriptor for the parent container of the object. If there is no parent container, this parameter is NULL.

CurrentSecurityDescriptor

Pointer to the current security descriptor of the object.

NewSecurityDescriptor

Pointer to a variable that receives a pointer to the newly allocated self-relative security descriptor. It is the caller's responsibility to call the DestroyPrivateObjectSecurity function to free this security descriptor.

ObjectType

Pointer to a GUID structure that identifies the type of object associated with CurrentSecurityDescriptor. Set ObjectType to NULL if the object does not have a GUID.

IsDirectoryObject

Specifies whether the new object can contain other objects. A value of TRUE indicates that the new object is a container. A value of FALSE indicates that the new object is not a container.

GenericMapping

Pointer to a GENERIC_MAPPING structure that specifies the mapping from each generic right to specific rights for the object.

Remarks

The ConvertToAutoInheritPrivateObjectSecurity function attempts to determine whether the ACEs in the DACL and SACL of the current security descriptor were inherited from the parent security descriptor. The function passes the ParentDescriptor parameter to the CreatePrivateObjectSecurityEx function to get ACLs that contain only inherited ACEs. Then it compares these ACEs to the ACEs in the original security descriptor to determine which of the original ACEs were inherited. The ACEs do not need to match one-to-one. For instance, an ACE that allows read and write access to a trustee can be equivalent to two ACEs: an ACE that allows read access and an ACE that allows write access.

Any ACEs in the original security descriptor that are equivalent to the ACEs inherited from the parent security descriptor are marked with the INHERITED_ACE flag and added to the new security descriptor. All other ACEs in the original security descriptor are added to the new security descriptor as noninherited ACEs.

If the original DACL does not have any inherited ACEs, the function sets the SE_DACL_PROTECTED flag in the control bits of the new security descriptor. Similarly, the SE_SACL_PROTECTED flag is set if none of the ACEs in the SACL is inherited.

For DACLs that have inherited ACEs, the function reorders the ACEs into two groups. The first group has ACEs that were directly applied to the object. The second group has inherited ACEs. This ordering ensures that noninherited ACEs have precedence over inherited ACEs. For more information, see Order of ACEs in a DACL.

The function sets the SE_DACL_AUTO_INHERITED and SE_SACL_AUTO_INHERITED flags in the control bits of the new security descriptor.

The function does not change the ordering of access-allowed ACEs in relation to access-denied ACEs in the DACL, because to do so would change the semantics of the resulting security descriptor. If the function cannot convert the DACL without changing the semantics, it leaves the DACL unchanged and sets the SE_DACL_PROTECTED flag.

The new security descriptor has the same owner and primary group as the original security descriptor.

The new security descriptor is equivalent to the original security descriptor, so the caller needs no access rights or privileges to update the security descriptor to the new format.

This function works with ACL_REVISION and ACL_REVISION_DS ACLs.

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, CreatePrivateObjectSecurityEx, GENERIC_MAPPING