Peios Common Data Structures

This document defines the common binary data structures shared across Peios subsystems: three identifier types — the Globally Unique Identifier (GUID), the Locally Unique Identifier (LUID), and the Security Identifier (SID) — and the Security Descriptor (SD) family.

This document covers:

• GUID — binary format, string representation, comparison semantics, and generation requirements
• LUID — binary format, comparison semantics, and allocation model
• SID — binary format, string representation, comparison semantics, and the well-known SID catalogue
• SD — the security descriptor structure and its subtypes: ACL and ACE formats, access masks, ACE ordering, inheritance, ownership, conditional ACEs and their bytecode, claim attributes, and resource attributes

This document does not cover:

• Well-known GUID and LUID values — defined in the specifications of the subsystems that declare them
• SID-bearing aggregate structures such as SID_AND_ATTRIBUTES — described in the Peios Kernel TRM §3.2.2
• The access-check algorithm that evaluates these structures — described in the Peios Kernel TRM §3.8
• Per-object-type SD storage locations — described in the Peios Kernel TRM §3.3.3 for processes and §3.9.5 for files
• Application-specific identifier namespaces

Three of those exclusions point at a manual rather than at another specification, which is deliberate and worth stating once. KACS — the kernel's access-control implementation — is described in the Peios Kernel TRM §3 and is not separately specified. Peios does not offer a standard from which a second, independent access-control implementation could be built; it offers a manual describing the one that exists.

What a third party does need is the other half: the structures that cross the boundary into that implementation, and the rules for reading and writing them. That is this document, and it is specified. Where a structure's meaning depends on what KACS does with it, this document names the manual article that describes the behaviour rather than restating it (Conventions §4.7).

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119. Text set off as a note is informative, not normative.

Everything else — roles, byte order, sizes, layout tables, notation, strings, timestamps, citation, and the external standards this anthology depends on — is defined in the Conventions book and is not restated here. PCDS departs from none of it.

Where a chapter needs a convention of its own, that chapter states it.

A GUID (Globally Unique Identifier) is a 128-bit identifier with global uniqueness guarantees, used to identify registry hives, layers, object types, and other entities that require stable identity across systems and reboots. The GUID with all 128 bits set to zero is the nil GUID, a sentinel value meaning "no GUID" or "unset."

A GUID is a 128-bit (16-byte) value with the following binary layout:

The total size of a GUID MUST be exactly 16 bytes with no padding.

Data1, Data2, and Data3 MUST be stored in little-endian byte order.

Data4 is a raw byte array with no endianness interpretation.

2.1.1 Nil GUID #

The nil GUID is the GUID with all 16 bytes set to zero.

The nil GUID is a valid GUID value. Specifications that require a non-nil GUID MUST state this requirement explicitly.

The nil GUID MUST NOT be produced by the generation algorithm defined in §2.4.

2.2.1 Canonical form #

The canonical string representation of a GUID MUST use the following format:

{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

The string MUST be exactly 38 characters: an opening brace, 32 hex digits arranged in 8-4-4-4-12 groups separated by hyphens, and a closing brace.

The fields map to the string as follows:

For Data1, Data2, and Data3, the hex representation is of the numeric value (most significant nibble first), not of the stored byte order. For Data4, each byte is encoded in sequence with the high nibble before the low nibble.

2.2.2 Case #

Canonical output MUST use lowercase hex digits (a–f).

2.2.3 Parsing #

Parsers MUST accept both uppercase and lowercase hex digits.

Parsers MUST accept the braced form {...} and SHOULD accept the unbraced form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Parsers MUST reject strings that do not have exactly the right number of hex digits in each group.

2.3.1 Equality #

Two GUIDs are equal if and only if their 16-byte binary representations are identical.

GUID comparison MUST be performed on the binary representation, not on string representations.

2.3.2 Ordering #

This document does not define a total ordering for GUIDs. Specifications that require an ordered GUID collection MUST define their ordering convention explicitly.

GUIDs generated by Peios MUST be version 4 (random) as defined in RFC 4122 §4.4.

2.4.1 Algorithm #

To generate a version 4 GUID:

1. Fill all 16 bytes with cryptographically random data.
2. Set the four most significant bits of Data3 to 0100 (version 4).
3. Set the two most significant bits of Data4[0] to 10 (RFC 4122 variant).

The resulting GUID has 122 random bits, 4 version bits, and 2 variant bits.

2.4.2 Randomness source #

The random data MUST be obtained from a cryptographically secure source.

In the kernel, this MUST be get_random_bytes() or equivalent.

In userspace, this MUST be getrandom(2) with no flags (blocking until the entropy pool is initialised) or equivalent.

GUIDs MUST NOT be generated using a pseudorandom number generator seeded from a predictable source.

2.A.1 MS-DTYP #

The GUID type defined in this document derives from the Microsoft Data Types specification (MS-DTYP), §2.3.4. The Peios GUID binary format is identical to the MS-DTYP GUID. The Peios GUID string format follows the same hyphenated hex convention but normalises to lowercase hex digits on output, where Microsoft implementations typically produce uppercase.

2.A.2 RFC 4122 #

RFC 4122 ("A Universally Unique IDentifier (UUID) URN Namespace") defines the UUID format and generation algorithms. The GUID binary layout used by Microsoft and adopted by Peios is the mixed-endian variant of the RFC 4122 UUID: the first three fields are little-endian integers and the last field is a raw byte array. This differs from the RFC 4122 network byte order representation where all fields are big-endian.

Peios generates version 4 (random) GUIDs as defined in RFC 4122 §4.4.

2.A.3 DCE RPC #

The GUID structure originates from the DCE 1.1 RPC specification, which defined the uuid_t type with the same field layout. The mixed-endian encoding reflects the DCE convention of encoding integer fields in the sender's native byte order (little-endian on x86).

An LUID (Locally Unique Identifier) is a 64-bit identifier with boot-scoped local uniqueness, used to identify transient entities such as logon sessions and privilege instances that do not persist across reboots. The LUID with all 64 bits set to zero is the nil LUID, a sentinel value meaning "no LUID" or "unset."

An LUID is a 64-bit (8-byte) value with the following binary layout:

The total size of an LUID MUST be exactly 8 bytes with no padding.

Both fields MUST be stored in little-endian byte order.

3.1.1 Nil LUID #

The nil LUID is the LUID with all 8 bytes set to zero (LowPart = 0, HighPart = 0).

The nil LUID is a valid LUID value. The nil LUID MUST NOT be assigned by the allocation algorithm defined in §3.3.

Specifications that require a non-nil LUID MUST state this requirement explicitly.

3.2.1 Equality #

Two LUIDs are equal if and only if both their LowPart and HighPart fields are identical.

3.2.2 Ordering #

This document does not define a total ordering for LUIDs. Although LUIDs are allocated monotonically within a boot session (see §3.3), consumers MUST NOT rely on numeric ordering to infer temporal relationships between LUIDs obtained from different contexts.

LUIDs MUST be allocated by the kernel.

3.3.1 Uniqueness scope #

Each LUID MUST be unique within a single boot session.

LUID values MUST NOT be assumed unique across reboots. A value allocated in one boot session MAY be reused in a subsequent boot session.

3.3.2 Monotonicity #

The kernel MUST allocate LUIDs in strictly monotonically increasing order within a boot session, treating the two fields as a single unsigned 64-bit integer (HighPart << 32 | LowPart).

The starting value of the allocation sequence after each boot is implementation-defined.

3.3.3 Fabrication prohibition #

Userspace code MUST NOT fabricate LUID values. All LUIDs MUST be obtained through the kernel allocation interface or from well-known constants defined in a Peios specification.

3.A.1 MS-DTYP #

The LUID type defined in this document derives from the Microsoft Data Types specification (MS-DTYP), §2.3.7.

The Peios LUID binary format diverges from MS-DTYP in one detail: HighPart is an unsigned 32-bit integer (uint32) rather than the signed 32-bit integer (LONG) used in MS-DTYP. The signed type in MS-DTYP is a Win32 API convention with no semantic purpose — LUID values are never negative. Making the field unsigned simplifies comparison and eliminates a class of sign-extension bugs.

A SID (Security Identifier) is a variable-length binary value that uniquely identifies a principal — a user, group, service, machine, or well-known entity. SIDs are the fundamental identity primitive of the Peios security model: they appear in tokens as identity, in security descriptors as access rules, and as references throughout the system.

A SID is encoded as a contiguous binary structure with the following layout:

The total size of a SID in bytes is 8 + (4 × SubAuthorityCount). The minimum size is 8 bytes (zero sub-authorities). The maximum size is 68 bytes (15 sub-authorities).

The last sub-authority in a SID is the Relative Identifier (RID) — the portion that distinguishes individual principals within a domain.

SIDs are represented in string form as:

S-1-{authority}-{sub1}-{sub2}-...-{subN}

Where:

• S is a literal prefix.
• 1 is the revision number.
• {authority} is the IdentifierAuthority. If the upper 2 bytes are zero, this is the decimal representation of the lower 4 bytes. Otherwise, it is the lowercase hexadecimal representation of all 6 bytes, zero-padded to 12 hex digits and prefixed with 0x.
• Each {subN} is the decimal representation of the corresponding 32-bit sub-authority.

4.3.1 Equality #

Two SIDs are equal if and only if their binary representations are byte-for-byte identical.

SID comparison MUST be performed on the binary encoding, not the string form. There is no case sensitivity, normalisation, or equivalence relation — equality is exact binary match.

4.3.2 Ordering #

This document does not define a total ordering for SIDs. Specifications that require an ordered SID collection MUST define their ordering convention explicitly.

The following SIDs have fixed values and well-defined meanings. An implementation MUST recognise these SIDs and apply their defined semantics wherever they are referenced. The access-check behaviour attached to them is described in the Peios Kernel TRM §3.8.

4.4.1 Universal authorities #

4.4.2 Creator authorities #

4.4.3 NT Authority (S-1-5) #

4.4.4 Logon SIDs #

4.4.5 BUILTIN domain (S-1-5-32) #

4.4.6 Domain SIDs (S-1-5-21) #

Domain-specific SIDs follow the pattern S-1-5-21-{DA1}-{DA2}-{DA3}-{RID}, where the three domain authority sub-authorities identify the domain and the RID identifies the principal within that domain.

4.4.7 Mandatory integrity labels (S-1-16) #

The five levels above are the standard, well-known integrity levels; in practice they behave like an enum. Technically the level is the SID's single sub-authority as an unsigned integer: any S-1-16-<n> with exactly one sub-authority is a valid level, and MIC compares levels numerically. Non-standard values occur in Windows-interop SDs — e.g. S-1-16-8448 (medium-plus) or S-1-16-20480 (protected). A mandatory-label SID with a different identifier authority or more than one sub-authority is malformed and rejected. The standard order is System > High > Medium > Low > Untrusted.

4.4.8 Process trust labels (S-1-19) #

Trust labels encode two dimensions in the SID: the first sub-authority is the PIP type axis and the second is the trust axis (higher = more trusted). Dominance requires both dimensions to be greater than or equal.

KACS currently standardises these PIP type values:

• 0 = None
• 512 = Protected
• 1024 = Isolated

These values are standardised labels, not a closed enum for AccessCheck. Other numeric type values remain valid and are compared numerically by the same dominance rule.

4.4.9 Confinement SIDs (S-1-15) #

4.4.10 Capability SIDs (S-1-15-3) #

Capability SIDs 4–7 (picturesLibrary, videosLibrary, musicLibrary, documentsLibrary) are reserved. Their SID values MUST NOT be redefined.

Derived capabilities use 8 sub-authorities computed from the SHA-256 hash of the capability name: S-1-15-3-{h0}-{h1}-{h2}-{h3}-{h4}-{h5}-{h6}-{h7}. The same name always produces the same SID.

4.4.11 Service SIDs #

Service SIDs follow the pattern SERVICE\{service_name} (e.g., SERVICE\jellyfin, SERVICE\loregd) and are added as a group in the service's token. The token's primary user SID is the account the service runs as (typically SYSTEM, LocalService, or NetworkService); the service SID enables per-service access control — a file's DACL can grant access to SERVICE\jellyfin specifically, rather than to the broad account the service runs under.

The SID value is derived from the service name using a SHA-1 hash: the UTF-16LE encoding of the uppercased service name is hashed, and the 20-byte digest is split into five little-endian 32-bit sub-authorities: S-1-5-80-{h0}-{h1}-{h2}-{h3}-{h4}. The same service name always produces the same SID. This matches the Windows service SID derivation (MS-DTYP compatible).

4.A.1 MS-DTYP #

The SID type defined in this document derives from the Microsoft Data Types specification (MS-DTYP), §2.4.2. The Peios binary encoding is identical to the MS-DTYP packet representation, and the string form follows the same S-R-I-S convention. The structure itself originates in Windows NT, where it has been the principal identity primitive since NT 3.1.

A Security Descriptor (SD) defines the complete security policy for a protected object. Every protected object in Peios — every file, registry key, IPC endpoint, service, token, and process — MUST have a Security Descriptor.

An SD has four components and a set of control flags:

• Owner SID — the principal that owns the object. The owner has implicit rights (READ_CONTROL and WRITE_DAC) unless suppressed by an OWNER RIGHTS ACE.

• Group SID — an optional primary group associated with the object. When present, it is stored and returned on query and used during CREATOR GROUP substitution during inheritance. When absent, no primary group is available for those metadata operations. No access control decision depends on the group SID directly. If an inheritance or ACL-rewrite operation must materialize a CREATOR GROUP SID and the source object SD has no group SID, KACS MUST fail closed rather than substitute another SID or silently drop the ACE.

• DACL (Discretionary Access Control List) — an ordered list of ACEs that define who is allowed or denied access. The object's owner controls the DACL (via WRITE_DAC).

• SACL (System Access Control List) — an ordered list of ACEs that define system-level policy. Despite the name, the SACL carries several distinct ACE types:

  • Audit ACEs — which access attempts to log.
  • Mandatory label ACE — the object's integrity level for MIC.
  • Resource attribute ACEs — name-value attributes for conditional ACE evaluation.
  • Scoped policy ID ACEs — references to central access policies.
  • Process trust label ACE — the object's PIP trust level.

  Modifying the SACL requires ACCESS_SYSTEM_SECURITY. ACCESS_SYSTEM_SECURITY is privilege-controlled: it is normally granted by SeSecurityPrivilege, and may also be granted by restore-intent SeRestorePrivilege in the kacs_set_sd cases described in the Peios Kernel TRM §3.9.6.

Both the DACL and SACL use the standard binary ACL format defined in §5.2.

5.1.1 Binary format #

SDs use the self-relative binary format defined in MS-DTYP §2.4.6. The format is a 20-byte header followed by the owner SID, optional group SID, SACL, and DACL at offsets specified in the header.

Field names are those of MS-DTYP §2.4.6.

The self-relative format packs everything into a contiguous byte buffer with no pointers. This makes it suitable for storage (xattrs, database fields) and wire transmission (IPC, SMB).

KACS MUST use the self-relative format exclusively.

5.1.2 Control flags #

The SD's 16-bit Control field records metadata about the descriptor:

The architectural maximum SD size is 65,535 bytes. KACS MUST reject any parsed or computed SD whose serialised self-relative byte length exceeds 65,535 bytes.

The DEFAULTED flags are metadata. During object-SD creation, KACS MUST set the corresponding DEFAULTED flag when it supplies that component from a default source rather than from an explicit creator SD component or inherited ACL. KACS MUST NOT grant or deny access based solely on a DEFAULTED flag.

This document records the SE_SERVER_SECURITY flag value but does not define the server-ACL construction algorithm. An implementation MUST fail closed when a creator SD attempts to use SE_SERVER_SECURITY.

The PROTECTED flags are operationally significant. Setting SE_DACL_PROTECTED prevents inheritance from parent objects — the object keeps its current ACEs and stops accepting new inheritable ACEs from above.

5.1.3 Null DACL vs empty DACL #

The SE_DACL_PRESENT flag distinguishes two states with very different security consequences:

• Null DACL (SE_DACL_PRESENT not set) — no discretionary access control. AccessCheck grants all requested access to every caller. This SHOULD almost never be used.

• Empty DACL (SE_DACL_PRESENT set, zero ACEs) — AccessCheck grants no access to any caller (except the owner's implicit rights). An explicit statement that no principal has discretionary access.

Objects SHOULD always have a DACL. This is a preferred-object-shape recommendation, not a fail-closed requirement. If object creation has no explicit DACL, no inherited DACL, and the creator token has no default DACL, the resulting object SD has a null DACL: SE_DACL_PRESENT is clear and the DACL offset is zero.

An Access Control List (ACL) is the binary container for ACEs. DACLs, SACLs, and CAAP policy ACL blobs all use the same standard binary ACL format.

5.2.1 Binary format #

An ACL begins with an 8-byte header followed by AceCount ACEs packed contiguously:

The ACE array begins immediately at offset 8. Each ACE is self-delimiting via its AceSize field. The parser walks the ACL by iterating exactly AceCount ACEs within the AclSize boundary.

5.2.2 Parsing rules #

• AclSize MUST be at least 8 bytes.
• AclSize MUST NOT exceed the containing buffer.
• The ACL body MUST contain exactly AceCount ACEs within the declared AclSize.
• Truncated ACEs, ACE overruns, or leftover bytes within AclSize are malformed.
• The architectural maximum ACL size is 64 KB because AclSize is a 16-bit field.

ACE structure, ACE-type definitions, and revision-versus-ACE-family rules are specified in §5.4.

Every ACE carries an access mask — a 32-bit integer where each bit represents a specific right. The same 32-bit layout is used in three contexts: the ACE's mask (what the rule grants or denies), the requested access (what the caller asks for), and the granted access (what AccessCheck returns).

5.3.1 Bit layout #

The 32 bits are divided into four regions:

5.3.1.1 Object-specific rights (bits 0–15) #

Defined by the object type. Different object types assign different meanings to these bits. A file uses bits for read, write, append, execute; a registry key uses bits for query value, set value, create subkey; a token uses bits for query, duplicate, impersonate. Each subsystem defines its own mapping.

5.3.1.2 Standard rights (bits 16–20) #

Common to all object types:

5.3.1.3 Special rights (bits 24–25) #

5.3.1.4 Generic rights (bits 28–31) #

Abstract rights mapped to object-specific rights before evaluation:

5.3.1.5 Reserved bits #

Bits 21–23 and 26–27 are reserved and MUST NOT be used. An access mask setting any of them is rejected: a desired access mask carrying one fails the request, and an ACE mask carrying one makes the containing SD unparseable.

5.3.2 Generic mapping #

Generic rights exist because SDs need to be portable across object types. A central access policy might say "allow GENERIC_READ on all objects" — and GENERIC_READ means different specific bits for files versus registry keys.

Each object type defines a GenericMapping table:

Generic mapping happens once, at request time. AccessCheck MUST map any generic bits in the desired mask to object-specific bits using the object type's GenericMapping table, then clear the generic bits. The DACL walk operates exclusively on specific and standard bits.

An Access Control Entry (ACE) is a single rule in an ACL. Each ACE has a header, an access mask, and a principal SID, with optional extensions for object-type and conditional ACEs.

5.4.1 ACE header #

Every ACE begins with a 4-byte header:

5.4.2 ACE body layouts #

The ACE header is followed by a type-specific body. Every multibyte integer in the body is little-endian.

5.4.2.1 Single-SID ACE family #

The following ACE types share the same binary layout:

• ACCESS_ALLOWED_ACE
• ACCESS_DENIED_ACE
• SYSTEM_AUDIT_ACE
• SYSTEM_ALARM_ACE
• SYSTEM_MANDATORY_LABEL_ACE
• SYSTEM_SCOPED_POLICY_ID_ACE
• SYSTEM_PROCESS_TRUST_LABEL_ACE

Layout:

Parsing rules:

• AceSize MUST be at least 16 bytes (header + mask + minimum SID).
• The SID MUST consume the remainder of the ACE exactly.

5.4.2.2 Object ACE family #

The following ACE types share the object-ACE binary layout:

• ACCESS_ALLOWED_OBJECT_ACE
• ACCESS_DENIED_OBJECT_ACE
• SYSTEM_AUDIT_OBJECT_ACE
• SYSTEM_ALARM_OBJECT_ACE

Layout:

Object ACE flags:

Parsing rules:

• AceSize MUST be large enough to contain the header, mask, flags, all GUIDs selected by Flags, and a complete SID.
• Unknown bits in Flags MUST be ignored.
• If neither GUID-presence bit is set, the ACE has no GUID fields and behaves like the corresponding basic ACE.
• GUID fields are opaque 16-byte values at this layer. Their interpretation is described in the Peios Kernel TRM §3.8.5.

5.4.2.3 Callback ACE family #

The following ACE types extend the corresponding non-callback ACE layout by appending ApplicationData at the end of the ACE:

• ACCESS_ALLOWED_CALLBACK_ACE
• ACCESS_DENIED_CALLBACK_ACE
• SYSTEM_AUDIT_CALLBACK_ACE
• SYSTEM_ALARM_CALLBACK_ACE
• ACCESS_ALLOWED_CALLBACK_OBJECT_ACE
• ACCESS_DENIED_CALLBACK_OBJECT_ACE
• SYSTEM_AUDIT_CALLBACK_OBJECT_ACE
• SYSTEM_ALARM_CALLBACK_OBJECT_ACE

For non-object callback ACEs, the body layout is:

For callback object ACEs, the body layout is:

Parsing rules:

• The SID begins after the fixed fields and any optional GUIDs, exactly as in the corresponding non-callback ACE family.
• ApplicationData MAY be empty. Semantics for empty or malformed callback payloads are defined by the relevant subsystem.
• For conditional ACEs, ApplicationData carries the conditional expression bytecode defined in the Conditional ACE Bytecode Reference.

5.4.2.4 Resource attribute ACE #

SYSTEM_RESOURCE_ATTRIBUTE_ACE uses the single-SID ACE prefix followed by trailing application data:

Parsing rules:

• The SID MUST be Everyone.
• ApplicationData MUST contain exactly one claim entry using §5.9.

5.4.3 DACL ACE types #

5.4.3.1 Basic ACEs #

5.4.3.2 Object-type ACEs #

Extend basic ACEs with one or two GUIDs that scope the rule to a specific property or object class. Used for Active Directory access control.

The ObjectType GUID identifies the property or property set the ACE applies to. The InheritedObjectType GUID restricts inheritance to child objects of a specific class. Either or both GUIDs MAY be absent (indicated by a flags field), in which case the ACE behaves like a basic ACE for that dimension.

5.4.3.3 Conditional ACEs #

Extend basic and object-type ACEs with a conditional expression. The ACE only takes effect if the expression evaluates to TRUE against the caller's token attributes and the object's resource attributes.

5.4.4 SACL ACE types #

5.4.4.1 Audit ACEs #

Trigger audit log entries when matching access attempts occur. The AceFlags field carries SUCCESSFUL_ACCESS_ACE_FLAG (0x40) and/or FAILED_ACCESS_ACE_FLAG (0x80).

5.4.4.2 Alarm ACEs (continuous auditing) #

5.4.4.3 Mandatory label ACE #

Defines the object's integrity level for MIC. Conforming producers SHOULD emit at most one non-inherit-only mandatory-label ACE per SACL. Imported or existing SACLs MAY contain multiple mandatory-label ACEs; MIC uses the first non-inherit-only mandatory-label ACE as described in the Peios Kernel TRM §3.8.3. Inherit-only mandatory-label ACEs do not apply to the current object. The SID encodes the integrity level. The access mask encodes the MIC policy (which operations are blocked for non-dominant callers).

5.4.4.4 Resource attribute ACE #

Attaches name-value attributes to the object for conditional ACE evaluation. The ACE's SID is always Everyone (S-1-1-0).

5.4.4.5 Scoped policy ID ACE #

References a central access policy by SID. During AccessCheck, the referenced policy's rules are evaluated in addition to the object's own DACL.

5.4.4.6 Process trust label ACE #

Defines the object's PIP trust level. The SID encodes the PIP type and trust level. The access mask specifies the exact rights that non-dominant callers are allowed.

5.4.5 Allocated but unimplemented ACE types #

Two values in the range have a name but no KACS behaviour.

ACCESS_ALLOWED_COMPOUND_ACE was specified and then abandoned before any conforming system implemented it. Nothing produces it.

SYSTEM_ACCESS_FILTER_ACE is different: it is a live MS-DTYP ACE type that KACS has not implemented. The kernel ABI defines a constant for it (KACS_ACE_TYPE_SYSTEM_ACCESS_FILTER) so that a decoder can put a name to the byte, but no section of this specification assigns it meaning. A 0x15 ACE therefore takes the unrecognised-ACE path described at the end of this section: skipped during evaluation, preserved byte-for-byte on round-trip. An implementation MUST NOT grant, deny, audit, or filter access on the basis of a 0x15 ACE.

Values above 0x15 are unallocated.

5.4.6 AceType constants #

The tables above name each ACE structure. The AceType header field carries a constant with its own name, which is what a reader decoding a descriptor by hand will be holding. Both spellings, in value order:

5.4.7 ACL revision #

ACLs carry a revision number that constrains which ACE types MAY appear:

• ACL_REVISION (0x02) — basic ACE types (0x00, 0x01, 0x02, 0x03), mandatory label (0x11), resource attribute (0x12), scoped policy (0x13), and process trust label (0x14).
• ACL_REVISION_DS (0x04) — additionally permits object-type ACEs (0x05–0x08), callback ACEs (0x09–0x0C, 0x0D–0x10). Required for Active Directory access control.

When creating new ACLs containing only recognised ACE types, the revision MUST be set to the minimum required by the ACE types present. When rewriting an existing ACL while preserving one or more unrecognised ACE types, KACS MUST set the revision to the greater of the minimum required by recognised ACE types present and the source ACL revision. When parsing ACLs, KACS MUST NOT reject an ACL based on revision-vs-ACE-type mismatch — accept permissively, write correctly.

Unrecognised ACE types — every value not given semantics above, which today means 0x04, 0x15, and everything from 0x16 up — MUST be silently skipped during evaluation and preserved byte-for-byte during round-trip serialisation. The ACE's raw bytes (from AceType through AceType + AceSize) are stored opaquely and written back unchanged. ACEs with AceSize not a multiple of 4 MUST be rejected (the containing ACL is malformed).

The order of ACEs in a DACL determines the outcome of AccessCheck. AccessCheck walks the DACL from first ACE to last, and the first-writer-wins principle means each bit is decided at most once. ACE ordering is semantically load-bearing.

5.5.1 Canonical ordering #

Tools that author SDs SHOULD produce canonically-ordered DACLs. KACS MUST NOT reject non-canonical DACLs — it evaluates whatever order it receives — but non-canonical ordering can produce results that contradict administrative intent.

The canonical order is:

1. Explicit deny ACEs — deny rules placed directly on this object (not inherited).
2. Explicit allow ACEs — allow rules placed directly on this object.
3. Inherited deny ACEs — deny rules inherited from parent objects (nearest parent first).
4. Inherited allow ACEs — allow rules inherited from parent objects.

Within each category, object-type ACEs (those scoped to a specific property GUID) SHOULD be ordered after whole-object ACEs.

This ordering guarantees: explicit rules override inherited rules, denials override allows at the same level, and whole-object rules override property-scoped rules.

KACS kernel paths that evaluate, store, query, or set caller-supplied DACLs MUST preserve the caller-supplied ACE order. KACS MUST NOT canonicalise those DACLs by reordering deny ACEs, allow ACEs, whole-object ACEs, or object-type ACEs.

When KACS constructs a file DACL by combining an explicit source DACL with an inherited source DACL, it MUST emit the explicit ACE sequence before the inherited ACE sequence. Within each sequence, KACS MUST preserve the source-relative ACE order. This recombination rule is not a general canonical sorting step.

5.5.2 SACL ordering #

SACLs do not have a canonical ordering requirement. Audit ACEs are evaluated independently (each matching ACE generates its own audit event). The mandatory label ACE, resource attribute ACEs, and scoped policy ID ACEs are located by type scan, not by position.

Security Descriptors propagate structurally. When a file is created in a directory, the directory's inheritable ACEs flow down to the new file's SD. This automatic propagation is inheritance.

Inheritance applies to objects with a container/child relationship: directories contain files and subdirectories, registry keys contain subkeys and values. Objects without a container parent (standalone IPC endpoints, tokens, processes) do not inherit.

5.6.1 Inheritance flags #

Four flags in the ACE header's AceFlags field control propagation:

A fifth flag records provenance:

5.6.2 Common flag combinations #

5.6.3 CREATOR OWNER and CREATOR GROUP #

Two well-known SIDs receive special treatment during inheritance:

• CREATOR OWNER (S-1-3-0) — when an ACE with this SID is inherited by a child object, the SID is replaced with the owner SID of the new object (as determined by the owner computation above).

• CREATOR GROUP (S-1-3-1) — replaced with the primary group SID of the creating principal.

Substitution happens at inheritance time. The resulting ACE on the child contains the resolved SID, not the placeholder.

5.6.4 Inheritance algorithm #

When a new object is created, its SD is computed from up to three sources:

1. Parent SD — provides inheritable ACEs.
2. Creator SD — an explicit SD provided by the caller (if any).
3. Creator token — provides the default owner, primary group, and default DACL.

A creator SD with SE_SERVER_SECURITY set is rejected; see §5.1.

5.6.4.1 Owner #

If the creator SD specifies an owner, use it. Otherwise, use the token's owner SID.

5.6.4.2 Group #

If the creator SD specifies a group, use it. Otherwise, use the token's primary group SID.

5.6.4.3 DACL #

The DACL is computed by merging explicit ACEs from the creator SD with inheritable ACEs from the parent SD:

• If no creator SD is supplied and the parent has inheritable ACEs: the new object's DACL consists entirely of inherited ACEs from the parent.

• If no creator SD is supplied and the parent has no inheritable ACEs: the new object's DACL is the token's default DACL. If the token has no default DACL, the new object's DACL is null: SE_DACL_PRESENT is clear and the DACL offset is zero.

• If a creator SD is supplied but has no DACL (SE_DACL_PRESENT not set): the new object's DACL is computed as if no creator SD was supplied (inherit from parent, or fall back to the token's default DACL, or null DACL if the token has no default DACL).

• If a creator SD is supplied with a DACL (SE_DACL_PRESENT set):

  • Explicit ACEs from the creator SD are preserved.
  • If the creator SD's DACL is not protected (SE_DACL_PROTECTED not set) and SE_DACL_AUTO_INHERIT_REQ is set on the creator SD: inheritable ACEs from the parent are appended after the explicit ACEs. If SE_DACL_AUTO_INHERIT_REQ is not set, only the creator's explicit ACEs are used (no parent inheritance).
  • If the creator SD's DACL is protected: parent inheritance is blocked. Only the creator's explicit ACEs are used.

In all cases, the resulting DACL is post-processed:

• CREATOR OWNER / CREATOR GROUP SIDs are substituted with the actual owner and group. This substitution applies to the ACE's SID field only. ApplicationData — conditional expression bytecode — is copied verbatim: no SID substitution, no generic mapping, no offset adjustment. An implementation MUST NOT scan ApplicationData for CREATOR OWNER or CREATOR GROUP SIDs.
• Generic rights in all ACEs (both explicit and inherited) are mapped to object-specific rights via the object type's GenericMapping. This ensures no unresolved generic bits persist on stored ACEs. Generic rights appearing inside ApplicationData are not mapped.
• The INHERITED_ACE flag is set on all ACEs that came from the parent.
• If any ACE was inherited from the parent, SE_DACL_AUTO_INHERITED is set on the new SD's control flags; if the DACL came from the token's default DACL instead, SE_DACL_DEFAULTED is set. The equivalent applies to SE_SACL_AUTO_INHERITED for the SACL.

An ACE of an unrecognised type is carried to the child unchanged apart from its AceFlags byte (§5.4). Its mask is not mapped and its SID is not substituted, because neither can be located within an opaque ACE.

5.6.4.4 SACL #

Computed identically to the DACL, substituting SACL for DACL throughout. The token has no "default SACL" — if no creator SACL is supplied and the parent has no inheritable SACL ACEs, the new object has no SACL.

5.6.5 Eager evaluation #

Inheritance is eager. The new object's SD is fully computed at creation time. There is no lazy inheritance — the kernel MUST NOT walk up the directory tree at access time to find inheritable ACEs.

A consequence of eager evaluation: modifying an inheritable ACE on a parent object does not automatically update existing children. Existing children retain the SD they were created with. Propagating the change to descendants is an explicit operation outside the scope of this document. Children with SE_DACL_PROTECTED or SE_SACL_PROTECTED set MUST be skipped during any re-propagation.

Every SD has an owner. Ownership confers two implicit rights that AccessCheck grants regardless of what the DACL says:

• READ_CONTROL — the owner can always read the object's SD.
• WRITE_DAC — the owner can always modify the object's DACL.

These implicit grants are the "you can't lock yourself out" guarantee. Even if the DACL grants the owner nothing, the owner can read and rewrite the DACL to restore access.

Ownership is determined by SID equality against the caller's user SID or token group SIDs. Deny-only flags affect ACE matching, but they do not change the ownership relation itself.

5.7.1 OWNER RIGHTS (S-1-3-4) #

The implicit READ_CONTROL and WRITE_DAC grants MAY be suppressed or modified by including an ACE for the OWNER RIGHTS SID (S-1-3-4) in the DACL.

When AccessCheck detects any non-inherit-only access-control ACE targeting the OWNER RIGHTS SID in the DACL (via a pre-scan before the DACL walk), the implicit grant is suppressed. The owner's access then comes entirely from the DACL walk — through ACEs matching their user SID, group SIDs, and any ACEs targeting S-1-3-4.

This enables three patterns:

• Suppress owner rights — a deny ACE for S-1-3-4 with READ_CONTROL | WRITE_DAC.
• Expand owner rights — an allow ACE for S-1-3-4 with additional rights beyond the default.
• Restrict owner rights — an allow ACE for S-1-3-4 with only READ_CONTROL (no WRITE_DAC).

The OWNER RIGHTS pre-scan checks only for the presence of any non-inherit-only access-control ACE targeting the OWNER RIGHTS SID in the DACL, not whether any condition on the ACE evaluates to TRUE. A conditional ACE targeting OWNER RIGHTS suppresses the implicit grant even if the condition later evaluates to FALSE.

During the DACL walk, S-1-3-4 is treated as a normal SID. If the caller is the owner, ACEs targeting S-1-3-4 match the caller. The suppression only removes the automatic implicit grant; it does not isolate the owner from the rest of the DACL.

5.7.2 Ownership transfer #

Changing an object's owner requires WRITE_OWNER on the object. Without SeTakeOwnershipPrivilege, the new owner MUST be the caller's own SID or a group on the caller's token with SE_GROUP_OWNER (flag value 0x00000008; see the Peios Kernel TRM §3.2.2).

SeTakeOwnershipPrivilege grants WRITE_OWNER on any object regardless of the DACL (deny-proof, but subject to MIC/PIP). SeRestorePrivilege bypasses the ownership SID constraint entirely — the kacs_set_sd syscall checks for SeRestorePrivilege and, when present, skips the "own SID or SE_GROUP_OWNER group" validation, allowing the caller to set ownership to any arbitrary SID.

Standard ACEs match on SID alone. Conditional ACEs add a boolean expression that MUST also evaluate to TRUE for the rule to take effect. This enables attribute-based access control (ABAC).

A conditional ACE is structurally identical to its non-conditional counterpart with a conditional expression appended after the SID. The expression is stored in a binary format defined by MS-DTYP §2.4.4.17.

5.8.1 Three-valued evaluation #

Conditional expressions produce one of three results:

• TRUE — the condition is satisfied.
• FALSE — the condition is not satisfied.
• UNKNOWN — the condition could not be determined (missing attribute, type mismatch, malformed expression).

How the result affects the ACE depends on the ACE type:

This asymmetry is the fail-safe principle: uncertainty about whether to grant results in no grant; uncertainty about whether to deny results in denial.

5.8.2 Expression language #

The expression supports:

• Relational operators: ==, !=, <, <=, >, >=
• Set operators: Contains, Any_of, Not_Contains, Not_Any_of
• Membership operators: Member_of, Member_of_Any, Not_Member_of, Not_Member_of_Any, Device_Member_of, Device_Member_of_Any, Not_Device_Member_of, Not_Device_Member_of_Any
• Logical operators: AND, OR, NOT
• Existence tests: Exists, Not_Exists
• Literal values: integers, strings, SIDs, octet strings, composites

5.8.3 Three-valued logic #

NOT: TRUE↔FALSE; UNKNOWN→UNKNOWN.

Boolean coercion for logical operands: integer nonzero → TRUE, zero → FALSE. String non-empty → TRUE, empty → FALSE. NULL → UNKNOWN. SID, octet, composite → UNKNOWN. Literal-origin values (values pushed directly from the bytecode, not obtained via attribute lookup) used as operands in AND/OR/NOT → UNKNOWN for the entire expression.

5.8.4 Attribute sources #

Four attribute namespaces exist, resolved via bytecode opcodes:

Attribute names are matched case-insensitively. @User.Clearance, @User.clearance, and @User.CLEARANCE all resolve the same attribute.

5.8.5 Claim flags #

Claim flags apply to token claims (@User., @Device.) and resource attributes (@Resource.). @Local. claims also carry flags.

• DISABLED (0x0010) — the attribute is invisible to all conditions. Resolves as absent.
• USE_FOR_DENY_ONLY (0x0004) — the attribute participates only in deny-side conditional evaluation. Deny-side conditional evaluation includes deny ACE conditions and audit/alarm ACE conditions. For allow ACE conditions, it resolves as absent.

Empty attributes (zero values) are normalised to absent (NULL) at resolution time (when the expression evaluator reads the attribute value during AccessCheck).

Comparisons involving absent attributes evaluate to UNKNOWN. This includes comparing two absent attributes with == or !=: @User.Missing == @Device.AlsoMissing is UNKNOWN, not TRUE.

5.8.6 SID matching in expressions #

The Member_of family evaluates group membership on the token. These operators are polarity-aware: deny-only groups do not satisfy allow-ACE conditions. Deny ACE conditions and audit/alarm ACE conditions use deny-side membership polarity, so enabled groups and deny-only groups both participate.

An empty SID operand set uses normal set semantics: Member_of({}) and Device_Member_of({}) return TRUE, while Member_of_Any({}) and Device_Member_of_Any({}) return FALSE. The Not_* forms are the logical inverse of those results.

5.8.7 Binary format #

Conditional expressions are encoded as a stack-based bytecode program in reverse Polish notation. The binary format is defined by MS-DTYP §2.4.4.17.4 and MUST be byte-compatible.

The expression bytecode begins with a 4-byte magic: 0x61 0x72 0x74 0x78 ("artx"). If the magic is absent or the expression is shorter than 4 bytes, evaluation MUST return UNKNOWN.

Evaluation succeeds only if the final stack contains exactly one tri-state result. If evaluation ends with zero entries, more than one entry, or a raw non-boolean value still on the stack, the expression MUST evaluate to UNKNOWN.

The full operator bytecodes and literal encodings are specified in §5.11. KACS implementations MUST be byte-compatible with MS-DTYP §2.4.4.17.4.

5.8.8 Limits #

Implementations SHOULD enforce a maximum evaluation stack depth (recommended: 1024) and SHOULD return UNKNOWN for expressions that exceed it. Any bounds violation during parsing (reading beyond the expression buffer, underflowing the stack, integer overflow) MUST return UNKNOWN.

KACS v0.20 uses a Windows-compatible CLAIM_SECURITY_ATTRIBUTE_RELATIVE_V1 entry format for:

• resource attributes in SYSTEM_RESOURCE_ATTRIBUTE_ACE
• token user_claims
• token device_claims
• local_claims passed to AccessCheck

The claim entry format itself is shared across all four surfaces. When multiple entries are carried in one buffer (token claims or local_claims), KACS wraps the Windows-compatible entry format in a simple length-prefixed sequence so the buffer can be parsed deterministically without external metadata.

5.9.1 Supported types #

KACS v0.20 supports these claim value types:

FQBN (0x0004) is reserved and not supported in KACS v0.20. Any unsupported claim type makes the containing claim entry invalid.

5.9.2 Entry layout #

All multibyte integers are little-endian. All offsets are relative to the start of the claim entry.

Claim flags use the same meanings everywhere this format appears:

Unknown flag bits are preserved but have no defined semantics.

5.9.3 Value encodings #

5.9.3.1 INT64 / UINT64 / BOOLEAN #

For INT64, UINT64, and BOOLEAN, each ValueOffsets[i] points directly to an 8-byte scalar:

• INT64: signed 64-bit integer
• UINT64: unsigned 64-bit integer
• BOOLEAN: unsigned 64-bit integer, normalised at resolution time:
  • 0 = false
  • any non-zero value = true

5.9.3.2 STRING #

For STRING, each ValueOffsets[i] points to a 4-byte u32 named StringOffset. StringOffset then points to the actual UTF-16LE null-terminated string.

Strings are stored without a separate length field. The terminating UTF-16 null (0x0000) MUST appear within the containing claim entry.

5.9.3.3 SID #

For SID, each ValueOffsets[i] points to a 4-byte u32 named SidOffset. SidOffset then points to a binary SID in the standard SID wire format.

5.9.3.4 OCTET #

For OCTET, each ValueOffsets[i] points to a 4-byte u32 named OctetOffset. OctetOffset then points to:

5.9.4 Single-entry containers #

SYSTEM_RESOURCE_ATTRIBUTE_ACE.ApplicationData contains exactly one claim entry and consumes the remainder of the ACE.

5.9.5 Multi-entry containers #

Token claim buffers (user_claims, device_claims) and local_claims use a KACS claim-array wrapper:

repeat until buffer exhausted:
  [entry_len:u32le]
  [entry_bytes: entry_len bytes]

Rules:

• entry_len MUST be non-zero.
• entry_len MUST fit entirely within the containing buffer.
• entry_bytes is one complete claim entry using the layout above.
• The parser consumes entries sequentially until the containing buffer length is exhausted exactly.

5.9.6 Validation rules #

• The fixed header and ValueOffsets[] array MUST fit within the entry.
• Every offset and nested offset MUST remain within the entry bounds.
• Every string name and string value MUST terminate within the entry.
• Every referenced SID MUST be structurally valid.
• A malformed claim entry invalidates the containing surface:
  • malformed resource attribute ACE payload -> malformed SD for AccessCheck
  • malformed token claim buffer -> invalid token spec
  • malformed local_claims buffer -> invalid AccessCheck input

ValueCount = 0 is valid. Empty attributes normalise to absent at resolution time, as defined in §5.8.

A Security Descriptor MAY carry metadata about the object it protects — descriptive properties rather than access rules. These are resource attributes: name-value pairs stored as SYSTEM_RESOURCE_ATTRIBUTE_ACEs in the SACL.

Resource attributes do not grant or deny access. They exist so that conditional ACEs in the DACL can reference properties of the object during evaluation. A conditional allow ACE might say "grant read access if @User.clearance >= @Resource.confidentiality."

Each resource attribute ACE encodes a single named, typed, multi-valued attribute. The name is a string. Values MAY be integers, strings, booleans, SIDs, or byte arrays. The attribute data uses the claim entry format defined in §5.9.

Multiple resource attribute ACEs MAY appear in the same SACL, each carrying a different attribute. If two ACEs carry the same attribute name, the first one wins — duplicates are silently ignored. Name comparison is case-insensitive, matching the conditional expression evaluator's attribute name matching.

An inherit-only SYSTEM_RESOURCE_ATTRIBUTE_ACE does not apply to the object it is attached to and MUST be ignored during resource-attribute extraction.

Resource attributes are extracted from the SACL before the DACL walk begins, so they are available when conditional expressions need them.

A resource attribute marked CLAIM_SECURITY_ATTRIBUTE_MANDATORY is protected metadata. Set-security operations MUST preserve each mandatory resource attribute unless the caller has SeTcbPrivilege, as described in the Peios Kernel TRM §3.4.2.

5.10.1 Claim types #

Boolean values MUST be normalised to 1 (true) or 0 (false) at resolution time (when the conditional expression evaluator reads the attribute value), regardless of the wire encoding.

This section specifies the binary encoding for conditional ACE expressions. The format is byte-compatible with MS-DTYP §2.4.4.17.4. Conditional expressions are stored in the ApplicationData member of CALLBACK ACE types, encoded in postfix (reverse Polish) notation.

5.11.1 Magic signature #

A CALLBACK ACE contains a conditional expression if the ApplicationData begins with 0x61 0x72 0x74 0x78 (the string "artx"). If the signature is absent or the expression is shorter than 4 bytes, evaluation MUST return UNKNOWN.

5.11.2 Token formats #

Each token begins with a single byte-code identifying the token type. All multibyte integers, including Unicode characters, are stored least-significant byte first (little-endian). Expressions end at the ACE boundary; any bytes needed for DWORD alignment MUST be set to 0x00.

5.11.3 Literal tokens #

5.11.3.1 Sign codes #

Integer literals include a sign byte after the QWORD value:

During relational evaluation, the sign byte determines the literal sign. Positive (0x01) and no-sign (0x03) literals MUST be evaluated as the positive magnitude of the QWORD value. Negative (0x02) literals MUST be evaluated as the negative magnitude of the QWORD value. If the resulting signed value does not fit the declared signed-width token, evaluation MUST return UNKNOWN.

5.11.3.2 Base codes #

Integer literals include a base byte after the sign byte. The base is for display purposes only — the value is always stored as binary 2's complement regardless of base:

5.11.3.3 Integer encoding example #

The decimal value -1 encoded as a signed int64:

0x04 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0x02 0x02
 ^    ^-------- QWORD (2's complement) --------^  ^    ^
 |                                                 |    base=decimal
 byte-code=int64                                   sign=negative

5.11.4 Relational operator tokens #

5.11.4.1 Binary relational operators #

LHS is the second element on the stack, RHS is the top. If LHS and RHS are different types, the entire conditional expression evaluates to UNKNOWN — with the exception of INT64 and UINT64 which are promoted for comparison (see §5.8 for promotion rules). If either operand is UNKNOWN, the operation returns UNKNOWN.

String and octet string comparisons are byte-by-byte, case-insensitive by default. If the CLAIM_SECURITY_ATTRIBUTE_VALUE_CASE_SENSITIVE flag (0x0002) is set on either operand's attribute, comparison is case-sensitive.

5.11.4.2 Unary relational operators (SID membership) #

The operand is the top of the stack and MUST be a SID literal or a composite of SID literals.

For an empty SID operand set:

• Member_of({}) and Device_Member_of({}) return TRUE (vacuous truth).
• Member_of_Any({}) and Device_Member_of_Any({}) return FALSE.
• The Not_* forms are the logical inverse of those results.

5.11.5 Logical operator tokens #

Logical operators test the logical value of operands and produce TRUE, FALSE, or UNKNOWN. The logical value of an operand is determined by:

• Literal-origin value → error (entire expression returns UNKNOWN)
• Attribute with null value → UNKNOWN
• Attribute with integer value → TRUE if nonzero, FALSE if zero
• Attribute with string value → TRUE if non-empty, FALSE if empty
• Result value → the result's tri-state value

5.11.5.1 Unary logical operators #

5.11.5.2 Binary logical operators #

LHS is the second element on the stack, RHS is the top.

5.11.6 Attribute reference tokens #

Attribute names are encoded as Unicode strings (same format as the 0x10 literal: DWORD length + UTF-16LE code units). The byte-code determines which namespace to look up the attribute in.

Attribute lookup is case-insensitive: the encoded name is matched against the namespace's attribute names without regard to case.

5.11.7 Complete byte-code summary #

For quick reference, all byte-codes in numeric order:

KACS implementations MUST be byte-compatible with these encodings.

5.A.1 MS-DTYP #

The security descriptor family defined in this chapter derives from the Microsoft Data Types specification (MS-DTYP): the self-relative security descriptor (§2.4.6), the ACL and ACE binary formats, the CLAIM_SECURITY_ATTRIBUTE_RELATIVE_V1 claim entry, and the conditional expression bytecode (§2.4.4.17). Peios keeps the binary formats byte-compatible so security descriptors round-trip with Windows systems — over the wire and on NTFS volumes.

Deliberate divergences from the reference model are flagged inline as notes where they occur: permissive ACL-revision parsing, the repurposing of alarm ACEs for continuous auditing, evaluation-time generic mapping, the extension of Exists to all four attribute namespaces, INT64/UINT64 promotion in relational operators, and virtual-group visibility in Member_of.