Export (0) Print
Expand All

ZwQuerySecurityObject routine

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

Syntax


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

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]

Pointer to a SECURITY_INFORMATION value specifying the information to be queried.

ValueMeaning

DACL_SECURITY_INFORMATION

Indicates the discretionary access control list (DACL) of the object is being queried. Requires READ_CONTROL access.

GROUP_SECURITY_INFORMATION

Indicates the primary group identifier of the object is being queried. Requires READ_CONTROL access.

OWNER_SECURITY_INFORMATION

Indicates the owner identifier of the object is being queried. Requires READ_CONTROL access.

SACL_SECURITY_INFORMATION

Indicates the system ACL (SACL) of the object is being queried. Requires ACCESS_SYSTEM_SECURITY 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 codeDescription
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.

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 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".

Requirements

Version

Available in Windows XP and later versions of Windows.

Header

Ntifs.h (include Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

DDI compliance rules

PowerIrpDDis, HwStorPortProhibitedDDIs

See also

FltQuerySecurityObject
SECURITY_DESCRIPTOR
SECURITY_INFORMATION
ZwSetSecurityObject

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft