NtQuerySecurityObject function (ntifs.h)
The NtQuerySecurityObject routine retrieves a copy of an object's security descriptor.
Syntax
__kernel_entry NTSYSCALLAPI NTSTATUS NtQuerySecurityObject(
[in] HANDLE Handle,
[in] SECURITY_INFORMATION SecurityInformation,
[out] PSECURITY_DESCRIPTOR SecurityDescriptor,
[in] ULONG Length,
[out] PULONG LengthNeeded
);
Parameters
[in] Handle
Handle for the object whose security descriptor is to be queried. This handle must have the access specified in the Meaning column of the table shown in the description of the SecurityInformation parameter.
[in] SecurityInformation
A SECURITY_INFORMATION value specifying the information to be queried as a combination of one or more of the following.
| Value | Meaning |
|---|---|
| OWNER_SECURITY_INFORMATION | The object's owner identifier is being queried. Requires READ_CONTROL access. |
| GROUP_SECURITY_INFORMATION | The object's primary group identifier is being queried. Requires READ_CONTROL access. |
| SACL_SECURITY_INFORMATION | The object's system ACL (SACL) is being queried. Requires ACCESS_SYSTEM_SECURITY access. |
| DACL_SECURITY_INFORMATION | The object's discretionary access control list (DACL) is being queried. Requires READ_CONTROL access. |
[out] SecurityDescriptor
Caller-allocated buffer that NtQuerySecurityObject fills with a copy of the specified security descriptor. The SECURITY_DESCRIPTOR structure is returned in self-relative format.
[in] Length
Size, in bytes, of the buffer pointed to by SecurityDescriptor.
[out] LengthNeeded
Pointer to a caller-allocated variable that receives the number of bytes required to store the copied security descriptor.
Return value
NtQuerySecurityObject returns STATUS_SUCCESS or an appropriate error status. Possible error status codes include the following:
| Return code | Description |
|---|---|
| STATUS_ACCESS_DENIED | Handle did not have the required access. |
| STATUS_BUFFER_TOO_SMALL | The buffer is too small for the security descriptor. None of the security information was copied to the buffer. |
| STATUS_INVALID_HANDLE | Handle was not a valid handle. |
| STATUS_OBJECT_TYPE_MISMATCH | Handle was not a handle of the expected type. |
Remarks
Minifilters should call FltQuerySecurityObject.
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.
The NTFS file system imposes a 64K limit on the size of the security descriptor that is written to disk for a file. (The FAT file system does not support security descriptors for files.) Thus a 64K SecurityDescriptor buffer is guaranteed to be large enough to hold the returned SECURITY_DESCRIPTOR structure.
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.
Note
If the call to the NtQuerySecurityObject function occurs in user mode, you should use the name "NtQuerySecurityObject" instead of "ZwQuerySecurityObject".
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 |
| DDI compliance rules | HwStorPortProhibitedDDIs, PowerIrpDDis |