Peios technical reference

Peios runs Linux applications with little to no modification. The Linux identity APIs — getuid, getgid, getgroups, setuid, setgid, capset, capget, the credential xattr, the credential-bearing socket controls — all continue to work. Many programs built against the Linux ABI need no changes; they call the same syscalls, see the same return values, and observe semantics close enough to Linux that nothing breaks. Some programs need adjustments; a few cannot work at all on Peios without restructuring.

The boundary between "works as-is" and "needs work" comes from a single principle: Peios does not carve out exceptions in the KACS model for Linux compatibility. The compatibility layer is built on top of KACS; it does not bend KACS to fit Linux. When a Linux API can be satisfied by deriving the answer from KACS state — getuid() returns a UID computed from the token — that works cleanly. When a Linux API expects to modify state that KACS owns — setuid() expects to change the kernel's notion of the calling process's identity — the compatibility layer either no-ops (preserving the syscall's contract without actually changing KACS state) or routes the request through KACS-aware mechanisms (and only succeeds when the calling token has the appropriate KACS privileges).

The result is best-effort compatibility. The values Linux APIs return are derived from the KACS model, not parallel to it. The token is the authoritative identity; the Linux credentials are a projection of it. The Linux compatibility layer is the bridge between "what Linux applications expect" and "how Peios actually works" — but it is a bridge that respects KACS at every point. Where a Linux semantic conflicts with KACS, KACS wins; the Linux call gets the closest reasonable approximation.

This page covers the model: how the projection works, what the Linux APIs see, and where the compatibility boundary lies.

The projection model in one sentence #

The token's identity is projected into Linux's UID/GID/capability fields, but only flows that direction — Linux APIs never write back to the token.

A process's primary identity is the user SID on its token. The kernel computes a corresponding UID (via the directory's SID-to-UID mapping) and stores it as part of the token's projection state. When the process calls getuid(), the value returned is the projection. The kernel does not consult the actual cred->uid field that Linux usually uses for this; it consults the token.

The same applies to GID and supplementary GIDs. They are projections from the token, not authoritative on their own.

This is the one-way rule. Token → cred always; cred → token never. There is no API in the compatibility layer that lets Linux semantics override the token. A setuid() call either causes the token to change (via authd, on the rare paths where that is allowed) or does nothing. It does not write a new UID into the token.

What you see vs what counts #

A Linux process running on Peios sees:

• getuid(), getgid() return UID/GID values consistent with the token's projection.
• getgroups() returns supplementary GIDs from the projection.
• stat() on a file returns UID/GID values consistent with the file's owner SID (also projected).
• /proc/<pid>/status shows the token's projected UIDs and capabilities.
• capget() returns the mandatory capability substrate (covered in the capabilities page).

What the kernel actually uses for access decisions is the token, not what getuid() returns. If a process's token has user SID S-1-5-21-...-1001 and that SID projects to UID 1001, then getuid() returns 1001 — but the access check uses the SID. The two values are kept consistent by the projection, but the SID is authoritative.

Tools that work this way include: ls -l, ps, top, who, anything that uses standard POSIX APIs to query identity and ownership. They all see the projection; the underlying KACS state is what actually controls access.

What works, what changes #

A handful of Linux behaviours map cleanly into KACS; others are deliberately redirected. Quick summary:

The pattern: identity-querying APIs see the projection; identity-modifying APIs either no-op (preserving the Linux contract) or are redirected through KACS-aware paths.

Why the compatibility layer exists #

A reasonable question: why bother with Linux compatibility at all? Why not require applications to be rewritten?

The answer is operational: the ecosystem of Linux software is large. Forcing every application to be ported to a Peios-native API surface would be a barrier to adoption that the value of native integration does not justify. The compatibility layer lets most Linux software run with little or no modification.

The cost is the indirection of the projection — every getuid() consults the token rather than cred->uid, every setuid() is interpreted through the privilege model. The cost is small at runtime; the operational benefit is large.

The compatibility layer is not a translation layer. It does not "convert Linux access control to KACS"; KACS is what runs. The compatibility layer is the set of rules that make Linux APIs return sensible values when called on a system whose actual access control is KACS. Where a Linux behaviour cannot be satisfied without compromising KACS, the layer prefers approximation to special-casing — the Linux call returns something reasonable rather than the kernel making a KACS exception. This is why "best-effort" is the right framing: most things work, some things approximate, a few things require the application to be aware of the underlying model.

DAC neutralisation #

A specific aspect of the compatibility layer worth flagging: the kernel sets every process up with a mandatory set of Linux capabilities — CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_CHOWN, CAP_SETUID, CAP_SETGID — that effectively neutralise the legacy Linux DAC checks.

The reason: Linux's traditional DAC (file mode bits, UID/GID checks) would otherwise run before the KACS LSM hooks. A Linux file mode of 400 (read-only by owner) would block a write attempt by a non-owner before KACS could evaluate the DACL. The mandatory capabilities tell the Linux DAC to defer to the LSM layer; KACS then makes the authoritative decision.

This is why the file's mode bits don't enforce access in Peios — DAC is neutralised. The mode is informational (derived from the SD); KACS is the authority.

The capability story is more nuanced than just "neutralise DAC"; it's covered in detail in DAC neutralisation and capabilities.

What about the root user #

A common question: what about root? Linux's root is UID 0; programs that check geteuid() == 0 to detect administrative privilege rely on this. On Peios, who is "root"?

The mapping is:

• The SYSTEM principal (S-1-5-18) projects to UID 0. Processes running on the SYSTEM token see getuid() return 0.
• A user in BUILTIN\Administrators (S-1-5-32-544) projects to their normal UID, typically non-zero. They are administratively privileged in KACS terms but getuid() does not return 0.
• The uid0 utility lets a process with SeAssignPrimaryTokenPrivilege and the right authority cosmetically set its UID to 0 without changing the underlying token. Useful for legacy applications that hard-code geteuid() == 0 checks but where the actual identity should remain non-SYSTEM.

The uid0 mechanism is covered in setuid and uid0. The short version: legacy "is this root?" checks see UID 0 when the calling code has explicitly arranged for them to; otherwise the real projection is what they see.

Where to start #

If you want the projection mechanism in detail — how the token's identity becomes UID/GID values, how the projection handles impersonation, how the kernel maintains consistency — read Credential projection.

If you want the capability story — DAC neutralisation, the 41 Linux capabilities classified, why security_capable() is authoritative — read DAC neutralisation and capabilities.

If you want setuid semantics and the uid0 utility, read setuid and uid0.

If you want peer credentials — SO_PEERCRED, SCM_CREDENTIALS, the rules for migrating Linux services to KACS-aware peer-identity APIs — read Peer credentials.

If you want the map of every Linux IPC mechanism — which carry identity, what protects each object, and the three rules that fall out — read IPC on Peios.

If you want the Linux features that survive only as relics — superseded mechanisms that still work but sit outside Peios's recommended surface, and where to look instead — read Linux relics.

For the merged filesystem used to combine packaged and local directory trees — now covered with the rest of the storage tooling — read StrataFS.

The projection model is straightforward: when authd mints a token, it resolves the user's SID against the directory's SID-to-UID mapping and stores the resulting UID, GID, and supplementary GIDs on the token. These values are the projection — derived from the SID, not parallel to it. From then on, any Linux API that asks "what's this process's UID?" gets the answer from the projection.

The projection is one-way. Token state determines the projection; the projection never determines token state. There is no API that lets a Linux call modify the token through the projection layer; the token is authoritative.

This page covers how the projection is constructed, what Linux APIs see when they consult it, how impersonation changes the visible projection, and the rule that keeps the model consistent.

What's on the token #

Every token carries three projection-related fields:

These fields are set when the token is created. authd reads the user's SID-to-UID mapping from the directory at authentication time, fills in the projection, and includes the values in the wire-format token specification passed to kacs_create_token.

The mapping is per-directory. On a standalone Peios system, loregd's registry holds the mapping; on a domain-joined system, the domain's directory provides it. The same SID can in principle map to different UIDs on different systems if the directories are different, though in practice deployments aim for consistency.

A SID with no mapping (a principal that exists in the directory but has no UID assignment) projects to 65534 — the conventional Linux "nobody" UID. This lets the projection produce a value even when the directory does not have one, while signalling that the principal is unknown to the projection.

What syscalls see #

The standard Linux identity syscalls all return projected values:

The split between getuid (primary) and geteuid (effective) preserves Linux semantics where the two diverge during impersonation-like operations. On Peios, the divergence is when the thread is actually impersonating.

The kernel maintains the synchronisation between token state and these queries automatically. Adjusting privileges, adjusting groups, installing/reverting impersonation — each updates whatever the next getuid()-style call would see.

What impersonation does #

A thread that is currently impersonating has two tokens: its primary and its impersonation. The projection layer follows the effective token (the impersonation, while it's in effect) for geteuid-style queries and the primary for getuid-style queries.

The result:

• Before impersonating: getuid() == geteuid() == projected_uid(primary).
• During impersonation: getuid() == projected_uid(primary), geteuid() == projected_uid(impersonation).
• After reverting: back to the first state.

A program checking "am I running as user X right now?" via geteuid() sees the impersonated user, not the service's own user. A program checking "what's my real identity?" via getuid() sees the service's own user.

This is the standard Linux divergence: real (primary) vs effective (current). Peios preserves it through the projection. A service that captures a client's identity via impersonation and then opens a file as the client sees the file open with the client's projection (which is what allows the open to succeed if the client has access); other Linux calls on the same thread see the same effective identity.

The threads that are not impersonating see only the primary projection. Impersonation is per-thread; the projection is too.

current_fsuid() and the fsuid path #

A subtle case: the Linux kernel internally uses a function called current_fsuid() (and the corresponding current_fsgid()) for file-related credential lookups — file ownership, disk quotas, keyring lookups, NFS credentials. These are different from getuid()/geteuid(); they go through their own code path inside the kernel.

Peios patches current_fsuid() (and its variants) to return the projected UID from the effective token, not from cred->fsuid. This is what makes the projection consistent across all the places the kernel might consult it.

The practical effect: a thread impersonating a client opens a file. The Linux kernel might internally call current_fsuid() to record who created the file in the filesystem's metadata. The patched current_fsuid() returns the impersonated client's UID, so the file appears to be created by the client. This is consistent with the file's owner SID being the client's SID (which KACS would set), and consistent with stat() later returning the client's UID.

Without the patch, current_fsuid() would return cred->fsuid, which might be the service's own UID — and the file's metadata would be inconsistent with the file's actual KACS owner.

Creates through a stacking filesystem #

Reading the projection rather than cred->fsuid has one consequence worth knowing about, because it inverts an assumption the rest of Linux makes.

A stacking filesystem — overlayfs, which the live root is — does not perform a create as the calling process. It switches to the credential it captured when it was mounted, because writing the upper layer needs authority the caller may not have. To keep the new file owned by the caller rather than by the mounter, it assigns the caller's ids to that credential's fsuid and fsgid and lets the underlying filesystem read them back.

On Peios that assignment decides nothing, because current_fsuid() reads the projection instead of the field. The credential the stacking filesystem prepared still carries the mounter's token, so the underlying filesystem would stamp the mounter's ids on every file, whoever created it.

The kernel therefore hands the projection across explicitly, through the dentry_create_files_as LSM hook that exists for this purpose: KACS gives the prepared credential the calling principal's projected ids. Only the projection moves — the token stays the mounter's, which is what the stacking filesystem needs in order to write at all, so no access decision is affected. The descriptor stamped on the new file is computed separately, from the caller's token.

Two things follow. A filesystem that creates under the caller's own credentials, as StrataFS does, needs none of this. And ownership set this way is decided at creation: it is the projection of whoever created the file, captured then, not a value re-derived afterwards.

The one-way rule #

The projection flows token → cred. Never cred → token.

A Linux call that would, on a non-Peios system, modify the kernel's notion of the process's UID is not allowed to modify the token. Specifically:

• setuid() and friends do not modify the token. They either become a no-op (without SeAssignPrimaryTokenPrivilege) or trigger a full identity swap through authd (with the privilege). See setuid and uid0.
• The setuid-on-exec bit (S_ISUID in a file's mode) similarly does not modify the token without the privilege.
• prctl(PR_SET_SECUREBITS) and related operations do not affect the token's projection.

The reason: the token is the authoritative identity. Letting Linux APIs write to it would mean the token's value depends on what Linux code thinks. Peios's model is that the token is decided by authd (at mint time) and adjusted only through KACS APIs (AdjustPrivileges, AdjustGroups, etc.). Linux is a consumer; it does not get to be a producer.

File ownership in stat() #

When stat() returns a file's owner and group, the values come from the file's SD — specifically, the owner SID's projection and the primary group SID's projection.

The flow:

1. The file has an SD with owner_sid = S-1-5-21-...-1001 and group_sid = S-1-5-21-...-513.
2. Each SID is run through the SID-to-UID mapping.
3. stat() returns st_uid = 1001, st_gid = 513.

The values are computed from the SD's SIDs every time, not stored as separate fields. The file's underlying filesystem may have its own i_uid and i_gid fields (ext4 does), but the kernel maintains them consistent with the SD-derived values. A change to the file's owner SID via kacs_set_sd updates the SD and re-derives the projected UIDs, which then become visible to stat().

This consistency is what makes ls -l work. The output shows ownership; the ownership is the projection of the SD; the SD is what KACS evaluates against. The three views agree.

SO_PEERCRED and SCM_CREDENTIALS #

Two Linux APIs let one process learn another's identity over Unix sockets:

• SO_PEERCRED — getsockopt option returning the peer's pid, uid, gid.
• SCM_CREDENTIALS — sendmsg/recvmsg control message allowing the sender to attach (or the receiver to extract) similar credentials.

On Peios, these return the peer's projected UID/GID values. The values are correct in the projection sense — they correspond to the peer's token's projection. But they are not the right tool for security-relevant identity:

• They don't distinguish between an authenticated user and an unauthenticated process running as the same UID.
• They don't carry the token's SIDs, groups, integrity level, or privileges.
• They don't reflect impersonation correctly in all cases.

For security purposes, the right tool is the peer-token socket option, getsockopt(SOL_KACS, KACS_SO_PEER_TOKEN) (peios_token_open_peer in libpeios) — it returns a token fd carrying the full identity. See Peer credentials.

SO_PEERCRED and SCM_CREDENTIALS are kept for compatibility with Linux applications that use them for non-security purposes (logging, debugging, friendly identification). Code that needs to make access decisions on peer identity uses the KACS-aware API.

What the projection is not #

A few clarifications:

• The projection is not the access decision input. KACS uses the token (SIDs, groups, privileges, integrity, PIP); the projection is for Linux API compatibility only. AccessCheck does not consult projected_uid.
• The projection is not historical. A token reflects identity now; if the SID-to-UID mapping changes (rare but possible), existing tokens continue to use their cached projection. New tokens (created after the mapping change) would see the new value. The projection is fixed when the token is minted.
• The projection is not the file system's notion of ownership. ext4 stores i_uid and i_gid; Peios keeps these consistent with the SD's owner-projection, but the SD is authoritative. A file whose i_uid somehow diverges from the SD owner's projection is inconsistent; KACS uses the SD.
• The projection is not a substitute for the token. Code that needs to make security decisions on identity should use the token, not the projection. The projection is for compatibility; the token is for authority.

The cleanest mental model: the projection is the Linux-shaped view of an identity that fundamentally lives in KACS. It exists to satisfy POSIX programs that ask "what's my UID?" and have to get a number back. The number is computed; the actual identity is something else.

Where to go next #

For how Linux's own DAC and capability checks are made to defer to KACS, read DAC neutralisation and capabilities.

For what the setuid family does — and does not do — to the projection, read setuid and uid0.

For the security-grade replacement for projected peer credentials, read Peer credentials.

Linux has its own access-control mechanisms below the LSM layer — DAC (file mode bits, owner/group checks) and capabilities (POSIX-style fine-grained privileges). When Peios's KACS runs as an LSM, it sees an access after these other layers have already had their say. If DAC has already refused the access for legacy reasons, KACS never gets a chance to evaluate.

The fix is DAC neutralisation — Peios sets up every process with a specific set of mandatory Linux capabilities that effectively defer the DAC and capability decisions to the LSM layer. Combined with a classification of the 41 standard Linux capabilities (some always-on, some mapped to KACS privileges, some always-off), this lets KACS be the authoritative access-decision layer.

This page covers the model — what DAC neutralisation is, how it works, and the three-way classification of Linux capabilities.

The problem: DAC runs first #

In a standard Linux kernel, an access proceeds through several layers:

1. The syscall (open, read, etc.) is called.
2. The kernel does its DAC check — file mode bits, owner UID, group GID. If DAC refuses, the syscall fails with EACCES.
3. The kernel does capability checks for operations that require specific capabilities.
4. LSM hooks fire. SELinux, AppArmor, etc. get to make additional decisions.

KACS is an LSM. It fires at step 4. By the time it runs, DAC has already had its say. If a file has mode 400 (read-only by owner), a non-owner attempting to read it gets EACCES from DAC before KACS sees the call. KACS may have a DACL granting the access, but it cannot help — DAC already refused.

The same applies to capabilities. Operations gated by Linux capabilities (CAP_SYS_ADMIN, CAP_NET_BIND_SERVICE, etc.) check the capability at the relevant point. If the process lacks the capability, the operation fails. KACS's privilege model (SeTcbPrivilege, SeDebugPrivilege, etc.) is parallel but separate.

The naive answer would be to remove DAC from the kernel. But that breaks Linux compatibility — applications expect the kernel to enforce mode bits. Peios's answer is more subtle: keep DAC and capabilities, but neutralise them so they always defer to LSM.

The fix: mandatory capabilities #

Every process on a Peios system is set up with a mandatory set of Linux capabilities always present in their effective set:

• CAP_DAC_OVERRIDE — bypass DAC read/write checks.
• CAP_DAC_READ_SEARCH — bypass DAC read/search checks on directories.
• CAP_FOWNER — bypass ownership-based permission checks.
• CAP_CHOWN — bypass restrictions on chown.
• CAP_SETUID — bypass restrictions on setuid.
• CAP_SETGID — bypass restrictions on setgid.

These caps are present on every process's credentials, mandatorily, regardless of what the application's binary or the user requested. They cannot be removed by capset().

Their effect: the DAC layer of the kernel sees these caps and treats the corresponding checks as already-passed. The check proceeds to the LSM layer, where KACS gets to make the actual decision.

This is the "neutralisation". DAC is not gone — the code paths still exist — but it never refuses anything by itself. Every access flows through to KACS.

The same approach is taken for the capability checks: capabilities relevant to access decisions are pre-allowed so the kernel does not stop the operation before LSM gets to see it. KACS then makes the call.

The capability classification #

There are 41 Linux capabilities defined in v0.20 (the standard set from Linux 5.x). Peios classifies each as one of three things:

The classification is per-capability and is hard-coded into the kernel.

ALLOW capabilities #

The DAC-neutralisation set is the core of ALLOW:

These are mandatory. No process can clear them; capset() ignores attempts to remove them.

PRIVILEGE capabilities #

Many Linux capabilities map cleanly to a KACS privilege. Examples:

OR-mapping. Most capabilities map to a single KACS privilege. A small number span multiple Peios privilege tiers, where no single privilege covers everything the Linux capability gates — these OR-map: security_capable() returns granted if the token holds any of the listed privileges. CAP_PERFMON is the current example. The cap_capable() answer is only a ceiling that prevents false denials; the specific privilege for the specific operation is enforced at the relevant syscall hook. For perf, the perf_event_open path distinguishes own-task profiling (no privilege), cross-task profiling (SeProfileSingleProcessPrivilege + PIP dominance), and system-wide profiling (SeSystemProfilePrivilege). OR-mapping never grants authority the holder does not already have via one of the listed privileges.

When the kernel asks "does this caller have CAP_X?", the answer is computed by consulting the token's privileges. The kernel's security_capable() hook is what does this lookup — Peios's PKM module overrides the default capability check to consult KACS privileges instead of (or in addition to) the credential's capability set.

This means a process's Linux-capability state and its KACS-privilege state are kept consistent for the PRIVILEGE-class capabilities. A user with SeSystemtimePrivilege enabled on their token gets the answer "yes" from cap_capable(CAP_SYS_TIME); a user without it gets "no".

DENY capabilities #

A few Linux capabilities have no useful semantics on Peios and are always denied:

These are denied unconditionally. No combination of token state grants them.

security_capable() is authoritative #

The kernel exposes a function security_capable() that callers use to check "is this caller allowed to do the thing this capability gates?". Peios's PKM module hooks this function:

• For ALLOW caps: always returns granted.
• For PRIVILEGE caps: returns granted iff the corresponding KACS privilege is enabled on the calling token.
• For DENY caps: always returns denied.

security_capable() is authoritative. The actual bit state of the credentials (the cap masks visible to capget()) is informational; the security decision comes from security_capable().

Why this matters: a program that reads /proc/self/status sees a capability bitmask. That bitmask is the "what the credentials currently say" view — for compatibility with tools that parse the file. But the kernel's enforcement uses security_capable(), which goes through KACS.

The two views are kept consistent for ALLOW (the bits are always on) and DENY (the bits are always off). For PRIVILEGE, the visible bitmask reflects the KACS privilege state — a privilege enabled on the token corresponds to the cap appearing in the bitmask.

capset() limitations #

capset() lets a process modify its capability set. Under Peios:

• It cannot clear ALLOW bits. Attempts to remove CAP_DAC_OVERRIDE etc. silently leave them set. The process cannot opt out of DAC neutralisation.
• It cannot grant DENY bits. Attempts to add CAP_SETFCAP etc. silently fail (the bit stays clear).
• For PRIVILEGE bits, capset() cannot grant capabilities the corresponding KACS privilege does not provide. A process can drop the bit (which would normally drop the capability), but this does not affect the underlying KACS privilege — the privilege is the source of truth.

The kernel maintains the apparent capability state consistent with the KACS privileges (and the ALLOW/DENY rules). A program using capset() to try to drop privileges sees the visible mask drop, but the underlying KACS state is what security_capable() consults.

prctl(PR_SET_KEEPCAPS) and the secure bits #

A program that does setuid and wants to preserve some capabilities afterward sets PR_SET_KEEPCAPS via prctl(). Under Peios:

• prctl(PR_SET_KEEPCAPS, 1) is accepted but does not change the effective behaviour. The Linux capability state is reset across setuid by default; the KACS token state is unaffected by setuid (unless SeAssignPrimaryTokenPrivilege triggers the full identity swap path).
• prctl(PR_SET_SECUREBITS, ...) is similarly accepted but does not modify the KACS state.

These are operations that affect the Linux credentials view. The KACS authority continues to live on the token.

Capabilities at exec — file capabilities are dead #

Linux supports file-bearing capabilities via the security.capability xattr. A binary with this xattr gets the listed capabilities at exec, regardless of who launched it. This is how (for example) ping gets CAP_NET_RAW on a Linux system.

Under Peios, file capabilities are dead:

• Writing the security.capability xattr is unconditionally denied.
• Existing security.capability xattrs on files are ignored at exec.
• The mechanism's role on Peios is filled by KACS privileges, applied at token creation time by authd.

A binary that needs special capabilities on Peios doesn't carry them as a file xattr. Instead, authd's privilege policy decides which principals get which privileges; the binary running under one of those principals' tokens gets the corresponding KACS privileges naturally.

The capability CAP_SETFCAP (set file capabilities) is in the DENY class as a consequence — there are no file capabilities to set.

What this looks like in practice #

For an application running on Peios:

• Linux DAC checks are invisible. The application's mode-bit-aware code paths work, but the mode bits don't refuse anything. KACS makes the call.
• Capability checks (via security_capable()) return the KACS-derived answer. A process that holds SeSystemtimePrivilege on its token sees CAP_SYS_TIME as granted; one that doesn't sees it as denied.
• capset() does not grant or remove ALLOW/DENY capabilities. The mask returned by capget() is informational.
• File capabilities don't work. Binaries that depended on security.capability need to be run under tokens with the appropriate KACS privileges instead.

For most applications this is transparent. They make their normal calls; the access decisions come out as KACS decides. The exceptions are programs that explicitly manipulate Linux capabilities — a paranoid daemon that calls prctl(PR_CAPBSET_DROP) to drop unneeded capabilities — and these programs see their drops not take effect in the way they expect. Migrating to use KACS privileges via AdjustPrivileges is the right pattern.

Where to go next #

For the projection that feeds getuid and friends, read Credential projection.

For the setuid family's reinterpretation, read setuid and uid0.

For the KACS privileges the PRIVILEGE-class capabilities map to, read Privileges.

The Linux setuid() family of syscalls — setuid, seteuid, setreuid, setresuid, plus the GID variants — is reinterpreted under Peios. Without a specific privilege, calling setuid() succeeds (returns 0) but does not actually change anything. With the privilege, it triggers a full identity swap through authd. The setuid-bit-on-exec mechanism (S_ISUID in a file's mode) follows the same rule.

For legacy programs that check getuid() == 0 to detect administrative privilege, a separate utility — uid0 — provides a cosmetic UID-0 view without actually changing the underlying token. This page covers all three: setuid syscalls, the setuid bit, and uid0.

The setuid syscalls #

The Linux setuid family has several variants:

• setuid(uid_t uid) — set real and effective UIDs to uid.
• seteuid(uid_t euid) — set effective UID to euid.
• setreuid(uid_t ruid, uid_t euid) — set real and effective independently.
• setresuid(uid_t ruid, uid_t euid, uid_t suid) — set real, effective, and saved-set independently.
• Corresponding setgid, setegid, setregid, setresgid for GIDs.

On Linux, these change the kernel's cred->uid (and related fields). The credential is updated; the next getuid() returns the new value.

On Peios, the behaviour depends on whether the calling token holds SeAssignPrimaryTokenPrivilege:

The no-op path is the default. The privileged path is reserved for a narrow set of components — typically authd itself, plus a small number of bootstrap services.

Why no-op without privilege #

A reasonable question: why does setuid succeed but do nothing? Why not just return an error?

The answer is compatibility. Linux programs assume setuid() works in the documented way. A program that does setuid(geteuid()) to "drop" privileges expects success. A setuid(0) followed by setuid(non-root) is a common idiom for "elevate, do work, drop". If setuid simply returned an error, every Linux program that did this would fail on Peios.

By making the call succeed but not change anything, Peios preserves the contract — programs see success — without actually changing the token. The programs continue running on whatever identity they had; the kernel's KACS-level access control is unaffected.

The cost: programs that rely on the post-setuid identity having changed might do incorrect things. A program that drops to a less-privileged UID expecting that to limit it will find that KACS access checks are unaffected, and the process retains whatever access its token had. For most programs this is fine (they're using setuid as defence in depth, and KACS's gates are stricter); for a few it could be surprising.

The escape hatch: a program that genuinely needs to change identity at runtime needs to be running with SeAssignPrimaryTokenPrivilege (so the call actually does something) or to be re-architected to do the identity-swap work via the proper KACS channels (call authd directly, get a token, install it via KACS_IOC_INSTALL).

What the privileged path does #

When the calling token holds SeAssignPrimaryTokenPrivilege and setuid(N) is called, the kernel:

1. Looks up the SID corresponding to UID N (via the directory's reverse mapping).
2. Asks authd to construct a token for that principal.
3. Replaces the calling process's primary token with the new one.
4. Updates the credentials so subsequent getuid() returns N.

The token is genuinely different now. Privileges, groups, integrity level are whatever authd produced for that principal. The previous token is released (its references drop).

This is what login frontends do. A user signs in; the login frontend (running with SeAssignPrimaryTokenPrivilege) calls setuid(target_user); the frontend's token is replaced with the user's token; the rest of the user's session runs as the user.

This is also the path for su and similar utilities — they run with the privilege and use the setuid syscall to actually become a different user.

The privilege is rare #

SeAssignPrimaryTokenPrivilege is held by:

• authd itself (which actually needs it to mint tokens).
• Login frontends that handle user sign-in (sshd, the console login, terminal services).
• A few specific TCB tools that need to launch processes as specific users (peinit at boot, certain administrative utilities).

Ordinary programs do not have it. A user-installed application that calls setuid() falls through to the no-op path.

This is the right distribution: only components that legitimately swap identities have the privilege. Everything else gets the compatibility behaviour.

The setuid bit on exec #

A file with S_ISUID set in its mode runs as the file's owner when exec'd (on Linux). The setuid bit is what makes ping run as root, makes passwd able to modify /etc/shadow, makes sudo work.

On Peios, the setuid bit's behaviour mirrors the setuid syscall:

The cosmetic-only path is what most setuid-bit binaries get on Peios. The binary runs as the user who invoked it; the euid that geteuid() returns is the binary's owner; KACS sees no identity change.

For most uses this is correct. A setuid-root binary on a Linux system that just wants to do "is the caller root?" check sees geteuid() == 0 even on Peios; the cosmetic euid update is enough for that.

For uses that actually need to perform privileged operations on the user's behalf, the cosmetic-only path is insufficient. The KACS access control sees the calling user, not the binary's owner. The binary fails its access checks. The fix is to either:

• Run the binary as a service launched by peinit with the appropriate token.
• Have the binary connect to a service (running with the appropriate identity) and ask the service to do the work.

This is the pattern for "privileged operations" on Peios. Rather than setuid-bit binaries, services run with the right token; clients connect to the services and ask for what they need.

The setuid-bit-as-identity-swap path (with SeAssignPrimaryTokenPrivilege) exists for compatibility with tooling that genuinely needs it — but it requires the parent process to hold the privilege.

uid0 — cosmetic root for legacy programs #

A specific class of legacy programs hard-code getuid() == 0 (or geteuid() == 0) checks to detect root and refuse to run otherwise. The programs may have legitimate logic that requires elevated privileges, or they may just be checking out of paranoia.

For these programs, Peios provides the uid0 utility. It is a small wrapper that:

1. Runs as a user with SeAssignPrimaryTokenPrivilege (or chains through one).
2. Sets the calling credentials' cred->uid, cred->euid, and cred->suid all to 0.
3. Execs the target binary.

The result: the target binary sees getuid() == 0, satisfies its root check, and proceeds.

Crucially, uid0 does not change the KACS token. The current_fsuid() patch (from Credential projection) ensures that file-related credential lookups still return the projected UID from the token — not the cosmetic 0. So uid0 is purely a cosmetic adjustment for legacy "am I root?" checks; it doesn't grant any actual privileges or change the security-relevant identity.

The use case: a legacy script that does [ $(id -u) -eq 0 ] || exit 1 at the top. The script's actual work might be perfectly fine to run as the calling user, but the check refuses. uid0 makes the check pass.

The uid0 utility itself is signed and runs with the appropriate privilege; an ordinary user invoking uid0 does not gain root authority — they gain a cosmetic UID-0 view for the duration of the wrapped program. The KACS token is unchanged; the access decisions still flow through KACS.

This is the right way to handle the "is root?" check pattern. The check is satisfied; the actual authority comes from KACS; the legacy code path works.

Comparison: setuid syscall, setuid bit, uid0 #

A handy summary:

The pattern: real identity changes are gated by the privilege and go through authd. Cosmetic changes (for legacy compatibility) don't require the privilege and don't touch the token.

What setuid semantics are not #

A few clarifications:

• They are not a way to elevate privilege. A program calling setuid(0) without the privilege does not gain root authority — the call is a no-op. To genuinely gain authority, you need a different token, which requires authd.
• They are not the way Peios changes identity. The setuid syscall is a compatibility layer. The native way to change identity is to be assigned a different token by authd (typically through a re-authentication or through being launched with a specific token by peinit).
• They are not bypass mechanisms for KACS. Whatever the setuid syscall does, the KACS access checks continue to operate against the token. There is no setuid combination that gets around a DACL.
• They are not how login frontends actually work. Login frontends do use setuid() (with the privilege), but the actual identity-establishment work is in authd — minting the token, setting up the session, applying the privileges and claims. The setuid() call is the final step that installs the result on the calling process.

The cleanest mental model: setuid is a Linux-compatibility veneer on the actual Peios identity machinery. The veneer is enough for legacy programs to think they're operating on Linux; the actual identity changes (when they happen) go through authd.

Migrating away from setuid #

For new code or refactored services, the cleaner pattern is to avoid setuid entirely:

• Services should be launched with the right token from the start. peinit fork-installs the correct token before exec; the service never needs to setuid.
• User-facing operations should be done as the user, not via setuid-to-root. Impersonation (capturing the user's token via peer-token capture) is the right pattern — the service can act on the user's behalf without changing its own identity.
• Cross-identity work happens through IPC. A service needing to do something as another identity sends an IPC request to a service running with that identity; the latter does the work.

Setuid is the legacy compatibility path. Native Peios code paths look different.

Where to go next #

For the projection behind the cosmetic UID values, read Credential projection.

For why setuid's Linux-level checks defer to KACS in the first place, read DAC neutralisation and capabilities.

For acting on another identity without changing your own, read Peer credentials.

When one process connects to another over a Unix socket, the recipient often wants to know who is connecting. Linux provides two mechanisms for this — SO_PEERCRED (a socket option) and SCM_CREDENTIALS (a control message). Both return basic credential information about the peer.

On Peios, both continue to work and return projected UID/GID values — useful for compatibility with Linux applications, but insufficient for making security decisions. For services that need to authenticate the connecting peer's identity to decide access, the right tool is the KACS peer-token socket option, getsockopt(SOL_KACS, KACS_SO_PEER_TOKEN), which returns a full KACS token reflecting the peer's complete identity.

This page covers the two Linux mechanisms and the right replacement.

SO_PEERCRED #

SO_PEERCRED is a getsockopt option on a connected Unix socket. The caller queries the socket and gets back a struct ucred:

struct ucred {
    pid_t pid;
    uid_t uid;
    gid_t gid;
};

The fields are:

• pid — the connecting peer's PID at connect time.
• uid — the projected UID of the peer's effective token at connect time.
• gid — the projected GID similarly.

On Peios, the projection is computed from the token at the moment the connection was made. If the peer was impersonating at connect, the projected UID is the impersonated client's. If not, it's the peer's own.

The values are stable for the life of the socket. If the peer changes identity later (impersonation install/revert, token adjustment), the values returned by SO_PEERCRED do not update.

What SO_PEERCRED does not capture #

The struct ucred is fundamentally lossy. It returns three numbers — pid, uid, gid. It does not return:

• Group memberships beyond the primary GID.
• Privileges.
• Integrity level.
• PIP fields.
• Claims (user or device).
• The session ID.
• Whether the connecting principal is authenticated, anonymous, or somewhere in between.
• The token's restricted-SID list, confinement state, audit policy, or any other non-trivial structure.

For most security purposes, the missing information matters more than what's present. A service that grants access based on UID does not distinguish "user 1001 connecting as their normal Medium-integrity session" from "user 1001 connecting from a Low-integrity sandbox where they shouldn't be doing this". The UID is the same; KACS treats the two cases differently; SO_PEERCRED cannot tell them apart.

What SO_PEERCRED is for #

SO_PEERCRED is useful for:

• Logging. "Connection from PID 12345 (UID 1001) at time T". This is a friendly identification, not a security claim.
• Display. A daemon that wants to show "currently connected user: bob" can use the projected UID to look up the name.
• Coarse compatibility. Linux applications that already use SO_PEERCRED for their own non-security checks continue to work.

For security purposes, it is the wrong tool. The information is too coarse; the connection between projected UID and authoritative identity is too easy to misread.

SCM_CREDENTIALS #

SCM_CREDENTIALS is a control message used with sendmsg/recvmsg on Unix sockets (including datagram sockets where SO_PEERCRED doesn't apply). The sender attaches a struct ucred to a message; the receiver extracts it.

On Linux, the sender can attach any struct ucred they like (subject to capability checks if the values would be different from their actual credentials). Peios projects the same way:

• The sender's projected UID/GID is attached to the message.
• The receiver can extract it via the control-message API.

The same caveats as SO_PEERCRED apply: the projected values do not carry the full identity, do not survive non-trivial state changes, and should not be used for security decisions.

SCM_CREDENTIALS is the way to attach credential info to datagram messages or socketpair-style sockets, where there is no "connect time" to capture peer info at.

Why these are insufficient for security #

The fundamental issue: the projection is for compatibility, not authority. UID 1001 corresponds to a SID, and that SID is what KACS uses for access decisions — but the projection doesn't carry the SID. It carries the projected UID, which is a derived value. A service that grants access based on the projected UID is making a decision based on a derivation, not the source of truth.

In practice, this leads to two classes of issue:

Identity collisions. Two different principals can in principle project to the same UID. The SID-to-UID mapping is typically 1-to-1, but reasonable failure modes (a misconfigured directory, a colliding mapping during a migration) can produce collisions. KACS sees them as different; UID-based code sees them as the same.

State that doesn't project. A token's integrity level, PIP, privileges, restricted-SID status — none of these project to UID/GID. A service that does "if the UID is admin's UID, grant access" cannot tell that the calling process is running on a restricted token with admin's SID but no actual privileges. KACS would deny most accesses; the UID-only check would grant them.

For services that need to be secure, neither SO_PEERCRED nor SCM_CREDENTIALS is the right tool. The right tool is the KACS-aware peer-token mechanism.

The replacement: the peer-token socket option #

The KACS-native equivalent is a socket option on the same connection, under the SOL_KACS option level:

int token_fd;
socklen_t len = sizeof token_fd;
getsockopt(socket_fd, SOL_KACS, KACS_SO_PEER_TOKEN, &token_fd, &len);

libpeios wraps it as peios_token_open_peer(socket_fd), which returns the fd directly. The call

Returns a token fd reflecting the peer's complete identity at connect time. The fd carries TOKEN_QUERY | TOKEN_IMPERSONATE | TOKEN_DUPLICATE access — enough to inspect the token's full state, to install it as an impersonation token, and to duplicate it.

What the token includes:

• The peer's user SID, group SIDs (with attributes), restricted SIDs, logon SID.
• Their integrity level, mandatory_policy, PIP type and trust.
• Their privileges (present, enabled, used, removed states).
• Their confinement state (sid, capabilities, exempt).
• Their session reference (auth_id).
• Their claims (user and device).
• Their default DACL, owner index, primary group index.
• Their projected UID/GID (for completeness — the same values SO_PEERCRED would have returned).

Everything. The full identity, atomic, captured at connect time. From the receiver's perspective, this token is what KACS would have access-decided against if the peer had made the request directly.

The service can:

• Inspect the token (via KACS_IOC_QUERY) to make authorisation decisions on real identity, not projected UID.
• Impersonate the peer (via KACS_IOC_IMPERSONATE on the fd, or the fused peios_token_impersonate_peer) to perform operations on their behalf — with the just-in-time pattern from Peer tokens and capture.

This is the security-grade peer-identity API. For services that need real access control on connecting peers, this is the tool.

When to use which #

A handful of guidelines:

The pattern: compatibility-grade peer ID uses the Linux APIs; security-grade peer ID uses the KACS APIs. The distinction matters most for services that handle untrusted callers — a public-facing daemon should use KACS_SO_PEER_TOKEN; an internal diagnostic tool can use SO_PEERCRED.

What about TCP sockets #

Linux's SO_PEERCRED does not work on TCP sockets — the peer is potentially remote, and there's no kernel-side credential to query. The same is true on Peios: KACS does not capture peer tokens over TCP. The peer is whatever the network layer says it is, identified by IP / connection state, not by a token.

For services accepting TCP connections from authenticated peers, the authentication is at a different layer — TLS with mutual certificates, Kerberos via authd, application-layer protocols. The result of that authentication is what determines the connecting principal's identity; the kernel-level peer-credential APIs are not involved.

Once authentication has produced a token (typically by authd), the service can install that token as an impersonation token via the normal KACS_IOC_IMPERSONATE path. The token-installation API is uniform regardless of whether the token came from a Unix-socket peer or a TCP-authenticated session.

What goes wrong if you use the wrong tool #

A few concrete failure modes from using SO_PEERCRED for security:

• Sandbox bypass. A user runs a sandboxed application that connects to a privileged daemon. The application's token has the user's SID (restricted, with privileges removed). The daemon does SO_PEERCRED, sees UID 1001, looks the user up, sees they're in the administrators group, grants admin access. The sandbox is bypassed — KACS would have refused based on the restricted token, but the daemon never asked KACS.
• Impersonation confusion. A service that connects to another service while impersonating a client should appear (to the receiver) as the client. With SO_PEERCRED, the receiver sees the client's projected UID — correct in this case. But if the impersonation changed mid-session (the service reverted, then made another call), SO_PEERCRED still shows the original peer's UID. The receiver can be confused about who they're actually serving.
• Identity not present in projection. A service that wants to make decisions based on the peer's integrity level cannot — there's no projection for it. A SO_PEERCRED-using service sees nothing about integrity; the call effectively ignores that axis of access control.

For each of these, the peer token would produce the correct result because it carries the full identity. The migration path for an existing service is: replace SO_PEERCRED with KACS_SO_PEER_TOKEN on the same socket, use the token to make decisions instead of the projected UID. The code surface changes; the semantic is more accurate.

Compatibility, not removal #

SO_PEERCRED and SCM_CREDENTIALS are not being removed. They continue to work with sensible semantics for compatibility with Linux software. The recommendation is to migrate security-sensitive code to KACS-aware APIs, not to deprecate the Linux APIs.

For most services this means: keep the Linux API for friendly identification; add KACS-aware logic for access decisions. Both can coexist on the same connection; the security paths use the KACS-aware data, the diagnostic paths use the Linux API.

Where to go next #

For how the projected UID/GID values are computed, read Credential projection.

For capturing and impersonating a peer's full token, read Peer tokens and capture.

For what a token carries that a struct ucred cannot, read Tokens.

A handful of Linux features are relics: they still exist and still work the way they do on Linux — so software depending on them keeps running — but they have been superseded and are not part of how anything is meant to be done on Peios. Peios does not document them in depth. For the mechanics of the underlying Linux feature, the authoritative source is third-party Linux documentation (the relevant man pages and the kernel's own docs). Where Peios has a native replacement for what the relic was used for, this page points to it — that, not the relic, is the path to take.

A feature belongs here only if it is genuinely superseded, has no role in Peios's future, and gives essentially no reason to reach for it. This is a short list by design, not a place to park anything inconvenient to document.

Process accounting (acct) #

acct() is BSD process accounting. Called with a filename it turns on system-wide accounting, appending a fixed binary record for every process as it terminates — resource usage, timing, exit status, and a few behaviour flags; called with no argument it turns accounting off. Enabling or disabling it requires SeTcbPrivilege (the privilege Linux's CAP_SYS_PACCT maps to). For the record format and per-field detail, see the Linux acct(2) and acct(5) documentation.

On Peios you almost certainly want eventd and KMES instead: process lifecycle is already an event stream there, keyed on each process's GUID and carrying its real identity, exit status, and resource usage — structured and queryable, where acct produces an opaque append-only file built around the Linux UID model. See the eventd and KMES material for the native way to account for what processes do.

Where to go next #

For the compatibility model that decides what survives and how, read Linux compatibility.

For the native event pipeline that replaces process accounting, read Events and transport.

For following that event stream from the command line, read The event stream.

A Linux program calls getpwuid and has never heard of a token. Between that call and the authority sits one shared object:

/usr/lib/libnss_peios.so.2

It asks authd over /run/ident.sock and renders the answer as a struct passwd.

There is nothing to configure #

On other systems /etc/nsswitch.conf decides where identity comes from. On Peios it does not, for passwd, group, shadow or initgroups. glibc is patched so those four reach the authority and nothing else, whatever any file says.

That is not tidiness. A second search order the authority cannot see is a second answer to the question who is jack, and a program acting on one principal's behalf while its access is checked against another is a confused-deputy bug rather than a cosmetic inconsistency. The authority resolves a name across the principal sources it is configured to have, in a configured order, applying domain and numeric confinement — none of which nsswitch.conf can express, and all of which a line in it would bypass.

It also closes an extension point Peios does not want. Naming a module in nsswitch.conf injects a shared object into every address space on the system. That is the in-process-plugin pattern this design rejects everywhere else it appears. Adding a source of identity to a Peios machine means writing a principal source — a separate process the authority confines, which cannot mint.

hosts is fixed the same way, for the same reason, to a different module: libnss_peios_net.so.2, which forwards to resolvd, the stub resolver. A files dns line would be a second resolver with none of resolvd's routing — and a second answer to which address is git.corp. There is no /etc/hosts; static names live in the registry and resolvd answers them at every door. See name resolution. services, networks and the rest are untouched.

Certificates are not in a directory you write to #

The same shape appears again for TLS trust, and for the same reason. Other systems have update-ca-certificates and a directory to drop a .crt into; Peios has neither. What the machine trusts is composed by trustd from the roots the ca-certificates package ships and the decisions under Machine\System\Trust, and rendered to /etc/ssl.

So /etc/ssl/certs/ca-certificates.crt, /etc/ssl/cert.pem and the hashed /etc/ssl/certs/ directory all exist and hold what you would expect — OpenSSL, curl, Go and Python find them where they look — but they are generated. Adding a certificate to one of them lasts until the next change and no longer. trust add writes the registry instead, where the question "who may widen what this machine trusts" is an access check rather than a matter of who can write to a directory.

There is no /etc/passwd #

No files entry, and nothing behind the authority to fall back to.

There is no root to hold there. uid 0 is where the SYSTEM token projects, not an account — nothing on the system looks for a principal called root, and peinit projects SYSTEM itself without resolving anything. A flat file of accounts would be a second identity store with none of the confinement the real one has, holding entries for principals that do not exist.

shadow and gshadow return nothing, always. A Peios verifier lives in its source's store and cannot be read out at all, so there is no entry to return and never will be.

PAM does not exist on Peios. There is no libpam, no /etc/pam.d, and no stack to configure. Authentication goes through PGSS Logon, where a client collects what it is asked for and an authority decides — and the module-stacking model PAM is built on is the same one the paragraph above rejects.

Before the authority, nothing resolves #

Anything running before authd — peinit, an initramfs — gets numbers rather than names.

That is the correct answer rather than a gap. Identity comes from the authority; until it exists there is none to have, and a file that answered anyway would be answering for principals nobody had vouched for.

One call, one round trip #

The module holds itself to a rule: each libc call costs exactly one request.

• getpwuid asks for the six fields a passwd record needs, together.
• getgrnam asks for the group's members with their names already resolved, so filling gr_mem costs nothing further. A reply of bare identifiers would have turned one call into one per member.
• initgroups asks about the principal, which is the direction sources actually store memberships — it never walks a group's membership to get there.

It opens a connection per call rather than holding one. A shared object cannot see its process fork, and a connection inherited by a child that then interleaves requests on it with its parent is a well-known way for a name resolver to hand back somebody else's answer. Connecting to a Unix socket is cheap; the caching that would be cheaper belongs in the authority, where every process shares it and something can tell it when it goes stale.

What the return values mean #

The third row is the one that matters. A source that could have answered and did not is not the same as an account that does not exist, and reporting it as one would let an outage be remembered as a fact — the account comes back when the source does, but a cached "no such user" would not.

What POSIX cannot express #

The rendering is one-directional and lossy, and each loss is a property of struct passwd rather than of anything underneath it.

No claims. A principal's claims feed conditional ACEs and have no field in a passwd record. Peios-native tools see them; getpwnam does not.

No domain. A uid_t is a number. Which source and which domain it came from is recoverable — the ranges are laid out so it is — but nothing in the record carries it.

Empty member lists. gr_mem for Everyone is empty, because nothing records who is in Everyone; the authority adds it to every token it mints. Inventing a list of this machine's principals would be a wrong answer rather than a partial one. See resolving names for the three kinds of membership and which of them can be listed.

Unnumbered groups are skipped. Interactive and its siblings have no POSIX group id, because membership in them is a property of a session rather than of an account. They are omitted from a supplementary group list rather than rendered as nobody, which would grant whatever nobody can reach.

getent and the whole list #

getent passwd works, and pages through every source in turn.

A source is never required to enumerate — a directory able to answer any single question may be quite unable to answer all of them — so a listing can legitimately be partial. The authority records which sources did not contribute; a Peios-native tool can show that, though getent itself has nowhere to put it.

System V IPC — msgget, shmget, semget and the operations on the objects they create — keeps working on Peios exactly as Linux software expects, with one change to who is allowed to do what: every SysV object carries a security descriptor, and that descriptor, not the object's nine-bit mode, decides access.

What you get by default #

When a process creates a queue, segment or semaphore array, KACS stamps it with a descriptor built from the creator's token: the creator's user, Administrators and SYSTEM get full control; nobody else gets anything. Two consequences fall out that Linux does not give you:

• A sandboxed process (a restricted token) cannot reach segments its parent created, even though the projected UID is the same — the restricted-SID pass fails, as it would for a file.
• A different user is denied outright, with no way to loosen it through chmod-style mode bits. To share, edit the descriptor.

Mode bits are informational #

IPC_SET still updates the object's uid, gid and mode, and ipcs and IPC_STAT still show them — but nothing consults them for access, exactly as file mode bits work under FACS. IPC_SET itself needs WRITE_DAC and WRITE_OWNER on the descriptor (one command changes all three fields), on top of Linux's own rule that the caller be the creator or owner or hold SeTcbPrivilege.

Reading and changing the descriptor #

A SysV object has no path and no descriptor number, so the SD calls address it by kind and id: pass KACS_SD_AT_SYSV_SHM, KACS_SD_AT_SYSV_MSG or KACS_SD_AT_SYSV_SEM in the flags of kacs_get_sd / kacs_set_sd (peios_sysv_get_sd / peios_sysv_set_sd in libpeios, file::sysv_get_sd / sysv_set_sd in the Rust crate), the object id where a directory fd would go, and no path. The rights are in Peios Kernel TRM §3.11; the descriptor format is the ordinary one.

The key is not protected #

The descriptor protects the object once it exists. It cannot protect the name: keys are first-come, and a process that creates key 0x5432 before your service does owns whatever your service then finds there. This is the same trap as the abstract socket namespace and /dev/shm. Create with IPC_EXCL and treat failure as a signal — and if what you actually need is to know who sent a message, use a Unix socket, which carries the sender's identity; a message queue carries only bytes.

Where to go next #

For how DAC is switched off so that descriptors always decide, read DAC neutralisation and capabilities.

For the descriptor format and how to write one, read Security descriptors.

Peios does not add IPC primitives: Linux's are the substrate. What it adds is a consistent answer, for each of them, to two questions that Linux mostly leaves to convention — whose identity, if any, does a message carry, and what decides who may use the object. This page is the map. The rule of thumb it boils down to: identity travels only where one kernel sees both ends and the channel can carry an attested token; everything else is protected as an object, with a security descriptor, and conveys no identity at all.

Identity flows over Unix sockets, and nowhere else #

AF_UNIX is where identity lives. Every connection end has a conveyed-identity register: initialised when the connection is made — the accepted end sees the client, the connecting end sees the listener — and advanced by tokens attached in-band as the reader's position passes them. KACS_SO_PEER_TOKEN reads the register; KACS_SCM_TOKEN attaches a token to a send, gated exactly as impersonation would be; KACS_SO_PASS_TOKEN automates that on the sender's side; KACS_SO_IMPERSONATION_LEVEL bounds what the other end may do with what it receives. Stream and seqpacket sockets carry the register; datagram sockets carry identity per message only; a socketpair() starts with an empty register until one side conveys something. Peer tokens covers the programming model and Peer credentials the migration from SO_PEERCRED.

That is the whole list. In particular:

• TCP and UDP, loopback included carry no kernel-attested identity: the kernel attests only what it saw both ends of, and the other end of a network socket is a claim. Cross-machine identity is authd's job, and the token it produces re-enters through the ordinary install path.
• Netlink needs nothing: kernel-bound requests run synchronously in the sender's context, and the capability checks on both the socket's opener and the sender go through the capability switchboard, so they are already token decisions (Peios Kernel TRM §3.10.4).
• AF_VSOCK spans two kernels; process identity across it is a claim, not an attestation.
• Pipes and FIFOs carry no identity, structurally: there is no ancillary channel, and with several writers there is no "whose bytes". Linux has none either, so nothing is lost — but note the trap below.
• System V and POSIX queues deliver bytes and a type. SI_MESGQ and ucred-style crumbs carry projected values and are informational.
• Signals name a sender by projected si_pid/si_uid; the decision to deliver was made on the token (Peios Kernel TRM §3.7), the crumb is not evidence.

Everything is an object with a descriptor #

Where no identity flows, a descriptor decides who may use the thing, exactly as for a file:

Descriptor passing (SCM_RIGHTS) is untouched: it moves descriptors, and a token descriptor riding it is delegation — the receiver gets a handle — as distinct from KACS_SCM_TOKEN, which is attestation of who sent the bytes.

Three rules that fall out #

A FIFO is not a named pipe. NT programs use named pipes for identity-carrying request/response with impersonation. The Linux object with that name — a FIFO — carries no identity and cannot; porting that pattern means an AF_UNIX socket with KACS_SO_PEER_TOKEN, never a FIFO.

A name you did not create is not evidence. Abstract socket names, System V keys, and entries under /dev/shm and /dev/mqueue are claim-on-create: whoever gets there first owns the object, and the descriptor then protects the object — not the name. Peios-native services bind filesystem paths in directories they own and clients authenticate the peer, not the name; anyone using a first-come namespace creates with an exclusive flag and treats failure as a signal, not a retry.

Revocation does not reach established mappings. Editing a descriptor narrows future opens; it cannot take pages back from a process that has already mapped them. If that matters, replace the file instead of editing it, or end the process. The general form of this rule — decisions are made when a handle is created — is in Access decisions.

Where to go next #

For the socket options and the register in detail, read Peer tokens.

For how System V objects get and expose their descriptors, read System V IPC.

Many devices carry no firmware of their own: the driver has to upload a vendor-supplied blob into the device before it does anything. Almost every Wi-Fi adapter works this way, as do modern GPUs (AMD, Intel, NVIDIA), many Ethernet controllers, laptop audio codecs and amplifiers, and Bluetooth. Without the blob the driver loads, finds the device, asks the kernel for a file under /usr/lib/firmware/, and — if it is not there — gives up. The symptom is a device that is present (lspci lists it, the module is loaded) but never comes up, and a line in dmesg like firmware: failed to load iwlwifi-so-a0-gf-a0-89.ucode (-2).

The kernel loads firmware itself. There is no daemon and no udev step involved: the driver's request is answered from the filesystem, transparently decompressing the .zst files Peios ships. That makes firmware a packaging matter — the right file in the right place — and this page is about which package that is.

The org.kernel.linux-firmware-<family> packages #

Upstream collects device firmware in one tree, linux-firmware, which is over a gigabyte and mostly for hardware Peios does not run on. Peios does not ship it whole. One recipe builds it into packages by vendor or driver family, each carrying only that family's blobs and only that family's licence texts:

The names are the canonical reverse-DNS ones. Each package also provides the shorter firmware-<family> name it shipped under first, so an image manifest or an install command written against firmware-iwlwifi still resolves; that is a migration capability, not a second package.

Which ones a machine needs is a question about its hardware, and the answer is usually two or three: an Intel laptop wants org.kernel.linux-firmware-iwlwifi, org.kernel.linux-firmware-intel-graphics, org.kernel.linux-firmware-intel-platform (Bluetooth), org.sofproject.sof-firmware (audio DSP) and org.kernel.linux-firmware-audio-codecs; an AMD one swaps the graphics and platform packages. dmesg | grep firmware after boot names every file a driver asked for and did not get, and the file's directory (intel/, amdgpu/, rtw89/) maps onto the table.

Every package installs under /usr/lib/firmware/, which is where the kernel looks (it reads /lib/firmware, and /lib is a view of /usr/lib). The blobs are zstd-compressed on disk; the kernel decompresses them on load and no tool needs to know.

Licensing, and license_class = "firmware" #

Firmware blobs are almost never free software. Vendors permit redistribution of the unmodified binary and nothing more, each under their own terms, and there is no source. Peios does not pretend otherwise: each org.kernel.linux-firmware-<family> package declares its vendor licences as LicenseRef- SPDX identifiers and carries license_class = "firmware" in its manifest.

The licences come from upstream's WHENCE manifest, file by file. Each package's SPDX expression is derived from exactly the licences its own files cite, vendor terms and the GPL, MIT or Apache texts a few blobs are under alike. Those texts are shipped under /usr/share/licenses/org.kernel.linux-firmware-<family>/, together with a WHENCE excerpt: upstream's own licence statements and copyright notices for every entry the package draws on, verbatim. Where upstream hedges ("Allegedly GPL, but no source visible"), the excerpt keeps that wording rather than stating more than upstream does.

That class is the machine-readable fact. peipkg info org.kernel.linux-firmware-iwlwifi shows it, a composed image's /usr/share/licenses.json lists it for every package, and it is what lets a tool answer "what non-free is on this machine" without parsing licence expressions. firmware is a class of its own — distinct from proprietary — because it is a different bargain: it does not run on the CPU, it is needed to use hardware you already own, and you cannot get it any other way. Peios ships firmware and does not ship proprietary userspace; the class is how an image policy can say exactly that.

Trust #

Firmware runs on a device that can DMA into host memory, so a tampered blob is a compromise of the whole system — at least as bad as an unsigned binary running with kernel privilege, and it happens without an exec for the kernel to intercept. Peios treats firmware as part of the trusted computing base and signs it the same way it signs TCB binaries.

Every blob in every org.kernel.linux-firmware-<family> package carries an ML-DSA-65 signature made with the TCB key when the package is built. Blobs are not ELF, so the signature travels as a <blob>.peios.sig entry beside the blob in the package, and peipkg turns it into the file's security.peios.sig extended attribute as it installs the blob (see Signature format). The kernel verifies that attribute every time a driver asks for firmware, on the exact bytes it is about to hand to the device, and refuses a file that is unsigned, altered, or signed with a key below the TCB tier. The signature covers the compressed .zst bytes as they sit on disk, so verification happens before decompression.

In 2026.8 the check runs in log mode: a file that would be refused is reported to the kernel log and still loaded, so a system can be brought up on a mixed firmware set and the gaps found. Refusal becomes the default in the release after the whole farm has shipped signed; until then kacs_fwsig=enforce on the kernel command line turns it on for a boot, and kacs_fwsig=log turns it back off. Either way, /usr/lib/firmware is not a place to put files by hand: an unsigned blob dropped there, or one placed on a path added to the loader's search list, is exactly what the check exists to catch.

What is not shipped #

The upstream tree also carries firmware for ARM SoCs (Qualcomm, MediaTek video processors, Rockchip, Amlogic, NXP i.MX), datacentre switches and SmartNICs (Mellanox, Netronome), InfiniBand and crypto accelerators. None of it is packaged: Peios is x86-64, and a family is only added when there is hardware to use it. CPU microcode is a separate mechanism entirely — intel-ucode and com.amd.amd-ucode are early-loaded from the initramfs before the firmware loader exists.

Nothing under /usr/lib/firmware is needed to reach a root filesystem (NVMe, AHCI, USB and virtio storage need no blobs), so the initramfs carries no firmware. A driver that probes in the initramfs and cannot find its blob is re-probed once the real root is mounted and the device manager replays device events.

Intel Sound Open Firmware is not in linux-firmware at all; it is a separate upstream (thesofproject's sof-bin), which is why it is its own package, org.sofproject.sof-firmware, rather than a family of the linux-firmware recipe. The old firmware-intel-sof name remains a migration capability, not the package's canonical identity. Only the Intel-signed images ship — the community builds signed with the public development key run only on Chromebooks and development boards whose DSPs accept that key. Install org.sofproject.sof-firmware-debug separately when DSP debugging tools need the much less commonly used .ldc data.

This document defines how the technical documents of Peios are written and how they are read. It governs two classes of document:

• the specifications of this anthology — the four books that state what must be true for a Peios system and for the parties that interoperate with one; and
• the technical reference manuals — the per-component books that describe exhaustively how one piece of Peios actually behaves.

It covers normative language, the structure a document of each class takes, how any part of either is cited, and the style rules both share.

1.1.1 What this document does not cover #

• Task documentation — the tutorial and how-to material written for people using or building on Peios. That has its own house style, maintained separately, and neither the normative apparatus of a specification nor the exhaustiveness of a reference manual applies to it.
• Any behaviour of Peios itself. Nothing here specifies what a Peios system does. This document constrains documents.
• The renderer. The static site generator that builds these books supplies the chapter and article numbering this document's addressing scheme relies on, and is specified separately.
• Editorial process. How a document is reviewed, by whom, and when it is considered ready are project conventions rather than document conventions.

1.1.2 Position in the anthology #

This document sits ahead of the four specification books because it is read first. It is not itself a specification: it defines no Peios behaviour, and no implementation conforms to it. What conforms to it are documents.

Every technical document in this corpus is either a specification or a technical reference manual, and the difference is not a matter of subject, length, or tone. It is a matter of how many independently written parties have to reproduce the same computation in order to agree.

• If one party computes something and everyone else calls it, that is a manual.
• If a second party must reproduce it identically, or the two produce divergent results, that is a specification.

1.2.1 The sharper form of the test #

A third party wanting to interact with something directly is necessary but not sufficient. What makes something a specification is a second role — a party whose behaviour the other side depends on.

A system-call surface has no second role. It has callers, and callers are documented rather than specified. The question that settles it is which party is asking: a registry source answers the kernel's questions, and a package producer emits what a consumer validates, so both of those are specifications. Nobody serves mount(2), so that is a manual.

1.2.2 Most subsystems split #

The expected outcome for any given subsystem is both: a specification stating the contract, and a manual covering the nuances of how one implementation fulfils it.

Binary signing is a specification because a third party can sign binaries; the kernel's verification machinery behind it is a manual. Security descriptor inheritance is a specification even though there is one kernel, because the kernel does not propagate a descriptor change and every userspace tool that propagates one has to agree. A package's manifest schema is a specification; how a package manager decides which of several candidates to install is a manual.

A subsystem whose only external surface is its own syscalls contributes no specification at all, and that is a legitimate outcome rather than an oversight.

1.2.3 Consequences for the reader #

A specification tells you what you may rely on. Its statements are commitments, and an implementation that contradicts one has a defect.

A manual tells you what a component does. Its authority comes from the software: where the two disagree, the software is right and the manual is stale. A manual makes no stability commitment, and nothing in one is a promise about a future version.

That difference is why the two classes are written so differently, and why a reader must be able to tell at a glance which one is in front of them (§4.2).

1.3.1 Normative keywords #

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119. Their meaning within a specification is defined in §2.1.

Text set off as a note is informative.

1.3.2 The two halves carry different weight, deliberately #

Chapters 2 and 3 govern specifications and are normative throughout. A specification that violates one of their requirements is malformed, and the requirement is stated as such.

Chapter 4 governs technical reference manuals and is deliberately lighter. Most of it is SHOULD and MAY, and some of it is offered as guidance carrying no normative weight at all. A manual is a description of software rather than a contract, so prescribing its shape tightly would be prescribing the shape of the software.

Two rules in chapter 4 are exceptions and are stated as MUST NOT, because they are what makes the class a class rather than a matter of taste: a manual carries no RFC 2119 keywords (§4.2), and a manual does not narrate the difference between itself and a specification (§4.4).

Chapters 5 and 6 apply to both classes.

1.3.3 Reading order #

An implementer needs §2.1 and chapter 5, and nothing else.

An author needs the chapter for the class they are writing, then chapters 5 and 6.

A reader trying to work out which class a document belongs to, or why a given fact is documented in one place rather than another, wants §1.2.

A specification MUST declare its use of RFC 2119 keywords in its conventions article (§3.1).

The following keywords, when they appear in uppercase, MUST be interpreted as described in RFC 2119:

A specification MAY use a subset. Its conventions article MUST list which keywords it uses.

2.1.1 Lowercase is not a keyword #

The same words in lowercase carry no normative weight. This is not a loophole to be exploited: a lowercase "must" in a passage that reads as a requirement is an editing defect, because the reader cannot tell whether an obligation was intended.

An author writing a requirement MUST use the uppercase form. An author writing description SHOULD reach for a verb that is not a keyword at all — "is", "carries", "produces" — rather than relying on case to carry the distinction.

2.1.2 Requirements are stated against a role #

A specification with more than one party MUST state each requirement against the role rather than the program (§3.2). An obligation on a consumer binds whatever process is acting as the consumer, and one program may serve different roles on different interfaces.

2.1.3 SHOULD means something #

A SHOULD is not a soft MUST and not a decorative MAY. It marks a requirement with a real exception, and a specification using one SHOULD say what the exception is — either inline or in an adjacent note.

2.2.1 Everything is normative by default #

All text in a specification is normative unless it is explicitly marked otherwise.

2.2.2 Marking #

Informative text MUST be marked, using a note callout:

> [!NOTE]
> This paragraph gives context and defines no behaviour.

An inline aside introduced by "For example" or "Note:" is also informative.

2.2.3 What informative text may not do #

Informative text MUST NOT contain an RFC 2119 keyword used in its normative sense. Where a note needs to refer to required behaviour, it MUST cite the normative statement that defines it rather than restating it.

2.2.4 What informative text is for #

Rationale, worked examples, the attack a rule defends against, and the alternative that was considered and rejected.

A specification SHOULD carry that material rather than omit it. A rule whose reason is unrecorded is a rule that a later revision will remove as redundant, or preserve for the wrong reason — and a wrong reason is what the revision after that will reason from.

A specification that includes pseudocode MUST document its conventions in its conventions article (§3.1).

The conventions below are established across this corpus and SHOULD be used, so that a reader moving between books does not have to relearn the notation.

Pseudocode MUST appear in a fenced code block.

A specification MAY use further conventions — and, or, not for boolean operators, or named error returns — and MUST document any it uses.

2.3.1 Pseudocode is normative #

Pseudocode in a specification is a normative statement like any other, and MUST be read as one. It is not an illustration of a rule stated elsewhere; where it is meant as illustration, it belongs in a note (§2.2).

A specification book and each of its chapters carry a fixed opening and closing shape, so that a reader arriving at any chapter finds the same things in the same places.

3.1.1 Book level #

A book MUST open with an introduction chapter containing:

3.1.2 Chapter level #

A chapter specifying a protocol or a format MUST open with:

and SHOULD close with an Extension article (§3.4) and a Conformance article (§3.4), in that order, before any appendices.

A chapter defining a data structure rather than a protocol has no roles and no conformance obligations of its own, and is exempt from both.

3.1.3 Terminology delegates rather than repeats #

A terminology article MUST define the terms the chapter introduces. A term already defined elsewhere in the corpus MUST be delegated by reference rather than redefined:

Terms defined in §5.2 — package, manifest, payload, repository — are
used here with the same meaning and are not redefined.

3.1.4 Scope names its exclusions #

A scope article's exclusion list MUST identify, for each excluded item, which document covers it. An exclusion that names nothing tells a reader the subject is out of scope without telling them where to go, which is the least useful thing a scope article can do.

A specification with more than one party MUST name its roles in its scope article, and MUST state every requirement against a role rather than against a program.

A role is a position in an interaction, not a piece of software. One program frequently occupies several — a repository operator is usually also a package producer, and a daemon that answers one protocol may consume another.

3.2.1 Why the distinction is load-bearing #

Naming a program in a requirement makes the requirement untestable against anything else, which defeats the purpose of writing the specification down. The whole reason a contract is published is that somebody other than the current implementation may satisfy it.

3.2.2 Enumerating roles #

A chapter's scope article SHOULD present its roles as a table giving, for each, the obligation it carries:

Two or three roles is typical. A specification finding itself with six has probably merged two interactions that want separate chapters.

3.2.3 Conformance follows the roles #

Because requirements attach to roles, a conformance article (§3.4) states what each role must do, separately. A reader implementing one side needs to know which requirements are theirs without reading the other side's.

The conventions below hold across every book in this anthology. A book MUST NOT restate them, and MUST state any point on which it differs.

3.3.1 Byte order #

All multi-byte integer fields are little-endian unless explicitly stated otherwise.

3.3.2 Sizes #

All sizes and offsets are in bytes. u8, u16, u32, and u64 denote unsigned integers of 8, 16, 32, and 64 bits.

3.3.3 Layout tables #

A field layout is given as a table in declaration order. A layout table is normative: fields appear on the wire in the order listed, with no padding between them.

3.3.4 Notation #

Hexadecimal values carry the 0x prefix. Byte sequences are written as space-separated hex pairs: 0a 0b 0c.

3.3.5 Strings #

Strings are UTF-8 (RFC 3629). String comparison is byte-for-byte equality unless stated otherwise.

3.3.6 Hashes and signatures #

Hash values are lowercase hexadecimal unless stated otherwise, and hash algorithms are named by their IANA-registered identifiers.

3.3.7 Timestamps #

Timestamps are RFC 3339, in UTC, and end with Z.

3.3.8 What a book's conventions article carries #

Given the above, a book's conventions article (§3.1) is short. It MUST carry the book's RFC 2119 declaration, and SHOULD carry only:

• notation the book introduces that is not listed here;
• any point on which the book departs from this article;
• pseudocode conventions, if the book uses pseudocode (§2.3).

3.4.1 Extension #

A chapter specifying a wire format, a file format, or a protocol SHOULD close with an extension article stating how the thing may grow.

An extension article SHOULD distinguish:

• Additive changes, which an implementation of the current version can ignore safely — a new optional field, a new entry in an open-ended set.
• Changes requiring a version bump, which it cannot — a new required field, a new value in a closed enumeration, any change to an algorithm the format has frozen.
• Reserved space, where the format deliberately leaves room, and what an implementation does when it encounters a value there.

A specification MUST state, for every enumeration it defines, whether that enumeration is closed. An implementation cannot decide whether to ignore or reject an unknown value without being told.

3.4.2 Conformance #

A chapter SHOULD close with a conformance article summarising, per role (§3.2), what that role must do. The article is a summary and MUST NOT introduce a requirement stated nowhere else.

A conformance article SHOULD also state plainly what conformance does not require. A reader who has just been given a list of obligations benefits more from knowing where their freedom lies than from a longer list.

A technical reference manual is an exhaustive descriptive reference for one component: what it does, how it behaves at every edge, and what happens when it fails.

The hardware analogy is deliberate. If the specification anthology is the architecture reference manual, a TRM is the per-implementation technical reference manual that sits beside it — the document that tells you what this thing actually does, given that the architecture told you what any conforming thing must do.

4.1.1 One book per component #

A TRM covers one component, where the boundary is drawn by what ships and is maintained together rather than by subject matter. Several subsystems that live in one codebase and version together are chapters of one manual, not manuals of their own.

4.1.2 Its authority comes from the software #

This is the property that governs everything else in this chapter. A specification is authoritative over its implementations: where the two disagree, the implementation has a defect. A TRM is the reverse. Where a manual and the software disagree, the software is right and the manual is stale.

A TRM therefore makes no stability commitment. Nothing in one is a promise about a future version, and a reader who needs a promise needs a specification instead.

4.1.3 What belongs in one #

Everything about the component that is true and not specified elsewhere: its architecture, its state, its configuration, its algorithms where they are its own, its failure modes, its on-disk artifacts, and the reasoning behind its design decisions.

A manual SHOULD carry rationale generously. It is the only document in the corpus with room for it, and a component's design decisions are otherwise recorded only in the history of the work that produced them.

4.1.4 What does not #

Anything a third party must reproduce in order to interoperate. That is a contract, and a contract belongs in a specification (§1.2). A manual cites it (§4.6) rather than restating it.

4.2.1 No normative keywords #

A TRM MUST NOT use RFC 2119 keywords. Not uppercase, and not in the lowercase constructions that read as obligation.

This is the one rule in this chapter with no exceptions, because it is what makes the class a class. A manual describes; it does not require. A reader must be able to tell, from the first paragraph of any document in this corpus, whether they are being told what something does or what they must do.

4.2.2 The indicative mood #

Write what the component does.

The third and fourth rows are the ones that catch people. "May" and "must" survive into descriptive prose easily, because an author describing something real slips into obligation without noticing — particularly when the source material was a specification.

4.2.3 Lowercase keywords are the actual hazard #

Uppercase keywords are trivially caught by searching. Lowercase ones are not, and they are far more common: a conversion from specification prose typically leaves a dozen or more.

An author SHOULD search a finished manual for lowercase must, should, shall, may not, and must not, and rewrite every instance that reads as a requirement. Idiomatic uses survive — "what the content should be", "two files that cannot both be present" — and the test is whether a reader could mistake the sentence for an obligation.

4.2.4 Register #

Plain declarative prose, addressed to a competent engineer. Not tutorial and not chatty. A manual SHOULD assume its reader knows the platform and wants the specifics.

A TRM's chapter structure follows the component rather than a template. The conventions below are what has worked, offered as guidance.

4.3.1 The introduction #

A manual SHOULD open with an introduction containing:

The overview article is the most valuable page in the book and the one most often written last and least. It SHOULD say what is surprising about the component — the two or three decisions that would not be guessed from the name — rather than restating the component's purpose in a paragraph.

4.3.2 Body chapters #

Ordered so that a reader following the component's own flow reads them in order: what it is made of, what it does, in the sequence it does it.

4.3.3 A failure-modes chapter #

A manual SHOULD close with a chapter describing what goes wrong: the common failures, what each looks like from outside, what signal is available, and how to get back to a known state.

This is the chapter readers arrive at from a search engine at two in the morning, and it is the one most often omitted. A manual that documents every success path and no failure path has documented the easy half.

4.3.4 Appendices #

Consolidated reference material: constants, paths, on-disk state, configuration keys, event types. See §6.1.

4.3.5 Length is not a virtue, but exhaustiveness is #

A manual SHOULD document the edge cases. The odd interaction, the counter-intuitive default, the thing that happens only when two features meet — those are why the manual exists. A summary of the happy path is already in the component's README.

A TRM describes what the component does now. This has a consequence that authors reliably find uncomfortable, and it is worth stating directly.

4.4.1 Divergences are not narrated #

A TRM MUST NOT frame anything as a difference between itself and a specification. No "the specification requires X but the implementation does Y", anywhere, in any form.

Where an implementation does not satisfy a contract, that is a defect. It is recorded as one, in the project tracker, against the work that would fix it — and the manual simply describes what the software does.

4.4.2 Which does not mean writing around it #

Describing the true state is not the same as being vague about it. A manual SHOULD state plainly what a component does not do, where a reader would otherwise assume it did:

peipkg does not check free space before it starts. Exhaustion is discovered when a write fails.

That sentence is descriptive, useful, and carries no comparison to any contract. The distinction is between what is absent — which a reader needs — and what was promised — which belongs in the tracker.

4.4.3 Interim states #

Where behaviour is deliberately provisional, a manual MAY say so and describe the intended end state, provided it describes the current one first and at greater length. A manual SHOULD NOT let a description of an intention displace the description of what actually runs.

A technical reference manual proposal is a TRM for a component that does not exist yet.

It is written exactly as a TRM is written — indicative mood, no normative keywords, exhaustive — and it describes software that has not been built.

4.5.1 Why the class exists #

A design that has been written out at reference-manual depth is a design whose gaps are visible. Every field, limit, and interaction has to be decided in order to be described, and describing it is how the contradictions surface.

4.5.2 Saying what it is #

A proposal MUST identify itself as one. It SHOULD do so in two places: in its description, and in an opening article stating plainly that a manual's authority comes from the software (§4.1) and that this one has none of that yet — so a surprising statement in it is a design decision that has not survived contact with an implementation.

The document class carries that warning by itself, which is why no banner on every page is needed.

4.5.3 It graduates in place #

A proposal sits alongside the finished manuals and MUST NOT be moved when the software lands. Moving it breaks every inbound link. Graduating consists of correcting it against the implementation and dropping the word "proposal".

4.5.4 Reviewing one #

A proposal cannot be verified against code, so review is internal composition instead: for each field, rule, limit, and configured value, find every other place the document constrains it, and compose them by hand.

The failure to look for is two rules that are individually right and jointly wrong — a default stated in one chapter and a validity constraint stated in another, which together reject the default. The related one is two rules with no stated order, where both can fire on one input and the document never says which runs first.

Composing every pair of independently configured size limits on one data path, at their default values, is worth doing every time. Two documents in a row have carried a ceiling on one side larger than the ceiling on the other, letting one party accept what the other cannot carry.

A proposal MAY still contribute a specification chapter, where the component owes one. Publishing a contract with no implementation to keep it honest is a real cost, and it is a decision to take deliberately rather than by default.

Where a component implements a published contract, its manual cites the contract rather than restating it.

4.6.1 Cite, do not paraphrase #

A manual SHOULD state that the contract exists, name where it is, and describe what this implementation does about it:

A dependency is satisfied by a candidate when the conditions of PSPU §5.21 hold. Three consequences of those rules shape how peipkg behaves.

A manual MUST NOT restate the contract's normative content in descriptive prose. A paraphrase is a second copy that drifts, and because the paraphrase carries no normative keywords, a reader cannot tell which of the two they are supposed to rely on.

4.6.2 What the manual adds #

The nuances of one implementation: the order it does things in, the limits it applies, what it does where the contract leaves a choice, and what it does not implement.

A manual is the right place to say that a component is more restrictive than the contract requires, or that it makes a choice the contract leaves open. Those are facts about the software, not comparisons against it.

4.6.3 Where the split falls #

The recurring question is whether a given fact belongs in the manual or in the specification, and the test in §1.2 answers it: if a second independently written party must reproduce it, it is contract.

Worked, from one component: what satisfies a dependency is contract; which of several satisfying candidates gets chosen is implementation. The schema of a declaration is contract; the command-line flag that overrides it is implementation. The layout of an artifact is contract; where the tool keeps its own database is implementation.

§4.6 covers the ordinary direction: a manual cites the contract it implements. The reverse direction needs a rule of its own, because a specification that defers to a manual has given something up, and a reader is entitled to know that it did.

4.7.1 When it is allowed #

A specification MAY cite a manual for material it deliberately does not specify. It MUST NOT cite one for material within its own scope.

The test of §1.2 decides which case applies. If a second, independently written party must reproduce the behaviour, it is contract — and a citation to a manual there is a specification failing at its job, since the other party has no manual for their own implementation. If no second party is expected to reproduce it, because the component is Peios' alone and is described rather than standardised, then the manual is the only document that holds the material, and naming it beats implying a standard exists somewhere.

4.7.2 Say that it is a deferral #

A specification citing a manual MUST make the deferral legible rather than let it read as an ordinary cross-reference. "Described in the Peios Kernel TRM §3.8" says what it is; "see §3.8" does not.

Where a scope article excludes a whole area to a manual, it SHOULD say why once, in that article, rather than re-arguing it at each citation site. The sites then only need to name the article.

4.7.3 The standing case #

KACS is the one that recurs. Peios' access-control implementation is described in the Peios Kernel TRM §3 and is not separately specified, so PCDS — which specifies the structures KACS consumes — defers to that manual wherever a structure's meaning depends on what KACS does with it. PCDS §1.1 records the arrangement; the individual citations name the articles.

A specification's testable statements are already findable: they carry RFC 2119 keywords, so MUST can be searched for and enumerated. A manual has none, by the rule that defines the class (§4.2). Nothing in its text distinguishes a behavioural claim from the prose around it.

A named citation (§5.3) is therefore not a convenience for a manual. It is the only handle a manual can give a test suite, and the reason to anchor one is usually that something outside the corpus needs to point at it.

4.8.1 Anchor after writing, not during #

An author SHOULD write a manual, or a chapter of one, to completion first, and add anchors in a separate pass afterwards.

Marking anchors while drafting interrupts the writing for a decision that has nothing to do with the sentence being written. Choosing which statements are testable is also a different kind of attention from composing them: it reads the finished text as an implementer would, looking for what could be observed, and that reading is easier when the text is finished.

Where a component's manual is written before its tests exist — which is usual — the anchoring pass is still worth running, because it is what tells the test author where to start.

4.8.2 Put the anchor on the heading #

By default an anchor goes on a section's heading, and a section gets one. A manual that is well structured already devotes a section to a behaviour, so the section is the thing a test wants to cite, and the heading is where the anchor belongs:

### `ro` [*strata.ro-is-independent-of-filesystem]

An anchor on a heading rides the document's structure rather than one sentence of prose. A sentence gets rewritten in the ordinary course of keeping a manual true; a section is a more stable thing to have named, and the anchor moves with it.

The exception is a section that states several distinct behaviours — most often a table of error conditions, or a numbered list of rules that each hold independently. There the section is the wrong unit: one name for fourteen rules tells a test suite no more than the article number did. Anchor those individually, in the table row or list item that states each rule.

The test is not a count. It is whether a reader asking "which behaviour does this name?" could get more than one answer.

4.8.3 Choosing what to anchor #

Anchor a statement that could be observed: a rule about what is accepted or refused, a value, an ordering, a returned error, an invariant that holds while the component runs.

Do not anchor rationale, comparison with prior art, an account of how the source is organised where no behaviour follows from it, or a restatement of something already anchored nearby. An anchor on prose that no test could ever cite is worse than no anchor: it will be counted as uncovered forever.

4.8.4 Anchor where the rule is defined, once #

A manual states its important rules more than once — in the article that defines a rule, in a summary of consequences, in a table collecting every error condition. Only the defining occurrence carries the anchor.

A second anchor on a restatement does not add coverage; it splits it. Two names for one behaviour means two entries in a report, one test between them, and no way for a reader to tell which name the other tests were meant to cite.

The signals that a passage is a restatement rather than a definition are usually explicit: it closes with a § reference to the article that owns the rule, or it sits under a heading that disclaims authority. Where a section says the articles above remain authoritative, it carries no anchors at all.

The mirror of this also has to be checked. A summary left unanchored is correct only if the rules it summarises are anchored where they are defined — a table of error conditions whose rows appear nowhere else in prose is a definition, however much it looks like a summary, and an author SHOULD anchor its rows rather than leave the most testable surface in the manual uncitable.

4.8.5 One anchor is not one test #

Coverage against a manual is "does this citation have at least one passing test". It is not a mapping.

In a specification a normative statement is often close to a single testable behaviour. In a manual it frequently is not — an anchor is as much a way of dividing a long descriptive document into pieces a test suite can reason about as it is a single assertion, and several tests may reasonably cite one name. An author SHOULD move toward one anchor per behaviour where the prose allows it, and SHOULD NOT contort the prose to achieve it.

Any part of any book in this corpus is addressable with the § symbol followed by a number derived from the book's structure.

The examples are qualified because a bare § reference means "this book" (§5.2). Within this document, §2.1 is the RFC 2119 article and §A is the normative-reference list.

5.1.1 Where the numbers come from #

Chapter and article numbers derive from the ordering of directories and files, and are supplied by the renderer. An author does not write them into the text.

A chapter appendix — a file whose name marks it as an appendix, within a chapter directory — is lettered rather than numbered, and cited in the form §N.A. A book-level appendix, at the book root, is rendered as "Appendix A" and is cited by its letter alone, with no chapter component at all.

The two are easy to confuse and produce silently wrong references. An author adding a second appendix to a chapter SHOULD check the rendered index before relying on the citation.

5.1.2 Stability #

Section numbers are positional. Inserting a chapter shifts every following chapter; inserting an article shifts the rest of its chapter.

A book that other documents cite SHOULD therefore append rather than insert, where the choice exists. Where a restructure is unavoidable, every inbound reference has to be revalidated (§5.4).

5.2.1 Within a book #

A reference to another part of the same book omits the book name:

The claim-path set is the union defined in §5.23.

5.2.2 Between books #

A reference to another book leads with that book's short name:

A dependency is satisfied when the conditions of PSPU §5.21 hold.

The short name is the one declared in the book's own metadata — PCDS, PGSS, PSPK, PSPU. A reference to a manual names the component: the peipkg TRM §7.4.

5.2.3 Referring to a whole book #

All identifiers in this chapter conform to PCDS.

5.2.4 Prose and the reference are different things #

A citation MAY be accompanied by prose naming what is at the other end:

Sender authentication is performed by peer credential (§4.18).

The descriptor store article (§4.20) defines the retention rules.

The § reference is the durable part. The prose is a readability aid, and it MAY drift across revisions without invalidating the reference — which is also why prose alone is not a citation.

5.2.5 In code and in commit messages #

A code comment or a test referring to a documented rule SHOULD carry the full citation, so that a search finds every site depending on it:

/* Per PCDS §5.6: inherited ACEs precede explicit ones. */

Where the rule carries a named citation (§5.3), cite it by name instead. It resolves to the statement rather than to the article holding it, so a test says exactly what it verifies:

// Verifies PCDS *sd.inherited-aces-precede-explicit

The finest unit a § reference addresses is the article — the §N.M form of §5.1. Headings within an article are not numbered, and there is no § form that reaches inside one.

For prose that is the right size. A reader following a reference wants the surrounding argument, not one sentence stripped of it.

It is the wrong size for a test. A test verifies one statement, and an article holds many, so "this test covers §5.9" cannot say which of §5.9's statements remain unverified. For that there is a second scheme, addressing a statement by name.

5.3.1 Named citations #

A document MAY anchor an individual statement with a name:

A source MUST reject a relative identifier outside its declared
range. [*psi.rejects-out-of-range-relative-id]

which is then cited from outside the corpus — from a test, or a code comment — by qualifying it with the book's short name:

// Verifies PGSS *psi.rejects-out-of-range-relative-id

An anchor is a locator, not a delimiter. It marks a place; it does not record where the statement it names begins or ends, and nothing computes that. A reader follows the name and reads.

Four rules, all enforced by the builder:

• A name MUST be unique within its book. Citations from outside are qualified by the book's short name, so book scope is enough.
• A name MUST be lowercase, in dot- or hyphen-separated segments, beginning and ending with an alphanumeric.
• Only a book may carry an anchor. A citation is addressed through its book, so an anchor anywhere else could never be cited.
• An anchor MUST NOT appear inside a code block or inline code, where it is shown rather than declared.

A retired name MUST NOT be reused for a different statement. Nothing can detect the reuse, and every citation that already existed silently comes to mean something else.

5.3.2 Why not clause numbers #

An earlier corpus defined a finer § form: clauses numbered implicitly by counting normative statements within the deepest enclosing heading, cited as §3.2.1(4), with a validation rule for checking that a clause number still resolved.

It was specified in detail and never adopted. Across thirteen documents it was used eighteen times, and never once in the current corpus. What it cost was real: every editorial change to an article renumbered the clauses after it, so every citation into that article had to be checked against a count that nothing computed.

A name is not a count. It is written once, it does not shift when a statement is inserted above it, and a change that would break it — deleting the statement — is exactly the change that ought to break it. The failure that retired clause numbering does not reach the named form, which is why the two can coexist.

5.3.3 Why a name and not an extent #

A name identifies a statement; it does not describe one. Naming a statement copy-up.preserves-ownership says which statement is meant, not what it says, and the name does not grow when the statement gains an exception. This is the same division as §5.2's: the reference is the durable part, and the prose around it may drift.

An author MAY be tempted to mark where a statement ends as well as where it is. The corpus does not offer that, deliberately. A name is arbitrary, so nobody disputes it and nobody revises it; an extent appears to have a correct answer, so it invites both, and every revision of one buys nothing for the test or the code comment that cites it. Statements also overlap and nest in prose — a rule and its exception — in ways no bracketing scheme resolves cleanly.

5.3.4 Writing for citability #

Because the article is the unit a § reference reaches, an author SHOULD size articles so that one is a sensible thing to point at. An article covering one rule is easy to cite; an article covering nine unrelated rules forces every citation to be approximate.

The same applies one level down. Where a paragraph holds several statements that need separate names, an author SHOULD split the paragraph rather than crowd it, since a paragraph is also the unit of context a tool can report around an anchor.

Where a single statement needs picking out and no anchor exists, a citation MAY name it in prose alongside the article reference:

the duplicate-key rule of §5.9

5.3.5 Reading an old citation #

A (N) clause suffix in older material, or in a code comment predating this corpus, refers to the retired scheme. It SHOULD be resolved to an article reference, or to a named citation, when the surrounding text is next touched.

5.4.1 Every reference resolves #

A published book MUST NOT contain a reference that does not resolve. A reference to a chapter, article, or appendix that does not exist is an error, not a cosmetic defect: it is indistinguishable, to a reader, from a reference to something that was deleted.

5.4.2 Checking #

Because section numbers are positional (§5.1), any structural change invalidates references — including references from other books, which the author making the change is least likely to be looking at.

After a structural change, an author SHOULD:

1. Build the affected books and extract the actual chapter and article numbering from the rendered index.
2. Collect every § reference in the corpus.
3. Check each against that numbering.

Steps 1 to 3 are mechanical and worth automating. What is not mechanical is whether a reference that still resolves still means what the citing text implies. A reference to "the ordering rules of PSPU §5.6" resolves happily after that article is rewritten to cover something else.

5.4.3 Named citations are checked for you #

Unlike § references, named citations (§5.3) are validated by the builder: a duplicated name, a malformed one, or an anchor outside a book fails the build. What the builder cannot check is the other direction — whether a citation from outside the corpus, in a test or a code comment, still names a statement that exists. Deleting an anchor is therefore a deliberate act: grep the name across the repositories that cite it before removing it.

5.4.4 Two traps #

Line-wrapped references. A citation split across a line break — the book's short name at the end of one line and the § number at the start of the next — is easy for a checker to miss and easy for an author to introduce.

Appendix forms. A chapter appendix and a book appendix take different forms (§5.1), and a reference using the wrong one resolves to nothing — or worse, to something.

An appendix consolidates reference material that is defined in the body: constants, limits, enumerated values, paths, configuration keys, event types, wire vocabularies.

6.1.1 Appendices and the body do not duplicate #

Where a constant, table, or layout is defined in an appendix, the body MUST reference it rather than restate it — and where it is defined in the body, the appendix MUST reference that.

Exactly one of the two is the definition. The other points at it.

An appendix entry SHOULD carry a citation to the article that defines what it lists, so that a reader who needs the semantics can get there in one step.

6.1.2 What earns an appendix #

Material a reader looks up rather than reads: something they arrive at knowing what they want.

A limits appendix is the clearest case. Every size bound, count cap, and default in one table is genuinely more useful than the same figures scattered across twenty articles, and the body articles then cite it rather than repeating the number.

6.1.3 Generated appendices #

An appendix listing values that exist in source — an ABI table, a constants list, an error enumeration — SHOULD be generated from that source rather than transcribed, with a check mode that fails when the committed file is stale.

6.2.1 One canonical home #

Every exhaustive table or enumeration lives in exactly one place. Everywhere else that needs it gets a clearly framed subset and a reference to the canonical one.

This applies across the whole corpus, not within a single book: a table in a specification is not re-tabulated in a manual, and a manual's configuration reference is not duplicated into task documentation.

6.2.2 Subsets are labelled as subsets #

A partial table MUST be framed as partial. A reader who cannot tell a subset from the full set will treat the subset as exhaustive, which is how a table that was correct becomes a document that is wrong.

6.2.3 Disagreeing copies are never averaged #

Where two copies of a table disagree, the resolution is to check the source — the implementation, or the specification that defines it — and then to delete one of the copies. Splitting the difference produces a third value that matches nothing.

6.2.4 Layout tables #

A table describing a binary layout is normative in a specification (§3.3) and descriptive in a manual, and in both cases gives fields in declaration order.

6.2.5 Formatting #

A table row MUST NOT contain an unescaped |. A pipe inside a cell — common when documenting bitwise expressions — silently eats a column, and the resulting table renders as though it always had one fewer.

A table SHOULD have a header row with a meaningful label per column. Field | Type | Description beats three unlabelled columns.

Very wide tables SHOULD be broken up or transposed. A table that needs horizontal scrolling is a table nobody reads the right-hand end of.

A note carries what the surrounding text cannot: why the rule is the way it is, what it defends against, what was tried instead.

> [!NOTE]
> Text.

In a specification a note is informative and is bound by §2.2. In a manual, where nothing is normative, a note is a change of register rather than of authority.

6.3.1 What a good note does #

• Names the failure the rule prevents. Concretely, with the mechanism. "Without this, an attacker who controls a cache edge replays an older signed index and the consumer never notices" is worth ten lines of abstract rationale.
• Records the alternative that was rejected, and why. The next person to look at the design will otherwise propose it again.
• Flags the counter-intuitive. Where a reader's first instinct is wrong, a note is where to say so.

6.3.2 What a note is not #

• A restatement of the rule above it in different words.
• A place to hide a requirement (§2.2).
• An apology for a design.

6.3.3 Density #

Roughly one note per two or three articles is what has worked. A book with a note under every heading has diluted the marker to the point where readers skip them, which wastes the ones that matter.

Mechanical conventions. None of these affects meaning; all of them affect whether a diff is readable.

6.4.1 Line length #

Prose SHOULD wrap at 78 columns. Tables, code blocks, and link-heavy lines are exempt — breaking those hurts more than it helps.

The reason is diffs. A paragraph on one long line produces a whole-paragraph diff for a one-word change, which makes review of a large document impractical.

6.4.2 Frontmatter #

Every article carries YAML frontmatter with a title and a description:

---
title: Freshness and Rollback Protection
description: An index that verifies is not necessarily current — monotonic
  versions, staleness limits, and the defences against rollback and freeze.
---

Titles are in title case, and name the subject rather than describing it. "Freshness and Rollback Protection", not "How freshness works".

The description is one sentence saying what the article covers. It is what a reader sees in a search result, so it does the work the title deliberately does not: where the title names the subject, the description says what is in there. It SHOULD name the specific things — "monotonic versions, staleness limits" beats "the freshness rules" — because a corpus this size has many articles called Overview, Structure and Conventions, and the description is what tells them apart.

Do not restate the title. title: Persistence with description: How persistence works has spent a line and told the reader nothing.

Books were written without descriptions for a time, and the omission was invisible until search made it obvious. The site build takes --strict, which fails on any article missing one; run it that way.

6.4.3 Headings #

Articles use ## for their top-level headings. An article does not repeat its own title as a heading — the renderer supplies it.

Heading text is short and specific. Because headings are not addressable (§5.3), they are navigation rather than citation targets, and they SHOULD read as scannable labels.

6.4.4 Code and identifiers #

Identifiers, paths, field names, and literal values are in backticks. Fenced blocks carry a language tag where one applies.

Code spans are not translated: a field named size_installed is written that way in prose, not as "size installed".

6.4.5 Text hygiene #

Straight quotes and apostrophes rather than typographic ones; a regular hyphen rather than a non-breaking one; a normal space rather than a non-breaking space; and no zero-width characters. Each of those renders identically and greps differently, which is the worst combination.

An em dash is written as —, spaced as the surrounding prose requires.

6.4.6 Spelling #

British English, except in identifiers, code, and the names of external standards, which are reproduced exactly as their source spells them.

Much of what this corpus documents already has names — given by an external standard, by a published header, or by both, spelled differently. A reader arrives holding one of those names and expects to find it.

6.5.1 Each document uses its own reader's vocabulary #

A specification is written for an implementer who has the external standard and does not have this implementation's source. It uses the external standard's spelling, exactly as that standard spells it.

A technical reference manual is written for someone reading alongside the implementation. It uses the implementation's spelling, exactly as the header declares it.

Neither adopts the other's vocabulary. A specification that named private headers would be documenting something its reader cannot see, and a manual that named only the standard would not match the code in front of the reader.

6.5.2 Divergences are recorded once per book #

Where the two vocabularies disagree, the disagreement is stated once — in a table, in an appendix — and not repeated at every use. Inline double-naming makes prose unreadable to both audiences at once.

The table gives both spellings and nothing else. It is a lookup, not an explanation.

6.5.3 Where a standard names a structure and its constant separately #

Many standards give one name to a structure and another to the constant that selects it: a record type and the numeric tag identifying that record. A reader may arrive with either — one from a declaration, the other from a hex dump — so a table that gives a value MUST name the constant that carries it, not only the structure it selects.

Naming the structure in a column headed with the constant's value is the common form of this mistake. It reads correctly and is unfindable by half the people who need it.

6.5.4 The test #

For any name a reader could plausibly arrive with, searching the corpus for that exact string finds something. A name that appears only as prose — "the offset to the owner SID", where the standard calls the field OffsetOwner — fails this test even though the surrounding text is correct.

Correct and unfindable is the failure this rule exists to prevent. Reference material is read by search.

The external standards this corpus depends on. A book MUST NOT restate this list; it cites into it.

A.1 Deferral #

Where a document defers to an external standard, that standard's requirements apply as though written out. A document citing one MUST name the specific part it relies on where the whole would be ambiguous.

A.2 Citation format #

A.3 IETF #

A.4 Microsoft Open Specifications #

The Windows security model is the design source for several Peios subsystems, and its documents are cited for parity mappings.

A.5 Unicode #

A.6 POSIX and other standards #

A.7 External conventions #

Some documents describe interoperation with conventions that have no formal specification — the sd_notify readiness protocol and the freedesktop os-release file among them. Where a document relies on one, it MUST describe the behaviour it depends on rather than citing the convention alone, because there is no normative text at the other end of the citation.

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

This document covers:

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

This document does not cover:

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

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

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

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

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

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

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

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

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

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

Data4 is a raw byte array with no endianness interpretation.

2.1.1 Nil GUID #

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

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

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

2.2.1 Canonical form #

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

{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

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

The fields map to the string as follows:

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

2.2.2 Case #

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

2.2.3 Parsing #

Parsers MUST accept both uppercase and lowercase hex digits.

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

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

2.3.1 Equality #

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

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

2.3.2 Ordering #

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

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

2.4.1 Algorithm #

To generate a version 4 GUID:

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

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

2.4.2 Randomness source #

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

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

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

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

2.A.1 MS-DTYP #

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

2.A.2 RFC 4122 #

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

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

2.A.3 DCE RPC #

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

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

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

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

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

3.1.1 Nil LUID #

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

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

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

3.2.1 Equality #

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

3.2.2 Ordering #

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

LUIDs MUST be allocated by the kernel.

3.3.1 Uniqueness scope #

Each LUID MUST be unique within a single boot session.

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

3.3.2 Monotonicity #

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

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

3.3.3 Fabrication prohibition #

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

3.A.1 MS-DTYP #

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

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

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

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

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

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

SIDs are represented in string form as:

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

Where:

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

4.3.1 Equality #

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

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

4.3.2 Ordering #

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

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

4.4.1 Universal authorities #

4.4.2 Creator authorities #

4.4.3 NT Authority (S-1-5) #

4.4.4 Logon SIDs #

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

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

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

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

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

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

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

KACS currently standardises these PIP type values:

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

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

4.4.9 Confinement SIDs (S-1-15) #

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

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

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

4.4.11 Service SIDs #

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

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

4.A.1 MS-DTYP #

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

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

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

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

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

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

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

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

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

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

5.1.1 Binary format #

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

Field names are those of MS-DTYP §2.4.6.

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

KACS MUST use the self-relative format exclusively.

5.1.2 Control flags #

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

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

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

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

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

5.1.3 Null DACL vs empty DACL #

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

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

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

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

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

5.2.1 Binary format #

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

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

5.2.2 Parsing rules #

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

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

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

5.3.1 Bit layout #

The 32 bits are divided into four regions:

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

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

5.3.1.2 Standard rights (bits 16–20) #

Common to all object types:

5.3.1.3 Special rights (bits 24–25) #

5.3.1.4 Generic rights (bits 28–31) #

Abstract rights mapped to object-specific rights before evaluation:

5.3.1.5 Reserved bits #

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

5.3.2 Generic mapping #

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

Each object type defines a GenericMapping table:

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

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

5.4.1 ACE header #

Every ACE begins with a 4-byte header:

The size includes trailing padding. Builders zero-pad a variable-length raw body to the next four-byte boundary, including resource-attribute claims whose final octet value has an arbitrary length. This padding belongs to the ACE; it does not increase the claim's declared octet-value length.

5.4.2 ACE body layouts #

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

5.4.2.1 Single-SID ACE family #

The following ACE types share the same binary layout:

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

Layout:

Parsing rules:

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

5.4.2.2 Object ACE family #

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

• ACCESS_ALLOWED_OBJECT_ACE
• ACCESS_DENIED_OBJECT_ACE
• SYSTEM_AUDIT_OBJECT_ACE
• SYSTEM_ALARM_OBJECT_ACE

Layout:

Object ACE flags:

Parsing rules:

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

5.4.2.3 Callback ACE family #

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

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

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

For callback object ACEs, the body layout is:

Parsing rules:

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

5.4.2.4 Resource attribute ACE #

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

Parsing rules:

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

5.4.3 DACL ACE types #

5.4.3.1 Basic ACEs #

5.4.3.2 Object-type ACEs #

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

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

5.4.3.3 Conditional ACEs #

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

5.4.4 SACL ACE types #

5.4.4.1 Audit ACEs #

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

5.4.4.2 Alarm ACEs (continuous auditing) #

5.4.4.3 Mandatory label ACE #

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

5.4.4.4 Resource attribute ACE #

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

5.4.4.5 Scoped policy ID ACE #

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

5.4.4.6 Process trust label ACE #

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

5.4.5 Allocated but unimplemented ACE types #

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

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

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

Values above 0x15 are unallocated.

5.4.6 AceType constants #

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

5.4.7 ACL revision #

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

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

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

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

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

5.5.1 Canonical ordering #

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

The canonical order is:

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

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

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

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

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

5.5.2 SACL ordering #

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

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

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

5.6.1 Inheritance flags #

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

A fifth flag records provenance:

5.6.2 Common flag combinations #

5.6.3 CREATOR OWNER and CREATOR GROUP #

Two well-known SIDs receive special treatment during inheritance:

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

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

Substitution happens at inheritance time, in each ACE that applies to the new object. An inherit-only ACE keeps the placeholder, so that each object further down resolves it to its own owner or group (see the inherited ACEs below).

5.6.4 The ACEs a child inherits #

Each ACE of the parent's ACL contributes to a new child as follows. The same rule applies to the DACL and the SACL.

1. Whether it passes. An ACE passes to a container child if it has CI, or OI without NP. It passes to a non-container child if it has OI. INHERIT_ONLY on the parent's ACE plays no part. An ACE that does not pass contributes nothing.

2. The copy's flags. The copy has INHERITED_ACE set and INHERIT_ONLY cleared, with three exceptions:

   • An ACE with OI and neither CI nor NP reaches a container as inherit-only (OI, IO): it applies to the objects inside, not to the container.
   • NP clears OI, CI and NP from the copy. The copy applies to the child and goes no further.
   • A non-container's copy has no OI, CI, NP or IO.

   Flags other than these (SUCCESSFUL_ACCESS_ACE, FAILED_ACCESS_ACE) are kept.

3. Resolution. A copy that applies to the child (IO clear) has CREATOR OWNER and CREATOR GROUP substituted, and its generic rights mapped through the child's GenericMapping (see below).

4. The split. An ACE that names CREATOR OWNER or CREATOR GROUP, or carries generic rights, and whose copy both applies to a container child and goes on from it (OI or CI still set), gives the child two ACEs, written one after the other:

   • the resolved copy, with OI, CI, NP and IO cleared, applying to the child alone; and
   • an inherit-only copy (the copy's flags with IO set), left as written: the placeholder unsubstituted and the generic rights unmapped.

   Resolving the ACE once and carrying the result down would grant the first creator over everything beneath, and map rights through one object type's mapping for objects of another. Carrying it unresolved would grant nothing here. A non-container gets the resolved copy alone. Every other ACE is inherited as one copy.

For example, a directory whose DACL holds (A;OICIIO;GA;;;CO) and (A;OICI;GR;;;AU) gives a new subdirectory owned by alice (A;ID;FA;;;alice)(A;OICIIOID;GA;;;CO)(A;ID;FR;;;AU)(A;OICIIOID;GR;;;AU), and a new file in it (A;ID;FA;;;alice)(A;ID;FR;;;AU).

5.6.5 Inheritance algorithm #

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

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

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

5.6.5.1 Owner #

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

5.6.5.2 Group #

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

5.6.5.3 DACL #

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

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

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

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

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

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

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

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

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

5.6.5.4 SACL #

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

5.6.6 Eager evaluation #

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

A consequence of eager evaluation: modifying an inheritable ACE on a parent object does not automatically update existing children. Existing children retain the SD they were created with. Propagating the change to descendants is an explicit operation, done by userspace, as below.

5.6.7 Re-propagation #

Re-propagation brings existing descendants up to date with their parent. The kernel has no primitive for it: the program that changed the parent walks the tree. Every program that does MUST give the same result, which is this.

For one child and one ACL (the DACL, the SACL, or each in turn):

1. If the child protects that ACL (SE_DACL_PROTECTED or SE_SACL_PROTECTED), it is left exactly as it is.
2. Otherwise, the child's ACEs with INHERITED_ACE set are removed, its other ACEs are kept in their order, and the ACEs the parent's ACL gives it (above, resolved against the child's own owner and group, through the child's object type's GenericMapping) are appended after them. The ACL is marked SE_DACL_AUTO_INHERITED or SE_SACL_AUTO_INHERITED.
3. A parent without that ACL gives nothing, so only the inherited ACEs are removed. A child without that ACL gets one only if something is inherited into it.

The owner, group and the ACL not being re-propagated are unchanged. A child is re-propagated from its parent as the parent is after its own re-propagation, so a walk goes parents first. A protected child still passes its own ACEs on: its descendants are re-propagated from it as it is. A failure on one child does not stop the walk: the rest are re-propagated and the failures reported.

libpeios implements this as reinherit_with (peios_sd_reinherit_ex).

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

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

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

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

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

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

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

This enables three patterns:

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

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

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

5.7.2 Ownership transfer #

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

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

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

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

5.8.1 Three-valued evaluation #

Conditional expressions produce one of three results:

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

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

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

5.8.2 Expression language #

The expression supports:

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

5.8.3 Three-valued logic #

NOT: TRUE↔FALSE; UNKNOWN→UNKNOWN.

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

5.8.4 Attribute sources #

Four attribute namespaces exist, resolved via bytecode opcodes:

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

5.8.5 Claim flags #

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

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

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

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

5.8.6 SID matching in expressions #

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

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

5.8.7 Binary format #

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

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

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

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

5.8.8 Limits #

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

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

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

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

5.9.1 Supported types #

KACS v0.20 supports these claim value types:

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

5.9.2 Entry layout #

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

Claim flags use the same meanings everywhere this format appears:

Unknown flag bits are preserved but have no defined semantics.

5.9.3 Value encodings #

5.9.3.1 INT64 / UINT64 / BOOLEAN #

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

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

5.9.3.2 STRING #

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

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

5.9.3.3 SID #

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

5.9.3.4 OCTET #

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

5.9.4 Single-entry containers #

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

5.9.5 Multi-entry containers #

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

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

Rules:

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

5.9.6 Validation rules #

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

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

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

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

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

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

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

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

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

5.10.1 Claim types #

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

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

5.11.1 Magic signature #

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

5.11.2 Token formats #

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

5.11.3 Literal tokens #

5.11.3.1 Sign codes #

Integer literals include a sign byte after the QWORD value:

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

5.11.3.2 Base codes #

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

5.11.3.3 Integer encoding example #

The decimal value -1 encoded as a signed int64:

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

5.11.4 Relational operator tokens #

5.11.4.1 Binary relational operators #

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

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

5.11.4.2 Unary relational operators (SID membership) #

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

For an empty SID operand set:

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

5.11.5 Logical operator tokens #

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

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

5.11.5.1 Unary logical operators #

5.11.5.2 Binary logical operators #

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

5.11.6 Attribute reference tokens #

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

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

5.11.7 Complete byte-code summary #

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

KACS implementations MUST be byte-compatible with these encodings.

5.A.1 MS-DTYP #

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

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

This document defines the Peios Generic System Standards (PGSS): the cross-platform protocols and standards a system MUST implement in order to be Peios.

A standard belongs in this document when three things are true of it.

It is a conformance requirement. A system that does not offer the protocol, at the specified path, with the specified semantics, is not Peios. Each standard here is a bar to clear, not a recommendation to weigh.

It belongs to no implementation. A PGSS standard describes a contract between two roles, not the behaviour of a particular program. Mainline ships an implementation of each role; nothing in this document depends on that implementation, or describes it.

Either role may be replaced. A third party MAY ship its own implementation of one role — or of both — and interoperate with the other unchanged. A standard that cannot survive that substitution is a description of one system rather than a contract between two, and does not belong here.

For each standard, this document covers:

• the channel it is offered on, and the access control governing it
• message framing, encoding, and the rules under which the format may be extended
• the messages exchanged, their fields, and the order in which they are exchanged
• the obligations binding on each role, including what a role MUST establish for itself rather than believe from a message
• the conformance requirements for each role

This document does not cover:

• How an implementation reaches the answers it gives — that is precisely what different systems exist to do differently
• The binary structures these protocols carry — defined in PCDS
• Protocols spoken across the kernel boundary — defined in PSPK
• Protocols between foundational userspace components — defined in PSPU
• Interfaces particular to one Mainline component — defined in the specification of the component that offers them

1.1.1 Distinguishing a standard from a protocol #

The anthology's three protocol documents are told apart by what happens when you disagree with one.

Disagreeing with a standard in this document means shipping something that is not Peios.

Disagreeing with PSPK or PSPU means shipping a system built from different parts — a different kernel subsystem, or a different set of userspace components. That is a design choice, not a conformance failure.

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

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

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

This chapter specifies PGSS Logon: the protocol by which a caller obtains a KACS token and a logon session from an authentication authority, and the protocol by which any program on the system resolves an identity it already holds into a name, a SID, or the attributes a POSIX program expects of one.

Two roles participate.

The authority is the process that listens on the logon socket. It decides whether a logon succeeds, mints the resulting token, creates the logon session, and answers identity lookups. There MUST be at most one authority on a running system.

The client connects and speaks on a principal's behalf. It proposes what kind of logon it wants, renders prompts and returns answers without interpreting them, and receives the token and installs it itself. A client is not trusted: everything it sends is a claim (§2.4).

The principal is the identity a logon is for — the person or service being authenticated. The principal is not a party to the conversation.

Both roles are publicly implementable. A third party MAY ship a different authority, a different logon originator, or both, and interoperate with the other half unchanged.

This chapter covers:

• the two channels an authority offers, and the access control governing each (§2.5, §2.14)
• message framing, header layout, and the rules under which the format may be extended (§2.6)
• the messages of the logon conversation, their fields, and their encodings (§2.7 to §2.10)
• the shape of a conversation: who speaks, in what order, and how it terminates (§2.3)
• the transfer of the minted token to the caller, and the session-profile values a logon originator needs in order to start a session (§2.9)
• credential handling obligations binding on both roles (§2.11, §2.12)
• what an authority MUST establish for itself rather than believe from a message (§2.4)
• resolving a principal to a name, a SID, a POSIX identifier, or the attributes a POSIX program expects of one (§2.13 to §2.18)
• how a bare name is resolved when more than one source could answer it (§2.15)
• how a service manager obtains a token for a service, where there is no credential to exchange (§2.19)
• how a principal changes their own credential (§2.20)
• the obligations binding on each role (§2.21)
• how a caller asks the authority to end a logon session — its own, or, where policy permits, somebody else's (§2.22)
• how a principal adds a credential of their own, such as an SSH public key, or removes one (§2.23)

This chapter does not cover:

• Tokens, SIDs, privileges, integrity levels, logon sessions, logon types, and access checks — described in the Peios Kernel TRM. SIDs and security descriptors are specified in PCDS.
• How an authority decides whether a credential is valid, where it keeps identity, which principals exist, or what they are called. Those belong to the authority's own design. Mainline's authority federates them over PSI, the Principal Source Interface, specified in PSPU §2.
• Credential enrolment — giving a principal a credential it does not have — and account administration, including setting a credential on another principal's behalf. Neither is specified.
• Service startup and ordering, described in the peinit TRM.

The distinction in the second point is the load-bearing one. PGSS Logon specifies how a caller asks and how an authority answers. It says nothing about how the authority reaches its answer, because that is exactly what different systems will do differently, and constraining it would make the standard a description of one implementation rather than a contract between two.

2.1.1 What the authority does not do #

An authority MUST NOT be a process factory. It does not fork the principal's shell, does not learn about controlling terminals, environments, or session leadership, and does not decide what the caller does with the token it receives.

The caller installs the token and proceeds. This keeps the most privileged process on the system out of the business of launching arbitrary programs, and it means a client can obtain a token for a purpose the authority need never have anticipated.

The authority still starts nothing when it is asked to end a logon session (§2.22). It MAY then end the processes running in that session, and only those: ending what exists launches nothing, and the prohibition is on launching.

2.1.2 Authentication and derivation #

Two acts, deliberately separated.

Authentication establishes that the principal is who they claim. Its output is an identity and nothing more.

Derivation constructs the token: which SIDs it carries, which privileges, at what integrity level, with what projected identifiers. Its inputs are the authenticated identity and local policy.

The separation matters because the second is where a machine's own rules apply. An identity established elsewhere — by a directory, by a remote authority — does not carry entitlements onto this machine with it. What that identity means here is decided here, every time, by the authority applying local policy.

An authority MUST perform derivation itself. It MUST NOT accept a token, a privilege set, or an integrity level supplied by any other party, whatever its trust level.

2.1.3 The token this chapter does not describe #

This chapter governs the conversation and the delivery of its result. It does not govern the contents of the token that results. What SIDs, privileges, and integrity level a principal receives is derivation, and derivation is the authority's judgement applied to local policy.

A caller that receives a token from this protocol has been told who it may act as. It has not been told, and MUST NOT infer, anything further about how that conclusion was reached.

Terms defined in the Peios Kernel TRM (token, logon session, privilege, integrity level, logon type) and in PCDS (SID, security descriptor, DACL) are used here with the same meaning and are not redefined.

Authority. The process that listens on the logon socket, decides whether a logon succeeds, mints the resulting token, creates the logon session, and answers identity lookups. There is at most one authority on a running system.

Client. A process that connects to the authority. Also called the originator when the emphasis is on whose identity the authority verifies. There are four client roles — originating a logon, changing the caller's own credential, looking an identity up, and ending a logon session — and they are independent (§2.21).

Principal. The identity a logon is for — the person or service being authenticated. The principal is not a party to the conversation; the client speaks on their behalf.

Conversation. One connection's exchange, from the client's opening message — a logon's, a credential change's (§2.20), an enrolment's (§2.23), or a request to end a logon session (§2.22) — to a terminal message from the authority. One connection carries exactly one conversation.

Round. One CredentialRequest from the authority and the CredentialResponse that answers it. A conversation MAY take several rounds.

Terminal message. AccessGranted or AccessDenied for a logon; CredentialChanged or AccessDenied for a credential change (§2.20) or an enrolment (§2.23); SessionEnded, SessionEndAllowed or AccessDenied for a request to end a logon session or to ask whether one may (§2.22). Exactly one is sent, and nothing follows it.

Credential material. Any byte sequence a principal supplies as proof of identity — a password, a one-time code, a response from a token. Distinguished throughout from a verifier, which is what an authority stores and which MUST NOT be usable as credential material.

Prompt. A request from the authority for one piece of credential material, carrying enough description for a client to render it without understanding what it is for.

Derivation. The authority's construction of a token's contents — its SIDs, privileges and integrity level — from the authenticated identity and local policy. Distinct from authentication, which establishes only that the principal is who they claim.

Attestation. A trusted process's assertion that a logon should happen, standing in for a credential where none exists and none should. Distinct from authentication, which establishes that a principal is who they claim by something only they could present; an attestation establishes only that the party asking is one the authority permits to ask (§2.19).

Source. A party an authority consults in order to answer a question about identity. Whether an authority has sources at all, and what they are, is its own design; the term appears here only where the protocol's behaviour depends on there being more than one possible answerer (§2.15, §2.18).

2.2.1 A note on "logon type" #

LogonType (§2.7) describes the kind of session being established — interactive, network, batch, service. It is a property of the situation, not of the principal, and the same principal may hold several sessions of different types at once. Its values and meanings are defined by KACS and described in the Peios Kernel TRM; this chapter carries it but does not define it. The values are listed for reference in §2.B.

A logon is a conversation, not a call. The client opens it, the authority asks for whatever the principal's policy requires, and the authority ends it.

client                                   authority
  |                                          |
  |------------- LogonStart ---------------->|
  |                                          |
  |<--------- CredentialRequest -------------|   round 1
  |---------- CredentialResponse ----------->|
  |                                          |
  |<--------- CredentialRequest -------------|   round 2 (if required)
  |---------- CredentialResponse ----------->|
  |                                          |
  |<-- AccessGranted (+ token fd) -----------|   terminal
  |         or AccessDenied                  |

2.3.1 Why a conversation #

The value of this shape is that the client stays generic. It does not know what a password is. It renders the prompts it is given, collects the answers, and returns them.

That is what makes multi-factor authentication, password-expiry-forces-change, smartcards, or a policy that asks for a second factor only from an unfamiliar host, changes to authorities rather than to every client on the system. A protocol that named its credential kinds would have to be revised, and every client rebuilt, for each one.

Most logons are one round: the authority asks for everything the principal's policy requires, in one array, and decides. The conversational shape exists for what one round cannot express — choosing between authentication paths, or a shared account where one credential unlocks a requirement for another.

2.3.2 Sequence rules #

A conversation MUST proceed as follows.

1. The client sends exactly one opening message: LogonStart, CredentialChangeStart to change its own credential (§2.20), CredentialEnrollStart to add or remove one of its own (§2.23), or SessionEnd or SessionEndQuery about a logon session (§2.22). It MUST be the first message. An authority MUST reject any conversation that opens with something else.
2. The authority sends zero or more CredentialRequest messages. Each MUST be answered by exactly one CredentialResponse before the authority sends anything further.
3. The authority sends exactly one terminal message: AccessGranted or AccessDenied for a logon, CredentialChanged or AccessDenied for a credential change or an enrolment, SessionEnded or AccessDenied for a SessionEnd, and SessionEndAllowed or AccessDenied for a SessionEndQuery.
4. Both parties close the connection.

SessionEnd and SessionEndQuery exchange no credentials: the authority sends no CredentialRequest in reply to either, and the conversation is the opening message and its terminal.

The authority MAY send a terminal message at any point after LogonStart, including before any CredentialRequest. Zero rounds is a conforming conversation: an authority that can decide from LogonStart alone — a pre-authenticated caller, or a refusal on logon type — is not required to ask for anything.

A client MUST NOT send a CredentialResponse that was not solicited by a CredentialRequest. An authority MUST reject one that was not.

2.3.3 Bounding the conversation #

An authority MUST bound the number of rounds it will conduct and MUST bound the time it will wait for a CredentialResponse. Neither bound is fixed by this chapter, since both are policy. An authority that exhausts either MUST terminate with AccessDenied carrying ConversationLimit rather than closing silently, so that the client can distinguish a policy limit from a crash.

2.3.4 Termination #

Exactly one terminal message is sent. After it, the authority MUST NOT send anything further on that connection, and MUST close it.

A connection that closes without a terminal message is an abnormal termination. A client MUST treat it as a failed logon and MUST NOT retry automatically, since the reason is unknown and may be a policy refusal the authority could not express.

Nothing a client sends is trusted. This section states the rule once, because every field in §2.7 is subject to it.

2.4.1 Peer identity #

An authority MUST establish the connected peer's identity from the connected socket, by reading the peer's token from the kernel. It MUST NOT take the peer's identity from any message body, because there is no field in which a client could put it that the client could not also lie in.

An authority MUST NOT use SO_PEERCRED for this purpose. It answers a similar-looking question and is the wrong answer: it returns the projected UID, which cannot distinguish an authenticated principal from an unauthenticated process running under the same projection, and carries none of the token's SIDs, groups, integrity level or privileges.

2.4.2 Logon type #

LogonStart.logon_type is a proposal, not an instruction.

Only the caller knows whether an inbound connection is an interactive shell or a batch command, so the caller has to be the one to say. But an authority MUST constrain the proposal against what that verified peer is permitted to request. Otherwise anything that can reach the socket can mint itself an interactive session, and the logon type — which access control decisions depend on — becomes a value chosen by the least trusted party in the exchange.

2.4.3 Identifier #

The identifier names the principal a logon is for. It is a claim about who is being authenticated, and it is what the subsequent credential exchange exists to test. An authority MUST NOT treat an identifier as established until authentication has succeeded.

2.4.4 Everything else #

tty and remote_host are unverified context. An authority MAY record them, MAY use them in policy, and MUST NOT treat them as established facts. A client that lies about its remote host is not prevented from doing so by this protocol.

2.4.5 Access to the socket #

Access to the logon socket MUST be controlled by a security descriptor.

It MUST NOT be controlled by process integrity level. PIP can gate a socket, but using it here would require every future caller — a graphical greeter, a web console, a remote access daemon — to be signed at high trust merely to collect a password. Collecting a credential is not a privileged act; deciding whether it is correct is, and that decision happens on the other side of the socket.

The descriptor decides who may reach the socket, not what a peer may do once there. Where it admits principals so that they can change their own credential (§2.20) or enrol one (§2.23), it admits peers that may not originate logons, and an authority MUST decide from each peer's identity whether it may originate one.

Rate limiting is defence in depth. It is not the access control, and an authority MUST NOT rely on it as such.

2.5.1 Socket #

An authority MUST listen on a SOCK_STREAM Unix domain socket at:

/run/logon.sock

The path is normative. It is the standard's path, not an implementation's, and a client MUST NOT require configuration to find it.

2.5.2 Access control #

The socket MUST carry a security descriptor granting connect access to the principals permitted to originate logons, to the principals permitted to change their own credential (§2.20) or enrol one (§2.23), and to those permitted to end a logon session (§2.22). See §2.4 for why this, and not process integrity, is the control — and why reaching the socket is not, on its own, permission to originate a logon.

2.5.3 One conversation per connection #

A connection carries exactly one conversation. The connection is the conversation's identity.

There is therefore no correlation identifier in the header, and none is needed: a message belongs to the conversation it arrived on. This removes a class of error and attack — a forged or confused identifier cannot attach a credential response to somebody else's logon, because there is no identifier to forge.

It also bounds the credential's lifetime by the connection's, which makes that the kernel's job to enforce rather than the authority's to remember.

An authority MUST close the connection after sending its terminal message. A client MUST close after receiving one.

A ServiceAttest (§2.19) is not a conversation and exchanges no credential, but it is bound by the same rule: one per connection, answered with one terminal message, and the connection closed. It is carried here rather than on its own socket because it is a logon in every respect except how the authority was satisfied — it creates a session and mints a token — and because the volume is a handful of requests at start-up rather than the sustained load §2.14 exists to separate.

SessionEnd and SessionEndQuery (§2.22) are bound by the same rule: one request per connection, one terminal message, and the connection closed. They are here because ending a session is a decision about logons, made by the party that created the session.

2.5.4 Concurrency #

An authority MUST serve conversations concurrently. A logon that stalls — a principal who walks away mid-prompt — MUST NOT prevent other logons from proceeding.

An authority MUST bound the number of conversations it will serve at once, and MUST bound the time a conversation may remain open. Both are policy; neither is fixed here.

2.5.5 Descriptor passing #

The channel MUST support ancillary data (SCM_RIGHTS). The token is transferred as a file descriptor alongside AccessGranted — see §2.9.

Both of an authority's channels use the framing specified here without modification. The identity socket's departures are stated in §2.14; they concern which message types are served where, not the encoding.

2.6.1 Header #

Every message begins with a 12-byte header:

total_len counts the header. A message is therefore self-delimiting from its first 12 bytes, and a reader can size its buffer before reading the body.

2.6.2 Magic #

The magic MUST be checked on every message and MUST cause an immediate, whole-connection failure when wrong.

This is not decoration. Peios protocols share this codec and this header layout, and some of them share message bodies. A socket plugged into the wrong daemon would otherwise partially work, which is far worse than failing outright — a subtle misbehaviour several fields in, rather than a hard error on byte zero. A protocol reusing this codec MUST take a distinct magic.

2.6.3 Version #

A peer receiving a version it does not implement MUST refuse the message. An authority MUST refuse with AccessDenied carrying UnsupportedVersion where it can still encode one.

2.6.4 Size limit #

A message MUST NOT exceed 65536 bytes in total. A decoder MUST reject a header declaring more, without reading the body, and MUST reject one declaring fewer than the header's own length.

2.6.5 Message type #

The high bit of msg_type marks a message sent by the authority. Client messages have it clear. This is a readability property rather than a security one — a peer MUST validate the message type it received against what it expected, not merely against the direction bit.

2.6.6 Encoding #

All multi-byte integers are little-endian.

Strings are UTF-8 and are not NUL-terminated. A string is encoded as a u32 byte count followed by exactly that many bytes. A decoder MUST reject a string whose bytes are not valid UTF-8.

An empty string and an absent optional string are encoded identically, as a zero byte count. A field documented as optional is therefore absent when empty, and an implementation MUST NOT distinguish the two.

Byte strings are encoded the same way and carry no encoding requirement.

Arrays are encoded as a u32 element count followed by that many length-framed structures. Every array in this chapter has a stated maximum; an encoder MUST refuse to produce a longer one and a decoder MUST reject one it receives. The same holds for every stated byte limit.

Two distinct length mechanisms therefore appear, and confusing them is the most likely implementation error:

• Byte strings and strings are prefixed with a u32 byte count, and the bytes follow immediately.
• Structures and array elements are prefixed with a u32 byte count of the whole structure, and a decoder MUST skip to the structure's declared end after reading the fields it knows.

The second is what makes the format extensible.

2.6.7 Body extensibility #

The body is a single length-framed structure, and every structure and every array element within it is length-framed too.

A decoder reads the fields it knows and then skips to the structure's declared end. A field appended by a newer peer is therefore stepped over rather than mistaken for the next field — which is what makes the format extensible inside arrays, where ignoring trailing bytes at the message level would not help.

A structure that ends before a field an older encoder never wrote is not an error. A decoder that reaches the end of a structure's body where an optional trailing field would have been MUST substitute that field's documented default (§2.7, §2.9) rather than failing.

The rules this keeps working under are binding on anyone revising this chapter:

• Fields are appended only. Never reordered, never removed, never changed in meaning.
• A new field MUST be optional with a safe default, because older peers will not send it and will not read it.
• Adding a value to an enumeration is a breaking change and requires a version bump, because every peer is required to understand every value it is sent.

The last rule is the one that surprises people. An unknown enumeration value cannot be safely ignored: a client that skipped an unrecognised credential type would silently fail to collect something the authority required, and an authority that skipped an unrecognised logon type would grant the wrong kind of session.

There are exactly four exceptions, and each is stated where it applies: LogonStart.supported_credential_types, which is a statement of capability rather than an instruction (§2.7); LogonStart.logon_type, which only the authority ever receives (§2.7); the field mask of Lookup, whose reply says which bits it answered (§2.16); and a denial code that only ever answers a message newer than every peer that does not know it, so that no such peer is ever sent it (§2.B, §2.22, §2.23).

2.6.8 Initial unpublished layout replacement #

The coordinated SSH credential extension replaced the unpublished version-1 layout without retaining older codecs. Current LogonStart capability, required-method and binding fields, Prompt parameters, and all current Assertion fields are mandatory, including explicit empty/zero values. Omitted mandatory fields fail decoding. The compatibility rules above apply to future extensions of this replacement contract; they do not require accepting the superseded development layout. See PGSS Logon §2.D.

msg_type = 0x0001. Client to authority. Opens the conversation; MUST be the first message.

2.7.1 Layout #

Everything here is asserted by the client, and §2.4 governs all of it.

2.7.2 logon_type #

The kind of session the client is asking for. A proposal, which the authority MUST constrain against the verified peer — see §2.4.

Values are defined by KACS and listed for reference in §2.B.

2.7.2.1 The exception this field carries #

A value MAY be added to this enumeration without a version bump. This is the third departure from §2.6, and it turns on the same question that rule turns on: which party has to understand the value. The rule binds because every peer must understand every value it is sent, and logon_type only ever travels client to authority. The authority is therefore the only party that must understand a new one.

An authority MUST refuse a logon_type it does not recognise, with MalformedRequest (§2.10). A message carrying a value the authority cannot name is one it could not understand, and it is refused before any question of what the peer is permitted arises.

Neither direction of mismatch is left to chance by that. An older client never proposes a value it has not heard of, and a newer client proposing one to an older authority is refused — so the failure is no session rather than a session of the wrong kind, which is the outcome §2.6 exists to prevent.

2.7.3 identifier_type and identifier #

Together these name the principal. identifier_type says how to read identifier; identifier is opaque bytes, not a string.

Bytes rather than a string because an identifier is not always text. A certificate thumbprint, a smartcard serial, or a binary principal name are all reasonable identifiers, and a protocol that insisted on UTF-8 would exclude them. An authority that expects text MUST validate the encoding itself.

An identifier MAY be empty. An empty identifier means the principal is not named here — the authority is expected to determine it from the credential, as with a smartcard that carries its own identity.

identifier_type is distinct from credential_type (§2.8): this is the claim of identity, that is the proof. A passkey names a principal and proves them in one artefact; a username names them and proves nothing.

2.7.4 tty and remote_host #

Unverified context, both optional, both empty when absent.

tty names the terminal the logon is happening on, where there is one. remote_host names where a network logon came from.

An authority MAY use either in policy and MAY record either in its audit trail. It MUST NOT treat either as established. A client that lies about them is not prevented from doing so.

2.7.5 supported_credential_types #

Every credential type this client can render, one byte each.

This is the client declaring its capabilities, and it is binding on the authority: an authority MUST NOT send a prompt for a credential type absent from this list (§2.8).

A client that supports nothing sends an empty list. That is meaningful rather than degenerate — it says "I can complete a logon that requires no interaction, and nothing else" — and an authority MUST either complete the logon without prompting or deny it.

2.7.5.1 Mandatory capability and method fields #

The capability list and following method/binding fields are mandatory in the current unpublished version-1 layout. Missing tails are malformed; there is no absent-field Password default. An explicit empty list means that the client cannot collect a credential.

A nonzero required method must appear in the capability list. The authority rejects any source assertion that did not authenticate with that method. The SSH binding is present exactly when SshPublicKey is advertised. It is an enclosing length-framed structure containing 16 raw connection-ID bytes, a session-identifier byte string (16–64 bytes), and a UTF-8 username (1–256 bytes, no controls), equal to the Username identifier byte for byte. Only the authorized SSH monitor may supply it; see §2.D.

An unrecognised value is dropped, not refused. A decoder MUST discard a credential type it does not recognise and proceed with the rest, leaving the intersection of what the client claims and what the decoder understands. This is safe here and nowhere else, because the field is a statement of capability rather than an instruction: an authority that ignores a type it has never heard of merely declines to use it, which is the correct outcome.

Without this, a client that learned a new credential type could not speak to an older authority at all — the authority would be obliged by §2.6 to refuse the whole message. The capability list exists precisely so that an authority using a new type cannot reach an older client; it would be self-defeating if a client using a new type could not reach an older authority either.

2.8.1 CredentialRequest #

msg_type = 0x8001. Authority to client.

Message:

Prompt:

Both arrays MAY be empty.

2.8.1.1 Messages #

Text for the principal to read, before any prompt is presented. "Your password expires in three days"; "Authenticating against the local source".

A client MUST display messages it receives, in order, before the prompts in the same request. It MUST NOT interpret them, and MUST NOT vary its behaviour on their content.

2.8.1.2 Prompts #

Each prompt asks for one piece of credential material.

credential_ref identifies the prompt within the conversation. The client echoes it back unchanged in its answer. It MUST be unique among the prompts of a single request. An authority MAY reuse a value in a later round.

credential_name is what to show the principal — "Password", "Verification code". It is a display string. A client MUST NOT branch on it; credential_type is what says how to collect the answer.

2.8.1.3 The client capability rule #

An authority MUST NOT send a prompt whose credential_type is absent from the client's supported_credential_types (§2.7).

This is a hard requirement rather than a courtesy. A client that receives a prompt it cannot render has no good option: failing the logon punishes the principal for a mismatch neither party chose, and guessing — collecting a line of text for a credential type that is not a password — may echo a secret to the screen. An authority that cannot proceed within the client's declared capabilities MUST deny the logon instead.

A client that nevertheless receives an unrenderable prompt MUST fail the conversation rather than guess.

2.8.1.4 Empty requests #

A CredentialRequest with no prompts is valid. It carries messages only, and the client MUST answer it with a CredentialResponse carrying no answers. This is how an authority conveys information mid-conversation without asking for anything.

2.8.2 CredentialResponse #

msg_type = 0x0002. Client to authority.

Answer:

credential_ref MUST match a prompt from the request being answered. data is the material the principal supplied — opaque bytes, no encoding implied.

A client SHOULD answer every prompt it was given. An authority MUST NOT assume it has: a missing answer is a failed logon, not a protocol violation, and MUST be treated as such rather than as grounds to tear down the connection.

An authority MUST match answers to prompts by credential_ref and MUST NOT rely on ordering.

Both parties encode and decode this message under the obligations of §2.12. The encoded message holds the credential just as much as the data field inside it does.

2.8.3 Typed parameters #

Prompt parameters are mandatory, empty for Password, and carry the bounded SshPublicKey disposition structure described in §2.D. They are protocol input to the matching collector, never instructions to render or execute. An ordinary password client must refuse an unsupported SSH prompt.

msg_type = 0x8002. Authority to client. One of the two terminal messages; nothing follows it.

Ancillary data: the token, as one file descriptor via SCM_RIGHTS.

2.9.1 The descriptor #

The token MUST be transferred as a file descriptor attached to this message. It MUST NOT be named, and there MUST be no path, handle, or identifier by which another process could reach it.

Possession of the conversation is what confers the token. There is no window in which a minted token exists under a name something else could open, and no lookup that could be raced or guessed.

A client MUST read the descriptor from the ancillary data of this message. An AccessGranted arriving without one is a protocol violation and MUST be treated as a failed logon — a client MUST NOT proceed as though a logon succeeded when it holds no token.

2.9.2 session_id #

The logon session the token belongs to. The client MAY record it, MAY report it, and needs it to relate this logon to the kernel's session records.

It is informational to the protocol. The token is the thing that confers authority; the session identifier merely names the session the token already belongs to.

2.9.3 profile #

Where the session starts, and what to call the principal. A length-framed structure, so it can grow without displacing anything appended to AccessGranted after it.

profile is an optional trailing field. Every field may be empty, and an empty field means the authority did not say. An authority that knows nothing about home directories is conforming, and so is one that omits the whole structure — a client MUST treat an absent profile exactly as it treats one whose fields are all empty.

A client MUST have a fallback for each field and MUST NOT treat an empty value as an error.

home and shell, when non-empty, MUST be absolute paths. A client MUST NOT execute a relative shell or resolve a relative home against its own working directory. An authority with no value for a field MUST leave it empty rather than invent one.

2.9.3.1 Why this is on the terminal message #

Nothing here is an access-control input. No ACL names a home directory, and the token carries none of these fields — so this is not identity, and an authority that got it wrong would produce an inconvenient session rather than an unsafe one.

It is here because the authority has just read these values in order to decide the logon, and a caller that needs them in order to start a session would otherwise have to ask a second time. A logon originator cannot chdir or exec without them.

2.9.3.2 What this is not #

It is not a directory lookup, and it MUST NOT be treated as one. It answers for exactly one principal — the one who just authenticated — at exactly one moment. It cannot answer for anybody else, it cannot answer for a principal who never logged on, and nothing in this protocol says what it means an instant later.

Resolving arbitrary principals to home directories or shells is §2.16's, and a client that caches these values as though they had come from there has misread them.

2.9.3.3 display_name #

A human's name for a human to read.

It is deliberately not a GECOS field. GECOS is a comma-separated /etc/passwd artefact carrying a name, an office, and two telephone numbers in one string; a protocol that carried one would oblige every client to parse it apart, and would tie this chapter to a file format it has nothing to do with.

An implementation that must produce a GECOS field renders it from this, not the other way round.

2.9.4 What the client does next #

Installs the token, if that is what it wanted. The authority is not involved and MUST NOT be told (§2.1).

A client that decides not to install the token MUST close the descriptor. A logon session whose token is never installed still exists as far as the kernel is concerned.

A client SHOULD NOT fail a logon because a home it was given does not exist. The principal has authenticated and holds a token; refusing to start their session over a missing directory turns a cosmetic problem into being locked out. Starting elsewhere and saying so is the better failure.

msg_type = 0x8003. Authority to client. The terminal failure message of a logon, of a credential change (§2.20), of an enrolment (§2.23), and of a request to end a logon session or to ask whether one may (§2.22) alike; nothing follows it.

2.10.1 denial #

A code from a deliberately small vocabulary (§2.B), for a client that needs to act differently — retry, offer a different account, report a system fault.

PermissionDenied and LogonTypeNotPermitted are distinct on purpose: the first says the peer may not use this socket for this at all, the second that it may originate logons but not of this kind. A client can act differently on each.

NoSuchSession answers only SessionEnd and SessionEndQuery, and only a caller who would otherwise have been permitted (§2.22). Anybody else is told PermissionDenied, so the code cannot be used to learn which sessions exist.

CredentialRejected answers only CredentialEnrollStart, and says the credential offered or named was refused, not the principal's proof of who they are (§2.23).

2.10.2 reason #

Text for the principal to read. A client SHOULD display it and MUST NOT interpret it.

The division is the same one CredentialRequest makes between credential_type and credential_name: the machine-readable field is small and stable, the human-readable one is free.

reason MUST NOT narrow an AuthenticationFailed into a specific cause.

2.10.3 What a denial must not reveal #

The denial vocabulary deliberately does not distinguish "no such principal" from "wrong credential". Both are AuthenticationFailed.

A protocol that distinguished them would make account enumeration a supported feature: anyone able to reach the socket could test names and learn which exist. An authority MUST NOT provide that distinction through the denial code, through reason, or through observable timing.

The timing obligation is the one most often missed, and it binds even though this chapter cannot check it. An authority whose unknown-principal path returns faster than its wrong-credential path has published the distinction it just declined to state — see §2.12.

A credential type tells a client how to collect an answer. It does not tell it what the answer means.

The registry is deliberately short. A type is added when a client would need to collect something differently, not when an authority acquires a new way of checking something.

2.11.1 Adding a type #

The initial unpublished type-2 extension replaced the version-1 layout and all consumers together (§2.D). Future incompatible changes to a published contract require the version discipline in §2.6.

An authority MUST NOT send a prompt for a type absent from the client's supported_credential_types, so an authority using a new type simply cannot reach an older client — which is the correct outcome, and is why the capability list exists. The converse — a newer client reaching an older authority — is what the dropping rule in §2.7 exists for.

2.11.2 Why passwords cross the local socket in the clear #

Passwords travel this local socket as plaintext. SSH public-key authentication instead carries public keys and signatures; private keys never cross it. Remote SSH transport encrypts both authentication methods. The local password choice allows the source to retain a memory-hard password verifier without storing a password-equivalent secret.

Challenge-response requires the verifier to store something it can recompute the response from: either the plaintext, or a value that is password-equivalent. NTLM works exactly this way — the stored hash is as good as the password, forever, which is why pass-the-hash has been the most valuable credential on a Windows network for twenty years.

A modern verifier — argon2id and its relatives — is deliberately not password-equivalent and cannot answer a challenge. That is the property that makes stealing the store meaningfully weaker than knowing the passwords.

So challenge-response would trade a permanent weakness at rest for protection of a channel that is not the weak point. Anyone able to read this socket can already ptrace the process holding the password.

2.11.2.1 What would change the answer #

A PAKE — OPAQUE, SRP — gives both properties at once: nothing password-equivalent at rest, and no plaintext on the wire. It is worth revisiting if an authority ever authenticates across a network without TLS.

It is not worth its complexity for a local, kernel-mediated socket, where the threat it defends against is already able to do worse.

2.11.2.2 What follows #

Because plaintext crosses the wire, bounding how long it survives becomes an obligation of both roles rather than a nicety. See §2.12.

These bind both roles. They are stated normatively because plaintext on the wire (§2.11) is only defensible if its lifetime is short.

2.12.1 Bounding lifetime #

An implementation MUST hold credential material in memory that is erased before it is released, and the erasure MUST NOT be removable by an optimising compiler.

The obligation extends to the encoded message, not only to the credential field. A CredentialResponse holds the password just as much as the answer inside it does, and a buffer wiped at one level while another copy is dropped unerased achieves nothing.

An implementation MUST erase:

• the buffer credential material was read into;
• any buffer it was copied into during encoding or decoding, including an intermediate allocation abandoned by a buffer that grew;
• any structure holding it once the conversation reaches a terminal state.

The middle clause is the one an implementation is most likely to miss. A growable buffer that reallocates while a message is being encoded leaves a complete copy of everything written so far in the abandoned allocation, and erasing the buffer that survives does not touch it. Reserving the encoded size before writing avoids the problem entirely.

2.12.2 What this does not promise #

It guarantees that these buffers are erased before their memory is reused. It cannot guarantee anything about copies made elsewhere — a string the caller parsed a credential out of, a register or stack slot the optimiser chose, a terminal's own input buffer. Those belong to whoever made them.

Nor does it defend against a hostile kernel, a core dump, or swap. Those are addressed elsewhere: process integrity protection, and disabling core dumps for the authority.

2.12.3 Logging and diagnostics #

An implementation MUST NOT write credential material to a log, an audit record, an error message, or a debugging aid.

A type carrying credential material SHOULD render, under whatever debug formatting its language provides, as a redaction rather than as its contents. A stray diagnostic print is the most common way material escapes a process that was otherwise careful, and the defence is to make the careless thing produce nothing useful.

2.12.4 Collection #

A client MUST collect a Password without echoing it. Where it cannot establish that echo is suppressed, it MUST NOT collect the credential anyway.

A client MUST NOT silently truncate an answer. data admits 32768 bytes (§2.8); a client whose collection method admits fewer MUST fail the conversation rather than send a prefix of what the principal supplied, which would present as a wrong credential and leave the remainder in whatever buffer it was read from.

2.12.5 Timing #

An authority MUST NOT allow the time it takes to reach a denial to distinguish an unknown principal from a bad credential (§2.10).

This is more demanding than it looks with a memory-hard verifier, because the natural implementation returns immediately when a principal does not exist and spends tens of milliseconds when one does. An authority MUST perform equivalent work in both cases — verifying against a decoy verifier that no credential matches is the usual construction.

Sections 2.3 to 2.12 specify how a caller obtains a token. The remainder of this chapter specifies how any program on the system turns an identity it already holds into something it can display or compare: a name into a SID, a SID into a name, a POSIX identifier into either.

It exists because a Linux program calls getpwuid and has never heard of a token. Without this surface, every principal an authority mints appears throughout the system as a bare number.

2.13.1 Why the authority answers this #

An authority may federate identity to separate sources, and a source counts POSIX identifiers relative to a range the authority assigns it. The authority adds the base. No message in either direction carries an absolute identifier to or from a source: a source asserts relative numbers, and is asked by relative number or by SID.

The arithmetic that makes a number absolute therefore exists in exactly one place, and only that place can invert it. No source can be asked "who is uid 1001000", because no source is ever asked an absolute number at all. The authority is not merely a convenient place to put this — it is the only party the protocol permits to answer.

The same holds for names. A bare name may exist in more than one source, and which one wins is a property of the system rather than of any source in it (§2.15).

2.13.2 A second socket, not a second standard #

Identity lookup is served on /run/ident.sock (§2.14), separately from /run/logon.sock, by the same authority speaking the same framing (§2.6).

The separation is not for isolation. One authority answers both, so a defect or a hang in either reaches the other regardless; a second socket buys nothing there and this chapter does not pretend otherwise.

It is for admission. A listening socket has one accept queue. A single directory listing is thousands of lookups and a filesystem walk is millions, where logons are a handful per boot — so a shared socket would let an ordinary find fill the queue that an administrator needs in order to sign in and stop it. Two sockets means the two populations of caller cannot starve each other, whatever load either is under.

The second reason is access control. The set of programs that may originate a logon is small and enumerable; the set that may look up a name is every program on the system. Those want different security descriptors, and a descriptor is a property of a socket.

2.13.3 Not a conversation #

A logon is stateful: the connection is the conversation, and needs no correlation identifier (§2.5).

A lookup is not. Requests are independent, a connection carries as many as a client cares to send, and replies MAY return in an order other than the one requests arrived in. Each request therefore carries a tag that its reply echoes (§2.14).

2.13.4 Not authentication #

No credential ever crosses this socket. There is no message with which a client could offer one and none with which an authority could ask.

Everything here returns the kind of data a POSIX system has historically kept in a world-readable file. An authority MAY nonetheless restrict individual fields (§2.16), and the request names the fields it wants precisely so that it can.

2.13.5 Not in this version #

Privileges, integrity levels, owner and default DACL are not returned by any message here. They are not identity: nothing stores them, and an authority computes them from local policy at the moment it derives a token (§2.1).

They are, however, deliberately reserved rather than excluded. An authority that cannot be asked what a policy would produce can only be verified by signing someone in and observing the result. A future revision is expected to add a distinct request of the shape:

Evaluate { key, logon_type } -> { privileges, integrity, owner, default_dacl }

— a token that is derived and then discarded. It is parameterised by logon type because the answer genuinely depends on it: an authority adds SIDs reflecting how a principal signed in (§2.16), so "what privileges does this principal have" has no single answer.

A revision MUST NOT instead add privileges or integrity as fields of Lookup (§2.16). A field of a record describes something a source holds; this does not.

2.14.1 Socket #

An authority MUST listen on a SOCK_STREAM Unix domain socket at:

/run/ident.sock

The path is normative, for the same reason /run/logon.sock is: a name resolver linked into every process on the system cannot be asked to find it by configuration.

An authority MUST listen on both sockets. Offering one without the other is not conformance — a system whose principals cannot be named is as broken as one whose principals cannot sign in.

2.14.2 Access control #

The socket MUST carry a security descriptor granting connect access to every principal that runs ordinary programs.

This is the opposite posture to /run/logon.sock, and deliberately so. A descriptor that withheld connect access would not protect anything: it would make ls -l print numbers for the principals it excluded, while a principal who can connect learns the same names either way. Restriction, where an authority wants it, belongs on individual fields (§2.16) — not on reaching the socket at all.

2.14.3 Framing #

Messages use the header, magic, version, size limit and body extensibility rules of §2.6 without modification. The message types served here are disjoint from those of the logon socket (§2.A).

A message of one socket's range arriving on the other MUST be refused. An authority MUST NOT serve a Lookup received on /run/logon.sock, and MUST NOT serve a LogonStart received on /run/ident.sock.

2.14.4 Multiplexing #

A connection carries any number of requests. A client MAY have more than one outstanding at a time, and an authority MAY answer them in any order.

Every request carries a tag, a u32 chosen by the client, and its reply carries the same value. The tag is in the message body, not the header, so that the header of §2.6 is unchanged.

A client MUST NOT reuse a tag while a request bearing it is outstanding. An authority MUST echo the tag it received and MUST NOT interpret it otherwise.

A client MUST NOT assume replies arrive in request order. An authority that answers strictly in order is conformant; a client that depends on it is not.

2.14.5 Concurrency and bounds #

An authority MUST serve connections concurrently, and MUST NOT let a slow answer on one connection delay answers on another.

An authority MUST bound the number of connections it will accept and the number of requests it will hold outstanding per connection, and SHOULD refuse further requests on a connection that exceeds the second rather than closing it.

An authority MUST NOT wait indefinitely for a source. A request that cannot be answered within the authority's own bound MUST be answered Unavailable (§2.18). The bound is on the request, not on each source consulted: an authority that walks several sources in turn MUST NOT let the total exceed what it would have allowed one.

2.14.6 No descriptor passing #

Nothing is transferred over this channel by descriptor. An authority MUST ignore ancillary data received here.

2.14.7 Peer identity #

An authority that restricts any field (§2.16) MUST establish peer identity from the connected socket's peer token, as §2.4 requires, and MUST NOT take it from a message body.

An authority that restricts no field MAY skip establishing peer identity, since it would make no decision with it.

2.15.1 The name is opaque to the client #

A name is carried as a single string. A client MUST forward what it was given, unchanged, and MUST NOT parse, split, qualify, case-fold, or otherwise interpret it.

All interpretation is the authority's.

This is the load-bearing rule of the section. If a client resolved part of a name itself — chose which source to consult, or which of two candidates wins — then that policy would live in every client separately, and a native tool could resolve jack to a different principal than a POSIX name resolver on the same machine. Two components disagreeing about who a name refers to is not a display inconsistency; it is a program acting on one principal's behalf while checking another's access.

One authority means one answer, and it means a name resolves identically here and in a logon (§2.7), because the same resolution serves both.

2.15.2 Comparison #

Name comparison is ASCII case-insensitive.

This is normative rather than each source's own choice, because a system may have more than one source and they must not disagree about whether JACK is jack. An authority MUST establish the comparison for itself rather than delegate it to whatever a source happens to do.

2.15.3 Reserved characters #

A principal or group name MUST NOT contain any of:

A name MUST NOT contain a byte outside the printable ASCII range 0x20–0x7e, and MUST NOT begin or end with a space.

An authority MUST refuse to create a name violating these rules, MUST refuse one it is asked to resolve, and MUST refuse one asserted by a source. The third is the one that matters: a name reaching a caller from a source has crossed a boundary the other two never did, and it is the one that ends up in a passwd-format record, an audit line, or a log.

The excluded control characters are the record separators. A name carrying a newline could forge a whole line in a passwd-format file, an audit record, or a log — and the damage is done by the reader, so it cannot be prevented at the point the name is displayed.

The rules apply to every name an authority emits, including the names carried alongside SIDs in references (§2.16), not only to the name a request was keyed on.

2.15.4 Qualified names #

A name MAY be qualified with a realm, written name@realm.

No realm syntax is defined in this version. An authority MUST refuse a name containing @, and the character is reserved so that a principal literally named jack@local cannot come into existence before the syntax does.

Nothing here changes when realms arrive: a qualified name is a different string in the same field, parsed by the same authority. That is why the field is one opaque string rather than a structured pair — a structure would have put the parsing in the client, which the first rule of this section forbids.

2.15.5 Search order #

A bare name is resolved by consulting sources in an order that is local configuration of the authority.

An authority MUST resolve in a configured order, MUST NOT derive that order from the order in which sources registered, and MUST stop at the first source that answers.

2.15.6 Answers an authority holds itself #

An authority MAY answer from its own knowledge, without consulting any source. Well-known principals and groups — those whose SIDs are fixed by the system rather than issued by anybody — are the ordinary case: their names, and, for those whose membership is a rule, the fact that nothing records it (§2.16), are properties of the system. Who is in a BUILTIN group is not: it is recorded by the sources, and asked of them (§2.16).

Such an answer is subject to every rule in this section. In particular an authority MUST apply the reserved-character and comparison rules to it, and MUST NOT return an answer for a name it would have refused.

An answer of this kind is not an outage and does not make a reply Unavailable, whatever the state of the configured sources. It is also not a source: an authority MUST NOT report it in the incomplete list of an enumeration (§2.17), and MUST NOT count it as a source having answered for the purpose of §2.18.

2.15.7 Bare in, qualified out #

Every successful reply carries the resolved SID and the canonical qualified name, whatever form the request used (§2.16).

A caller that looked up a bare name can therefore always tell which principal it got, compare two answers for identity, and record an unambiguous name in a log. Ambiguity is permitted in what a caller may ask; it is not permitted in what an authority answers.

Where no realm syntax exists, a canonical qualified name is indistinguishable from a bare one, and the SID alongside it is what carries the unambiguity. A client MUST NOT rely on the two being distinguishable, in either direction: it MUST NOT assume a returned name is unqualified, and MUST NOT treat one that is as a failure to canonicalise.

2.15.8 Shadowing #

Adding a source ahead of another in the search order changes which principal a bare name resolves to. The new principal has a different SID, so every security descriptor naming the old one stops applying to the person now signing in under that name.

This is inherent to a flat namespace and this chapter does not forbid it. An authority SHOULD detect it at logon — where the cost is one additional query per sign-in rather than one per lookup — and SHOULD record that a bare name resolved while another source could also have answered.

An authority MUST NOT fail a logon because it could not complete that check. A source being unreachable is not a reason to refuse a principal whose own source answered.

One request answers every question a name resolver asks.

2.16.1 Lookup #

msg_type = 0x0010. Client to authority.

Exactly one of name, sid and unix_id is meaningful, selected by key_type. An encoder MUST leave the others empty or zero, and a decoder MUST ignore them.

2.16.1.1 key_type #

UnixId is a key even though no source is ever asked one. An authority converts the number to a source and a relative identifier by the range arithmetic it assigned, and asks that source by relative identifier or by SID.

A source therefore never receives an absolute number here, exactly as it never receives one during a logon. The property that made the authority the only possible answerer (§2.13) is the same property that keeps this side of it confined.

2.16.1.2 kind #

A request for Principal MUST NOT be answered with a group, and a request for Group MUST NOT be answered with a principal. Where the key matches only an object of the other kind, the outcome is NotFound (§2.18).

An authority MUST establish this for itself. Where the object came from a source, the authority MUST check the kind it received against the kind that was asked for, rather than relaying the source's answer and letting the client discover the mismatch.

2.16.1.3 fields #

A bitmask of the attributes the reply should carry. Identity is not among them: every successful reply carries the SID, the canonical qualified name, and the kind actually found, and a client cannot decline them.

An authority MUST ignore a bit it does not implement, and MUST NOT report it (below). Claim entries use the claim attribute format PCDS §5.9 specifies.

LOGON_TYPES is a bitmask over the logon type values of §2.B: bit n set means the principal may be used for logon type n. Zero means the holder states nothing, not that nothing is permitted — a source that predates the field sends zero, and an authority that read that as "no logon permitted" would lock every principal on every existing system out at once.

An authority substituting a default for zero MUST NOT include Service in it. A principal that has never said how it may be used has certainly not said it may be used for a credential-free service logon (§2.19).

DESCRIPTION says what a group is for, in words for a person to read, on one line. A group with none is answered with an empty string: it has no description, which is an answer. A principal has none, and the field is withheld as Absent (below). An authority answers it for its own well-known groups as well as relaying a source's.

Requesting only what is wanted is not primarily a bandwidth measure — a getpwuid wants nearly every field anyway. It matters for the caller that resolves a dozen SIDs to render a security descriptor and wants only names, and it is the seam at which an authority can restrict individual fields without restricting the socket (§2.14).

2.16.2 LookupReply #

msg_type = 0x8010. Authority to client.