SeAssignSecurity function (wdm.h)
The SeAssignSecurity routine 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.
Syntax
NTSTATUS SeAssignSecurity(
[in, optional] PSECURITY_DESCRIPTOR ParentDescriptor,
[in, optional] PSECURITY_DESCRIPTOR ExplicitDescriptor,
[out] PSECURITY_DESCRIPTOR *NewDescriptor,
[in] BOOLEAN IsDirectoryObject,
[in] PSECURITY_SUBJECT_CONTEXT SubjectContext,
[in] PGENERIC_MAPPING GenericMapping,
[in] POOL_TYPE PoolType
);
Parameters
[in, optional] ParentDescriptor
Pointer to a buffer containing the SECURITY_DESCRIPTOR for the parent directory, if any, containing 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 a buffer containing the SECURITY_DESCRIPTOR specified by the user that is applied to the new object. ExplicitDescriptor can be NULL, or have a NULL SACL or a NULL DACL.
[out] NewDescriptor
Receives a pointer to the returned SECURITY_DESCRIPTOR. SeAssignSecurity allocates the buffer from the paged memory pool.
[in] IsDirectoryObject
Specifies whether the new object is a directory object. TRUE indicates the object contains other objects.
[in] SubjectContext
Pointer 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.
[in] GenericMapping
Pointer to the GENERIC_MAPPING structure that describes the mapping from each generic right to the implied nongeneric rights.
[in] PoolType
This parameter is unused. The buffer to hold the new security descriptor is always allocated from paged pool.
Return value
SeAssignSecurity can return one of the following:
| Return code | Description |
|---|---|
|
The assignment was successful. |
|
The SID provided for the owner of the target security descriptor is not one 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 system ACL. |
Remarks
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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows 2000 and later versions of Windows. |
| Target Platform | Universal |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI compliance rules | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |