Peios Kernel

The Peios kernel is a Linux kernel with Peios compiled into it. Peios contributes three things to the tree it is built from: a patch series of around fifty patches against existing kernel files, a new security/pkm subtree, and a new fs/stratafs subtree. None of it is loadable. CONFIG_SECURITY_PKM and CONFIG_STRATAFS_FS are both boolean options, so what they build is linked into vmlinux; there is no module to insert and none to unload.

security/pkm builds as PKM, the Peios Kernel Module — the name predates the decision to build in, and the subsystem still carries it. PKM registers as a Linux Security Module, provides the syscalls in the PKM range, and holds three of the four subsystems described here. The fourth, stratafs, is an ordinary in-tree filesystem that sits beside PKM rather than inside it, and reaches PKM through a kernel-private header that exports no symbols to modules.

The four subsystems are peers.

KMES, the Kernel Mediated Event Subsystem, is the sole event emission path in Peios. Kernel subsystems and userspace processes alike emit events exclusively through KMES; it stamps each event with trusted metadata, buffers it in per-CPU ring buffers, and delivers it to userspace consumers through shared memory.

KACS, the Kernel Access Control System, is the security core: SIDs, tokens, security descriptors, privileges, impersonation, process protection, binary signature verification, and the AccessCheck algorithm that ties them together. KACS also projects Peios identities onto Linux credentials so that unmodified Linux subsystems make decisions consistent with Peios policy.

stratafs is the layered filesystem. It composes an ordered stack of strata — ordinary directories, independently owned — into a single mounted tree, resolving each name in the highest-precedence stratum that holds it, routing each modification to the stratum that will accept it, and copying an object up into the designated create stratum when its own stratum will not. It stores nothing of its own, and delegates every access decision to KACS.

LCS, the Layered Configuration Subsystem, is the kernel half of the Peios registry. It owns the data model — hives, keys, values, and the precedence-ordered layers the name refers to — along with access control, watches, transactions, and the syscall and ioctl surface through which processes read and write configuration. It holds no storage of its own, delegating that to userspace sources over the Registry Source Interface.

This manual describes each subsystem in its own chapter, in the order above. They are peers, but not independent: KMES stamps events with identities it obtains from KACS, KACS emits its audit trail through KMES, LCS enforces access with KACS security descriptors, and stratafs consults KACS for every delegation decision. Cross-references between chapters mark these seams.

1.1.1 What this manual is #

This is a technical reference manual: an exhaustive description of the kernel as it is actually built. It documents observed behaviour — formats, algorithms, limits, failure modes — in plain indicative prose. It is not a standard, and it makes no conformance demands.

The contracts the kernel shares with other parties are specified elsewhere, in the Peios Core Specification Anthology: the binary structures that cross subsystem boundaries (GUIDs, SIDs, security descriptors) in PCDS, and the protocols the kernel speaks with userspace services and the formats they exchange — the registry source interface, the registry backup format, the event stream consumer protocol — in PSPK. Where a chapter touches one of those contracts, it references the specification rather than restating it, and describes only what this kernel adds: how the contract is implemented, and the behaviour on this side of the boundary.

Constants, ABI tables, and catalogues are collected in appendices at the end of the chapter they belong to, so that a chapter's reference material sits beside the prose that explains it.

The Kernel Mediated Event Subsystem is the sole event emission path in Peios. Kernel subsystems and userspace processes alike emit events exclusively through KMES — there is no alternative path. KMES stamps each event with trusted metadata at emission time, buffers it in per-CPU shared memory ring buffers, and delivers it to userspace consumers that map those buffers directly. It does not persist, index, or query events, and it imposes no schema or naming convention on them; those are consumer concerns, handled by eventd.

KMES serves a similar role to ETW in the Windows kernel and auditd in Linux, but is compatible with neither at the wire, format, or API level. The design — structured events with a fixed binary header and a msgpack payload, shared memory delivery, one emission path for kernel and userspace — was chosen for unified observability with kernel-trusted metadata.

The consumer-facing contract — the event header layout, the mapped ring buffer regions, and the protocols a consumer follows to drain, sleep, and survive buffer swaps — is specified in PSPK's KMES event stream chapter. This chapter describes the kernel side: how events are constructed and stamped (§2.2), the in-kernel emission API (§2.3), the syscall surface (§2.4), how the ring buffers are organised and written (§2.5), self-configuration through the registry (§2.6), and behaviour under failure (§2.7).

2.1.1 Terminology #

An event is an indivisible record: a packed binary header carrying KMES-intrinsic metadata, followed by a msgpack-encoded payload whose structure is defined by the emitter. Header and payload are produced, stored, and consumed together as one contiguous byte sequence; neither is meaningful alone. KMES treats the payload as opaque.

The stamp fields are the header fields KMES populates itself at emission time: the timestamp, sequence number, CPU identifier, and origin class, plus three identity GUIDs captured from KACS — the effective token GUID (the token governing the emitting thread's access rights, which is the impersonation token when the thread is impersonating), the true token GUID (the process's primary token, regardless of impersonation), and the process GUID (assigned by KACS at fork and unchanged across exec). The null GUID — sixteen zero bytes — stamps an identity field whose value is unavailable.

The sequence number is a per-CPU, per-boot monotonic 64-bit counter. Each CPU counts independently; the counter starts at zero when PKM loads and is incremented before its value is taken, so the first event on each CPU carries sequence number 1 and sequence 0 is never assigned. A gap in one CPU's sequence indicates lost events. The pair (cpu_id, sequence) uniquely identifies an event within a boot; there is no global sequence.

The origin class is a header byte identifying the emission path: userspace (0), KMES itself (1), KACS (2), or LCS (3). Values 4–255 are unassigned.

The event type is a length-prefixed UTF-8 string in the header identifying the kind of event. KMES imposes no structure on it and compares nothing against it; types are consumer vocabulary.

A ring buffer is a per-CPU shared memory region — producer metadata page, consumer metadata page, and a data region — created and managed by KMES and mapped by consumers. A consumer is a userspace process that maps one or more ring buffers and drains events from them, typically with one thread per CPU. Boot-time ring buffers are the ordinary per-CPU buffers created at module load using compiled-in defaults; they are the live consumer-facing buffers from the first instant, not a separate class.

2.2.1 Structure #

An event is a packed binary header followed immediately by its msgpack payload, written and delivered as a single contiguous byte sequence with no padding or alignment gaps anywhere. The header is never represented as a C struct in the kernel; it is serialised field by field, in order, directly into the ring buffer. The field-by-field layout — offsets, sizes, and endianness — is part of the consumer contract and is defined in the PSPK event stream specification. In summary: all fields before the event type string sit at fixed offsets, the event type string begins at offset 77 with its u16 length at offset 75, the header is exactly 77 + type_len bytes, the payload occupies the bytes from header_size to event_size, and the next event begins at offset event_size from the start of the current one. All multi-byte header integers are little-endian; the identity GUIDs are copied as opaque 16-byte values.

event_size, header_size, and type_len are structural fields computed by KMES during construction. The emitter supplies only the event type string and the payload, and KMES copies both verbatim.

2.2.2 Intrinsic stamps #

KMES populates four intrinsic stamp fields at emission time, unconditionally; the emitter cannot supply them.

• timestamp — wall clock time (CLOCK_REALTIME, via ktime_get_real_ns()) at the moment KMES accepts the event, in nanoseconds since the Unix epoch.
• sequence — the emitting CPU's per-boot counter, incremented and then read, so the first event on each CPU gets 1.
• cpu_id — the CPU on which the ring buffer write occurs, which identifies the per-CPU buffer holding the event.
• origin_class — for syscall emission, set unconditionally to 0 (userspace); the caller cannot influence it. For kernel emission, the value the calling subsystem passed, written to the header without validation — kernel emitters are trusted to pass an assigned value.

The timestamp is captured before the sequence number is assigned, so two events with the same timestamp on the same CPU are ordered by sequence.

2.2.3 Identity stamps #

The three identity GUIDs are captured by calling KACS accessors during the preemption-disabled ring buffer write phase, after the sequence number is taken and before the header is built. All three accessors are safe with preemption disabled — each is a handful of pointer dereferences and a 16-byte copy, with no allocation and no sleeping. The stamps therefore reflect the thread's identity at the moment of the ring buffer write, not at syscall entry.

• kacs_effective_token_guid() reads the thread's subjective credentials (current_cred()), so during impersonation — which installs the impersonation token via override_creds() — it yields the impersonation token's GUID. Otherwise it equals the true token GUID.
• kacs_primary_token_guid() reads the real credentials (current_real_cred()), which impersonation leaves untouched, so it always yields the process's primary token GUID.
• kacs_process_guid() reads the process GUID KACS assigned when the process's security state was created at fork. Threads created with CLONE_THREAD share the process state, and no exec path writes the field, so the GUID is stable for the process's lifetime.

All three accessors return the null GUID when there is no task context (!current or not in_task()), and the token accessors also return it when the token cannot be resolved. A fully null identity triple therefore indicates emission before KACS initialisation, from a kernel thread, or from interrupt or softirq context. No event is ever stamped with the identity of a task that merely happened to be interrupted.

For batch emission, the timestamp and the three identity GUIDs are captured once, before the per-event loop, and shared by every event in the batch: the batch executes with preemption disabled on one CPU, so the emitting thread's identity cannot change mid-batch. Each event still receives its own sequence number.

2.2.4 Ordering #

Cross-CPU ordering is by timestamp. Events with identical timestamps from different CPUs were genuinely concurrent and have no defined relative order. Within one CPU, sequence is the reliable ordering primitive, monotonic even across wall-clock discontinuities; events with identical timestamps on the same CPU are ordered by sequence.

2.2.5 Payload #

The payload is a single msgpack value. KMES neither interprets nor modifies it — buffering and delivery are content-blind — and it performs no payload validation at all for kernel emitters, which are trusted callers inside PKM.

Payloads arriving through the syscall interface are validated before acceptance by an iterative (non-recursive) msgpack walker implemented in Rust, operating on the kernel's staged copy of the payload:

• The payload is exactly one well-formed top-level msgpack value. Trailing bytes after it are rejected, as is the never-used 0xc1 type byte. A zero-length payload is rejected — an empty byte sequence is not a msgpack value — so syscall events always carry a payload. (Kernel emitters can emit header-only events with event_size == header_size.)
• Nesting depth is bounded by the configured MaxNestingDepth (§2.6). Depth counts from 1 at the top-level value; each child of an array or map sits one deeper than its container. A non-empty container at the maximum depth is invalid, because its children would exceed the limit; an empty array or map at the maximum depth is valid, consuming no depth. Map keys and values each occupy a child slot, so a map contributes twice its entry count of children.
• The walker's own stack is 256 frames, matching the upper bound of the MaxNestingDepth range; a configured depth outside 1–256 causes every payload to be rejected rather than any to be waved through.
• Length prefixes inside msgpack are big-endian, per the MessagePack specification — the one big-endian ingredient in an otherwise little-endian event.

A rejected payload fails the syscall with EINVAL and nothing is written to the ring buffer.

The event type string is validated as UTF-8 on the syscall path by the same staged-copy pass; kernel emitters' type strings are trusted and copied as given. Types are compared by consumers as raw bytes — no case folding or normalisation is applied anywhere.

2.2.6 Size limits #

Three structural bounds apply to every event, and one configurable policy bound applies to syscall emitters only:

• The event type length fits the header's u16 type_len field and is nonzero. Syscall emitters cannot express an overlong type — the ABI length field is already u16 — but the kernel emission API takes a size_t and enforces the bound itself.
• The total event size (header + payload) fits a u32, checked with overflow-safe arithmetic on the declared lengths.
• The total event size does not exceed 50% of the per-CPU ring buffer capacity — a fixed ratio, not configurable, protecting a CPU's event history from a single giant event. An event of exactly half the capacity is accepted. Capacity is always a power of two, so the halving is exact.
• Syscall events are additionally bounded by the registry-configurable MaxEventSize (§2.6), rejected with ENOSPC when exceeded. Kernel emitters are exempt from this policy limit.

The emission API is the internal kernel interface through which PKM subsystems emit events — an ordinary function call inside the module, not a syscall. Userspace emission goes through the syscall interface (§2.4). There are two entry points: single emission (pkm_kmes_emit_kernel) and batch emission (pkm_kmes_emit_kernel_batch). Both return nothing: kernel emission is fire-and-forget, and the emitting subsystem is never notified of a drop.

2.3.1 Single emission #

A kernel emitter passes an origin class, an event type (pointer and length), and a payload (pointer and length). It does not choose a CPU or buffer: KMES writes the event to the ring buffer of the CPU the calling code is executing on.

The entire emission path runs with preemption disabled — from before the current CPU is determined until after the ring buffer write — which guarantees the emitting thread cannot migrate mid-write and preserves the single-writer-per-buffer invariant. For kernel emitters this covers the full path, timestamp capture through ring write; the payloads are small and trusted, and the non-preemptible window is a few hundred nanoseconds.

Construction proceeds in order: capture the wall clock timestamp; increment the CPU's sequence counter and take the new value; capture the three identity GUIDs from KACS; build the packed header; write header and payload contiguously into the ring. The ordering consequences of these steps are described in §2.2.

KMES trusts kernel emitters. It does not validate the origin class, the type string's encoding, or the payload — only the structural checks below run. A null event-type pointer is not checked on the single-emission path; passing one faults.

2.3.2 Structural checks and drops #

Every kernel emission is checked for: nonzero event type length; type length within u16; total event size within u32 (overflow-checked); and total event size within 50% of the per-CPU ring capacity.

A failing event is not written — but its sequence number has already been consumed, so the drop is visible to consumers as a gap in that CPU's sequence, and an internal per-CPU dropped-event counter is incremented. That counter also aggregates events discarded by overwrite when the buffer wraps; it is not exposed in the ring buffer metadata and is readable only by the KUnit test harness.

Two further situations discard kernel events entirely outside this accounting:

• Before KMES initialisation completes, emission is a silent no-op: no sequence number is consumed, no counter is incremented, and no gap is visible. Events emitted in this window are simply gone.
• If the ring's recorded CPU identity does not match the executing CPU, single emission treats it as a structural drop (sequence consumed, counter incremented), while both batch paths return early without consuming anything.

2.3.3 Ring buffer full #

Each per-CPU buffer is circular. When it is full, KMES overwrites the oldest events to make room; the write position advances unconditionally, and emission never blocks and never fails from buffer pressure. Consumers detect the overwritten events as sequence gaps, and a consumer whose read position has been overtaken re-anchors to the oldest surviving event, as specified in the PSPK event stream chapter. The overwrite mechanics are described with the write protocol in §2.5.

2.3.4 Batch emission #

The batch API emits multiple events in one operation: an origin class applied to the whole batch, an array of event descriptors (type pointer and length, payload pointer and length each), and a count. There is no upper bound on the kernel batch count — unlike the syscall batch, which caps at 256 entries — so the non-preemptible window is bounded only by the caller's restraint.

The batch executes as one preemption-disabled section:

1. One wall clock timestamp is captured; every event in the batch shares it.
2. The three identity GUIDs are captured once and shared.
3. Each event, in order: structural checks, sequence assignment, header build, ring write. The batch structural check is slightly stronger than the single-emission one — it also rejects a null type pointer, a null payload pointer with a nonzero length, and a header size beyond u32. A failing event is dropped exactly as in single emission (sequence consumed, gap visible, counter incremented) and the batch continues with the next event — kernel emitters are trusted, and an individual structural failure indicates a kernel bug rather than hostile input. This differs deliberately from the syscall batch, which stops at the first failure so the untrusted caller learns which entry was bad.
4. After the loop, provided at least one event was actually written, the new tail position and then the new write position are published with release stores — one publication for the whole batch — and the consumer wake flag is checked once, incrementing the futex counter if a consumer is asleep. A batch in which every event failed publishes nothing and performs no wake check.
5. Preemption is re-enabled, and only then is the futex wake syscall work performed, outside the non-preemptible window.

Deferring publication gives batch atomicity: consumers observe either none of the batch or all of it, since the data is fully written before the single write_pos release store. During the batch, the overwrite check runs against an internal running write offset — the consumer- visible write_pos stays untouched until the end. The tail position is likewise kept local and published only at the end.

2.3.5 Write atomicity #

Individual event writes are atomic from the consumer's perspective: an event's bytes are fully written into the data region before the write_pos release store makes them reachable, so a consumer bounded by write_pos can never observe a partially written event. The memory-ordering contract this rests on is part of the PSPK event stream specification; the kernel-side implementation of the write protocol is described in §2.5.

KMES exposes three syscalls in the PKM syscall range (1090–1099): kmes_emit (1090) emits a single event from userspace, kmes_attach (1091) attaches the caller as a consumer of one per-CPU ring buffer, and kmes_emit_batch (1092) emits multiple events in one operation. All three follow the standard Linux convention — they return −1 and set errno on failure — and their numbers, entry struct layout, error tables, and privilege masks are collected in §2.A.

Before KMES initialisation completes, all three syscalls fail with ENOMEM. Before KACS initialisation, the emit syscalls fail closed with EPERM, since privilege checks cannot be performed.

2.4.1 kmes_emit #

Emits one event. The origin class is set to 0 (userspace) unconditionally — the caller cannot choose it — and the event is written to the ring buffer of the CPU the calling thread is executing on at write time.

2.4.1.1 Privilege gate #

The caller's effective token has to hold SeAuditPrivilege, enabled; otherwise the syscall fails with EPERM. A successful gate records SeAuditPrivilege as used on the token, as a KACS standalone privilege gate; a failed gate records nothing. If recording the used state itself fails, the syscall also fails with EPERM.

2.4.1.2 Rate limiting #

Callers without enabled SeTcbPrivilege are rate limited per process by a token bucket: the refill rate and the burst capacity both equal the configured MaxEmitRatePerProcess (§2.6). The bucket is allocated together with the process's KACS security state at fork, initialised to full capacity, and freed when the process's security state is released at exit. Refill is computed against the monotonic clock, so wall-clock jumps do not affect it. When MaxEmitRatePerProcess changes at runtime, the new rate and capacity take effect immediately — rates are read live on every operation — and each bucket's current token count is clamped down to the new capacity.

A token is reserved up front and refunded if the syscall subsequently fails, so validation failures cost nothing; the refund is clamped to capacity, which means a refund landing just after a rate decrease can forfeit the token. An empty bucket fails the reserve with EAGAIN, consuming nothing. Callers holding enabled SeTcbPrivilege bypass the bucket entirely, and the exemption records SeTcbPrivilege as used.

Rate state is per-process rather than per-SID: per-SID limiting would penalise unrelated services sharing a SID (LocalService, for instance). A process that forks to reset its limit is bounded by RLIMIT_NPROC.

2.4.1.3 Validation #

Validation runs in order and stops at the first failure; the errno reflects the first failing check.

1. The privilege gate and rate reservation, above.
2. event_type_len is nonzero — EINVAL otherwise.
3. The declared total event size (77 + type_len + payload_len) is computed from the length fields alone, without dereferencing either userspace pointer, with overflow-checked arithmetic — overflow is EINVAL.
4. The declared size is within MaxEventSize — ENOSPC otherwise.
5. The declared size is within 50% of the ring capacity — ENOSPC otherwise. At this stage the check runs against the first live ring's capacity; it is repeated against the actual target CPU's ring inside the write phase, so a capacity swap racing the syscall can surface ENOSPC after all other validation has passed.
6. The event type and payload are copied into a kernel staging buffer (EFAULT if a pointer is inaccessible, ENOMEM if allocation fails). Everything after this point — validation and the ring write — operates on the kernel copy, closing the TOCTOU window in which userspace could rewrite the payload after validation.
7. The event type is validated as UTF-8 — EINVAL otherwise.
8. The payload is validated as msgpack within MaxNestingDepth (§2.2) — EINVAL otherwise.

2.4.1.4 Preemption #

Validation runs with preemption enabled — the userspace copies can fault, and msgpack validation of a large payload takes microseconds. Preemption is disabled only around the ring buffer write: determining the CPU, stamping, writing, publishing write_pos, and checking need_wake. The cpu_id and identity GUIDs therefore reflect the thread's state at write time, not at syscall entry. On success the syscall returns 0 and the event is immediately visible to consumers.

2.4.2 kmes_emit_batch #

Emits up to 256 events in one call, sharing the privilege check, the timestamp, the identity capture, and the single write_pos publication across the batch. The 256-entry cap bounds the preemption-disabled write window to roughly 50–100 microseconds for typical event sizes.

The caller passes an array of 32-byte entry descriptors (layout in §2.A; the descriptor padding bytes are documented as reserved-must-be-zero in the ABI header but are not validated), a count, and an emitted_out pointer.

Processing order:

1. The SeAuditPrivilege gate, as for kmes_emit.
2. count is within 1–256 — EINVAL otherwise.
3. count tokens are reserved from the rate bucket in one critical section, so concurrent threads cannot both pass the check — EAGAIN if unavailable, and nothing is emitted. SeTcbPrivilege exempts as before.
4. Zero is stored to *emitted_out before any per-entry work — EFAULT if unwritable, with nothing emitted.
5. The descriptor array is copied from userspace (EFAULT/ENOMEM).
6. Each entry, in order, goes through the same staging pipeline as kmes_emit — declared-size arithmetic, MaxEventSize, 50% capacity, userspace copy, UTF-8, msgpack. Staging stops at the first failing entry.
7. The validated prefix is emitted in one preemption-disabled write phase: one timestamp, one identity capture, a sequence number per event, origin class 0 throughout, and a single deferred publication that makes the whole prefix visible atomically.
8. Unused tokens (count minus events emitted) are refunded — only events actually emitted are charged.

On full success the syscall returns 0 and writes count to *emitted_out. If entry N fails, entries 0 through N−1 are emitted, N is written to *emitted_out, and the syscall returns −1 with the errno of the failing entry. Failed entries never consume sequence numbers, so batch validation failures leave no consumer-visible gap. The final emitted_out store is a second write to userspace; if it faults, the syscall reports EFAULT even though the prefix was already emitted.

Every staged entry is held in kernel memory simultaneously until the write phase completes, so a batch's transient allocation is bounded by count × MaxEventSize — up to 1 GB at the maximum settings — rather than by a single event.

2.4.3 kmes_attach #

Attaches the caller as a consumer of one per-CPU ring buffer, returning a file descriptor. The consumer contract built on this fd — the mapped region layout, the drain and notification protocols, and the re-attach protocol across buffer swaps — is specified in the PSPK event stream chapter; the TRM side of the mechanics is §2.5.

The caller's effective token has to hold SeSecurityPrivilege, enabled — EPERM otherwise — and a successful gate records SeSecurityPrivilege as used. cpu_id is a logical CPU index using the same numbering as the ring metadata and event headers.

The slot array is allocated at KMES initialisation and sized by nr_cpu_ids, then filled by walking for_each_possible_cpu. Those two quantities are not the same thing: the array size bounds a valid cpu_id, while the ring count is however many of those slots got a ring. They agree only when the possible-CPU mask is dense. An index at or beyond the array size fails with EINVAL; so does an index inside it whose slot holds no live ring.

A consumer learns the array size by calling kmes_attach with cpu_id set to KMES_ATTACH_QUERY_SLOTS (0xFFFFFFFF). The call takes the same privilege gate, writes the slot count through capacity, returns 0, and opens no descriptor. Enumeration then walks 0 to slots-1 and skips the indexes that answer EINVAL.

Counting up until the first EINVAL — which is what this interface used to ask for — is wrong on a sparse mask: it stops at the first hole, and every ring above it becomes permanently unreachable, filling and overwriting with no consumer able to attach.

CPUs that were possible but offline at initialisation have rings and are attachable; hotplug beyond the initial set is not handled (§2.7).

On success the current ring capacity is written to *capacity — the consumer computes its mmap size as 8192 + 2 × capacity — and the fd is returned. The fd is opened O_RDWR | O_CLOEXEC and supports exactly two operations: mmap() and close(). The fd is installed before the capacity write-back; if that write faults, the fd is closed again and the syscall returns EFAULT, but another thread of the process can have observed the fd in the interim.

Repeated attaches to the same CPU are permitted and return a new fd each time; all fds for one CPU share the same ring — producer metadata, consumer metadata, and data region — so multiple direct consumers can drain one buffer concurrently, each keeping its own read position in its own memory. KMES stores no per-consumer state: the fd's private data is a reference to the ring, nothing more. When events arrive and need_wake is set, KMES increments that buffer's futex counter and wakes all waiting threads.

2.5.1 Organisation #

KMES maintains one ring buffer per logical CPU, created for every CPU in the kernel's possible-CPU set when the module initialises — before LCS exists, using the compiled-in default capacity — and buffering events from that first instant. These boot-time buffers are ordinary buffers: same layout, same overwrite semantics, same generation model, immediately attachable. If LCS never becomes available they simply remain the live buffers indefinitely.

Each ring is an independent, reference-counted object holding its capacity, generation, sequence counter, write and tail positions, futex counter, dropped-event counter, two metadata pages, and the data region. There is no shared state between rings on the write path: each CPU writes only to its own ring, using plain non-atomic fields under preemption disablement, and the only ordering machinery is a set of release stores at publication points. Fds taken by consumers hold references, so a ring — including a superseded generation — survives until the last consumer releases it.

The data region is a vzalloc allocation of exactly capacity bytes, zeroed once at creation and never scrubbed afterwards; overwritten regions retain stale bytes, which is why the consumer contract forbids reading beyond an event's event_size. Capacity is always a power of two — enforced at every entry point — so position wrap is a bitwise AND with capacity - 1. The permitted range is 64 KB to 256 MB, with a 4 MB default.

2.5.2 The two producer metadata pages #

Producer metadata exists twice. The kernel writes its working copy to a private page allocated with the ring, and mirrors every store to a second, consumer-visible page. The consumer-visible page is shmem-backed and allocated lazily at the first kmes_attach for the ring; shmem backing is what makes the notification futex work, since a shared (inode-keyed) futex needs a page-backed mapping. Every producer store — write_pos, tail_pos, futex_counter, generation — is a release store performed to both pages; the static fields are initialised at ring creation and re-stamped when the shared page appears. The mmap handler exposes only the shared page. The field offsets on the page are part of the consumer contract, defined in the PSPK event stream chapter.

2.5.3 Wrap handling #

The consumer's data region is double virtual mapped — the same physical pages appear twice consecutively — so a consumer reads an event that crosses the physical end of the buffer as one contiguous byte sequence. The producer side has no such mapping: kernel writes into the vzalloc region are wrap-aware, splitting a byte-range copy that crosses the boundary into two memcpy calls and masking scalar stores per byte. The contiguity guarantee is a property of the consumer's view, produced by the mmap layout rather than by the writer.

2.5.4 Write protocol #

Each ring has exactly one writer — its CPU — and the write path takes no locks and performs no cross-CPU atomics. For a single kernel emission: capture the timestamp; take the next sequence number; if the event fails a structural check, count the drop and stop (§2.3); otherwise make room, write the event at write_pos & (capacity - 1), publish the new write_pos (old value plus event size) with a release store, and check need_wake. The release store is what makes the event atomic from the consumer's side: the bytes are complete before the position that makes them reachable moves.

Making room is the overwrite walk. While the live span (write_pos - tail_pos) plus the incoming event exceeds capacity, KMES reads the event_size of the event at the tail and advances tail_pos past it, counting each overwritten event in the internal dropped-event counter, and publishes the advanced tail with a release store before the new data lands on top of it. Walking the tail is sequential and possibly cache-cold — the tail can be megabytes from the write position — a cost accepted in preference to maintaining an index of event offsets on the hot write path.

The walk carries a corruption guard: if the size field read at the tail is zero, larger than the capacity, or larger than the live span, KMES abandons the walk and resynchronises by jumping tail_pos straight to write_pos, discarding the entire surviving window in one step (the discarded span is not itemised in the drop counter) and emitting a tracepoint.

During batch writes the running write and tail positions are kept in locals; nothing is published until the batch ends, when the tail and then the write position get one release store each, followed by a single need_wake check — provided at least one event was written. Consumers therefore observe a batch atomically, and see one tail transition per batch rather than one per overwritten event.

2.5.5 Notification #

The wake path reads the consumer page's need_wake byte — the single consumer-writable byte KMES ever reads, treated as a boolean and trusted for nothing else. If it is zero, notification costs that one read. If set, KMES increments the futex counter with a release store and wakes every thread waiting on it. The futex is a shared, inode-keyed futex on the shmem producer page at the counter's offset — a consequence a consumer must match: a FUTEX_PRIVATE_FLAG wait on the mapped address is never woken. Before any consumer has attached, the shared page does not exist and the wake is skipped entirely, though the private counter still advances.

The futex_wake call itself is issued after preemption is re-enabled, outside the write window; only the counter increment happens inside it. Waking a thread that is already awake is a harmless no-op, which is also why the consumer's relaxed clearing of need_wake is safe.

2.5.6 Capacity swaps #

A valid BufferCapacity configuration change replaces every ring. New rings are allocated first, at the old generation plus one, fully initialised before any CPU can see them. The switch itself runs under stop_machine: with every CPU quiesced, each ring's surviving events are migrated to its replacement, the per-CPU live pointers are switched, and each old ring's published generation is bumped to the new value — signalling consumers on the old mapping to re-attach. If an old ring's need_wake is set, its futex counter is bumped inside the quiesced section and the wake is issued after it, so consumers asleep on a dead generation do not sleep forever.

Migration copies the surviving span in sequence order, re-compacted contiguously from position zero: the new ring starts with tail_pos = 0 and write_pos equal to the bytes copied, and the sequence and dropped-event counters carry over, so sequence numbers are continuous across a swap. When the new capacity is smaller than the surviving span, the oldest events are skipped from the tail forward until the suffix fits — loss is bounded to the oldest prefix, traced but not counted as drops. Old positions are meaningless in the new ring; a consumer re-locates by sequence number, per the PSPK protocol.

If allocating the new rings fails, the old rings stay live at their size, no generation changes, and the failure is reported through a KMES_BUFFER_SWAP_FAILED event (§2.6). A migration abort — a corrupt size field encountered inside the quiesced section — abandons the swap the same way but emits no event. There is no automatic retry; the next configuration write or reboot tries again. A superseded generation's pages stay valid for as long as any consumer keeps them mapped, so during and after a swap old and new rings coexist until the last old fd closes.

KMES reads four operational parameters from the registry under Machine\System\KMES\. Compiled-in defaults carry it from module load until LCS becomes available; from then on a persistent kernel-internal watch keeps it current. The key names, types, defaults, and ranges are in §2.A.

At no point does KMES wait for configuration. The defaults are always sufficient, and if LCS never appears KMES runs on them indefinitely.

2.6.1 Reading and validating #

Value names are matched with LCS's value-name comparison rules — Unicode Simple Case Folding, case-preserving and case-insensitive. Names in the subtree that do not fold to one of the four canonical names are unknown keys: they are counted and ignored.

A REG_DWORD value carries exactly four little-endian payload bytes and a REG_QWORD exactly eight. A value whose type tag is right but whose payload length is wrong is not a malformed number — it is classified as a wrong-type value, and reported as such.

Values are never clamped or silently corrected. A value outside its range, of the wrong type, of the wrong payload length, absent, or (for BufferCapacity) not a power of two is rejected outright and the previously active value is retained — the compiled-in default, or the last accepted value. The registry write itself succeeds, because the source does not enforce kernel semantics; the registry therefore shows what was written while the event log shows what KMES is actually using. Validation happens twice: once when the change plan is built, and again in C before the plan is applied, so an out-of-range field reaching the second gate fails the whole application with EINVAL.

Applying a plan is all or nothing, and the capacity swap runs first. A BufferCapacity change that cannot be applied therefore also prevents MaxEventSize, MaxNestingDepth, and MaxEmitRatePerProcess from being applied in the same pass, even though those three are valid and would otherwise take effect immediately for subsequent syscalls. A MaxEmitRatePerProcess change additionally reconfigures every live rate bucket, clamping any bucket holding more tokens than the new capacity (§2.4).

A valid BufferCapacity different from the current one triggers a ring buffer swap (§2.5).

2.6.2 Self-configuration events #

KMES reports its own configuration handling through KMES, with origin class 1. These events are best-effort diagnostics: emission runs before the configuration is applied and its result is discarded, so a failed emission neither rolls back a valid application nor activates an invalid value. Each event's payload is built by a small in-kernel msgpack writer into a 768-byte buffer; a payload that would exceed it is silently skipped.

KMES_SELF_CONFIG_INVALID reports one missing or invalid value. Its payload is a msgpack map of exactly nine keys, in order: configuration_parent_path (always Machine\System\KMES), configuration_name (the canonical name), expected_type, expected_min and expected_max (from the key's definition), received_kind (one of missing, wrong_type, u32_out_of_range, u64_out_of_range — a malformed payload length reports wrong_type), received_type (the actual registry type code for a wrong-type value, nil otherwise), received_value (the numeric value for an out-of-range value, nil otherwise), and retained_value (the value KMES continues to use, read before any part of the plan was applied).

One read reports at most four of these events, which is exactly the number of configuration keys. A plan that would need more is rejected before anything is applied, and the entire configuration read is abandoned.

On a first boot where the KMES key exists but is empty, all four keys are missing, so the read emits four KMES_SELF_CONFIG_INVALID events and retains all four defaults.

KMES_BUFFER_SWAP_FAILED reports a valid BufferCapacity change that could not be applied because replacement rings could not be allocated. Its payload is a three-key map: requested_capacity, retained_capacity, and errno — the last carrying the positive value of ENOMEM as an unsigned integer. It is emitted only for allocation failure; a swap abandoned because migration hit a corrupt size field produces no event.

2.6.3 Bootstrap and watching #

1. PKM loads. KMES initialises with compiled-in defaults and creates per-CPU rings at the default capacity. They are live immediately.
2. The first Machine-hive source registers, making LCS usable. KMES enumerates every value under Machine\System\KMES\.
3. Valid values are applied. A BufferCapacity differing from the current one drives a swap; a matching or absent one changes nothing.
4. KMES arms a persistent watch on the key through LCS's internal watch mechanism — a kernel-internal registration, not a userspace fd-based watch. Delivery is filtered to value-set and value-deleted notifications on the key itself, so changes in keys below Machine\System\KMES do not trigger a re-read.
5. If the key does not exist yet, the fallback watch is armed on the Machine hive root and fires on subkey creation at any depth. When it fires, KMES re-runs the whole bootstrap: discover the key, read it, and re-arm the targeted watch. Deleting the key afterwards does not re-arm the fallback.
6. On subsequent changes — administrator edit, or a Group Policy push at a higher-precedence layer — the watch fires and KMES re-reads, validates, and applies or rejects.

2.6.4 Access to the configuration #

The configuration keys inherit the Machine hive root security descriptor, which grants KEY_ALL_ACCESS to SYSTEM and Administrators and KEY_READ to Authenticated Users, so unprivileged processes cannot change KMES's operational parameters. Enforcement is LCS's, not KMES's — KMES reads values that LCS has already decided the caller was entitled to write. Domain policy at a higher-precedence layer provides defence against a compromised local administrator, since creating a layer above precedence 0 requires SeTcbPrivilege.

The boot-time capacity is the compiled-in default and is not separately configurable: making it so would need a channel to deliver a value to the kernel before the registry exists. Once LCS is available, capacity changes go through the ordinary swap.

KMES has no external trust boundary on the write path: kernel emitters are trusted, and userspace emitters are validated at the syscall boundary (§2.4). Its failure semantics are correspondingly simpler than a subsystem like LCS that spans the kernel-userspace boundary in both directions.

2.7.1 Ring overrun #

When events are emitted faster than consumers drain them, the buffer fills and KMES overwrites the oldest events. The write path is never blocked and emission never fails from buffer pressure. Consumers see the loss as gaps in the per-CPU sequence, and a consumer whose read position has been overtaken re-anchors to the oldest surviving event.

Overrun is a normal operating condition under load, not an error: the system degrades by keeping recent events, losing old ones, and telling consumers that it did.

Two bulk-loss cases sit outside that model. The tail resynchronisation guard (§2.5) can discard an entire surviving window at once when a size field reads back implausibly, and a shrinking capacity swap drops the oldest events that do not fit the new ring. Neither itemises the discarded events in the drop counter, though both are traced.

2.7.2 Event drop #

An event is dropped without reaching the buffer when a structural limit is exceeded — an event type length that cannot be encoded in the header's u16 field, or an event larger than half the ring capacity — and, for syscall emitters only, when the event exceeds MaxEventSize or the payload fails msgpack validation.

The two paths differ in what a consumer sees. For kernel emitters the sequence number is consumed before the structural checks run, so the drop appears as a sequence gap; the emitting subsystem is not notified, since emission is fire-and-forget. For syscall emitters validation completes before the write phase, so no sequence number is consumed and no gap appears — the drop is visible only to the caller, as the syscall's error return.

Events emitted before KMES initialisation completes are discarded with no sequence consumed and no counter incremented, and are therefore invisible to consumers in both ways.

The internal per-CPU dropped-event counter aggregates structural drops and overwrite losses together. It is not exposed in the ring metadata and is reachable only through the KUnit test interface.

2.7.3 Consumer crash #

A crashed consumer's mappings are cleaned up by the ordinary kernel path when its file descriptors close on process exit, and the rings themselves are reference-counted, so they survive until the last reference goes. KMES is unaffected and keeps writing regardless of whether any consumer is attached — a system with no consumers behaves identically to one with consumers, events simply being stamped, buffered, and eventually overwritten. A restarted consumer re-attaches and sees every surviving event, with the outage visible as a sequence gap.

2.7.4 Buffer swap failure #

If replacement rings cannot be allocated, the existing rings stay live at their current size, the configuration change is not applied, no generation changes, and consumers are unaffected. A KMES_BUFFER_SWAP_FAILED event records the requested and retained capacities (§2.6). KMES does not retry; the next configuration write or a reboot triggers another attempt.

2.7.5 LCS unavailable #

If no source ever registers, KMES runs indefinitely on compiled-in defaults with the boot-time rings live and the configuration watch never armed. This is a valid operating mode, not a failure — the only consequence is that the parameters cannot be tuned.

2.7.6 Clock discontinuity #

Timestamps come from CLOCK_REALTIME, so an NTP adjustment can move them forward or backward and consumers sorting by timestamp will see an apparent reordering. Sequence numbers are unaffected: they are independent monotonic counters, never derived from the clock, and remain the reliable ordering primitive within a CPU. KMES neither detects nor compensates for discontinuities. Cross-CPU ordering near a jump is best-effort — an inherent cost of wall-clock timestamps, accepted for their readability and cross-boot comparability. Rate limiting is immune, being driven by the monotonic clock.

System suspend and hibernate are special cases of the same thing. Ring contents survive suspend to RAM, and are restored from the hibernate image on resume; in both cases the clock jumps forward by the sleep duration, so consumers see a wall-clock gap with no sequence gap.

2.7.7 CPU topology #

The set of rings is fixed at initialisation from the kernel's possible-CPU set, and topology changes are not handled dynamically.

A CPU that was possible but offline at initialisation already has a ring: if it comes online later, its events go to that ring, and consumers can attach to it throughout. A CPU whose logical index was outside the possible-CPU set has no ring, and kmes_attach rejects that index; KMES neither creates rings for such CPUs nor publishes topology-change notifications. A CPU taken offline through cpu_online keeps its ring, and a consumer draining it simply sleeps indefinitely, unable to distinguish a quiet CPU from a departed one. Hot-add is the realistic case — hypervisors adding vCPUs to a running guest — while hot-remove is rare outside mainframes.

Anything that fixes this is additive: a topology-change notification, whether a generation bump meaning "re-enumerate", a dedicated descriptor, or a status field in the metadata page, fits the existing attach-per-CPU design without changing the ring format, the event format, or the emission API.

One structural caveat applies to attach discovery. The index bound is the count of rings successfully created, while rings are indexed by logical CPU id. On a system whose possible-CPU mask has holes, the two differ: the "attach with incrementing indexes until EINVAL" loop stops early, and rings at high logical indexes are unreachable.

Each logical CPU — each hardware thread under SMT — gets its own ring, so ring memory scales with threads rather than cores: at the 4 MB default a 64-core, 128-thread machine holds 512 MB of ring buffers. This follows from events being emitted per logical CPU and cpu_id naming the logical CPU.

2.7.8 Memory bounding #

Ring memory in steady state is num_cpus × BufferCapacity for the fixed CPU count fixed at initialisation, plus two metadata pages per CPU and one shmem page per ring that has ever been attached. During a capacity swap old and new rings coexist until every mapping of the old generation is released.

Transient allocation during emission is bounded by the event size for a single emit and freed as soon as the event is written. A batch is different: every entry is staged in kernel memory simultaneously, so a batch holds up to count × MaxEventSize — 256 entries at a 4 MB maximum event size — until its write phase completes.

Each kmes_attach creates one file descriptor, bounded by RLIMIT_NOFILE and by the SeSecurityPrivilege requirement. No KMES-specific global memory cap exists; the capacity configuration and standard Linux resource limits are the bounds.

2.7.9 Allocation and timing choices #

The data region is a plain vzalloc allocation of 4 KB pages, and the mmap handler inserts pages one at a time, so hugepage backing is not available to it. The difference is substantial for TLB coverage: a 4 MB ring needs 1024 standard pages against 2 hugepages, and because the double mapping doubles the virtual range, 2048 standard pages against 4 hugepages. Allocation is not NUMA-aware: pages come from the general allocator with no attempt to place a ring on the node local to its CPU, so writes on a CPU whose ring landed on a remote node cross the interconnect — roughly 100-150 ns against about 70 ns for a local node. Timestamps use the full ktime_get_real_ns() rather than ktime_get_real_fast_ns(), which avoids the timekeeper seqlock and costs roughly 15-25 ns less per event at the price of being up to one tick stale when a timer interrupt is updating the timekeeper concurrently. Headers are built field by field on every event with no precomputed per-CPU template, msgpack validation is scalar, and each staged syscall event takes its own kvmalloc rather than drawing on a per-CPU staging buffer.

None of these choices affects the ring format, the event header, or the consumer protocol.

Every name, value, offset and size in this appendix is generated from pkm/uapi/pkm/kmes.h by pkm/tools/gen-kmes-abi.py, with struct layouts measured by compiling a probe against the real header. Regenerate it whenever the ABI changes; do not edit it by hand. The names here are the ones a program actually compiles against.

What a compiler cannot measure -- the error vocabulary of each syscall, the privilege each requires by name, what the configuration keys do, and the implementation bounds that are not in the header -- is in the notes appendix, §2.B, which this generator does not touch.

2.A.1 Syscall numbers #

Signatures are read from the SYSCALL_DEFINE sites in pkm/kmes/.

2.A.2 Structure layouts #

Offsets and sizes are measured, not declared.

2.A.2.1 struct kmes_emit_entry #

Total size 32 bytes.

2.A.3 Constants #

Grouped as the header groups them.

Event origin class — kmes_event_header.origin_class.

Ring-slot discovery.

Ring slots are indexed by logical CPU id and the array is sized by the kernel's nr_cpu_ids, so a slot inside the array holds no ring when that CPU is not possible. Counting up from 0 until SYS_KMES_ATTACH returns -EINVAL therefore stops at the first hole and misses every ring above it, leaving those CPUs' events permanently unreachable.

Call SYS_KMES_ATTACH with cpu_id KMES_ATTACH_QUERY_SLOTS to learn the slot count instead. It writes the count through the capacity argument, returns 0, and opens no descriptor. Enumerate 0 .. count-1 and treat -EINVAL as "this slot holds no ring", not as the end of the array.

The sentinel is outside the index space for good: nr_cpu_ids is bounded by CONFIG_NR_CPUS, which cannot reach 2^32-1.

Largest entry count a single SYS_KMES_EMIT_BATCH call accepts.

Runtime configuration registry location and keys.

Type values match the LCS REG_* constants: REG_DWORD is 4 and REG_QWORD is 11. They are repeated here so <pkm/kmes.h> remains standalone.

Privilege requirements.

Values mirror the corresponding KACS privilege bits while keeping this header standalone.

On-wire event header.

Every event in a ring begins with a fixed 77-byte header, followed by event_type_len bytes of type string and then the msgpack payload. Events abut at event_size stride, so a header is not generally aligned; it crosses the ABI as raw bytes, not a C struct. Its fields, in order:

__u32  event_size            total event byte length (header + type + payload)
__u32  header_size           byte offset from the event start to the payload
__u64  timestamp_ns
__u64  sequence
__u16  cpu_id
__u8   origin_class          one of KMES_ORIGIN_* above
__u8   effective_token_guid[16]
__u8   true_token_guid[16]
__u8   process_guid[16]
__u16  event_type_len        length of the type string following the header

The three GUIDs are 16-byte Microsoft GUID binary values (Data1/Data2/Data3 little-endian, Data4 raw), captured from KACS at emission time; the null GUID (16 zero bytes) means identity was unavailable (KACS not initialised, or no process context). KMES copies them opaquely.

Read each field at its KMES_EVENT_*_OFFSET below. header_size locates the payload: it is KMES_EVENT_HEADER_BASE_SIZE + event_type_len. A future revision may grow the header, so consumers must use header_size, not the end of the type string, to find the payload.

Byte width of each identity GUID in the event header.

Byte size of the fixed event header — the offset at which the type string begins.

Ring-buffer metadata layout.

An attached ring is mmap'd as:

page 0          producer metadata (read-only to the consumer)
page 1          consumer metadata (read-write)
ring data       the event bytes, mapped twice back-to-back so an event
                that wraps the buffer end is still contiguous.

The producer metadata page begins with KMES_RING_MAGIC.

Field offsets within the producer metadata page.

Field offset within the consumer metadata page.

2.A.4 Tracepoint diagnostic codes #

From uapi/pkm/trace.h. These are a diagnostic contract for ftrace, perf and eBPF consumers, letting a tool decode a kmes: event's reason, op or state field without recompiling against a specific kernel. No KMES syscall accepts or returns them, and values are append-only.

kmes_drop reason — why the KMES ring machinery lost an event.

RING_FULL is a normal overwrite; TAIL_RESYNC is the silent corruption- recovery path that discards ALL pending events; VALIDATE is a kernel- emit size/type reject at the ring boundary; BATCH_STRUCT_INVALID is a per-entry structural reject in the kernel batch path. Emitted by kmes:kmes_drop. No event payload bytes.

kmes_swap reason — a bounded ring capacity swap lifecycle marker.

BEGIN and COMPLETE/FAILED are whole-topology (cpu field is U16_MAX); MIGRATE_SKIP is per-CPU and carries the skipped byte count in ret. Emitted by kmes:kmes_swap.

kmes_rate reason — the per-process token-bucket backpressure signal.

THROTTLE is an -EAGAIN emit rejection; RECONFIGURE marks an admin rate change clamping all buckets. Emitted by kmes:kmes_rate.

kmes_wake reason — consumer wakeup machinery.

NOTE arms a pending wake; FUTEX is the actual futex wake of blocked consumers. Emitted by kmes:kmes_wake.

kmes_ring_lifecycle reason — a generation-stable ring object transition.

ret is the outcome. Emitted by kmes:kmes_ring_lifecycle.

kmes_ingress_reject reason — why an emit request was rejected before the ring.

OVER_MAX/OVER_CAP_HALF/SIZE_OVERFLOW are declared-size rejects; EMIT_OVERSIZE is a staged event too large at ring-write time; BATCH_PARTIAL marks a batch that validated fewer entries than requested. Emitted by kmes:kmes_ingress_reject.

kmes_validate reason — the C-boundary result of the Rust staged-event validator.

The Rust side collapses its structural checks into one nonzero return; only visible type/payload lengths and ret are recorded here. Emitted by kmes:kmes_validate.

§2.A is generated from pkm/uapi/pkm/kmes.h and holds only what a compiler can measure. This appendix holds the rest.

The split is structural rather than editorial. gen-kmes-abi.py overwrites §2.A wholesale on every run, so anything written there is lost the next time the ABI changes.

Layouts that form part of the consumer contract — the event header, the producer and consumer metadata pages, and the mapped region — are specified normatively in the PSPK event stream specification. §2.A gives their offsets as the header defines them; the specification governs.

2.B.1 Syscall parameters #

kmes_emit and kmes_emit_batch return 0 on success; kmes_attach returns a file descriptor. All three return -1 and set errno on failure.

The PKM syscall range is 1090–1099; KMES uses the first three.

2.B.2 Privilege requirements #

kmes.h gives these as bit masks so it can stand alone. The names belong to the KACS privilege catalogue, and the bit index is what the two agree on.

Holding a privilege is not enough: it must be enabled, and KMES marks it used before proceeding. A failure to record the used state is itself an EPERM, because an unrecorded privilege use is an audit gap.

SeTcbPrivilege is checked but not required — an emitter that holds it enabled is exempt from the per-process rate limit, and one that does not is throttled.

2.B.3 Implementation bounds #

These are properties of the implementation rather than of the ABI, so they are not in kmes.h and a program must not compile against them. They bound what the interface will accept.

The structural 50% bound is independent of MaxEventSize and applies to kernel emitters too. An event may satisfy the configured maximum and still be refused because the ring is small.

The validator's 256-frame stack is why MaxNestingDepth has a maximum of 256. The two bounds are enforced independently: the configuration range check refuses a larger value at apply time, and the validator refuses every event outright if it is somehow handed one, rather than silently accepting nesting it cannot track.

2.B.4 Configuration keys #

Registry path Machine\System\KMES\. The type codes, defaults and ranges are in §2.A; what each key does is here.

MaxEventSize, MaxNestingDepth and MaxEmitRatePerProcess apply only to syscall emitters. A kernel emitter is not rate-limited and its payload is not parsed as MessagePack, but it is still checked structurally — non-empty type string within PKM_KMES_MAX_KERNEL_TYPE_LEN, a payload pointer if the length is non-zero, no size arithmetic overflow, and the 50% bound. A kernel event that fails is dropped with KMES_DROP_VALIDATE, not emitted.

A key that is missing, of the wrong type, or out of range does not fail the read: the previous value is retained and the disagreement is recorded as an audit intent. At most four such intents are carried out of one read, so a configuration with five bad keys reports four.

2.B.5 Error codes #

2.B.5.1 kmes_emit #

2.B.5.2 kmes_emit_batch #

2.B.5.3 kmes_attach #

A KMES_ATTACH_QUERY_SLOTS call takes the same EPERM, EFAULT and ENOMEM conditions and cannot return EINVAL.

The ring array is sized by nr_cpu_ids, not by the number of rings allocated. On a machine with a sparse possible-CPU mask the two differ, and a slot inside the array with no live ring returns EINVAL exactly as an index beyond the array does. A consumer therefore enumerates against the slot count from KMES_ATTACH_QUERY_SLOTS and skips the EINVAL slots rather than stopping at the first one; see §2.4.

2.B.6 Build configuration #

KMES is built by CONFIG_SECURITY_PKM, a boolean option, so it is linked into vmlinux rather than loaded. CONFIG_RUST=y is required: the MessagePack validator is Rust. The whole subsystem is staged into the kernel tree as security/pkm/kmes by pkm/kernel/stage-sources.sh, which also stages <trace/events/kmes.h> so the tracepoints resolve.

The three syscall numbers are added to the syscall table by kernel/patches/arch/syscall-table-pkm.patch, which patches both arch/x86/entry/syscalls/syscall_64.tbl and the copy of it that ships under tools/perf/. They are registered common, so they are reachable from the x32 ABI as well as from x86-64.

CONFIG_SECURITY_PKM_KUNIT compiles in the in-kernel test harness.

The Kernel Access Control System is the security core of Peios: an LSM within PKM providing identity-based access control in the Linux kernel. It is the sole identity-based authorization mechanism for managed objects. Every identity-based decision — a file open, a registry read, an IPC connection, a signal, a token operation — passes through one evaluation function, AccessCheck.

This chapter covers tokens (§3.2), the Process Security Block (§3.3), privileges (§3.4), impersonation (§3.5), binary signature verification (§3.6), Process Integrity Protection (§3.7), the AccessCheck algorithm in full (§3.8), file enforcement (§3.9), and how Peios identity is projected onto the Linux credential model (§3.10).

Two bodies of material that KACS owns conceptually live elsewhere in the documentation. The binary structures — SIDs, security descriptors, ACLs, ACEs, access masks, conditional ACE bytecode — are specified in PCDS, because userspace tooling constructs and interprets them and has to agree with the kernel byte for byte. The signing format a third party would use to sign a binary with a PIP level is specified in PSPK; this chapter describes only the verification side. What remains here is the kernel's own behaviour: how it holds identity, and how it decides.

3.1.1 Terminology #

A token is a per-thread identity object held in the kernel's credential structure, carrying a user SID, group SIDs, a privilege bitmask, an integrity level, an impersonation level, and metadata. Identity fields — SIDs, type, integrity level — are immutable; policy fields — enabled privileges, enabled groups, default owner, group and DACL — are atomically adjustable. Every thread has a token, and there is no such thing as a null token.

A primary token defines a process's baseline identity and is inherited on fork, reached through task->real_cred. An impersonation token temporarily overrides it for access decisions on one thread only, reached through task->cred.

A LogonSession is a kernel object representing one authentication event: a session ID, a logon type, a user SID, an authentication package, a logon time, and a logon SID. Tokens reference their session by ID.

A privilege is a system-wide right carried on a token. Some influence AccessCheck; others gate a standalone operation.

An impersonation level controls how far an identity can travel: Anonymous, Identification, Impersonation, or Delegation.

An integrity level is a vertical trust classification on tokens and objects. Numerically it is the mandatory label SID's single sub-authority compared as an unsigned integer, so any S-1-16-<n> with exactly one sub-authority is valid. In practice five standard levels form a strict total order — Untrusted (0), Low (4096), Medium (8192), High (12288), System (16384) — and non-standard values such as S-1-16-8448 appear only in SDs authored for Windows interop. Mandatory Integrity Control is the constraint evaluated before the DACL, blocking write access, and optionally read and execute, when the caller's level is below the object's label.

Process Integrity Protection is a two-dimensional trust model — type against trust level — protecting processes and objects from insufficiently trusted callers. Unlike MIC, it revokes rights that a privilege would otherwise have granted.

The Process Security Block is a per-process structure carrying PIP identity, process mitigations, and process restrictions. It is never affected by impersonation, which is the point of keeping it separate from the token.

FACS, the File Access Control Shim, is the part of KACS that replaces Linux DAC with security-descriptor evaluation on files. It enforces the handle model: AccessCheck runs at open time and the granted mask is cached on the file description, with later operations checked against the cached mask.

An object type is the category of a protected resource. Each defines a GenericMapping table translating generic rights into object-specific ones.

The TCB — the components whose correct behaviour is necessary for system security — is the Linux kernel, PKM, and the core trusted userspace daemons: peinit, authd, and loregd.

3.1.2 Relationship to MS-DTYP #

KACS is not a port of another system's security model. Tokens, security descriptors, AccessCheck, structured SIDs, and per-thread impersonation were chosen because they solve what Peios needs solved: coherent identity, rich per-object access control, scoped delegation, and integrated audit.

Those same primitives are the ones Active Directory uses, and Peios is built to join AD domains as a first-class member — exchanging security data with domain controllers, authenticating through Kerberos, and enforcing policy distributed by Group Policy. That imposes binary format compatibility, which PCDS specifies: an SD written by a Windows domain controller and replicated through Samba is evaluated by KACS without translation.

Format compatibility does not imply evaluator compatibility in every corner. Given the same token, descriptor, and desired mask, KACS generally reaches the same decision MS-DTYP describes, which is what makes policy authored in an AD environment behave predictably here. Where it deliberately does not, §3.B records every departure and why.

A token is a kernel object representing a thread's identity and security policy: the user's SID, group memberships, privileges, integrity level, impersonation state, claims, confinement settings, and metadata. Every KACS-mediated access control decision evaluates the thread's effective token.

Every live userspace thread has one. KACS-mediated authorization never evaluates a null token — credentials that are blank, uncommitted, kernel-only, asynchronous, or otherwise outside a meaningful userspace evaluation context may carry no token at all, and an LSM hook that reaches KACS with such a credential fails closed rather than evaluate a meaningless identity.

3.2.1.1 Relationship to Linux credentials #

Tokens are independently allocated, reference-counted kernel objects. A struct cred holds a pointer to the token in its LSM security blob, not the token data itself.

That indirection is architecturally load-bearing. Linux credentials are immutable once committed: after commit_creds() a struct cred cannot be modified. Had token data been embedded in the credential, every token mutation — toggling a privilege, adjusting a group — would have required allocating a whole new credential. Keeping the token behind a pointer lets token-internal mutations use the token's own synchronisation and leave the credential alone.

Several thread credentials within a process may reference one token object through real_cred, and a mutation to a shared token is visible to every thread sharing it. At fork the child receives an independent deep copy, so mutations after fork are invisible across the process boundary.

3.2.1.2 Primary and effective tokens #

The real_cred/cred split on task_struct carries two roles.

real_cred is the task's objective identity, used when other tasks evaluate access to this task. Its LSM blob points at the primary token — the process's baseline identity, inherited from the parent at fork.

cred is the task's subjective identity, used when this task evaluates access to other objects. Its blob points at the effective token: normally the primary token, or an impersonation token installed by a server thread acting for a client.

With no impersonation in play, real_cred and cred are the same credential and resolve to the same token. Impersonation swaps cred to a new credential pointing at a different token; reverting restores cred to real_cred.

3.2.1.3 Evaluation context #

Token evaluation — AccessCheck, privilege checks — happens only where a meaningful subject authority exists. In task context that authority is the effective token reached through current_cred().

Linux credential substitution is authoritative for deferred work. When a kernel path runs under credentials installed by override_creds() or another subjective-credential mechanism, the token pointer in that credential's blob travels with it and is evaluated normally. KACS does not strip authority merely because the current task carries a kernel-thread, workqueue, or io_uring-worker flag — the credential is what counts, not the worker flag.

Authorization already cached on an object handle, such as the granted mask on a file description, continues to use that cached authority for post-open operations. User-originated asynchronous work that has neither captured credentials nor cached handle authority reaches KACS without a token-bearing credential and fails closed.

Kernel-originated infrastructure work running under the boot SYSTEM credential evaluates as SYSTEM. There is no separate worker-flag-based kernel authority identity.

Token fields fall into three mutability classes. Fixed fields are set at creation and never change — every security-critical identity field is fixed. Adjustable fields can be modified at runtime through the adjustment operations (§3.2.5). One-way fields can be set or tightened but never cleared or loosened.

3.2.2.1 Identity core (fixed) #

The logon SID — S-1-5-5-X-Y, tying the token to its LogonSession — is not stored as a token field at all. It is derived from the session on every read, and materialised once in groups carrying SE_GROUP_LOGON_ID, which is where AccessCheck finds it.

The group SID set is fixed at creation — adjustment never adds or removes a SID. Individual groups can be enabled or disabled by modifying SE_GROUP_ENABLED, within two limits: a mandatory group (SE_GROUP_MANDATORY) cannot be disabled, and a deny-only group (SE_GROUP_USE_FOR_DENY_ONLY) cannot be re-enabled.

A token holds at most 1024 group entries including the kernel-injected logon SID, so CreateToken accepts at most 1023 caller-supplied groups.

3.2.2.2 Token type (fixed) #

3.2.2.3 Integrity (fixed) #

mandatory_policy is immutable: a process cannot change its own MIC constraints at runtime, neither loosening nor tightening them. This is a deliberate departure from MS-DTYP, where the mandatory policy is runtime-modifiable — which reduces MIC to a constraint that stops only processes not actively trying to bypass it. Immutability is what makes MIC a real boundary here, and it is also what allows the impersonation integrity ceiling (§3.5) to be enforced unconditionally.

3.2.2.4 Privileges (adjustable) #

Each privilege on a token has four independent states.

Present — the privilege exists on the token. A present privilege can be removed permanently, but no privilege can be added after creation. Enabled — the privilege is currently active; only present privileges can be enabled or disabled. Enabled by default — the creation-time enabled state, which adjustment can restore. Used — the privilege has been exercised during this token's lifetime; monotonic, and never cleared once set.

The lifecycle runs: present and disabled, to enabled, to used, then optionally disabled, then optionally removed permanently. Removal clears the privilege from the present, enabled, and enabled-by-default states together.

The four states are encoded as four 64-bit bitmasks, one bit per defined privilege, which makes a privilege check constant-time and a multi-privilege operation atomic.

3.2.2.5 Elevation (one-way) #

A token is created as Default. Only KACS_IOC_LINK_TOKENS sets Full or Limited, when a linked pair is established, and once set neither reverts to Default on that token object. The role is sticky: relinking can replace the partner but never converts Full to Limited or the reverse. DuplicateToken and FilterToken produce new token objects whose elevation_type starts again at Default, because a new token is not part of any linked pair.

Linked pairs are associated at the LogonSession level rather than stored on individual tokens; §3.2.6 describes the pairing mechanism.

3.2.2.6 Default object security (adjustable) #

Storing indices rather than SID copies keeps the owner and primary group consistent with the group array they name.

3.2.2.7 Metadata (fixed) #

3.2.2.8 Mutation tracking (adjustable) #

Marking a privilege used is audit and accounting state rather than an access-decision input, so it stays monotonic but does not bump modified_id. Setting the elevation type is the one other mutation that leaves the counter alone.

The counter is intended as a cache invalidation key — a modified_id that has changed since a cached decision was taken means the decision is stale. Nothing currently reads it for that purpose: it is maintained on every adjustment and reported through the statistics query class, and no cache anywhere invalidates on it.

3.2.2.9 Interactivity scope (adjustable) #

3.2.2.10 Claims and security attributes (fixed) #

3.2.2.11 LCS registry credentials (fixed) #

These are KACS-owned credential material belonging to LCS. They are fixed at creation and copied by duplication and filtering, and attaching them is authorized by the same trusted-minting gate as the rest of CreateToken — only a caller holding SeCreateTokenPrivilege can create a token carrying them.

3.2.2.12 Device identity (fixed) #

3.2.2.13 Confinement (fixed) #

ALL_APPLICATION_PACKAGES participates only when it is present in confinement_capabilities. KACS never synthesises it, and equally never rejects an otherwise valid confined token merely because it is present — strict confinement is expressed by the caller omitting it. Deciding which capabilities a package token receives is authd's job and policy tooling's, not the kernel's.

3.2.2.14 Audit (fixed) #

The policy is additive. It forces audit events that system-wide policy would not generate, and cannot suppress events that system-wide policy requires. It follows impersonation: when service A impersonates client B and B's token has a category enabled, operations during impersonation are audited under B's identity. The creation default is 0.

3.2.2.15 Credential projection (fixed) #

authd computes these at token creation and they are stored on the token; KACS never resolves a SID-to-UID mapping at runtime. Projection reflects all groups regardless of enabled state, so adjusting groups does not trigger recalculation. §3.10 covers how the projection is used.

3.2.2.16 Token security (adjustable) #

3.2.2.17 Internal #

3.2.3.1 Fork and clone #

Every process and thread creation path goes through clone(), and KACS branches on CLONE_THREAD.

Without CLONE_THREAD — fork or vfork — a new process is created and the child receives an independent deep copy of the parent's primary token. If the parent is impersonating, the impersonation token is not inherited: the child's effective credential is set from real_cred. After the fork, mutations to either token are invisible to the other.

With CLONE_THREAD a new thread is created. Threads share the parent's real_cred by reference and therefore share one primary token object, so a privilege adjustment on it is visible to every thread. Each thread keeps independent impersonation state through its own cred. If the cloning thread is impersonating at the moment of the clone, the impersonation token does not become the new thread's primary or effective identity — the new thread starts with the shared primary token as both, and may impersonate independently later.

3.2.3.2 Exec #

The primary token survives execve() unchanged, with the single exception of NEW_PROCESS_MIN below. If the calling thread is impersonating, impersonation is reverted before the new program runs; a new program always starts with the primary token as its effective identity.

Token assignment for services happens between fork and exec: peinit forks, installs the service's token on the child, and the child then execs the service binary.

3.2.3.2.1 NEW_PROCESS_MIN #

When a token's mandatory_policy includes NEW_PROCESS_MIN, the kernel replaces the primary token at exec time if the executable carries a lower integrity label.

1. The executable's integrity label is read from the mandatory label ACE in its descriptor's SACL. A file with no label is treated as Medium.
2. If the file's level is lower than the token's, a new token is created following DuplicateToken semantics — new token_id, new token_guid, modified_id initialised to the new token_id, elevation_type reset to Default — with integrity_level set to the file's label. Every other field is copied from the source, and the original token is dropped.
3. If the file's level is greater than or equal to the token's, nothing happens and the token survives exec unchanged.

The mechanism only ever lowers integrity, so a child's level is always at most its parent's. The flag itself is immutable on the token, which is what prevents a process from opting out before exec.

3.2.3.3 Self-installing a primary token #

KACS_IOC_INSTALL commits a new primary token on the calling process. The operation is process-wide: the kernel replaces the primary token for the entire thread group, not just the calling thread.

A thread that is not impersonating switches both real_cred and cred to the new primary token. A thread that is impersonating has only real_cred replaced, and its active impersonation stays in cred until it reverts or execs — so reverting after an install restores the thread to the new primary token, not the old one.

The calling thread installs immediately. Sibling threads converge in their own context through queued in-kernel credential work, with no atomic all-threads-at-once swap: during a brief transition window some siblings may still observe the old primary token until they run their queued work. No completion barrier is exposed to the caller.

If the installed token's user SID differs from the outgoing primary token's, the process security descriptor is regenerated from the default template for the new token. Otherwise the existing process descriptor is preserved.

3.2.3.4 Bootstrap tokens #

Two tokens are created by PKM during kernel initialisation, before any userspace process exists. Neither involves a syscall — the kernel allocates the objects directly.

The SYSTEM token is hardcoded with user SID S-1-5-18 (Local System); groups S-1-5-32-544 (BUILTIN\Administrators), S-1-1-0 (Everyone), S-1-5-11 (Authenticated Users) and other well-known SIDs; every defined privilege present and enabled; integrity level System; token type Primary; elevation type Default; token source PeiosKrn; projected UID 0; and auth_id set to SYSTEM_LUID. It is assigned to the kernel's init task and inherited by PID 1 at exec.

The Anonymous token is a global singleton with user SID S-1-5-7; Everyone (S-1-1-0) as its only group; no privileges; integrity level Untrusted; logon type Network; token type Impersonation; impersonation level Anonymous; elevation type Default; token source PeiosKrn; and auth_id set to ANONYMOUS_LOGON_LUID. It is effectively immutable, having no privileges and no groups to adjust. kacs_impersonate_peer at Anonymous level references this global object, whereas KACS_IOC_DUPLICATE targeting Anonymous level creates a fresh independent token of the same shape, because the DuplicateToken contract requires a new object.

LogonSessions created dynamically by authd receive auto-generated LUIDs starting at 1000; 999 and 998 are never assigned dynamically.

The SYSTEM token carries SeBackupPrivilege and SeRestorePrivilege present and enabled at boot. FACS passes backup and restore intent flags into AccessCheck, which grants read and write regardless of file DACLs — subject still to PIP. Once peinit has launched the TCB services and early boot is complete, it disables these on child service tokens through FilterToken.

3.2.3.5 External token replacement #

A privileged process being able to replace the primary token on another running process — peinit downgrading a pre-authd service from SYSTEM to a purpose-built token, for instance — is designed but not built. Nothing in the kernel implements it today.

The design uses task_work_add() to queue a credential swap on each task in the target thread group, each task executing the swap in its own context to preserve RCU safety, with an impersonating thread having only real_cred replaced and its impersonation left intact. The gates would be SeAssignPrimaryTokenPrivilege on the caller's real token, TOKEN_ASSIGN_PRIMARY (0x0001) on the token fd, PROCESS_SET_INFORMATION on the target process's descriptor, and two constraints — the new token's user SID matching the target's current one, and the new token belonging to the same LogonSession — both bypassed by SeTcbPrivilege. The process descriptor gate puts the target's owner in control of who can change its identity, while the SID and LogonSession constraints stop a non-TCB holder of SeAssignPrimaryTokenPrivilege assigning an arbitrary token to a process it can reach. SeTcbPrivilege bypassing both is how peinit would assign tokens with different user SIDs and LogonSessions to child services. Per-thread queuing would leave a brief window with some threads on the new token and some on the old, which is acceptable only because replacement is always a downgrade.

In its absence, the mitigation for pre-authd services is privilege removal: peinit uses FilterToken to copy the SYSTEM token with the dangerous privileges permanently deleted and assigns that filtered token to the service at launch. The service keeps the SYSTEM SID but permanently lacks the ability to exercise those privileges.

Three operations create tokens, each for a different purpose: CreateToken mints one from nothing, DuplicateToken copies one, and FilterToken produces a strictly weaker copy.

3.2.4.1 CreateToken #

Mints a new token from scratch. The caller supplies the security-meaningful content; the kernel generates the internal bookkeeping and validates the structural invariants. The operation is gated by SeCreateTokenPrivilege.

The caller supplies user_sid, groups with their attributes, privileges as privs_present plus privs_enabled, owner_sid_index, primary_group_index, default_dacl, integrity_level, mandatory_policy, token_type, impersonation_level, auth_id referencing an existing LogonSession, expiration (0 for none), audit_policy, source as a name plus LUID, user_claims, device_claims, lcs_scope_guids, lcs_private_layers, device_groups, restricted_sids, restricted_device_groups, confinement_sid, confinement_capabilities, confinement_exempt, isolation_boundary, write_restricted, user_deny_only, projected_uid, projected_gid, projected_supplementary_gids, origin, and interactivity_scope. The wire format is in §3.A.

Including the well-known implicit groups is the caller's responsibility — Everyone (S-1-1-0), Authenticated Users (S-1-5-11), and whatever else the principal's authentication context implies, such as S-1-5-4 Interactive, S-1-5-6 Service, or S-1-5-15 This Organization. The kernel injects none of these. The logon SID is the sole kernel-generated group.

The kernel generates token_id as a LUID, token_guid, modified_id initialised to token_id, created_at as the current time, elevation_type always Default, the token's own default security descriptor (§3.2.7), and logon_sid, derived from the LogonSession ID as S-1-5-5-{id >> 32}-{id & 0xFFFFFFFF}.

The logon SID is injected into the groups array carrying SE_GROUP_MANDATORY | SE_GROUP_ENABLED_BY_DEFAULT | SE_GROUP_ENABLED | SE_GROUP_LOGON_ID, appended after the caller's groups. Callers do not include it themselves. Because the injected entry is appended, owner_sid_index and primary_group_index are interpreted relative to the caller-supplied groups — 0 for the user SID, 1..N for the caller's groups — and not against the array with the logon SID in it.

Validation covers, in turn: that the caller holds SeCreateTokenPrivilege; that every SID is structurally well-formed; that the owner SID is the user SID or a group carrying SE_GROUP_OWNER, resolved to owner_sid_index; that the primary group SID is the user SID or a group on the token, resolved to primary_group_index; that auth_id references an existing LogonSession; that a Primary token carries impersonation level Anonymous; that user_deny_only is true whenever write_restricted is; that confinement_sid is present whenever isolation_boundary is; that the wire format's elevation_type field is 0, since the kernel always sets Default itself; and that the caller's group count plus the injected logon SID fits the 1024-entry limit.

The optional LCS registry credential extension, when present, has to use the version and layout of §3.A, and carries at most 256 scope GUIDs and at most 256 private layer names, with no nil scope GUID, no duplicate scope GUIDs, no empty or overlong layer names, and no duplicate layer names under LCS case-insensitive matching. Malformed LCS credentials fail the whole call closed.

The kernel does not authenticate the user, look up SIDs in the directory, resolve SID-to-UID mappings, or check that the principal exists at all. Holding SeCreateTokenPrivilege is what makes the caller trusted, and that trust is total.

The call returns a token file descriptor. Since CreateToken takes no desired-access parameter, the returned handle always carries a cached access mask of TOKEN_ALL_ACCESS.

3.2.4.2 DuplicateToken #

Creates an independent copy of an existing token, requiring TOKEN_DUPLICATE access on the source.

Two things may change during duplication. The token type may go from primary to impersonation or the reverse; duplicating to Primary forces impersonation_level to Anonymous. The impersonation level may be chosen freely when the source is a Primary token, but when the source is itself an impersonation token the new level has to be equal to or lower than the source's — an Identification-level token cannot be duplicated up to Impersonation or Delegation.

On the new token, token_id and token_guid are fresh, modified_id is initialised to the new token_id, and elevation_type resets to Default because the copy belongs to no linked pair. token_type and impersonation_level are as the caller specified, within the rules above. The token's own descriptor is a fresh default (§3.2.7): no custom descriptor can be supplied at duplication time, and changing it afterwards means using WRITE_DAC on the new handle.

Everything else is copied from the source: user_sid, user_deny_only, logon_sid; groups with all per-group attributes; restricted_sids and write_restricted; the privilege present, enabled, enabled-by-default and used states; integrity_level and mandatory_policy; auth_id, origin, source, created_at, expiration, audit_policy; interactivity_scope; default_dacl, owner_sid_index, primary_group_index; user_claims, device_claims, device_groups, restricted_device_groups; lcs_scope_guids and lcs_private_layers; confinement_sid, confinement_capabilities, confinement_exempt; and the three projection fields.

One target is not a copy at all. Duplicating to Impersonation at Anonymous level discards the source entirely and returns a fresh token of the boot Anonymous shape — user SID S-1-5-7, Everyone as its only group, no privileges, Untrusted integrity, and LogonSession 998 rather than the source's. None of the copied-field rules above apply to it. Assuming Anonymous is an identity boundary rather than a level change, so the operation constructs the minimal identity instead of narrowing the caller's.

The original token is unaffected.

3.2.4.3 FilterToken #

Creates a restricted copy, requiring TOKEN_DUPLICATE access on the source. Filtering only ever weakens: there is no parameter that grants anything.

It can remove privileges, deleting them permanently from the new token by clearing them from the present, enabled, and enabled-by-default states at once. It can set groups to deny-only, giving them SE_GROUP_USE_FOR_DENY_ONLY so they block access through deny ACEs but never grant it through allow ACEs — permanently, with no way back. It can add restricted SIDs, a secondary list that makes AccessCheck evaluate the DACL twice, granting access only when the normal SIDs and the restricted SIDs independently both pass. And it can enable write-restricted mode, limiting that second evaluation to write operations so reads use the normal list alone; enabling it forces user_deny_only true on the new token.

Input validation is all-or-nothing — a single malformed entry means no token is created. The deny-only list uses zero-based group indices into the source's group array, and a duplicate or out-of-range index is invalid. The restricting SID blob has to parse exactly as the declared packed SID list, with no truncated or trailing bytes. If the source token is already restricted and the intersection of its restricted SID list with the supplied list is empty, the request is invalid and nothing is created.

On the new token, token_id and token_guid are fresh, modified_id is initialised to the new token_id, and elevation_type resets to Default. The privilege states are the source's modified by the removal list, except that used resets to 0 — unlike duplication, which carries it across. groups keeps the source's SIDs with attributes modified per the deny-only list, adding and removing nothing. restricted_sids is the supplied list, or its intersection with the source's when the source was already restricted. write_restricted is sticky: set if requested or if the source had it. user_deny_only is true when write-restricted is enabled and otherwise copied. user_sid, logon_sid, integrity_level, mandatory_policy, token_type and impersonation_level are copied, as are auth_id, origin, source, created_at, expiration, audit_policy, default_dacl, owner_sid_index, primary_group_index, the claims and device group arrays, the LCS credentials, the confinement fields, and the projection fields. The token's descriptor is a fresh default.

A live token's privileges, groups, default object-creation metadata, and interactive session metadata can be adjusted at runtime. These are distinct operations with separate access rights and constraint models. All of them mutate the token object in place using atomic operations, all become visible immediately to every thread sharing the token, and all bump modified_id.

3.2.5.1 AdjustPrivileges #

Requires TOKEN_ADJUST_PRIVILEGES on the token, and has three modes.

Enable and disable flips individual bits in privileges_enabled for privileges present on the token. A privilege that is not present cannot be enabled, and disabling one that is already absent is a no-op. The operation activates existing privileges; it never grants new ones.

Reset to defaults restores privileges_enabled to match privileges_enabled_by_default, returning every privilege to its creation-time state in one operation. It is encoded as a single kacs_priv_entry with luid = 0 and attributes = KACS_PRIV_RESET_ALL_DEFAULTS. The reset touches only privileges_enabled: it does not restore privileges that were removed from privileges_present.

Remove permanently deletes a privilege, clearing its bit in privileges_present, privileges_enabled, and privileges_enabled_by_default together. Removing an already-absent privilege is a no-op. The deletion is irreversible; nothing re-adds a privilege to a token.

Duplicate privilege indices in one request are invalid. The kernel validates every entry before applying any change, so an invalid entry fails the whole operation with no state change at all. The caller receives a report of each adjusted privilege's previous state.

3.2.5.2 AdjustGroups #

Requires TOKEN_ADJUST_GROUPS on the token, and has two modes.

Enable and disable flips SE_GROUP_ENABLED on individual groups, within two constraints. A group carrying SE_GROUP_MANDATORY, SE_GROUP_USE_FOR_DENY_ONLY, or SE_GROUP_LOGON_ID cannot be adjusted in either direction — not enabled, not disabled, whatever its current state; naming one in a request fails the whole call. And the user SID, when it appears in the group list, cannot be disabled, which is the one constraint that is direction-scoped.

Reset to defaults restores every group to its creation-time enabled state. It restores only that state — it does not clear SE_GROUP_USE_FOR_DENY_ONLY from a group that FilterToken marked deny-only afterwards.

Groups are addressed by zero-based index into the token's groups array. A count of 0 is invalid, as is a count above 1024, as are duplicate indices in one request. Reset is encoded as a single kacs_group_entry of { index = 0xFFFFFFFF, enable = 0 }.

The caller receives the previous enabled state of every group as a 1024-bit mask encoded as sixteen 64-bit words in ascending order: word 0 covers group indices 0–63, word 1 covers 64–127, and bit i % 64 of word i / 64 corresponds to group index i. Since group arrays cap at 1024 entries, the mask is complete for any valid token.

3.2.5.3 AdjustInteractivityScope #

Requires TOKEN_ADJUST_INTERACTIVITY_SCOPE on the token and SeTcbPrivilege on the caller's real token. It changes the token's interactivity_scope to a new u32 and nothing else: the field is metadata, and changing it grants or removes no privilege, group, access right, label, claim, default owner, default primary group, default DACL, or any other authorization state.

3.2.5.4 AdjustDefault #

Requires TOKEN_ADJUST_DEFAULT on the token, and covers three fields.

The default DACL applied to new objects is replaced by an RCU pointer swap, with the old DACL freed after a grace period. The owner SID index changes which SID becomes the default owner of new objects, and has to reference the user SID or a group carrying SE_GROUP_OWNER. The primary group index changes the default primary group, and has to reference the user SID or any group SID on the token. Both index updates are atomic.

All three affect future object creation only; existing objects are untouched. None can escalate anything, because the caller is choosing among SIDs already on their own token.

audit_policy is fixed at creation, and no adjustment operation changes it.

At logon, authd may create two tokens for one principal and link them. The elevated token, elevation_type = Full, carries the user's complete identity: every group active, every assigned privilege present and enabled. The filtered token, elevation_type = Limited, carries the same user SID with administrative groups set to deny-only and dangerous privileges stripped, produced from the elevated token by FilterToken.

Both tokens belong to the same LogonSession, are both primary tokens, and carry the same user SID. The filtered token is installed as the LogonSession's default; the elevated token exists but is not directly reachable by unprivileged processes.

A token never assigned a linked-pair role has elevation_type = Default. Once KACS_IOC_LINK_TOKENS sets a token object to Full or Limited, that role is sticky on that object. If the pair is later replaced or destroyed the token has no active partner and KACS_IOC_GET_LINKED_TOKEN returns an error, but the token goes on reporting its last assigned elevation type.

3.2.6.1 What KACS does #

KACS provides pairing, storage, and query restriction — three mechanisms, no policy.

Linked pair association registers the pair on the LogonSession, so given either token the system can retrieve its partner. The pairing lives at the LogonSession level and is not stored on the token objects.

Establishing a pair is a TCB operation: the caller holds SeTcbPrivilege on its primary token — an impersonating thread's effective token does not satisfy it — and holds TOKEN_DUPLICATE on both of the token handles being linked. The two handles have to name distinct token objects, and both have to belong to the LogonSession named in the request, which itself has to be published. The ioctl ignores the handle it was issued on entirely; only the two named handles matter.

Elevation type classification puts elevation_type on each token so a consumer can tell which side it is holding.

Identification-level query restriction governs what an unprivileged caller gets when it queries a token's partner: a deep clone at Identification impersonation level. The clone follows DuplicateToken semantics — a new token object, a new token_id, modified_id initialised to it, a fresh default descriptor — except that it preserves the partner's elevation_type, and it is always returned through a TOKEN_QUERY-only handle. The caller can inspect the elevated token but cannot use it for an access decision. A caller holding SeTcbPrivilege receives a full handle to the actual linked token instead.

Returning a copy through TOKEN_QUERY is a deliberate exception to the normal access-right model, where TOKEN_DUPLICATE would be expected. It holds because the returned copy is always Identification-level: functionally a query result rather than a usable token.

3.2.6.2 What KACS does not do #

The elevation decision itself — whether this user should be allowed to use their elevated token right now — is entirely authd's. KACS does not gate elevation, verify credentials, or display prompts. It stores the pair and restricts unprivileged access to it.

Beyond enforcing the LogonSession, token-type and same-user invariants, KACS does not verify that the filtered token really is a FilterToken-derived reduction of the elevated one. That correspondence is authd's to get right.

3.2.6.3 Lifecycle #

Both tokens in a pair share a LogonSession, and that session is not destroyed while any token fd, credential, pair slot, or other reference keeps one of its token objects live. When the last external reference is released and only the linked-pair's own references remain, KACS destroys the LogonSession, removes the linkage, and drops the pair's references to both tokens. After that cleanup no token object from the session remains live purely because it was linked.

Stale-role tokens can exist before final destruction — for instance when KACS_IOC_LINK_TOKENS replaces a LogonSession's active pair while an old token object is still held by an fd or credential. Fork produces them too: the deep copy a child receives preserves the parent's elevation type, so a forked child can hold a Full or Limited token that was never linked to anything. Once a token is no longer the active member of the pair, querying its linked token returns an error, because the partner relationship no longer exists for it. Such survivors keep their sticky Full or Limited elevation type: they are stale-role tokens with no active partner, not Default tokens.

3.2.7.1 LogonSessions #

A LogonSession is a lightweight kernel object identified by a LUID, carried on tokens as auth_id. Every token references one.

authd creates a LogonSession through a KACS syscall at authentication time, before creating the token. The object holds the LogonSession ID, the logon type (Interactive, Network, Service, and so on), the user SID, the authentication package name such as Kerberos or Negotiate, and a creation timestamp. The logon SID, S-1-5-5-X-Y, is derived from the LogonSession ID. Several tokens may share one session — linked pairs, and tokens derived by duplication.

When the last token referencing a session is freed, the kernel destroys the session object and emits a logon-session-destroyed event through KMES. authd subscribes to those events and uses them to clean up associated credentials such as cached Kerberos tickets.

There is one rollback path for the case where authd creates a session but no token ever becomes live for it: kacs_destroy_empty_logon_session, which requires SeTcbPrivilege and succeeds only when the session exists, has zero live tokens, has no linked-token state, and has no other in-flight kernel references. On success it destroys the object and emits the same logon-session-destroyed event as normal cleanup. A nonexistent session fails with -ENOENT; one with any live token, linked-token state, or in-flight reference fails with -EBUSY.

A second enumeration surface exists alongside /proc: /sys/kernel/security/kacs/sessions lists every live session, one line each, giving the session ID, user SID, logon type, authentication package, and creation time. Reading it is access-checked against a synthetic descriptor granting read to SYSTEM and the creator, and is PIP-checked.

AccessCheck never consults auth_id, and the logon SID influences a decision only because it is materialised as an ordinary group SID on the token. Two enforcement decisions elsewhere in the kernel do read session state, though: installing a primary token denies a non-TCB caller whose target token belongs to a different LogonSession, and the CAP_SYS_BOOT mapping selects between SeShutdownPrivilege and SeRemoteShutdownPrivilege by inspecting the session's logon type. interactivity_scope is metadata in the same way: the kernel stores it and returns it on query, and no kernel security mechanism evaluates it.

3.2.7.2 Expiration #

The expiration field carries a timestamp, and AccessCheck does not enforce it. It is informational.

Token lifetime is governed by reference counting instead: a token exists as long as at least one reference — a process credential or an open file descriptor — exists.

3.2.7.3 Revocation #

KACS has no token revocation primitive. There is no "invalidate token X" syscall, and no syscall destroys a LogonSession while tokens still reference it. kacs_destroy_empty_logon_session is only authd's rollback for a session that never acquired live tokens.

Terminating a LogonSession is therefore userspace coordination:

1. authd decides a session has to end — an admin request, a security incident, an account deletion, or a user logging off.
2. authd enumerates processes whose tokens carry the target auth_id or interactivity_scope by walking /proc/*/token, opening each node's query-only inspection handle, and reading TokenStatistics, which includes auth_id. No dedicated enumeration syscall exists or is needed.
3. authd requests termination — through peinit for supervised services, through signals for user processes.
4. The processes terminate, dropping their token references.
5. The last reference drops and the session object is cleaned up.

Token file descriptors can be passed between processes over IPC, so a reference held by a process outside the target session survives that session's process termination. authd has to account for this when enumerating token holders — the walk finds processes running under the session, not every process holding one of its tokens.

Kernel-side invalidation — a dead flag on the LogonSession object checked during AccessCheck, so that access checks against its tokens fail immediately — is not implemented.

Tokens are securable objects: each has its own security descriptor, and reaching a token means passing an AccessCheck against it.

3.2.8.1 Obtaining a token file descriptor #

Opening directly. A syscall takes a pidfd — not a raw PID — and a desired access mask. The kernel finds the target's primary token, evaluates the caller's token against that token's descriptor, and returns a token fd with the granted mask cached on it. A separate variant opens a thread's impersonation token. Opening another process's token additionally requires PROCESS_QUERY_INFORMATION on the target process's descriptor.

kacs_open_peer_token is the exception: it takes no desired-access mask, and the fd it returns always carries the fixed rights TOKEN_QUERY | TOKEN_IMPERSONATE.

Receiving over IPC. A token fd can be passed over a Unix socket with SCM_RIGHTS. What the recipient may do is bounded by the mask cached on the fd when it was originally opened, not by the recipient's own identity.

Implicit self-access. A thread has implicit access to its own effective token for query operations, but this is not a kernel bypass. It follows from the default token descriptor, which grants TOKEN_QUERY and the adjustment rights to the token's own user SID. The AccessCheck still runs; it simply succeeds while the descriptor continues to grant the right. Explicitly mutating a token's own descriptor later can revoke self-query by removing that grant.

3.2.8.2 Token-specific rights #

Bit 0x0010, TOKEN_QUERY_SOURCE, is subsumed by TOKEN_QUERY: a holder of 0x0008 can query source information too. The bit is not reused for anything else, for format compatibility with MS-DTYP.

TOKEN_ALL_ACCESS is 0x000F01FF — the union of the token-specific rights with STANDARD_RIGHTS_REQUIRED (DELETE | READ_CONTROL | WRITE_DAC | WRITE_OWNER, 0x000F0000). The named rights alone OR to 0x01EF; the reserved TOKEN_QUERY_SOURCE bit adds 0x0010 to reach 0x01FF.

3.2.8.3 Generic mapping #

3.2.8.4 Standard rights #

READ_CONTROL reads the token's own descriptor, WRITE_DAC modifies its DACL, and WRITE_OWNER changes its owner. DELETE has no practical effect on a token and is present only for uniformity across standard rights.

3.2.8.5 The default token descriptor #

A newly created token receives a descriptor owned by the creating process's user SID, with a DACL granting:

• the token's own user SID TOKEN_QUERY | TOKEN_ADJUST_PRIVILEGES | TOKEN_ADJUST_GROUPS | TOKEN_ADJUST_DEFAULT;
• the creator TOKEN_ALL_ACCESS;
• SYSTEM (S-1-5-18) TOKEN_ALL_ACCESS.

Self-access is deliberately limited to the adjustment operations that cannot escalate. TOKEN_DUPLICATE, TOKEN_IMPERSONATE, and WRITE_DAC are not granted to the token's own subject.

That limit needs protecting in the case where the creator and the token's own user SID are the same, which would otherwise hand the subject TOKEN_ALL_ACCESS through the creator ACE. When the two SIDs are identical the creator ACE is omitted — and the descriptor also gains a non-inherit-only OWNER RIGHTS ACE suppressing the owner's implicit READ_CONTROL | WRITE_DAC grant while preserving READ_CONTROL. Without it, owner-implicit WRITE_DAC would let the subject rewrite its own DACL and reintroduce exactly the escalation that omitting the creator ACE was meant to close.

3.2.8.6 Check-at-open #

The check-at-open model applies to tokens exactly as it does to files, for the token-specific rights. AccessCheck runs once, when the token fd is obtained; the granted mask is cached on the fd; and each of the token ioctls verifies against that cached mask with no re-evaluation.

The standard rights are the exception. Reading and writing a token's own descriptor passes no cached mask at all and runs a live AccessCheck on every call, so READ_CONTROL, WRITE_DAC and WRITE_OWNER are re-evaluated per operation rather than snapshotted at open. A descriptor change therefore takes effect immediately for those three rights, while already-opened handles keep their cached token-specific rights.

The Process Security Block is a per-process structure carrying properties that describe what the process is, independent of the principal running it.

Its PIP identity fields, pip_type and pip_trust, are determined by the binary loaded at exec (§3.6). Its other fields — process mitigations and process restrictions — are process policy, set by whoever launches the process. Neither category is token identity, and neither is determined by the principal.

Keeping the PSB separate from the token is the point. The token describes identity and travels with impersonation: when a thread impersonates a client, the effective token changes. The PSB describes the process, and impersonation never touches it.

The PSB is never affected by impersonation. Impersonation changes who the thread is acting as. It does not change what the process is.

The canonical PSB reference lives on the task's LSM security blob, task_struct->security, separate from the credential that holds the token pointer. A mirrored, non-authoritative reference is also kept in credential security blobs, for the benefit of Linux hooks that receive only a credential. For any task-attached credential that mirror refers to the same PSB as the task blob, and it never defines a different process identity.

Credentials are swapped during impersonation, and that swap may change the credential's token pointer — but the canonical PSB is untouched and any credential-level mirror continues to refer to it.

3.3.2.1 Process identity (fixed at fork) #

The process GUID is distinct from the PID. PIDs are recycled; process GUIDs are unique within a boot, and globally unique in practice. It is the stable correlation key that lets KMES attribute events to a process across its whole lifetime.

3.3.2.2 Protection (set at exec, fixed) #

PIP fields are signing-based. At exec the kernel verifies the binary's signature and derives both fields from the signer, using the algorithm and key model of §3.6.

Both are plain unsigned integers rather than enumerations, and are compared numerically. Three type values are conventional — None (0), Protected (512) and Isolated (1024) — but only two are producible: the key table validator accepts a key only at exactly Protected with PeiosTcb trust (8192) and rejects the whole table otherwise, so Isolated is unreachable and a signed binary is always Protected/8192. Neither None nor Isolated is defined as a named constant in the public ABI at all. The parent process cannot influence the determination at all — even a compromised peinit running as SYSTEM cannot forge PIP protection for an unsigned binary. The public verification key is compiled into the kernel image, and the kernel only ever verifies; it never signs.

This is a deliberate departure from MS-DTYP, where the parent sets a protection level at process creation and the kernel validates the binary's signature against it. Peios removes the parent-controlled half entirely: one input, one answer.

3.3.2.3 Process mitigations (one-way) #

Mitigations are inherited from the parent at fork and can be set by syscall, typically by peinit between fork and exec. They are one-way: once set they are never cleared, and exec does not reset them — a mitigation set by the launcher persists regardless of which binary is loaded.

Setting a bit is activation-backed. Before a mitigation bit moves from clear to set, KACS either activates the underlying protection for the target process or verifies that the process already satisfies the invariant. If any requested mitigation cannot be activated or verified, the whole operation fails closed without mutating any bit from that request. Once committed, later operations that would disable the protection or make the process violate the invariant are rejected, and re-requesting an already-set mitigation never weakens what is already committed.

For the runtime memory mitigations, activation covers existing state as well as future transitions. Enabling wxp fails if the process already has a mapping that is simultaneously writable and executable, or otherwise already violates the invariant in a way KACS can observe. Enabling tlp fails if the process already has a file-backed executable mapping whose kernel-resolved path is missing, unresolvable, outside the approved prefix cache, or otherwise TLP-denied. Enabling lsv fails if the process already has a file-backed executable mapping whose signing material is missing, invalid, or below the required PIP trust. Anonymous executable mappings are governed by wxp alone; tlp and lsv apply only to file-backed ones.

For the architecture-backed mitigations, activation goes through the architecture's kernel interface to place the process in the protected state and prevent later process-controlled disablement. Enabling cfif, cfib, or sml fails closed when the platform cannot make the protection true for the target.

sml also accepts a second route: a platform that reports speculation as unconditionally not-affected satisfies activation by that fact alone, with nothing to enable.

cfif cannot currently be committed at all. Activation against a live task returns ENODEV unconditionally, because the kernel exposes no userspace control surface for IBT or BTI, so the bit fails closed on every request. cfib works, through shadow-stack enable-and-lock, with one restriction: enabling it on a task other than the caller fails.

Two mitigations are event-gated rather than retroactive: pie is enforced at subsequent exec and no_child_process at subsequent process creation. They still follow the one-way commit rule, and have to be set before the event they are meant to constrain.

All of this is distinct from PIP. Mitigations are policy set by the launcher; PIP is a property of the binary determined by the kernel.

The mitigations compose deliberately: LSV ensures only signed libraries load, WXP blocks code injection, CFIF blocks forward-edge code reuse through indirect calls and jumps, CFIB blocks return-oriented programming, and PIE makes ASLR effective. Together they make exploitation dramatically harder than any one of them alone.

3.3.2.4 UI access (one-way) #

3.3.2.5 Process restrictions (one-way) #

Unlike the exec-time fields, this one can be set at two points. The parent's code, running in the freshly forked child, can set it before exec, so the new binary loads with the restriction already in place. Or a process can restrict itself at any time during its life — after it has finished spawning its own workers, for instance.

3.3.2.6 The TLP cache #

The approved directory prefixes for TLP live in a global kernel cache rather than on individual PSBs: the tlp flag decides whether a process is subject to enforcement, while the paths themselves are machine-wide.

The cache is an array of absolute directory prefix byte strings evaluated against kernel-resolved Linux path bytes, holding at most 64 entries of at most 4096 bytes each. Every prefix begins with / and ends with / — so that /usr/lib/ does not match /usr/libevil — and contains no embedded NUL byte. An empty, relative, NUL-containing, or non-slash-terminated prefix is invalid and is rejected without mutating the existing cache, which is staged and swapped under a mutex so a rejected update cannot leave it partly written.

The cache has no production writer. The only code that populates it is a test helper compiled in solely under the KUnit configuration: there is no syscall, no securityfs node, and no registry path that fills it. In a shipping build the cache is therefore permanently empty — and since an empty cache matches no path, enabling tlp on a process denies every file-backed executable mapping it subsequently attempts.

At mmap(PROT_EXEC) time, a process with TLP enabled has the mapped file's current kernel-resolved backing path checked against every approved prefix. If the path cannot be resolved, if no prefix matches, or if the cache is empty, the mapping is rejected.

3.3.2.7 Identity virtualization (reserved) #

Every process carries a security descriptor controlling who may operate on it, stored on the PSB alongside the PIP and mitigation fields. It replaces Linux's UID-based process access control — a patchwork of UID comparisons and capabilities — with a single descriptor evaluation.

3.3.3.1 Process access rights #

Three /proc entries are not where the right names suggest. maps, fd and environ are not gated by PROCESS_QUERY_INFORMATION: they keep their upstream PTRACE_MODE_READ_FSCREDS gating, which maps to PROCESS_VM_READ — reading a process's memory map is treated as reading its memory, which is defensible but is not what the right's name implies. And cgroup sits in the PROCESS_QUERY_LIMITED set rather than the detailed one.

3.3.3.2 Signal classification #

Each Linux signal maps to a process access right according to its default action.

Signal 0 is not delivered at all. A kill(), tkill(), or tgkill() call with signal 0 is an existence and permission probe, requiring PROCESS_QUERY_LIMITED on the target plus PIP dominance.

PROCESS_TERMINATE — default action terminate, or terminate with a core dump:

PROCESS_SUSPEND_RESUME — default action stop or continue:

PROCESS_SIGNAL — default action ignore:

The real-time signals, SIGRTMIN through SIGRTMAX (32–64), default to terminate and therefore require PROCESS_TERMINATE.

3.3.3.2.1 What bypasses the check #

This classification applies only to signals sent by userspace through kill(), tkill(), and tgkill(). Kernel-generated signals — hardware faults such as SIGSEGV, SIGBUS and SIGFPE, SIGCHLD from a child exiting, SIGPIPE from a broken pipe — are delivered by the kernel and bypass the process descriptor check entirely, because the task_kill LSM hook does not fire for kernel-originated delivery.

Terminal-generated job control signals are kernel-originated under that rule and bypass the check the same way: SIGINT, SIGQUIT and SIGTSTP from the tty driver's isig handling, and SIGHUP on hangup. This is intentional. Authorization for keyboard-driven signals is possession of the controlling terminal, which was gated by the terminal's file descriptor at open time — so Ctrl-C reaches the whole foreground process group even when a member of it is more privileged or more PIP-trusted than whoever holds the terminal. A process that cannot accept that exposure must not attach to an untrusted controlling terminal.

The si_uid in a delivered signal's siginfo_t is the sender's projected UID (§3.10), captured at send time. Like every projected credential surface it is informational only and is not an authorization input; si_pid carries the same caveat and is subject to PID reuse besides.

3.3.3.3 Generic mapping #

3.3.3.4 The default process descriptor #

Every process receives a default descriptor at creation:

Owner: <creator's primary token user SID>
Group: <creator's primary token primary group SID>
DACL:
  ALLOW  <process's own user SID>   GENERIC_ALL
  ALLOW  BUILTIN\Administrators     GENERIC_ALL
  ALLOW  SYSTEM                     GENERIC_ALL
  ALLOW  Everyone                   PROCESS_QUERY_LIMITED

A process can therefore do anything to itself; Administrators and SYSTEM have full control over every process; everyone can see basic process information, which is what makes ps and top work for all users; and detailed inspection — token, memory, environment — is restricted to the process itself, administrators, and SYSTEM.

A service can modify its own descriptor at runtime with kacs_set_sd, which requires WRITE_DAC — granted to the process itself by the default DACL. Requesting a custom descriptor at launch through a service definition is not implemented: the only descriptor creation path always builds the default template, so every process starts from it and any deviation is a subsequent write.

3.3.3.5 How PIP relates to it #

PIP and the process descriptor are complementary, and both checks have to pass. The descriptor controls who may operate on the process; PIP controls what trust level is required for invasive access to a protected one. AccessCheck evaluates the caller's token against the target's descriptor for the requested right, and PIP evaluates the caller's trust against the target's pip_type and pip_trust for operations crossing the process boundary.

The two are genuinely independent. A process may have a permissive descriptor granting Administrators GENERIC_ALL and still be PIP-protected, so administrators pass the descriptor check and are stopped only by insufficient PIP trust.

The converse — a process with no PIP protection carrying a restrictive descriptor that denies even administrators — holds with one qualification. When a descriptor check denies access and PIP was not the deciding factor, an enabled SeDebugPrivilege on the caller grants the access anyway and is marked used. The privilege therefore rescues a descriptor denial while remaining unable to cross a PIP boundary, which is exactly the split §3.4.2 describes for it.

3.3.4.1 Fork #

The child receives a copy of the parent's PSB with a single exception: process_guid is not copied, and the child is given a new kernel-generated one. Everything else — the PIP fields, the mitigations, and any active restrictions — is inherited, so a Protected process's children start Protected and PIP propagates across fork.

The child also receives a new default process descriptor. Its owner is the forking thread's primary token's user SID, not the impersonation token's, even when the thread is impersonating at the time. The DACL follows the default template.

3.3.4.2 Exec #

The PIP fields are reset at exec from the new binary's cryptographic signature. A Protected parent that execs an unsigned binary loses PIP protection: protection follows the binary, not the lineage.

The mitigation flags — lsv, wxp, tlp, cfif, cfib, pie, sml, ui_access — are not reset. They persist across exec unchanged, so a mitigation set between fork and exec survives whatever binary is subsequently loaded. no_child_process persists in the same way: a process restricted from creating children stays restricted no matter what it execs.

process_guid is not reset either, because it identifies the process — the scheduling entity — rather than the binary.

The process descriptor is not reset. Exec preserves it unchanged. It was initialised at fork from the forking thread's primary token and reflects the process creation context, or a later explicit management context, rather than the binary being executed. Primary token installation and the other explicit process-descriptor mutation paths replace or modify it only under their own rules (§3.2.3).

3.3.4.3 Clone with CLONE_THREAD #

Threads share the process's PSB. Thread creation is unaffected by no_child_process, which blocks new processes only.

3.3.4.4 Relationship to AccessCheck #

The PSB is not an input to AccessCheck in the general case. AccessCheck takes a token and a descriptor and evaluates access; most PSB fields are invisible to it.

PIP is the exception. The pipeline includes a PIP enforcement step reading pip_type and pip_trust, which come from the PSB rather than from any token: the enforcement layer extracts them and passes them to AccessCheck as explicit parameters.

The asymmetry between MIC and PIP follows from that. MIC uses the effective token, so impersonation changes how it evaluates — which is safe because the integrity ceiling on impersonation (§3.5.2) prevents escalation. PIP uses the PSB, so impersonation cannot change how it evaluates — necessary because there is no impersonation gate constraining the PIP dimensions, making the PSB the only safe source.

The process mitigations and no_child_process do not interact with AccessCheck at all. Each is enforced at its own enforcement point, independently of the access control pipeline.

Some operations do not fit the subject-object model at all. Rebooting the machine, loading a kernel module, changing the system clock, creating a token — these affect the system itself rather than a specific protected resource, so there is nothing to attach a security descriptor to. They still need authorization.

Privileges fill that gap. A privilege is the right to perform a particular system operation, carried on the token beside the principal's identity. Where a descriptor says "this principal may read this file", a privilege says "this principal may shut down the system". The descriptor lives on the object; the privilege lives on the subject.

3.4.1.1 Lifecycle #

A privilege is assigned by policy when authd creates the token, resolving the principal's assignments from security policy once, at creation. There are no runtime grants: a privilege absent at creation can never be added later.

The privilege then sits on the token in whatever enabled state it was created with. The kernel accepts any enabled set that is a subset of the present set, and takes the creation-time enabled set as the enabled-by-default set. authd issues every privilege it grants already enabled, on the reasoning that a privilege the holder had to enable before it worked would be a grant in name only — so the present-but-disabled resting state exists in the model and is reachable through AdjustPrivileges, but is not where privileges normally start.

A privilege that has been disabled is re-activated by explicitly enabling it through AdjustPrivileges.

When the privilege is exercised, the kernel checks that it is both present and enabled — a single mask test against both words — permits the operation, and records it as used.

For a standalone gate, "exercised" means the gate accepted that bit, and the used bit is meant to be recorded even when a later independent check — a process descriptor, PIP, or a malformed-input test — denies the operation afterwards. Where the shared privilege helper performs the check, it marks the bit immediately, and the impersonation gate does the same. Three gates mark later and therefore record nothing when a subsequent check fails: token creation marks after the token has been constructed and its descriptor allocated, so a malformed specification leaves the bit unset; primary token installation marks after the same-user and same-LogonSession gate; and the CAP_SYS_BOOT mapping marks after the remote-shutdown origin gate.

Used-state for the AccessCheck-influencing privileges follows the provenance rules of §3.8 instead.

Recording the used bit is not merely bookkeeping. Every gate treats a failure to record it as a failure of the operation itself and returns EPERM or EACCES.

Afterwards the privilege may be disabled, returning to rest, or removed permanently, which clears it from the present, enabled, and enabled-by-default states while preserving the used bit for audit.

3.4.1.2 Two enforcement categories #

Standalone operation gates are the majority. They authorize specific operations that AccessCheck does not mediate — rebooting, loading modules, debugging processes — and the kernel simply checks whether the calling thread's token holds the privilege present and enabled before allowing the operation.

AccessCheck-influencing privileges alter the outcome of AccessCheck itself, causing it to grant rights the object's DACL would not grant on its own. They are evaluated inside the pipeline alongside DACL rules, integrity policy, and confinement. There are five: SeSecurityPrivilege grants ACCESS_SYSTEM_SECURITY for SACL access (and doubles as a standalone gate for the audit-related Linux capabilities); SeTakeOwnershipPrivilege grants WRITE_OWNER as a post-DACL fallback; SeBackupPrivilege grants all read access; SeRestorePrivilege grants all write access plus WRITE_DAC, WRITE_OWNER, DELETE and ACCESS_SYSTEM_SECURITY; and SeRelabelPrivilege loosens MIC's constraint on WRITE_OWNER for non-dominant callers. §3.8 gives the exact mechanics.

3.4.1.3 Intent gating #

SeBackupPrivilege and SeRestorePrivilege are intent-gated. Other AccessCheck-influencing privileges are self-scoping — SeSecurityPrivilege only matters when ACCESS_SYSTEM_SECURITY is requested — but backup and restore grant such broad categories of access that evaluating them unconditionally would apply them to every AccessCheck on the system.

AccessCheck therefore takes a privilege_intent parameter. A caller passes BACKUP_INTENT for a backup-context operation and RESTORE_INTENT for a restore-context one, and the corresponding privilege is evaluated only when its flag is present. Without the flag, these privileges are invisible to the pipeline.

Intent gating also keeps backup and restore inside the pipeline rather than short-circuiting it, which matters because later stages — PIP in particular — have to be able to constrain privilege-granted access.

3.4.1.4 Assignment #

Privileges are assigned by security policy, not by identity. Membership of the Administrators group confers no privilege by itself. Groups and privileges are orthogonal: groups determine which objects you can reach through DACLs, privileges determine which system operations you can perform.

An administrator defines policy — that members of Backup Operators receive SeBackupPrivilege and SeRestorePrivilege, say. At authentication authd resolves the principal's group memberships, evaluates the policy against them, and creates the token carrying the result. The kernel neither verifies nor evaluates that policy; it trusts authd as a TCB component. The token then carries those privileges for its whole lifetime.

3.4.1.5 Auditing #

Every exercise sets the token's monotonic used state for that privilege, and every standalone gate emits an ftrace event.

KMES audit events are emitted only for the five AccessCheck-influencing privileges, and only when the token's audit_policy opts in through PRIVILEGE_USE_SUCCESS or PRIVILEGE_USE_FAILURE. The event fires when the privilege's provenance bits intersect both the mapped desired mask and the final granted mask. For SeSecurityPrivilege and SeTakeOwnershipPrivilege that intersection is genuinely counterfactual — ACCESS_SYSTEM_SECURITY is pre-decided by the privilege, and take-ownership contributes only when WRITE_OWNER was not already granted — so an event means the privilege was load-bearing. Backup and restore seed their bits unconditionally, without asking whether the DACL would have granted the same access, so their events also fire for accesses the DACL alone would have permitted.

A MAXIMUM_ALLOWED request short-circuits this accounting entirely, recording no used bits and emitting no privilege-use events for any privilege.

The complete set of Peios privileges, with the bit each occupies in the token's four 64-bit privilege words. Format-compatible privileges sit at their standard Windows LUID positions in bits 2–35; custom Peios privileges are allocated downward from bit 63, so that a privilege defined by a future AD release cannot collide with one of ours.

Enforcement classes are: kernel standalone, enforced at a specific operation boundary independently of AccessCheck; AccessCheck, evaluated inside the pipeline; AccessCheck + standalone, both; application-level, checked by a userspace service rather than the kernel; and reserved, allocated for format compatibility with no enforcement point.

3.4.2.1 Identity and token management #

SeCreateTokenPrivilege mints tokens from scratch, and only TCB components — authd and peinit — carry it. SeImpersonatePrivilege lets a service impersonate a principal other than itself, and every service that handles requests on behalf of users needs it; it is checked in exactly one place, the impersonation identity gate (§3.5.2).

SeAssignPrimaryTokenPrivilege gates installing a token as a process's primary identity. Installation is self-directed: KACS_IOC_INSTALL acts on the calling process and fans out to the sibling threads of its own thread group. There is no mechanism for installing a token on a different process (§3.2.3). The kernel also requires the new token to carry the same user SID and the same LogonSession as the outgoing one, unless the caller additionally holds SeTcbPrivilege. The privilege is also consulted as a deny gate on the exec and credential projection paths.

3.4.2.2 Access control #

SeSecurityPrivilege reads and writes an object's SACL, and also gates CAP_AUDIT_CONTROL, CAP_MAC_ADMIN and CAP_AUDIT_READ through the capability mapping, the KMES ring buffer attach, and supplying a SACL at object creation.

SeTakeOwnershipPrivilege takes ownership of any object regardless of its permissions. It is the only privilege here with no standalone enforcement point at all — it exists purely inside AccessCheck.

SeBackupPrivilege and SeRestorePrivilege read and write any object regardless of the DACL. Inside AccessCheck they are intent-gated (§3.4.1), but both are also used as plain standalone gates outside it: restore on the descriptor replacement path when the cache is invalid and on owner assignment to a SID the subject does not hold, and both on the registry key backup and restore paths.

SeRelabelPrivilege changes an object's integrity label, punching WRITE_OWNER through MIC for non-dominant callers and removing the at-or-below-own-level restriction when a label is written.

SeChangeNotifyPrivilege bypasses traverse checking — without it, reaching a file requires FILE_TRAVERSE on every intermediate directory. The bypass has one exception the name does not suggest: it is suppressed when the access carries MAY_CHDIR, so an explicit chdir takes a full FILE_TRAVERSE check whether or not the caller holds the privilege. The privilege additionally gates open_by_handle_at, which has nothing to do with traversal. It is checked once per intermediate directory on every path resolution, and each check takes the token's mutation lock for a snapshot and then performs a used-bit update, so the cost is O(depth) locked operations per path walk.

SeCreateSymbolicLinkPrivilege creates symbolic links, and is required in addition to FILE_ADD_FILE on the parent directory.

3.4.2.3 System operations #

SeTcbPrivilege is the catch-all for system operations with no more specific privilege, and only TCB services need it. It has by far the widest reach of any privilege: fourteen Linux capability mappings, several token operations, the mount policy paths, the central access policy cache, LogonSession creation and destruction, removal of mandatory resource attribute ACEs during descriptor merge, a KMES rate limit exemption, the LCS source authentication path, and the upgrade of a linked-token query from an Identification-level copy to the real token at full access.

SeShutdownPrivilege shuts down or reboots the machine, mapped through CAP_SYS_BOOT. SeRemoteShutdownPrivilege is required in addition when the request originates from a Network, NetworkCleartext, or NewCredentials logon.

SeLoadDriverPrivilege loads and unloads kernel modules through CAP_SYS_MODULE. SeDebugPrivilege attaches to and inspects any process regardless of its descriptor, and does not bypass PIP (§3.7). SeSystemtimePrivilege changes the clock, SeIncreaseBasePriorityPrivilege raises scheduling priority and sets CPU affinity for other processes, SeIncreaseQuotaPrivilege overrides resource limits, SeLockMemoryPrivilege locks pages in physical memory, and SeAuditPrivilege writes events to the audit log — it is what KMES requires for userspace event emission.

SeProfileSingleProcessPrivilege attaches perf_event_open() to a specific other process. It respects PIP dominance, and own-task profiling requires nothing. SeSystemProfilePrivilege covers system-wide profiling — per-CPU events, all-task sampling, kernel-mode events — and does not respect PIP at the per-sample level, since system-wide samples include PIP-protected tasks. It is an operator-class privilege.

Those two and SeLoadDriverPrivilege share one mapping: CAP_PERFMON is satisfied by any of the three, and every one the caller holds is marked used. The two profiling privileges are otherwise disjoint tiers.

3.4.2.4 Network #

Binds TCP and UDP ports below 1024, mapped through CAP_NET_BIND_SERVICE. A custom Peios privilege, retaining the Linux convention as defence in depth.

3.4.2.5 Directory and domain operations #

SeSyncAgentPrivilege reads every object in the directory regardless of per-object permissions, for AD replication agents. SeEnableDelegationPrivilege marks a principal as trusted for delegation. SeMachineAccountPrivilege adds computer accounts to the domain. None has a kernel definition, which is consistent with their being application-level — but none has a userspace definition in the tree either, so at present nothing anywhere enforces them.

3.4.2.6 Reserved #

Allocated for format compatibility so that tokens from Active Directory environments carry them without information loss. None is defined in the kernel and none has an enforcement point.

3.4.2.7 Unallocated and unnamed bits #

SeCreateJobPrivilege is allocated bit 62 for submitting supervised jobs through JFS. No kernel definition exists for it. The bit is nevertheless included in the boot SYSTEM token's privilege set, which covers bits 2–35 together with 62 and 63, so the SYSTEM token holds bit 62 present and enabled with no name attached to it and no gate that consults it.

Nothing validates a privilege mask against the allocated set. Token creation checks only that the enabled set is a subset of the present set, and adjustment accepts any bit index from 0 to 63. Bits 0, 1, and 36–61 — positions the catalogue does not allocate at all — can therefore be set at creation and disabled or removed afterwards without error, and are simply inert.

3.4.2.8 Default grants #

SeChangeNotifyPrivilege is granted to every principal, as an authd policy decision rather than a kernel one: the issuer's floor grants it to Everyone. SeCreateSymbolicLinkPrivilege is not granted by default despite being the other traditional default-grant privilege — authd deliberately omits it from the floor, and no shipped seed grants it. Either can be removed from a specific token by FilterToken.

Impersonation lets a server thread temporarily assume a client's identity, so that access control decisions on that thread evaluate the client's token instead of the server's.

The client controls how far its identity can travel by setting an impersonation level on the connection before it is established, and the server cannot escalate beyond the level the client chose. There is no API that bypasses that choice.

Anonymous. The server cannot identify the caller at all. The connection carries no identity information: both token inspection and impersonation yield a token whose user SID is Anonymous (S-1-5-7), which carries Everyone as an enabled group and does not carry Authenticated Users.

Identification. The server can identify the caller — read SIDs, query groups, inspect privileges — but cannot act as them. An Identification-level token is barred from AccessCheck against resources: a server thread impersonating one and attempting to open a file simply fails the check.

Impersonation. The server can act as the caller for all local operations, including ones that cross local IPC boundaries. If service A impersonates client B at this level and connects to local service C, C sees B's identity — identity cascades freely across local services. This is the default.

Delegation. Locally identical to Impersonation. The distinction activates at the network boundary, where a Delegation-level token carries authorization for the server to forward the client's identity to services on other machines through Kerberos. KACS enforces the level; authd is what acts on it.

The level is set by the client through a KACS syscall on the socket before connect(), and defaults to Impersonation.

When a server thread attempts to impersonate a client's token, two independent checks decide whether it proceeds at the requested level. Both have to pass. If either fails the effective level is reduced to Identification — the movement is only ever downward.

Both gates are evaluated against the server's primary token (real_cred), never its effective token. A server already impersonating another client has its gates judged against its own service identity, so a previous impersonation cannot influence the next one.

3.5.2.1 The identity gate #

The identity gate asks whether this server may impersonate this particular user's identity. Impersonation at Impersonation or Delegation level is permitted if either of two conditions holds.

Same user, same restriction status — the server's primary token and the client's token carry the same user SID, and both are restricted or both unrestricted.

SeImpersonatePrivilege — the server's primary token holds it, enabled.

If neither holds, the level is silently capped to Identification. No error is returned: the call succeeds, and the resulting token is merely at Identification level.

There is one hard denial. A restricted server impersonating an unrestricted client of the same user is rejected outright with -EPERM rather than capped, because that is precisely how a sandboxed process would escape by impersonating its parent's unrestricted token. The reverse direction, unrestricted server to restricted client, is a harmless downgrade and takes the ordinary cap-to-Identification path.

MS-DTYP includes a third condition — an origin LogonSession check letting the session that created a token impersonate it without the privilege. KACS drops it. A service needing to impersonate a different user holds SeImpersonatePrivilege, and there are no hidden paths.

3.5.2.2 The integrity ceiling #

The integrity ceiling asks whether the client's token sits at an integrity level the server is allowed to assume. To act at Impersonation or Delegation level, the client token's integrity level has to be less than or equal to the server primary token's. A Medium-integrity server can impersonate Low or Medium clients; against a High-integrity client the level caps to Identification.

The installed token may keep the client's literal integrity label as identity metadata after the cap, but that preserved label authorizes nothing, because Identification-level tokens are barred from AccessCheck entirely.

The ceiling exists because MIC evaluates the effective token's integrity level for tokens that can act. Without it, a server could impersonate a higher-integrity token and gain write access to higher-integrity objects — integrity escalation through impersonation.

The ceiling is enforced unconditionally, regardless of privilege. SeImpersonatePrivilege bypasses the identity gate and never the ceiling. MS-DTYP allows the privilege to bypass every check including this one; KACS does not, because mandatory_policy is immutable here (§3.2.2) and MIC is consequently a real boundary. Letting a privilege punch through would give back exactly what that immutability buys.

3.5.2.3 Composition #

The two gates are independent, both are evaluated, and the effective level is the minimum any constraint permits: start from the level the client set on the socket, cap to Identification if the identity gate fails, cap to Identification if the integrity ceiling fails, and the result is the effective impersonation level.

3.5.3.1 The sequence #

The client connects. It optionally sets the maximum impersonation level through a syscall — the default is Impersonation — and calls connect(). The kernel's LSM hook fires on the Unix stream connection.

Identity is captured. The hook examines the client thread's effective credential together with the socket's maximum level. At Anonymous, a token whose user SID is S-1-5-7, whose enabled groups include Everyone, and which does not carry Authenticated Users is stored on the socket's LSM blob, and the client's real identity is never recorded. At Impersonation or Delegation, the thread's effective token is stored — and if the connecting thread is itself impersonating, the impersonated identity is what flows through, which is how identity cascades across local services. At Identification, the effective token is stored but tagged at that level.

The server impersonates by calling kacs_impersonate_peer with the connection fd. The kernel retrieves the stored token, evaluates both gates against the server thread's primary token, computes the effective level, and constructs a new credential carrying the impersonation token at that level.

Access control follows the impersonation token. Every subsequent AccessCheck on the thread evaluates it, and MIC uses its integrity level. PIP continues to read the PSB, unchanged.

The server reverts with kacs_revert(), restoring the thread's credential to real_cred and its service identity with it.

3.5.3.2 Anonymous #

Any thread may impersonate the Anonymous identity without passing either gate. Assuming Anonymous is always a downgrade — the token has no access beyond what is explicitly granted to S-1-5-7 or Everyone — so no privilege is needed, no identity gate runs, and no integrity ceiling applies.

Anonymous tokens carry the Anonymous SID as the user SID, no privileges, and Untrusted integrity. The socket path constructs that minimal shape rather than preserving any part of the caller's real identity.

3.5.3.3 Double impersonation #

A thread already impersonating that calls kacs_impersonate_peer again causes the kernel to revert internally and then re-impersonate. Because the gates are evaluated against the primary token, the previous impersonation has no bearing on the new one.

3.5.3.4 Interaction with MIC and PIP #

MIC reads the effective token for tokens permitted to act, which is safe precisely because the integrity ceiling makes acting impersonation safe. A thread cannot act at Impersonation or Delegation level with a client token whose integrity exceeds the server primary token's. When the ceiling caps the level to Identification, the installed token may still preserve the client's literal label as metadata, but it authorizes no resource access because Identification-level tokens are barred from AccessCheck. An acting impersonation token therefore preserves or lowers the server's integrity, and a higher literal label can only ever exist on a non-acting Identification-level token.

PIP reads the PSB, because there is no equivalent ceiling for it. PIP operates on pip_type and pip_trust, which are orthogonal to integrity level. Reading them from the effective token would let a process impersonate a token carrying higher PIP values and acquire protection it has not earned.

3.5.3.5 SeImpersonatePrivilege #

The privilege permits a service to impersonate arbitrary clients — those with different user SIDs. Without it a process can impersonate only tokens matching its own user SID and restriction status.

It is checked against the server's primary token, so a thread already impersonating one client is judged on its real service identity. It has to be enabled at the moment of the call. And it bypasses the identity gate only, never the integrity ceiling.

3.5.3.6 Delegation and the network boundary #

Locally, Impersonation and Delegation behave identically. The distinction activates at the network boundary, where a Delegation-level token carries authorization for Kerberos credential forwarding to services on other machines.

KACS tracks the level on the token and the socket, and authd checks it when it needs to perform Kerberos authentication for an impersonating thread. KACS itself has no Kerberos awareness and no network awareness: the level is a flag that authd interprets.

3.5.3.7 Supported transports #

Socket-based impersonation through kacs_impersonate_peer works on two socket types. SOCK_STREAM is the connection-oriented byte stream, and SOCK_SEQPACKET is connection-oriented with message boundaries and uses the same identity capture model. Both follow the same lifecycle: capture at connect(), impersonate, revert.

Three transports do not support it. SOCK_DGRAM is connectionless, so identity would arrive as per-message credentials — a different model that is not part of this syscall surface; datagram sockets create no KACS peer token. Sockets from socketpair() are pre-connected and unnamed, and while possession of the fd authorizes use of the channel, no peer-token snapshot is installed. Pipes and FIFOs have no peer credential mechanism at all.

For all of these, the universal fallback is explicit token fd impersonation through KACS_IOC_IMPERSONATE, which works regardless of how the token fd was obtained — socket-based capture, an SCM_RIGHTS transfer, kacs_open_peer_token, or any other path.

Binary signing is the foundation of PIP trust determination and of Library Signature Verification. The kernel verifies cryptographic signatures on executable files to establish their trust level, and signing is the only mechanism by which a binary acquires PIP protection — there is no runtime API that can confer it.

This section describes verification. The signature format itself, and what a signer has to produce, are specified in PSPK's Binary Signing and PIP chapter. The kernel only ever verifies; it holds no private key and contains no signing primitive.

3.6.1 The key table #

The kernel carries its verification keys in a dedicated data section of the kernel image, as an array of 1960-byte entries — a raw 1952-byte ML-DSA-65 public key, then a u32 little-endian PIP type, then a u32 little-endian PIP trust — terminated by an all-zero entry.

Before any cryptographic work, the whole table is walked and validated. A table with no all-zero terminator is rejected with EINVAL, and so is a table containing any entry whose tier is not exactly Protected (512) with PeiosTcb trust (8192). Both rejections fail every verification on the system, which is what makes the single-tier constraint absolute rather than conventional: a key at any other tier does not merely fail to be honoured, it disables signing entirely.

The consequence is that a verified binary is always Protected/8192. The Isolated type (1024) is reserved and unreachable, and the multi-key, multi-tier model the table layout anticipates would need a change to the validator, not merely an added key.

A build configured for KUnit compiles in a different, hard-coded key at the same tier, taken from the test vector header. Such a kernel trusts a publicly known key.

3.6.2 Finding a signature #

Verification begins by recording the file's current size. Everything that follows is bounded by that snapshot, and the size is re-read before the attempt returns — a file that changed size mid-verification invalidates the whole result.

The first four bytes decide the path. A file matching \x7fELF takes the ELF path; a file shorter than four bytes, or with different magic, goes straight to the xattr.

On the ELF path the kernel parses the header, locates the section header table and the section-name string table, and scans sections in index order for one named exactly .peios.sig. The match is over all eleven bytes including the terminating NUL, so a longer name with that prefix does not match.

Finding the section commits the ELF path. The moment a section header with that name is found, the xattr is no longer consulted — whatever happens next. A wrong section type, a size other than 3310, a range outside the file, an allocation failure, a short read, a bad version byte, or a hash failure all yield "unsigned" rather than falling back. This is deliberate: without it, an attacker could craft a malformed ELF section to force fallback to whichever path they could more easily control.

Several structural ELF failures commit the path too, before any .peios.sig section has been seen: a file shorter than an ELF header, a class other than ELFCLASS64, a byte order other than little-endian, an unexpected ELF version, a section header entry size other than 64, an absent or out-of-range section-name string table index, and a section header table or string table lying outside the recorded size. A 32-bit or big-endian ELF therefore cannot carry an xattr signature at all — it is committed to the ELF path and then fails on it. The one structural case that does not commit is e_shnum == 0, so an ELF with no section headers falls through to the xattr normally.

The xattr path reads security.peios.sig and requires exactly 3310 bytes; any other size is treated as unsigned. The read bypasses the LSM xattr hooks, so FACS does not mediate the verifier's own read of the signature.

3.6.3 Hashing and verification #

The message signed is a 32-byte SHA-256 content hash, computed differently depending on where the signature was found. For an ELF section source, the hash covers the file with the section's contents replaced by zeros — the Elf64_Shdr entry describing it is hashed verbatim, along with everything else. For an xattr source the hash covers the entire file with no exclusions, and that applies to ELF files reaching the xattr path as well as to non-ELF ones. Hashing proceeds in 4 KB chunks, with the zero run emitted in SHA256_BLOCK_SIZE pieces.

The kernel then verifies the 3309-byte signature against each key in the table, in order, returning on the first success. There is no key identifier in the blob, so key selection is exhaustive trial and the cost is one ML-DSA verification per key. The trust tier is a property of which key verified, never of anything the signer encoded.

Verification uses the kernel crypto signature API with the mldsa65 algorithm. That API exposes no context parameter, so the empty FIPS 204 context is structurally guaranteed rather than checked — a signature made under a non-empty context simply fails to verify.

3.6.3.1 When verification cannot be performed #

"Did not verify" and "could not be verified" are different answers and are kept apart. The per-key verifier is tri-state: verified, did not verify, or a negative errno meaning the check could not be made — an unavailable ML-DSA transform, or a key the transform will not accept.

A negative stops the search rather than trying the remaining keys: the failure is in the machinery, and every remaining key would meet the same one. It then propagates out of the exec path, which refuses the exec with EACCES.

That asymmetry with the ordinary unsigned path is the point. An unsigned binary runs with no integrity label, which is legitimate. Treating an unverifiable one the same way removes PIP from every process the system executes, and the result is indistinguishable from a correctly working system that has no signed binaries — so nothing surfaces it until signing is deployed, at which point it looks like the signing rollout broke something.

On the LSV path the same condition denies the mapping, which already fails closed.

3.6.3.2 The boot-time probe #

A late_initcall allocates the transform once and, if it cannot, emits pr_err and a KACS_SIGNING_CRYPTO_UNAVAILABLE KMES event carrying the errno. The condition is then visible at boot rather than inferred from every process running without an integrity label.

It cannot refuse to start, and two things rule that out rather than one:

• At LSM init the algorithm is not yet registered, so crypto_alloc_sig returns ENOENT on every boot. A probe there would fire always.
• A non-zero return from an LSM's init function is only WARN'd (security/lsm_init.c, lsm_init_single). The hooks are never added, so "refuse to initialise" means running with no KACS at all — worse than the failure it would be preventing.

Enforcement therefore lives at exec, where refusing one exec is recoverable in a way losing the integrity boundary is not.

The probe is not IS_ENABLED(CONFIG_CRYPTO_MLDSA). That option is an unconditional select under SECURITY_PKM, which is a bool, so a config test would always pass and catch nothing. Only calling the allocator sees the ordering failure.

3.6.4 PIP determination at exec #

At execve() the kernel looks up and verifies the signature as above. A verified binary takes pip_type and pip_trust from the matched key; no signature, an invalid or unstable one, a bad signature, or no matching key all yield None/0.

Exec proceeds in every case where the question could be answered. PIP is additive protection, not an execution gate: it determines trust level, not permission to run. The one exception is a signature that could not be verified at all, described above, which refuses the exec — because there the question was not answered, so there is no basis on which to assign a trust level. An attacker who replaces a signed binary's signature with garbage costs it PIP protection but can still execute it, subject to FACS. The asymmetry with LSV — which does block unsigned libraries — is intentional. Exec is permissive; mmap(PROT_EXEC) is restrictive.

Determination is transactional with exec success, in three phases. The pending value is cleared at the top of every bprm_creds_from_file invocation, staged into the task's security blob, and committed to the process state only from bprm_committed_creds. An exec that fails between staging and commit leaves the process state untouched, and the stale pending value is cleared by the next exec or at task teardown.

Because the hook fires once per binfmt iteration and each iteration re-stages, a #! script's PIP comes from the interpreter — the last file processed — not from the script. A TCB-signed interpreter runs at TCB level whatever script it executes. Symlinks need no special handling either: the LSM hooks receive the already-resolved target file, so a symlink inherits its target's level by construction.

Once committed, the values are fixed for the lifetime of the process image, inherited at fork, and re-derived at the child's exec.

3.6.5 Content pinning #

A binary that verifies to a nonzero tier has its backing inode pinned as KACS-verified executable content before the exec result is committed, and LSV pins on success too, before allowing the mapping. Pinning closes the gap between verifying one byte image and modifying the same inode afterwards.

If pinning fails at exec, the PIP result is downgraded to None/0 rather than the exec being failed or the tier being kept — the process runs unprotected. Under LSV a pin failure denies the mapping instead.

A pinned inode rejects in-place content mutation even when the size would be preserved: ordinary, positioned and append writes; ftruncate() and pathname truncate(); and every fallocate mode, including allocation-only ones, because the pin check runs before and independently of the mode-support test. File ioctls that mutate content, ranges, or allocation are rejected, and so are ioctls the kernel cannot classify — unknown ioctls fail closed on a pinned inode. Mutation or removal of the security.peios.sig xattr is rejected as well.

The pin is conservative and one-way. It is set once and cleared only when the inode is allocated or freed, never while the inode is live. Updating verified executable content therefore means replacing the inode — write a new file and rename() over it — rather than modifying it in place.

Unsigned, invalid, unstable, bad-signature and no-match attempts never pin.

3.6.6 Library Signature Verification #

With the lsv mitigation enabled, mmap() with PROT_EXEC on a file-backed mapping verifies the backing file. An unsigned file, an invalid or unstable one, a bad signature, or no matching key all deny the mapping with EACCES. On success the library's tier is compared against the loading process's: the image has to dominate the process, so a Protected/PeiosTcb process can load only PeiosTcb-or-above libraries. With one key in the table this reduces to "is it signed with the TCB key?"

The hash covers the entire file, not the mapped region — the whole file is read and hashed even when only part of it is being mapped, so the signature covers code in sections this particular mapping does not touch.

mprotect() adding PROT_EXEC to a mapping that was not already executable runs the same checks in a fixed order: WXP, then TLP, then LSV. Anonymous mappings have neither a path nor a signature, so TLP and LSV skip them and only WXP applies.

Enabling lsv on a running process also re-validates its existing executable mappings before the bit is committed (§3.3.2), so the mitigation cannot be turned on over already-mapped unsigned code.

3.6.7 Revocation #

There is none. A signed binary later found to be malicious cannot be invalidated short of removing it from the filesystem or replacing the kernel image with a different key. No hash blocklist, no per-key revocation, and no revocation state of any kind exists.

3.6.8 Interaction with other mechanisms #

WXP is orthogonal: it prevents pages being writable and executable at once, while LSV prevents unsigned executable pages. A process with both can execute only signed code in read-only pages.

FACS runs independently. A signed binary in a directory the caller cannot reach is still unreachable — the open is denied before signing is consulted. Signing determines the PIP level of a binary that is already being executed; it never grants access to one.

PIP object protection consumes the result: once a process carries a tier from its binary's signature, trust labels on objects are enforced through the AccessCheck pipeline against the pip_type and pip_trust held in the PSB (§3.7).

PIP protects objects from insufficiently trusted processes through trust label ACEs evaluated inside AccessCheck (§3.8.7). It also protects processes — their memory, their execution, their metadata — from other processes, which is what this section covers.

Every process-to-process operation passes two independent checks, and both have to succeed.

The process descriptor check is an ordinary AccessCheck of the caller's token against the target's process descriptor (§3.3.3). It answers who may operate on the process, and it is where per-operation granularity lives — different rights for signals, memory, and metadata.

The PIP dominance check is a direct comparison of the two processes' PSB fields. It answers what trust level is required. It does not use AccessCheck, does not read a descriptor, and does not involve the DACL pipeline at all: it is a standalone arithmetic test.

The two are complementary. Object PIP protection stops a non-dominant process opening authd's private key file; process PIP protection stops the same process reading the key straight out of authd's memory with ptrace, or killing authd with a signal.

3.7.1 The dominance test #

pip_dominates(caller_psb, target_psb) -> bool:
    if target_psb.pip_type == None:
        return true   // Unprotected target — any caller dominates.
    return caller_psb.pip_type  >= target_psb.pip_type
       AND caller_psb.pip_trust >= target_psb.pip_trust

Both axes are plain unsigned integers compared numerically, not closed enumerations — the dominance layer would happily order tiers the signing layer cannot currently produce (§3.3.2). The early return for an unprotected target is what keeps ordinary processes universally accessible whatever trust values a caller happens to carry.

Dominance is binary. A caller that does not dominate has no process access at all, whichever operation was attempted; the descriptor provides the granularity and PIP is the all-or-nothing gate above it.

That asymmetry with the object model is deliberate. Object access has natural categories — read, write, execute. Process access does not: a caller that can ptrace a process can read its memory, inject code, and effectively become it. Partial process access is not a meaningful boundary.

3.7.2 SeDebugPrivilege #

SeDebugPrivilege bypasses the descriptor check and never the dominance check. This holds at every enforcement point, and it is enforced structurally in two independent places: inside the descriptor evaluation a PIP-label denial short-circuits before the debug rescue is reached, and the standalone dominance test runs afterwards with no privilege escape of any kind.

3.7.3 Where dominance is enforced #

ptrace, in every mode. A single successful attach is equivalent to full compromise of the target — read and write memory and registers, single-step, inject signals, redirect execution — so a non-dominant caller is refused whatever the mode. The Linux __ptrace_may_access path is patched to return the LSM's answer directly, so native UID and capability rules no longer grant where KACS denies. Direct memory access through /proc/<pid>/mem, process_vm_readv and process_vm_writev routes through the same check, so one hook covers every memory-access vector. This is what makes in-memory secrets genuinely unreachable: a compromised administrator cannot read an HSM daemon's key material out of its address space.

PTRACE_TRACEME inverts the roles — the nominated tracer is the subject and the caller is the target — and requires PROCESS_VM_WRITE on the caller's own descriptor plus dominance by the nominated tracer.

Mode combinations are validated: the mutually exclusive PIDFD_OPEN, GETFD and PROC_QUERY flags cannot be combined, and a request that is neither a read nor an attach, or claims to be both, is rejected as malformed.

Signal delivery, uniformly regardless of signal type. Lifecycle management of PIP-protected processes therefore has to go through a process that dominates them — in practice peinit, which runs at the highest tier.

Signalling within the same process security state is not a boundary operation, and the exemption is structural: it is a pointer comparison of the two processes' security state, tested before any descriptor or dominance evaluation. It does not depend on the default descriptor's self ACE, which is what makes raise(), abort() and pthread_kill() work for restricted and confined tokens whose AccessCheck against their own descriptor would fail.

Multi-target sends are evaluated per target by Linux's own iteration, so the signal reaches the permitted subset and the call succeeds if at least one delivery happened. POSIX's same-session SIGCONT exception is deliberately absent — the patched check_kill_permission returns the KACS answer before reaching the switch that carried it — so SIGCONT needs PROCESS_SUSPEND_RESUME plus dominance like every other job-control signal, whatever the session.

Kernel-originated signals bypass the whole check, as described in §3.3.3.

pidfd_open(), a boundary information query rather than a memory or attach operation, needs PROCESS_QUERY_LIMITED plus dominance. pidfd_getfd() maps to PROCESS_DUP_HANDLE plus dominance — extracting a descriptor from another process is a boundary crossing in its own right.

/proc metadata. Entries that are already ptrace-gated or memory-open-gated are covered automatically by the ptrace hook. The rest would leak information about a protected process, so the non-ptrace-gated entries carry their own descriptor requirement plus dominance; §3.3.3 gives the mapping. Entries stricter than a metadata query, such as /proc/<pid>/stack, keep their native hardening and are not brought under the metadata rule.

Denying access prevents reading inside /proc/<pid>/ but does not hide the PID: the directory name is still visible through getdents. Visible-but-inaccessible is the accepted position.

/proc is not FACS-managed — it is a virtual filesystem with no backing store and no xattrs — so enforcement there happens through direct kernel checks rather than an object-backed FACS path.

Capability metadata. capget() on the current process, or on a thread sharing its security state, is not a boundary operation. Against another process it is a detailed information query needing PROCESS_QUERY_INFORMATION plus dominance.

Resource limits, scheduler and placement. Read-only prlimit needs PROCESS_QUERY_INFORMATION plus dominance; a limit change needs PROCESS_SET_INFORMATION plus dominance. setpgid() needs PROCESS_SET_INFORMATION; getpgid() and getsid() need PROCESS_QUERY_LIMITED; the scheduler, affinity and I/O priority queries need PROCESS_QUERY_INFORMATION; and the memory-placement mutations Linux routes through task_movememory need PROCESS_SET_INFORMATION. Setting nice, scheduler parameters and I/O priority all need PROCESS_SET_INFORMATION too. Self-directed versions of all of these are not boundary operations and skip both checks.

CPU affinity is per-thread, so changing the caller's own thread or a sibling in the same process is not a boundary operation. Changing a thread in a different process needs PROCESS_SET_INFORMATION plus dominance plus SeIncreaseBasePriorityPrivilege — and the privilege is checked and marked used before the descriptor and dominance call, so the SeDebugPrivilege rescue cannot substitute for it. KACS does not relax the kernel's native affinity validity rules: an invalid or disallowed mask still fails.

Token opens. kacs_open_process_token and kacs_open_thread_token need PROCESS_QUERY_INFORMATION plus dominance. Reading a process's security identity is as sensitive as reading its memory.

Performance monitoring. Target-specific perf_event_open() on another process can leak execution timing, branch prediction behaviour, cache access patterns and instruction traces — side channels that reveal cryptographic keys. It needs SeProfileSingleProcessPrivilege plus PROCESS_QUERY_INFORMATION plus dominance, with the privilege again checked first so the debug rescue cannot stand in for it. Own-task profiling is not a boundary operation and needs no privilege. System-wide profiling, pid == -1, samples every task on a CPU including protected ones, so it needs the operator-class SeSystemProfilePrivilege. Cgroup perf mode stays under Linux's native model. Because the target task is resolved after the stock security_perf_event_open hook fires, this rule is enforced through a target-resolved syscall patch rather than that hook — there is no security_perf_event_open registration at all.

3.7.4 The PeiosTcb floor on kernel-initiated execs #

One place PIP gates execution rather than merely labelling it. It is not a dominance test — there is no caller to compare against — but a threshold: a binary the kernel execs on its own behalf must carry at least PeiosTcb trust, or the exec fails with EACCES.

The case that motivates it is request_module(). When the kernel needs a module it does not have — get_fs_type() on a mount, socket() for an unknown protocol family, the crypto API resolving a name — it spawns CONFIG_MODPROBE_PATH as a usermode helper and runs it at the kernel's own authority. That path is a writable sysctl, which makes redirecting /proc/sys/kernel/modprobe a classic escalation: point it somewhere attacker-controlled and the next module request executes it with the kernel behind it. The floor makes the redirection worthless on its own, because the attacker would also have to produce a TCB-signed binary.

This is the only exec KACS refuses on integrity grounds. Everywhere else an unsigned binary runs and simply carries no tier, because a requesting process's own authority bounds what it can do. A kernel-initiated exec has no such process behind it, so there is no lesser authority to fall back to.

The floor also refuses when no tier could be derived at all, not only when one was derived and graded too low. Treating "could not establish trust" differently from "is not trusted" would leave the check bypassable by whatever prevented the derivation from running.

Nothing upstream identifies such an exec by the time the LSM sees it. The helper child is created by user_mode_thread(), so it never carries PF_KTHREAD — kernel_execve() rejects kernel threads outright — and security_kernel_module_request() fires in the requesting task, before the child exists. So kernel/umh.c is patched to mark the child after commit_creds() and before kernel_execve(), and the mark is read in the bprm_creds_from_file hook. It lives in the KACS task blob rather than costing a task_struct flag.

The mark is never cleared. A helper that re-execs — an interpreter for a #! helper — stays under the floor rather than escaping it on the second exec; the task exists only to be that helper.

A refusal emits kacs_exec with reason umh-not-tcb, so it is visible rather than presenting as an unexplained module-load failure.

3.7.5 Raw physical memory #

A process able to read /dev/mem could map any process's physical pages and bypass virtual memory protections entirely, PIP included.

The defence is CONFIG_STRICT_DEVMEM, which restricts /dev/mem to I/O regions and denies RAM access. It is not merely a recommended build option: the LSM refuses to initialise unless both CONFIG_STRICT_DEVMEM and CONFIG_MODULE_SIG_FORCE are enabled, so a kernel configured without them does not boot with KACS at all. The same initialisation gate refuses to coexist with SELinux, AppArmor, Smack, TOMOYO or the BPF LSM.

Placing a restrictive descriptor on /dev/mem and /dev/kmem as a secondary defence is not implemented; nothing in the kernel handles those paths specially.

3.7.6 Limits of the guarantee #

PIP operates inside the kernel's trust boundary, and three things sit outside it.

Kernel compromise. A loaded module runs with unrestricted access to all memory and kernel structures. PIP is enforced by the kernel, so a compromised kernel voids it, and SeLoadDriverPrivilege is the ceiling of every guarantee here. CONFIG_MODULE_SIG_FORCE is hard-required as noted above, and module signing is itself ML-DSA-65. Stripping SeLoadDriverPrivilege from every token but peinit's and the device manager's is the other half of that defence, and is policy rather than kernel behaviour — nothing in the kernel strips it. The device manager holds it because loading drivers for the hardware that appears is its job; module signature enforcement is what keeps the privilege from meaning more than "load a module Peios built".

Hardware access. DMA-capable devices read and write physical memory directly, bypassing the CPU's virtual memory system. An IOMMU mitigates this, and configuring one is a kernel responsibility outside KACS.

Hypervisor-level isolation. PIP does not offer guarantees equivalent to hypervisor-based memory isolation. The threat model ceiling is a non-compromised kernel.

3.7.7 Impersonation #

PIP reads the PSB, never the effective token. A Protected service impersonating a client still evaluates its own PSB for every process boundary check, so the client's identity has no bearing on it. In the other direction, an unprotected process impersonating a token created for a protected one gains nothing — its PSB is still None. Since nothing constrains the PIP dimensions the way the integrity ceiling constrains impersonation (§3.5.3), the PSB is the only safe source.

3.7.8 Coredumps #

A crashing PIP-protected process is a potential secret leak, so its dumps must not be readable by non-dominant processes.

The implemented strategy is to disable them: a process with a nonzero pip_type has its dumpable flag cleared at exec, and prctl(PR_SET_DUMPABLE, 1) is refused for as long as the process remains protected. Requests that keep or make it non-dumpable are allowed, and no alternative dumpable-setting path is left ungated. If a later exec assigns None/0, normal Linux exec-time dumpability rules apply to the new image.

The alternative — a signed, high-trust crash handler receiving dump data from the kernel and writing it under a restrictive descriptor, so that diagnostics survive without bypassing isolation — is not implemented. The two are not mutually exclusive; disabling dumps is the minimum viable position.

AccessCheck is the function that connects tokens to security descriptors. Given a token — who is asking — a descriptor — what the rules are — and a desired access mask — what they want to do — it returns a verdict: which of the requested rights are granted, and whether the request as a whole succeeds.

It is a pipeline, evaluating several layers of policy in a fixed order. Each layer can grant or constrain access and the layers interact: integrity policy can block what the DACL would allow, privileges can override what the DACL denied, and confinement can revoke what privileges granted. The order is not incidental — it is the specification.

3.8.1.1 Two API variants #

AccessCheck is the common case. It returns the granted access mask, whether the request succeeded, a continuous audit mask derived from SACL alarm ACEs, and a CAAP staging mismatch flag. When an object type list is supplied, success requires every listed node to pass and the returned mask is the intersection across them. The staging mismatch flag is set when the staged scalar result differs from the effective scalar result, when any per-node staged grant differs from the effective per-node grant, or when staged auditing differs from effective auditing.

AccessCheckResultList is the per-property variant and requires an object type list. It returns a separate verdict for each node, so a denial on one property fails that property alone rather than the whole request. It returns the same continuous audit mask and staging mismatch flag, with the flag set when any node's staged granted mask differs from that node's effective granted mask, or when staged auditing differs from effective auditing. Directory services use it, because one operation there may touch several properties with independent access rules. Privilege-use auditing in this variant takes the same per-node view: a privilege counts as successfully used if its contributed bits survive on any node's final granted mask.

Both variants share one evaluation pipeline. Only the collection of results differs.

3.8.1.2 The three state values #

Every access check tracks three masks.

decided records which bits have been resolved. It enforces first-writer-wins within the DACL walk: once a bit is decided, no later ACE in the same walk changes its outcome. Pipeline layers that operate on top of the DACL result — restricted token intersection, confinement intersection, PIP revocation, CAAP intersection — may still revoke granted bits. Those layers narrow the result; they do not re-open decided bits for re-evaluation through the DACL.

granted records which bits resolved to yes. During the walk it is a subset of decided. Afterwards the later layers may remove bits from it, and the final value is what the caller receives.

privilege_granted records which bits in granted came from a privilege rather than from the DACL. It exists for two reasons: audit accuracy, so that privilege-granted access is distinguishable from DACL-granted access, and the restricted token merge, where privilege-granted bits are restored after the intersection so that privileges bypass the restricted pass. PIP may revoke privilege-granted bits.

With an object type list present, each node carries its own decided and granted pair.

The DACL is an ordered list of ACEs, walked from first to last, comparing each ACE's SID against the calling token's identity. The governing principle is first-writer-wins: once a bit has been resolved, granted or denied, no later ACE changes the outcome for that bit.

An allow ACE whose SID matches the token grants the rights it carries that have not yet been decided, leaving already-decided bits untouched. A deny ACE whose SID matches denies its not-yet-decided rights — marking them decided but not granted — and likewise leaves decided bits alone.

3.8.2.1 SID matching #

An ACE's SID matches the token when it equals the user SID or a group SID on the token, subject to attribute filtering.

For allow ACEs, only groups that are enabled and not deny-only match. For deny ACEs, both enabled groups and deny-only groups match: a deny-only group always participates in deny matching whatever its enabled state. A group with neither SE_GROUP_ENABLED nor SE_GROUP_USE_FOR_DENY_ONLY participates in no matching at all.

The user SID follows the same rule — when user_deny_only is set on the token, it matches deny ACEs and not allow ACEs.

3.8.2.2 Skipping and mapping #

ACEs carrying INHERIT_ONLY exist purely to propagate to child objects and are skipped by the walk.

At the top of the walk each ACE's access mask is mapped through MapGenericBits using the same GenericMapping applied to the caller's request. The mapping works on a local copy — the ACE itself is never mutated. Mapping ACE masks at evaluation time is a deliberate departure from MS-DTYP, and it is what makes GENERIC_ALL work in central access policy recovery ACEs (§3.8.8).

3.8.2.3 Absent and empty DACLs #

If the descriptor has no DACL — SE_DACL_PRESENT unset — every valid right not already decided by an earlier pipeline stage is granted. The valid rights are bounded by MapGenericBits(GENERIC_ALL, mapping) rather than by a raw 0xFFFFFFFF.

If the DACL is present but holds zero ACEs, the walk grants nothing. The only access an owner gets in that case comes from the implicit rights mechanism below.

3.8.2.4 Owner implicit rights #

By default the owner of an object receives READ_CONTROL and WRITE_DAC whatever the DACL says. These are granted before the walk begins, as the first action inside EvaluateDACL, and because first-writer-wins governs the walk, no deny ACE encountered later can override them.

EvaluateDACL takes a skip_owner_implicit parameter. The confinement pass sets it, because confinement is an absolute intersection with no owner bypass.

The grant is suppressed entirely if any non-inherit-only access-control ACE in the DACL targets the OWNER RIGHTS SID (S-1-3-4). This is a pre-scan performed at the start of EvaluateDACL, before the main loop, and it checks only for the SID's presence — it does not evaluate any conditional expression on the ACE.

During the walk proper, S-1-3-4 is treated as an ordinary SID matching the owner, at both allow and deny polarity. It obeys the same rules as any other SID: an allow ACE matches only through an enabled, non-deny-only group, and not through the user SID of a user_deny_only token; a deny ACE matches through a group that is enabled or deny-only, and through the user SID unconditionally.

Note that the implicit grant above is a separate rule and remains presence-based. It is bounded by the pre-scan rather than by polarity.

The implicit grant is also bounded twice over: by the object type's valid rights, and by what has already been decided. A pre-decision from MIC, PIP or a privilege therefore suppresses it — a non-dominant owner does not receive WRITE_DAC through this route.

3.8.2.5 MAXIMUM_ALLOWED #

When the caller includes MAXIMUM_ALLOWED (bit 25), AccessCheck runs the full pipeline and returns the complete set of rights that would be granted. The bit is stripped from the desired mask before evaluation begins.

Two things change. The walk runs to completion with no short-circuit, and the returned mask is whatever the pipeline accumulated rather than being filtered to the requested bits.

MAXIMUM_ALLOWED can be combined with specific rights: MAXIMUM_ALLOWED | READ_CONTROL asks both "can I read the descriptor?" as a success or failure and "what else could I get?" as a mask. A pure MAXIMUM_ALLOWED request carrying no specific bits always succeeds.

Otherwise — when the desired mask is fully decided — the walk may stop early.

First-writer-wins applies to MAXIMUM_ALLOWED requests exactly as it does to targeted ones. MS-DTYP treats the two differently; KACS does not, which is what stops "what can I do?" and "can I do this?" disagreeing on a DACL that is not in canonical order.

MIC is a mandatory constraint that restricts which rights the DACL is allowed to grant, along a vertical trust hierarchy. It is evaluated before the DACL walk, in the pre-SACL phase.

Every token carries an integrity level, and every object may carry a mandatory label — a SYSTEM_MANDATORY_LABEL_ACE in its SACL. MIC compares the two: a caller below the object's level is blocked from whole categories of access whatever the DACL says.

The default is no-write-up. A lower-integrity process can read and execute a higher-integrity object but cannot write to it, and the object's label may additionally block reads or execution for callers beneath it.

An object with no mandatory label ACE in its SACL — or no SACL at all — is treated as Medium integrity with no-write-up, so Low and Untrusted processes cannot write to unlabelled objects.

A caller whose level is greater than or equal to the object's label dominates it, and MIC pre-decides nothing: the DACL handles authorization normally.

3.8.3.1 What MIC does and does not touch #

MIC constrains what the DACL can grant. It does not revoke what privileges have already granted, because it mutates only decided and never touches granted or privilege_granted.

ACCESS_SYSTEM_SECURITY is outside its reach for a structural reason: the bits MIC can decide are bounded by MapGenericBits(GENERIC_ALL, mapping), which does not include it. The right is privilege-granted rather than DACL-granted, so MIC never blocks it. PIP is stricter and does revoke it for non-dominant callers — explicitly ORing it into the set of bits it can take away — which is the mechanism by which objects stay protected even from administrators.

SeRelabelPrivilege has one specific interaction: it lets the DACL grant WRITE_OWNER even when an integrity mismatch would otherwise block it, so a privileged administrator can take ownership of a higher-integrity object as the first step in modifying it. The bit granted this way is recorded under its own provenance and is deliberately not part of privilege_granted, so it is not restored after the restricted merge and is not preserved by the CAAP error escape hatch.

Enforcement is gated on the token's mandatory_policy: with NO_WRITE_UP set — the default — the rule applies, and with it clear MIC is effectively disabled for that token. The field is fixed at creation (§3.2.2), which is what makes MIC a boundary rather than a suggestion.

3.8.3.2 Labels #

An object's SACL may carry more than one mandatory label ACE. Only the first non-inherit-only one is used; inherit-only labels do not apply to the object carrying them.

The SID in a mandatory label ACE has the Mandatory Label authority (S-1-16) and exactly one sub-authority, and that sub-authority value is the integrity level, compared as an unsigned integer. Any S-1-16-X is therefore valid.

Peios tooling and authd use these five, but intermediate values such as S-1-16-2048 or S-1-16-8448 are valid and compared numerically, which is what allows Windows-originated descriptors carrying non-standard levels to be evaluated without translation.

A label ACE whose SID falls outside the S-1-16 authority — wrong identifier authority, or the wrong sub-authority count — is malformed, and so is one that is not a plain single-SID ACE. Either causes AccessCheck to reject the whole descriptor with an error rather than ignore the label.

3.8.3.3 Policy bits #

Unknown bits in a label mask are ignored.

3.8.3.4 The algorithm #

EnforceMIC(ace, token, mapping, &decided):

    if not (token.mandatory_policy & NO_WRITE_UP):
        return

    token_dominates = (token.integrity_level >= ace.integrity_level)

    if token_dominates:
        return

    // Non-dominant: start with read + execute, strip per label policy.
    allowed = MapGenericBits(GENERIC_READ, mapping)
            | MapGenericBits(GENERIC_EXECUTE, mapping)

    if ace.mask & SYSTEM_MANDATORY_LABEL_NO_READ_UP:
        allowed &= ~MapGenericBits(GENERIC_READ, mapping)
    if ace.mask & SYSTEM_MANDATORY_LABEL_NO_WRITE_UP:
        allowed &= ~MapGenericBits(GENERIC_WRITE, mapping)
    if ace.mask & SYSTEM_MANDATORY_LABEL_NO_EXECUTE_UP:
        allowed &= ~MapGenericBits(GENERIC_EXECUTE, mapping)

    // READ_CONTROL and SYNCHRONIZE are always allowed regardless of the
    // object type's GenericMapping and the label's up-strip policy — a
    // non-dominant caller can always read the descriptor and synchronize
    // on the object. Applied after the strips because a file GENERIC_READ
    // mapping folds these bits in, so NO_READ_UP would otherwise take them.
    allowed |= READ_CONTROL | SYNCHRONIZE

    // SeRelabelPrivilege: let WRITE_OWNER through MIC.
    if token.privilege_enabled(SeRelabelPrivilege):
        allowed |= WRITE_OWNER

    all_bits = MapGenericBits(GENERIC_ALL, mapping)
    decided |= all_bits & ~allowed

A restricted token carries a secondary SID list, the restricting SIDs. The second pass runs whenever that list or the restricted device group list is non-empty, and AccessCheck evaluates the DACL twice.

The normal pass evaluates the DACL against the token's ordinary identity — user SID and group SIDs — exactly as usual. The restricted pass evaluates the same DACL again with SID matching drawn only from the restricting SID list; the token's normal groups are invisible to it. Conditional membership operators — Member_of, Member_of_Any, and their device variants — take the same restricted view, seeing only the restricting SIDs plus any virtual groups injected from that list.

The restricting SID list is presence-based. A SID participates whenever it appears in the list, and SE_GROUP_ENABLED and SE_GROUP_USE_FOR_DENY_ONLY on those entries are ignored both for restricted-pass SID matching and for restricted-pass non-device conditional membership. This matches Windows restricted-token behaviour, where restricting SIDs are always enabled for access checks.

Access is granted only for rights both passes agree on — the intersection. The restricting list acts as a ceiling: the principal can never receive more access than the restricting SIDs would independently justify.

3.8.4.1 Write-restricted tokens #

In the write-restricted variant the intersection applies only to write-category bits, and read and execute access comes from the normal pass alone. What counts as write is whatever the object type's GenericMapping maps GENERIC_WRITE onto.

3.8.4.2 Privileges bypass the restricted pass #

Rights granted by privileges are added back after the intersection. Privileges are system-level grants from security policy rather than from the object's DACL: token restriction reduces the identity-based access surface, and privilege-based grants are orthogonal to it. The bits restored are the post-PIP privilege-granted set together with the take-ownership grant.

3.8.4.3 Owner rights and virtual groups in the restricted pass #

The restricted pass evaluates owner implicit rights independently. If the object's owner SID appears in the restricting SID list, the pass grants READ_CONTROL and WRITE_DAC, subject to the same OWNER RIGHTS suppression pre-scan as the normal pass; if the owner SID is not a restricting SID, no implicit rights are granted.

Two virtual groups are injected on the same basis. S-1-3-4 (OWNER RIGHTS) is injected when the object's owner SID is among the restricting SIDs, and S-1-5-10 (PRINCIPAL_SELF) when self_sid is. This keeps the restricted pass consistent in its handling of these well-known SIDs rather than letting them leak the unrestricted identity.

Restricted device groups, when the token has them, are swapped in for the restricted pass so that Device_Member_of and its relatives evaluate against the restricted set rather than the unrestricted device groups.

An object ACE carries a GUID identifying the property or property set its rule applies to, which is what enables per-property access control on objects with internal structure — Active Directory objects, most obviously. An object ACE with no GUID, meaning ACE_OBJECT_TYPE_PRESENT is unset, behaves exactly like a basic ACE.

3.8.5.1 Object type lists #

To request property-level access the caller supplies an object type list: a tree of GUIDs representing the properties being asked for. Each node carries its own decided and granted pair and is resolved independently.

With no list supplied, object ACEs with GUIDs apply globally, as if they were basic ACEs. With a list supplied, every ACE that behaves like a basic ACE — ordinary basic ACEs, and object ACEs without an ObjectType GUID — applies to every node in the tree. An object ACE whose GUID does not appear anywhere in the supplied tree is silently skipped.

3.8.5.2 Propagation #

Decisions move through the tree in four ways.

Downward from grants. A grant on a property set flows to every attribute within it, each child node still applying first-writer-wins for itself.

Upward from grants. When every attribute within a property set has been granted the same right, that right propagates up to the set's node. The propagation is a per-bit intersection, so a right reaches the parent only if all siblings share it.

Upward from denials. A denial on an attribute propagates to every ancestor regardless of what its siblings hold, and siblings are themselves unaffected. Ancestors still apply first-writer-wins to the propagated bits, so a denial cannot overturn something an ancestor had already decided.

Downward from denials. A denial on a property set flows to every attribute within it, again subject to first-writer-wins.

3.8.5.3 PRINCIPAL_SELF #

PRINCIPAL_SELF (S-1-5-10) is a placeholder for the object's associated principal. An ACE targeting it matches the caller when the caller's token represents the same principal as the object, which the caller establishes by passing the object's principal SID as the self_sid parameter. With a null self_sid, PRINCIPAL_SELF ACEs match nothing.

It follows the ordinary deny-only rules: if the caller's matching SID is deny-only, PRINCIPAL_SELF matches deny ACEs but not allow ACEs.

3.8.5.4 Scalar and per-node results #

AccessCheck requires every node to pass, so a denial on any one property fails the whole request. AccessCheckResultList returns a separate verdict per node.

The scalar result AccessCheck returns is the root node's granted mask. That is equivalent to the intersection across all nodes, but by construction rather than by computation: upward denial propagation forces every descendant's denial into all of its ancestors' decided sets, which guarantees the root's granted mask is a subset of every node's.

3.8.5.5 Validation #

Object type lists are validated strictly, at parse time. A supplied list is non-empty; its first node is at level 0; there is exactly one level-0 node; there are no level gaps, meaning no node at level N+2 following one at level N; and no GUID appears twice.

These checks are stricter than MS-DTYP, which does not specify them. They exist because a duplicate GUID makes node lookup return the wrong node, and a level gap makes propagation undefined.

Confinement restricts a token's effective access to what is explicitly granted to its confinement identity. Even where the normal DACL walk grants access through the user SID or a group SID, the confinement pass intersects that with what the confinement SIDs would receive on their own, and revokes anything they cannot independently justify.

A confined token carries confinement_sid, its confinement identity; confinement_capabilities, the capability SIDs the application declares; and confinement_exempt, an escape hatch that skips confinement evaluation entirely.

The confinement SID set is confinement_sid together with every SID in confinement_capabilities. Capabilities are presence-based identities rather than ordinary ACE-matching groups: a capability SID participates whenever it is present, and disabling an entry or marking it deny-only does not remove it from the confinement identity.

The pass also injects two confinement-scoped virtual groups. S-1-5-10 (PRINCIPAL_SELF) is injected only when self_sid equals the confinement SID or one of the capability SIDs, and S-1-3-4 (OWNER RIGHTS) only when the object's owner SID does. Both apply to ACE SID matching during the confinement walk and to the conditional membership operators — Member_of, Member_of_Any, and their device and negated variants — evaluated during that pass.

3.8.6.1 An absolute boundary #

Confinement is not overridable. Privileges do not bypass it: the confinement merge takes no privilege-granted input at all, so backup, restore, SeTakeOwnershipPrivilege and SeSecurityPrivilege are alike unable to grant access the confinement check denies. Owner implicit rights are skipped entirely, because the pass runs with skip_owner_implicit set.

One thing does pass through: an object with a null DACL grants in the confinement pass exactly as it does in the normal pass. A null DACL means "no discretionary restrictions", and the confinement pass follows standard evaluation, granting all valid bits.

3.8.6.2 Strict confinement #

A normal confined token carries both ALL_APPLICATION_PACKAGES and ALL_RESTRICTED_APPLICATION_PACKAGES among its capabilities. Omitting ALL_APPLICATION_PACKAGES gives strict confinement: far fewer system objects grant to ALL_RESTRICTED_APPLICATION_PACKAGES, so the access surface is much narrower.

Strict confinement is not a separate kernel mode bit. It is derived purely from the SID set supplied at token creation — if ALL_APPLICATION_PACKAGES is absent, AccessCheck simply evaluates the remaining confinement SIDs. The kernel never synthesises it, and never rejects an otherwise valid confined token for carrying it. Deciding which capabilities a package token receives belongs to authd and policy tooling.

3.8.6.3 Consequences worth stating #

SACL access is unreachable. ACCESS_SYSTEM_SECURITY is only ever privilege-granted, and privileges do not bypass confinement, so a confined token cannot reach a SACL unless a confinement ACE grants the right outright.

OWNER RIGHTS is confinement-scoped. S-1-3-4 matches in the confinement pass only when the owner SID is part of the confinement SID set.

PRINCIPAL_SELF is isolated from user identity. S-1-5-10 is injected only when self_sid matches a confinement SID — the package SID or one of its capabilities — not when it matches the user.

Conditional expressions still see the full token. The confinement pass isolates ordinary SID matching to the confinement identity, but conditional expressions inside ACEs continue to evaluate against the user's real groups and claims. The two confinement-scoped virtual groups are the only exception, and they follow the confinement rules during conditional membership evaluation.

3.8.6.4 Ordering #

Confinement runs after the restricted token merge and after its privilege restoration. The order is load-bearing: privileges bypass the restricted pass but must not bypass confinement, and if confinement ran first the privilege restoration would resurrect bits that confinement had already blocked.

An object opts in to PIP protection by carrying a SYSTEM_PROCESS_TRUST_LABEL_ACE in its SACL. The ACE's SID encodes the required type and trust, and its access mask names exactly the rights a non-dominant caller may still have.

A caller that dominates — pip_type and pip_trust both greater than or equal to the ACE's — is unrestricted by PIP. A caller that does not dominate is limited to the ACE mask, and everything else is denied.

Unlike MIC, PIP has no default. An object with no trust label is unrestricted, reachable by any process whatever its PIP identity.

3.8.7.1 The label SID #

A trust label SID has the form S-1-19-{type}-{trust} — the Process Trust authority, exactly two sub-authorities. Both axes are compared numerically. The conventional type values are 0 (None), 512 (Protected) and 1024 (Isolated), but they are labels rather than a closed enum: any other numeric type is valid and compared by the same dominance rule.

A trust label SID of any other shape — wrong authority, wrong sub-authority count — makes the descriptor malformed, and AccessCheck rejects it outright rather than guessing.

Where a SACL carries more than one trust label ACE, only the first non-inherit-only one is used; inherit-only labels do not apply to the object carrying them.

3.8.7.2 Privilege revocation #

This is the critical difference from MIC. PIP does not merely constrain what the DACL may grant — it revokes rights privileges already granted. A non-dominant caller who used SeBackupPrivilege to obtain read has those bits stripped; SeTakeOwnershipPrivilege's WRITE_OWNER is stripped; SeSecurityPrivilege's ACCESS_SYSTEM_SECURITY is stripped.

The last of those is the point. Without privilege revocation, a non-dominant administrator holding SeSecurityPrivilege could read the SACL of a PIP-protected object — and remove the trust label from it. PIP would be self-defeating.

There is no escape hatch. PIP has no SeRelabelPrivilege equivalent, and no privilege compensates for insufficient trust. It is an absolute boundary, which is why the enforcement step explicitly ORs ACCESS_SYSTEM_SECURITY into the set of bits it can take away — that right is outside the generic mapping and would otherwise escape.

3.8.7.3 The algorithm #

EnforcePIP(ace, pip_type, pip_trust, mapping, &decided,
           &granted, &privilege_granted):

    // pip_type and pip_trust are the subject's process-trust context,
    // not a token field. See "Where the values come from" below.

    ace_type  = ace.sid.pip_type
    ace_trust = ace.sid.pip_trust

    caller_dominates = (pip_type  >= ace_type
                    and pip_trust >= ace_trust)

    if caller_dominates:
        return

    // Non-dominant: the ACE mask IS the allowed set.
    allowed = MapGenericBits(ace.mask, mapping)

    // Everything not explicitly allowed is denied, including
    // ACCESS_SYSTEM_SECURITY.
    all_bits = MapGenericBits(GENERIC_ALL, mapping)
             | ACCESS_SYSTEM_SECURITY
    pip_denied = all_bits & ~allowed

    decided |= pip_denied

    // Revoke privilege-granted rights.
    granted           &= ~pip_denied
    privilege_granted &= ~pip_denied

3.8.7.4 Where the values come from #

pip_type and pip_trust are the subject's process trust context and are never derived from a token field — the token structure has no PIP field at all. They are passed into AccessCheck as explicit parameters by whichever layer is enforcing.

During enforcement — FACS file access, process boundaries — the values are the subject process's PSB, set at exec from the binary's signature (§3.6, §3.7).

The kacs_access_check query may instead supply them through its arguments, per axis: zero means "use the calling process's PSB value" and a nonzero value evaluates against the supplied context. This lets a userspace broker evaluate access under a client's trust level, in the same way the query's token argument lets it evaluate a token other than its own. The query is advisory and gates nothing in the kernel; enforcement always uses the PSB. The same effective values are used for the verdict and for the event the check emits, so an audit record never disagrees with the decision it describes.

The enforcement step also computes a record of which bits PIP decided. Nothing currently consumes it — it is threaded through three structures and exported, and no caller reads it.

CAAP separates policy definition from the objects it governs. A policy is defined once, centrally; objects reference it by SID through a SYSTEM_SCOPED_POLICY_ID_ACE in their SACL. When the policy changes, every future AccessCheck against a referencing object uses the new rules — already-open handles are unaffected, because the model is check-at-open.

It extends the Windows Central Access Policy model by adding an audit component: each rule carries both an access restriction and an audit requirement.

3.8.8.1 Policy structure #

A policy is a named collection of rules identified by a policy SID. Each rule carries:

An optional applies-to condition, a conditional expression determining whether the rule governs this decision. It may reference the @Resource, @User, @Device and @Local claim namespaces, but it cannot inspect SID or device-group membership: Member_of, Member_of_Any, Device_Member_of, Device_Member_of_Any and their negated forms all evaluate to UNKNOWN inside applies_to. A rule with no condition applies to every object referencing the policy.

A mandatory effective DACL — a real DACL evaluated through the full pipeline. An optional effective SACL, whose audit ACEs merge with the object's own during the audit walk. And optional staged DACL and SACL, proposed replacements used for testing.

3.8.8.2 Access evaluation #

The DACL result is ANDed with the normal evaluation. CAAP can only restrict, never expand: if the object's DACL grants read and write but the applicable rule's effective DACL grants only read, the result is read.

A SACL may carry several scoped policy ACEs, which makes policies composable — and the AND semantics are what make composition safe, since each additional policy can only narrow. Inherit-only scoped policy ACEs do not apply to the object carrying them and are ignored during lookup. MS-DTYP allows one scoped policy ACE per SACL; KACS allows several.

For each scoped policy ACE, AccessCheck looks the policy up in the kernel cache, then for every rule whose applies_to is TRUE or absent evaluates the rule's effective DACL through the full pipeline — privilege grants, MIC, PIP, the DACL walk, restricted tokens, confinement — and intersects the result with the running total, which starts at the normal evaluation's granted mask.

A rule whose condition evaluates FALSE or UNKNOWN is skipped. That is deliberately the opposite of the deny-ACE UNKNOWN rule: skipping is the conservative choice here, because a rule's DACL can only narrow what the normal DACL already granted.

If no rules apply — every condition false or unknown, or the policy has no rules — CAAP has no effect and the normal result stands.

The rule's DACL is evaluated with backup and restore intent not passed: intent is a caller concern, not a policy concern. And CAAP never recurses. A rule's synthetic descriptor has scoped policy ACEs stripped before evaluation, so nested CAAP evaluation cannot occur even when the original SACL carried more of them. The synthetic descriptor keeps the original owner and group, and preserves the MIC and PIP labels, so a rule is evaluated against the same mandatory constraints as the object itself.

3.8.8.3 Audit evaluation #

For each applicable rule carrying an effective SACL, the rule's audit ACEs are evaluated alongside the object's own during the audit walk. They are treated identically — if either says to audit an operation, it is audited.

The SACL component is purely additive. A CAAP SACL can add audit coverage and can never suppress auditing the object's own SACL asks for.

3.8.8.4 The policy cache #

The kernel keeps a map from policy SID to policy object, empty at boot. Policies are pushed in through kacs_set_caap, which requires SeTcbPrivilege — and marks it used. A non-null spec for an existing SID replaces the policy; a null spec or zero length removes it. The policy SID's length is bounded to 8–68 bytes before parsing begins, and until the cache has been initialised both setting and evaluating fail with EACCES.

The wire format is:

[version:u8 = 0x01]
[rule_count:u32le]
per rule:
  [applies_to_len:u32le][applies_to_expr bytes]     (0 = no condition)
  [effective_dacl_len:u32le][effective_dacl bytes]  (MUST NOT be 0)
  [effective_sacl_len:u32le][effective_sacl bytes]  (0 = no audit rules)
  [staged_dacl_len:u32le][staged_dacl bytes]        (0 = no staged DACL)
  [staged_sacl_len:u32le][staged_sacl bytes]        (0 = no staged SACL)

All lengths are little-endian u32. ACLs use the standard binary format, and every ACE type valid in a DACL or SACL is permitted inside a policy ACL. The applies_to expression is conditional ACE bytecode, carrying the same artx prefix as callback ACE application data.

The limits are a spec of at most 256 KB, at most 256 rules, an applies_to of at most 64 KB, and an individual ACL of at most 64 KB. The version byte has to be 0x01. Trailing bytes after the declared rules are rejected.

Validation is strict and total. Malformed or truncated applies_to bytecode fails the whole call with EINVAL at ingestion rather than being admitted and later treated as a runtime UNKNOWN — the structural check happens once, at the boundary. A rule with a zero-length effective DACL fails the same way, as do truncated fields, lengths exceeding the buffer, and invalid ACL headers. SeTcbPrivilege is checked before any parsing begins.

authd populates the cache — from the registry on a standalone machine, from Active Directory on a domain-joined one. The kernel neither knows nor cares about the source; it is a passive cache. Policies pushed after services are running do not retroactively affect handles already opened.

3.8.8.5 The recovery policy #

When a scoped policy ACE names a SID that is not in the cache — authd failed to push it, the policy was deleted, the machine is disconnected — a hardcoded recovery policy is used instead: GENERIC_ALL to BUILTIN\Administrators, to SYSTEM, and to OWNER RIGHTS.

Those masks are stored as the literal GENERIC_ALL bit rather than pre-mapped object-specific bits, and are expanded through the caller's GenericMapping at evaluation time, so the recovery policy works correctly for every object type.

Because CAAP is an intersection, recovery does not widen access beyond the object's own DACL: it limits missing-policy access to callers who also satisfy the recovery DACL. This is a fail-closed recovery mode with administrator, SYSTEM and owner escape hatches — not a no-effect fallback.

3.8.8.6 Errors #

A rule whose DACL evaluation errors denies everything except rights granted by privileges. Preserving those is the escape hatch: an administrator with SeSecurityPrivilege keeps the ability to read and modify the SACL and remove the offending scoped policy ACE.

The escape hatch is conditional, though, and the ordering is why. PIP runs before CAAP and may already have stripped ACCESS_SYSTEM_SECURITY from the privilege-granted set for a non-dominant caller. The hatch therefore only works for callers who are PIP-dominant, or where the object carries no trust label.

Rule evaluation swallows every error kind, including allocation failure, so an out-of-memory condition inside a rule is reported as "this rule denied all except privileges" rather than as ENOMEM.

A rule whose SACL evaluation errors has its audit contribution skipped, and a diagnostic event is emitted.

3.8.8.7 Staging #

A rule may carry staged DACLs and SACLs alongside its effective ones, and AccessCheck evaluates both in parallel. The staged result affects neither access nor audit; where effective and staged differ, the difference is reported through a staging mismatch flag returned to the caller and a diagnostic event.

A rule with no staged DACL contributes its effective result to both running totals, and a rule with no staged SACL contributes its effective SACL to both.

Auditing is purely observational. No audit rule affects the access decision, and audit ACEs are evaluated after the decision is final.

Three mechanisms operate inside the pipeline, emitting two families of KMES record: access-audit for object-access events from the SACL walk and from token audit-policy forcing, and privilege-use for privilege-use events. A third family, caap-policy-diagnostic, is emitted for the CAAP conditions of §3.8.8 — a SACL evaluation error, or a staged-versus-effective mismatch. The event type strings and payload schemas are in §3.C.

Event delivery happens before any result is written back to the caller, and a failure to deliver fails the call. An audit event cannot be suppressed by handing the syscall a bad output pointer.

3.8.9.1 Access auditing #

SYSTEM_AUDIT ACEs in the SACL define which attempts to log. Each carries a SID, an access mask, and success and failure flags — SUCCESSFUL_ACCESS_ACE_FLAG (0x40) and FAILED_ACCESS_ACE_FLAG (0x80).

An event is emitted when the ACE's SID matches the caller, its mask overlaps the requested access, and its flags match the outcome.

Two details matter. The SID is matched with deny polarity — the broadest identity view, in which deny-only groups are visible — because auditing should capture the widest possible picture rather than the narrowest. And the overlap is tested against the generic-mapped requested mask, not the final granted mask, so a failed request is still auditable for the rights it actually asked for.

Conditional audit ACEs gate the event on an expression, using the same deny-side membership polarity. An expression evaluating to UNKNOWN emits the event: when in doubt, audit.

3.8.9.2 Continuous auditing #

Access auditing fires once, where AccessCheck runs. Continuous auditing covers per-operation monitoring.

SYSTEM_ALARM ACEs configure it. When AccessCheck evaluates an alarm ACE whose SID matches, the ACE's mask is accumulated into a continuous audit mask returned to the caller, which stores it on the open handle and enforces it per operation. Conditional alarm ACEs use the same deny-side polarity as conditional audit ACEs. The alarm branch deliberately performs no overlap test against the requested mask — an alarm ACE contributes its mask on a SID match alone.

On each later operation the enforcement point emits a continuous-audit event when the operation's normalised required-access mask overlaps the stored mask. For FACS handles that is the same mask used by the use-time check (§3.9.4). Where an operation's authorization accepts any one of several rights — append or write data, say — the required mask holds the accepted set and the event records the subset that overlapped.

Events are emitted after the per-operation decision is known, for successful and denied attempts alike. The subject and process recorded are the operation-time effective token and current task, not necessarily the ones that opened the handle. That keeps attribution correct after a handle is passed between processes, while still using the opener-computed mask to decide whether the handle is audited at all.

An enforcement point that cannot construct a required continuous-audit event fails closed. Transport buffering and drop accounting remain KMES's concern (§2.7).

3.8.9.3 Privilege-use auditing #

When a privilege is exercised to grant access the DACL would not have granted independently, a privilege-use event may be emitted. This runs after the complete pipeline — after integrity policy, confinement and central access policy — so it reflects the final result rather than an intermediate one.

Successful privilege use means the privilege's contributed bits survive into the final granted result. The privilege is marked used, and an event is emitted when the token's audit_policy carries PRIVILEGE_USE_SUCCESS (0x04). Failed privilege use means the privilege contributed bits during evaluation that did not survive. The privilege is not marked used, and an event is emitted under PRIVILEGE_USE_FAILURE (0x08). A privilege that contributed nothing to the requested access produces no event either way.

With an object type list, the test is per-node: a privilege counts as successfully used if its bits survive on any node's final mask.

A MAXIMUM_ALLOWED request short-circuits this stage entirely, recording no used bits and emitting no privilege-use events at all.

How counterfactual the accounting really is varies by privilege, as §3.4.1 describes: SeSecurityPrivilege and SeTakeOwnershipPrivilege contribute only where the DACL had not already granted the right, while backup and restore seed their bits unconditionally and so also report use for accesses the DACL alone would have permitted.

3.8.9.4 Per-token audit policy #

A token's audit_policy can force events regardless of SACL content. This runs after the SACL walk and before result computation: if the access succeeded and the policy carries OBJECT_ACCESS_SUCCESS (0x01), a success event is emitted; if it failed and the policy carries OBJECT_ACCESS_FAILURE (0x02), a failure event is.

Success here means every requested bit was granted, or that nothing was requested at all.

These events are additive — they fire even when no SACL ACE matched — and they carry the object_audit_context the caller supplied. The policy is per-token, fixed at creation, and follows impersonation, since it is read from the effective token.

3.8.9.5 Event contents #

An event carries the subject, the calling token's identity — user SID, group SIDs, integrity level, PIP identity; the object, as the caller-provided context; the access, meaning what was requested, what was granted, and whether the request succeeded; the trigger, which audit ACE matched or which privilege was exercised; and the process, its PID, name and executable path.

The pipeline itself produces only the object-and-access half — the matched ACE bytes, the requested and granted masks, the outcome, whether the event was policy-forced, the privilege, and the audit context. The subject and process halves are attached at emission time from the resolved call context, which is also where the effective PIP values used for the verdict are reused for attribution.

The preceding sections describe what each layer of AccessCheck does. This one describes how they compose, and is the definitive statement of the evaluation order.

3.8.10.1 Pipeline overview #

Before the pipeline proper, two things are checked and can fail the call outright. The token's own invariants are validated — a write_restricted token without user_deny_only is rejected as invalid — and, in the orchestrator, a null descriptor is rejected and AccessCheckResultList is required to have been given an object type list. A null descriptor presented by an Identification-level token therefore fails as an invalid parameter rather than as access denied, because the null check runs first.

The pipeline then runs in this order:

0. Impersonation level gate. An impersonation token at Identification level is denied immediately. Anonymous tokens proceed through the full pipeline.
1. Input validation. Reject a descriptor with no owner. A null group SID is valid and has no direct effect on the decision.
2. Generic mapping. Map generic bits in the desired mask to object-specific bits; strip MAXIMUM_ALLOWED.
3. Effective privileges. Clear the backup and restore bits when the corresponding intent flag is absent.
4. Privilege grants. Resolve ACCESS_SYSTEM_SECURITY, backup and restore. Seed decided, granted and privilege_granted.
5. Pre-SACL walk. Extract the mandatory integrity label, the PIP trust label, resource attributes and scoped policy SIDs from the SACL, then enforce MIC and PIP.
6. Virtual group resolution. S-1-3-4 and S-1-5-10 become matchable where the caller is the owner or the object's principal.
7. Tree initialisation. Seed each node from the scalar state.
8. Normal DACL evaluation. Owner implicit rights, then the walk.
9. Post-DACL WRITE_OWNER override. SeTakeOwnershipPrivilege grants WRITE_OWNER if the DACL did not and no mandatory mechanism blocked it.
10. Restricted token pass, with intersection and privilege restoration.
11. Confinement pass, with absolute intersection.
12. CAAP. Evaluate each applicable rule's DACL through the full per-descriptor pipeline and intersect; collect SACLs.
13. Privilege-use auditing.
14. Audit emission, over the object's SACL and any CAAP SACLs.
15. Result computation.

Object type lists are validated at parse time rather than at step 1 — non-empty, one level-0 node first, no level gaps, no duplicate GUIDs — so a malformed list never reaches the pipeline. Step 1 re-checks only emptiness.

Reserved access-mask bits (0x0CE0_0000) are rejected wherever a mask is mapped. That applies to the caller's desired mask and to every ACE mask, so a single ACE carrying a reserved bit aborts the entire check rather than being skipped.

3.8.10.2 EvaluateSecurityDescriptor #

Steps 0–11, called once for the normal evaluation and once per CAAP rule with a synthetic descriptor.

EvaluateSecurityDescriptor(
    sd, token, pip_type, pip_trust, desired, mapping,
    object_tree, self_sid, local_claims, privilege_intent
) -> (decided, granted, privilege_granted,
      max_allowed_mode, mapped_desired, resource_attributes,
      policy_sids) | error

    // Step 0: Impersonation level gate.
    if token.token_type == Impersonation
       and token.impersonation_level == Identification:
        return ERROR_ACCESS_DENIED

    // Step 1: Input validation.
    if sd.owner is null:
        return ERROR_INVALID_SECURITY_DESCR

    // Step 2: Generic mapping.
    desired = MapGenericBits(desired, mapping)
    max_allowed_mode = (desired & MAXIMUM_ALLOWED) != 0
    desired = desired & ~MAXIMUM_ALLOWED

    // Step 3: Effective privileges.
    effective_privileges = token.privileges_enabled
    if not (privilege_intent & BACKUP_INTENT):
        effective_privileges &= ~SeBackupPrivilege
    if not (privilege_intent & RESTORE_INTENT):
        effective_privileges &= ~SeRestorePrivilege

    // Step 4: Privilege-based grants.
    decided = 0; granted = 0; privilege_granted = 0

    // ACCESS_SYSTEM_SECURITY is always decided by privilege.
    decided |= ACCESS_SYSTEM_SECURITY
    if (effective_privileges & SeSecurityPrivilege):
        granted           |= ACCESS_SYSTEM_SECURITY
        privilege_granted |= ACCESS_SYSTEM_SECURITY

    if (effective_privileges & SeBackupPrivilege):
        backup_bits = MapGenericBits(GENERIC_READ, mapping)
        decided |= backup_bits; granted |= backup_bits
        privilege_granted |= backup_bits

    if (effective_privileges & SeRestorePrivilege):
        restore_bits = MapGenericBits(GENERIC_WRITE, mapping)
                     | WRITE_DAC | WRITE_OWNER | DELETE
                     | ACCESS_SYSTEM_SECURITY
        decided |= restore_bits; granted |= restore_bits
        privilege_granted |= restore_bits

    // Restore already includes WRITE_OWNER, so when it is active
    // step 9 has nothing left to do. Step 9 is the fallback for
    // when restore is inactive and the DACL did not grant it.

    // Step 5: Pre-SACL walk. mandatory_decided records bits decided
    // by MIC and PIP, so step 9 cannot override them.
    resource_attributes = {}; policy_sids = []; mandatory_decided = 0
    PreSACLWalk(sd, token, pip_type, pip_trust, mapping,
                &decided, &granted, &privilege_granted,
                &mandatory_decided, &resource_attributes,
                &policy_sids)

    // Steps 6-8: owner implicit rights are granted first, inside
    // EvaluateDACL, and the tree is seeded from the already
    // augmented scalar state. Virtual groups are resolved per
    // lookup rather than by building an enriched token.
    EvaluateDACL(sd, token, mapping, object_tree,
                 SidMatchesToken, desired, max_allowed_mode,
                 resource_attributes, local_claims,
                 skip_owner_implicit=false,
                 &decided, &granted)

    // Step 9: Post-DACL WRITE_OWNER override.
    if (desired & WRITE_OWNER) != 0 or max_allowed_mode:
        if (effective_privileges & SeTakeOwnershipPrivilege):
            if not (mandatory_decided & WRITE_OWNER)
               and not (granted & WRITE_OWNER):
                decided |= WRITE_OWNER
                granted |= WRITE_OWNER
                privilege_granted |= WRITE_OWNER
                for each node with WRITE_OWNER ungranted:
                    node.decided |= WRITE_OWNER
                    node.granted |= WRITE_OWNER

    // Step 10: Restricted token pass.
    if token.restricted_sids or token.restricted_device_groups:
        // Restricted identity view: only restricting SIDs, plus
        // S-1-3-4 if the owner is among them and S-1-5-10 if
        // self_sid is. Restricted device groups swap in.
        // Fresh tree, zeroed state.
        EvaluateDACL(sd, restricted_view, mapping, r_tree,
                     SidInRestrictingSids, desired,
                     max_allowed_mode, resource_attributes,
                     local_claims, skip_owner_implicit=false,
                     &r_decided, &r_granted)
        if token.write_restricted:
            write_bits = MapGenericBits(GENERIC_WRITE, mapping)
            granted = (granted & ~write_bits)
                    | (granted & r_granted & write_bits)
        else:
            granted = granted & r_granted
        granted |= privilege_granted        // privileges bypass
        // Same intersection and restoration per node.

    // Step 11: Confinement pass.
    if token.confinement_sid and not token.confinement_exempt:
        // Confinement SID set: confinement_sid plus every
        // capability, presence-based. S-1-3-4 and S-1-5-10 are
        // injected only if the owner or self_sid is in that set.
        EvaluateDACL(sd, token, mapping, c_tree,
                     SidInConfinementSids, desired,
                     max_allowed_mode, resource_attributes,
                     local_claims, skip_owner_implicit=true,
                     &c_decided, &c_granted)
        granted = granted & c_granted       // no privilege bypass
        // Same absolute intersection per node.

    return (decided, granted & root-consistent state,
            privilege_granted narrowed to what survived,
            max_allowed_mode, desired, resource_attributes,
            policy_sids)

The returned privilege_granted is narrowed by what actually survived the pass — it is intersected with the root's granted mask on return, and the orchestrator narrows it again against the CAAP result. A privilege-granted bit that the write-restricted merge or the confinement intersection removed is therefore no longer part of it, which matters in two places: the CAAP error escape hatch (§3.8.8) has fewer bits to preserve, and the audit provenance masks reflect the narrowed set.

3.8.10.3 AccessCheckCore #

The orchestrator runs steps 12 through 15.

Step 12, CAAP. For each scoped policy SID, look the policy up — falling back to the recovery policy when it is absent — and for each rule whose applies_to is TRUE or absent, evaluate the rule's synthetic descriptor through EvaluateSecurityDescriptor and intersect. A rule that errors denies everything except the (already narrowed) privilege-granted bits. Staged DACLs are evaluated in parallel into a separate running total; a rule with no staged DACL contributes its effective result to both.

After all policies, the staged and effective totals are compared and any difference sets the staging mismatch flag. In result-list mode a per-node delta sets it too — and so does a scalar delta, since the comparison is not mode-branched.

Step 13, privilege-use auditing. For each of the five provenance masks — security, backup, restore, take-ownership and relabel:

success_bits = provenance & mapped_desired & granted
failure_bits = provenance & mapped_desired & ~granted

Nonzero success_bits means the privilege was load-bearing: mark it used on the token, and emit a success event under PRIVILEGE_USE_SUCCESS. Otherwise nonzero failure_bits means it was exercised but did not survive: do not mark it used, and emit a failure event under PRIVILEGE_USE_FAILURE. Both zero means no event. In result-list mode the comparison folds across nodes — success if the bits survive on any node, failure only if they survive on none.

The whole step is skipped in MAXIMUM_ALLOWED mode, so such a request marks nothing used and emits nothing.

Note that relabel_granted is tracked as provenance but is deliberately excluded from privilege_granted itself, so a relabel-loosened WRITE_OWNER is neither restored after the restricted merge nor preserved by the CAAP error hatch.

Step 14, audit emission. Walk the object's SACL, then each CAAP effective SACL, accumulating audit events and ORing alarm masks into the continuous audit mask. This is read-only with respect to granted.

The staged comparison then walks the object's SACL again followed by the staged SACLs. That second walk is driven by the staged granted total rather than the effective one, so the success and failure classification of staged audit events reflects the staged access result — which is what makes the flag sensitive to descriptors whose staged and effective grants differ.

Step 14b, forced auditing. With success = (granted & mapped_desired) == mapped_desired or mapped_desired == 0, the token's audit_policy forces a success or failure event additively, regardless of what the SACL matched.

Step 15 returns the accumulated state.

3.8.10.4 The wrappers #

AccessCheck takes the root node's granted mask when a tree is present, then computes allowed as mapped_desired == 0 or every requested bit granted. The root's mask equals the intersection across all nodes by construction rather than by computation: upward denial propagation (§3.8.5) forces every descendant's denial into all of its ancestors, so the root can never grant what a descendant denies.

AccessCheckResultList requires a tree and returns a per-node granted mask and status, each node judged against mapped_desired independently.

Neither wrapper filters the returned granted to the requested mask. Privilege seeding at step 4 ORs bits in regardless of what was asked for, so a caller that requested only READ_CONTROL while holding backup can see read bits it never requested. The file enforcement path does filter its result; the generic query path does not.

3.8.10.5 Helpers #

SidMatchesToken(sid, token, for_allow) -> bool
    if sid == token.user_sid:
        if for_allow and token.user_deny_only:
            return false
        return true
    for group in token.groups:
        if not group.enabled and not group.deny_only:
            continue
        if for_allow and group.deny_only:
            continue
        if sid == group.sid:
            return true
    return false

MapGenericBits(mask, mapping) -> ACCESS_MASK
    if mask & RESERVED_BITS: reject
    mapped = mask & ~(GENERIC_READ | GENERIC_WRITE
                    | GENERIC_EXECUTE | GENERIC_ALL)
    if mask & GENERIC_READ:    mapped |= mapping.read
    if mask & GENERIC_WRITE:   mapped |= mapping.write
    if mask & GENERIC_EXECUTE: mapped |= mapping.execute
    if mask & GENERIC_ALL:     mapped |= mapping.all
    return mapped

All four generic bits are cleared before any is expanded, so a mask naming several generics maps every one of them.

Virtual group resolution. There is no enrichment step producing a modified token. S-1-3-4 and S-1-5-10 are resolved at each lookup instead, in the DACL walk, the SACL walk and conditional membership alike. S-1-5-10 resolves through the ordinary polarity rules against self_sid, and S-1-3-4 through the ordinary polarity rules against the object's owner SID. Both are computed once per walk — the owner is fixed while the polarity is per ACE — so each carries its allow and deny answers together.

EvaluateSACL walks in a fixed order per ACE: SID match with deny polarity, then object-type scoping against the tree, then the condition, then the mask overlap against mapped_desired. Audit ACEs need all four; alarm ACEs deliberately skip the overlap test and contribute their mask on a SID match alone. Inherit-only ACEs are skipped throughout.

synthetic_sd builds a CAAP rule's descriptor from the original's owner and optional group with the rule's DACL substituted, and the SACL copied with every scoped policy ACE stripped — which is what prevents recursion. The MIC and PIP labels are preserved, so a rule is evaluated under the same mandatory constraints as the object. The control bits and the stripped SACL's revision are recomputed rather than copied.

3.8.10.6 Provenance masks #

Each records which bits that privilege contributed, and step 13 compares each against the requested mask and the final result.

FACS, the File Access Control Shim, is the file-specific enforcement surface of KACS. It replaces Linux DAC — UID, GID and mode-bit checks — with security-descriptor evaluation on files.

Enforcement follows the handle pattern. AccessCheck runs once at open time, the granted mask is cached on the file description, and later operations test the cached mask:

(fd.granted & required) == required ? allow : deny

The mask is set once and never modified, and it is immutable for the descriptor's whole lifetime regardless of any later descriptor change. A file's DACL can be rewritten while a process holds it open, and that process keeps the rights it was granted. A few operations use a live AccessCheck instead; §3.9.4 lists them.

A second immutable mask is stamped alongside it: the continuous audit mask (§3.8.9), which every use-time operation consults to decide whether to emit a per-operation audit event. It travels with the granted mask through every path described below.

3.9.1.1 Mount policy #

Every mounted filesystem exposes exactly one FACS mount-policy class, scoped to the kernel superblock object rather than to a pathname or a bind mount — several paths or bind mounts over one superblock all observe the same class.

unmanaged puts the mount outside the handle model entirely: no granted mask is stamped on its file descriptions. facs_deny_missing is FACS-managed and denies access where a descriptor is missing. facs_synthesize_ephemeral synthesises missing descriptors and caches them in memory only. facs_synthesize_persistent synthesises them and writes them back immediately. The three facs_* classes are the only managed ones.

The default classifier is conservative. Hardcoded pseudo-filesystems — /proc, /sys, nullfs — are unmanaged. Filesystems that cannot reliably store the canonical descriptor xattr are facs_synthesize_ephemeral: FAT, exFAT, NFS client mounts, ISO9660, and cgroup2. StrataFS is fixed at facs_deny_missing. Everything else — tmpfs, squashfs, ext4, btrfs — defaults to facs_deny_missing unless a trusted policy agent adopts it.

Userspace cannot set a superblock to unmanaged through the public ABI; the class is reserved for the kernel classifier and the hardcoded rules. Attempting to set a policy on a magic-derived unmanaged superblock fails with EOPNOTSUPP, and so does attempting to change StrataFS's.

3.9.1.2 Scope #

The sole-authority claim covers local FACS-managed filesystems. It does not cover O_PATH descriptors, which are not managed; NFS client mounts, which are ephemeral-synthesising and retain dual authority with the server; /proc, which is unmanaged and PIP-protected; or /sys, which is unmanaged and carries a hardcoded rule instead — writes there require Administrators or SYSTEM, enforced against a built-in descriptor. Descriptors for processes obtained through pidfd bypass FACS at open as well.

3.9.1.3 Handle acquisition #

A descriptor carries its granted mask through every acquisition path, and transfer is an intentional capability-delegation mechanism. dup/dup3 and fork produce the same open file description and therefore the same rights; descriptors without FD_CLOEXEC survive exec unchanged; SCM_RIGHTS transfers the descriptor as a capability token, with possession as authorization and no re-check of the receiver's identity; and pidfd_getfd() is gated by an AccessCheck for PROCESS_DUP_HANDLE against the target process, after which the caller receives the descriptor with its full mask.

The security boundary is at open time. Every subsequent transfer carries the mask unchanged.

This means mandatory subject policy — MIC and PIP — is evaluated once, at open, against the opener. A high-integrity process that opens a file and passes the descriptor to a low-integrity one has effectively delegated its access. That is the handle model: authority is on the handle, not on the holder.

3.9.1.4 Stacked backing files #

When a stacking filesystem creates a kernel-private backing file for a managed user-visible file, the outer file's granted and continuous audit masks are captured into the backing-file blob, and the backing file's ordinary blob receives that exact snapshot when the provider is opened. No new AccessCheck runs against the task executing the stacking filesystem.

The inheritance is deliberately narrow. It is admitted only through the kernel's typed backing-file allocation path, only from a managed non-O_PATH outer file, and it retains no reference to that outer file — only the values. It is not a general snapshot-cloning mechanism.

An active StrataFS copy-up context takes precedence: a backing open that does not match its exact object and phase does not fall back to inherited authority. When an exactly-bound copy-up backing file is adopted by the outer descriptor, the outer snapshot is installed into both blobs as a single transition, after which the backing file behaves like any other stacked open.

The user-visible operation is checked and continuously audited once, against the outer handle. Immediate provider re-entry through security_file_permission or security_mmap_file neither repeats the caller authorization nor emits a second caller audit event. The backing file keeps the snapshot for later descriptor-local enforcement, including mprotect() after a stacked mmap, and the mmap_backing_file handoff verifies that the outer, backing and captured snapshots still agree before the provider mapping is installed.

This suppresses duplicate KACS authorization only. It bypasses nothing else — not another LSM, not filesystem errors, not read-only mounts, immutable state, quota, space, I/O, or format validation.

kacs_open takes an explicit desired access mask. The caller names every right it will need — FILE_READ_DATA, FILE_WRITE_DATA, WRITE_DAC, READ_CONTROL, any combination — and AccessCheck evaluates the whole requested mask at open. If every requested right is granted the descriptor's mask is set to the requested mask; if any is denied, the open fails. This is the strict mode, in contrast to the legacy path's subset behaviour (§3.9.3).

MAXIMUM_ALLOWED may be combined with at least one concrete data right or FILE_EXECUTE. The concrete bits define the Linux f_mode of the returned descriptor and have to be granted; MAXIMUM_ALLOWED then makes the cached mask the full computed maximum rather than the requested set. Alone it is invalid, because it defines no file mode, and fails with EINVAL.

3.9.2.1 The required data right #

Every native open names at least one data right — FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA — or FILE_EXECUTE, so that every descriptor has a valid mode. FILE_READ_DATA maps to FMODE_READ; either write right maps to FMODE_WRITE; and FILE_EXECUTE alone maps to FMODE_EXEC, which enables execveat(fd, "", ..., AT_EMPTY_PATH) — an execute-only handle that can neither read nor write the file's contents.

3.9.2.2 Directories #

Directory rights share bit positions with file data rights: FILE_LIST_DIRECTORY is FILE_READ_DATA (0x0001), FILE_ADD_FILE is FILE_WRITE_DATA (0x0002), and FILE_ADD_SUBDIRECTORY is FILE_APPEND_DATA (0x0004). A native directory open with FILE_LIST_DIRECTORY satisfies the data-right requirement and maps to FMODE_READ.

The two write aliases are not cacheable directory handle rights, though. kacs_open rejects a desired mask naming FILE_ADD_FILE, FILE_ADD_SUBDIRECTORY or FILE_DELETE_CHILD on a directory with EOPNOTSUPP. Those are parent-directory authorization rights for namespace operations, evaluated live at the operation, not rights a handle carries.

3.9.2.3 Special nodes and symlinks #

Existing FIFOs, pathname socket nodes, and character and block device nodes on managed mounts are ordinary filesystem file objects for authorization: the file object type, the file right mapping, and the file GenericMapping for metadata, standard and generic rights.

FILE_EXECUTE is not a valid data substitute for them — a kacs_open naming it on such a node fails closed. The Linux object implementation may still impose its own device- or filesystem-specific denial after KACS has authorized the file object.

Symlink objects are file objects for kacs_get_sd, kacs_set_sd and readlink, but they are not opened as terminal objects by kacs_open. Following is the default resolution behaviour, and AT_SYMLINK_NOFOLLOW fails with ELOOP. This differs deliberately from kacs_get_sd and kacs_set_sd, where the same flag resolves the symlink object itself.

Operations needing neither data nor execute access — changing a DACL without reading contents — use path-based interfaces or O_PATH descriptors as object anchors, which the get and set security calls accept through AT_EMPTY_PATH.

3.9.2.4 Create dispositions #

FILE_SUPERSEDE deletes the existing name and creates a new file under it, requiring DELETE on the existing file — or FILE_DELETE_CHILD on the parent — together with FILE_ADD_FILE on the parent. The new file gets a new inode and a new descriptor, inherited or caller-supplied. The superseded pathname is broken away from the old hardlink set and names the new inode; other pre-existing hardlinks continue to name the old inode, and already-open descriptors still reference it.

FILE_OVERWRITE truncates in place — same inode, same descriptor, hardlinks preserved — and requires FILE_WRITE_DATA.

On an unmanaged mount, FILE_OPEN and FILE_OPEN_IF succeed and return an unmanaged descriptor with no stamped mask rather than failing; the creating dispositions fail with EOPNOTSUPP.

3.9.2.4.1 The DELETE fallback #

Both FILE_SUPERSEDE and delete-on-close reference "DELETE on the file, or FILE_DELETE_CHILD on the parent". That is a two-descriptor check inside the open path: AccessCheck runs first against the target file for DELETE, and if that is not granted it runs again against the parent directory for FILE_DELETE_CHILD. If neither grants, the open fails. The same duality governs link operations.

3.9.2.5 Create options #

All other bits are reserved and have to be zero; a nonzero reserved bit fails with EINVAL.

Delete-on-close is deliberately no-share. kacs_open_how carries no share-mode field, so the Windows FILE_SHARE_DELETE compatibility matrix is not representable in the frozen ABI, and the kernel contract is bounded instead. The obligation attaches to one ordinary file description lineage rather than to Linux inode last-reference semantics, so dup(), fork() and SCM_RIGHTS all preserve it because they preserve the description. Once a lineage exists for a file object, later opens of that object fail closed rather than emulating share-mode compatibility. The unlink happens at final close of that lineage — not at open, and not at generic inode last-reference drop — and if the pathname is already gone by then the close path treats it as a no-op rather than a new error. Regular files only: directory delete-on-close fails closed.

3.9.2.6 Caller-supplied descriptors #

When a disposition results in a new file the caller may supply a descriptor. A null pointer with zero length means the new file's descriptor is inherited from the parent directory through the inheritance algorithm.

Supplying one on a branch that opens an existing object is invalid input rather than something silently ignored. FILE_OPEN_IF resolving to an existing object fails with EINVAL, and so do FILE_OVERWRITE and the existing-object branch of FILE_OVERWRITE_IF, since those retain the existing inode and its descriptor. FILE_OPEN with a descriptor supplied fails with EOPNOTSUPP.

For a genuine creation the kernel computes the new object's descriptor first, then runs the strict native-open AccessCheck against that descriptor for the requested access. Parent create rights authorize namespace creation; they do not by themselves authorize the returned handle. A failed strict check rolls the creation back — the newly created file or directory is removed — and the syscall fails.

Creator-supplied descriptors are validated at create time. An owner SID has to be the caller's own or a token group marked SE_GROUP_OWNER, unless SeRestorePrivilege is enabled, in which case any owner is allowed. A supplied SACL is treated as a full SACL input rather than a label-only fragment, and therefore requires SeSecurityPrivilege. If that SACL carries an explicit mandatory label ACE, the label also has to satisfy the ordinary label-write constraint: at or below the caller's integrity level, unless SeRelabelPrivilege is held.

3.9.2.7 Modes and status #

kacs_open_how carries no POSIX mode field, so the raw Linux inode mode for native creation is fixed: 0600 for regular files, 0700 for directories. These are compatibility metadata only — and if Linux DAC ever denies an operation KACS would have authorized, the operation fails closed.

Native creation does not create FIFOs, socket nodes, device nodes or symlinks. Those stay on the Linux namespace APIs — mknod(), mkfifo(), Unix bind() to a path — governed by the namespace hooks. NTFS is excluded from native creation entirely.

The syscall reports what happened: created, opened, overwritten, or superseded. KACS_STATUS_SUPERSEDED is used only when an existing object was actually replaced — a FILE_SUPERSEDE that finds no target and simply creates one reports KACS_STATUS_CREATED.

Linux's open() and openat() cannot express rights like WRITE_DAC or READ_CONTROL. FACS maps the open flags to a core set of required rights plus a compat set of POSIX-expected ones, and evaluates both in a single AccessCheck.

3.9.3.1 Core rights #

The core set is the minimum for a usable descriptor, and the open fails if any of it is denied.

For regular files, device nodes, FIFOs and pathname sockets:

For directories, O_RDONLY gives FILE_READ_ATTRIBUTES | FILE_TRAVERSE. Directory core deliberately excludes FILE_LIST_DIRECTORY, so a directory opened O_RDONLY can be used for fchdir() and fstat() without listing permission; listing is a compat right.

Two modifiers apply in order. O_APPEND replaces FILE_WRITE_DATA with FILE_APPEND_DATA, and O_TRUNC adds FILE_WRITE_DATA. Given both, the replacement happens first and the re-addition second, so core ends up with FILE_APPEND_DATA and FILE_WRITE_DATA together.

FILE_READ_ATTRIBUTES is always core: a descriptor granting data access but denying attribute reads is not openable through the legacy APIs at all.

3.9.3.2 Compat rights #

Requested alongside core and silently omitted where denied: FILE_READ_EA for fgetxattr(); READ_CONTROL for reading the descriptor; FILE_WRITE_ATTRIBUTES for futimens(); FILE_WRITE_EA for fsetxattr(); FILE_WRITE_DATA on O_APPEND opens so ftruncate() works where the descriptor allows it; WRITE_DAC, because POSIX permits fchmod() on any descriptor; WRITE_OWNER, for fchown() on the same grounds; SYNCHRONIZE; FILE_LIST_DIRECTORY, enabling readdir() on directory descriptors; and FILE_EXECUTE, enabling fexecve() on regular files.

3.9.3.3 The flow #

The full requested mask is core plus compat. AccessCheck returns the subset the descriptor allows. If every core right is present the actual granted mask — which may include all, some or none of compat — is stamped on the descriptor; otherwise the open fails with EACCES.

Both open paths run the same pipeline with different success criteria. Native open is strict: everything requested has to be granted. Legacy open is subset: only core has to be fully present.

3.9.3.4 O_PATH #

O_PATH descriptors are not FACS-managed. The open hook does fire for them, but returns immediately without evaluating anything, so they carry no granted mask and are left unmanaged. They serve as namespace anchors for the *at() syscalls.

fstat() and fstatfs() on them are allowed unconditionally. fchdir() runs a live FILE_TRAVERSE check at use time. fchmod(), fchown(), fgetxattr(), fsetxattr(), ioctl() and mmap() are denied with EBADF — though futimens() currently has no such guard. execveat(fd, "", ..., AT_EMPTY_PATH) has exec permission enforced by a live AccessCheck in the bprm hook, and kacs_get_sd and kacs_set_sd with AT_EMPTY_PATH likewise run live, which gives race-free object identity without snapshot authorization.

That fstat() is unconditional means FILE_READ_ATTRIBUTES is not authoritative for attribute confidentiality. In practice size, timestamps and inode number are rarely confidential. The descriptor itself is protected: kacs_get_sd on an O_PATH handle performs a live check.

Every operation on an open descriptor is a mask check against the granted mask, with one exception: execveat(AT_EMPTY_PATH) uses a live AccessCheck.

3.9.4.1 Data operations #

A fallocate mode outside the supported set fails closed, and PUNCH_HOLE additionally requires KEEP_SIZE.

3.9.4.2 Metadata operations #

Reads and writes of the canonical descriptor xattr are denied unconditionally through the xattr hooks — security.peios.sd, or system.ntfs_security on NTFS. All descriptor access goes through kacs_get_sd and kacs_set_sd. POSIX ACL xattr writes are denied unconditionally too, with EOPNOTSUPP rather than EACCES so that probe-then-tolerate callers behave sensibly.

3.9.4.3 Directory traversal #

Path resolution checks FILE_TRAVERSE on managed directory components. A token holding SeChangeNotifyPrivilege bypasses the intermediate checks, including on directories whose descriptor is missing.

Explicit changes of the current or root directory are not intermediate resolution: chdir() and chroot() take a live FILE_TRAVERSE check on the final directory, and the privilege bypass does not apply (§3.4.2). An ordinary fchdir() checks the descriptor's cached mask; an O_PATH fchdir() runs live.

3.9.4.4 Append-only enforcement #

A handle carrying FILE_APPEND_DATA but not FILE_WRITE_DATA allows only true append-intent writes. Append intent means the effective write position is forced to end-of-file by O_APPEND or per-I/O RWF_APPEND, and is not negated by RWF_NOAPPEND on the same operation. Requesting both RWF_APPEND and RWF_NOAPPEND together fails with EACCES.

Denied on such a handle: positioned writes without effective append intent — pwrite64, pwritev, pwritev2 with an explicit offset, io_uring writes with an explicit offset, and AIO writes with an offset; any write using RWF_NOAPPEND, since it can negate append semantics inherited from O_APPEND; shared writable mmap and mprotect upgrades to PROT_WRITE; and the fallocate mutation modes.

3.9.4.5 fcntl #

For F_SETFL, KACS evaluates the mutable status flags Linux accepts — O_APPEND, O_NONBLOCK/O_NDELAY, O_DIRECT, O_NOATIME. Clearing O_APPEND is denied on a handle with FILE_APPEND_DATA but not FILE_WRITE_DATA; setting it is always allowed, being a privilege reduction. Adding O_NOATIME requires FILE_WRITE_ATTRIBUTES and clearing it is always allowed. Changing only O_NONBLOCK, O_NDELAY or O_DIRECT needs no KACS right, though ordinary Linux validation still applies.

These commands are descriptor-local and require no KACS right, and none of them widens the cached mask: F_CREATED_QUERY; F_DUPFD, F_DUPFD_CLOEXEC and F_DUPFD_QUERY, which preserve the same file description and mask; F_GETFD and F_SETFD; F_GETFL; and the async-notification set F_GETOWN, F_GETOWN_EX, F_GETOWNER_UIDS, F_GETSIG, F_SETOWN, F_SETOWN_EX and F_SETSIG, where Linux pid and signal validation still applies.

These are object-state queries or mutations, checked against the cached mask before Linux-specific validation:

Lock, lease and delegation commands — F_SETLK, F_SETLKW, F_SETLK64, F_SETLKW64, F_OFD_SETLK, F_OFD_SETLKW, F_SETLEASE, F_SETDELEG — pass through the fcntl hook so that the later file-lock hook can enforce them against normalised F_RDLCK, F_WRLCK or F_UNLCK values. An unknown lock type fails closed there.

For F_NOTIFY, removing a watch — a zero event mask, ignoring DN_MULTISHOT — requires nothing. Installing one with any known DN_* event requires FILE_LIST_DIRECTORY. Unknown DN_* bits on a managed descriptor fail closed.

Unmanaged descriptors sit outside the handle check entirely, and an unknown fcntl command on a managed one fails closed.

3.9.4.6 ioctl #

Known ioctls are classified by required right; an unclassified one is allowed if the descriptor carries at least one data right. The 32-bit compat aliases take the same right as their native command, including FS_IOC32_GETFLAGS, FS_IOC32_SETFLAGS, FS_IOC32_GETVERSION, FS_IOC32_SETVERSION and the compat preallocation commands.

Descriptor-local, requiring nothing: FIOCLEX and FIONCLEX, which change close-on-exec state; FIONBIO, which changes nonblocking state; and FIOASYNC, which changes async notification state with Linux and fops validation still applying.

Common VFS:

FIFREEZE, FITHAW and FITRIM mutate filesystem operational state, and Linux's own CAP_SYS_ADMIN checks still apply on top.

File and object:

On directories, FS_IOC_GETFLAGS and FS_IOC_SETFLAGS take the same rights as on files.

Anything unclassified is allowed on any data right. For device nodes, pipes and sockets, device-specific ioctl semantics are outside FACS scope: the node's descriptor is the authorization boundary, and Linux's device-specific validation may still deny.

A pinned inode (§3.6) narrows all of this. Every content-, range- or allocation-mutating ioctl is rejected on one, and so is every ioctl the classifier does not recognise — unknown ioctls fail closed there rather than falling back to the data-right rule.

3.9.4.7 Execution #

Execution is nominally a two-layer check. The mode execute bit is the prerequisite meaning "this file is a program", set by package managers and chmod +x, applying to execve and execveat but not to mmap(PROT_EXEC). The descriptor's FILE_EXECUTE is the access control, gating both.

KACS enforces only the second. Nothing in the kernel module tests the execute mode bit; the prerequisite survives because Linux's own generic_permission() refuses MAY_EXEC on a file with no execute bit set, by way of capable_wrt_inode_uidgid(CAP_DAC_OVERRIDE). The +x requirement is therefore a Linux DAC property that KACS inherits rather than a FACS rule, and it is one of the few decisions where mode bits still matter (§3.10.2).

For descriptor-based exec — execveat with AT_EMPTY_PATH, including on O_PATH handles — a live AccessCheck for FILE_EXECUTE runs against the re-opened file rather than the cached mask being consulted.

3.9.5.1 Xattr protection #

FACS intercepts every raw xattr operation on the canonical descriptor xattr — security.peios.sd, or system.ntfs_security on NTFS — and denies all three directions.

Writes are denied: all modification goes through the set-security interface. Removal is denied: a descriptor is never detached from a file. And reads are denied, which is the least obvious of the three and the most important. The raw xattr holds the entire descriptor including the SACL, so allowing a read under READ_CONTROL alone would leak SACL content that properly requires ACCESS_SYSTEM_SECURITY. All reads go through kacs_get_sd, which distinguishes the two.

3.9.5.2 Caching #

A validated, parsed descriptor object is cached in the inode's LSM blob, holding immutable self-relative bytes together with a prevalidated component layout — enough for AccessCheck readers never to reparse untrusted storage bytes.

Readers on the AccessCheck path use the RCU-published pointer. Once a current entry exists, a reader does not take the inode mutex merely to run AccessCheck. It either completes the evaluation inside an RCU read-side critical section, or pins the object with a refcount while still under RCU and drops the RCU lock before doing anything that can allocate, sleep or emit an audit event. A pin is acquired with a non-zero refcount check and dropped afterwards.

Writers allocate a new object, swap the pointer atomically, and free the old one after a grace period and after reader pins have drained. No partial read is possible.

Population is lazy, on first access. The xattr is read through an internal kernel path that bypasses the read-denial hook, and the parsed result is installed by compare-and-swap; a thread that loses the race frees its own copy.

Eviction frees the cached descriptor when the inode is evicted, through an RCU-safe callback with the same pin draining, so in-flight permission checks complete before the object goes away.

Invalidation happens on write, but not atomically with it. The set-security path deliberately releases the inode security lock across the xattr write and re-acquires it afterwards to publish the new parsed object, because holding it across the write would invert the i_rwsem ordering the access path requires. Two concurrent set-security calls on one inode are therefore last-writer-wins rather than serialised end to end, and there is a window in which the xattr and the cache disagree. Readers are never blocked, and no reader sees a partially written object — the exposure is which of two racing writes lands, not a torn state.

3.9.5.3 Mount policy classes #

The superblock policy object carries the class (§3.9.1) and, for synthesise-class mounts, an optional mount-level default template.

The default classifier maps from the superblock's filesystem magic. PROC_SUPER_MAGIC and SYSFS_MAGIC are unmanaged: these expose kernel state through inode-shaped handles with no on-disk identity and no descriptor to consult. NULL_FS_MAGIC is unmanaged too — nullfs is the immutable, permanently empty filesystem the kernel mounts as the mount-namespace root, with the mutable rootfs mounted on top of it. It declares no xattr support at all, so it can never carry a descriptor, and its single root inode is immutable and childless: nothing to stamp and nothing to protect.

STRATAFS_SUPER_MAGIC is fixed at facs_deny_missing for the superblock's lifetime, because StrataFS delegates every check to current provider objects and must never synthesise a descriptor for its merged namespace. An attempt to change it fails with EOPNOTSUPP.

RAMFS_MAGIC, NFS_SUPER_MAGIC, MSDOS_SUPER_MAGIC, EXFAT_SUPER_MAGIC, ISOFS_SUPER_MAGIC and CGROUP2_SUPER_MAGIC are facs_synthesize_ephemeral — either no persistent backing at all, or storage with no native descriptor slot.

Everything else, including TMPFS_MAGIC, SQUASHFS_MAGIC, EXT4_SUPER_MAGIC and BTRFS_SUPER_MAGIC, defaults to facs_deny_missing. These can all carry the descriptor xattr natively and are expected to on every inode that participates in access checks.

TMPFS_MAGIC covers both userspace tmpfs mounts and the kernel-mounted instances established before any userspace runs. The latter are not exempt from the default; they are handled by seeding.

3.9.5.4 Kernel-internal mounts #

Two filesystems are mounted by the kernel before any userspace process exists and before anything can call kacs_set_mount_policy or kacs_set_sd: the mutable root filesystem mounted by init_mount_tree, a tmpfs mounted on top of the immutable nullfs namespace root and made / by set_fs_root; and the devtmpfs instance mounted by devtmpfs_init and populated by the kdevtmpfs thread.

Both are TMPFS_MAGIC and therefore facs_deny_missing, and their root inodes are kernel-created, never passing through a userspace-supplied artifact, so they carry no descriptor at the moment they become reachable. To make the class viable the kernel seeds one.

The rootfs root is seeded inside init_mount_tree, immediately after vfs_kern_mount returns and before the mount is published into init_mnt_ns, with the inode's i_rwsem held. The devtmpfs root is seeded inside devtmpfs_init, after vfs_kern_mount and before kdevtmpfs starts, likewise under i_rwsem. The nullfs root is not seeded — it is unmanaged, empty, and incapable of xattr storage.

The seeded descriptor is byte-for-byte identical in both places: owner and group SYSTEM (S-1-5-18), a DACL of one ACCESS_ALLOWED ACE granting GENERIC_ALL to SYSTEM flagged OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE so that inheritance derives a child descriptor for every inode created on the mount afterwards, and no SACL.

The writes go through the kernel-internal xattr path, bypassing both the FACS denial hooks and the LSM setxattr permission hook. They consult no token — at the point either runs there may be no meaningful subject — and the seeded descriptor is the sole authority for the mount until trusted userspace replaces it. They depend on nothing beyond the LSM scaffold that allocates inode and superblock blobs.

These are not exempt from later management: trusted userspace can overwrite the per-inode descriptor or change the superblock's class once it holds the privileges.

3.9.5.5 Boot artifacts #

A filesystem shipped as a boot artifact — a squashfs concatenated into the initrd, a vendor squashfs delivered as a package, a flashed partition image — defaults to facs_deny_missing and the kernel does not seed it. These are already-populated trees the kernel cannot extend at mount time, and in the read-only case cannot extend at all.

The obligation falls on the build pipeline, which emits security.peios.sd on every inode ordinary access checks will reach. mksquashfs, the ext utilities and the standard userland xattr surfaces all preserve security.* natively.

An artifact without descriptors is a packaging defect. FACS treats every missing descriptor on a facs_deny_missing mount as a corruption indicator and denies. The operator path is to rebuild the artifact, or to adopt the superblock under a synthesise class.

3.9.5.6 Administration #

Trusted userspace adopts a mounted filesystem by calling kacs_set_mount_policy on a descriptor naming any object on the target superblock; O_PATH descriptors are valid targets. The change applies to the superblock, not the pathname used to reach it.

The call requires enabled SeTcbPrivilege and marks it used. The public ABI accepts only the three managed classes; unmanaged, unknown values, nonzero reserved flags and malformed arguments all fail closed.

The optional template is accepted only with a synthesise class. It is a complete self-relative descriptor rather than a subset, passes structural validation, and is at most 65535 bytes. A null pointer with zero length clears it. Setting facs_deny_missing clears it and rejects non-empty template input. Pointer and length mismatches and invalid bytes fail before any state changes.

Policy changes are lazy. They do not walk the filesystem and do not stamp anything. The superblock carries a monotonic generation counter, incremented on every successful policy or template replacement. Missing-descriptor, ephemeral-synthetic and not-yet-written-back persistent-synthetic cache entries record the generation they came from and are discarded and repopulated when it changes. Xattr-backed and corrupt-descriptor caches are not made valid by a policy change, and open file descriptions keep their immutable masks.

3.9.5.7 Missing descriptors #

Under facs_deny_missing, no descriptor means deny. Two exceptions keep the repair path open. SeChangeNotifyPrivilege bypasses intermediate traverse checks including on directories with no descriptor, though not explicit chdir(), chroot() or fchdir() use-time checks. And O_PATH opens bypass the open hook entirely, so a file with a missing descriptor can still be acquired as an O_PATH reference — which is exactly the repair route: open(path, O_PATH) then kacs_set_sd with AT_EMPTY_PATH under SeRestorePrivilege.

Under the synthesise classes, a missing descriptor is generated from two sources in order. First, inheritance from the parent: if the parent has one, the inheritance algorithm runs as though a new file were being created. Otherwise the mount-level template, applied where there is no parent descriptor — typically only at the mount root. With no template configured, the fallback grants GENERIC_ALL to SYSTEM and BUILTIN\Administrators and GENERIC_READ | GENERIC_EXECUTE to Everyone, owned by SYSTEM with SYSTEM as group.

Because these files already exist, the accessor is not their creator. Where inheritance needs creator inputs — owner, primary group, default DACL — a synthetic system-policy creator supplies them: the template's owner, group and DACL if one exists, the fallback's otherwise. The accessor's token never affects the synthesised descriptor, and the synthesis path takes no subject token at all.

Inheritance is recursive — a parent whose own descriptor is missing is synthesised first, walking toward the mount root where the template terminates it. The walk is bounded at 32 ancestor levels; a target nested deeper than that below the nearest resolvable ancestor fails closed with EACCES rather than synthesising.

An ephemeral synthesis is cached in the inode blob only and never written back, leaving the original filesystem unmodified. A persistent one is additionally written to the xattr so the medium acquires durable descriptors — but never inline.

3.9.5.8 Deferred write-back #

Synthesis runs holding the FACS inode lock, and writing the xattr takes the inode's i_rwsem. Doing that inline would acquire i_rwsem under the FACS lock, inverting the order the access path requires, and would self-deadlock when synthesis is reached from a metadata operation whose VFS caller already holds i_rwsem. Write-back therefore runs with no FACS or VFS lock held.

Synthesis caches the descriptor immediately and marks the entry pending. The access decision is correct from that cached value the instant synthesis completes — correctness never depends on the xattr reaching disk. The write-back runs later from a task-work callback firing as the triggering syscall returns to userspace, so a persistent descriptor is normally on disk by the time the operation that first observed it missing returns.

A pending entry is generation-tagged exactly like an ephemeral one, so a policy or template change before the write-back discards it and re-synthesises; a stale pre-change descriptor is never pinned to disk.

Write-back is best-effort, and can be because the synthesised descriptor is a deterministic function of the parent or the template — the on-disk xattr is a cache of a recomputable value, not unique state. If it does not happen, because the entry was evicted or the task exited first, the identical descriptor is re-synthesised on next access and retried. A failed or skipped write-back never fails the operation that triggered synthesis. Kernel threads, and a failure to queue the callback, fall back to re-synthesis the same way.

Once written, the next cache miss reads it back as an ordinary xattr-backed descriptor: durable, no longer generation-tagged, and never synthesised again.

An ancestor synthesised only to supply inheritance inputs for a descendant is itself pending, and persists under the same rules when it is next accessed in its own right.

3.9.5.9 Corrupt descriptors #

A descriptor xattr that exists but fails structural validation is corrupt, and the policy is fail-closed: deny all access, do not call AccessCheck, and never treat a truncated DACL as an empty one.

Every encounter emits an audit event, fired exactly once per inode per cache population rather than per access, so a hot corrupt inode does not flood the log.

Recovery is a process holding SeRestorePrivilege calling set-security to overwrite it. Offline repair tools can also rewrite xattrs directly on an unmounted filesystem.

3.9.5.10 NFS client mounts #

NFS is the one managed class where the sole-authority guarantee does not hold. The server enforces its own access control independently: FACS evaluates locally against a synthesised descriptor, and the server may deny I/O that FACS allowed. A locally authorized open() can therefore produce a descriptor whose read() calls fail. This is inherent to network filesystems with server-side enforcement, and nothing suppresses the server's denial.

All descriptor modification flows through one syscall. The caller provides a file descriptor or path, a bitmask naming which components to modify, and a self-relative descriptor blob carrying the new values.

The blob is validated structurally — parseable, well-formed ACEs, valid SIDs, at most 65535 bytes — and then only the indicated components are merged into the existing descriptor. Unindicated components are preserved unchanged.

The input is always one self-relative descriptor subset, never a raw SID or ACL fragment. SACL_SECURITY_INFORMATION and LABEL_SECURITY_INFORMATION cannot be combined in one call, because both target the SACL field with incompatible meanings; the pair fails with EINVAL.

A SACL_SECURITY_INFORMATION write replaces the object's entire SACL. A LABEL_SECURITY_INFORMATION write interprets the input SACL as the label subset only: no SACL component removes the explicit mandatory label and returns the object to the default unlabelled state; a present SACL contains exactly one non-inherit-only SYSTEM_MANDATORY_LABEL_ACE and nothing else; and the object's non-label SACL ACEs are preserved.

After merging, the result still has a non-null owner — the group SID may be null — and a merge that would leave no owner fails.

MIC and PIP apply to these checks. A low-integrity caller cannot modify a high-integrity file's descriptor even where the DACL grants WRITE_OWNER.

3.9.6.1 Ownership #

A new owner may be set only to the caller's own SID, or to a group SID on the token carrying SE_GROUP_OWNER. SeTakeOwnershipPrivilege allows setting ownership to the caller's own SID regardless of what the current descriptor says, and SeRestorePrivilege allows any arbitrary SID.

3.9.6.2 Integrity labels #

Without SeRelabelPrivilege a caller may set a label only at or below its own integrity level; with it, any level.

The constraint applies through both paths — the dedicated label subset, and a label ACE embedded in a full SACL write. A SACL write whose ACL contains a mandatory label ACE raising integrity above the caller's level requires SeRelabelPrivilege exactly as the label path does, even though the SACL component itself is gated only by ACCESS_SYSTEM_SECURITY.

3.9.6.3 The SeRestorePrivilege bypass #

SeRestorePrivilege fires inside the AccessCheck pipeline, so it bypasses the check only where kacs_set_sd runs a live one: an O_PATH descriptor with AT_EMPTY_PATH, a pidfd, a token descriptor with AT_EMPTY_PATH, or a path. On those paths it grants every requested right, WRITE_OWNER, WRITE_DAC and ACCESS_SYSTEM_SECURITY included.

Called on an ordinary file descriptor the required rights are checked against the cached mask instead, no AccessCheck runs, and the privilege has no effect at all. A caller needing the bypass has to use the O_PATH route — which is the mechanism behind backup restoration, administrative repair, and the missing-descriptor repair path (§3.9.5).

3.9.6.4 Mandatory resource attributes #

When a caller modifies the SACL, the existing and new SACLs are compared for changes to SYSTEM_RESOURCE_ATTRIBUTE_ACE entries. An existing attribute carrying CLAIM_SECURITY_ATTRIBUTE_MANDATORY (0x0020) cannot be removed, nor its values modified, without SeTcbPrivilege — and an attempt without it fails the entire call rather than silently dropping the change.

3.9.6.5 Write mechanics #

The updated descriptor is serialised to self-relative binary form and written to the xattr through an internal kernel path bypassing the denial hook, and the in-memory cache is updated. An audit event is emitted if the file's SACL carries a matching audit ACE.

The cache update is not atomic with the xattr write; §3.9.5 describes the lock ordering that forces this and the last-writer-wins window it produces.

StrataFS copy-up is the internal realisation of an operation already authorized against a StrataFS handle — not a second caller-requested operation. KACS therefore provides a kernel-internal context so that the mechanics of copy-up introduce no new rights checks against the task that happens to execute them.

The context exempts KACS caller authorization only. It does not replace credentials, borrow an identity, grant a privilege, bypass another LSM, neutralise an underlying filesystem check, make a read-only mount writable, or suppress immutable, append-only, quota, space, I/O or format errors. Every exemption is a return before the authorize call, and every mutation still goes through the ordinary vfs_* path under mnt_want_write().

3.9.7.1 Admission and lifetime #

Only the in-kernel StrataFS implementation can create or enter a context. There is no userspace surface of any kind — no ABI, file descriptor, token, ioctl, syscall or securityfs control — and the copy-up API is declared in a kernel-private header with no exported symbols.

A context is created only after the StrataFS operation requiring copy-up has passed its complete outer authorization. KACS does not verify that: the context creation call performs no check, and the ordering is satisfied by StrataFS calling in the right order. The context is not itself an alternative authorization path.

The exemption covers namespace creation the outer handle authorises without an add-entry right on the create stratum, so the context is reachable only from a create-enabled mount established by a caller holding CAP_SYS_ADMIN in the initial user namespace. That closure rests on an explicit test of the mounter's user namespace at stack establishment — the capability half contributes nothing to it, because the KACS switchboard discards the target namespace and answers from SeTcbPrivilege alone (§3.10.2). The check is made when the immutable stack is established rather than when a copy-up runs, so descriptor delegation cannot reintroduce acting-task authorization. Reconfiguration cannot re-supply the strata list.

A context attaches to at most one task, and a task carries at most one. It is not inherited by fork(), clone() or execve() — exec explicitly clears it. A refcounted context can be transferred to a kernel worker, but the originating task leaves it first. Leaving, task exit, every error path, and completion all remove the attachment and clear any armed phase.

The interface fails closed on nesting, concurrent attachment, a stale phase, or an object mismatch. A mismatched operation is evaluated normally and neither consumes nor broadens the armed exemption.

3.9.7.2 Object and phase binding #

Creation pins the exact provider path, its current inode, a complete validated copy of its effective descriptor, and the provider-visible security.capability value or its absence. Every later positive path is paired with a pinned inode as well — retaining a dentry alone is insufficient, because an unlink followed by recreation can reinstantiate it over a different inode.

One phase is armed at a time:

Path, dentry, inode, parent, object type and operation kind are all compared wherever the hook supplies them — and path comparison includes the mount, so the same dentry reached through a different mount of the same superblock does not match. An inode-only hook can match the pinned inode, but that does not authorize a pathname operation on another dentry, and a phase never acts as a wildcard for other objects of the same filesystem or directory.

The staged binding stays valid only while its dentry names the pinned inode under the pinned staging parent, and that parent still names its own pinned inode. A rename or parent substitution invalidates the populate, protected-metadata and publish exemptions even when the staged dentry and inode are themselves unchanged.

Named creation is bound to the exact final component. Anonymous creation is bound to its parent, expected object type, the attached task, and the single armed create phase — and once created, the anonymous object has to be bound as the staged object before populate, publish or cleanup can use it.

Where the destination is a stacking filesystem creating a real inode below the armed destination dentry, the transition is authenticated at the exact outer dentry, and only the one subsequent real-inode security initialisation of the expected type receives the pinned provider descriptor. The real inode is not the staged binding: the outer inode is separately anchored, through the matching post-create event for an anonymous object or an explicit confirmation of the exact positive outer dentry for a named one. A missing, repeated, mismatched or out-of-order transition fails closed, and an inner post-create event from the real filesystem is rejected as the outer anchor by superblock comparison.

KACS retains the exact path, inode, parent path and parent inode of every named object whose creation it admits. Cleanup can be armed only for one of those or for the exact bound staging object; an unrelated positive dentry fails with ESTALE. The cleanup setup call is not itself authority to choose a deletion victim.

After an atomic rename or link publishes the staged inode, the staging identity can be rebound to the published path, but only while mount, inode, parent dentry and pinned parent inode all still match. The rebind API exists and is not called by StrataFS: the link case is rebound internally by the publish path, and the rename case relies on publish preserving the dentry. That holds because publication always renames within a single parent. A cross-directory publish rename would silently invalidate the staging binding, since the rename-publish entry point does not require the destination parent to equal the staging parent — currently unreachable, but the guard is the caller's discipline rather than the interface's.

Named staging entries carry security.peios.stratafs_staging. Caller-originated writes and removals of it are denied. A write or removal is admitted only on the exact bound staging inode during populate, or on the exact orphan-marker object during authenticated recovery — where the predicate admits a write as well as a removal, being shared between the setxattr and removexattr hooks. Probing the marker for recovery is a kernel-only raw read conveying no caller authority, and orphan deletion is bound to the exact dentry, inode, parent dentry and parent inode supplied when the phase was armed, so an arbitrary name sharing the staging prefix never matches. Recovery processes at most 128 entries per batch.

3.9.7.3 Exempt operations #

For a matching object in a matching phase, the ordinary AccessCheck, cached-grant check, privilege check and caller-access audit decision are omitted at these points:

A security_inode_permission or security_file_permission match also matches the requested mask. Provider access is read-only — write, append and non-directory execute requests never match it. Staging access is limited to the read, write and append masks population needs, plus execute and chdir for directories, and namespace parents to the write and traverse masks the one armed action needs, plus open and chdir. Unknown mask bits fail closed.

The list is exhaustive. The context does not exempt execution, memory mapping, ioctl, locking, arbitrary fcntl, device access, process access, socket access, mount operations, or operations on a descriptor installed into a userspace file table — each verified by the absence of any copy-up branch on those paths. Internal copy-up files are additionally denied statfs, truncate, fsync and fallocate.

A file opened internally under the exemption is marked copy-up-internal in its blob and carries a granted mask of zero. It is usable without a cached caller grant only while the same context is attached and its phase admits that exact file. Use after phase completion, from another task, or after transfer through SCM_RIGHTS fails closed. Each armed phase has a distinct monotonically increasing generation — overflowing it fails closed — and an internal file is sealed to the generation it was opened in, so a later phase of the same kind after a worker transfer cannot reactivate an older file. Final release drops the context reference.

The one exception is the read-only provider-directory cursor used by bounded staging recovery. StrataFS may retain that file while it leaves the context to clean one captured batch, then resume it after re-entering the same context and arming a new source-read phase. Only a directory file already marked internal for that exact context, still naming the pinned provider path and inode, opened for read without write, execute or path-only mode, and inside that attached source-read phase, resumes; it is then resealed to the new generation. Between phases it is unusable and conveys no deletion authority.

3.9.7.4 Backing-file adoption #

Once a regular-file copy is published, one exact copy-up-internal backing file can become the backing file for the outer StrataFS open description. The staging binding is verified, and the backing file's recorded user path is confirmed to be that same outer description; the outer description's immutable granted and continuous-audit snapshot is then copied across and the internal marker removed. This is a transfer of authority already attached to the descriptor, not a new AccessCheck against the task that caused the copy-up, which is what preserves descriptor delegation when that task is not the opener. It is one-shot, and requires the backing file mode.

The ordering is worth noting: StrataFS performs the adoption before publishing the anonymous staged object rather than after, so what is verified is the still-bound staging binding rather than a published one.

3.9.7.5 Deferred deletion #

Delete-on-close is authorized when armed and recorded on the open file description (§3.9.2). At final close there is no re-authorization against the closing task. Instead a synchronous, non-nesting internal deletion scope is armed for that exact outer file, and StrataFS binds it once to the exact provider parent, dentry and inode selected from the descriptor's settled provider. Only the corresponding outer and lower unlink calls match, and the scope is cleared on every return.

The mechanism never turns an ordinary close into deletion authority, never admits a different provider entry, and never permits unlinking an entry that no longer names the descriptor's inode. If the original entry has disappeared or changed identity, the deletion is already complete and no exemption is used.

3.9.7.6 Exact protected-metadata cloning #

KACS owns descriptor cloning rather than StrataFS raw-xattr code. Before a create phase is armed, the provider's complete effective descriptor is resolved and pinned using the ordinary mount-policy and corrupt-descriptor rules (§3.9.5). A missing, corrupt, unresolvable, oversized or unsupported descriptor fails the phase before the destination is created.

For a matching inode security initialisation, an exact byte-for-byte copy of the pinned descriptor is installed instead of inheritance running. The canonical xattr is installed as part of inode creation and the inode's validated parsed cache is seeded from identical bytes before the inode becomes usable. Failure to allocate, validate or install either representation fails creation — there is no window in which a named staging inode carries an inherited or otherwise weaker descriptor.

On a stacking destination the same applies to the real inode created below the outer dentry, with the authenticated outer transition as the only authority to redirect installation there. The pinned bytes are installed and cached during the real inode's creation, before the outer object is confirmed or bound; inheriting the parent's descriptor and repairing it afterwards would not be conforming.

The canonical descriptor is not copied by ordinary xattr enumeration — it is reported as cancelled so a stacking filesystem discards it — and raw canonical getxattr and setxattr stay denied even inside the context, with the hook-side denial evaluated before any phase match. The context does not override the unconditional denial of POSIX ACL mutation either.

Raw setxattr, including through an internal copy-up file, remains unable to install security.capability. Where the provider has one, StrataFS calls the dedicated clone entry point during populate, after any operation that might clear file capabilities. That call accepts only a kernel buffer exactly matching the pinned value, under the same user namespace it was pinned in, for the still-bound staged inode. It re-reads the provider immediately before installing and fails with ESTALE if the value or its presence changed.

The call copies the caller's buffer before comparing, and installs with XATTR_CREATE through the ordinary VFS path, so mount-idmap conversion, xattr validation, filesystem permission and format checks and other LSM checks all still apply. The otherwise-dead CAP_SETFCAP gate is satisfied only synchronously inside that validated call, and the corresponding setxattr re-entry is admitted only after the first hook matches the exact staged inode. The capability answer targets only the pinned caller namespace or the staged inode's filesystem namespace, and the condition is cleared on every return. Nothing is installed when the provider had no attribute, a different one, or an unreadable or invalid one. The exception does not revive exec-time file-capability grants.

There is one asymmetry here: the removal path does not reject security.capability the way the set path does, so an internal copy-up descriptor can remove it from the staged object during populate.

Other eligible provider xattrs follow StrataFS's replication rules while KACS's caller checks on their source and staging objects are exempted as above. An ineligible xattr that cannot be replicated triggers StrataFS's ordinary copy-up failure rule rather than being silently omitted.

3.9.7.7 Auditing #

The outer authorized handle operation remains subject to ordinary audit. No second caller AccessCheck or privilege-use audit is emitted for an exempt internal sub-operation, since that would attribute StrataFS mechanics to a caller decision that never happened — and internal files carry a continuous-audit mask of zero, so they generate no per-operation events either. The CAP_SETFCAP satisfaction path returns before the capability check that would record privilege use.

StrataFS decides when its own copy-up lifecycle and failure events occur; KACS supplies the kernel-only emitter, so KMES stamps each event with the effective token of the task whose operation caused it (§2.2). Two of those emissions are best-effort: an allocation failure, or an operation string that is empty or over 64 bytes, drops the event silently.

Denied mismatches, and operations performed with no active matching context, follow the ordinary authorization and audit paths.

KACS tokens are the sole identity-based authorization mechanism, and Linux applications do not know tokens exist. They call getuid(), getgid() and getgroups(), read /proc/self/status, and assume those numbers determine their access. KACS projects token identity onto standard Linux credentials so unmodified applications work.

When a token is installed on a process, the process's Linux credentials are set to match. The numbers themselves are already on the token: the user SID's projected uid, the primary group SID's projected gid, and a projected supplementary gid per group SID are all computed by authd when the token is minted, and KACS copies them.

KACS never resolves a SID to a number itself. It holds no directory handle and consults nothing at install time — which is what makes projection cheap enough to do on every credential change, and what keeps a name-service outage from being able to change what a running process may do.

How a SID becomes a number is therefore not KACS's rule to state, and this chapter deliberately does not restate it. The authority is the principal source interface's numeric scope (PSPU §2): identifiers are computed — an authority grants a source a band (base, count) and derives base + r from a relative identifier — rather than looked up per principal, and a source's assertion outside its band is refused rather than clamped.

65534 does appear in KACS, but not as a "no attribute was set" fallback: it is ANONYMOUS_PROJECTED_ID, what the projected-id accessors return for the anonymous identity and for an invalid token pointer. It is a sentinel for no identity, not a default for an identity whose number could not be found.

The consequences are mostly convenient ones. No process runs as UID 0 unless it holds the SYSTEM token — enforced, not merely expected: a token creation naming a projected UID of 0 with any user SID other than S-1-5-18 is rejected, and the projection path refuses it again at install time. Home directories work naturally, because getpwuid(getuid()) returns the right answer when the UID is real and consistent with NSS. And different services get different UIDs, which is incidental defence in depth alongside KACS's own enforcement.

3.10.1.1 Projection is one-way #

Token state flows into credential fields and never the reverse. The projected credentials are observational compatibility data; the token is the authority. The setuid family restores the old credential rather than deriving a token from it (§3.10.3).

Projection reflects all groups regardless of enabled state, so adjusting groups never triggers recalculation.

Projected credentials reflect the effective token — the impersonated one during impersonation, the primary one otherwise. When a service thread impersonates a client and creates a file, the file is owned by the client's projected UID, quota is charged to the client, and audit attributes to the client.

The two accessors deliberately disagree during impersonation. current_fsuid() reads the projected UID from the effective credential, so it yields the client's UID; getuid() reads the primary credential's UID, so it yields the service's. During impersonation getuid() returns the service and current_fsuid() returns the client, and that is the intended behaviour rather than an inconsistency.

One caveat applies to a credential carrying no token at all — a blank credential, or one created before KACS initialised. current_fsuid() falls back to cred->fsuid in that case, and the capability switchboard denies before consulting the ALLOW list (§3.10.2), so Linux DAC becomes authoritative for such a task.

3.10.1.2 Precomputed values #

Every token carries precomputed projected UID and GID values, calculated by authd at creation and stored on the token. KACS never resolves a SID-to-UID mapping at runtime; the accessors are pure field reads.

Because SIDs are one namespace while Linux UIDs and GIDs are two, authd allocates from a single unified counter across all principal types rather than a separate one per namespace, so every SID projects to a unique number whichever Linux namespace it lands in. A user and a group can never collide on a number, which is what lets one SID answer both getuid() and getgid() questions without ambiguity.

Linux evaluates DAC — UID, GID and mode-bit checks — before consulting LSM hooks. If DAC denies an operation the hook never fires, and KACS cannot override a DAC denial: LSM hooks are restrictive, able to further deny what DAC would allow but never to grant what DAC has refused.

KACS therefore neutralises DAC so the hooks always fire. Every process receives a set of Linux capabilities that bypass the DAC gates, and those capabilities are mandatory substrate rather than grants.

3.10.2.1 The capability switchboard #

Linux's capabilities fall into three categories, and security_capable() is authoritative for all of them — the raw capability sets on struct cred are compatibility-visible state that answers nothing.

ALLOW capabilities exist to override UID-based permission checks on operations KACS enforces through its own hooks, so DAC never blocks something KACS will evaluate independently:

PRIVILEGE capabilities gate operations no other KACS hook covers, and map to a KACS privilege:

CAP_PERFMON is the one OR-mapped entry: the Linux capability genuinely spans several Peios privilege tiers, and no single privilege covers everything it gates. The check succeeds if the caller holds any of the three, and every one it holds is marked used. Per-operation enforcement then happens at the relevant syscall hook, which checks the specific privilege the specific operation needs (§3.7). OR-mapping stops the capability ceiling manufacturing false denials; it grants nothing the holder does not already have.

CAP_SYS_ADMIN maps to SeTcbPrivilege and is not OR-mapped, which would be the obvious way to let administrators mount and is the wrong one: CAP_SYS_ADMIN gates dozens of unrelated operations, so widening it would hand out far more than mounting.

Mounting is handled outside the capability table instead. may_mount() (fs/namespace.c, patched) calls pkm_kacs_may_manage_volumes(), which accepts SeManageVolumePrivilege or SeTcbPrivilege, before falling back to the ordinary CAP_SYS_ADMIN check. Every other CAP_SYS_ADMIN caller still needs the TCB.

It has to be asked there rather than through the sb_mount LSM hook: may_mount()'s capability check runs before security_sb_mount(), so an LSM is never consulted about a mount the capability check already refused. A hook can narrow that decision; it cannot widen it.

CAP_SYS_BOOT carries an extra condition the table cannot express: a token whose logon session is of a remote origin — Network, NetworkCleartext or NewCredentials — additionally requires SeRemoteShutdownPrivilege.

DENY capabilities are refused unconditionally, whatever privilege the caller holds: CAP_SETPCAP (8) and CAP_SETFCAP (31), because capabilities are dead under KACS, and CAP_MAC_OVERRIDE (32), because KACS is the active LSM and must not be bypassable.

An unmapped or unknown capability is denied by default. The switchboard fails closed.

3.10.2.2 Compatibility state #

Programs may inspect the credential capability sets with capget() or /proc/<pid>/status, and may attempt to mutate the non-ALLOW subset with capset() or prctl(). None of that is authoritative.

capget() and /proc/<pid>/status report the ALLOW substrate as present in the effective, permitted and inheritable sets — reported as CapEff, CapPrm and CapInh, and additionally CapBnd, by the proc interface. Non-ALLOW bits present in the credential state may also be reported, but grant no authority. CapAmb reports raw Linux ambient state; the ALLOW substrate does not depend on ambient capabilities.

The strict invariant is that the ALLOW set is mandatory substrate and has to survive wherever Linux capability mechanics would otherwise drop it out from under KACS. capset() rejects any request clearing an ALLOW capability from the effective, permitted or inheritable sets, and bounding-set drops and ambient manipulation reject anything that would clear or exclude one. The implementation is slightly stricter than that: an ambient raise of an ALLOW capability is refused too, not only a clear.

After that validation, capset() follows ordinary Linux ambient behaviour — ambient bits no longer present in both the requested permitted and inheritable sets may be cleared. Because requests clearing ALLOW bits from permitted or inheritable are denied outright, that intersection can never indirectly clear an existing ALLOW ambient bit.

Direct mutation of non-ALLOW state is therefore compatibility-only. It may change what capget() reports and cannot change the authority answer for any capability-gated operation.

3.10.2.3 Neutralised native paths #

Native commoncap helpers that make raw capability-subset decisions before a KACS hook are neutralised where KACS has an authoritative hook of its own. That covers the subset gates in ptrace access, PTRACE_TRACEME, and task_setnice, task_setscheduler and task_setioprio — each replaced by an unconditional allow, leaving the KACS process-descriptor and PIP hooks to decide. Capability checks that reach security_capable() directly stay under the switchboard.

For raw xattr operations the FACS metadata hooks are authoritative, so the native security-xattr capability prechecks that would run first are skipped. This does not revive Linux file capabilities: installing or replacing non-empty security.capability data stays denied by the dead CAP_SETFCAP policy, with the single exception of the KACS-owned StrataFS clone (§3.9.7), and exec-time file-capability grants remain suppressed. Removing stale metadata goes through the ordinary FILE_WRITE_EA path.

One structural wrinkle: security_capable() reaches the KACS switchboard twice — once through the patched commoncap entry point and once through the KACS capable hook — so a privilege consulted this way is marked used twice. The authorization answer is unaffected; the privilege-use accounting double-counts.

3.10.2.4 The LSM stack #

MAC LSMs — SELinux, AppArmor, SMACK, TOMOYO — and the BPF LSM have to be disabled. They would independently deny operations from their own label and policy systems, undermining KACS's claim to be the sole identity-based authorization mechanism and FACS's to be the sole file access authority. Non-MAC LSMs are permitted: landlock, lockdown, yama and integrity make no identity-based access decisions and stack safely.

The check is made at initialisation and KACS refuses to activate if it fails — but it is a build-configuration test rather than an inspection of the live LSM stack. It tests whether each conflicting LSM is enabled in the kernel config, and never parses CONFIG_LSM or enumerates what is actually registered.

Under KACS a UID has no security properties whatever. It is not consulted in any access decision, appears in no descriptor, and is referenced by no ACE. It is a compatibility value stored in struct cred for the sole purpose of answering getuid().

3.10.3.1 The setuid syscalls #

The setuid family — setuid, setgid, setresuid, setresgid, setgroups — changes Linux credentials.

Without SeAssignPrimaryTokenPrivilege, which is the common case, the call is a silent no-op. It returns success, and every credential field is restored from the old credential: UIDs, GIDs, supplementary groups, capabilities. Neither the credential nor the token changes, and the process's authority before and after is identical.

The silent success preserves consistency between the visible UID and the KACS identity. Changing the UID without changing the token would produce subtle failures — the wrong home directory from getpwuid(), for instance — for no security benefit.

With SeAssignPrimaryTokenPrivilege the design calls for the credential change to trigger a full identity swap, redirected to authd to obtain a token for the target UID's principal, so that both token and credential change together.

That is not what happens. A caller holding the privilege receives EOPNOTSUPP and the call fails. There is no authd redirect anywhere in the LSM. The practical effect is that the privileged path is unavailable rather than dangerous: a TCB component cannot change identity this way, and has to install a token directly instead (§3.2.3).

3.10.3.2 The setuid bit on exec #

The filesystem setuid bit tells the kernel to change the effective UID to the file owner's on exec.

Without the privilege, the Linux-visible UID and GID slots change to the file owner's identity while the token is untouched — a cosmetic escalation in which the process sees geteuid() == 0 while KACS continues to enforce the original token. Concretely uid and suid are set from euid, the GID counterparts mirror that, fsuid and fsgid are carried over unchanged from the old credential, and the token is cloned as-is.

With the privilege, the design calls for the slots and the token to change — genuine escalation. As with the syscall, this is not implemented: an exec that would change UID or GID under a token holding SeAssignPrimaryTokenPrivilege returns EOPNOTSUPP and the exec fails.

The asymmetry between the two mechanisms is intentional in the design. setuid() is de-escalation, so leaving everything unchanged is the safe failure mode. The setuid bit is escalation, and the target binary expects the euid and will check it — sudo verifies geteuid() == 0 — so the euid has to change for the binary to function at all.

3.10.3.3 The current_fsuid patch #

The kernel calls current_fsuid() whenever it needs a UID for a filesystem operation — file creation ownership, quota tracking, keyring lookup, NFS credentials. KACS redefines it, along with current_fsgid() and current_fsuid_fsgid(), to return the projected value from the effective token rather than cred->fsuid.

So files are created owned by the projected UID, quotas track against it, per-user keyrings are keyed by it, and an NFS server sees the real identity rather than UID 0.

3.10.3.4 Compatibility gaps #

The privilege-drop pattern. A daemon that calls setuid(target) and then checks getuid() != target to confirm the drop sees success returned with the UID unchanged. This is intentional — UIDs carry no security meaning here — and software ported to Peios should use KACS-native token operations for privilege management instead.

Direct capability manipulation. Software that manipulates capabilities with capset() and capget(), writes seccomp filters, or inspects its own capability set may behave unexpectedly (§3.10.2).

setfsuid() is a no-op for filesystem purposes, since current_fsuid() ignores cred->fsuid; and cosmetic setuid-bit exec transitions do not flow into the projected values either.

access() and faccessat() use the effective token rather than the real credential — the entire native credential-override machinery those calls normally use is compiled out. The concept of a "real identity" separate from the acting one does not exist in KACS.

SO_PEERCRED returns projected UIDs rather than token information, and because the switchboard allows CAP_SETUID, cosmetic UID forgery in SCM_CREDENTIALS is possible. Both are Linux compatibility metadata, not peer-token authorities: a service needing authoritative identity uses stream or seqpacket peer-token capture, or explicit token descriptor passing (§3.5.3).

Legacy auditd records projected UIDs, so KACS audit through KMES replaces Linux audit for security-relevant logging.

A uid0 utility — running a program with cred->uid forced to 0 for legacy programs that refuse to start otherwise — is described in the design and does not exist in the tree. The kernel-side guarantee it would rely on does hold: current_fsuid() ignores cred->uid entirely, so even with such a utility active, filesystem operations would use the projected UID and files would be owned by the real user.

Every name, value, offset and size in this appendix is generated from pkm/uapi/pkm/ by pkm/tools/gen-kacs-abi.py, with struct layouts measured by compiling a probe against the real headers. Regenerate it whenever the ABI changes; do not edit it by hand.

The names here are the ones a program actually compiles against. Everything about the ABI a compiler cannot measure -- token query payload shapes, the specification spellings that differ from these names, what is documented elsewhere, and the kernel configuration -- is in the notes appendix, §3.D, which this generator does not touch.

3.A.1 Syscall numbers #

Signatures are read from the SYSCALL_DEFINE sites in pkm/kacs/.

uapi/pkm/syscall.h also registers the KMES and LCS numbers, 1090–1102, documented in their own chapters.

3.A.2 Structure layouts #

3.A.2.1 struct kacs_query_args #

Total size 16 bytes.

3.A.2.2 struct kacs_adjust_privs_args #

Total size 24 bytes.

3.A.2.3 struct kacs_priv_entry #

Total size 8 bytes.

3.A.2.4 struct kacs_adjust_groups_args #

Total size 144 bytes.

3.A.2.5 struct kacs_duplicate_args #

Total size 16 bytes.

3.A.2.6 struct kacs_group_entry #

Total size 8 bytes.

3.A.2.7 struct kacs_adjust_default_args #

Total size 16 bytes.

3.A.2.8 struct kacs_restrict_args #

Total size 40 bytes.

3.A.2.9 struct kacs_link_tokens_args #

Total size 16 bytes.

3.A.2.10 struct kacs_get_linked_token_args #

Total size 4 bytes.

3.A.2.11 struct kacs_access_check_args #

Total size 136 bytes.

3.A.2.12 struct kacs_object_type_entry #

Total size 20 bytes.

3.A.2.13 struct kacs_node_result #

Total size 8 bytes.

3.A.2.14 struct kacs_open_how #

Total size 32 bytes.