NtSetSecurityObject function (ntifs.h)
The NtSetSecurityObject routine sets an object's security state.
Syntax
__kernel_entry NTSYSCALLAPI NTSTATUS NtSetSecurityObject(
[in] HANDLE Handle,
[in] SECURITY_INFORMATION SecurityInformation,
[in] PSECURITY_DESCRIPTOR SecurityDescriptor
);
Parameters
[in] Handle
Handle for the object whose security state is to be set. This handle must have the access specified in the Meaning column of the table shown in the description of the SecurityInformation parameter.
[in] SecurityInformation
SECURITY_INFORMATION value specifying the information to be set as a combination of one or more of the following.
| Value | Meaning |
|---|---|
| OWNER_SECURITY_INFORMATION | Indicates the owner identifier of the object is to be set. Requires WRITE_OWNER access. |
| GROUP_SECURITY_INFORMATION | Indicates the primary group identifier of the object is to be set. Requires WRITE_OWNER access. |
| SACL_SECURITY_INFORMATION | Indicates the system ACL (SACL) of the object is to be set. Requires ACCESS_SYSTEM_SECURITY access. |
| DACL_SECURITY_INFORMATION | Indicates the discretionary access control list (DACL) of the object is to be set. Requires WRITE_DAC access. |
[in] SecurityDescriptor
Pointer to the security descriptor to be set for the object.
Return value
NtSetSecurityObject returns STATUS_SUCCESS or an appropriate error status. Possible error status codes include the following:
| Return code | Description |
|---|---|
| STATUS_ACCESS_DENIED | The caller did not have the required access. |
| STATUS_ACCESS_VIOLATION | SecurityDescriptor was a NULL pointer. |
| STATUS_INSUFFICIENT_RESOURCES | The object's security descriptor could not be captured. |
| STATUS_INVALID_ACL | The object's security descriptor contained an invalid ACL. |
| STATUS_INVALID_HANDLE | Handle is not a valid handle. |
| STATUS_INVALID_SECURITY_DESCR | SecurityDescriptor did not point to a valid security descriptor. |
| STATUS_INVALID_SID | The object's security descriptor contained an invalid SID. |
| STATUS_OBJECT_TYPE_MISMATCH | Handle is not a handle of the expected type. |
| STATUS_UNKNOWN_REVISION | The revision level of the object's security descriptor was unknown or not supported. |
Remarks
A security descriptor can be in absolute or self-relative form. In self-relative form, all members of the structure are located contiguously in memory. In absolute form, the structure only contains pointers to the members. For more information, see Absolute and Self-Relative Security Descriptors.
For more information about security and access control, see Windows security model for driver developers and the documentation on these topics in the Windows SDK.
Minifilters should use FltSetSecurityObject instead of NtSetSecurityObject.
Callers of NtSetSecurityObject must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.
Note
If the call to the NtSetSecurityObject function occurs in user mode, you should use the name "NtSetSecurityObject" instead of "ZwSetSecurityObject".
For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP |
| Target Platform | Universal |
| Header | ntifs.h (include Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (see Remarks section) |
| DDI compliance rules | HwStorPortProhibitedDDIs, PowerIrpDDis |
See also
Using Nt and Zw Versions of the Native System Services Routines