TokenHasRestrictions: documented DWORD vs observed one-byte output

[KRYST4LBEI]

I am asking for Win32 output-type/documentation guidance, not reporting a confirmed win32metadata bug. Please redirect this question if another team or repository owns the contract.

The Microsoft TOKEN_INFORMATION_CLASS documentation describes TokenHasRestrictions (class 21) as returning a DWORD. In one completed read-only Windows x64 diagnostic, both GetTokenInformation calls succeeded with a four-byte output buffer but reported ReturnLength = 1:

Call	Capacity	Bytes before	Bytes after	ReturnLength	Native BOOL
A	4	A5 A5 A5 A5	00 A5 A5 A5	1	1
B	4	5A 5A 5A 5A	00 5A 5A 5A	1	1

Each output and ReturnLength occupied the aligned middle DWORD of a separate 20-byte allocation, with eight guard bytes on either side. Guards stayed intact. The same current-process primary token was opened with TOKEN_QUERY only. Four complete TokenStatistics observations matched across the experiment. No privilege or security-setting changes were made.

Environment: Windows x64, 64-bit CPython 3.12.14, elevated interactive local context; PowerShell 7.6.5 launched the diagnostic. The binding was ctypes.WinDLL("advapi32.dll", use_last_error=True, winmode=0x800), with [HANDLE(void*), int32, void*, uint32, uint32*] -> int32 BOOL. DWORD/BOOL sizes were checked as 4, pointer size as 8. The exact Windows edition/build was NOT recorded and is not inferred. This is a description of the completed experiment, not an independently compiled C/C++ reproduction.

Only offset 0 visibly changed. Offsets 1-3 retained different caller-initialized patterns and have not been treated as valid returned DWORD bytes. We do not infer a universal one-byte ABI or the exact physical write count. The seeded last-error value was unchanged after success and was not interpreted as a failure.

Questions:

1. Is the supported output a fully initialized four-byte DWORD, or does the documented type need correction?
2. When success reports ReturnLength = 1 with capacity 4, which bytes are valid to consume? Does ReturnLength specify required capacity, initialized extent, or both?
3. Where is the authoritative type/byte-validity contract and its applicable Windows versions/architectures?
4. Does the query retain its documented "filtered at some point" meaning? IsTokenRestricted, empty RestrictedSids, elevation and AppContainer status are not assumed equivalent.

No one-byte compatibility rule has been adopted. Only sanitized observations are included; no account names, private SIDs, local paths, token identifiers, credentials or raw security records.

Official references:
https://learn.microsoft.com/en-us/windows/win32/api/winnt/ne-winnt-token_information_class
https://learn.microsoft.com/en-us/windows/win32/api/securitybaseapi/nf-securitybaseapi-gettokeninformation

[KRYST4LBEI]

Adding a standalone C++ source draft for review (attached), to make the earlier TokenHasRestrictions observation easier to inspect independently of Python.

Status: NOT BUILT / NOT NATIVE-TESTED. The previously reported measurements did not come from this source.

Known draft limitation: same_stats() compares ImpersonationLevel even for a primary token. That comparison needs correction before this can be considered a ready-to-run reproduction.

The attached source is preserved unchanged. I am seeking clarification of the supported class-21 output layout and valid initialized bytes when a successful call reports ReturnLength=1 with a four-byte buffer. No one-byte compatibility rule has been adopted.

class21_repro_20260914.cpp.txt

[Jevan Saks (jevansaks)]

Based on some internal discussion, it sounds like the documentation is wrong and should say that it returns BOOLEAN but that the BOOLEAN pointer must be DWORD-aligned. If you would like to file an issue in this repo or on the docs, that will help us track getting it fixed.

[KRYST4LBEI]

Thanks, Jevan — the distinction between a BOOLEAN payload and DWORD pointer alignment is helpful and consistent with our saved observation.

Our completed Windows x64 test used a DWORD-aligned four-byte output buffer. Both calls succeeded with ReturnLength == 1:

A5 A5 A5 A5 -> 00 A5 A5 A5
5A 5A 5A 5A -> 00 5A 5A 5A

We have prepared an aligned BOOLEAN-decoding candidate, but its new native validation has not run yet. The standalone C++ source attached earlier also remains unbuilt and unexecuted.

For the documentation issue you suggested, could you clarify two points?

1. With a DWORD-aligned output address and four-byte buffer capacity, should a successful class-21 call report ReturnLength == 1, with only the first BOOLEAN byte valid to consume and the remaining bytes not part of the returned value?

2. Is this a correction describing existing behavior across supported Windows versions and architectures, or are there known version/architecture qualifications we should document?

The documentation issue draft is ready but has not been filed yet. Your clarification will help us describe the intended contract accurately. Thank you for checking internally.

[Jevan Saks (jevansaks)]

1. That sounds right.
2. I expect this is going to be consistent across versions.

Your observed behavior should be documented as the behavior. Any deviation is going to be a bug in the docs, not in the implementation. Thanks!

[KRYST4LBEI]

Hi Jevan — thank you again for your help on the class-21 / GetTokenInformation question in this thread.

A related Windows security investigation has now surfaced a different Win32 API question, and I wanted to ask whether you are the right person to point us to the appropriate venue before opening a new discussion.

Using SetFileSecurityW on a synthetic test directory, we set DACL_SECURITY_INFORMATION | PROTECTED_DACL_SECURITY_INFORMATION (0x80000004). The call succeeds and the resulting DACL bytes are exactly what we intended, but the SECURITY_DESCRIPTOR_CONTROL values change in a way we have not been able to explain from the public documentation:

• baseline: 0x8404
• expected by our contract: 0x9404
• observed with owner/group/DACL query: 0x9004
• observed with BACKUP_SECURITY_INFORMATION: 0xb004

In other words, SE_DACL_PROTECTED is set as intended, but SE_DACL_AUTO_INHERITED (0x0400) disappears; the backup-security view also reports SE_SACL_PROTECTED (0x2000), while the SACL bytes themselves are unchanged.

We are not asking whether our failed test should be treated as a pass. We are trying to establish two things authoritatively:

1. Whether these control-bit changes are expected/defined behavior for SetFileSecurityW / the underlying file-security provider.
2. Whether restoring only the original DACL/protection state is sufficient to reproduce the original control state exactly, or whether other security-information/control operations are required.

The test is fully synthetic and we can provide a minimal reproduction without private project data.

Would you recommend opening a new discussion here, a MicrosoftDocs/sdk-api issue, or another Windows security API support channel? If you are the right contact, I’m happy to post the minimal repro in a separate thread rather than mixing it into #2308.

[Jevan Saks (jevansaks)]

Instead of a discussion I'd recommend filing an issue in the docs repo.