SeAssignSecurity

NTSTATUS
SeAssignSecurity(

IN PSECURITY_DESCRIPTOR ParentDescriptor,/* optional*/
IN PSECURITY_DESCRIPTOR ExplicitDescriptor,
OUT PSECURITY_DESCRIPTOR *NewDescriptor,
IN BOOLEAN IsDirectoryObject,
IN PSECURITY_SUBJECT_CONTEXT SubjectContext,
IN PGENERIC_MAPPING GenericMapping,
IN POOL_TYPE PoolType
);

SeAssignSecurity builds a self-relative security descriptor for a new object, given the security descriptor of its parent directory and any originally requested security for the object.

Parameters

ParentDescriptor

Points to a buffer containing the security descriptor of the parent directory containing the new object being created.

ExplicitDescriptor

Points to a buffer containing the security descriptor specified by the user that is applied to the new object.

NewDescriptor

Receives a pointer to the returned security descriptor for which this routine allocates a buffer according to the given PoolType.

IsDirectoryObject

Specifies whether the new object is a directory object. TRUE indicates the object contains other objects.

SubjectContext

Points to a buffer containing the security context of the subject creating the object. This is used to retrieve default security information for the new object, such as the default owner, the primary group, and discretionary access control.

GenericMapping

Points to an array of access mask values denoting the mapping between each generic right to nongeneric rights.

PoolType

Specifies the pool type to use when allocating a new security descriptor, which can be one of the following:

NonPagedPool
PagedPool
NonPagedPoolMustSucceed
NonPagedPoolCacheAligned
NonPagedPoolCacheAlignedMustS
PagedPoolCacheAligned

Usually, a caller specifies PagedPool, or else NonPagedPool if the buffer will be accessed at raised IRQL in an arbitrary thread context.

Return Value

SeAssignSecurity can return one of the following:

Status Meaning
STATUS_SUCCESS Indicates the operation was successful.
STATUS_INVALID_OWNER The owner SID that was provided as the owner of the target security descriptor is not one the caller is authorized to assign as the owner of an object.
STATUS_PRIVILEGE_NOT_HELD The caller does not have the privilege (SeSecurityPrivilege) necessary to explicitly assign the specified system ACL.

Comments

Network transport drivers call this routine.

The final security descriptor returned to the caller may contain a mix of information, some explicitly provided from the new object’s parent.

SeAssignSecurity assumes privilege checking has not been performed. This routine performs privilege checking.

The assignment of system and discretionary ACLs is governed by the logic illustrated in the following table:

Explicit (nondefault) ACL specified Explicit default ACL specified No ACL specified
Inheritable ACL from parent Assign specified ACL Assign inherited ACL Assign inherited ACL
No inheritable ACL from parent Assign specified ACL Assign default ACL Assign no ACL

An explicitly specified ACL, whether a default ACL or not, can be empty or null. The caller must be a kernel-mode client or be appropriately privileged to explicitly assign a default or nondefault system ACL.

The assignment of the new object’s owner and group is governed by the following logic:

·If the passed security descriptor includes an owner, it is assigned as the new object’s owner. Otherwise, the caller’s token is considered to determine the owner. Within the token, the default owner, if any, is assigned. Otherwise, the caller’s user ID is assigned.

·If the passed security descriptor includes a group, it is assigned as the new object’s group. Otherwise, the caller’s token is considered to determine the group. Within the token, the default group, if any, is assigned. Otherwise, the caller’s primary group ID is assigned.

Callers of SeAssignSecurity must be running at IRQL PASSIVE_LEVEL.

See Also

IoGetFileObjectGenericMapping, SeDeassignSecurity