NtQuerySecurityObject - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTOBAPI_H
//
// Objects, handles
//
#if (PHNT_MODE != PHNT_MODE_KERNEL)

/**
 * The NtQuerySecurityObject routine retrieves a copy of an object's security descriptor.
 *
 * @param Handle Handle for the object whose security descriptor is to be queried. 
 * @param SecurityInformation A SECURITY_INFORMATION value specifying the information to be queried.
 * @param SecurityDescriptor Caller-allocated buffer that NtQuerySecurityObject fills with a copy of the specified security descriptor.
 * @param Length Size, in bytes, of the buffer pointed to by SecurityDescriptor.
 * @param LengthNeeded Pointer to a caller-allocated variable that receives the number of bytes required to store the copied security descriptor.
 * @return NTSTATUS Successful or errant status.
 * @sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntquerysecurityobject
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtQuerySecurityObject(
    _In_ HANDLE Handle,
    _In_ SECURITY_INFORMATION SecurityInformation,
    _Out_writes_bytes_to_opt_(Length, *LengthNeeded) PSECURITY_DESCRIPTOR SecurityDescriptor,
    _In_ ULONG Length,
    _Out_ PULONG LengthNeeded
    );

#endif
#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwQuerySecurityObject(
    _In_ HANDLE Handle,
    _In_ SECURITY_INFORMATION SecurityInformation,
    _Out_writes_bytes_to_opt_(Length, *LengthNeeded) PSECURITY_DESCRIPTOR SecurityDescriptor,
    _In_ ULONG Length,
    _Out_ PULONG LengthNeeded
    );

#endif

View code on GitHub
// ntifs.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtQuerySecurityObject(
  [in]  HANDLE               Handle,
  [in]  SECURITY_INFORMATION SecurityInformation,
  [out] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in]  ULONG                Length,
  [out] PULONG               LengthNeeded
);
View the official Windows Driver Kit DDI reference
// ntifs.h

NTSYSAPI NTSTATUS ZwQuerySecurityObject(
  [in]  HANDLE               Handle,
  [in]  SECURITY_INFORMATION SecurityInformation,
  [out] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in]  ULONG                Length,
  [out] PULONG               LengthNeeded
);
View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntifs-ntquerysecurityobject)

NtQuerySecurityObject function

Description

The NtQuerySecurityObject routine retrieves a copy of an object's security descriptor.

Parameters

Handle [in]

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.

SecurityInformation [in]

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.

SecurityDescriptor [out]

Caller-allocated buffer that NtQuerySecurityObject fills with a copy of the specified security descriptor. The SECURITY_DESCRIPTOR structure is returned in self-relative format.

Length [in]

Size, in bytes, of the buffer pointed to by SecurityDescriptor.

LengthNeeded [out]

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 Nt*Xxx* and Zw*Xxx* 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 Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

FltQuerySecurityObject

SECURITY_DESCRIPTOR

SECURITY_INFORMATION

NtSetSecurityObject

View the official Windows Driver Kit DDI reference

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntifs-zwquerysecurityobject)

ZwQuerySecurityObject function

Description

The ZwQuerySecurityObject routine retrieves a copy of an object's security descriptor.

Parameters

Handle [in]

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.

SecurityInformation [in]

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.

SecurityDescriptor [out]

Caller-allocated buffer that ZwQuerySecurityObject fills with a copy of the specified security descriptor. The SECURITY_DESCRIPTOR structure is returned in self-relative format.

Length [in]

Size, in bytes, of the buffer pointed to by SecurityDescriptor.

LengthNeeded [out]

Pointer to a caller-allocated variable that receives the number of bytes required to store the copied security descriptor.

Return value

ZwQuerySecurityObject 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

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.

Minifilters should call FltQuerySecurityObject instead of ZwQuerySecurityObject.

[!NOTE] If the call to the ZwQuerySecurityObject function occurs in user mode, you should use the name "NtQuerySecurityObject" instead of "ZwQuerySecurityObject".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* 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 Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

FltQuerySecurityObject

SECURITY_DESCRIPTOR

SECURITY_INFORMATION

ZwSetSecurityObject

View the official Windows Driver Kit DDI reference

Edit description on GitHub

NTinternals.net (undocumented.ntinternals.net)

This function is documented in Windows Driver Kit here and here.

Function NtQuerySecurityObject retrieve object's Security Descriptor.

ObjectHandle

HANDLE to any object opened with READ_CONTROL access.

SecurityInformationClass

Can be combination of:

DescriptorBuffer

Result of call - pointer to SECURITY_DESCRIPTOR structure.

DescriptorBufferLength

Size of buffer, in bytes.

RequiredLength

Pointer to value receiving required length of buffer.

Documented by

See also

Edit description on GitHub