SeAssignSecurityEx function (wdm.h)
The SeAssignSecurityEx routine builds a self-relative security descriptor for a new object given the following optional parameters: a security descriptor of the object's parent directory, an explicit security descriptor for the object, and the object type.
NTSTATUS SeAssignSecurityEx( [in, optional] PSECURITY_DESCRIPTOR ParentDescriptor, [in, optional] PSECURITY_DESCRIPTOR ExplicitDescriptor, [out] PSECURITY_DESCRIPTOR *NewDescriptor, [in, optional] GUID *ObjectType, [in] BOOLEAN IsDirectoryObject, [in] ULONG AutoInheritFlags, [in] PSECURITY_SUBJECT_CONTEXT SubjectContext, [in] PGENERIC_MAPPING GenericMapping, [in] POOL_TYPE PoolType );
[in, optional] ParentDescriptor
Pointer to the SECURITY_DESCRIPTOR of the parent object that contains the new object being created. ParentDescriptor can be NULL, or have a NULL system access control list (SACL) or a NULL discretionary access control list (DACL).
[in, optional] ExplicitDescriptor
Pointer to an explicit SECURITY_DESCRIPTOR that is applied to the new object. ExplicitDescriptor can be NULL, or have a NULL SACL or a NULL DACL.
Receives a pointer to the returned SECURITY_DESCRIPTOR. SeAssignSecurityEx allocates the buffer from the paged memory pool.
[in, optional] ObjectType
Pointer to a GUID for the type of object being created. If the object does not have a GUID, ObjectType must be set to NULL.
Specifies whether the new object is a directory object. If IsDirectoryObject is set to TRUE, the new object is a directory object, otherwise the new object is not a directory object.
Specifies the type of automatic inheritance that is applied to access control entries (ACE) in the access control lists (ACL) specified by ParentDescriptor. AutoInheritFlags also controls privilege checking, owner checking, and setting a default owner and group for NewDescriptor. AutoInheritFlags must be set to a logical OR of one or more of the following values:
|SEF_DACL_AUTO_INHERIT||ACEs in the DACL of ParentDescriptor are inherited by NewDescriptor, in addition to explicit ACEs specified by ExplicitDescriptor.|
|SEF_SACL_AUTO_INHERIT||ACEs in the SACL of ParentDescriptor are inherited by NewDescriptor, in addition to explicit ACEs specified by ExplicitDescriptor.|
|SEF_DEFAULT_DESCRIPTOR_FOR_OBJECT||ExplicitDescriptor is the default descriptor for the object type specified by ObjectType. ExplicitDescriptor is not used if ACEs are inherited from ParentDescriptor.|
|SEF_AVOID_PRIVILEGE_CHECK||Privilege checking is not done. This flag is useful with automatic inheritance because it avoids privilege checking on each child that needs to be updated.|
|SEF_AVOID_OWNER_CHECK||Owner checking is not done.|
If an owner is specified by ExplicitDescriptor, this flag is not used, and the owner of NewDescriptor is set to the owner specified by ExplictDescriptor.
If an owner is not specified by ExplicitDescriptor, this flag is used in the following way: If the flag is set, the owner of NewDescriptor is set to the owner of ParentDescriptor. Otherwise, the owner of NewDescriptor is set to the owner specified by the SubjectContext.
If a group is specified by ExplicitDescriptor, this flag is not used, and the group of NewDescriptor is set to the group specified by ExplictDescriptor.
If a group is not specified by ExplicitDescriptor, this flag is used in the following way: If the flag is set, the group of NewDescriptor is set to the group of ParentDescriptor. Otherwise, the group of NewDescriptor is set to the group specified by the SubjectContext.
The assignment of system and discretionary ACLs is described in the following table:
|Nondefault explicit descriptor(1)||Default explicit descriptor(2)||NULL Explicit descriptor|
|ACL is inherited from parent descriptor(3).||Assign both inherited and explicit ACLs(5)(6).||Assign inherited ACL.||Assign inherited ACL.|
|ACL is not inherited from parent descriptor(4).||Assign nondefault ACL.||Assign default ACL.||Assign no ACL.|
- The SEF_DEFAULT_DESCRIPTOR_FOR_OBJECT flag is not specified.
- The SEF_DEFAULT_DESCRIPTOR_FOR_OBJECT flag is specified.
- The auto inherit flag for an ACL is specified (SEF_DACL_AUTO_INHERIT or SEF_SACL_AUTO_INHERIT).
- The automatic inherit flag for an ACL is not specified.
- ACEs with the INHERITED_ACE bit set in their AceFlags member are not copied to the assigned security descriptor.
- ACEs that are inherited from the parent descriptor are appended after the ACEs specified by the explicit descriptor.
Pointer to a security context of the subject that is creating the object. SubjectContext is used to retrieve default security information for the new object, including the default owner, the primary group, and discretionary access control.
Pointer to an array of access mask values that specify the mapping between each generic rights to object-specific rights.
This parameter is unused. The buffer to hold the new security descriptor is always allocated from paged pool.
SeAssignSecurityEx returns one of the following values:
||The assignment was successful.|
||The SID provided as the owner of the new security descriptor is not a SID that the caller is authorized to assign as the owner of an object.|
||The caller does not have the privilege (SeSecurityPrivilege) necessary to explicitly assign the specified SACL.|
SeAssignSecurityEx extends the basic operation of SeAssignSecurity in the following ways:
- ObjectType optionally specifies an object type. Object-specific inheritance is controlled by the following members of an object-specific ACE: Flags, InheritedObjectType, and Header.AceFlags.
- AutoInheritFlags specifies the type of automatic inheritance of ACEs that is used. AutoInheritFlags also controls privilege checking, owner checking, and setting a default owner and group for NewDescriptor.
|Minimum supported client||Available starting with Windows 2000.|
|Header||wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)|
|DDI compliance rules||HwStorPortProhibitedDDIs(storport)|