Skip to content

Commit 2d94d27

Browse files
mhopkins-msftmhopkins-msft
authored
Merge pull request #1650 from justanotheranonymoususer/patch-2
Update nf-fltkernel-fltquerysecurityobject.md: clarify usage
2 parents 39ff53d + ff1f966 commit 2d94d27

File tree

1 file changed

+62
-121
lines changed

1 file changed

+62
-121
lines changed

‎wdk-ddi-src/content/fltkernel/nf-fltkernel-fltquerysecurityobject.md‎

Lines changed: 62 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title: FltQuerySecurityObject function (fltkernel.h)
44
description: FltQuerySecurityObject retrieves a copy of an object's security descriptor.
55
old-location: ifsk\fltquerysecurityobject.htm
66
tech.root: ifsk
7-
ms.date: 04/16/2018
7+
ms.date: 01/09/2026
88
keywords: ["FltQuerySecurityObject function"]
99
ms.keywords: FltApiRef_p_to_z_6fa8f026-1268-4a97-b1e3-a2773e0a1784.xml, FltQuerySecurityObject, FltQuerySecurityObject function [Installable File System Drivers], fltkernel/FltQuerySecurityObject, ifsk.fltquerysecurityobject
1010
req.header: fltkernel.h
@@ -42,164 +42,105 @@ api_name:
4242

4343
# FltQuerySecurityObject function
4444

45-
4645
## -description
4746

48-
<b>FltQuerySecurityObject</b> retrieves a copy of an object's security
49-
descriptor.
47+
**FltQuerySecurityObject** retrieves a copy of an object's security descriptor.
5048

5149
## -parameters
5250

5351
### -param Instance [in]
5452

55-
56-
Opaque instance pointer for the caller. This parameter is required and cannot be
57-
<b>NULL</b>.
53+
Opaque instance pointer for the caller. This parameter is required and cannot be **NULL**.
5854

5955
### -param FileObject [in]
6056

61-
62-
File object pointer for the object whose security descriptor is being queried. This parameter is required
63-
and cannot be <b>NULL</b>.
57+
File object pointer for the object whose security descriptor is being queried. This parameter is required and cannot be **NULL**.
6458

6559
### -param SecurityInformation [in]
6660

61+
[SECURITY_INFORMATION](/windows-hardware/drivers/ifs/security-information) value. This parameter is required and must be one of the following:
6762

68-
69-
<a href="/windows-hardware/drivers/ifs/security-information">SECURITY_INFORMATION</a> value. This parameter is
70-
required and must be one of the following:
71-
72-
<table>
73-
<tr>
74-
<th>SecurityInformation Value</th>
75-
<th>Meaning</th>
76-
</tr>
77-
<tr>
78-
<td>
79-
OWNER_SECURITY_INFORMATION
80-
81-
</td>
82-
<td>
83-
The owner identifier of the object is being queried. Requires <b>READ_CONTROL</b>
84-
access.
85-
86-
</td>
87-
</tr>
88-
<tr>
89-
<td>
90-
GROUP_SECURITY_INFORMATION
91-
92-
</td>
93-
<td>
94-
The primary group identifier of the object is being queried. Requires
95-
<b>READ_CONTROL</b> access.
96-
97-
</td>
98-
</tr>
99-
<tr>
100-
<td>
101-
DACL_SECURITY_INFORMATION
102-
103-
</td>
104-
<td>
105-
The discretionary access control list (DACL) of the object is being queried. Requires
106-
<b>READ_CONTROL</b> access.
107-
108-
</td>
109-
</tr>
110-
<tr>
111-
<td>
112-
SACL_SECURITY_INFORMATION
113-
114-
</td>
115-
<td>
116-
The system ACL (SACL) of the object is being queried. Requires
117-
<b>ACCESS_SYSTEM_SECURITY</b> access.
118-
119-
</td>
120-
</tr>
121-
</table>
63+
| SecurityInformation Value | Meaning |
64+
|---------------------------|---------|
65+
| OWNER_SECURITY_INFORMATION | The owner identifier of the object is being queried. Requires **READ_CONTROL** access. |
66+
| GROUP_SECURITY_INFORMATION | The primary group identifier of the object is being queried. Requires **READ_CONTROL** access. |
67+
| DACL_SECURITY_INFORMATION | The discretionary access control list (DACL) of the object is being queried. Requires **READ_CONTROL** access. |
68+
| SACL_SECURITY_INFORMATION | The system ACL (SACL) of the object is being queried. Requires **ACCESS_SYSTEM_SECURITY** access. |
12269

12370
### -param SecurityDescriptor [in, out]
12471

125-
126-
Pointer to a caller-supplied output buffer that receives a copy of the security descriptor for the
127-
specified object. The <a href="/windows-hardware/drivers/ddi/ntifs/ns-ntifs-_security_descriptor">SECURITY_DESCRIPTOR</a>
128-
structure is returned in self-relative format. This parameter is optional and can be
129-
<b>NULL</b>.
72+
Pointer to a caller-supplied output buffer that receives a copy of the security descriptor for the specified object. The [SECURITY_DESCRIPTOR](/windows-hardware/drivers/ddi/ntifs/ns-ntifs-_security_descriptor) structure is returned in self-relative format. This parameter is optional and can be **NULL**.
13073

13174
### -param Length [in]
13275

133-
134-
Size, in bytes, of the <i>SecurityDescriptor</i> buffer.
76+
Size, in bytes, of the *SecurityDescriptor* buffer.
13577

13678
### -param LengthNeeded [out, optional]
13779

138-
139-
Pointer to a caller-allocated variable that receives the number of bytes required to store the copied
140-
security descriptor returned in the buffer pointed to by the <i>SecurityDescriptor</i>
141-
parameter. This parameter is optional and can be <b>NULL</b>.
80+
Pointer to a caller-allocated variable that receives the number of bytes required to store the copiedsecurity descriptor returned in the buffer pointed to by the *SecurityDescriptor* parameter. This parameter is optional and can be **NULL**. If *SecurityDescriptor* is **NULL**, this parameter receives the required buffer size when the function returns **STATUS_BUFFER_TOO_SMALL**.
14281

14382
## -returns
14483

145-
<b>FltQuerySecurityObject</b> returns STATUS_SUCCESS or an appropriate
146-
<b>NTSTATUS</b> value such as one of the following:
147-
148-
<table>
149-
<tr>
150-
<th>Return code</th>
151-
<th>Description</th>
152-
</tr>
153-
<tr>
154-
<td width="40%">
155-
<dl>
156-
<dt><b>STATUS_ACCESS_DENIED</b></dt>
157-
</dl>
158-
</td>
159-
<td width="60%">
160-
The caller did not have the required access. This is an error code.
161-
162-
</td>
163-
</tr>
164-
<tr>
165-
<td width="40%">
166-
<dl>
167-
<dt><b>STATUS_BUFFER_TOO_SMALL</b></dt>
168-
</dl>
169-
</td>
170-
<td width="60%">
171-
The buffer is too small to contain the security descriptor. None of the security information was copied
172-
to the buffer. This is an error code.
173-
174-
</td>
175-
</tr>
176-
</table>
84+
**FltQuerySecurityObject** returns **STATUS_SUCCESS** or an appropriate **NTSTATUS** value such as one of the following:
85+
86+
| Return code | Description |
87+
|-------------|-------------|
88+
| **STATUS_ACCESS_DENIED** | The caller did not have the required access. This is an error code. |
89+
| **STATUS_BUFFER_TOO_SMALL** | The buffer is too small to contain the security descriptor. None of the security information was copied to the buffer. The required buffer size is returned in the *LengthNeeded* parameter. This is an error code. |
17790

17891
## -remarks
17992

180-
A security descriptor can be in absolute or self-relative form. In self-relative form, all members of the
181-
structure are located contiguously in memory. In absolute form, the structure contains only pointers to its
182-
members.
93+
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 contains only pointers to its members.
18394

184-
The NTFS file system imposes a 64-KB limit on the size of the security descriptor that is written to disk for a
185-
file. (The FAT file system does not support security descriptors for files.) Thus, a 64-KB buffer pointed to by
186-
the <i>SecurityDescriptor</i> parameter is guaranteed to be large enough to hold the returned
187-
<a href="/windows-hardware/drivers/ddi/ntifs/ns-ntifs-_security_descriptor">SECURITY_DESCRIPTOR</a> structure.
95+
The NTFS file system imposes a 64-KB 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 64-KB buffer pointed to by the *SecurityDescriptor* parameter is guaranteed to be large enough to hold the returned [SECURITY_DESCRIPTOR](/windows-hardware/drivers/ddi/ntifs/ns-ntifs-_security_descriptor) structure.
18896

189-
The object that the <i>FileObject</i> parameter points to can represent a named data stream.
190-
For more information about named data streams, see
191-
<a href="/windows-hardware/drivers/ddi/ntifs/ns-ntifs-_file_stream_information">FILE_STREAM_INFORMATION</a>.
97+
The object that the *FileObject* parameter points to can represent a named data stream. For more information about named data streams, see [FILE_STREAM_INFORMATION](/windows-hardware/drivers/ddi/ntifs/ns-ntifs-_file_stream_information).
19298

19399
For more information about security and access control, see the Microsoft Windows SDK documentation.
194100

195-
## -see-also
101+
### Two-Step query pattern
102+
103+
A common usage pattern involves two calls to **FltQuerySecurityObject** to dynamically determine the required buffer size:
104+
105+
#### Step 1: Query the required buffer size
106+
107+
Call the function with a NULL buffer and zero length to obtain the required buffer size:
196108

197-
<a href="/windows-hardware/drivers/ddi/ntifs/ns-ntifs-_file_stream_information">FILE_STREAM_INFORMATION</a>
109+
```cpp
110+
ULONG bytesNeeded;
198111

112+
status = FltQuerySecurityObject(
113+
instance,
114+
fileObj,
115+
securityInfo,
116+
NULL, // SecurityDescriptor - NULL to query size
117+
0, // Length - zero since no buffer provided
118+
&bytesNeeded); // Receives required buffer size
119+
```
199120

121+
This call returns **STATUS_BUFFER_TOO_SMALL** and populates *bytesNeeded* with the required buffer size.
200122

201-
<a href="/windows-hardware/drivers/ddi/ntifs/ns-ntifs-_security_descriptor">SECURITY_DESCRIPTOR</a>
123+
#### Step 2: Allocate and retrieve the security descriptor
202124

125+
Allocate a buffer of the required size and call the function again:
203126

127+
```cpp
128+
secDescriptor = ExAllocatePoolWithTag(PagedPool, bytesNeeded, 'cSeD');
129+
if (secDescriptor != NULL) {
130+
status = FltQuerySecurityObject(
131+
instance,
132+
fileObj,
133+
securityInfo,
134+
secDescriptor, // Allocated buffer
135+
bytesNeeded, // Size from first call
136+
NULL); // LengthNeeded - optional, can be NULL
137+
}
138+
```
139+
140+
The *LengthNeeded* parameter is optional and can be NULL on the second call when retry logic on failure is not needed.
141+
142+
## -see-also
204143

205-
<a href="/windows-hardware/drivers/ifs/security-information">SECURITY_INFORMATION</a>
144+
- [FILE_STREAM_INFORMATION](/windows-hardware/drivers/ddi/ntifs/ns-ntifs-_file_stream_information)
145+
- [SECURITY_DESCRIPTOR](/windows-hardware/drivers/ddi/ntifs/ns-ntifs-_security_descriptor)
146+
- [SECURITY_INFORMATION](/windows-hardware/drivers/ifs/security-information)

0 commit comments

Comments
 (0)