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.

For kernel build-time and initialization requirements, see Kernel invariants.

The boot chain — kernel-direct tokens, peinit at PID 1, the authd handoff — relies on a handful of kernel-level invariants to be safe. Things like "PKM is in the LSM stack and no incompatible LSM is", "the kernel rejects unsigned kernel modules", "physical memory is restricted to what is appropriate". If these invariants are violated, the security model the rest of these docs describes is no longer guaranteed.

This page covers the invariants, where each is enforced, and the consequences of failure. They are not user-facing settings in the sense of "things you might change" — they are kernel build-time and init-time configurations that the deployment requires. But knowing what they are helps with reasoning about the trust chain and diagnosing the rare case where something doesn't fit the expected model.

1.2.1 The LSM stack invariant #

The Linux Security Module framework lets the kernel host multiple security modules in a defined order. Peios's KACS is implemented as an LSM called PKM (Peios Kernel Module). For PKM to function correctly:

• PKM must be in the LSM stack.
• MAC (Mandatory Access Control) LSMs must not be in the stack — specifically SELinux, AppArmor, SMACK, and TOMOYO.
• The BPF LSM must not be active.

The reasoning: MAC LSMs and PKM both want to make authoritative access decisions, and the LSM framework's composition rules don't merge their decisions cleanly. A system with SELinux and PKM would have both modules trying to decide each access; the result would be that either both must agree (over-restrictive) or one supersedes the other (whichever the LSM order puts first), neither of which is the right semantic. Peios's model is that PKM is the sole authoritative module for the operations it covers.

1.2.1.1 What the kernel verifies #

The kernel verifies at PKM initialisation that no MAC LSM is active and that BPF LSM is not in use. If any are present, PKM refuses to activate. The kernel boots, but the access control is now broken — PKM is supposed to be enforcing, and it isn't. This is detected and reported as an init-time error.

Specifically, PKM refuses to activate if any of selinux, apparmor, smack, tomoyo, or bpf LSMs are present in the active stack.

1.2.1.2 The required stack #

The LSM stack Peios expects is, in order:

landlock, lockdown, integrity, pkm

• commoncap is implicit (Linux always includes it; not listed in CONFIG_LSM explicitly).
• landlock is permitted — it's a process-local sandboxing LSM that processes opt into; it doesn't conflict with PKM.
• lockdown is permitted — it gates specific kernel-debugging interfaces; orthogonal to PKM.
• integrity is permitted — Linux's IMA/EVM mechanisms can run alongside PKM for the use cases they cover.
• pkm is the Peios module.

yama is not built. Its ptrace_scope decides attach ahead of PKM, and its escape hatch is CAP_SYS_PTRACE, which PKM maps to SeDebugPrivilege — so with it present, a process descriptor that grants debugging never gets a say. PKM's own ptrace gating is the whole authority.

Distributors building a Peios kernel must include this stack. Building a kernel with SELinux enabled and active would produce a system where PKM cannot activate — boot would fail with a clear error.

1.2.2 Module signing #

CONFIG_MODULE_SIG_FORCE=y is required. This flag tells the kernel to refuse to load any kernel module that is not signed by a key the kernel recognises.

The reasoning: a kernel module runs with full kernel privileges. An attacker who can load arbitrary kernel modules bypasses every layer of PIP and KACS — they can read memory directly, modify any data structure, disable any check. The defence against this is to refuse to load unsigned modules.

CONFIG_MODULE_SIG_FORCE=y is the kernel-level switch that enforces it. With the flag set, unsigned modules are rejected at load time; a malicious or buggy administrator with SeLoadDriverPrivilege cannot load a malicious module unless they have the signing key, and it is not on a running system.

The module-signing key is deliberately a different key from the TCB key that signs binaries, and is not chained to it. Both are compiled into the image, so neither can rotate independently and neither can be an offline root — the TCB key signs binaries at build time. Chaining them would mean that compromising the TCB key also yielded the ability to load kernel modules. Keeping them independent contains binary signing and module loading separately. Both are ML-DSA-65.

The flag is verified at kernel build time. A kernel built without it doesn't enforce the rule and is not a valid Peios kernel for security purposes; the PIP threat model relies on this enforcement.

User-visible effect: kernel modules from the Peios distribution work (they are signed); modules built ad-hoc on a running system do not load. Third-party kernel modules (a vendor driver, say) must be signed by a key the kernel trusts, which in practice means going through the Peios signing infrastructure to add them.

1.2.3 The module-loading helper #

CONFIG_MODPROBE_PATH="/bin/modprobe" is required, and the binary it names must be TCB-signed.

When the kernel needs a module it does not have — mounting a filesystem whose driver is not built in, opening a socket for an unknown protocol family, resolving a crypto algorithm by name — it does not load it itself. It spawns a userspace helper to do it, and runs that helper at its own authority.

Two things follow. The path must be right: the upstream default is /sbin/modprobe, which does not exist on Peios, and left at that default every kernel-initiated load fails to find the helper while reporting nothing that names the cause.

And the path is a writable sysctl, which makes it an escalation vector — whoever can write /proc/sys/kernel/modprobe gets code of their choosing executed with the kernel behind it. The defence is not to protect the sysctl but to make redirecting it useless: KACS refuses any exec the kernel initiates on its own behalf unless the binary carries at least PeiosTcb trust. Pointing the sysctl elsewhere gains nothing without a TCB-signed binary to point it at.

This is the one place a signature gates execution rather than just labelling it. Everywhere else an unsigned binary runs and simply carries no integrity tier, because the process that asked for it bounds what it can do; a kernel-initiated exec has no such process behind it.

User-visible effect: a module the kernel asks for on your behalf loads only if the distribution's modprobe is in place and properly signed. A refusal is recorded as a kacs_exec event with reason umh-not-tcb, rather than appearing as an unexplained module-load failure.

1.2.4 Memory access restrictions #

CONFIG_STRICT_DEVMEM=y is required. This flag restricts /dev/mem and /dev/kmem access — physical-memory mapping pseudo-devices — to specific I/O regions, denying read or write access to actual system RAM.

The reasoning: a process that can read physical memory bypasses PIP. The DACL might say "this process cannot read the memory of authd"; the kernel's PIP check might agree; but if the process can mmap /dev/mem and read the corresponding physical pages, neither check matters. The defence is to restrict the device.

With CONFIG_STRICT_DEVMEM=y:

• /dev/mem is readable only for the kernel's defined I/O regions (memory-mapped I/O, the VGA framebuffer, etc.).
• General RAM is not readable through /dev/mem.
• /dev/kmem is unavailable.

This closes the physical-memory bypass for PIP. Combined with CONFIG_MODULE_SIG_FORCE, the two flags eliminate the kernel-level escapes from PIP that don't require an actual kernel compromise.

The flag is build-time; the kernel image either has it or doesn't. A kernel without it is not a valid Peios kernel for security purposes.

1.2.5 What the kernel will not have #

The Peios kernel is built with specific things excluded:

• CONFIG_BPF_LSM=n — the BPF LSM is not built. BPF programs running as security modules would conflict with PKM and bypass its checks.
• MAC LSMs disabled — SELinux, AppArmor, SMACK, TOMOYO are all disabled. Their config flags are off.

These exclusions are part of the kernel image. A distribution that includes these LSMs in its kernel image is not running Peios's intended security model.

1.2.6 What about user-space hardening #

A few things are explicit in the Peios environment that aren't strictly kernel invariants but are operational expectations:

• peinit is signed at TCB level. If the binary peinit is exec'd from is not signed at TCB, the kernel's verification at exec sets pip_type = None. peinit then runs unprotected, and any other process can interfere with it. This is operationally untenable; a properly-built Peios image has peinit signed.
• authd, loregd, eventd, lpsd are signed at TCB level. Same reasoning. These are the TCB daemons; they need PIP protection to function in their role.
• No kernel modules are loaded other than signed ones. Per CONFIG_MODULE_SIG_FORCE.

These are not enforced at boot in the sense of "the boot will fail" if violated — they are operational expectations. A Peios system where peinit is unsigned will boot, run, and "work" in a superficial sense; it just won't have the security properties Peios documents.

1.2.7 The invariant verification #

The kernel's init code does several checks at start:

1. Verify PKM is in the LSM stack and no incompatible LSM is present. PKM refuses to activate if violated.
2. Verify CONFIG_MODULE_SIG_FORCE is set. (This is a build-time flag; at runtime the kernel just behaves consistently with the build.)
3. Verify CONFIG_STRICT_DEVMEM is set. (Same; build-time.)
4. Construct the SYSTEM and Anonymous tokens. As covered in Bootstrap tokens.
5. Attach the SYSTEM token to init. Init becomes the first process holding it.
6. Start userspace. init execs the configured first program — prelude, the initramfs PID 1, which runs the initramfs and then execs the real init (peinit, in a normal Peios image). See The initramfs stage.

By the time userspace starts, the invariants are either satisfied (boot proceeds normally) or violated (boot fails or the security model is broken). The verification is internal; from the operator's perspective, the system either comes up cleanly or doesn't.

1.2.8 Failure modes #

If an invariant fails:

• MAC LSM detected at PKM init. PKM refuses to activate. The kernel boots but the access control is effectively absent. peinit's exec verification (looking for a TCB signature) returns "valid" but no PIP is set because PKM isn't running. The system is unsafe.
• CONFIG_MODULE_SIG_FORCE=n. Modules can be loaded without signing. An attacker with SeLoadDriverPrivilege can load arbitrary kernel modules and bypass everything. PIP is no longer meaningful.
• CONFIG_STRICT_DEVMEM=n. /dev/mem can read physical memory. Any process with READ_CONTROL on /dev/mem (or whose DACL grants it) can bypass PIP by reading memory directly.

Each failure mode is a security regression. The boot chain depends on the invariants holding. A deployment that needs to be sure its security model is operating correctly verifies these as part of the boot validation — typically via a post-boot tool that reads /proc/sys/kernel/lsm, checks build-time flags via the kernel config, etc.

For most Peios deployments built from the official kernel image, the invariants hold by construction. The verification is mostly relevant for custom kernels built from source — anyone modifying the kernel image needs to know which flags they cannot change.

1.2.9 Why these invariants #

Two themes underlie all of these:

The trust chain is rooted in kernel integrity. SYSTEM token, PIP, signed binaries — every layer of the model assumes the kernel is honest. If the kernel can be modified at runtime (unsigned modules), or its memory can be read or written from userspace (/dev/mem), the foundation crumbles.

PKM must be the sole authoritative LSM. Trying to compose PKM with MAC LSMs would give either over-restrictive or inconsistent semantics; the Peios access model is built on PKM's decisions, and that requires PKM to make the decisions alone.

The invariants are what make these themes operational: the kernel is built and initialised in ways that protect itself from runtime modification and that ensure PKM is in charge.

1.2.10 Where to go next #

For the tokens the verified kernel constructs at init, read Bootstrap tokens.

For the signing scheme module signing shares its keys with, read Binary signing.

For the protection model these invariants defend, read Process integrity protection.

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), behaviour under failure (§2.7), and the emission policy that decides which of the kernel's own event types are written (§2.8).

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.

Neither entry point consults the emission policy. Whether a type is switched on is decided by the emitter before it builds the event, with the check described in §2.8; an event that reaches the emission API is written.

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 and bottom halves 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 window is a few hundred nanoseconds.

Bottom halves matter because rings are written from softirq context as well as from tasks: the packet engine reports from the network receive path, and RCU callbacks run in softirq. With only preemption disabled, a softirq taken on interrupt exit could write the same CPU's ring between a task writer's sequence increment and its write_pos publication, interleaving two events in one reservation. Every ring writer — single, kernel batch and the emit syscalls — therefore holds bottom halves off across its reservation and write. A writer that runs with interrupts already disabled needs no more: neither a softirq nor a hard interrupt can reach its CPU.

Emission from hard interrupt or NMI context is refused. Bottom halves cannot be held off there, and such a writer could interrupt one holding the ring, so the event is dropped before any ring is touched: no sequence number is consumed, no ring drop is counted, and KMES tallies it in a private counter and logs the first such drop once. No kernel emitter runs in hard interrupt context.

The consumer wake that follows a write takes the futex hash bucket lock, which the futex core takes with bottom halves enabled; a softirq taking it while a task on the same CPU held it would spin forever. A writer outside task context therefore does not wake consumers itself: the write still advances the futex counter, and the wake is handed to a work item on the ring, which holds a reference to the ring until it has run in process context.

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, the drop counter is not incremented, and no gap is visible. Events emitted in this window are simply gone. KMES tallies them in a private counter and logs the total once when the rings come up.
• If the ring's recorded CPU identity does not match the executing CPU, the ring selection itself is untrustworthy, so every emission path — single, kernel batch and syscall — returns early without consuming a sequence number or counting a drop.

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 section with preemption and bottom halves disabled:

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 and bottom halves are re-enabled, and only then is the futex wake performed, outside the window — or, outside task context, handed to the ring's work item.

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 Consumer mapping permissions #

The producer metadata page and both aliases of the data region are read-only to consumers. The consumer metadata page is read-write: ordinary stores and authorised process_vm_writev writes can set need_wake. A consumer can remove write permission from that page with mprotect and restore it later.

A write-enabling mprotect covering any producer or data byte fails with EACCES, including requests spanning the consumer page and a protected region. Write faults and writable page pins must not upgrade the protected pages. These boundaries follow the original mapping offsets when mprotect splits a VMA; a new VMA start does not move the consumer page. Process access gates for remote writes still apply.

2.5.4 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.5 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.

For a batch, KMES first walks the reservations for every accepted event using local write and tail positions. It publishes the resulting tail with one release store before writing any event bytes, so a concurrent consumer can detect that the record it was reading has been overwritten. Publishing the tail only after the writes would allow the consumer's tail re-check to accept torn data.

After writing the events, KMES publishes the final write position with one release store and checks need_wake once, provided at least one event was written. New batch records become available at that final write-position store; the tail still transitions once per batch rather than once per overwritten event.

2.5.6 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.7 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 and is reported the same way, with -EIO as the error. 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.

The capacity swap runs first, and a BufferCapacity change that cannot be applied rolls back the capacity and nothing else: MaxEventSize, MaxNestingDepth, and MaxEmitRatePerProcess still commit in the same pass, against the capacity that is actually live, so the stored configuration describes the running system rather than the requested one. The situation that makes a swap fail — memory pressure — is exactly the one in which an administrator raising MaxEventSize and BufferCapacity together needs the MaxEventSize change to survive. 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.config.value.rejected reports one missing or invalid value. Its payload follows the event-field rules of PGSS §6: each dotted field path is a nested msgpack map, one per segment, and a field that does not apply is absent rather than nil. Every field lives under a single top-level config map of five keys, in order:

• config.key.path — always Machine\System\KMES.
• config.name — the canonical value name.
• config.expected.type, config.expected.min and config.expected.max — the registry type code and range from the key's definition.
• config.received.kind — one of missing, wrong-type or out-of-range. A malformed payload length reports wrong-type. A REG_DWORD and a REG_QWORD value out of range both report out-of-range, since config.expected.type already gives the width. config.received.type (the actual registry type code) is present exactly when the kind is wrong-type, and config.received.value (the number received) exactly when it is out-of-range. A missing value carries the kind alone.
• config.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.config.value.rejected events and retains all four defaults.

kmes.buffer.swap.failed reports a valid BufferCapacity change that could not be applied. Its payload is two maps: buffer, holding buffer.capacity-requested (the capacity asked for) and buffer.capacity (the capacity kept), and outcome, holding outcome.errno as a negative signed integer — -ENOMEM when the replacement rings could not be allocated, which is the usual case. The swap is system-wide, so no CPU or ring is named. Every failure is reported, not only allocation: a swap abandoned because migration met a corrupt size field reports -EIO, and one the kernel could not quiesce the CPUs for reports what stop_machine returned.

kmes.config.applied records a read of Machine\System\KMES that reached the commit, after the rejection reports and the commit itself. Its payload is three maps: config, holding config.key.path and config.counts with the four counts applied, retained-missing, retained-invalid and ignored-unknown; buffer, holding buffer.capacity; and emission, holding emission.rate-limit. The capacity and rate are read back after the commit, so they are what is in force rather than what the plan asked for. A read whose capacity swap failed still reaches the commit — the other three settings commit without it — so it is recorded as applied too, with the capacity kept, beside the kmes.buffer.swap.failed that says why. MaxEventSize and MaxNestingDepth in force are not in the record: the catalogue has no field for either yet.

kmes.config.refresh.failed records a re-read, after the watch saw a change, that failed: the source did not answer, answered with something malformed, or the plan was refused (more than four rejection reports, or a configuration the second gate rejects). Its payload is config, holding config.key.path, and outcome, holding outcome.errno. The configuration in force stays as it was. The record is essential: the registry and the running kernel disagree until the next change, and it is the only sign. A failed capacity swap is not a failed read and does not produce one. A read that fails during the bootstrap refresh is not recorded this way: it fails that refresh, which is traced and leaves the machine-root fallback armed to try again (LCS §5.10.4). The emission policy reports a failed walk of Machine\Generic\Events with the same record (§2.8).

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, or the migration meets a corrupt ring, the existing rings stay live at their current size, the capacity change is not applied, no generation changes, and consumers are unaffected. A kmes.buffer.swap.failed event records the requested and retained capacities as buffer.capacity-requested and buffer.capacity, and the error as outcome.errno (§2.6). KMES does not retry; the next configuration write or a reboot triggers another attempt.

2.7.5 Configuration that cannot be read #

A re-read of Machine\System\KMES that fails keeps the configuration in force, and a walk of the emission policy that fails keeps the mask in force; each is recorded as kmes.config.refresh.failed (§2.6, §2.8). Nothing retries on its own: the next change under the key reads it again.

2.7.6 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.7 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.8 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.9 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.10 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.

An event type that is switched off is never written. PGSS §6.9 defines the policy: a tree of keys under Machine\Generic\Events, one per event-type segment, any of which may hold an Enabled REG_DWORD of 0 or 1, where the deepest value on a type's path decides and the type's tier decides when there is none. This section is how the kernel applies that policy to the event types it writes itself. Userspace components apply it to their own types through libpeios, peios-rs and libp-go; KMES does not enforce the policy on what userspace emits.

2.8.1 The kernel's event types #

The kernel writes a closed set of event types, fixed when it is built. They are generated from the kernel's own evman fragments (pkm/evman/*.evman) by tools/gen-kmes-event-table.py into a C header and a matching Rust module, each type with an id, its type string and its tier. The generator has a --check mode, so a type cannot change tier in its fragment without the kernel's table following.

The policy is cached as a 64-bit mask with one bit per kernel type: bit i set means type i is switched on. A walk of the registry computes a whole new mask and publishes it with a single store, and an emitter reads it with a single load, so a decision is a load and a bit test and no lock is taken on any emission path. A mask is never published half-computed.

An emitter asks before it builds a payload, with pkm_kmes_event_enabled(id), and Rust emitters through the generated module's enabled(). An essential type's tier is a compile-time constant, so the check for it folds to on when the emitter is compiled and never reads the mask: no policy can switch an essential type off, whatever the tree holds. The policy and an event type's own gating — a SACL, an alarm mask, a REPORT level — combine by AND, the policy first because it is the cheaper of the two.

Every kernel emitter makes the check, and makes it first: before it resolves the subject, looks up a path, sizes the payload or allocates anything. A type that is switched off therefore costs one check and nothing else, and the emitter carries on as though the record had been written. Each emitter names its type with the generated table's string rather than one of its own, so the type written and the type the policy decided on cannot drift apart.

2.8.2 Before the policy can be read #

From the moment PKM initialises until a registry source for the Machine hive has registered and the first walk has finished, the mask holds the tier defaults: every essential and standard type on, every verbose and debug type off. That is PGSS §6.9's rule for an emitter that cannot read the policy, and the kernel writes events from long before any source exists, so it is the policy the kernel runs on for the whole of early boot. No event is ever held back to wait for the registry.

A verbose type the registry switches on is therefore not written before the walk, and a standard type the registry switches off is. A boot-time event that must be written whatever the policy says has the essential tier and nothing else.

If Machine\Generic\Events does not exist, no Enabled value can be found anywhere and the tier decides for every type: the kernel publishes the tier defaults. A bootstrap refresh that finds the key gone after it existed does the same, so deleting the key undoes the policy it held.

2.8.3 The walk #

One walk resolves every kernel type at once. It reads Enabled on Machine\Generic\Events itself, then descends the trie of the kernel types' segments — kacs, kacs\audit, kacs\audit\access and so on — looking up only the keys some kernel type's path passes through. Each key that exists costs one RSI_LOOKUP and one RSI_QUERY_VALUES.

A key that does not exist ends the walk down that path, and nothing beneath it is asked for: an empty Events key costs one query and one lookup per root. A key that is a link is not followed and ends the walk the same way.

Only an Enabled value that is a REG_DWORD holding 0 or 1 is a setting. A value of another type, of the wrong length, or holding any other number is ignored as though it were absent, and the setting found above it stands. Nothing reports the ignored value. Value names compare ignoring case, as the registry does.

From what it read the walk computes the mask by PGSS §6.9's procedure: for each type, the Enabled on the deepest existing key on its path decides; with none, the tier decides; an essential type is on. The mask is then published.

A walk that fails — the source does not answer in time, or answers with something malformed — publishes nothing. The mask in force stays, whether that is the tier defaults or the last mask a walk computed, and a kmes.config.refresh.failed record names Machine\Generic\Events and the error.

2.8.4 Noticing a change #

At bootstrap, after the KMES, layer, port reservation and network policy keys, LCS discovers Machine\Generic\Events and walks it. If it exists it gets an internal watch of its own; if not, the machine root fallback watch stays armed (LCS §5.10.4), and creating the key — Generic and Events two levels below Machine, with or without Generic already there — re-runs the bootstrap, which then walks it and watches it.

The watch covers the whole subtree at any depth, but it passes on only what can change a kernel type: a change on Events itself, a change beneath one of the kernel's five roots (kacs, kmes, lcs, ntfe, stratafs), and among value changes only those to a value named Enabled. A vendor writing under Events\org\…, which PGSS §6.9 lets an emitter ignore, costs the kernel nothing.

What the watch passes on is coalesced. The first change of a burst schedules one re-walk 50 ms later; changes that arrive before it runs join it rather than postponing it, and a change that arrives while a walk is running schedules the next one. A change to the policy applies within about 50 ms plus one walk of the write that made it — or, when a walk is already in progress, after that walk and one more — however busy the tree is, which is inside PGSS §6.9's one second.

A change is not retroactive. An event already written stays written, and a decision made before the walk publishes stays made.

2.8.5 The shipped seed #

The kernel package ships a registry seed, event-policy.reg in /usr/share/regim/, that creates Machine\Generic\Events and sets no Enabled anywhere: with nothing set, the tiers decide, which is the policy a machine ships with. The key is there so the policy has a home for an administrator to write beneath. Like every seed it is inert until an image names it in [registry] autoapply, and until then every emitter decides by tier just the same.

The seed gives the key the SACL PGSS §6.9 asks for, one that audits writes: S:(AL;CI;0x10002;;;WD), a SYSTEM_ALARM ACE for Everyone, inherited by every key beneath, over KEY_SET_VALUE | DELETE. A handle opened for writing anywhere in the policy tree carries that continuous-audit mask, so each change to what is recorded can itself be recorded. Only the SACL is set; the owner and DACL stay inherited from the Machine hive.

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/. The PKM UAPI exports the uppercase constants in <pkm/syscall.h>. Peios glibc 2.44-5 and later exports the standard lowercase SYS_kmes_* aliases in <sys/syscall.h>; each alias has the same number as its PKM constant.

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 in the table, but the kernel is built without CONFIG_X86_X32_ABI, so the only entry point that exists is x86-64: an x32 invocation (the number with bit 30 set) fails ENOSYS like any other x32 syscall on this kernel.

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

The kernel-private storage and call-site inventory is in §3.E: the LSM security blobs, every registered KACS hook, and the direct metadata entry points used by patched file-descriptor operations.

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. It is a ratchet carried by every token, primary or impersonation, and only ever goes down (§3.5.1).

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.

The audit records these categories produce describe the effective token in their subject.token fields: the user SID as sid, the groups as groups with their attribute words as the parallel group-attributes, the integrity level as integrity, token_id as id, auth_id as auth-id, the token type as type (primary or impersonation), the impersonation level as impersonation (0 for a primary token), and the projected Linux UID as uid (§3.C).

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 an explicit, 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 — no SACL, or no non-inherit-only mandatory label ACE — is unlabelled, and the token survives exec unchanged. This is deliberately not the access-check rule, under which an unlabelled object counts as Medium (§3.8.3): an image that labels nothing would otherwise demote every process on it, PID 1 first, to Medium — which is exactly what happened before PEI-530, leaving the TCB below every High-integrity user and unable to convey their identity.
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 — the impersonation level included — 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, and only to a level the image itself claims. 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.

The handle has to carry TOKEN_ASSIGN_PRIMARY, the token has to be a primary token, and the caller's real token has to hold SeAssignPrimaryTokenPrivilege enabled — an impersonating thread's effective token does not satisfy the gate, and the privilege is marked used on success. Unless that real token also holds SeTcbPrivilege enabled, the token being installed has to carry the same user SID and the same LogonSession as the caller's, or the call fails with EPERM; this is what stops a non-TCB holder of SeAssignPrimaryTokenPrivilege from installing an arbitrary higher-privilege token on itself, and SeTcbPrivilege bypassing it is how peinit installs service tokens with a different user SID and LogonSession.

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.

Successful installations are ordered per process. Siblings converge to the latest successful installation in that order; older queued work must not restore a superseded token, including when retried after an allocation failure. Concurrent callers need not complete their syscalls in installation order. Once exec commits its primary token, delayed pre-exec installation work cannot replace it.

A new thread joins the same convergence rule even if it was not yet visible when an installation selected the siblings to update. This does not change a process fork's independent copy of the calling thread's primary token.

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; impersonation level Delegation, the top of the ratchet; 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. Its audit_policy is PRIVILEGE_USE_SUCCESS, so every privilege SYSTEM spends — at a capability gate and in an access check — is recorded as kacs.audit.privilege.used (§3.4), and tokens derived from it carry the same policy. The Anonymous token and the query-only SYSTEM token have an audit policy of 0.

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. A peer token captured 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 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.

CreateToken accepts all four impersonation levels for a Primary token, including Identification and Anonymous, and preserves the chosen level and user identity. The level limits what may be derived from the token; it does not prevent the process from acting as its own primary identity. A peer capture takes the lower of the primary and socket levels: Identification conveys identity without authority to act as it, while Anonymous conveys the anonymous identity.

A minter chooses this ceiling deliberately (§3.5.1). authd uses Delegation for verified evidence and Impersonation for attested evidence; peinit's SYSTEM token uses Delegation. Each client may lower its level per connection. Older kernels refused Primary tokens below Impersonation as a migration guard; callers must not use an ignored or default Anonymous field when they intend peers to impersonate the identity.

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. The impersonation level is chosen by the caller and is a ratchet: whatever the types involved, the new level has to be equal to or lower than the source's, and asking for more fails with EINVAL. A primary minted at Delegation can be duplicated to an impersonation token at any level; a primary at Impersonation cannot yield a Delegation-level token; an Identification-level token cannot be duplicated up to Impersonation or Delegation. The level only ever goes down — reaching a higher one again means minting a fresh token with CreateToken.

Duplicating to Primary is how an impersonated identity becomes a process — the server's impersonation token, converted, is what a service manager installs on a child it launches as that client. The result keeps the identity and the level, so a primary made from a client captured at Impersonation is itself capped at Impersonation and so is every process and token descended from it. The kernel refuses a Primary result below Impersonation: a captured Identification or Anonymous identity must not become an acting process through duplication. This restriction applies even when the source is itself Primary. It is separate from privileged CreateToken, which may deliberately mint a primary with a low derivation ceiling.

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 kacs.session.destroyed event through KMES. The last token usually goes when a credential is freed, which happens in an RCU callback where no record can be built, so the session is queued, still referenced, and a kernel work item writes the event moments later and then releases it. The session is gone at once — it no longer resolves — but its event follows the teardown rather than coming from it, and its header names the kernel worker that wrote it. The event is for whatever keeps per-session state outside the kernel — an audit pipeline, an accounting tool, an authority that caches credentials per session. authd keeps none and does not subscribe.

The record describes the session under object.session: its LUID as id (the subject.token.auth-id of every record made under it), the user SID as user.sid, the logon type as logon-type, the authentication package as auth-package, and the creation time as logon-time. The logon type is written by name — interactive, network, batch, service, network-cleartext, new-credentials or remote-interactive — and the time in realtime nanoseconds, though the kernel holds it to whole seconds.

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 kacs.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. Each line reads

logon_session_id=<u64> user_sid=<hex> logon_type=<u32> auth_package=<hex> created_at=<u64>

with the user SID's binary form and the package name's bytes in lowercase hexadecimal, and created_at in seconds since the Unix epoch. securityfs itself is unclassified by FACS, so its objects sit deny-missing until the mount is given a synthesising policy (§3.9.5); only then can the file be opened at all. On Peios, peinit gives it one at boot that lets Authenticated Users open and traverse. Reading it is access-checked against a synthetic descriptor granting read to SYSTEM and Administrators, 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 (§3.2.3). And the CAP_SYS_BOOT mapping selects between SeShutdownPrivilege and SeRemoteShutdownPrivilege by inspecting the session's logon type (§3.10). 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. On Peios authd does it, when asked over /run/logon.sock (PGSS Logon §2.22):

1. A caller asks authd to end the session, and authd decides whether it may: its own session as a person, anyone else's by an access check against local policy. SYSTEM's session (999), Anonymous's (998) and every session of logon type Service are never ended this way; a service is stopped through peinit.
2. authd enumerates processes whose primary token carries the target auth_id, by walking /proc, opening each process with pidfd_open, opening its primary token with kacs_open_process_token on that pidfd, and reading TokenStatistics, which includes auth_id. No dedicated enumeration syscall exists or is needed. A thread's impersonation token is not consulted, so a service impersonating a member of the session is not one of its processes.
3. authd sends each SIGTERM with pidfd_send_signal, waits up to a grace period (5 seconds) for them to exit, and sends SIGKILL to the survivors.
4. It walks again, since a process may have forked meanwhile, for at most three rounds.
5. The processes terminate, dropping their token references.
6. The last reference drops and the session object is cleaned up.

Each token handle authd opens in the walk is itself a reference to the session, and is closed as soon as auth_id has been read.

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. The walk finds processes running under the session, not every process holding one of its tokens, so such a reference keeps the session alive after authd has ended every process in it, and authd reports nothing about it. A process that has exited but not been reaped likewise keeps its token, and the session, until it is reaped.

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.

Opening through /proc. /proc/<pid>/token and /proc/<pid>/task/<tid>/token open a process's primary token and a thread's effective token as a query-only handle: the fd always carries TOKEN_QUERY and nothing else. Opening another process's file makes both of the syscall's checks — PROCESS_QUERY_INFORMATION on the process's descriptor, with PIP dominance, and TOKEN_QUERY on the token's own descriptor — so the path reads nothing the syscall would refuse. A process opens its own without either check.

The peer-token socket option (getsockopt(SOL_KACS, KACS_SO_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 | TOKEN_DUPLICATE. A token delivered in a KACS_SCM_TOKEN control message carries the same three. TOKEN_DUPLICATE is what lets a server turn a client's identity into a primary token for a process it launches on the client's behalf (§3.2.4); it is safe to hand out because the level ratchet means the copy can never act above the level the client chose (§3.5.1).

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;
• Administrators (S-1-5-32-544) TOKEN_QUERY.

The Administrators grant is read-only: it lets an administrator see who any process runs as, its groups and privileges, and which logon session it belongs to, which is what a machine-wide process listing needs. Duplicating, impersonating, adjusting or rewriting the token still needs the token's own grants.

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

Do not infer an additional service policy from peinit launch: the source-checked peinit 0.0.12 path does not make a per-service PSB mitigation request. Inherited and self-applied flags are separate from that launcher behavior.

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 Reading the PSB #

/proc/<pid>/psb gives a process's PSB as one line of text, in this order:

pip_type=<u32> pip_trust=<u32> mitigations=0x<hex> process_guid=<uuid>

mitigations is the committed mitigation bitfield in at least three hexadecimal digits, including ui_access and no_child_process, with the bit values of §3.A. process_guid is the 16 bytes in order, formatted 8-4-4-4-12.

A process reads its own without any check. Reading another process's needs PROCESS_QUERY_LIMITED on its process descriptor, with SeDebugPrivilege rescuing a descriptor denial as it does for every process right, and does not need PIP dominance. That a process is protected is not a secret every other refusal keeps; it is what a caller needs to see to understand those refusals.

The PSB is otherwise written only: kacs_set_psb sets mitigations and returns nothing about them.

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

psb is the process's PSB, read under PROCESS_QUERY_LIMITED with no PIP dominance (§3.3.2). It is the one /proc entry whose check is KACS's own rather than the metadata rule's.

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, of type kacs.audit.privilege.used, are emitted only when the token's audit_policy opts in through PRIVILEGE_USE_SUCCESS or PRIVILEGE_USE_FAILURE, and they come from two places, told apart by operation.name.

3.4.1.5.1 In an access check #

An access check records the five AccessCheck-influencing privileges, with operation.name access-check. 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 kacs.audit.privilege.used events for any privilege.

3.4.1.5.2 At a capability gate #

A privilege that satisfies a Linux capability check is recorded too, with operation.name linux-cap, the capability in linux.cap and the privilege it mapped to in privilege.name, under the token's PRIVILEGE_USE_SUCCESS policy. The volume-management gate the mount paths consult in place of CAP_SYS_ADMIN records the same way with operation.name volume-mount and no linux.cap. Such a record carries no object, masks or contribution.

Each gate is recorded once per process and effective token: the first use of a capability by a process under a token is recorded, and later uses are not, until the process acts under a token with another GUID, when every gate counts as unused again. The set belongs to the process, not to the token, whose used flags derived tokens copy and every process sharing it shares.

Only successful uses are recorded, and only those of a user process's own capability checks: a check made with CAP_OPT_NOAUDIT is a probe and records nothing, nor does a kernel thread's check, a check from interrupt context, or a check against another process's credentials. A check that consumes no privilege — the capabilities every process holds and the ones none may hold — records nothing either.

A capability check can run with spinlocks held, where a record cannot be built, so the gate notes the use and the record is written as the process returns to user space, or as it exits. The record therefore follows the system call that spent the privilege rather than appearing within it.

The boot SYSTEM token carries PRIVILEGE_USE_SUCCESS (§3.2.3), so on a stock system these records come from SYSTEM and the services running on its token: they answer who used SeTcbPrivilege, and for what.

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 (§3.2.3). 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.

The PEI-549 block-layer change also accepts enabled SeManageVolumePrivilege or SeTcbPrivilege, with successful privilege-use marking, for BLKRRPART (partition-table rescan), BLKPG (partition management) and BLKFLSBUF (buffer-cache flush). The caller still needs a usable block-device handle. Administrators membership alone, or a present but disabled privilege, does not pass this gate. Other CAP_SYS_ADMIN checks, including BLKROSET, retain their existing TCB requirement. This change has native VM qualification; older published kernels may still require SeTcbPrivilege for all three.

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, NewCredentials, or RemoteInteractive 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 #

No privilege. Binding a port is an access check against the port's reservation — a security descriptor keyed by protocol and port range — not a privilege test; see Port reservations. Bit 63 was SeBindPrivilegedPortPrivilege until that object existed; the bit is retired and not reused.

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 and is unused: no kernel definition exists for it and nothing consults it. Submitting a supervised job is not a privilege at all — it is governed by the file Security Descriptor on the service manager's jobs socket, checked by the kernel when a process connects (the Peinit TRM). 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, with EACCES — the same refusal the kacs_access_check syscall reports for that token.

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.

3.5.1.1 The level is a ratchet #

Every token carries an impersonation level, and on every token it means the same thing: identity derived from this token may act at no more than this level. An impersonation token acts at its level. A primary token's level is the ceiling on everything the process carrying it can convey — what a peer captures at connect, what KACS_SO_PASS_TOKEN attaches, what KACS_IOC_DUPLICATE produces in either direction.

The level only ever goes down:

• Socket capture and KACS_SCM_TOKEN attach store the lower of the socket's level and the source token's own;
• DuplicateToken refuses a result above its source, whatever the types involved;
• fork, exec, NEW_PROCESS_MIN, FilterToken and primary installation copy it unchanged.

The one way to a higher level is a fresh token from CreateToken, which takes SeCreateTokenPrivilege. authd mints logon tokens at Delegation and the bootstrap SYSTEM token is Delegation, so an identity starts at the top and each hop can only lower it.

This is what makes the client's choice hold across any number of hops and process boundaries. A client that connects at Impersonation is captured at Impersonation; a server that converts that token to a primary and launches a process with it (§3.2.4) produces a process capped at Impersonation; and nothing that process captures, conveys or duplicates can ever be Delegation — so authd, which reads the level to decide whether to forward the client's credentials, is never shown a Delegation flag the client did not grant.

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 on the socket with setsockopt(SOL_KACS, KACS_SO_IMPERSONATION_LEVEL) — the default is Impersonation; the option may be changed at any time and bounds every capture made from then on — and calls connect(). The kernel's LSM hook fires on the Unix stream connection.

Identity is captured, both ways. The hook examines the client thread's effective credential together with the socket's maximum level, derives the identity at the lower of that level and the effective token's own (§3.5.1), and stores the result on the accepted end. It also stores, on the connecting end, the identity the listener captured when listen() was called — so a client can read KACS_SO_PEER_TOKEN on its own socket immediately after connect() and verify who it reached, at Identification level unless the listener set its own level. The listener's identity is what listen() saw; a process that inherits a listener it did not create (from a descriptor store after a restart, or from a broker) replaces it with its own using setsockopt(SOL_KACS, KACS_SO_RESTAMP), which is self-gated and fails with EINVAL on a socket that is not listening. Clients that connect before the restamp see the previous holder, which is honest: that is who was listening. Squatting a name therefore buys nothing against a client that checks — the squatter's own identity is what it conveys. 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 reads the peer token with getsockopt(SOL_KACS, KACS_SO_PEER_TOKEN) on the accepted connection, which opens a token fd carrying TOKEN_QUERY | TOKEN_IMPERSONATE | TOKEN_DUPLICATE for the identity in that end's conveyed-identity register — at this point, the identity captured at connect (see Per-message identity below for how the register moves). It impersonates by installing that fd with KACS_IOC_IMPERSONATE: the kernel 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. libpeios fuses the two steps as peios_token_impersonate_peer for the handler that impersonates, works and reverts on one thread.

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 installs another token with KACS_IOC_IMPERSONATE 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 Per-message identity #

The connect-time capture is the first entry in a per-end conveyed-identity register: the peer identity associated with the data that end has consumed so far. Identity can also travel with the data itself, as a KACS_SCM_TOKEN ancillary message under the SOL_KACS level, and each such message the reader's position passes advances the register. The anchor is the read position, never arrival: a token still queued behind unread data is not yet visible, so a handler can never be told an identity for a request it has not read. KACS_SO_PEER_TOKEN returns a fresh fd to an immutable snapshot each time; two calls may name different tokens, but a token never changes.

Sending. A sender conveys identity in one of two ways, and the receiver cannot tell them apart, because both mean the same thing — the kernel verified that the sender could be this identity when it sent these bytes:

• Automatically, with KACS_SO_PASS_TOKEN set on the sending end: every send carries the sender's effective token, derived at the lower of the end's impersonation level and the token's own. The derivation is cached against the effective token it was made from, so a run of sends under one identity costs one derivation. A thread that impersonates client A, writes to a pooled connection, reverts and writes again conveys A for the first write and its own identity for the second, with no change to the library doing the writing.
• Explicitly, by attaching a token fd in a KACS_SCM_TOKEN cmsg. The kernel gates the attach exactly as it would gate impersonating that token: the fd must carry TOKEN_IMPERSONATE, a primary token is first derived to an impersonation token at the lower of the end's level and its own, and the two-gate model runs with the sender as installer. An attach the gates would cap below the token's own level fails with EPERM — an explicit act fails loudly where an install would silently downgrade. Attaching a token is therefore never more than impersonating it, sending, and reverting; it just avoids the install. A router forwarding on behalf of many clients re-attaches each client's token to the messages it forwards, and each downstream receiver gets a kernel-verified identity through the router.

Anonymous-level tokens attach without a gate, as assuming Anonymous is always a downgrade. At most one token per message.

Receiving. Every skb a send produces carries the conveyed token, so a large stream write conveys the same identity on all of its fragments. A stream read stops at an identity boundary rather than gluing bytes conveyed under different identities into one return, which keeps the register exact even on a byte stream; on SOCK_SEQPACKET one send is one message and one identity, which is why it is the recommended type for Peios-native protocols. As the reader's position passes conveyed data, the register moves to that identity. MSG_PEEK neither advances the register nor consumes; a read() or splice() that consumes data advances it just as recvmsg does, because the register is kept at the point of consumption, not where ancillary data is copied out.

A KACS_SCM_TOKEN cmsg — carrying a fresh TOKEN_QUERY | TOKEN_IMPERSONATE | TOKEN_DUPLICATE fd — is delivered with a read when the receive call supplied room for it and the read's identity differs from the register the reader had before the read; otherwise nothing is delivered, and MSG_CTRUNC is set only when a token was due and no room was supplied. A handler that never reads ancillary data still has the register: recvmsg, then getsockopt(KACS_SO_PEER_TOKEN), gives the identity of what it just read. Parsing the cmsg is the path for pipelined or concurrent consumers that need the token bound to a particular message.

SOCK_DGRAM sockets carry no register — many senders share one receiving socket — so a datagram's token is delivered with every datagram that carries one and is never retained.

3.5.3.8 Supported transports #

Peer-token capture works on two AF_UNIX 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(), read with KACS_SO_PEER_TOKEN, impersonate, revert — with per-message identity layered on top as described above. SOCK_DGRAM supports per-message identity only: KACS_SO_PASS_TOKEN and KACS_SCM_TOKEN work, since a send needs no connection, and KACS_SO_IMPERSONATION_LEVEL bounds them as on any socket, but there is no register.

Where the register does not apply, KACS_SO_PEER_TOKEN reports which case it is. On a datagram socket, or any non-Unix family, the option fails with EOPNOTSUPP. A socketpair() end is connected but starts with an empty register — no connect happened to capture anything — so the option fails with ENODATA until the peer conveys an identity, after which the register works as on any connection. A socket that is not yet connected fails with ENOTCONN. Pipes and FIFOs are not sockets at all, so getsockopt itself fails with ENOTSOCK before KACS is reached.

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 — the peer-token option, an SCM_RIGHTS transfer, or any other path.

3.5.3.9 Audit records #

Every KACS_IOC_IMPERSONATE writes a kacs.impersonation.started record through KMES (§3.C). Its subject is the server's token, the one that acted, and its object is the client token: object.token.sid, .type, .integrity, .auth-id and .restricted, with the level the client token offered as object.token.impersonation and the level the gate allowed as object.token.impersonation-permitted. The thread that took the identity on is emitter.thread.tid, since impersonation is per thread. Where the gate needed SeImpersonatePrivilege and used it, the record carries privilege.name and privilege.held.

A level the gate lowered is not a failure: the record says outcome.success with impersonation-permitted below impersonation. A lowered level installs a new token, and the record's object.token.guid and object.token.id are always the installed token's — the client's own when the level was not lowered, the new one when it was — so they match the header of the records the thread writes next.

A refused impersonation is recorded too, with outcome.errno and, where the kernel knows why, outcome.reason: primary-token for a primary token (EINVAL), restriction-escape for a restricted server reaching for an unrestricted token of its own user (EPERM), no-impersonate-access for a handle without TOKEN_IMPERSONATE (EACCES), and projection-failed when the identity could not be projected onto the thread's credentials. A refusal before the gate answered carries no impersonation-permitted.

Ending an impersonation writes kacs.impersonation.reverted, a verbose type, so only where the emission policy (§2.8) switches it on. The record names the token given up in object.token.guid and object.token.sid, with the thread's token after the revert as subject. operation.name says why: revert for kacs_revert, exec for the revert every exec performs, and replaced when a second impersonation ends the first. A revert with no impersonation in force writes nothing, nor does the revert and re-apply around a primary-token install, which leaves the impersonation in place, nor does a thread that exits while impersonating. Both records are best effort: a record that cannot be built does not change the outcome of the impersonation or the revert.

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.

/sys/kernel/security/kacs/signing_keys lists the table: one line for each entry before the terminator, in table order, reading

key_sha256=<hex> pip_type=<u32> pip_trust=<u32>

where the key is named by the SHA-256 of its raw 1952-byte public key, in lowercase hexadecimal, and the type and trust are the entry's own, in decimal. Entries are listed as they are, whether or not the validator would accept them, so a table that disables signing shows why. The keys are public, so reading the file is not access-checked; whoever can open it can read it. Like every securityfs object, it can be opened only once the mount has a synthesising policy, which on Peios lets Authenticated Users in.

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.signature.crypto.failed KMES event carrying signature.crypto-stage boot-probe and the error as outcome.errno, negative. 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 Firmware verification #

A firmware load is not an exec, so none of the above would see it — and firmware is code that runs on a device with DMA into host memory, which makes a tampered blob a complete compromise. KACS therefore implements the kernel_read_file and kernel_post_read_file LSM hooks for READING_FIRMWARE (kacs/firmware.c).

The signature is the ordinary PIP blob, found by the lookup above. Firmware is never ELF, so in practice it is the security.peios.sig xattr, which peipkg stamps at install from the <file>.peios.sig sidecar the package carries (PSPU §5.16). The bar is the PeiosTcb tier — the same floor a usermodehelper exec must clear, since both are the kernel choosing to run code it did not ship. A verified signature at any other tier counts as no signature.

For a whole-file read, which is the common case, the post-read hook is handed the exact bytes the loader will decompress and give to the device, and those are what is hashed — no second read, no TOCTOU. A partial read (a driver pulling a window out of a large blob) only passes through the pre-read hook, where nothing has been read yet, so that path verifies the file through the reader probe instead. The hash covers the compressed bytes as they sit on disk, so verification precedes decompression.

Policy is CONFIG_SECURITY_PKM_FIRMWARE_SIG_ENFORCE, overridable for one boot with kacs_fwsig=enforce or kacs_fwsig=log on the kernel command line; there is no runtime switch. Under enforce an unsigned, tampered or under-tier file is refused with -EPERM; the loader logs that against the path it was refused at, moves on to its remaining search paths, and reports the driver an ordinary load failure. Under log the verdict goes to a rate-limited warning and the kacs:kacs_firmware_load tracepoint and the load proceeds. 2026.8 ships in log mode: the firmware set is being signed for the first time, and a blob the packaging missed has to show up as a warning rather than as a device that silently stops probing. Enforcement becomes the default once a release has run clean.

CONFIG_FW_UPLOAD — a device's own sysfs update interface — is not covered; it is selected by several drivers and cannot be turned off, and the drivers that expose it are the place to gate it if that ever matters. The test.fwsig build stage exercises both modes through CONFIG_TEST_FIRMWARE's trigger_request, which pulls a named file through the real loader path with no hardware.

3.6.8 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.9 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. The one exception is /proc/<pid>/psb, which needs PROCESS_QUERY_LIMITED and no dominance: a protected process's PIP type, trust and mitigations are readable to whoever its descriptor lets query it (§3.3.2). 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 Trust raising under a tracer or supervisor #

Dominance is tested when a tracer attaches and when a seccomp filter is installed, and not again. That leaves one way to end up controlling a process one does not dominate: be attached to it, or supervising its syscalls through seccomp user notification, when it execs a binary whose signature would raise its label. Linux marks exactly these execs — LSM_UNSAFE_PTRACE when the task is traced, LSM_UNSAFE_NO_NEW_PRIVS under no_new_privs, which every unprivileged seccomp filter requires — and uses them to withhold setuid gains. KACS applies the same rule to the label: the exec goes ahead, but the staged label is capped at the process's current one whenever the new label would not be dominated by it. The binary runs with the protection it can be given, as a setuid binary runs without its setuid under strace.

There is no privilege exception. SeDebugPrivilege never bypasses dominance, and a TCB tracer already dominates every label, so nothing is lost by capping. An exec that does not raise the label — the common case, and every unsigned binary — is untouched. A cap emits kacs_exec with reason pip-capped-unsafe carrying the label that was kept.

3.7.6 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.7 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.8 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.9 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 the staged scalar result differs from the effective one, when any node's staged granted mask differs from that node's effective granted mask, or when staged auditing differs from effective auditing — the scalar comparison is not mode-branched. 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.
• 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. Every call that passes the privilege gate writes a kacs.caap.policy.changed record (§3.C) naming the caller, the policy SID as caap.policy.sid, and operation.name set or remove, with outcome.success and, when the change did not apply, outcome.errno. 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 — in the effective and the staged evaluation alike, and in the scalar total exactly as on every node of a result-list check. 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: kacs.audit.access.checked for object-access events from the SACL walk and from token audit-policy forcing, and kacs.audit.privilege.used for privilege-use events. A third family is emitted for the CAAP conditions of §3.8.8: kacs.caap.sacl.skipped for a rule SACL that would not parse or evaluate, and kacs.caap.staging.diverged for 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.

3.8.9.1.1 On the AccessCheck syscall #

Through kacs_access_check and kacs_access_check_list the descriptor is the caller's own, SACL included. So that no process can write kernel-origin audit records at will by supplying a SACL that matches itself, the records a SACL generates there are written only when the calling process's effective token holds SeAuditPrivilege, enabled. Without it the check runs and answers exactly as it would otherwise, and its SACL records are withheld; the privilege is marked used when it admits them. The privilege is the caller's, not the subject's: a daemon checking a client through token_fd needs it on its own token. This is Windows' rule for AccessCheckAndAuditAlarm.

The records the checked token's own audit policy forces, and privilege-use and CAAP records, are not gated: the policy belongs to the token, not to the caller.

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 kacs.audit.handle.used 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, as access.matched, beside the whole stored mask as access.audit-mask.

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 identity from the audit context the caller supplied, exactly as a SACL-triggered record does. 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 — subject.token.sid, .groups with their parallel .group-attributes, .integrity, the token's own LUID as .id, its logon session as .auth-id, .type, .impersonation and the projected .uid — and the PIP state as subject.pip.type and subject.pip.trust; the object, as object.kind and the fields beneath it; the access, as access.requested and access.granted, with outcome.success; the trigger, trigger.kind (sacl or policy) and, for sacl, the matched ACE as trigger.ace, or for a privilege record the privilege.* fields; and the process, as emitter.process.pid, .name and .executable.

An access record also says what the mandatory checks withheld, since that is often the whole reason a check the DACL would allow was denied: access.denied-integrity is the requested bits the object's mandatory label denied, and access.denied-trust the requested bits its process-trust label denied — every bit each denied, for a MAXIMUM_ALLOWED request — and each is absent when it denied none.

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.

3.8.9.5.1 The object #

Where the kernel makes the check itself it knows the kind of object and writes object.kind: file, process, token, socket (which covers port-reservation binds) or ipc. A token check also writes the target's object.token.id and object.token.guid. Some identity is not yet reachable where the record is built, and is absent rather than invented: object.file.path on file checks, object.process.pid and object.process.guid on process checks. A mount-namespace check writes object.kind mount-namespace and nothing beneath it: a namespace has no name or identifier to carry.

A check made through kacs_access_check names its object through the audit context (audit_context_ptr, audit_context_len), the PGSS §6.7 map:

{kind: "service", service: {name: "jellyfin"}}

The kernel validates it before running the check and fails the call with EINVAL unless it is well-formed msgpack no deeper than KMES's default nesting depth less one; its root is a map of one or two entries with string keys; it has exactly one kind, a string matching the PGSS §6.3 segment grammar [a-z][a-z0-9]*(-[a-z0-9]+)*; and its only other entry is keyed by that kind and holds a non-empty map whose keys match the same grammar. The kernel copies it into the record as object.kind and object.<kind>.* — object.service.name above. A call without an audit context writes no object: the kernel does not know what was checked.

These values are the caller's claim, which the kernel copied but did not observe. So is everything else on the syscall path: the descriptor, and with it trigger.ace, is the caller's, as is any PIP type or trust it passes. Every record of kacs_access_check and kacs_access_check_list therefore carries fields.attestation.userspace set to true, with or without an audit context, and a record of a check the kernel makes itself never does. A context that is anything other than this map, such as the free-form strings earlier components passed, fails with EINVAL.

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.
• 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 event is kacs.audit.privilege.used. Its privilege.contributed is provenance & mapped_desired, its privilege.surviving is success_bits (empty on a failure event), and its access.requested and access.granted are the whole check's mapped_desired and final granted, not this privilege's share of them.

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: ramfs, 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.