Peios Security Fundamentals

Every action on a running Peios system happens on behalf of a principal — a user, a service, a machine, or a well-known system actor. Identity is the unit of policy: every access decision starts with "who is asking?", and the kernel answers that question the same way for files, registry keys, processes, sockets, and tokens themselves.

The shape of an identity #

Identity in Peios has four layers, each with a clear job.

These four words appear throughout the Peios documentation, and they are not interchangeable. A principal is the long-lived thing in the directory; a SID is its name; a token is its instance for one run; a session is what produced that token.

How an identity gets into the kernel #

flowchart LR
    A["Principal"] -->|"identity asserted by"| B["Principal source"]
    B -->|"verified identity"| C["authd"]
    C -->|creates| D["Logon session"]
    C -->|mints| E["Token"]
    E -->|installed on| F["Process"]
    F -->|"presents at every syscall"| G["Access decision"]

When a user signs in, authentication happens in three steps:

1. A principal source verifies the credential and asserts who the principal is — the local principal source for this machine's own accounts, or a directory-backed source on a domain-joined machine.
2. authd, the authentication authority, creates a logon session: a kernel object that records the authentication event (who, how, when).
3. authd mints a token carrying the user's SID, group SIDs, integrity level, privileges, and a reference to the session. The token becomes the user's runtime identity — and its privileges and integrity level come from this machine's policy for the principal, not from the source that identified them.

The client that requested the logon — login on a console, for example — installs the token on the session's first process, and every child process inherits it across fork. Threads that need to act on behalf of someone else (for example, a service handling a user request) can temporarily swap in an impersonation token while keeping their original — see Impersonation.

The token is the authoritative carrier. Any other identity values a process can observe — including the numeric IDs that surface through standard Linux system calls — are derived from the token, never the other way around. See Linux compatibility for how that projection works.

Identity vs authorisation #

An identity by itself grants nothing. A token says who a thread is; the Kernel Access Control Subsystem (KACS) decides what it can do, by comparing the token against each object's security descriptor. The same token will see different rights on different objects, and the same object will grant different rights to different tokens.

The rest of the security documentation is organised around this separation:

• Identity says "who". This topic, plus Tokens and Logon sessions.
• Authorisation says "what". Security descriptors and Access decisions.

If a request fails unexpectedly, you almost always need to look at both sides: which identity made the request, and which access rule rejected it. Pages in both halves cross-link where the two meet.

What identity does not include #

A few things often get bundled with identity that are kept deliberately separate in Peios:

• Privileges are not identity. A token carries a set of privileges, but a privilege gates a specific operation (loading a driver, taking ownership of an object), independent of who you are. See Privileges.
• Integrity level is not identity. It is a separate axis on the token that controls write-up restrictions. Two users at different integrity levels are still two distinct identities; the integrity level is an additional constraint on top.
• Process integrity (PIP) is not identity at all. PIP is a property of the binary the process is running, set by the kernel from the binary's signature. It controls who can inspect or signal the process, independent of who the process is acting as. See Process integrity protection.

These distinctions matter because they fail in different ways. An "access denied" caused by the integrity level looks like an identity problem but is not.

Where to start #

If you want to understand how SIDs are constructed, read SIDs. For the catalog of built-in principals and their fixed SIDs, read Well-known principals.

If you want the typed attributes a token carries beyond identity — the inputs to attribute-based access decisions — read Claims on a token.

If you want the runtime mechanics — how a token is composed, how it survives fork and exec, and how it gets adjusted — read Tokens.

If you are debugging an unexpected denial, the Inspecting tokens, sessions, and processes topic shows how to see the identity attached to any running thread.

A SID (Security Identifier) is the unique name for a principal. Every user, group, service, machine, and well-known system actor has exactly one SID, and that SID is how every other part of Peios refers to them: ACEs in a security descriptor name SIDs, tokens carry SIDs, audit events log SIDs.

Two SIDs are equal only if their binary encodings match byte-for-byte. There is no normalisation and no case folding. A SID is its bytes.

The string form #

The form you will see in logs, configuration, and almost every administrative tool is the string form:

S-1-5-21-3623811015-3361044348-30300820-1001

The pieces:

A SID has between 1 and 15 sub-authorities. Most have between 1 and 7. The RID is just whatever sub-authority comes last; "RID" is a name for its role in domain SIDs, not a separate field.

When the authority is written in hex #

The identifier authority is a 48-bit value. When it fits in 32 bits — which it does for every authority Peios uses — it is written in decimal. If the upper 16 bits are nonzero, the authority is instead written as a 0x-prefixed 12-digit hexadecimal value:

S-1-0x000000123456-1-2-3

You will not see this form in practice on Peios. It exists for parity with external systems that allocate from the upper authority range.

The binary form #

On the wire (in security descriptors, in tokens, in audit events), a SID is a packed byte structure:

+----+----+----+----+----+----+----+----+
| 01 | NN | AA   AA   AA   AA   AA   AA |
+----+----+----+----+----+----+----+----+
| sub_1 (4 bytes, little-endian)         |
+----+----+----+----+----+----+----+----+
| sub_2 (4 bytes, little-endian)         |
+----+----+----+----+----+----+----+----+
|                  ...                   |
+----+----+----+----+----+----+----+----+
| sub_N (4 bytes, little-endian)         |
+----+----+----+----+----+----+----+----+

The first byte is the revision (0x01), the second the sub-authority count, then the six-byte authority, then the sub-authorities. The canonical byte-level layout is in the wire formats reference, under "SIDs in wire format".

The mixed endianness — big-endian for the authority, little-endian for the sub-authorities — is the one detail worth memorising. The rest of KACS is uniformly little-endian; the SID authority is the exception, for compatibility with the way SIDs travel across federation boundaries.

A SID is between 8 bytes (no sub-authorities, very rare) and 68 bytes (15 sub-authorities) long.

Comparison #

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

This rule has consequences worth knowing:

• The string form is for humans. Two strings that look equivalent might not encode to the same bytes if one was reconstructed by hand and got a leading zero wrong, or if one used hex authority where decimal would do. Always compare in binary.
• There is no case folding. SIDs do not contain letters in their numeric form, so this rarely matters, but tools that print SIDs alongside resolved names — for example BUILTIN\Administrators for S-1-5-32-544 — must compare the SID, not the name.
• The kernel only compares for equality. When KACS matches a SID in an ACE against the SIDs in a token, it tests the full encoded bytes for equality — there is no "same domain" or "prefix match" at the access-check level. Userspace tooling can parse SIDs and compare them structurally for its own purposes (listing all users in a domain, filtering by authority, reporting), and is expected to. That parsing is on top of the byte representation; the underlying bytes are still what define identity.

If you are writing code that handles SIDs, store them as their binary form whenever possible and convert to strings only at the UI boundary.

SID patterns you will recognise #

The sub-authorities of a SID encode meaning by convention, not by parse rule. A few patterns appear so often that you will start to recognise them by shape:

The full catalog of named SIDs is in Well-known principals. The derivation rules for service SIDs and capability SIDs — where the hash values actually come from — are documented under their respective topics.

What a SID does not tell you #

A SID identifies a principal but says nothing else about them. From a SID alone you cannot tell:

• Which groups the principal is a member of (the token's group list does that).
• What integrity level the principal runs at (the token's integrity_level field).
• What privileges the principal has (the token's privilege bitmask).
• Whether the principal is currently logged in (the logon session does that).

A SID is just the name. Everything else about a principal lives somewhere else — usually on the token that carries the SID at runtime.

Where to go next #

For the catalog of SIDs whose values are fixed by the system — Everyone, SYSTEM, the BUILTIN aliases, and the rest — read Well-known principals.

For the typed attributes that travel alongside SIDs on a token, read Claims on a token.

For how a SID is carried into every access decision at runtime, read Tokens.

A well-known principal is a principal whose SID is fixed by the system rather than allocated when an account is created. Some name a single specific entity (SYSTEM, Anonymous). Some name a category (Everyone, Authenticated Users). Some are placeholders that get rewritten during inheritance (CREATOR OWNER). All of them have the same purpose: they let you write ACEs that target a role without naming a specific user.

You will recognise the common ones quickly; the full catalog exists so you can look up the rest when they appear in an audit log or an ACE.

How to read the catalog #

Each well-known SID has a fixed numeric value, a conventional name, and a defined behaviour during access checks. Some of them are not real principals at all — they are placeholders or labels that the access check treats specially. Where that distinction matters, it is called out.

The catalog is organised by SID authority, because that is how the SIDs are structured and how you will tend to recognise them.

Universal SIDs (S-1-0, S-1-1, S-1-2, S-1-3) #

These authorities are defined globally — not tied to any specific machine or domain — and exist for cross-system meaning.

The placeholder SIDs (S-1-3-0 and S-1-3-1) are the trickiest. They never grant or deny anything at access-check time. Their job is to make inheritable ACEs portable across owners — you write an ACE that grants WRITE to Creator Owner, and when a child object is created, that ACE is rewritten to grant WRITE to whoever owns the child.

NT Authority SIDs (S-1-5) #

This is the largest group of well-known SIDs and where most of the principals you will use day-to-day live.

Logon classifiers #

The pair S-1-1-0 (Everyone) and S-1-5-11 (Authenticated Users) is the most common distinction worth getting right. Everyone includes Anonymous; Authenticated Users excludes it. Anything reachable by Anonymous is reachable by an unauthenticated network peer, which is almost never what you want.

A remote desktop logon puts both S-1-5-4 and S-1-5-14 on the token. That pairing is what makes "only someone physically at the machine" expressible: the user counts as an interactive user in every ACL that was ever written, and can still be told apart by one that cares. Allow Interactive and deny Remote Interactive, and you have said exactly that — a rule you could not write if remote desktops had a type of their own and nothing else.

A remote desktop logon deliberately does not carry S-1-5-2 (Network), even though the session is reached over a wire. A deny entry beats any allow, so carrying Network would place every remote-desktop user inside every rule that denies access to network logons, with no way to carve them back out. Network says a credential crossed a wire; it does not say a screen did.

System actors #

Built-in aliases #

The sub-authority 32 under NT Authority is the "BUILTIN" domain, which holds aliases for common administrative roles. The full alias list includes a few dozen entries; the ones you will see most often:

Logon sessions and domains #

The full set of reserved RIDs under S-1-5-21-* follows administrative convention. Domain-specific principals (your actual users) get RIDs allocated above 1000.

Service SIDs #

A SID derived from a service's name, used to grant a service ACL entries independent of the account it runs under.

Service SIDs let you say "grant the loregd service read access to this file" without saying "grant SYSTEM read access" or "grant a specific user read access" — both of which would be too broad.

Mandatory integrity labels (S-1-16) #

These are not principals. They are labels carried in a token's integrity level field and in an object's mandatory label ACE.

These five are the standard, well-known levels. The level is really the SID's single sub-authority as an unsigned integer, compared numerically, so any S-1-16-<n> with exactly one sub-authority is valid — non-standard values such as medium-plus (S-1-16-8448) and protected (S-1-16-20480) appear for Windows interop.

Integrity levels are a vertical axis on top of identity. A user at Medium integrity and the same user at High integrity have the same SID but different integrity labels. See Mandatory integrity control for how the levels interact with access checks.

Process trust labels (S-1-19) #

Like integrity labels, these are not principals. They label processes by signing trust for Process integrity protection.

Common combinations:

Confinement and capability SIDs (S-1-15) #

These are used by Confinement to label sandboxed applications and the capabilities they have been granted.

Confinement domains #

Well-known capabilities #

Derived capability SIDs #

For application-defined capabilities beyond the well-known set, the SID is derived from the capability name:

Special placeholder SIDs #

A few SIDs never appear as a real principal but are recognised by the access check.

These are the cases where a SID in an ACE does not literally mean "match a token whose user SID is this value". They are special-cased by the access check.

Which ones to use in practice #

The catalog above is comprehensive. In practice, day-to-day administrative work touches a much smaller set:

• BUILTIN\Administrators and SYSTEM for default protective DACLs.
• Authenticated Users for "any logged-in user should be able to read this".
• Everyone only when you actually mean "including unauthenticated network peers".
• Creator Owner in inheritable ACEs that should follow the owner of a child object.
• Owner Rights when you want to suppress the owner's default grants on a sensitive object.
• Specific user/group SIDs allocated by the directory (the S-1-5-21-...-RID form) for everyone else.

The remaining well-known SIDs — service SIDs, capability SIDs, integrity labels, PIP labels — show up in specialised contexts that have their own topics in these docs.

Where to go next #

For the attributes a token carries beyond fixed identity — the other input to attribute-based access rules — read Claims on a token.

For the exact numeric values in machine-readable form, see the Well-known SIDs reference.

A claim is a typed key-value attribute that carries information about a principal beyond its identity. The user's department, the machine's compliance status, the time-of-day window for which a session is valid — all of these are claims. They are the raw material that conditional ACEs use to make access decisions about more than just "who is this".

Tokens carry two sets of claims:

• User claims — attributes about the user. Populated at authentication time by authd from the user's directory object.
• Device claims — attributes about the machine. Populated similarly from the machine's directory object.

Both sets are read-only after the token is minted. Adjusting a token's privileges or groups does not touch its claims; only re-authentication does.

What a claim looks like #

A single claim has three things:

• A name — a string, such as Department or Clearance. In conditional expressions the name is qualified by the set it belongs to: @User.Department.
• A value — typed (see below). May be a single value or an array of values.
• A set of flags that control how the claim participates in access checks.

Value types #

A claim's value is always one of:

Mixed-type arrays are not allowed. A claim either holds one STRING, three STRINGs, or one INT64 — never two strings and an integer.

Claim flags #

Each claim carries flags that change how it behaves during access evaluation.

The first two flags (DISABLED, USE_FOR_DENY_ONLY) are the security-relevant ones. They give administrators a way to neutralise a claim (for example, for a logon at a lower trust level) without rewriting the user's directory object.

How claims get onto a token #

flowchart LR
    A["User object"] -->|directory| B["authd"]
    C["Machine object"] -->|directory| B
    B -->|at authentication| D["Token"]
    D -->|user_claims| E["@User namespace"]
    D -->|device_claims| F["@Device namespace"]

When a user authenticates, authd reads:

• The user's directory object — name, group memberships, any attributes the directory schema defines. Anything the schema marks as a claim attribute is copied into the token as a user claim.
• The machine's directory object — same, but for the device. Anything the schema marks as a device claim is copied into the token as a device claim.

Both sets travel with the token for its entire lifetime.

The directory schema decides what is and is not a claim. A claim that is defined in the schema but absent from a specific user object becomes a missing claim on that user's token — not an empty one, not a default value. Conditional expressions distinguish between the two.

Where claims get used #

Claims do nothing by themselves. They are inputs to conditional ACEs — ACEs whose grant or deny is gated by an expression that references attributes.

A conditional expression refers to a claim by namespace and name:

• @User.Department — a claim on the caller's token, user-claims set.
• @Device.Compliance — a claim on the caller's token, device-claims set.
• @Resource.Classification — an attribute on the object being accessed.
• @Local.Time — a per-request attribute supplied by the caller of AccessCheck.

The first two are the token claim sets described above. The last two share the expression syntax but hold different kinds of data:

• @Resource values come from resource attributes in the object's SACL, not the caller's token. See Resource attributes.
• @Local values are supplied by the caller as a per-access-check parameter. They never live on a token. They exist for runtime context that does not fit into a directory.

The full grammar of conditional expressions — comparison operators, the three-valued logic (TRUE / FALSE / UNKNOWN), the way missing claims affect the outcome — lives in Conditional ACEs.

Missing claims fail closed #

One behaviour is worth knowing before you get to the conditional ACEs page: a missing claim is not a failure. A conditional expression that references a claim the token does not carry evaluates to UNKNOWN. UNKNOWN on an allow ACE means "skip this ACE"; UNKNOWN on a deny ACE means "treat this as deny". So a missing claim never accidentally grants access — it can only fail closed.

This is why USE_FOR_DENY_ONLY exists. It is the deliberate version of the same idea: take a claim that grants access and demote it to a claim that can only revoke access.

What claims are not #

A few things claims look like at a glance but are not:

• Claims are not groups. A group is a SID in the token's group list; group membership is presence-or-absence. A claim is a typed attribute with a value. The two appear in different parts of the token and are matched by different parts of an ACE.
• Claims are not privileges. Privileges are a fixed system bitmask gating specific operations. Claims are administrator-defined attributes with arbitrary names.
• Claims are not the audit log. Claims describe the principal; the audit log describes what the principal did. The audit-event subject record does include the principal's claims (so audit consumers can write rules over them), but a claim is not itself an event.

Where to go next #

For how the token that carries these claims is built, adjusted, and destroyed, read Tokens.

For the expression grammar that consumes claims — operators, three-valued logic, worked examples — read Conditional ACEs.

A token is the runtime carrier of identity in Peios. It is a reference-counted kernel object that holds a user SID, group SIDs, privileges, confinement capabilities, and a handful of other policy fields. Every thread on the system has exactly one effective token at any moment, and every access decision starts by reading that token.

If Identity describes who a principal is, the token is the concrete thing that says "this thread is acting as that principal, right now". Tokens appear throughout these docs because they are the input to AccessCheck for files, registry keys, processes, sockets, and the tokens themselves.

What a token contains #

A token is a structured object with around twenty fields. The full field list is covered in Token types and fields; this section sketches the shape so you have a mental model going into the rest of the topic.

Most fields are set once when the token is minted and never change. A few — the enabled state of privileges, the enabled state of groups, the default DACL — are adjustable at runtime within strict rules. None of the identity fields (the SIDs themselves) ever change. See Token types and fields for the exact rules.

Tokens and threads #

flowchart LR
    A["Thread"] -->|primary token| B["Primary token"]
    A -->|impersonation token, when set| C["Impersonation token"]
    B -->|read by AccessCheck| D["Kernel"]
    C -->|read by AccessCheck when in effect| D

Every thread has a primary token — its baseline identity, inherited at fork and shared with every other thread in the process. While the thread is running normally, the primary token is what AccessCheck reads.

A thread may also temporarily install an impersonation token — a second token that overrides the primary for that one thread until it is reverted. Services use impersonation to act on behalf of a client they are handling: accept the connection, impersonate the client, do the work as them, revert. The primary token survives unchanged; only the one thread sees the impersonated identity, and only until it reverts.

Impersonation has its own topic: Impersonation. For this page it is enough to know that a thread can have two tokens at once, and the kernel reads whichever is "in effect" right now.

Where a token comes from #

A token is always minted by code holding SeCreateTokenPrivilege. In a running system that effectively means authd — the authentication authority — which mints tokens once a principal source has verified who is signing in, and peinit, which mints service tokens during boot before authd is up.

The minting flow is straightforward:

1. Authentication succeeds, or a service is being launched.
2. The minting component gathers what the token will carry: the identity and memberships the principal source asserted, and the privileges and integrity level this machine's policy grants the principal.
3. It calls kacs_create_token with the resolved values.
4. The kernel returns a token file descriptor with TOKEN_ALL_ACCESS.
5. The minting component installs the token on the target process (the new login session's first process, or the service binary) and closes the fd.

From that point on the token lives in the kernel, referenced by every thread of every process that inherits it. The original fd is gone; the only handle into the token is through the threads carrying it (and any other process that opens it via /proc/<pid>/token or kacs_open_process_token).

No other component creates tokens. There is no API for an ordinary process to fabricate an identity for itself. A process can ask the kernel to duplicate a token it already has, or filter one to a more restricted version, but the original always comes from authd or peinit. This is deliberate: it is what makes the kernel's "where did this identity come from?" question always answerable.

Tokens are objects too #

A token is itself one of the objects KACS protects. It has a security descriptor of its own, and operations on it (querying, adjusting, impersonating, duplicating, installing) all go through AccessCheck against that SD.

By default, a freshly minted token grants the SYSTEM identity and the creating principal full access, and grants the token's own user identity TOKEN_QUERY and the adjustment rights.

This self-protection is what stops one thread from "stealing" another's identity. Even reading the fields of another process's token requires the PROCESS_QUERY_INFORMATION right on the target process and the relevant token rights on the token itself.

The two token rules to remember #

Almost every confusion about tokens reduces to one of two rules.

Rule 1: A thread always has a token. There is no "no identity" state. A thread that has not been given a more specific token is running on whichever token its process inherited — at the very least, the SYSTEM token from boot. Code that runs before authd is up runs as SYSTEM, which has every privilege. Code that runs after authd is up runs as whichever identity authd assigned. There is no third option.

Rule 2: Identity is the token, not the process. A process does not "have an identity" except through the tokens of its threads. Two threads in the same process can be running as different principals at the same instant, because one is impersonating and the other is not. When you debug an "access denied" question, the answer is in the thread's token, not the process's notional identity.

Where to start #

If you want to understand the token field-by-field — what each value means, when it can change, how it is encoded — read Token types and fields.

If you want to know how a token moves through fork, exec, adjustment, and destruction, read Token lifecycle.

If you are interested in the restricted-token model — the sandbox primitive where a token is intersected with a secondary identity list — read Restricted and write-restricted tokens.

If you need to understand UAC-style elevation — the linked Full/Limited token pair that lets one principal have two tokens for the same session — read Elevation and linked tokens.

To work with tokens from a shell — inspect, adjust, duplicate, restrict, impersonate — read The token command.

Every token in Peios is classified along several axes at once. A given token is either a primary token or an impersonation token. If it is an impersonation token it has an impersonation level. It is either restricted or not. If it is part of an elevation pair it has an elevation type. These are not types in an inheritance sense — they are independent dials, and a token's behaviour is the product of all of them.

This page walks through each axis, then through the token's fields grouped by what they do.

token_type — primary or impersonation #

This is the first and most important classification.

A primary token is the baseline identity of a process. Every process has exactly one. It is inherited across fork — child processes start with a copy of the parent's primary token — and survives exec. When a thread runs without doing anything special, AccessCheck reads its primary token.

An impersonation token is a thread-local override. A thread installs an impersonation token to act as someone else for a span of time, then reverts back to its primary. While the impersonation is in effect, AccessCheck reads the impersonation token instead of the primary. Other threads in the same process are unaffected.

The two types are not interchangeable. Trying to install a primary token as a thread's impersonation, or vice versa, fails. The kernel's kacs_open_self_token and related syscalls return tokens of the correct type for what they were asked to do.

impersonation_level — how far an identity may travel #

Every token carries an impersonation level, and it means the same thing on both kinds: nothing derived from this token may act above it. For an impersonation token that is the level the impersonator acts at. For a primary token it is the ceiling on everything the process can convey — what a peer captures when it connects, what gets attached to a message, what a duplicate can be. The level only ever goes down as identity travels; a fresh CreateToken is the only way back up. See Impersonation levels.

There are four levels, ordered from least to most permissive:

The level is set by the client, on the socket, before connecting. The server cannot raise it. It can only end up with the level the client granted, or lower if other constraints intervene (see Impersonation for the full two-gate model).

The Identification level is a common source of confusion. A frequent bug — in services not written for Peios — is to take a client's token and try to open files as them, finding that every open returns ACCESS_DENIED for reasons the code cannot diagnose. The cause is almost always that the client connected at Identification level and the server is supposed to be inspecting, not acting. The correct fix is at the client end: ask for Impersonation.

restricted — a secondary identity check #

A restricted token carries two SID lists: the normal groups list and a secondary restricted_sids list. During AccessCheck the kernel runs the DACL walk twice and intersects the results — once with the full identity, once with only the restricted SIDs. A right is granted only if both passes grant it.

The effect is to limit a token's identity-based access to what the restricted SIDs would independently receive. The user is still the same user; they just cannot use group memberships or other SIDs that are not in the restricted list to satisfy an ACE.

A write-restricted token is the same idea, but the intersection applies only to write-category rights. Reads and execute come from the normal pass alone. This is the common case: a sandbox that should be able to read system files but only write into a narrow allowed set.

Both variants are covered in detail under Restricted and write-restricted tokens. For this page it is enough to know that "restricted" is a property of the token, set at creation by FilterToken, and that the kernel handles the second pass automatically.

elevation_type — half of a linked pair #

When a principal has both a normal (Limited) token and an elevated (Full) token — the UAC-style pattern — the two tokens are linked at the session level. Each carries an elevation_type saying which half it is:

A linked pair is established by an explicit call to KACS_IOC_LINK_TOKENS. The elevation type does not change anything about the token's access rights by itself — it is a label that lets the system locate the partner token when the user requests elevation. The mechanics live in Elevation and linked tokens.

Field mutability classes #

Token fields fall into three classes. Knowing which class a field is in tells you whether you can ever change it after the token is minted.

This split is the source of one rule worth memorising: the identity in a token cannot change. You cannot relabel a token to a different user. You cannot add a group to a token. You can only adjust how existing identity bits are used — enable or disable a privilege, mark a group as deny-only, narrow the default DACL.

If you need a different identity, you need a different token. Either authd mints a new one for you (with a re-authentication), or you DuplicateToken / FilterToken your existing one into a more restricted copy.

Fields by purpose #

The token's fields, grouped by what they do. None of this is a low-level binary layout — that lives in the Kernel ABI reference topic. This is the conceptual field list.

Identity #

The fields that say who the token represents.

Type and level #

Defaults #

These fields contribute to the security descriptor of a new object when the creator does not supply one explicitly.

Session and provenance #

Privileges #

Privileges live in a 64-bit bitmask with four states per privilege:

• Absent — not on this token at all.
• Present, disabled — on the token but not currently in effect. May be enabled.
• Present, enabled — in effect; AccessCheck will use it.
• Used — a sticky audit bit set when the privilege has been exercised. Never cleared.

See Privileges for the model in detail and the catalog of named privileges.

Confinement #

See Confinement for the sandbox model.

Claims #

See Claims on a token.

Projection #

These fields hold pre-computed Linux UID/GID values for compatibility. They are derived from the token, never the other way around.

See Linux compatibility for what consumes these.

Audit policy #

When a flag is set, AccessCheck emits the corresponding audit event regardless of the object's SACL.

Self SD #

Other #

Where to go next #

For how these fields are set, shared, adjusted, and destroyed over a token's life — mint, fork, exec, impersonation, adjustment — read Token lifecycle.

For the full rules around impersonation tokens and their levels, read Impersonation.

To read these fields off a live token from a shell, read The token command.

A token is reference-counted. It comes into existence when a privileged component mints it, is reference-counted up and down as it gets attached to processes and threads, and is destroyed when the last reference drops. Between mint and destruction it moves through a handful of well-defined transitions. None of them change a token's identity — but each affects how the token is reached, how many references it has, or how its mutable fields are set.

Three ways to mint a token #

A token is always created by code holding the right privilege:

kacs_create_token is what authd and peinit use to mint genuinely new identities. The other two — DuplicateToken and FilterToken — produce copies derived from a token a process already has. A process can FilterToken its own primary token down to a more restricted version and install the result as the primary token of a child it is about to launch.

In all three cases the kernel:

1. Validates the inputs (well-formed SIDs, no duplicate luids, all index references in range, etc.).
2. Allocates a new token object with refcount = 1.
3. Assigns a fresh token_id LUID and modified_id = 0.
4. Stamps the created_at timestamp.
5. Injects the appropriate logon SID into the groups list (callers must not supply it).
6. Returns a token file descriptor with TOKEN_ALL_ACCESS (for create) or the access mask the caller asked for (for duplicate).

Any validation failure results in no token being created — the operation is all-or-nothing.

Attaching to a process #

A token by itself is just an object the kernel holds. It does not yet identify anyone. To take effect, it has to be attached to a process or thread.

There are three attachment paths:

• Inheritance at fork — the child's primary token is the parent's primary token. The token's reference count goes up by one.
• Installation by a privileged caller — KACS_IOC_INSTALL on a token fd makes the token the calling process's primary. Requires TOKEN_ASSIGN_PRIMARY on the token and SeAssignPrimaryTokenPrivilege on the caller. Used by peinit when launching a service: fork, install the service token on the child, exec the binary.
• Impersonation on a thread — KACS_IOC_IMPERSONATE on a token fd makes the token the calling thread's impersonation token. Requires TOKEN_IMPERSONATE. The process-wide primary token is unchanged.

A given token can be attached in all three ways at once: shared as the primary of N processes, also held as the impersonation token of M threads. Each attachment is a reference.

Fork, exec, and the primary token #

flowchart LR
    A["Parent process (primary token T)"] -->|fork| B["Child process (primary token T)"]
    B -->|exec| C["Child process (primary token T, possibly with lowered integrity)"]

Fork copies the parent's primary token pointer into the child. Both processes now share the same token object. Adjustments made by the parent are visible to the child instantly — they share the storage. Adjustments made by either process via AdjustPrivileges etc. affect the shared token.

What does not survive fork is the parent's impersonation. A thread that forks while impersonating gets a child whose primary token is the parent's primary (not the impersonation). The child is not impersonating; its first thread is running on the inherited primary.

Thread clone (CLONE_THREAD) is different: the new thread is part of the same process, so it shares the same primary token. Privilege or group adjustments made by any thread are visible to all of them immediately.

Exec keeps the primary token. The new binary runs as the same identity. One subtle exception: if the token's mandatory_policy has NEW_PROCESS_MIN set and the executable carries an explicit integrity label lower than the token's (an unlabelled executable changes nothing), the kernel creates a copy of the token with integrity lowered to match, replaces the primary with that copy, and drops the original reference. This is the mechanism that prevents Medium-integrity code from running at Medium when its image is labelled Low.

Impersonation is always reverted at exec. A thread that execs while impersonating has its impersonation token released before the new program runs. This is enforced — the new binary cannot inherit an impersonation it did not establish.

Impersonation install and revert #

A thread becomes an impersonator by installing an impersonation token. The two ways to do it:

• peios_token_impersonate_peer(fd) — read the peer's identity from a connected Unix socket (the KACS_SO_PEER_TOKEN socket option) and install it at the appropriate level. The most common path for services accepting client connections.
• KACS_IOC_IMPERSONATE on a token fd — install a specific token (for transports that do not carry a peer token, or when the server has obtained a token by some other means).

Either operation has the same effect: the thread now has a primary token (unchanged) and an impersonation token (newly installed). AccessCheck reads the impersonation token from this point.

A thread reverts with kacs_revert. It always succeeds. It drops the impersonation reference and restores the original primary as the effective identity.

If a thread that is already impersonating installs a different impersonation token, the kernel silently reverts the old one first and then installs the new one. There is no nesting.

Impersonation tokens come from one of three sources during the install:

• A peer's identity captured at socket connect time.
• A duplicate of an existing token (DuplicateToken to a token type of Impersonation with the desired level).
• A new mint from authd (rare).

The level on an impersonation token is set by the client at connect time, never raised by the server. The full two-gate model — identity gate plus integrity ceiling — is in Impersonation.

Adjustment in place #

Some fields can be changed at runtime. The operations are:

All adjustments are atomic — invalid input rolls the whole operation back, no partial change. Each successful adjustment bumps modified_id so caches keyed on token state can invalidate.

Because the token storage is shared across all threads of a process, an adjustment made by one thread is visible to all of them immediately. This includes adjustments to the primary token of a process that has just installed it but not yet had every thread converge — the kernel handles the convergence asynchronously, and during the brief window other threads may still see the old token. This window is small enough not to matter in practice but is worth knowing about if you are writing tests.

Permanent privilege removal #

When a privilege is removed rather than just disabled, it is gone from the token permanently. The token's privilege bitmask loses the present and enabled-by-default bits. The used bit stays — its purpose is auditing, and the fact that the privilege was once exercised is information that should not disappear.

Removal is irreversible by design. There is no API to re-add a removed privilege. The only way back is a different token (a fresh authentication, or a duplicate from a source that still has the privilege).

The same applies to SE_GROUP_USE_FOR_DENY_ONLY set on a group: it can be marked, but never cleared. Marking a group deny-only is a one-way trip down the access ladder.

The default DACL #

Every token carries a default DACL. It is the DACL that gets applied to a new object when:

• The creator (for example a kacs_open with CREATE disposition, or a registry-key create) does not supply an explicit SD.
• The object's parent has no inheritable ACEs that fully cover it.

In other words, the default DACL is the fallback. It guarantees that any object a token creates has at least some DACL, even when nothing else supplies one.

The default DACL is adjustable via AdjustDefault. A typical default DACL grants the token's user identity and SYSTEM full access and excludes everyone else. Services that want a more permissive or more restrictive default can change it once at startup.

The default owner and primary group also live on the token, as indices into the [user_sid, groups[0..N-1]] array. They tell the kernel which SID to stamp as owner and which to stamp as primary_group when synthesising a new SD. They are adjustable through the same call.

Reference counts and destruction #

Every attachment is a reference. A token is alive as long as any of these are true:

• Any process has it as a primary token.
• Any thread has it as an impersonation token.
• Any process has it open via a token fd.
• It is part of an established linked pair on a still-existing logon session.

When the last reference drops, the kernel destroys the token: frees the storage, releases the reference on the logon session. If the destroyed token's session loses its last token reference too, the session itself is destroyed and a kacs.session.destroyed event is emitted via KMES. See Logon sessions.

A token's expiration field has no effect on the lifecycle in v0.20 — it is stored for future use but not enforced. A token lives until its references drop. Ending a session early is done in userspace: asked to, authd finds every process whose primary token belongs to the session and ends it, and the kernel destroys the session when the last reference goes. A token descriptor held by a process outside the session survives that, and keeps the session alive. This is documented under Session lifecycle.

Quick reference: which transitions change what #

Where to go next #

For what FilterToken's restricted variants actually do at access-check time, read Restricted and write-restricted tokens.

For the session a token belongs to and what happens when the last token of a session is released, read Logon sessions.

To drive these transitions from a shell — duplicate, restrict, adjust, install — read The token command.

A restricted token is the kernel's narrow-the-identity primitive. It is a normal token with an extra list of SIDs attached — the restricted_sids list. During AccessCheck the kernel runs the DACL walk twice: once with the token's full identity, once with only the restricted SIDs. A bit is granted only if both passes grant it.

The effect is to put a ceiling on what the token can reach, expressed as "the rights this token would have if it were just those restricted SIDs". The identity (user, groups, privileges) is unchanged — but the kernel will only honour an ACE if the restricted-only view of the token would have honoured it independently.

Restricted tokens are the building block underneath several patterns: service hardening, sandbox processes, anti-malware quarantine, anything that says "this code should have less authority than the user it is running as".

The two-pass model #

flowchart TD
    A["AccessCheck"] -->|with full identity| B["Normal pass (user_sid + groups + ...)"]
    A -->|with restricted SIDs only| C["Restricted pass (restricted_sids only)"]
    B -->|granted_normal| D["Intersect"]
    C -->|granted_restricted| D
    D -->|granted = normal ∩ restricted| E["Final granted mask"]

When KACS evaluates AccessCheck for a restricted token, it runs through the same pipeline twice:

1. Normal pass. The DACL walk uses the token's user_sid, all enabled groups, and all the usual rules. Produces a granted_normal mask.
2. Restricted pass. The DACL walk runs again, but the only SIDs considered for matching are those in restricted_sids. The user_sid does not match. None of the regular groups match. Only the entries in restricted_sids count. Produces a granted_restricted mask.
3. Intersection. The final granted mask is granted_normal & granted_restricted.

Both passes must agree to grant a right. If the normal pass would grant FILE_WRITE_DATA but the restricted SIDs do not appear in any allow ACE for that right, the bit is dropped.

The restricted SIDs are usually narrow on purpose. A common pattern is to put a single capability SID (for example internetClient) in the restricted list — the token now has authority only on objects whose DACLs explicitly grant access to that capability.

What is not affected #

A few things are explicitly not narrowed by the restricted pass:

• Privileges. Privilege-granted access (SeBackup, SeRestore, SeTakeOwnership, SeSecurity) is restored after the intersection. A restricted token with SeBackup can still read any file the privilege would have granted.
• The default DACL on new objects. A restricted token still creates new objects with its default DACL, derived from its full identity.
• Reading the token's own state. Querying a restricted token does not require both passes; the token's self-SD governs that as normal.
• MIC. Mandatory integrity is evaluated before the DACL walks. A restricted token cannot use the restricted-SID trick to escape integrity rules.

Privileges being orthogonal to the restricted pass is the most important of these. The restricted-token model narrows identity-based access, not capability-based access. If you want to drop privileges too, that is a separate operation — see "Creation" below.

Write-restricted: the common case #

A write-restricted token narrows only the write-category rights. Reads and execute come from the normal pass alone; only write-mapped bits go through the intersection.

The motivation: it is rare to want a sandbox that cannot read anything in the normal world. Sandboxed code usually needs to load shared libraries, read configuration, perhaps look up its own metadata. What it must not do is write — into the user's home directory, into system paths, into any file outside the small set the sandbox explicitly allows.

In a write-restricted token:

The "category" is determined by which generic right the bit maps to. FILE_WRITE_EA is in the write category; FILE_READ_EA is in the read category; and so on. The generic mapping for each object type defines the partition.

There is a quirk worth noting. When a token is write-restricted, the kernel also sets a user_deny_only flag on the token internally. This causes the token's own user_sid to match only deny ACEs in any pass, never allow ACEs. The motivation is to prevent a token from getting write access on an object simply because its user SID matches an allow ACE — the write-restricted intersection would otherwise be too easy to bypass by writing an ACE that names the user directly. With user_deny_only set, the user SID can still trigger denials but cannot grant.

This is a subtle interaction; most code that uses write-restricted tokens does not need to think about it, but if you are debugging an access denial on a write-restricted token and the user appears in the DACL with an allow ACE, the explanation is here.

Creation #

There is one path to creating a restricted token: KACS_IOC_RESTRICT on a token fd — the ioctl behind the FilterToken operation named elsewhere in this topic. The operation takes:

• A list of privilege LUIDs to remove from the new token.
• A list of group indices to mark SE_GROUP_USE_FOR_DENY_ONLY in the new token (set once, irreversible).
• A list of restricting SIDs to put in the new token's restricted_sids.
• An optional flag enabling write-restricted mode (which also sets user_deny_only).

The result is a new token fd. The source token is unchanged.

A typical sandbox launcher does something like this:

1. Open its own primary token.
2. Call KACS_IOC_RESTRICT to produce a restricted variant: remove every privilege except SeChangeNotifyPrivilege, mark unsafe groups deny-only, add the sandbox's allowed capability SIDs as the restricted SIDs, set the write-restricted flag.
3. Fork.
4. KACS_IOC_INSTALL the restricted token on the child.
5. Exec the sandboxed binary.

The child now runs as the same user, but the user's group memberships are mostly invisible, the privileges are gone, and writes are confined to objects whose DACLs explicitly allow the sandbox's restricted SIDs.

Restricted tokens vs confinement #

Two things in Peios narrow what a token can reach: the restricted-token model on this page, and confinement (covered in Confinement). They look similar at a glance, but they exist for different audiences.

Restricted tokens are a tool for code. A program — a service, a sandbox launcher, an anti-malware engine — uses FilterToken or KACS_IOC_RESTRICT to narrow a token it already has, then runs sensitive work on the result. The decision is made in code, by the program itself, before it hands the restricted token to the constrained operation. Nothing outside the program needs to know about it, and nothing outside the program enforces it — the program is choosing to give itself less authority.

Confinement is a tool for policy. A sysadmin — or a service definition the sysadmin has chosen to deploy — declares that some component runs as a confined application with a specific confinement SID and an enumerated set of capabilities. The kernel enforces that policy whether or not the confined code is aware of it. Confinement is an administrative decision applied from outside the program, and the program cannot opt out of it.

That difference in audience is the reason behind the technical differences:

The technical asymmetry follows from the audience. A program restricting itself is trusting itself to use the primitive correctly — it can drop privileges if it wants to, leave them in if it doesn't, choose what its restricted SID set should be. Confinement is enforced against the code, so it has to be a harder line: privilege exercise and owner implicit rights are exactly the kinds of escape routes a confined application would otherwise reach for.

The two can be combined. A service that runs under a confinement policy and additionally restricts its own internal worker threads sets both. The kernel applies each layer; the final granted mask is the intersection of all of them.

Practical patterns #

A few patterns worth recognising:

• Drop privileges only. Sometimes you want to remove dangerous privileges without restricting identity at all. KACS_IOC_RESTRICT with a privilege removal list, an empty deny-only list, and an empty restricted_sids list does this — the result is a token with reduced privileges and no restricted-SID intersection.
• Write-restricted with the deny-only user trick. Set the write-restricted flag, leave restricted_sids containing only what you want the sandbox to be able to write to. The token's user SID can still match deny ACEs (so user-targeted denials still work) but cannot match allow ACEs on writes.
• Capability-style sandbox. Put one or more capability SIDs (well-known or derived) in restricted_sids. The sandbox can then reach only objects whose DACLs explicitly grant access to those capabilities, plus whatever its user identity grants in the normal pass.
• Anti-malware quarantine. Restrict to a narrow set of well-known SIDs (Everyone, Authenticated Users) and remove all privileges. The result is a token that can reach widely-shared resources but cannot exercise any system-level rights.

All of these are FilterToken / KACS_IOC_RESTRICT applied to the appropriate source token, with different inputs. The kernel does not distinguish between them; they are just patterns of use.

Where to go next #

For the linked Full/Limited token pair — the other derived-token pattern this topic covers — read Elevation and linked tokens.

For the policy-driven counterpart to restricted tokens, read Confinement.

To build a restricted token from a shell, read The token command.

A linked token pair is two tokens for the same principal, one elevated (Full) and one not (Limited), associated with each other through their shared logon session. The point of the pair is to give a user a default identity that is not fully privileged, while keeping a second identity available for explicit elevation when the user actually wants to do administrative work.

If you have used UAC on a Windows desktop, this is the same model. The Limited token is what runs the user's shell and most of their software. The Full token is what runs the action they have just been prompted to authorise. The kernel does not decide when to switch — that is a user-space decision, prompted by some authority broker — but the kernel is responsible for keeping the pair linked, locating the partner on demand, and enforcing the rules around who is allowed to see what.

The model #

flowchart LR
    A["Logon session"] -->|associates| B["Full token (elevation_type = Full)"]
    A -->|associates| C["Limited token (elevation_type = Limited)"]
    B <-->|partner| C

Both tokens share the same logon session (auth_id). They have the same user SID, the same logon SID, the same created_at. What differs:

• The Full token has whatever privileges and group memberships the principal is entitled to when running elevated — typically including BUILTIN\Administrators, SeBackup, SeRestore, etc.
• The Limited token is a filtered version — privileges removed, sensitive groups marked USE_FOR_DENY_ONLY. It is the version the user runs in by default.

Each carries an elevation_type:

A token's elevation_type is set when it joins a pair, never cleared. If the session is destroyed, the pair linkage is removed but the individual elevation_type values stay until the token objects themselves are freed.

Establishing a pair #

A pair is created by an authority broker — almost always authd, occasionally peinit — using:

KACS_IOC_LINK_TOKENS(elevated_fd, filtered_fd, session_id)

The kernel requires:

• SeTcbPrivilege on the caller.
• TOKEN_DUPLICATE on both token fds.
• Neither token already linked.
• Both tokens part of the same session (session_id).
• The two tokens not the same token.

When the call succeeds, the kernel:

1. Records the pair on the session.
2. Sets the elevated token's elevation_type = Full.
3. Sets the filtered token's elevation_type = Limited.

Both tokens continue to be valid as independent tokens. The pair linkage is additional state on the session, not a property that bundles the two into one object.

A typical flow during user login — none of which authd does yet, per the note at the top of this page:

1. authd authenticates the user.
2. authd creates the user's session.
3. authd mints the Full token with all the user's entitled privileges and groups.
4. authd FilterTokens the Full token down to the Limited version — privileges removed, admin groups deny-only.
5. authd calls KACS_IOC_LINK_TOKENS to link the two.
6. authd installs the Limited token as the primary of the user's first process.
7. The Full token is kept available (via session state or an authority broker process) for later elevation requests.

The user's shell, file manager, web browser, and most of their applications now run on the Limited token. Whenever the user does something administrative, the authority broker — after whatever consent step is appropriate — fetches the Full token via KACS_IOC_GET_LINKED_TOKEN and installs it on the new process.

Looking up the partner #

KACS_IOC_GET_LINKED_TOKEN(token_fd) -> partner_fd

Given a token that is part of a pair, this ioctl returns a handle to the partner. The semantics depend on who is asking:

• With SeTcbPrivilege, the caller gets a full handle on the partner token — TOKEN_ALL_ACCESS, the actual token object. This is what authority brokers use to perform an elevation: fetch the Full token's fd, install it on a child process.
• Without SeTcbPrivilege, the caller gets a degraded handle — a freshly duplicated Identification-level clone of the partner, opened only with TOKEN_QUERY. The clone is enough to inspect the partner's identity ("am I currently the Limited token? what would the Full version contain?") but cannot be used for any access check and cannot be installed.

The asymmetry is deliberate. Anyone who can prove they hold one half of a pair is allowed to learn something about the other half — that is useful for diagnostics and for user-facing tools that want to display "you are running as Limited; admin rights are available". But actually wielding the elevated identity requires SeTcbPrivilege, the privilege held only by the authority broker that is supposed to gate elevation.

KACS_IOC_GET_LINKED_TOKEN fails with -ENOENT on a token whose elevation_type is Default, or on a token whose pair was destroyed when its session was destroyed.

What the link does not do #

A few clarifications on what linkage does not change:

• It does not unify the two tokens. They remain independent objects. Adjustments to one have no effect on the other. Destroying one does not destroy the other.
• It does not change access decisions. AccessCheck reads whichever token is currently in effect on the thread. The fact that a token has a partner is invisible to the access check — only the broker that calls KACS_IOC_GET_LINKED_TOKEN sees the pair.
• It does not require either token to be installed. A pair can exist on a session that has not yet attached either of its tokens to any process. (Unusual but valid.)
• It does not change auth_id. Both tokens still report the same session ID. The session is the level at which they are paired.

Teardown #

A pair is dissolved when the underlying logon session is destroyed. At that point:

• The pair association is removed from the session.
• Subsequent calls to KACS_IOC_GET_LINKED_TOKEN on either token return -ENOENT.
• The individual tokens themselves continue to exist as long as their reference counts hold. Their elevation_type values are unchanged but no longer meaningful.

A session is destroyed when its last token reference drops (see Logon sessions). For a linked pair, that means: both tokens must lose all their attachments — every process running on them must exit, every fd open on them must be closed, every impersonation token derived from them must be reverted.

For the Limited token this happens naturally when the user logs out. For the Full token, the authority broker is responsible for releasing it when the session ends — typically by holding it in a process that exits when the user logs out.

Common patterns #

Default-Limited login. Every interactive login establishes a pair where the user's shell runs as Limited. The Full token is held by the authority broker.

Elevation on demand. When the user invokes an administrative action (a control panel, a sudo-equivalent), the broker prompts for consent, then uses KACS_IOC_GET_LINKED_TOKEN to fetch the Full token and KACS_IOC_INSTALL to install it on the privileged child process.

Service accounts (no pair). Services do not generally need elevation; their tokens are unpaired and elevation_type = Default. A service that needs occasional elevated work is a different pattern — usually IPC to an already-elevated service rather than a linked pair within the same service.

Diagnostics ("am I elevated?"). A process can call KACS_IOC_GET_LINKED_TOKEN on its own primary token (which it always has at least TOKEN_QUERY on). Without SeTcb it gets an Identification-level clone — enough to read elevation_type and groups on the partner and display "elevated rights available". The clone itself cannot be used for anything but inspection.

Where to go next #

For the session object that holds the pair together — and what happens to the pair when it dies — read Logon sessions.

To inspect a token's elevation type and its partner from a shell, read The token command.

A logon session is the kernel object that records one authentication event. It exists from the moment a principal successfully signs in to the moment every token derived from that sign-in is released. Every token references exactly one session through its auth_id field, and the session ties together everything that came out of that sign-in: the primary tokens, the impersonation tokens derived from them, the linked Full/Limited pair when one is established.

Sessions exist to answer two questions cleanly:

• "Did all of these tokens come from the same sign-in?"
• "When this principal logs out, what should we tear down?"

The first matters for audit and for signing somebody out. The second matters because logging out has to do more than just close a shell — it has to end every process of the sign-in, drop linked-pair associations, fire the right events. Sessions are the unit at which those teardowns happen.

What a session contains #

A logon session is a small kernel object — fewer fields than a token, no privileges or groups of its own. Its job is to identify the event, not the principal.

The session is the unit of identity provenance. If you want to answer "where did this token come from?", the path is: token → auth_id → session → logon_type, auth_package, created_at, user_sid. Everything an audit log needs to reconstruct a sign-in is reachable from the session.

The logon SID #

Every session has its own SID, called the logon SID:

S-1-5-5-X-Y

Where X and Y are the high and low 32 bits of the session's LUID. The logon SID is unique to the session — two different logins by the same user produce two different logon SIDs, because they have different session IDs.

Every token of the session carries its logon SID in two places: the dedicated logon_sid field, and as an entry in the groups list with the SE_GROUP_LOGON_ID flag set. Both views point at the same value. The flag exists so the access check can identify the logon SID without needing to know its specific value.

The logon SID is what lets you write an ACE that targets "the specific sign-in that did this" rather than "this user". Common uses:

• Per-session temporary objects. Grant access to the logon SID only. When the session ends, the SID becomes unreachable (no future token will ever carry it), so the object is effectively cleaned up at logout from an access-control perspective.
• Service-to-user isolation in shared sessions. Two services running for the same user but in different sessions can use the logon SID to keep their per-session state apart even though the user SIDs are identical.
• Audit anchoring. An audit event records the logon SID alongside the user SID. The two together let an investigator distinguish "this user did this" from "this specific sign-in did this".

The logon SID cannot be disabled (SE_GROUP_LOGON_ID is a mandatory-equivalent flag), and it cannot be removed from the token. It is intrinsic to the token.

Sessions and tokens #

A session can have many tokens. Every primary token of a process belonging to the session, every impersonation token derived from one of those primaries, every duplicated or filtered copy that shares the same auth_id — all of them are tokens of that session.

flowchart LR
    A["Logon session, auth_id=42"] --> B["Primary token (user's shell)"]
    A --> C["Primary token (child process)"]
    A --> D["Impersonation token (service handling this user)"]
    A --> E["Filtered token (restricted sandbox of B)"]
    A --> F["Full token (linked pair)"]
    A --> G["Limited token (linked pair)"]

The kernel keeps a reference count of how many tokens belong to a session. When the count drops to zero — every token of the session has been released — the session itself is destroyed and a kacs.session.destroyed event is emitted.

The implication is that destroying a session is not a primitive operation. There is no kacs_destroy_session syscall. You destroy a session by ensuring every token belonging to it is released, which usually means ending every process running on those tokens. Forced sign-out is implemented this way, in user space: asked by a person signing themselves out, or by an administrator signing somebody else out, authd ends every process whose primary token belongs to the session, and the kernel does the rest.

Bootstrap sessions #

Two sessions exist before authd is up, created by the kernel during boot:

Both are created by direct kernel initialisation — they do not go through kacs_create_logon_session. They are also never destroyed during a running system's lifetime: the SYSTEM token always exists somewhere, and the Anonymous token is a singleton.

You will see these IDs in audit logs and /sys/kernel/security/kacs/sessions listings. They are not bugs.

Sessions are not durable #

A session exists in the kernel only while it has active tokens. There is no on-disk session table. The session ID space is not stable across boots — after a reboot, the same user signing in again gets a different session ID, and a new logon SID.

This matters in two practical ways:

• You cannot reference a session across a reboot. An ACL entry that targets the logon SID of "the previous boot's session 5" is meaningless after the next boot. The SID format will look syntactically valid, but no token will ever match it.
• Per-session state should be in memory, not on disk. Anything intended to survive a single sign-in should be keyed on the user SID, not the logon SID.

Where to start #

If you want the catalog of logon types — what Interactive, Network, Service, Batch, NewCredentials, and the rest each mean — read Logon types.

If you want the creation, destruction, and forced sign-out mechanics — including the kacs.session.destroyed event and what authd does to sign somebody out — read Session lifecycle.

If you want to see which sessions are currently active on a running system, read Inspecting tokens, sessions, and processes.

To work with sessions from a shell — list them, see their processes, create and destroy them — read The logonse command.

Every logon session carries a logon_type — a single number, set by authd at session creation, that classifies the nature of the sign-in. The type is informational from KACS's point of view: AccessCheck does not branch on it. But it is recorded — by name, such as interactive or network — in the kacs.session.destroyed event that closes the session, and it is what audit consumers and SIEM tools use to distinguish "the user logged in at the console" from "the user logged in over the network" from "a service started under this account".

There are seven types in v0.20.

The SSH assignments below follow the current PGSS SSH implementation contract, whose release qualification is tracked by PEI-67. They do not establish the behavior of older builds; the contract's coordinated-rebuild requirements still apply.

The seven types #

The numeric values are also catalogued in Other constants.

Values 1, 6, 7, and 11 onward are reserved and not used in v0.20.

When each type is used #

Interactive #

The type for local console and desktop sign-ins. SSH connections and remote desktop sessions use RemoteInteractive.

In audit logs, Interactive distinguishes a local interactive sign-in from a remote one. It is not a marker for all human activity: a person using SSH or a remote desktop has a RemoteInteractive session.

Network #

Used when a principal authenticates only to access a network resource — for example, a remote user mounting a file share. The session exists on the server, the user's identity is established there, but the user has no interactive presence on the machine. The session's tokens are typically short-lived (one connection's worth of work).

A Network session is what an inbound SMB connection produces, what an authenticated RPC call produces, what a federated service request produces. It is also what a host typically sees when a user reaches a service on it that is acting on the user's behalf.

Batch #

Scheduled tasks. The principal is "logged in" only in the sense that the system mints a token for the user so the task can run as them. There is no human presence. Once the task finishes, the session ends.

Batch sessions are useful for auditing scheduled work — distinguishing "the user typed this command" from "the user's scheduled task did this command".

Service #

The session under which a service runs. The service account signs in once at service start; the session lives for as long as the service runs. Most services on a Peios machine are Service-type sessions.

This is the type you will see most often in the session listing at /sys/kernel/security/kacs/sessions on a system without active interactive users — every running service contributes one Service-type session.

NetworkCleartext #

Used when the authentication protocol exposed the credential in cleartext on the wire. The semantic effect is identical to Network — it is a network sign-in producing a Network-style session — but the type difference exists so audit policy can flag the cleartext exposure.

You should rarely see this in normal operation. Its presence in an audit log is worth attention; it usually indicates that an older or misconfigured protocol is in use.

NewCredentials #

The unusual one. A NewCredentials session does not replace the calling thread's identity. Instead, it represents "I want to keep being myself locally but use these other credentials for outbound network calls". The thread's effective token retains the local user's SIDs and privileges for everything KACS evaluates locally, but any outbound credential-using request carries the alternative principal.

The pattern matters in environments where a user has local rights on one machine and different rights on another, and wants to keep both available without switching sessions.

RemoteInteractive #

A remote desktop or SSH session. Every SSH logon uses this type, including commands without a PTY and SFTP; it does not become Network or Batch when no terminal is requested.

GXWI requests this type when logging on through authd. The kernel and authd must both support value 10; an older authd refuses the request rather than substituting another type. After updating GXWI and authd, log off existing GXWI sessions and start new ones: reconnecting to an existing compositor retains that session's original token and logon type.

It is a separate type from Interactive rather than a flavour of it because the two differ in exactly one respect that an administrator may want to act on: whether the person is physically at the machine. Everything else about the session is the same, which is why a RemoteInteractive token carries the Interactive group SID as well as its own — see Well-known principals for what that pair lets you write.

Rebooting from a RemoteInteractive session needs SeRemoteShutdownPrivilege on top of SeShutdownPrivilege, as it does from a Network, NetworkCleartext or NewCredentials session. The session being remote is what counts, not whether it is graphical.

Where the type appears #

The logon type is stamped in three places you will care about:

• In the session itself, retrievable through /sys/kernel/security/kacs/sessions and the session inspection APIs.
• In every token's session — via the token's auth_id field, which points to the session, which holds the type.
• In audit events — every audit event that includes a subject also implicitly identifies the subject's session, and audit consumers can use that to retrieve the logon type for the event.

The type is not part of any token's SID list. There is no "Interactive" SID that gets added to a token's groups based on the logon type. The well-known SIDs like S-1-5-4 (Interactive) and S-1-5-2 (Network) are added to a token's groups by authd based on the logon type, but they are independent token attributes from that point on. A token with the Interactive group SID has it because authd put it there; the session's logon_type is the input that drove that decision.

This independence is intentional. A token can in principle carry the Interactive group without belonging to an Interactive-type session (rare, but legal). Audit and ACL evaluation use the group SID; provenance uses the session's type.

What the type does not affect #

AccessCheck does not read the logon type. The DACL walk, the MIC check, the PIP check, the restricted/confinement passes — none of them branch on logon_type.

If you want different access for "Interactive users" vs "Network users", you write ACEs that reference the well-known group SIDs (S-1-5-4, S-1-5-2, etc.). Those SIDs end up in the token because of the logon type, but the access check matches on the SID, not the type.

The type matters at the seams: when authd is making decisions about which groups to add to a token, when the audit subsystem is recording provenance, when a SIEM correlates events across sessions. Inside the access check itself, the type is invisible.

Where to go next #

For how a session is created, destroyed, and forcibly revoked, read Session lifecycle.

For the well-known group SIDs (S-1-5-4 Interactive, S-1-5-2 Network, and the rest) that authd derives from the logon type, read Well-known principals.

To see the logon type of each active session from a shell, read The logonse command.

A session's life is bracketed by two kernel events: a successful kacs_create_logon_session call that brings it into existence, and the implicit drop of its last token reference that destroys it. There is nothing in between — no resize, no rename, no kernel-side timeout. Sessions are simple objects whose lifecycle is driven entirely by the tokens attached to them.

This page covers the three phases that matter: creation, destruction, and forced sign-out (ending a session before the person signs out themselves, which authd does on request).

Creation #

A session is created by kacs_create_logon_session. The call requires SeTcbPrivilege, so in practice the only callers are authd (every interactive and network sign-in) and peinit (services launched during boot before authd is available).

The call takes a wire-format specification with three fields:

The kernel:

1. Validates the inputs (well-formed SID, recognised logon type, sane string lengths).
2. Allocates a session object with a fresh session_id LUID.
3. Stamps created_at.
4. Derives the logon SID S-1-5-5-X-Y from the session ID.
5. Initialises the session's token reference count at zero.
6. Returns the new session ID to the caller.

The session now exists but has no tokens. It is in a transient state: any subsequent kacs_create_token call that references this session_id in its auth_id field bumps the count, and the session is "live".

authd's flow is "create session, then mint primary token referencing it". Between those two calls the session has no tokens, and a strict "destroy when refcount hits zero" rule would tear it down before authd's second call. So the kernel only destroys a session on a refcount that transitions from positive to zero, not on one that has been zero since creation. After a successful first attachment, normal destruction rules apply.

The consequence is that a session no token ever attaches to is never reaped. Nothing times it out. If authd's mint fails after it created the session, authd rolls the session back itself with kacs_destroy_empty_logon_session, which refuses any session that has a live token. An empty session left by some other caller stays in the listing until the machine restarts, or until a caller holding SeTcbPrivilege destroys it — logonse destroy does exactly that.

The boot sessions #

Two sessions exist without ever passing through kacs_create_logon_session:

Both are constructed in early boot, before any process exists. The SYSTEM session is attached to the kernel's bootstrap SYSTEM token, which init inherits and which propagates through every process until authd assigns real tokens. The Anonymous session backs the well-known Anonymous token used by Anonymous-level impersonation.

Neither is ever destroyed during the running system's lifetime. They are reference-counted like any other session, but their references never drop to zero — the SYSTEM token always has at least one attachment somewhere, and the Anonymous token is a kernel-internal singleton.

Destruction #

A session is destroyed when its token reference count, having been positive, drops to zero. The kernel:

1. Removes the session from the session table.
2. Tears down any linked-pair association it was holding (see Elevation and linked tokens).
3. Emits a kacs.session.destroyed event through KMES.

The event carries enough information for consumers to clean up downstream state:

The consumers are audit pipelines, accounting tools and session-aware services. authd is not one of them: it keeps no per-session state — no tickets, no cached credentials, no handle on the tokens it mints — so there is nothing of its own for it to release when a session goes. An authority that did hold session-scoped state would subscribe here to learn when to drop it.

The event is fire-and-forget — there is no acknowledgement, no retry, no replay. A consumer that misses an event misses it.

What ends a session #

A session ends only when every reference to it drops. The references are:

• Every primary token attached to a process with auth_id = session_id.
• Every impersonation token currently installed on any thread.
• Every token fd open on a process's behalf.
• The linked-pair association, while it exists.

Practically, this means a session ends when:

1. Every process running on a token of the session has exited.
2. Every thread that was impersonating a token of the session has reverted or exited.
3. Every fd held on a token of the session has been closed.
4. The linked pair, if any, has been dissolved.

The fourth condition is satisfied automatically when the session reaches refcount zero — the kernel dissolves the pair as part of destruction. The first three are user-space's responsibility.

For an ordinary logout, this happens naturally: the user's shell exits, its child processes exit, and anything that was handed a descriptor for one of the session's tokens closes it. Once all of those happen, the kernel sees refcount zero, fires the event, frees the session. (authd holds nothing: it closes its descriptor for a token the moment it has handed the token over.)

Forced sign-out: there is no kernel call #

There is no syscall to forcibly end a session. No kacs_destroy_session, no kacs_kill_session. The session model is reference-counted, and the only way to end one is to ensure every reference drops. (The one destroy syscall that exists, kacs_destroy_empty_logon_session, is a rollback primitive for empty sessions only — it refuses with -EBUSY any session that still has live tokens. This is what logonse destroy wraps.)

Forced sign-out — an administrator deciding that a person should not be signed in any more, or a person signing themselves out everywhere — is therefore a userspace operation, and authd performs it. A program that signs somebody out — a task manager, a command-line tool — asks with a SessionEnd request on /run/logon.sock (PGSS §2.22) and does none of the work itself. authd:

1. Checks that the caller may. Anyone may end their own session, when they are a person signed in as themselves. Ending anyone else's needs the right granted by the SessionEndSecurity descriptor on Machine\Generic\Authn\Policy — by default SYSTEM and Administrators have it. Nobody may end SYSTEM's session (999), Anonymous's (998), or a service's: a service is stopped through the service manager.
2. Finds every process whose primary token belongs to the session: it walks /proc, opens each process by pidfd, and reads auth_id from that process's primary token. A thread that is only impersonating a token of the session — a service answering the person's request — is not in the session, and is left alone.
3. Sends each SIGTERM through its pidfd, so the signal reaches the process whose token was read even if its pid has since been reused. It waits up to five seconds for them to exit, then sends SIGKILL to what is left.
4. Walks again, because a process may have forked during the grace period, and repeats — at most three rounds.
5. Answers with how many processes it ended and how many still hold the session, and records the request, who made it and the result as an authd.session.ended event.

Once the last process exits, the session reaches refcount zero, the event fires, and the person is signed out.

What the audit trail shows #

A forced sign-out leaves two records, from two components:

• authd.session.ended, written by authd when it has finished the rounds. It names who asked (subject.token.sid), the session (object.session.id), whose session it was (object.session.user.sid) and its logon type. outcome.success is false, with outcome.reason processes-remaining, when something still held the session after the last round. It is an essential event, so the emission policy cannot switch it off.
• kacs.session.destroyed, written by the kernel when the last reference drops. It cannot say who asked: only authd knows that.

A refused request is not an authd event. Whether a caller may end another principal's session is an access check against the SessionEndSecurity descriptor, and KACS records that decision as kacs.audit.access.checked, with object.kind authd-session-end, when the descriptor's SACL asks it to. To audit refused sign-outs, give the descriptor a failure-audit ACE, such as S:(AU;FA;0x1;;;WD). Ending one's own session needs no grant, so it runs no check. Neither does a request for SYSTEM's, Anonymous's or a service's session, which is always refused.

A program that ends the session it is itself running in is ended with it. authd therefore answers such a request first, saying how many processes it found, and does the work afterwards.

What this cannot reach:

• A token descriptor held outside the session. Token descriptors can be passed between processes; a process outside the session holding one keeps the session alive after every process in it has gone. authd walks processes, not descriptors, so it neither finds nor counts these.
• A thread impersonating a token of the session, by design (step 2). The session lasts until that thread reverts.
• A process that has exited but not been reaped. It holds its token until its parent reaps it, and counts as remaining until then.

There are two reasons the kernel does not provide a direct revoke:

• No graceful path. A "kill the session" syscall would need to choose between killing every process holding any of its tokens (loss of work, possible data corruption) and merely refusing future operations, which leaves running processes with stale identity. User-space can stage the teardown — send SIGTERM, wait, escalate — in a way the kernel cannot.
• Reference-counted identity is the simpler model. The rule "a session exists if and only if a token exists referencing it" has one fewer transition than "a session exists if and only if its tokens exist AND no revocation has been requested". Fewer transitions, fewer corner cases.

The cost is that revocation is observable: a thread can detect that its session is about to die (its parent process getting a TERM) before the kernel sees the session as gone. Anything that wants to enforce immediate revocation needs to design around that — typically by minimising the work a thread can do between receiving a signal and actually exiting.

Inspecting active sessions #

The kernel exposes the active session list at /sys/kernel/security/kacs/sessions. The file is a text listing, one session per line:

logon_session_id=1042 user_sid=<hex-encoded SID> logon_type=2 auth_package=<hex-encoded name> created_at=...

Lines are stable in their leading fields; new fields may be appended in a future version, so consumers must ignore unknown trailing fields. The file's own SD grants read to BUILTIN\Administrators and SYSTEM only.

This is the canonical way to enumerate sessions. Other tools — eventd consumers, who-equivalents, session monitors — can read it directly or through helpers that wrap it. See Inspecting tokens, sessions, and processes.

Where to go next #

For the token-side half of the same story — the references whose rise and fall drive a session's life — read Token lifecycle.

To list, create, and destroy sessions from a shell, read The logonse command.

Every sign-in on Peios is a conversation with an authority over a Unix socket at /run/logon.sock. The protocol is PGSS Logon, and it is a conformance requirement rather than an implementation detail: a system that does not offer it, at that path, with these semantics, is not Peios.

Knowing its shape is worth the few minutes it takes. It explains why a login prompt behaves the way it does, why a wrong password and an unknown account are indistinguishable, and what you would have to build to add a new way of signing in.

Three roles #

The authority listens on the logon socket. It decides whether a sign-in succeeds, and it is the only thing on the system that mints tokens. On a stock Peios system that is authd. There is at most one on a running system — two would make "who authenticated this?" unanswerable.

The client connects and speaks on the principal's behalf. login is a client. So is any greeter, remote access daemon or kiosk agent you might write. A client renders the prompts it is asked to render, returns the answers, and installs the token it is given. It is not trusted, and nothing it sends is taken as fact.

A principal source knows who exists and verifies credentials. It asserts an identity and can do nothing else — it cannot mint a token, grant a privilege or create a session, because the protocol it speaks has no message for any of those. lpsd is the local one. See principal sources.

The conversation #

A client opens a connection and sends one LogonStart, naming the principal, the kind of session it wants, and the credential types it is able to collect. The authority may then ask for credentials — as many rounds as the source needs — and each request carries prompts the client renders without interpreting. The conversation ends when the authority grants or denies.

The capability list is a statement about the client, not a demand. Declaring that you can collect a password does not mean one will be asked for; declaring that you can collect nothing says you are able to complete a sign-in that needs no interaction, and nothing else. An authority faced with that either completes the sign-in or denies it. That is the mechanism behind passwordless accounts and console autologon.

A connection carries exactly one conversation, so the connection is the conversation's identity. There is no correlation identifier to forge.

Changing your own password #

The logon socket carries one other kind of conversation: changing your own credential. It opens with a different message, which names nobody — the account is the one your token says you are — and it ends without a token, because a change mints nothing. Your current credential is asked for first, even though you are signed in. passwd is the client for it.

Because every principal needs to reach the socket for this, reaching it is not permission to originate a logon. The authority decides that per caller, from the caller's token.

The authority is not a process factory #

A grant carries a token as a file descriptor, a session identifier, and a profile. It carries nothing about what should happen next, because nothing about what happens next is the authority's concern.

The client installs the token itself and proceeds. login makes the token its own and then execs your shell, rather than the authority forking anything. This keeps the most privileged process on the system out of the business of launching programs: authd never learns about terminals, environments or session leadership, and stays small enough to audit.

It also means a client can obtain a token for a purpose the authority never anticipated.

Authentication and derivation are separate #

Two acts, deliberately distinguished.

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 this machine's policy.

The separation is what stops an identity established elsewhere from carrying entitlements onto this machine with it. A directory can tell this machine that you are a member of Domain Admins; whether that membership carries SeLoadDriverPrivilege here is answered here, every time, by the authority applying local policy. An authority never accepts a token, a privilege set or an integrity level from another party, whatever its trust level.

See privileges for what that policy contains.

What the authority does not trust #

Nothing a client sends. Three consequences are worth knowing because you will see them from the outside:

Peer identity comes from the socket. The authority reads the connected peer's token from the kernel rather than believing anything in a message, because there is no field a client could put its identity in that it could not also lie in. SO_PEERCRED is not used: it returns the projected uid, and on Peios many principals project to the same number.

The logon type is a proposal. Only the caller knows whether a connection is an interactive shell or a batch command, so the caller says — and the authority constrains that against what the verified peer is permitted to request. See logon types.

The identifier is a claim until authentication succeeds, and tty and remote_host are never more than that. A client that lies about its remote host is not prevented from doing so by this protocol.

A wrong password and an unknown account look identical #

An authority never distinguishes an unknown principal from a bad credential — not by denial code, not by the text it returns, and not by timing. There is one denial for both.

lpsd holds to the timing half by verifying an unknown name against a decoy: a real verifier over a password nobody knows, so both outcomes cost one full derivation. Returning early for a name it did not recognise would make "does this account exist?" answerable by anyone who can time a sign-in.

Account existence is not a secret, and Peios does not pretend otherwise — it is answered plainly on a different socket, /run/ident.sock, which is how ls -l turns an owner into a name. What the logon socket refuses to do is let you learn it by guessing credentials. See resolving names.

What the audit trail records #

The caller is told only that authentication failed, but the audit trail may know more. Every sign-in leaves two events, one from each side of the conversation:

• authd.logon.attempted, from the authority, once per LogonStart, however the logon ends. It names the originator: the principal of the program that asked, as source.token.sid. It also records the logon type asked for, the principal source asked, and the remote address when the originator gave an IP address. A success adds the principal signed in (subject.token.sid), the new session and the token. A failure adds outcome.reason: the denial the originator was sent, such as authentication-failed, logon-type-not-permitted or account-restricted.
• lpsd.credential.verified, from the local principal source, when it checks a credential. It says what the wire must not. outcome.reason is no-such-account, wrong-credential, disabled or not-permitted, and object.account.sid names the account when one exists.

The name typed is never recorded, in either event. A name the authority could not match to an account is the caller's input, not an identity, and a record of it would turn the audit trail into a list of mistyped passwords and probed usernames. An account appears only by its SID.

authd.logon.attempted is essential, so the emission policy cannot switch it off. lpsd.credential.verified is standard and can be: a machine exposed to a network may be asked to check credentials far more often than it signs anybody in.

Where to start #

• The login command — the terminal client, and how a live image signs in without being asked anything.
• The passwd command — changing your own password.
• Logon sessions — the kernel object a successful sign-in creates.
• Authorities and principal sources — the accounts being signed in to.

The protocol is specified rather than merely documented: PGSS §2 is Logon, and PSPU §2 is PSI, the interface principal sources speak. Read those if you are writing a client or a source of your own.

Signing in on Peios involves three separate things, and it is worth being able to name them before you administer any of them.

The authority is the process that mints tokens. On a stock Peios system that is authd. It listens on /run/logon.sock, it holds the privilege to create tokens, and it is the only thing on the system that does. When you type a password at a login prompt, login is talking to authd.

A principal source is a process that knows who exists. It verifies credentials and answers the question "who is this?" — and nothing else. It cannot mint a token, cannot grant a privilege, and cannot create a session, because the protocol it speaks gives it no way to say any of those things.

lpsd is the local principal source: the one that holds this machine's own accounts. It is where jack lives, and it is what you are administering when you run lps.

Why the split #

It would be simpler to have one daemon that both checks passwords and mints tokens. The split exists because those two jobs have very different risk profiles.

Checking a credential means parsing input that came from outside — from a login prompt, a network connection, a smartcard reader. That is the code most likely to have a defect in it. Minting a token is the most privileged operation on the system.

Putting them in one process means a defect in the first becomes a compromise of the second. So authd mints and cannot verify; lpsd verifies and cannot mint. A completely compromised lpsd can lie about the accounts it holds, and that is the whole of what it can do — it cannot elevate anyone, cannot forge a token, and cannot claim identities that are not its to claim.

The division runs through what a source is even able to say. A source states who someone is: their SID, their memberships, their POSIX identifiers, where their session starts. It never states how much this machine trusts them — privileges and integrity levels are authd's, decided from local policy, and there is no message with which a source could ask for one.

That local policy is a registry key, one record per principal, and it is where you go to change what an account may do as opposed to who it is: assigning privileges.

How they find each other #

lpsd connects to authd, not the other way round. That keeps authd — the process holding the token-minting privilege — free of any reason to open an outbound connection to anything.

At boot, lpsd starts after authd, connects to /run/psi.sock, registers itself, and only then reports itself ready. That ordering means anything that starts after lpsd — login, a greeter, a remote access daemon — finds a system that can genuinely authenticate, rather than one where the processes merely exist.

If you see lpsd failing to start, the usual causes are that authd is not running, or that this machine's configuration does not permit lpsd to register. The second is deliberate: a source must be explicitly allowed to assert identity, and an unconfigured machine permits none.

More than one source #

lpsd is the only source on a stock machine, but nothing about the design assumes it is alone. A directory-backed source can register alongside it, holding domain accounts while lpsd holds local ones, and authd routes each logon to whichever source owns the name.

Each source declares the SID namespace it is authoritative for, and authd confines it there. That is what stops a directory deciding who administers your machine, and equally what stops a local source handing out domain identities.

The same confinement applies to numbers. Sources assert relative POSIX identifiers; authd applies each source's assigned range and refuses out-of-range values. That keeps source-provided numbers clear of uid 0 and other sources' ranges. See Numeric Scope for the rebasing and bounds rules.

Seeing a principal, rather than a number #

Signing in is one half. The other is that everything on the system can turn an identifier back into a name — ls -l showing an owner, id showing a group.

That goes to authd too, on a socket of its own: the authority resolves effective POSIX identifiers and applies the machine's source-search order. See resolving names for what lookup answers mean, and Identity Lookup for the protocol boundary.

Where to start #

• The local store — what lpsd keeps, and where.
• Resolving names — how a name, a SID or a number becomes a principal.
• Creating accounts — the first one, and every one after.
• The lps command — the full reference.

The protocols themselves are specified rather than merely documented: PGSS §2 is Logon, and PSPU §2 is PSI, the interface sources speak. Read those if you are writing a principal source of your own.

lpsd keeps everything it knows in one file:

/var/state/lpsd/principals

It is read once at startup and held in memory. It changes when an authorised account or group change is made, including self-service account changes.

What is in it #

The machine's domain SID. Every local principal is numbered under it, and it is generated — from the kernel's random number generator — the first time lpsd runs on a machine that has no store.

That last point matters more than it sounds. Two machines built from the same image do not share a domain, so the security descriptors written on one do not grant access to the other's users. An image cannot ship a domain, because the domain does not exist until first boot.

The domain is always of the form S-1-5-21-A-B-C. That shape is structural — the store holds three numbers under a fixed prefix, so it cannot express a domain of any other kind. It cannot claim S-1-5-32 (BUILTIN) or any well-known namespace, whatever is written into it.

The principals. For each: a relative identifier (RID), a Unix ID, the canonical spelling of the name, whether the account is enabled, a password verifier, the groups it belongs to, which of them is primary, a home directory, a shell, a display name, and any claims.

A principal's SID is the domain plus their RID. jack with RID 1000 in domain S-1-5-21-A-B-C is S-1-5-21-A-B-C-1000.

RIDs start at 1000 and are never reused. Not even after an account is deleted. That is deliberate and it is the property that makes deletion safe to offer at all: a reissued RID would give a new person the SID of an old one, silently inheriting every access the descriptors on this machine still grant them. It is the one identity mistake that cannot be undone by fixing the account afterwards.

The local groups. A group created here is an object: a RID from the same counter, a name, a Unix ID, and a description of what it is for, which anyone may read. Sharing the counter with principals is what stops a group ever colliding with a user's SID.

Well-known groups — BUILTIN\Administrators, Everyone, Authenticated Users — are not stored. Their SIDs are the same on every Peios machine, so a stored copy could only ever drift from the real one, and provisioning would freeze whatever the table said that day. lpsd resolves their names from a table in its own code.

Unix IDs #

Linux programs call getuid and getgroups and have never heard of a token, so every token carries POSIX numbers alongside the SIDs. Those numbers begin here.

A principal's stored Unix ID is their RID, and a group's is its RID. These numbers are relative: authd adds a base from the registry before the number reaches a token, so jack with RID 1000 stores 1000 and signs in as uid 1001000 when the base is 1,000,000.

The range is a boundary enforced by authd: an out-of-range relative ID is refused, so a source cannot number its principals as uid 0 or in another source's range. Numeric Scope specifies the rebasing and bounds checks.

It also means moving a range is a registry edit rather than a rewrite: nothing stored here was ever absolute.

lps list and lps show display the effective number, with the base already added, because that is the one an operator will see everywhere else. The authority communicates the range at registration for that purpose; lpsd must still assert relative identifiers.

At lookup time, getpwuid asks authd about the effective number; authd queries the relevant source in its relative namespace. See resolving names.

Profiles and claims #

The profile — home directory, shell, display name — is not identity. No security descriptor names a home directory and no token carries one. It is stored here alongside the account, and it travels to login on the logon reply so a session can start without a second lookup.

Claims are named, typed attributes that conditional ACEs read: a descriptor can grant access to anyone whose Department is Engineering without naming principals individually. They are fixed on a token when it is minted, so a claim set now takes effect at the principal's next sign-in.

What is not in it #

Passwords. What is stored is a verifier — an argon2id hash — and a verifier is deliberately not password-equivalent. You cannot authenticate with it, and it cannot be used to answer a challenge.

That is the property that makes stealing the store meaningfully weaker than knowing the passwords. It is also why Peios does not use challenge-response schemes: those require storing something a response can be recomputed from, which is exactly what this avoids.

Each verifier carries the cost parameters it was created with, so raising them applies to passwords set afterwards while existing accounts keep working.

Well-known group definitions. The store defines the groups this machine creates, and records memberships of everything else as SIDs. BUILTIN\Administrators exists on every Peios machine whether or not this store mentions it; lpsd only records that jack is in it.

Privileges and integrity levels. What a principal may do is not stored here at all. authd decides it, from local policy keyed on the SIDs a token ends up carrying — a registry key rather than this file, so that it stays readable by an administrator and this file can stay readable by nobody. A principal source says who someone is; it has no way to say how much this machine trusts them. See assigning privileges.

The descriptor #

The store file is owned by LocalSystem and its DACL grants LocalSystem and nothing else — not even BUILTIN\Administrators.

That is narrower than almost anything else on the system, and it is on purpose. This is the machine's password material, and the list of principals entitled to read it should be as close to empty as the system permits. An administrator who genuinely needs the file can take ownership, which is an act that leaves a trail; a read granted by the DACL does not.

It is also why lps talks to lpsd over a socket rather than editing the file. A tool that wrote the file would need that descriptor widened to whatever the tool runs as, undoing the one thing it exists to do.

A file, not a database #

The store is serialised whole and replaced atomically. Its temporary inode is created with a protected SYSTEM-only descriptor before the first byte is written, flushed, then renamed over the old one. Stale temporary files are unlinked and recreated exclusively; they are never truncated or followed. At startup lpsd establishes a protected SYSTEM-only inheritable descriptor on its state directory before loading or provisioning the store. The final file has the same SYSTEM-only access policy, independent of parent inheritance.

A few hundred principals, rewritten when an authorised account or group change is made, is not a workload that needs a write-ahead log. And because the swap is a rename, a reader sees the old file or the new one and there is no third outcome — which means there is no recovery code, and code that does not exist cannot be wrong.

The file carries a checksum. Not to catch a half-written file, which atomic replacement makes impossible, but because a corrupted store that decoded short would present as an account quietly no longer existing.

Its format, and upgrading #

The file also carries a format number. lpsd reads the format it writes and the one before it: a store written before groups had descriptions loads with every description empty, and is written in the new format the next time anything changes. Nothing has to be done to upgrade it.

Going back is another matter. An older lpsd refuses a store in a format newer than it knows, and does not start, rather than guess at what it cannot read. So once a newer lpsd has changed the store, an older one cannot be put back in its place.

Missing versus corrupt #

These are treated as opposite outcomes, and the distinction is the most important behaviour in this page.

No store at all means an unprovisioned machine. lpsd generates a domain, writes an empty store, and carries on.

A store that will not read, damaged or in a format this lpsd doesn't know, is fatal. lpsd refuses to start.

Collapsing the two — "cannot read it, so make a new one" — would turn a flipped bit into every account on the machine silently ceasing to exist, and then reappearing under a new domain with different SIDs, orphaning every security descriptor that named them. Refusing to start is loud, reversible, and leaves the evidence intact.

If lpsd reports that the store is corrupt, do not delete it. Take a copy first: it is the only record of your machine's identity.

Every program that prints a name for a file's owner is asking the same question: who is this? On Peios that question goes to authd, over a socket of its own:

/run/ident.sock

Separate from /run/logon.sock, but the same standard — PGSS §2 defines both. What separates them is who calls: a handful of things ever originate a logon, where every process on the system resolves names. A filesystem walk is millions of lookups, and it must not be able to fill the queue an administrator needs in order to sign in.

Why the authority, and only the authority #

The protocol assigns this role to the authority: sources assert relative POSIX identifiers and answer numeric queries in their own relative namespace, while applications ask the authority about effective, machine-wide identifiers. The Identity Lookup contract defines that boundary; Numeric Scope explains how the authority applies a source's range even though the source knows it.

The same holds for names. A bare name may exist in more than one source, and which one wins is a property of the machine rather than of any source in it.

One answer, systemwide #

Whatever asks — a Peios tool, a Linux program through getpwnam, a future graphical console — the question goes to the same place and gets the same answer.

There is deliberately no way to arrange otherwise. glibc's identity databases are patched to reach the authority and nothing else, there is no /etc/passwd behind them, and PAM does not exist on Peios at all. Every route by which another system lets identity come from somewhere the authority cannot see has been closed rather than configured.

That is worth more than it sounds. If two components resolved names separately they could disagree, 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. It also means a name resolves identically at a logon and at an ls -l, because the same code answers both.

The search order #

A name nobody qualified is resolved by asking sources in a configured order, stopping at the first that answers.

The order is a value on each source's allowlist entry:

Machine\Software\Authd\Sources\lpsd
    SearchOrder    REG_DWORD    1000

Lower is consulted first. Sources that share a value are ordered by name. A source that sets nothing resolves at 1000, which leaves room to place a new source either side of the ones already there without renumbering them.

It is deliberately explicit. Resolving in the order sources happened to register would let a slow disk change which principal a name refers to.

Warnings about shadowed names #

If more than one source holds the same bare name, only the first owner in the search order answers the logon. After delivering a successful logon reply, authd asks later sources whether they also own that name. These are identity queries with no credentials or authentication assertion attached.

Each confirmed duplicate produces a warning in authd's service log, naming the entered name, its owning source and the later source. The warning does not change the token or select a different principal. Administrators should check whether an old local account is hiding a directory account, or whether a source order change has made a different SID win for a familiar name.

An absent, refusing or unavailable source makes the check inconclusive, not a failed logon. The success reply and normal logon audit record precede the check. All the later sources share one normal five-second lookup deadline; there is no extra query on a single-source machine or when the owning source is last. If the owning registration has disappeared or been replaced during authentication, authd skips the check rather than assuming its old position still holds. Absence of a warning therefore does not prove that a name is unique.

Bare in, qualified out #

You may look a principal up by a bare name. What comes back always carries the SID as well as the name.

So a tool can always tell which principal it got, compare two answers for identity, and record something unambiguous in a log. Ambiguity is permitted in what you ask; it is not permitted in what the authority answers.

Reserved characters #

A principal or group name may not contain @, \, /, : or ,, may not begin or end with a space, and must be printable ASCII.

Each of those is a separator somewhere a name ends up — a path, a passwd record, a group member list — and the damage is done by whatever reads it later, so it cannot be prevented at the point of display. @ and \ are reserved for qualified names (jack@local), which do not exist yet: reserving them now is what stops an account literally called jack@local colliding with the syntax the day it arrives.

The ASCII restriction defers confusables and normalisation rather than getting them wrong. jack spelled with a Cyrillic а renders identically and is a different principal, and the same name in NFC and NFD is two byte sequences a comparison calls two people. Relaxing this later is safe; tightening it later would mean renaming accounts.

Absent is not the same as missing #

Three answers, and the difference between the last two is the one worth knowing:

A source that is configured and not running does not simply drop out of the order. If lpsd has crashed, jack resolves to unavailable — not to a directory's jack further down the order, which would be a different principal with a different SID, and every security descriptor granting the local one would stop applying to the person signing in under that name.

It also matters because not found is safe to remember and unavailable is not. A cache told "no such user" during an outage would keep saying so long after the outage ended.

Groups you cannot list #

Ask who is in a local group and you get its members. Ask who is in Everyone and you get nothing — and that is the correct answer rather than a limitation.

Membership comes in three kinds:

Recorded. Local groups, and the BUILTIN groups: Administrators, Users and Guests. A source holds the edges, so it can list them, and authd gathers a BUILTIN group's members from every source that may record them. (Note that being well-known has nothing to do with it — Administrators is well-known and perfectly enumerable.)

Stapled. Everyone, Authenticated Users. Nothing records who is in them; authd adds them to every token it mints. Membership is a rule, not data, so there is no list to produce.

Session-scoped. Interactive, Remote Interactive, Network, Batch, Service. These are not properties of an account at all, but of a logon: jack is in Interactive at the console and not in it over the network. No static answer exists even in principle, which is why they have no POSIX group id either.

The asymmetry that falls out is the useful one. Which groups is this principal in is cheap and always works. Who is in this group is best-effort, and a source is entitled to decline it — listing a directory group can mean listing an entire organisation.

Every lookup is live #

The authority holds no cache. Each lookup it receives is a fresh round trip to the source that holds the answer.

That is a deliberate first step rather than an oversight: a cache is invisible on both sides of the wire, so adding one later changes nothing about how any of this behaves. Sources already declare what one will need — whether they can push a change notification, and how long an answer may be held — so the contract is in place before the thing that uses it.

One thing does cache, and only within a single command. Turning a SID into a name for display — the owner column of ls -l, and the same rendering everywhere else in the userland — remembers what it has already asked for the lifetime of that one process, so listing a large directory owned by a handful of principals costs a handful of lookups rather than one per file.

It is scoped that way on purpose. Two separate commands share nothing, so an account renamed between them shows its new name on the very next one, and there is no stale answer to invalidate because there is nothing that outlives the command. This is what a Linux system already does for getpwuid, so ls behaves the way its users expect.

Names that are fixed by specification rather than held by any source — Everyone, Local System, BUILTIN\Administrators and the rest — are answered from a table built into the renderer and never asked about at all. There is nothing a source could add to them, and asking would mean a large listing querying the authority thousands of times about Everyone, and printing something different depending on whether the authority happened to be running.

Name service switch lookups — getpwnam and friends — are not cached anywhere. Each is its own connection and its own round trip.

Asking from a program #

A Linux program asks through getpwnam and friends, and needs nothing more. A Rust program that wants the answer itself — a SID's name, or every principal there is — can use the libauthd-client crate in the authd repository. The name service switch module, ls and the other userland tools, Principals Manager and the permissions editor all ask through it.

It keeps the three answers apart: not found comes back as no principal, and a failure says what it was. Its transient says whether asking again could help, which is true when authd didn't answer in time or a source that could have answered didn't. Each question has a connection of its own, unless the program holds one for a walk through a long listing, a page at a time.

Where to go next #

For how Linux programs reach this resolution through getpwnam and friends, read Name service switch.

For where the local principals being resolved actually live, read The local store.

Impersonation is the mechanism that lets one thread temporarily act as another principal. The thread installs a second token — an impersonation token — and from that moment until it reverts, every access decision on that thread reads the impersonation token instead of the thread's primary. Other threads in the same process are unaffected. The primary token is preserved untouched and resumes its role the instant the thread reverts.

Impersonation exists because of one stubborn fact: most code that handles user requests does not run as the user. A storage service runs as a service account, a database runs as postgres, the registry daemon runs as loregd. When a real user asks one of these services to do something, the work has to be evaluated against the user's rights, not the service's. Impersonation is how that swap happens cleanly.

The two-token model #

A thread can have two tokens at once:

flowchart LR
    A["Thread"] -->|primary token, always| B["Primary token, the service's identity"]
    A -->|impersonation token, while impersonating| C["Impersonation token, the client's identity"]

While the impersonation token is installed, every AccessCheck on that thread reads it. The primary is invisible until revert. Other threads in the same process still read their own primary tokens — impersonation is strictly per-thread.

Two consequences worth knowing up front:

• The process's identity does not change. Other processes inspecting this one still see the primary token as the process's identity. Tools like ps, /proc/<pid>/token, and audit events that record the process identity all report the primary. Only the thread's own view is overridden.
• The PSB does not change. A thread impersonating a higher-trust token does not get higher process integrity protection. PIP is a property of the binary running, not of the impersonation token. See Process integrity protection for the why.

A canonical server flow #

The simplest case — one OS thread, one request, start to finish — follows a flow like this:

flowchart LR
    A["Client connects"] --> B["Server accepts"]
    B --> C["Server calls peios_token_impersonate_peer(fd)"]
    C --> D["Server does the work"]
    D --> E["Server calls kacs_revert()"]
    E --> F["Server handles next request"]

1. Client connects. Before connect, the client may have set KACS_SO_IMPERSONATION_LEVEL on the socket (peios_socket_set_impersonation_level) to bound how far its identity may travel (see Impersonation levels).
2. Server accepts. The kernel captures the client's identity onto the socket at connect time.
3. Server impersonates. A call to peios_token_impersonate_peer(fd) installs the captured identity onto the calling thread, at the effective level determined by the two-gate model.
4. Server does the work. Every access check on this thread now runs against the client's identity. File opens succeed if the client could open the file; registry reads succeed if the client could read; and so on.
5. Server reverts. kacs_revert() drops the impersonation token. The thread is back to its primary identity for the next request.

A server that handles many concurrent clients impersonates separately per thread. A server that handles requests serially impersonates and reverts in a loop. Either way, the impersonation is always a bracketed operation — install, do work, revert.

Just-in-time impersonation #

The canonical flow above assumes one OS thread is dedicated to one request from start to finish. That model fits a thread-per-connection server, but it does not fit most modern application runtimes. In Go, a goroutine can be scheduled onto any of the runtime's worker threads, and may move between them at any await point. In Rust's async runtimes, in Java's virtual threads, in Node's event loop — wherever you have M:N scheduling, the "impersonate at the top of the request, revert at the bottom" pattern is unsafe. The impersonation is installed on whichever OS thread happened to be running when the call was made; the request may continue on a different OS thread an instant later.

Most real Peios applications use just-in-time impersonation instead: capture the client's identity as a token fd at request start, hold the fd in the request context, and install it on the current OS thread only for the brief moment of the access-requiring action, reverting immediately after.

flowchart LR
    A["Accept connection"] --> B["Capture peer fd"]
    B --> C["Service-identity work"]
    C --> D["Install token, one action, revert"]
    D --> E["More service-identity work"]
    E --> F["Install token, one action, revert"]
    F --> G["..."]
    G --> H["Close token fd"]

The sequence:

1. At accept, the server calls peios_token_open_peer(fd) to capture the client's identity as a token fd. The fd is stored in the request context — request struct, goroutine-local, whatever the runtime provides.
2. Most of the request is processed as the service's own identity. Decoding, dispatching, internal bookkeeping, response framing — none of these need the client.
3. When the code reaches the one operation that requires the client — opening a user-controlled file, reading the user's home directory, anything where the access decision must be the client's, not the server's — it installs the impersonation token on the current OS thread (KACS_IOC_IMPERSONATE), does the single operation, and calls kacs_revert immediately.
4. The request continues at service identity. Further per-request impersonations follow the same install-do-revert pattern.
5. At end of request, the captured token fd is closed.

This pattern has two real advantages over the canonical flow:

• It is safe under multiplexed threading. The impersonation is installed and reverted within a tight, synchronous block of code that does not yield to the runtime, so the runtime cannot move the work to another OS thread mid-impersonation. The token fd in the request context travels with the request regardless of which thread is currently executing it; only the install-do-revert window actually pins a thread.
• It minimises the time spent impersonated. Bugs where the wrong code runs as the wrong identity — a logging call between impersonate and the real work, an error path that forgets to revert, an unrelated background task pre-empting on the same thread — are bounded by the same tight block. Most of the request is unambiguously the service's identity; only the access-requiring call is the client's.

The cost is a small amount of boilerplate at every impersonation point. The performance cost is negligible: install and revert are pure in-kernel operations with no allocation and no IPC.

If you are writing a new service for Peios in a modern runtime, this is the pattern to start from. The canonical flow above is the simple-case reference; just-in-time is the realistic default.

Why not just run the server as the user? #

The reason impersonation exists rather than "spawn one server process per user" is the cost. Long-lived services that handle many users — a file server, a database, the registry daemon — would otherwise need one process per concurrent session. Impersonation lets a single long-lived service process handle requests for arbitrary users by swapping identities per thread, paying only the cost of an in-kernel token install per request.

The trade-off is that the server has to be careful. Code paths that touch user-controlled state are expected to be running impersonated; code paths that touch service-internal state (its own configuration, its own logs) are not. Mixing these up is the most common bug category in services written for this model: a request handler that opens a user-controlled path while still running as the service account, or a maintenance routine that touches the service's own state while still impersonating the last client.

The pattern that minimises this is to make impersonation the default state of a request thread and revert only at well-defined boundaries (logging, internal bookkeeping, between requests).

What impersonation does not do #

A few things impersonation looks like at a glance but is not:

• It does not invent new authority. The impersonation token carries the client's privileges, integrity (capped at the server's own — see The two-gate model), groups, and SIDs intact, and the impersonating thread can exercise any of them on the client's behalf. What impersonation does not do is grant more than the client had, raise integrity above the server's ceiling, or change the binary's PIP.
• It does not give the server arbitrary identity. The server can only assume identities the kernel has handed it — through a captured peer token, or through a token fd the server already possessed by some other path. There is no API to fabricate an impersonation token from a SID string.
• It does not grant inherent access. Impersonating a user is not a master key to the user's data. The user's home directory, registry keys, and in-flight tokens are reachable if and only if the user themselves has access — the access check still runs to decide. Impersonation is the mechanism for evaluating that check as the user; it is not the access itself.
• It does not survive exec. A thread that execs while impersonating has its impersonation token released before the new program runs. Impersonation is intra-program state; the new binary cannot inherit it.

Where to start #

If you want to understand the four impersonation levels — Anonymous, Identification, Impersonation, Delegation — and what each one permits, read Impersonation levels.

If you want the rules that decide what level a server actually ends up with — the identity gate, the integrity ceiling, and the silent downgrade behaviour — read The two-gate model.

If you want the concrete mechanics — peer token capture from sockets, the difference between peios_token_impersonate_peer and peios_token_open_peer, and the explicit-fd variant — read Peer tokens and capture.

Every token carries an impersonation level — one of four values, ordered from least to most permissive. On an impersonation token it is the answer to "how much may a server do with this identity?". On a primary token it is the ceiling on everything derived from that process's identity. Each level admits all the operations of the levels below it and additionally allows specific extra things.

There is one rule worth pinning before the catalog: the level is set by the client, not the server. A client sets KACS_SO_IMPERSONATION_LEVEL on the socket (setsockopt under the SOL_KACS level, or peios_socket_set_impersonation_level) before connect() to declare the maximum level a server may use. The kernel records the level on the socket. When the server later impersonates the peer, the level cannot exceed what the client set. A server cannot ask for a higher level; it can only end up at the level the client granted or lower.

The four levels #

The numeric values are also catalogued in Other constants.

The default — what a socket carries if the client never sets a level — is Impersonation. This default exists because the vast majority of clients want their server to be able to act on their behalf; making the no-action case the conservative one would push every client into boilerplate.

Anonymous #

The least useful level, and not as common as you might expect. An Anonymous impersonation token has:

• A user SID of S-1-5-7 (the well-known Anonymous SID).
• The Everyone group, but not Authenticated Users.
• Untrusted integrity.
• No privileges.

A server impersonating an Anonymous client effectively has no identity at all. It can act, but every access check is evaluated as Anonymous — which usually fails because almost every interesting object's DACL grants nothing to Everyone-but-not-Authenticated-Users.

You will mostly see Anonymous in two cases:

• A client explicitly opted out of identity disclosure. Some protocols want the server to act on a request without knowing who issued it. The client sets its socket's level to Anonymous; the server impersonates and gets Anonymous.
• A connection that was never authenticated. A network peer that connected without going through any auth step is, from the server's point of view, Anonymous. The token reflects this honestly.

Identification #

The most misleading level. Identification gives the server enough of the client's token to inspect identity but explicitly forbids using it for access decisions. AccessCheck with an Identification-level token returns ACCESS_DENIED immediately, before reading the DACL.

The intended use is for servers that need to know who is asking — for audit logging, for routing decisions, for displaying a username — without actually wanting to act as them. A web server that logs which user made each request but always reads files as itself wants Identification.

The pitfall: a server that thinks it is doing Impersonation but the client set the level to Identification finds every file open returning ACCESS_DENIED for reasons that look nothing like an identity problem. The DACL is fine; the user has rights to the file; the server's primary identity has rights to the file. Yet every access fails. The cause is almost always that the client connected at Identification level and the server is supposed to be inspecting, not acting.

The fix is at the client end. If your server has to act on behalf of the user, the client must connect at Impersonation level (or accept the default — which is already Impersonation).

There is one specific construction that always produces an Identification-level token: KACS_IOC_GET_LINKED_TOKEN called without SeTcbPrivilege returns an Identification-level clone of the partner token. The clone is for inspection only — it cannot be installed and would fail every access check if it were. See Elevation and linked tokens.

Impersonation #

The level you will use almost all of the time. An Impersonation-level token can act as the client for any local operation:

• Open files as the client.
• Read and modify registry keys as the client.
• Connect to other local services as the client (and have those services impersonate the same client — see "Identity cascading" in Peer tokens and capture).
• Be the subject of any AccessCheck call.

What an Impersonation-level token cannot do is cross the machine boundary with the client's identity. If the impersonating service makes a network request that requires authentication, that request goes out using the service's credentials, not the client's. The client's identity stays on this machine.

That last point is the dividing line between Impersonation and Delegation.

Delegation #

Delegation extends Impersonation to remote calls. A server at Delegation level can act as the client locally and forward the client's identity to a remote machine over Kerberos. The remote service receives a token that represents the original client, not the intermediary.

The mechanism is entirely in authd. KACS records that the impersonation token was granted Delegation; the kernel does nothing further. When the impersonating server makes an outbound network request, authd consults the token's level. If it sees Delegation, authd performs the Kerberos credential forwarding (constrained or unconstrained, depending on the domain policy). If it sees only Impersonation, authd authenticates the outbound request as the server's own identity.

The split — KACS records the flag, authd acts on it — keeps the kernel out of the Kerberos business. It also means Delegation is meaningful only on domain-joined machines where authd has Kerberos configured. On a standalone machine, Delegation is recorded but has no effect, since there are no remote services to forward to.

What sets the level #

Three things determine the level a server actually ends up with:

1. The client's request, set on the socket with the KACS_SO_IMPERSONATION_LEVEL socket option (peios_socket_set_impersonation_level) — usually before connect, though it can change at any time and bounds every capture made from then on. Default is Impersonation if the client says nothing.
2. The two-gate model, applied at impersonation time: the identity gate and the integrity ceiling. Either can cause the granted level to be silently downgraded. See The two-gate model.
3. The transport. Datagram and socketpair sockets capture nothing at connect, so identity on them travels per message (KACS_SO_PASS_TOKEN or a KACS_SCM_TOKEN cmsg); pipes carry no identity at all, and a server on a pipe must obtain a token some other way and use the explicit-fd ioctl. See Peer tokens and capture.

The first sets the maximum. The second can lower it. The third is about the mechanism for getting the token at all.

There is a fourth input that usually never shows, because it starts at the top: the client's own token. The level is a ratchet. A logon token from authd starts at Delegation, and every step identity takes — a capture at connect, a KACS_SO_PASS_TOKEN send, a KACS_IOC_DUPLICATE in either direction — produces something at or below its source. A process running on a primary that was made from an Impersonation-level token can set Delegation on every socket it opens and still conveys Impersonation. Nothing short of a fresh CreateToken (SeCreateTokenPrivilege) goes back up, which is what makes the client's original choice hold across any number of services and process launches.

Inspecting the granted level #

A server that has just impersonated can read its own effective token to check what level it actually got. Reading the impersonation_level field of the effective token (via KACS_IOC_QUERY on the thread's token fd) returns the level in effect.

This is worth doing at runtime if your code branches on level. The "client asked for Impersonation, but the integrity ceiling silently downgraded to Identification" case is silent by design — the impersonation call succeeds and the work proceeds, but every access check on the downgraded token will fail. Code that wants to detect the downgrade before doing access-requiring work should query the level first and skip work for which the level is insufficient.

Where to go next #

For how the kernel decides the level a server actually ends up with — and why the downgrade is silent — read The two-gate model.

For how a server gets hold of a client's identity in the first place, read Peer tokens and capture.

When a server impersonates a client, it does not automatically get the level the client granted on the socket. The kernel runs two independent gates first. Each gate can lower the effective level. The granted level is the minimum the two gates permit.

The two gates are:

1. The identity gate — is the server allowed to impersonate this particular user's identity?
2. The integrity ceiling — may the impersonation token's integrity level exceed the server's own?

Each gate is checked independently. Failing either one is silent: the impersonation call still succeeds, the level is silently capped, and the server only finds out by inspecting the resulting token. The kernel deliberately does not raise an error, because the requested level is the maximum — any lower level is a valid outcome.

There is one case where the kernel refuses outright with -EPERM rather than downgrading. That case is covered below.

Gate 1: identity #

The identity gate asks: does the server have authority to impersonate this specific user? It has two ways to pass:

• The server's primary token has the same user SID as the client. A process can always impersonate its own user, regardless of privileges.
• The server's primary token holds SeImpersonatePrivilege. The privilege explicitly grants the right to assume any user's identity.

If neither is true, the identity gate fails. The token still gets installed, but the effective level is capped at Identification — the server can inspect the client's identity but cannot use the token for any access check.

The split is deliberate. A service whose job is handling user requests — a file share, a database, the registry daemon — holds SeImpersonatePrivilege and can impersonate any user. A process running as user X can act as user X without any special privilege. Code that holds neither — a random user-mode process trying to install some other user's token — is restricted to inspection only.

SeImpersonatePrivilege is one of the few privileges that authd grants liberally to services in the role-policy assignment. Almost every service that handles user requests has it. The privilege is what distinguishes "code authorised to act as users" from "code that happened to receive a token fd".

Gate 2: integrity ceiling #

The integrity ceiling asks: does the impersonation token's integrity level exceed the server's own primary token's integrity level?

If it does — the client has High integrity, the server has Medium — the effective impersonation level is silently capped at Identification. The token still installs, and the client's integrity label may be preserved as inert identity metadata, but the token cannot pass any access check.

The motivation is concrete. Without the ceiling, a Medium-integrity service that captured a High-integrity client's token would suddenly be operating at High integrity for the duration of the request. That breaks the integrity model — a process's effective ceiling should be bounded by what it would have had on its own.

The ceiling is always enforced, and it caps the level, not the token's integrity label. SeImpersonatePrivilege does not bypass it. There is no privilege that does. A service that needs to act on behalf of a High-integrity client must itself run at High integrity.

Composition: the minimum permitted #

The two gates are independent. Each one decides what level it permits:

The granted level is the minimum the two gates permit. Neither gate fails the operation; both can downgrade it. The downgrade is silent.

The silent downgrade #

This is the consequence worth memorising: impersonation never errors on policy failure. It silently downgrades.

A server that calls peios_token_impersonate_peer(fd) and gets a successful return does not know whether the resulting token has the level it expected. Both an Impersonation-level token and an Identification-level token can come out of the same call, with no error in either case. The only way to tell is to query the token after install.

Code that wants to detect a downgrade has to do something like:

1. Call peios_token_impersonate_peer(fd) (or the explicit-fd variant).
2. Open the thread's effective token.
3. Read impersonation_level via KACS_IOC_QUERY.
4. Branch on the result: proceed if Impersonation or Delegation, log-and-skip if Identification or Anonymous.

The reason for the silent design is that the gates are bounded by policy and the policy is the operator's decision. A service may legitimately want to handle requests from clients regardless of whether it can fully impersonate them — recording who asked for what even when it cannot act as them is useful. Making the downgrade an error would force every server to either bypass the failure or refuse to handle the request, neither of which is the right default.

The one hard-deny case #

There is exactly one situation where impersonation fails with an error rather than downgrading: a restricted token attempting to impersonate an unrestricted token of the same user.

The kernel refuses with -EPERM. The impersonation does not happen, the thread does not get a new token, the call returns an error.

The reason is sandbox-escape prevention. A process running on a restricted token — a sandbox process, an anti-malware quarantine — is supposed to have narrowed identity. If that process could impersonate an unrestricted version of the same user, the restriction would be trivially escapable: capture any token fd belonging to the same user (which the sandbox could obtain via socket peer capture or other means), impersonate, and suddenly the sandbox is running with full user identity.

The hard-deny applies specifically to the same-user case. A restricted process can still impersonate a different user's token, subject to the normal gates. It just cannot use impersonation as a way to "promote" itself back to the unrestricted version of its own identity.

This is the only impersonation case that errors. Every other policy failure is silent.

Double impersonation #

A thread that is already impersonating can install a second impersonation token. The kernel handles this by silently reverting the first impersonation before installing the second — there is no nesting.

The gates are evaluated against the primary token, not the current impersonation. Whatever the thread was previously impersonating does not affect what it can impersonate next. The primary's identity and privileges (notably SeImpersonatePrivilege) are what the kernel reads to decide both gates.

When the gates do not apply #

The gates fire on impersonation install. They do not fire on:

• Reverting. kacs_revert always succeeds and does not consult the gates.
• Reading a token. peios_token_open_peer or kacs_open_thread_token returns a token fd without impersonating; the gates only run when the token is actually installed on a thread.
• Process token operations. Opening another process's primary token (kacs_open_process_token) is governed by the process SD and PIP dominance, not the impersonation gates.

The gates are specifically about installing a foreign identity on a thread. Reading information about a token is a different operation governed by different checks.

The principle behind the model #

The two-gate model is the kernel's enforcement of one rule: a thread can never end up at a higher effective trust level than it could have reached on its own.

The identity gate makes sure the impersonation has authority behind it: either the same user, or the explicit SeImpersonatePrivilege that says "this service handles users by design". The integrity ceiling makes sure the impersonation cannot raise the server's effective integrity. Together they bound impersonation to what the server's own primary token would have permitted.

Everything else is a consequence. The silent downgrade exists because the requested level is a maximum, not a promise. The restricted-token hard-deny exists because that one case is the only way a same-user impersonation could increase authority rather than decrease it. The PIP exclusion (covered in Process integrity protection) is the same rule applied to the binary's trust label: PIP is a property of the binary, not of an identity, and impersonation does not change which binary is running.

Where to go next #

For the capture mechanism the gates run against — how a client's identity gets onto a socket and into the server's hands — read Peer tokens and capture.

For the restricted tokens behind the one hard-deny case, read Restricted and write-restricted tokens.

When a client connects to a server over a connected Unix socket, the kernel captures the client's identity onto the socket at connect time. The server can later impersonate that identity by calling peios_token_impersonate_peer(fd) on the connection — no further negotiation, no credential exchange, no token transfer in the message stream. The token is held by the kernel and tagged to the socket from the moment of connect.

This is the primary way servers acquire impersonation tokens. Almost every local IPC in Peios — registry access, service-to-service calls, user-to-daemon requests — goes through it. The model is simple enough that most services need to know only one call (peios_token_impersonate_peer) and one cleanup call (kacs_revert).

The kernel surface behind it is a socket option. Every KACS socket option lives under one option level, SOL_KACS, and the peer token is getsockopt(fd, SOL_KACS, KACS_SO_PEER_TOKEN, &token_fd, &len) on the accepted connection: the kernel writes a new token fd into the option value. libpeios wraps that as peios_token_open_peer(fd), and peios_token_impersonate_peer(fd) is the same call followed by an install and a close.

This page covers the capture mechanism, the two ways of using a captured peer token, the transports that do and do not carry peer tokens, and how identity cascades when a service that is itself impersonating connects to a third service.

Capture at connect time #

flowchart LR
    A["Client thread, primary token T_C"] -->|"KACS_SO_IMPERSONATION_LEVEL (optional)"| B["Socket"]
    A -->|connect| C["Server socket"]
    B -.->|captured at connect| D["Peer token on server side, derived from T_C at the client-requested level"]

When the client calls connect() on a Unix stream or seqpacket socket, the kernel:

1. Reads the client's effective token (impersonation if set, primary otherwise).
2. Reads the impersonation level the client requested on the socket with KACS_SO_IMPERSONATION_LEVEL (default Impersonation). The option can be changed at any time; it bounds every capture made from then on.
3. Constructs a peer token derived from the client's token, at the requested level.
4. Attaches the peer token to the server-side socket.

The peer token is held by the kernel for the life of the socket. The client's identity travels into the kernel at connect, not at impersonate. By the time the server reads the peer token, the work of capturing identity is already done.

What the server reads is the connection's conveyed-identity register: the peer identity that goes with the data the server has consumed so far. The connect-time capture is its first value, and it stays that unless the client conveys a new identity with the data itself (next section). Whatever it holds, it is always an immutable snapshot — each read of KACS_SO_PEER_TOKEN returns a fresh fd, two reads may name different tokens, but no token ever changes under you.

Identity that travels with the data #

A single identity per connection is the right model for a client that connects, acts as itself, and disconnects. It is the wrong model for two things real systems do constantly:

• Connection pooling. A service keeps a few long-lived connections to a downstream service and reuses them for many requests, on behalf of many different users. The identity at connect time is the pool's; the identity that matters is whoever is writing this request.
• Proxies and routers. One process accepts from many clients and forwards their messages over its own connections. Its outbound connection carries one connect-time identity, but it is speaking for many.

Both are solved by letting identity travel in-band, attached to the bytes it describes, as a KACS_SCM_TOKEN ancillary message under the SOL_KACS level. It arrives ordered with the data — the kernel never coalesces bytes conveyed under different identities into one read — and as the server's reads pass each one, the register moves to it. There is nothing to listen for: the server reads a request, then asks KACS_SO_PEER_TOKEN who sent it.

There are two ways to send it, and the receiver cannot tell them apart, because the kernel guarantees the same thing for both: the sender could be this identity when it sent these bytes.

• Automatically, by setting KACS_SO_PASS_TOKEN on the sending socket (peios_socket_set_pass_token). From then on every send carries the sender's effective identity, derived at the socket's impersonation level. This is the fix for pooling: a service that impersonates user A and writes through an off-the-shelf client library conveys A, because the capture happens at the sendmsg the library was already calling. Nothing in the library changes.
• Explicitly, by attaching a token fd in a KACS_SCM_TOKEN cmsg on sendmsg. This is the fix for proxies: the router holds each client's token fd (read from its own inbound connection) and attaches it to the messages it forwards downstream. The kernel gates the attach as if the sender were impersonating that token — the fd needs TOKEN_IMPERSONATE, and if the two-gate model would cap the token below its own level the send fails with EPERM rather than quietly downgrading. Attaching is never more than impersonating, sending, and reverting; it just skips the install.

On the receiving side, a KACS_SCM_TOKEN cmsg (carrying a fresh TOKEN_QUERY | TOKEN_IMPERSONATE | TOKEN_DUPLICATE fd) is delivered with a read when the call supplied control-buffer space and the read's identity differs from what the register held. A server that never touches ancillary data loses nothing — the register is kept by the kernel regardless — which makes the simple loop the right default:

n = recvmsg(conn, &msg, 0);              /* just the data */
tok = peios_token_open_peer(conn);       /* who sent what I just read */

Parsing the cmsg is the path for pipelined or concurrent consumers that need each token bound to a specific message. SOCK_SEQPACKET keeps that association exact by construction (one send, one message, one identity), which is why it is the recommended socket type for Peios-native protocols; on SOCK_STREAM a read simply stops at each identity boundary.

Datagram sockets have no register (many senders share one socket), so on SOCK_DGRAM per-message identity is the only kind: each datagram carrying a token delivers it.

Two ways to use a peer token #

libpeios exposes two operations on a peer token:

• peios_token_impersonate_peer(fd) — the combined operation. Reads the peer's identity from the socket and installs it on the calling thread, at the level the two-gate model permits, then closes the token fd. The most common path.
• peios_token_open_peer(fd) — the inspect-and-store operation: getsockopt(SOL_KACS, KACS_SO_PEER_TOKEN). Returns a token fd to the peer's identity without installing it. The fd carries TOKEN_QUERY | TOKEN_IMPERSONATE | TOKEN_DUPLICATE access — enough to read the token, to install it later via KACS_IOC_IMPERSONATE, and to duplicate it (for instance to a primary token for a process launched as the client), but not enough to adjust it. Duplicating never raises the level: the copy is capped at whatever the client granted.

The two operations exist because servers have different needs:

• Direct request handling. A request thread that wants to impersonate, do work, and revert all in one tight synchronous block calls peios_token_impersonate_peer and then kacs_revert. There is no reason to hold the token fd around.
• Just-in-time impersonation. A server that wants to keep the client's identity available across a request but only install it at the moment of each access-requiring action — the just-in-time pattern covered on the overview page — calls peios_token_open_peer to capture the token fd at request start, stores it in the request context, and installs it on the current OS thread (KACS_IOC_IMPERSONATE) just before each action that needs the client's identity, reverting immediately after. This is the right pattern for any server using a multiplexed runtime (Go, Rust async, Java virtual threads, Node), and is the recommended default for new services.
• Deferred work across threads. A request handler that hands off work to a thread pool cannot reasonably keep its own thread impersonating while another thread does the work — impersonation is per-thread. The same peios_token_open_peer mechanism lets it capture the token fd, pass it to the worker, and have the worker install it before doing the access-requiring operation.
• Inspection without action. A logging or audit thread that wants to record the client's identity without doing any work as them calls peios_token_open_peer, queries the token via KACS_IOC_QUERY, and closes the fd. No impersonation is ever installed.

The "capture once, install per action" pattern is the main reason for separating the two operations. It is what makes safe impersonation possible under M:N threading and what bounds the time a thread is actually impersonated to the smallest window that does the work.

kacs_revert and the explicit-fd variant #

A thread reverts impersonation with kacs_revert(). It always succeeds. It drops the impersonation token reference and restores the primary as the effective identity.

There is also KACS_IOC_IMPERSONATE — an ioctl on a token fd, not on a socket. This is the explicit-fd variant. The caller passes the fd of a token they have obtained by some other means (DuplicateToken, the peer-token option, etc.) and the kernel installs it on the calling thread, running the two-gate model as usual.

peios_token_impersonate_peer is exactly peios_token_open_peer followed by KACS_IOC_IMPERSONATE and a close, fused for the common case where you do not need the token fd to outlive the impersonate-and-revert cycle. It is a library convenience: the kernel's only impersonation entry is the ioctl.

Transports that carry peer tokens #

Peer token capture works on Unix sockets that have a real connect step. Specifically:

A stream or seqpacket socket that is not yet connected fails with ENOTCONN. Servers using a transport that does not carry a peer token cannot use peios_token_impersonate_peer. They have to obtain a token fd by some other path and use KACS_IOC_IMPERSONATE to install it. Common patterns:

• Token fd passed over the connection. A datagram protocol can include a token fd in an SCM_RIGHTS message; the receiver gets the fd and impersonates from it. The token fd has whatever access the sender opened it with, bounded by what the sender held.
• Out-of-band capture. A service that knows the peer's PID can call kacs_open_process_token(pidfd) to get the peer's primary token (subject to the process SD and PIP dominance checks). Less common; usually only the loopback-like patterns inside the TCB work this way.

The lack of peer tokens on datagram and pipe transports is intentional, not an oversight. Those transports are fundamentally connection-less or pre-existing; capturing a "peer" identity that may not exist is ill-defined.

Verifying the server #

Capture is symmetric. When the client's connect() completes, its own socket's register holds the identity of whoever called listen() on the name it reached, at Identification level unless the server raised its listener's level — enough to verify, not enough to impersonate. So a client checks the service it is about to trust with one call:

int server = peios_token_open_peer(sock);   /* who is actually listening */
/* query its user SID, compare with the principal the service is expected to run as */

This is what makes a socket path safe to connect to even when the path itself could have been bound by someone else: the name is a rendezvous, the token is the proof. A process that ends up holding a listener it did not create — one returned from peinit's descriptor store after a restart, or one handed over by a broker — calls peios_socket_restamp on it before accepting, so that clients see the process actually serving them rather than the one that originally called listen().

Identity cascading #

A service that is impersonating client A may itself need to call a third service. When it does, the connection it opens carries A's identity, not the service's own.

flowchart LR
    A["Client A"] -->|connect| B["Server S1, impersonating A"]
    B -->|connect to S2 while impersonating| C["Server S2"]
    C -.->|peer token sees A, not S1| D["S2 can impersonate A"]

The mechanism: the impersonation token is the thread's effective token, and the effective token is what the kernel reads when capturing peer identity at connect. So when S1, while impersonating A, calls connect() on a socket to S2, the kernel captures A's identity onto S2's side of the socket. S2 can then call peios_token_impersonate_peer and get A.

This cascading is automatic and is what makes the local-IPC ecosystem work cleanly. A user makes one request to a service, and that service makes downstream requests to other services on the user's behalf — registry, file system, audit logging — and each of those downstream services sees the user as the peer. No explicit token forwarding is required.

The cascading is bounded by the impersonation level the original client granted. If A connected at Impersonation level, S1 captures A at Impersonation; when S1 connects to S2, the captured identity on S2's side is bounded by what S1's effective token currently is — which is A at Impersonation. The level does not get re-extended by cascading.

The same mechanism reaches the network boundary only at Delegation. If A connected at Delegation level, the captured identity on cascaded local connections is still A at Delegation, and outbound network calls from S1 carry A's Kerberos credentials (via authd; KACS only records the flag). Without Delegation, network calls from S1 go out as S1, not as A.

What the server has to do #

There are two server-side shapes, depending on which pattern (canonical synchronous or just-in-time) the server is using. Both start at the same point — the kernel has captured the client's peer token onto the socket at connect time — and diverge after accept.

Canonical synchronous flow (one OS thread, one request, start to finish):

1. Accept the connection. Standard accept() on the Unix socket. The kernel has already captured the client's peer token onto this socket.
2. Impersonate the peer. Call peios_token_impersonate_peer(fd). The kernel runs the two-gate model and installs the resulting token.
3. (Optional) Inspect the granted level. Read the thread's effective token's impersonation_level. If it is below what you expected, the client's request, the identity gate, or the integrity ceiling has lowered it.
4. Do the work. Every access check on this thread is now against the impersonation token.
5. Revert. Call kacs_revert(). The thread is back to its primary identity.
6. Handle the next request. Either on the same connection (loop back to step 2 if the client may re-impersonate per request) or on the next connection.

Just-in-time flow (the right shape for any modern runtime — Go, Rust async, etc. — and the recommended default):

1. Accept the connection. As above.
2. Capture the peer token fd. Call peios_token_open_peer(fd) and store the returned token fd in the request context. The fd carries TOKEN_QUERY | TOKEN_IMPERSONATE | TOKEN_DUPLICATE.
3. (Optional) Inspect the captured token. Query the captured fd to verify the identity and level before doing any work.
4. Do most of the request as the service. Decoding, dispatch, internal bookkeeping, response framing — all run as the service's own identity.
5. For each access-requiring action, install the captured token on the current OS thread (KACS_IOC_IMPERSONATE on the stored fd), do the single action, call kacs_revert() immediately. Keep the impersonation window as tight as possible.
6. Close the captured fd at end of request.

A server that handles concurrent connections per thread runs whichever flow it uses in each thread, in parallel. The impersonation state is strictly per-thread; nothing shared.

Common mistakes #

A few patterns that bite first-time service authors:

• Forgetting to revert. A thread that finishes a request without calling kacs_revert continues to impersonate the previous client. The next request handled on that thread uses the wrong identity. Make kacs_revert part of your between-requests cleanup, unconditionally.
• Reverting too early. A thread that reverts before all of the work is done — perhaps because an inner function is doing cleanup that runs as the service identity — will fail access checks on the parts that needed to remain impersonated. Keep the impersonation scope wide enough to cover the whole user-facing operation.
• Holding a peer token fd across exec. Token fds are file descriptors and survive exec by default (unless O_CLOEXEC was set). But the impersonation state of the thread does not survive exec — it is reverted automatically. If your service execs another binary, the new binary starts with no impersonation, even if the old code was impersonating.
• Assuming the level you asked for is the level you got. The two-gate model can silently downgrade. Code that branches on level should query, not assume.

Where to go next #

For what the impersonated identity is checked against once the server starts acting as the client, read Security descriptors.

To drive impersonation from a shell — impersonate a peer, revert, inspect the effective token — read The token command.

A security descriptor (often just SD) is the policy attached to every protected object in Peios. Every file, every registry key, every IPC socket, every running process, every token — all of them carry an SD that defines the security policy for that one object. Where the token is the "who" of an access decision, the SD is the "what to check against".

A security descriptor has four components, each with its own role, its own evaluation rules, and its own pitfalls. This topic covers each in turn.

The four components #

Every SD has exactly four parts:

A given SD can have all four components or some subset. An SD without a DACL is not the same as an SD with an empty DACL — see DACL evaluation for the rule. An SD without an owner is malformed; the access check rejects it.

What an SD does not contain #

Worth knowing what is not in an SD, because these things are often mistakenly attributed to it:

• The object's content or data. SDs say nothing about what the object is, only about who can use it.
• The object's type. Whether you are dealing with a file, a registry key, or a process is the object manager's concern. The SD is the same shape regardless; only the access rights it grants are object-type-specific (because the GenericMapping for each type is different).
• The token of the principal who is trying to access the object. That comes from the caller, not the SD. An SD is policy; tokens are subjects; the access check matches them up.
• Anything about the parent object. Inheritance is computed at creation time — a child object's SD is its own complete value, not a delegation to the parent. See Inheritance for the eager-evaluation model.

These boundaries matter because the SD's job is small and well-defined. Everything else about an object lives somewhere else: the data is in the data path, the type is in the object manager, the access decision is in the access check.

Where SDs live #

Different object types store SDs in different places, but the format and meaning are the same.

The binary format — the self-relative layout — is uniform. An SD that was written for a file can be read by a tool that uses the same parser as for a registry key. This consistency is what lets system tools work generically across object types.

Note one important rule: reading or writing the SD xattr directly is denied unconditionally. Even with CAP_DAC_OVERRIDE. All SD access must go through the appropriate KACS API (kacs_get_sd, kacs_set_sd, or the equivalent registry-side APIs). The xattr exists so the SD travels with the file across normal filesystem operations (copy, backup, restore by tools that understand xattrs), but the security boundary is the API, not the xattr layer.

The cost-of-modification asymmetry #

A useful intuition: modifying different parts of an SD requires different rights.

This asymmetry is deliberate. The DACL is what users control to manage their own data. Ownership is a stronger lever — taking ownership is a deliberate administrative act. The SACL is a system-level concern, gated by a privilege held by administrators and audit systems.

How an SD gets created #

There are three ways an object ends up with its SD:

1. Inherited from a parent. The most common path: when a child object is created, its SD is computed by combining the parent's inheritable ACEs with the creating principal's defaults. The result is stored on the child as a complete SD. The parent is not consulted again at access-check time. See Inheritance.
2. Explicitly supplied at creation. The creator passes an SD as a parameter (to kacs_open with a create disposition, to a registry key create, etc.). This SD is taken as-is, subject to the rules about what fields the creator may set (the creator must be entitled to name the owner, for instance).
3. Synthesised by the kernel. For objects whose storage layer cannot hold an explicit SD (an abstract socket bound by a process that did not provide one, a file on a mount with synthesize_ephemeral policy and no parent inheritance), the kernel constructs a default SD from the creating principal's token (default_dacl, owner_sid_index, primary_group_index). The synthesis path is per-object-type but the result is a normal SD.

Once an SD is in place, it is the authoritative policy for the object. Modifying it after creation is a separate operation governed by kacs_set_sd and its access requirements.

The SD as an evaluation target #

When the access check runs on an SD, it is not reading every field. The pipeline does specific things with specific parts of the SD in a specific order. The full algorithm lives in Access decisions; a brief sketch for orientation:

1. The owner field is consulted to determine implicit rights (and whether they have been suppressed by OWNER RIGHTS).
2. The SACL is scanned for mandatory integrity labels and PIP trust labels — these gate the access independently of the DACL.
3. The DACL is walked, ACE by ACE, in order, applying first-writer-wins.
4. The SACL is scanned again for audit and alarm ACEs that should fire as a result of the access attempt.

Each step has its own page in this topic. The point of mentioning the order here is so that as you read the deeper pages you can see where each component is consulted.

Where to start #

If you want the structural details — what an ACL looks like, what each ACE type means, what bits the access mask uses — read ACLs, ACEs, and access masks.

If you want to understand how a DACL actually decides "allowed" or "denied" — first-writer-wins, ACE ordering, the canonical order, MAXIMUM_ALLOWED — read DACL evaluation.

If you want to know how owner implicit rights work and why OWNER RIGHTS can suppress them, read Ownership and implicit rights.

If you want the inheritance model — how a child's SD is computed from its parent and creator, and why parent changes don't propagate to existing children — read Inheritance.

If you want conditional ACEs — the ABAC-style mechanism where access depends on token claims and resource attributes — read Conditional ACEs.

If you want the SACL specifically — audit, alarm, integrity labels, central access policy references, PIP trust labels — read The SACL.

To read and change a descriptor from a shell — owner, DACL, SACL, label, inheritance — read The sd command.

A DACL and a SACL are both Access Control Lists — sequences of Access Control Entries in a defined order. The two lists have different jobs (the DACL decides access; the SACL records system-level policy and audit), but they share a structure. This page covers that structure, plus the catalog of ACE types and the layout of the 32-bit access mask that almost every ACE carries.

ACL structure #

An ACL is, conceptually, an ordered array of ACEs. The binary form is a short header — a revision byte, the total AclSize, and the AceCount — followed by the ACEs back-to-back; the byte-level layout is owned by the Security descriptors wire format.

The maximum ACL size is 64 KB — the AclSize field is a 16-bit value. An ACL is self-delimiting: a parser walks exactly AceCount ACEs starting after the header and stops when it has consumed AclSize bytes.

The two ACL revisions differ only in what ACE types they are allowed to contain. 0x02 is the basic revision; 0x04 additionally allows object ACEs (the type with property GUIDs) and callback ACEs (the type with conditional expressions). Parsers should accept whichever revision they see; writers should emit the minimum revision necessary for the ACEs they are including.

ACE structure #

Every ACE has a 4-byte header — a one-byte AceType, a one-byte AceFlags, and a two-byte AceSize (always a multiple of 4) — followed by a type-specific body. The body's shape depends on the type. The most common shapes:

• Single-SID body — Mask (4 bytes) | SID (variable). Used by basic allow/deny/audit/alarm ACEs and by the integrity/scoped-policy/trust-label SACL types.
• Object ACE body — Mask (4) | Flags (4) | optional ObjectType GUID (16) | optional InheritedObjectType GUID (16) | SID (variable). The flags field controls whether each GUID is present.
• Callback (conditional) body — same as the corresponding non-callback type, plus a trailing ApplicationData block holding the conditional expression bytecode. See Conditional ACEs.

The detailed byte-level layouts live in the Wire formats reference. For this page, what matters is that every ACE is self-describing — the parser reads the header, dispatches by type, and consumes exactly AceSize bytes.

The ACE type catalog #

There are twenty-one ACE types, split into three families: access-control, audit/alarm, and system-policy. Most SDs you will look at use only a small subset of these — typically ACCESS_ALLOWED, ACCESS_DENIED, SYSTEM_AUDIT, and SYSTEM_MANDATORY_LABEL. The numeric type values are catalogued in ACE types and flags; the tables here describe what each type is for.

Access-control ACE family #

These ACEs participate in the DACL walk.

The most common ACEs you will write are ACCESS_ALLOWED and ACCESS_DENIED — plain "this principal gets these rights" or "this principal does not get these rights". The object variants matter when you are protecting directory-style objects with per-property permissions. The callback variants are how conditional expressions show up in ACEs.

Audit and alarm ACE family #

These ACEs sit in the SACL and decide when access produces an audit event.

The distinction between AUDIT and ALARM is important: AUDIT fires at the moment of handle creation (one event per access attempt), ALARM configures a per-operation mask on the open handle that fires on every subsequent operation. See The SACL and Auditing for the full story.

System-policy ACE family #

These ACEs sit in the SACL and carry policy other than audit.

These four are how the SACL extends the access decision beyond what the DACL alone can express. Each has its own evaluation rules (covered in the relevant topics — MIC under Access decisions, resource attributes under Resource attributes, CAAP under Central access policies, PIP under Process integrity protection).

ACE flags #

The AceFlags field is a bitmask. Most flags control inheritance — whether and how an ACE on a parent object propagates to children. Two flags control audit firing on SYSTEM_AUDIT and SYSTEM_ALARM ACEs. (Bit values: ACE types and flags.)

The inheritance flags compose in non-obvious ways. Combinations you will see often:

The full inheritance machinery is on Inheritance.

The access mask #

Every ACE that participates in the DACL walk, and every audit/alarm ACE, carries a 32-bit access mask. The mask uses four regions, partitioned by bit position.

The numeric values for every right live in Access mask bits; the mask's byte layout is in the SD wire format. A few things worth noting about the layout:

• The same bit means different things on different object types. Bit 0 is FILE_READ_DATA on a file but KEY_QUERY_VALUE on a registry key. The object-specific portion of the mask is reusable across types because the object manager knows what kind of object it is.
• Standard rights are uniform. DELETE always means delete the object; READ_CONTROL always means read the SD; WRITE_DAC always means modify the DACL; WRITE_OWNER always means change the owner. These bits work identically regardless of object type.
• Generic rights are abstract. GENERIC_READ does not name a specific right. It is a placeholder that gets mapped to a concrete combination of object-specific and standard rights at the moment of evaluation, using the object type's GenericMapping table.

Generic mapping #

When an access check sees a generic right in either an ACE mask or a requested mask, it consults the object type's GenericMapping table to substitute concrete rights. The mapping is per-type:

The full GenericMapping tables live in the Constants and catalogs reference. The key idea for now is: generic rights let an ACE author say "give the read permission for this thing" without knowing exactly which bits "read" means for this object type. The access check fills in the concrete bits at evaluation time.

This is also why an ACE that grants GENERIC_READ to a principal will produce different concrete grants depending on which object the ACE is on. The bit pattern in the ACE is the same; the meaning depends on where it lives.

MAXIMUM_ALLOWED is a request, not a right #

MAXIMUM_ALLOWED (bit 25) is special. It is not a right an ACE can grant — it is a marker the caller sets in a desired-access mask when asking "what is the maximum access I could be granted right now?". The access check sees the flag, evaluates the DACL fully, and returns every right the caller could be granted.

MAXIMUM_ALLOWED must not appear in an ACE. It is meaningless there.

Sizes and limits #

The size limits (maximum SD size, maximum ACL size, and the rest) are catalogued in Other constants. A practical SD on a typical object is far below all of them — a few hundred bytes at most. The limits exist for the pathological cases.

Where to go next #

For how the ACEs in a DACL actually decide "allowed" or "denied" — first-writer-wins, ordering, the null/empty distinction — read DACL evaluation.

For the full numeric catalog of ACE types, flags, and access-mask bits, see ACE types and flags.

To read and edit ACLs from a shell, read The sd command.

When the access check walks a DACL, it is answering one question, bit by bit: for each right the caller asked for, does this DACL grant or deny it? The mechanism is first-writer-wins — each bit is decided by the first ACE that mentions it, and once decided, no later ACE can override the decision. The walk is in the order ACEs appear in the DACL.

That rule is short. The consequences are not. The order of ACEs in a DACL is semantically load-bearing. A canonical order exists precisely so the rule produces the result you would expect. This page covers the walk, the canonical order, the special cases for null and empty DACLs, and what MAXIMUM_ALLOWED does to the algorithm.

The walk #

The access check starts with two state variables: decided (bits whose grant/deny status is now fixed) and granted (bits that have been granted). Both start empty. It walks the DACL from first ACE to last. For each ACE: skip if the ACE does not match the caller (wrong SID, INHERIT_ONLY_ACE set, conditional expression evaluates UNKNOWN-or-FALSE for allow / FALSE for deny). For an ACCESS_DENIED ACE that matches: any of its mask bits that are not yet in decided are added to decided and not added to granted (they are denied). For an ACCESS_ALLOWED ACE that matches: any of its mask bits that are not yet in decided are added to both decided and granted. After the walk, the access check has its answer: the bits in granted are the rights this DACL would give.

That paragraph is the whole algorithm for an ordinary DACL. Everything else on this page is either a special case (null/empty DACL, MAXIMUM_ALLOWED) or a rule about how to arrange ACEs so the walk produces the right answer.

First-writer-wins, illustrated #

Suppose a DACL contains:

1. ACCESS_ALLOWED Alice FILE_READ_DATA | FILE_WRITE_DATA
2. ACCESS_DENIED Alice FILE_WRITE_DATA

Alice asks for FILE_READ_DATA | FILE_WRITE_DATA. The walk:

• ACE 1 matches Alice. FILE_READ_DATA and FILE_WRITE_DATA are not yet decided. Both are added to decided and to granted.
• ACE 2 matches Alice. FILE_WRITE_DATA is already decided. The ACE has no effect.

Result: Alice gets both rights. The deny in ACE 2 came too late.

Now suppose the DACL is in the other order:

1. ACCESS_DENIED Alice FILE_WRITE_DATA
2. ACCESS_ALLOWED Alice FILE_READ_DATA | FILE_WRITE_DATA

The walk:

• ACE 1 matches Alice. FILE_WRITE_DATA is not yet decided. It is added to decided but not to granted (denied).
• ACE 2 matches Alice. FILE_READ_DATA is not yet decided — it is added to both. FILE_WRITE_DATA is already decided. The ACE only takes effect on FILE_READ_DATA.

Result: Alice gets FILE_READ_DATA only. The deny in ACE 1 prevented the allow in ACE 2 from granting write.

The two DACLs contain exactly the same ACEs but produce different results. That is what is meant by "order matters".

The canonical ACE order #

Because ordering is load-bearing, Peios defines a canonical order that produces the result a reasonable reader would expect: explicit denies override explicit allows, and explicit ACEs override inherited ACEs.

A DACL written in this order has the following properties:

• An explicit deny always overrides any allow (explicit or inherited) for the bits it covers.
• An explicit allow overrides any inherited rule.
• Inherited denies override inherited allows.

Tools that compose DACLs — a properties dialog, a system utility — are expected to maintain canonical order. The access check itself does not require it; the walk is the same regardless. But a DACL whose ACEs are out of canonical order produces results that may surprise the author. "I added a deny ACE and it had no effect" is almost always a canonical-order problem: the deny was placed after an allow that already decided the bits.

The four classes are distinguished by ACE type plus the INHERITED_ACE flag (0x10). Explicit ACEs have the flag clear; inherited ACEs have it set. The kernel sets the flag automatically when an ACE is created by inheritance.

NULL DACL vs empty DACL #

The two states look identical to a casual reader but mean opposite things.

The empty-DACL case is what you get when you explicitly remove every ACE from a DACL but keep the DACL itself. The intent is "no one has any rights to this object", and the access check honours it.

Tools that print or parse SDs must distinguish the two. Saying "the DACL is empty" without distinguishing between absent-DACL and zero-ACE-DACL is a recipe for misreading an object's policy.

ACE flags that affect the walk #

A few flags change whether or how an ACE participates:

The one to remember is INHERIT_ONLY_ACE. An ACE with that flag set is for inheritance purposes only and does not control access to the object it is on. This is sometimes the source of a confusing "but my ACE is right there in the DACL" — yes, it is, but it is inherit-only, so the walk skips it.

MAXIMUM_ALLOWED: the "what could I get" mode #

Normally the access check stops as soon as every bit in the requested mask is decided. If the caller asked for FILE_READ_DATA | FILE_WRITE_DATA and both bits are decided after three ACEs in a DACL of twenty, the walk stops — there is nothing more to learn.

When the caller sets MAXIMUM_ALLOWED (bit 25) in the requested mask, the access check changes mode. Instead of stopping when the requested bits are decided, it walks the entire DACL and accumulates every bit that any ACE would grant the caller. The returned granted mask is the union of all rights the caller could have gotten.

This is what tools use to display "you have read, write, and delete access to this file" without having to ask for each right separately. It is also what services use when they want to open an object with whatever rights they can get, deferring the actual privilege check to later operations.

Two specific rules about MAXIMUM_ALLOWED:

• The flag itself is stripped from the requested mask before the walk runs. The actual decided/granted arithmetic is done on the real bits.
• The granted mask is returned through the same channel as a normal access check; the caller learns what they got back.

MAXIMUM_ALLOWED does not affect first-writer-wins. A deny ACE that decides a bit still decides it. The full-walk mode just means the walk does not exit early.

What the DACL walk does not decide #

A handful of access decisions happen outside the DACL walk:

• Owner implicit rights are granted before the walk starts, based on the SD's owner field. Covered in Ownership and implicit rights.
• Privilege-granted rights (SeBackup, SeRestore, SeSecurity, SeTakeOwnership, SeRelabel) are decided before or after the walk, depending on the privilege. The DACL has no say.
• MIC (mandatory integrity) and PIP (process integrity protection) checks happen before the DACL walk for non-dominant callers, and can pre-decide write or other bits as denied.
• Restricted token and confinement intersections happen after the DACL walk and can narrow the result.
• CAAP (central access policies) evaluate alongside the DACL and can further restrict.
• SACL audit happens after the access decision, based on whatever the DACL walk + the other layers produced.

In other words, the DACL walk is one layer in a longer pipeline. It is the layer most people mean when they talk about "permissions", but it is not the whole story. The full pipeline lives in Access decisions.

Practical tips #

A handful of patterns that come up repeatedly:

• When a deny ACE seems to have no effect, check whether it appears after an allow ACE that already decided the bit. The fix is to move it earlier (or move the allow later) — i.e. canonicalise.
• When an inherited ACE seems to override an explicit one, check canonical order. Inherited ACEs should sit after explicit ones; if you find an inherited deny ahead of an explicit allow, the DACL is out of order.
• When testing access, query the full SD and walk it manually if the answer is surprising. Almost every "why doesn't this work" reduces to either a misordered DACL, a misplaced INHERIT_ONLY_ACE, or a missing flag.
• When writing a DACL programmatically, build it in canonical order from the start. Adding ACEs at the end and "sorting later" is fragile.

Where to go next #

For the implicit rights the owner gets before the walk starts — and how to suppress them — read Ownership and implicit rights.

For the full pipeline the walk sits inside — MIC, PIP, privileges, narrowing layers — read Access decisions.

To test what a DACL would grant from a shell, read The sd command.

Every security descriptor names an owner, a SID associated with the object's access policy. An owner normally receives READ_CONTROL to read the descriptor and WRITE_DAC to change its DACL. Ownership does not automatically grant access to file contents, and it is not a guarantee against locking yourself out.

Before relying on ownership to repair access, inspect the DACL for OWNER RIGHTS ACEs and check the other access layers. For a shell workflow, use Managing file security; this page explains when ownership helps and when it does not.

The implicit rights #

At the start of the normal DACL walk, an owner can receive READ_CONTROL and WRITE_DAC. Those bits are marked granted and decided, so a later DACL ACE cannot reverse them. The grant is limited to valid rights that an earlier policy stage has not already decided; a mandatory denial is not overridden by ownership.

The descriptor specification determines ownership by equality with the caller's user SID or token group SIDs. This ownership relation is distinct from the SE_GROUP_OWNER requirement for assigning a group as a new owner. Allow and deny ACE matching also has its own enabled/deny-only group rules.

The implicit grant covers only descriptor reading and DACL editing. It does not include FILE_READ_DATA, FILE_WRITE_DATA, WRITE_OWNER or ACCESS_SYSTEM_SECURITY. In particular, being the owner does not confer SACL access or permission to transfer ownership.

An owner may be able to repair a DACL that excludes them from data access, but only if WRITE_DAC remains available. The Kernel TRM documents two important limits:

• A qualifying OWNER RIGHTS ACE suppresses the implicit grant.
• The grant cannot override rights already decided by mandatory policy. Confinement also performs its secondary walk without an owner-implicit bypass.

OWNER RIGHTS: suppressing the implicit grant #

S-1-3-4, OWNER RIGHTS, lets a policy control the owner's rights through ordinary DACL rules rather than an automatic grant. This can be useful when a service that owns a file should not also be free to rewrite its access policy.

Suppression happens if the DACL contains a non-inherit-only access-control ACE targeting S-1-3-4. The pre-scan tests the ACE's presence, not whether its condition evaluates true. Even a conditional OWNER RIGHTS ACE whose condition later fails suppresses implicit READ_CONTROL | WRITE_DAC.

The owner then receives whatever access the full DACL walk and remaining policy allow, including matching user, group and OWNER RIGHTS ACEs. It is not limited to the OWNER RIGHTS ACE alone. An OWNER RIGHTS allow ACE granting only read-data therefore removes the implicit WRITE_DAC, but another applicable ACE could still grant WRITE_DAC.

OWNER RIGHTS ACEs obey the same first-writer-wins order and allow/deny matching rules as other access-control ACEs. An inherit-only OWNER RIGHTS ACE does not suppress implicit rights on the object it is attached to.

Changing ownership #

Changing an owner requires WRITE_OWNER (standard-right bit 19, 0x00080000) on the object. The DACL can grant it, or an applicable privilege can contribute it through the access-check pipeline. Passing that gate and being allowed to name the new owner are separate requirements.

Without SeRestorePrivilege, the new owner must be either:

• The caller's own user SID, or
• A group SID on the caller's token carrying SE_GROUP_OWNER.

SeTakeOwnershipPrivilege does not relax this new-owner restriction. With SeRestorePrivilege, the SID constraint is bypassed and any well-formed SID can be assigned; the operation still needs the applicable set-security access path and checks. The kernel validates the change before applying it.

For example, the documented shell form for making the current caller the owner of one file is:

sd owner ./report.txt @self

Use it only when that is the intended ownership policy and the required authority is established. It leaves the DACL in place and does not itself restore file-data or DACL-edit access. Inspect and verify as described in Managing file security.

SeTakeOwnership and recovery limits #

The kernel access-check contract lets SeTakeOwnershipPrivilege supply WRITE_OWNER after the DACL walk when the DACL did not grant it and mandatory policy did not block it. This is a DACL override for one right, not an unconditional grant of access to the object.

It does not bypass:

• The new-owner SID rule. Use of an arbitrary SID instead requires SeRestorePrivilege.
• MIC or PIP restrictions. A caller that does not dominate the object's required integrity or trust does not gain an override merely by holding take-ownership.
• Other narrowing layers, including confinement.
• OWNER RIGHTS suppression after the owner changes. The unchanged DACL can still withhold WRITE_DAC.

SeRestorePrivilege is also not a generic promise that an arbitrary file handle can repair a descriptor. The set-security contract distinguishes live checks through a path or O_PATH handle from cached rights on an ordinary fd. Verify the supported repair mechanism rather than improvising one from privilege names.

The primary group #

The SD's primary group field is a relic. It exists because the SD format reserves a slot for it and because some legacy code paths consult it, but in Peios its role is almost entirely passive.

The one place the primary group matters is inheritance. When the kernel synthesises a new child SD and an inheritable ACE names CREATOR_GROUP (the well-known SID S-1-3-1), the substitution uses the new child's primary group SID. The primary group is set to the creator's token's primary group at the time of creation.

After inheritance has run, the primary group on the child SD is just a stored value. The access check does not consult it. ACEs do not match it. It exists so the CREATOR_GROUP substitution has a target.

You will rarely need to think about the primary group. The few times it matters are:

• Programs that read SDs and expect to display the primary group alongside the owner.
• Legacy POSIX-style applications that map the primary group to a Linux GID for compatibility purposes.
• Inheritable ACEs that use CREATOR_GROUP to grant access to "the group of whoever created this".

Most of the time, the primary group is set to whatever the creating token had and is then ignored.

Recovery patterns #

If no authorized repair route is established, stop and resolve that with the system's policy administrator or documented recovery process. Do not try broad grants, label lowering or raw xattr writes as a substitute for diagnosis.

Where to go next #

• Managing file security — inspect, choose a bounded change and verify it.
• The sd command — exact shell syntax.
• Inheritance — creator placeholders and child descriptors.
• Privileges — how privilege-held rights differ from ownership.

When a new object is created under a parent — a file in a directory, a registry key under another key — the new object gets its own security descriptor. The kernel computes that SD at creation time by combining inheritable ACEs from the parent's SD with whatever the creator supplied or defaulted. The result is stored on the child as a complete, self-contained SD. From that point on, the access check on the child consults only the child's own SD; the parent is not walked.

This is the eager evaluation model. It has one large consequence: modifying a parent's inheritable ACEs does not propagate to existing children. The children's SDs were computed when they were created and are now their own. Whatever changes you make to the parent affect only objects created after the change. Children that already exist keep the SDs they had.

This page covers the inheritance algorithm — what counts as inheritable, how the merge works, the special placeholders (CREATOR_OWNER, CREATOR_GROUP), and the SE_DACL_PROTECTED and SE_SACL_PROTECTED flags that opt an object out of inheritance entirely.

Eager vs lazy #

Two models are possible:

• Lazy inheritance: a child has no inherited ACEs of its own; access checks on the child walk the parent SD too. Changes to the parent propagate immediately.
• Eager inheritance: a child's SD is fully computed at creation; access checks consult only the child. Changes to the parent affect future children only.

Peios uses eager inheritance, like the access-control model it grew out of. The advantages: access checks are local (you only need one SD's worth of data), no walking up directory trees during evaluation, no concurrency issues with "the parent moved between my permission check and the operation". The disadvantage: when you change a parent's permissions, you need a separate sweep to propagate the change to existing children — a tool's job, not the kernel's.

In practice, eager inheritance means: when an administrator changes a directory's DACL and wants the change to apply to existing files, they need a propagation tool. The kernel does not do this automatically and provides no syscall for "re-inherit all children". A propagation tool walks the tree and rewrites child SDs explicitly.

The inheritance flags #

Four ACE flags control how an ACE propagates to children. They are the same four mentioned on the ACLs and ACEs page:

Common combinations:

The INHERIT_ONLY_ACE (IO) flag is what lets you say "this rule is for children, not for the parent itself". An IO ACE is invisible to the access check on its own object; the DACL walk skips it. But it is copied to children at creation time.

The merge algorithm #

When a new child is created, the kernel needs to produce the child's SD from three inputs:

1. The parent's SD. Inheritable ACEs from here will be copied (with adjustments) into the child.
2. The creator's SD, if one was supplied as a parameter to the create call. This contains explicit ACEs the creator wants on the new object.
3. The creator's token. Provides defaults (owner, primary group, default DACL) when the creator did not supply specific values.

The merge proceeds as follows:

1. Compute the child's owner. If the creator supplied an owner in the explicit SD, use it (subject to the same-self-or-owner-group rule from Ownership). Otherwise, use the creator's token's default owner.
2. Compute the child's primary group. Same rule: explicit SD if present, otherwise the creator's token's default primary group.
3. Compute the child's DACL. If the creator supplied a DACL, start with its explicit ACEs and append the inheritable ACEs from the parent's DACL — only those whose flags say they should propagate to this kind of child (container or non-container). If the creator supplied no DACL, the child's DACL is the inherited ACEs alone. Only when the parent yields no inheritable ACE at all is the creator's token consulted: the child then gets the token's default_dacl, and if the token has none, a null DACL. The default DACL is a fallback, never a base that inherited ACEs are added to.
4. Compute the child's SACL. Same algorithm as the DACL, applied to SACL ACEs.

Each inherited ACE goes through a small transformation as it is copied:

• The INHERITED_ACE flag (0x10) is set in the copy. This marks it as having come from inheritance, not from explicit assignment.
• If NO_PROPAGATE_INHERIT_ACE was set, the OI, CI and NP flags are cleared in the copy.
• If the ACE's SID is CREATOR_OWNER (S-1-3-0), the SID is substituted with the new child's owner SID.
• If the ACE's SID is CREATOR_GROUP (S-1-3-1), the SID is substituted with the new child's primary group SID.

The CREATOR substitution is the mechanism that makes inheritable ACEs portable. A directory's DACL containing CI | OI ACCESS_ALLOWED CREATOR_OWNER GENERIC_ALL means "every file or subdirectory created under here grants full access to whoever owns it". The owner of each child is different; the substitution at creation time fills in the right SID for each one.

Creator SIDs and generic rights can produce two ACEs #

Substitution alone would answer the question for one object and destroy the rule that asked it. A subdirectory would come away holding a concrete SID — its own creator's — with that access over everything beneath it, permanently, and nothing further down would ever resolve against its own creator again.

When a container inherits an ACE that names a creator SID or carries generic rights, and the ACE both applies to the child and propagates further, it receives both halves:

The second is inherit-only, so it grants nothing on the directory itself; it exists to be inherited again further down, where it resolves against whoever creates the next object.

This also applies to registry keys. A generic-rights ACE with an ordinary SID still needs both copies: its effective rights are mapped now, while its original generic mask is preserved for descendants. An ACE with a concrete SID and concrete rights is inherited as one copy.

An ACE that targets files only (OI without CI) passes through a directory as one unresolved, inherit-only copy. Adding NP prevents that copy from reaching files below the directory, so the directory inherits no such ACE.

A non-container receives the resolved ACE alone. A file has no children for the rule to reach, so the copy carries no inheritance flags either.

NO_PROPAGATE_INHERIT_ACE ends the rule as it ends any other: with OI, CI and NP cleared there is nothing to carry, and only the substituted ACE is written.

Sources of an inherited SD, ranked #

Which source wins for each component of the child SD, in order:

Whenever the parent has inheritable ACEs, they are appended to an explicit DACL or SACL rather than replacing it, so a creator who supplies an explicit DACL gets that DACL plus the inheritable ACEs from the parent. They cannot exclude the parent's ACEs except by setting the protected flag (see below).

The token's default_dacl is a fallback, not a base. It is consulted only when the creator supplied no DACL and inheritance produced nothing, which depends on the filesystem and its explicit subtree policies. The cases that reach it are objects with no parent to inherit from, such as an abstract socket, and children of a container whose descriptor was deliberately written without inheritable ACEs.

Protected ACLs #

There is an opt-out: the SE_DACL_PROTECTED and SE_SACL_PROTECTED flags in the SD's control field.

When a creator sets these flags on the explicit SD they pass to the create call, the resulting child's DACL/SACL is purely what the creator wrote. The parent might have a hundred inheritable ACEs; none of them appear on the child.

Protected ACLs are used when an object should be administered without reference to its container. A service that creates files whose access should be controlled only by the service, not by whoever happens to own the directory it lives in, sets SE_DACL_PROTECTED on each file's explicit SD at creation.

The flags can also be set after creation, via a subsequent kacs_set_sd. Doing so does not retroactively remove previously inherited ACEs — they were copied at creation time and are now the child's own — but it does protect against future re-inheritance if a propagation tool sweeps the tree.

A protected DACL is how a subtree gets its own policy #

The Peios filesystem is a worked example, and a useful one because it is small enough to hold in your head.

dev.peios.fsbase declares protected inheritance scopes for the intended public software trees: /usr, and /lcl/bin, /lcl/sbin, /lcl/libexec, /lcl/lib, /lcl/include, /lcl/share, /lcl/etc and /lcl/conf. SYSTEM and Administrators have full control; Everyone inherits read/execute. Thus newly installed software stays readable to ordinary principals, including on a live image whose lower filesystem synthesises non-inheritable descriptors. This is not a public inheritance policy for all of /var.

A protected parent does not retroactively protect an existing child. Runtime credential writers must establish protection before writing; a later rename or a Unix mode such as 0600 does not replace the Peios security descriptor.

Auto-inherit flags #

Two more SD control flags work alongside the protected flags:

The corresponding SACL pair (SE_SACL_AUTO_INHERIT_REQ, SE_SACL_AUTO_INHERITED) works the same way.

These flags exist so tools can distinguish "this child wants automated propagation" from "this child has its own bespoke DACL the user wrote by hand". A propagation tool sweeping a tree typically updates only children with the auto-inherit flags set, leaving hand-crafted DACLs untouched.

What inheritance does not do #

A handful of things often attributed to inheritance but not done by it:

• Inheritance does not happen at access-check time. Once a child has its SD, the parent is not consulted on access decisions. Inheritance is purely a creation-time activity.
• Inheritance does not retroactively update children. A change to a parent's inheritable ACEs is invisible to children created before the change. Propagation requires an explicit sweep.
• Inheritance does not chain across moves. Moving a file from directory A to directory B does not re-run inheritance against B. The file's SD remains whatever it was. (Copying is a different operation; it creates a new object, which does go through inheritance.)
• Inheritance does not preserve ACE order. Inheritable ACEs from the parent are appended to the explicit ACEs from the creator. If you want canonical order, the creator needs to either start from the parent's order and intersperse, or run a canonicalisation pass afterwards.

Inheritance and creator-supplied SDs #

A subtle interaction worth knowing: when a creator passes an explicit SD to the create call, the explicit ACEs go before the inherited ones. This means the creator's ACEs sit higher in the DACL than the parent's, and first-writer-wins favours them.

If the parent says "deny X" and the creator says "allow X", the creator's allow wins because it sits first. If the canonical order says the parent's inherited deny should win (because explicit ACEs from the creator should not override the parent's policy), the creator needs to either not supply a competing ACE or arrange the explicit SD to use the protected-ACL flag.

This is one of the reasons creators usually pass no explicit DACL (relying on the default-DACL + parent-inheritance merge) rather than constructing a custom SD. The latter is correct in cases where the creator knows exactly what the child's policy should be; the former is correct in cases where the creator just wants the natural policy of its location.

Where to go next #

For ACEs whose effect is gated by an expression rather than fixed at write time, read Conditional ACEs.

To sweep a tree and propagate inheritable ACEs from a shell, read The sd command.

Private state and data defaults #

The base filesystem gives /var/state, /var/cache, /var/log, /var/crash, /data and /srv protected, inheritable SYSTEM/Administrators full access. Everyone may traverse each container to an explicitly shared child, but may not list it, create entries, or inherit public access into new contents. The reduced initramfs skeleton carries the same policies for its /var branches.

A package or administrator must establish an explicit child scope before a service writes there: grant the service's own SID and any intended readers. Changing a directory descriptor does not recursively rewrite existing children. Public software under /usr and the designated /lcl branches remains readable; /var/tmp keeps its separate creator-private temporary-file policy. The secrets scope stays SYSTEM-only, excluding Administrators unless explicitly granted.

SYSTEM remains trusted across private scopes. A service-specific grant isolates a lower-privilege service from unrelated stores; it does not contain another process that retains SYSTEM identity or equivalent machine-wide privileges.

The credential store under /var/state/lpsd grants the distinct lpsd service account and SYSTEM; it continues to exclude Administrators and other services.

A conditional ACE is an ACE whose effect depends on a boolean expression. Where an ordinary allow ACE says "grant these rights to this principal", a conditional allow ACE says "grant these rights to this principal if this expression is true". The expression can reference attributes of the calling token (the user's department, the device's compliance state), attributes of the object (its classification, its sensitivity), and runtime context supplied by the caller.

Conditional ACEs are how Peios expresses attribute-based access control — ABAC — as opposed to identity-based access control where every rule names a specific principal or group. The conditional model is strictly an extension: every conditional ACE is also keyed to a SID, so it composes naturally with the rest of the DACL. The expression is an extra gate on top.

This page covers the model, the expression language at a conceptual level, and the three-valued logic that makes the model fail safely when an expression cannot be evaluated.

The model #

A conditional ACE is one of the callback ACE types from ACLs and ACEs:

The body of a callback ACE is the body of the corresponding non-callback ACE — Mask, optional GUIDs, SID — plus a trailing ApplicationData block holding the conditional expression in a binary bytecode format. The bytecode begins with the four-byte magic 0x61 0x72 0x74 0x78 (the ASCII string artx); a callback ACE whose ApplicationData does not start with that magic is treated as having an UNKNOWN expression and falls into the UNKNOWN-handling rules below.

During the DACL walk, the access check evaluates the expression at the moment the ACE is examined. The result is TRUE, FALSE, or UNKNOWN. What happens next depends on the ACE type and the result:

The asymmetry between allows and denies is deliberate. An UNKNOWN result on an allow is skipped (the allow does not get to grant access on incomplete information). The same UNKNOWN on a deny does apply (the deny errs on the side of denying). And UNKNOWN on audit fires the event (the audit errs on the side of recording).

The principle is that UNKNOWN never accidentally grants. It can only fail safely closed, or fail safely open for auditing.

The four attribute namespaces #

Conditional expressions reference attributes through four namespaces, each backed by a different source:

So an expression like @User.Department == "Engineering" refers to a claim on the caller's token. @Resource.Classification == "Public" refers to an attribute on the object being accessed. @Local.Time > 9 refers to context the calling code passed in. The four namespaces let an ACE reference the caller, the object, and the runtime situation in one expression.

Two of the namespaces are token-side (caller properties), one is object-side (resource properties), and one is per-call context. They cover the three "where can an attribute come from?" possibilities cleanly.

User and device claims are covered on Claims on a token. Resource attributes are covered on Resource attributes. Local claims are passed by the caller; the API surface lives in the Kernel ABI reference.

The expression language #

The expression bytecode is postfix (reverse Polish notation), evaluated by a stack machine. Literal tokens push values onto the stack; operator tokens pop operands, do their work, and push a result. The final stack must contain exactly one tri-state value, which is the expression's result.

On the wire an expression is bytecode; the textual form, which sd --if accepts, looks like:

@User.Department == "Engineering"

@User.Department == "Engineering" && @Resource.Classification != "Secret"

Member_of({SID-of-AdminGroup})

@Device.Compliance == "Compliant" && @Local.Time >= 9 && @Local.Time <= 17

Exists(@User.ProjectAccess) && @User.ProjectAccess Any_of {"alpha", "beta"}

The operators fall into four families:

The membership operators reference SID sets — Member_of({S-1-5-21-...}) evaluates TRUE if the caller's token has that SID in its groups. Any_of evaluates TRUE if any value in a multi-valued attribute appears in a literal set. Contains and Exists test for presence rather than equality.

The full operator catalog with bytecode values lives in Wire formats reference.

Value types and comparisons #

Expressions operate on six value types: INT64, UINT64, STRING, SID, BOOLEAN, OCTET. Comparisons follow rules you would expect:

• Numeric comparisons work across INT64 and UINT64 with sign-aware promotion: a negative INT64 is always less than any UINT64.
• String comparisons are case-insensitive by default. A claim or attribute can opt into case sensitivity via the CLAIM_SECURITY_ATTRIBUTE_VALUE_CASE_SENSITIVE flag (see Claims on a token).
• SID comparisons are byte-exact, same as everywhere else.
• Octet comparisons are byte-exact.

Boolean coercion of other types happens when an expression treats a non-boolean as a boolean (rarely, but it can happen): a nonzero integer is TRUE, zero is FALSE, NULL is UNKNOWN, SIDs/octets/composites are UNKNOWN. Compositions of types that do not coerce cleanly produce UNKNOWN.

The "missing attribute" case #

The most common UNKNOWN producer is a reference to an attribute the token or object does not carry. @User.ClearanceLevel on a token that has no ClearanceLevel claim evaluates to UNKNOWN — not to NULL, not to FALSE, not to an empty string. UNKNOWN.

This is why the three-valued logic exists. Schemas evolve; not every user object has every defined attribute; the access check needs to behave well when an attribute is missing. The rule "UNKNOWN skips an allow, applies a deny, fires an audit" means a missing attribute can never accidentally upgrade access — at worst, the gated allow does nothing.

Three-valued logic #

The truth tables for &&, ||, and ! over {TRUE, FALSE, UNKNOWN}:

AND (&&) #

OR (||) #

NOT (!) #

The pattern: a definite value (TRUE or FALSE) combined with UNKNOWN can sometimes determine the result (FALSE && UNKNOWN is FALSE; TRUE || UNKNOWN is TRUE) and sometimes cannot (TRUE && UNKNOWN is UNKNOWN; FALSE || UNKNOWN is UNKNOWN). NOT preserves UNKNOWN.

This means you cannot prove an UNKNOWN attribute is false by negating it. ! Exists(@User.ClearanceLevel) evaluates to UNKNOWN if the attribute is missing, because Exists returns UNKNOWN in that case and the NOT preserves it. The right way to check "the user does not have this attribute" is the Not_Exists operator, which returns TRUE for a missing attribute and FALSE for a present one.

A worked example #

Consider an SD on a sensitive file with this DACL:

1. ACCESS_DENIED_CALLBACK Everyone (when @Resource.Classification == "TopSecret" && Not_Member_of({Cleared-SID})) — deny everyone when the file is TopSecret and they are not in the Cleared group
2. ACCESS_ALLOWED Authenticated_Users GENERIC_READ — allow read to authenticated users
3. ACCESS_ALLOWED Authenticated_Users GENERIC_WRITE — allow write to authenticated users

The resource attribute is set on the file's SACL: Classification = "TopSecret".

User Alice, who is not in the Cleared group, tries to read.

• ACE 1: matches Alice (Everyone matches all tokens). Expression: Classification == "TopSecret" is TRUE (the file's resource attribute matches), Not_Member_of({Cleared-SID}) is TRUE (Alice is not in the group). Both TRUE, so AND is TRUE. The deny applies. FILE_READ_DATA and friends are decided and not granted.
• ACE 2: also matches Alice, but FILE_READ_DATA etc. are already decided. The allow has no effect.
• ACE 3: same.

Alice gets nothing. The conditional deny did its job.

Now user Bob, who is in the Cleared group:

• ACE 1: matches Bob. Expression: Classification == "TopSecret" is TRUE, Not_Member_of({Cleared-SID}) is FALSE. TRUE AND FALSE is FALSE. The deny does not apply.
• ACE 2: matches Bob. FILE_READ_DATA not yet decided. Granted.
• ACE 3: matches Bob. FILE_WRITE_DATA not yet decided. Granted.

Bob gets read and write. The conditional deny knew not to apply to him.

Now suppose the file's classification attribute is missing (administrative mistake):

• ACE 1: expression Classification == "TopSecret" is UNKNOWN (the attribute does not exist). AND of UNKNOWN with anything: depends on the other operand. Even if Not_Member_of is TRUE, UNKNOWN AND TRUE is UNKNOWN. The deny ACE has UNKNOWN, which applies (denies err on the side of denying). FILE_READ_DATA is decided as denied.
• ACE 2, 3: same fate; already decided.

Both Alice and Bob get nothing. The missing attribute caused the deny to fire, not the allow to grant. Fail safe.

When conditional ACEs are the right tool #

Conditional ACEs are the right tool when:

• The set of principals who should have access varies based on attributes that change more often than the SD does. A "members of the Engineering department who joined after 2020" rule is one expression; encoding it as a group membership would require maintaining the group as people join.
• Access depends on something that is not the principal's identity at all — the resource's classification, the time of day, the integrity of the request.
• The same DACL needs to express many cases without duplication. One conditional ACE covers what would otherwise be N parallel ACEs.

They are the wrong tool when:

• The condition reduces to "is this user in this group?". Use a group SID and a plain ACE; it is simpler and faster.
• The condition is a static identity check at a fixed point in time. Use a SID and a plain ACE.
• The expression depends on state that changes faster than you can update the SD. Conditional ACEs evaluate at access-check time using the data on the token and object now; if the relevant data is stale, the result is stale.

Most DACLs in practice use no conditional ACEs at all. They appear in the SDs of objects whose access policy is genuinely attribute-driven — central access policies, data-classification-driven sharing, time-bound access. For everything else, plain ACEs are clearer.

Where to go next #

For the object-side attributes that @Resource.* references resolve against, read Resource attributes.

For the token-side attributes behind @User.* and @Device.*, read Claims on a token.

A resource attribute is a typed key-value attribute attached to an object — much like a claim on a token, but applied to the resource rather than the principal. A file might have Classification = "Internal". A registry key might have Department = "Finance". A process or token might have a Compliance = TRUE attribute. These attributes do not grant or deny access by themselves; they are inputs that conditional ACEs can reference as @Resource.<name>.

Resource attributes are stored in the SACL using the SYSTEM_RESOURCE_ATTRIBUTE_ACE type. They share the binary format used by token claims: same value types, same flags, same case-sensitivity rules. The key difference is location — claims live on a token, resource attributes live on an object's SD.

What a resource attribute looks like #

Each resource attribute carries:

• A name — a string, conventionally Namespace.Attribute (Classification, Department, Project.Code).
• A value — typed. One of INT64, UINT64, STRING, SID, BOOLEAN, OCTET. Single or multi-valued, but homogeneous (no mixed-type arrays).
• A set of flags controlling how the attribute participates in access checks.

The flags are the same set used for claims:

These are the same flags described on Claims on a token, applied here to attributes on the resource side.

Storage in the SACL #

A resource attribute lives in a SYSTEM_RESOURCE_ATTRIBUTE_ACE (type 0x12). The ACE body uses a single-SID layout where the SID is always Everyone (S-1-1-0); the SID slot is structural, not semantic — resource attribute ACEs do not match against tokens like access-control ACEs do. The real payload is in the ApplicationData portion, which carries one claim entry in the same format as a token claim.

A single SACL can hold many resource attribute ACEs — one per attribute. The full ABI layout of the claim entry is in the Wire formats reference.

Two structural notes:

• The first non-inherit-only ACE for each name wins. If two SYSTEM_RESOURCE_ATTRIBUTE_ACE ACEs in the SACL define the same attribute name, only the first one is used. Duplicates after the first are ignored.
• Resource attributes are located by type-scan, not position. Unlike DACL ACEs, the order of resource attribute ACEs within a SACL is not load-bearing beyond the first-wins tiebreak. The access check finds them by scanning for the type, not by walking.

How resource attributes are used #

When the access check evaluates a conditional ACE that references @Resource.<name>, the lookup runs:

1. Scan the object's SACL for a SYSTEM_RESOURCE_ATTRIBUTE_ACE whose attribute name matches <name>.
2. If found, read the value(s) and use them in the expression.
3. If not found, the reference produces UNKNOWN. The expression continues with that value, subject to three-valued logic.

The "not found" case is what makes the design tolerant of schema evolution. A conditional ACE that references @Resource.Classification works whether or not the specific object has a Classification attribute — if it has one, the expression uses it; if not, the expression evaluates UNKNOWN at that subexpression, and the three-valued logic handles the rest.

Resource attributes do not need to be referenced to exist. An object can carry attributes that no current ACE references — perhaps the schema is being prepared for future use, or the attributes are read by separate tooling that scans the SACL directly. The access check ignores resource attribute ACEs that no conditional expression names; they are inert from its perspective.

Setting and modifying resource attributes #

Resource attributes are part of the SACL. Modifying them goes through kacs_set_sd with SACL_SECURITY_INFORMATION in the security-information mask, which requires ACCESS_SYSTEM_SECURITY on the object. In practice this means a caller holding SeSecurityPrivilege — the same privilege that gates other SACL modifications.

One additional rule: a resource attribute marked MANDATORY cannot be removed or modified except by a caller holding SeTcbPrivilege. This is the lever for system-maintained attributes — values the kernel or a TCB component sets that ordinary administrators should not be able to overwrite.

Replacing the SACL with a new one that omits a MANDATORY attribute is also rejected; the kernel checks the diff, not just the new value.

Namespacing #

Resource attribute names are arbitrary strings. By convention, attributes use a namespace prefix:

• Project.Code — the project this resource belongs to.
• Department.Name — the owning department.
• Compliance.Status — a compliance classification.

The convention is just a convention. The access check compares names as strings; Project.Code and ProjectCode are different attributes. Establishing a stable naming scheme is the administrator's job.

In the conditional expression, the reference is @Resource.<name> regardless of whether the name itself contains dots:

• @Resource.Project.Code references an attribute named exactly Project.Code.
• @Resource.Department references an attribute named exactly Department.

The expression parser treats the dot as part of the attribute name, not as a structural separator.

Resource attributes vs claims vs local context #

Resource attributes sit alongside two other attribute sources that conditional expressions can reference. The three together give the conditional model its expressiveness:

The four namespaces let a single conditional expression weave together "who is the caller", "what machine are they on", "what is the object's property", and "what is the runtime context". The most common pattern uses two of them — caller and resource — for classification-based access. The remaining two appear when machine identity matters or when the calling code wants to supply runtime context.

What resource attributes are not #

A few things resource attributes look like at a glance but are not:

• Resource attributes are not part of the data. They are policy metadata, stored in the SACL, separate from the object's content. Reading the object's data does not give you access to the attribute, and vice versa.
• Resource attributes are not ACEs themselves. They live in SYSTEM_RESOURCE_ATTRIBUTE_ACE entries, but the ACE form is structural — the attribute does not grant or deny anything. The access check skips it during the DACL walk and during the SACL audit walk.
• Resource attributes do not propagate via inheritance. They are not inherited from a parent object to a child. A child inherits the parent's inheritable DACL/SACL access-control ACEs; resource attribute ACEs do not have inheritance semantics. If you want the same attribute on every file in a directory, you set it on each one (or use tooling that walks the tree).
• Resource attributes are not searchable through the access check. The access check uses attributes for evaluating expressions, not for filtering objects. There is no "list all objects where @Resource.Classification == 'Public'" API. That would be a job for a separate indexing layer.

Where to go next #

For the SACL these attributes live in — and everything else stored alongside them — read The SACL.

For the principal-side counterpart to resource attributes, read Claims on a token.

The SACL — System Access Control List — is the half of a security descriptor that holds system-level policy. Where the DACL decides "who can do what to this object", the SACL covers everything else the kernel needs to know about the object for security purposes: which access attempts to audit, what integrity level the object has, what PIP trust label it carries, which central access policies apply to it, and what attributes it exposes for conditional evaluation.

The SACL is not part of the access-grant decision in the way the DACL is. Most of its entries do not grant or deny anything; they configure policy that runs alongside or after the DACL walk. The two access-related entries — SYSTEM_AUDIT and SYSTEM_ALARM — fire events but do not gate access.

This page covers each type of SACL entry, how the access check consumes it, and the special status of SACL modification.

What the SACL holds #

A SACL is an ACL — same on-wire structure as a DACL, the same AceCount/AclSize header and the same ACE format. But the ACE types it holds are different. While a DACL is dominated by access-control types (ACCESS_ALLOWED, ACCESS_DENIED, callbacks), a SACL holds the system-policy types:

The numeric type values are in the canonical catalog, ACE types and flags.

A SACL can mix these in any combination. Most SACLs in practice are small — a few audit ACEs, perhaps a mandatory label, sometimes a resource attribute or two. SACLs with every type populated are rare and exist only on the most highly-protected objects.

Audit ACEs: one event per access attempt #

A SYSTEM_AUDIT ACE specifies: when this principal attempts these rights on the object, emit an audit event if the access succeeded (SUCCESSFUL_ACCESS_ACE_FLAG set) or if it failed (FAILED_ACCESS_ACE_FLAG set) or both.

The event fires at the moment the access check completes. One event per matching audit ACE per access attempt. A handle opened with FILE_READ_DATA | FILE_WRITE_DATA against an SD with an audit ACE matching both rights produces one event covering both. A separate handle later, with separate access checks, produces separate events.

Audit ACEs match like other ACEs: the SID in the ACE is compared against the caller's identity. Audit ACE matching uses deny polarity — it considers the broadest identity view, including deny-only groups, so that any identity the caller has that should produce an audit event will produce one even if it would not match an allow ACE.

The callback variants (SYSTEM_AUDIT_CALLBACK, etc.) add a conditional expression. If the expression evaluates TRUE or UNKNOWN, the event fires; if FALSE, it does not. This is why conditional audit fails open — recording something is the safe choice when uncertain.

The full audit model is covered in Auditing.

Alarm ACEs: an event per operation #

SYSTEM_ALARM configures continuous auditing, not one-shot. The ACE's mask is recorded on the open handle as a continuous audit mask. From then on, every operation performed on the handle has its required-access mask compared against the continuous mask; if any bit overlaps, an event fires.

The difference between AUDIT and ALARM is in granularity. AUDIT records "this principal opened this object with these rights". ALARM records "this principal opened this object with these rights, and then performed this specific operation, then this one, then this one". The trade-off is event volume — alarm ACEs on a hot path can produce many events; audit ACEs produce one per handle.

ALARM is the right tool for objects where post-open behaviour is what matters: an audited credential store, a sensitive log file, a security-critical configuration. For most objects, AUDIT is enough.

SYSTEM_MANDATORY_LABEL: the integrity floor #

A SYSTEM_MANDATORY_LABEL ACE sets the object's mandatory integrity level. The ACE has two parts:

• A SID from the S-1-16-* integrity namespace, whose single sub-authority is the numeric level (S-1-16-8192 for Medium, S-1-16-12288 for High, and so on — any single-sub-authority S-1-16 value is a valid level, compared numerically).
• A mask containing the MIC policy bits: SYSTEM_MANDATORY_LABEL_NO_READ_UP (0x01), SYSTEM_MANDATORY_LABEL_NO_WRITE_UP (0x02), SYSTEM_MANDATORY_LABEL_NO_EXECUTE_UP (0x04).

When the access check evaluates the SD, it scans for a SYSTEM_MANDATORY_LABEL ACE. The first non-inherit-only one is the object's effective label. If none is present, the object's effective integrity is Medium with NO_WRITE_UP (the default).

A caller whose effective token's integrity level is below the object's label cannot perform the right categories blocked by the policy bits. The check runs before the DACL walk. A non-dominant caller's deny is decided before any allow ACE in the DACL has a chance to grant the same right.

The label is independent of identity. Two users at different integrity levels with identical SIDs see the same DACL but different effective access, because the label-vs-token-integrity comparison happens first.

MIC is covered in detail in Access decisions.

SYSTEM_PROCESS_TRUST_LABEL: the PIP gate #

A SYSTEM_PROCESS_TRUST_LABEL ACE opts the object in to process integrity protection (PIP). The ACE has:

• A SID of the form S-1-19-T-L where T is the PIP type and L is the trust level.
• A mask specifying the rights that non-dominant callers are explicitly allowed.

PIP enforcement is two-step. First, the access check determines whether the caller's PSB dominates the object's trust label — that is, the caller's pip_type is at least the ACE's type AND the caller's pip_trust is at least the ACE's trust level. If the caller dominates, the trust label imposes no restrictions. If the caller does not dominate, only the rights in the ACE's mask are permitted, and privilege-granted rights are revoked (which is what makes PIP different from MIC).

Objects without a PIP trust label ACE are unprotected — PIP is opt-in. The access check does not impose PIP rules unless the SACL specifically asks for them.

PIP is covered in Process integrity protection.

SYSTEM_SCOPED_POLICY_ID: central access policies #

A SYSTEM_SCOPED_POLICY_ID ACE references a centrally-defined access policy by SID. The policy itself is distributed by authd (from loregd on standalone machines, from the machine's directory source on domain-joined ones) and held in a kernel cache. When the access check sees this ACE, it looks up the referenced policy and evaluates its rules in addition to the object's own DACL — intersecting the result, never widening.

Multiple SYSTEM_SCOPED_POLICY_ID ACEs in one SACL apply multiple policies. The result is the intersection of all of them with the object's DACL.

The mechanism — applies-to expressions, staged vs effective rules, the recovery policy for when a referenced policy is missing — lives in Central access policies. For this page, what matters is that the entry exists, sits in the SACL, and is looked up by SID at access time.

SYSTEM_RESOURCE_ATTRIBUTE: typed properties on the object #

SYSTEM_RESOURCE_ATTRIBUTE carries a typed key-value attribute on the object — referenceable as @Resource.<name> in conditional expressions on this or any other SD. The structural role is described above; the full story is in Resource attributes.

How the SACL is consumed #

The access check consults the SACL twice, at different points:

1. Before the DACL walk, the check scans the SACL for the MIC, PIP, and scoped-policy ACEs. MIC and PIP pre-decide certain bits as denied for non-dominant callers; scoped policies are noted for later evaluation. Resource attribute ACEs are scanned and indexed so that conditional expressions in the DACL can reference them.
2. After the DACL walk, the check scans the SACL again for SYSTEM_AUDIT and SYSTEM_ALARM ACEs and decides which events to fire. The MIC, PIP, and scoped-policy ACEs are not consulted again here — their job is done.

This two-pass shape is why the SACL is "structural" rather than "evaluated": its job is to set policy for the DACL walk and to record audit about the DACL walk's outcome, not to participate in the walk itself.

Modifying the SACL #

The DACL is gated by WRITE_DAC, which the owner has implicitly. The SACL is gated by ACCESS_SYSTEM_SECURITY, which the owner does not have implicitly. To modify a SACL, a caller needs:

• Either SeSecurityPrivilege (which grants ACCESS_SYSTEM_SECURITY on any object), or
• SeRestorePrivilege (which grants it for specific kacs_set_sd use cases — backup/restore tooling).

WRITE_DAC does not grant ACCESS_SYSTEM_SECURITY. An owner who can rewrite a DACL freely cannot touch the SACL. This is deliberate: the SACL holds audit policy and system-level constraints that the object's owner should not be able to unilaterally remove. An audited object's audit policy is the administrator's, not the user's.

Modifying a SACL that contains a MANDATORY-flagged resource attribute is further restricted: removing or changing a mandatory attribute requires SeTcbPrivilege (covered under Resource attributes).

The LABEL_SECURITY_INFORMATION shortcut #

The kacs_set_sd syscall takes a security_information bitmask saying which SD components to update. Two of the bits are relevant here:

LABEL_SECURITY_INFORMATION is the right tool when you want to change an object's integrity level without touching its audit policy. Setting an integrity label downward (to a level at or below the caller's own integrity level) is allowed; setting it above requires SeRelabelPrivilege.

The two flags are mutually exclusive in a single kacs_set_sd call. You either replace the entire SACL or update only the label, not both at once.

What the SACL is not #

A few clarifications:

• The SACL is not for "extra security". It is the kernel's place for system-level policy. Putting more entries in the SACL does not make an object more secure; it just records more policy.
• The SACL is not where the DACL goes if you forget the DACL. The two lists are structurally distinct in the SD format; an SD with a missing DACL but a populated SACL has a NULL DACL (grant all access) regardless of what the SACL says.
• The SACL is not visible to ordinary users. Reading the SACL — kacs_get_sd with SACL_SECURITY_INFORMATION — also requires ACCESS_SYSTEM_SECURITY. An owner can read their object's DACL freely but cannot read its SACL without the same privilege required to modify it.

Where to go next #

For the events audit and alarm ACEs produce, and where they go, read Auditing.

For how the SACL's labels and policies fit into the full check pipeline, read Access decisions.

To read and edit a SACL from a shell, read The sd command.

A security descriptor is a binary structure, but almost nobody writes one by hand. SDDL — the Security Descriptor Definition Language — is its text form: a single line that names an owner, a group, and the two access control lists.

You meet it wherever a descriptor has to be written down rather than computed:

• sd set and sd show --sddl
• mount's --synth-sddl, which supplies the template descriptor for a filesystem that has no native descriptor storage
• registry seeds, which carry descriptors for the keys they create
• peinit service definitions, whose ControlSecurity and ServiceSecurity values are descriptors

This article is the canonical list of the codes Peios accepts. The concepts behind them — what a DACL is, how inheritance propagates, what the SACL carries — have their own articles, linked at the end.

The shape of a descriptor string #

Four optional sections, each introduced by a letter and a colon:

O:<sid>G:<sid>D:<acl>S:<acl>

A section you omit is absent from the descriptor rather than empty, and the formatter emits the sections in the order above regardless of the order you wrote them. A section may appear only once; a repeat is an error rather than an override.

A bare D: is an empty DACL: it contains no grants. A NULL DACL is written D:NO_ACCESS_CONTROL and imposes no discretionary access restrictions. Omitting D: has the same binary meaning as D:NO_ACCESS_CONTROL: the SE_DACL_PRESENT bit is clear and the DACL offset is zero. A bare D: sets PRESENT and points to a real ACL containing zero ACEs. There are two states, not three.

NO_ACCESS_CONTROL may accompany ACL flags, such as D:PAINO_ACCESS_CONTROL, but cannot accompany ACEs. The same applies to S:: S:NO_ACCESS_CONTROL is a descriptor with no SACL.

The formatter leaves out a PRESENT-clear ACL, just as you can, unless it carries P, AR or AI flags. Those have nowhere else to go, so it writes them with the marker: D:PNO_ACCESS_CONTROL. A descriptor with nothing at all to show formats as D:NO_ACCESS_CONTROL, because SDDL has no empty string. The C, Rust and Go SDKs format identically, and their output always parses back to the same binary descriptor.

So a missing D: in a tool's output means a NULL DACL. Tools that read only some sections of a descriptor, such as reg sd --owner, also leave out the sections they did not read. There, a missing section means only that it was not requested.

ACL flags #

An ACL body may open with one or more flags, in any order, before the first (:

So D:PAI(A;;GA;;;SY) is a protected, auto-inherited DACL with one ACE.

An ACE #

Each ACE is a parenthesised list of six semicolon-separated fields, or seven when the ACE carries a payload:

(type;flags;rights;object_guid;inherit_object_guid;account_sid)
(type;flags;rights;object_guid;inherit_object_guid;account_sid;payload)

The two GUID fields apply only to object ACEs and are left empty otherwise — supplying one on a non-object ACE is an error rather than a value that is quietly discarded. The seventh field carries the condition expression on a callback ACE, or the claim on a resource-attribute ACE.

Reading a real one:

O:SYG:SYD:(A;OICI;GA;;;SY)

Owner SYSTEM, group SYSTEM, and a DACL with one ACE: allow (A), inherited by both containers and objects (OI CI), all access (GA), no object GUIDs, to SYSTEM (SY). That is the descriptor Peios seeds /run with at boot.

ACE types #

The callback types are how a conditional ACE is spelled: XA is an allow ACE with an expression in its seventh field.

XL and ZL are Peios' own. Windows names no callback alarm, so a string holding one does not read on Windows.

The formatter fails on any other ACE type, such as a compound ACE (0x04) or an unallocated value. It does not leave the entry out, because a string without it would describe a descriptor other than the one held.

ACE flags #

SA and FA are meaningful only on an audit ACE in the SACL.

Access rights #

Generic rights, mapped to concrete rights by the object class:

Standard rights, which mean the same thing on every object class:

File composites:

Registry-key composites:

Directory-object rights, for object ACEs:

Mandatory-label policy bits, valid on an ML ACE:

An all-ASCII-digit rights field is an unsigned decimal mask. For example, 1179817 means 0x001200a9, and 0 means no rights. Leading zeroes are accepted as decimal, not octal. The maximum is 4294967295 (0xffffffff); larger values, signs and non-ASCII digits are rejected. Decimal masks must occupy the whole rights field and cannot be appended to mnemonic codes. This grammar applies to libpeios, legacy libp-go, and the independent peios-go SDK.

A rights field may also be a hexadecimal mask, written 0x followed by the value. It consumes the rest of the field, so it can only come last — but it may follow letter codes rather than replacing them. FRFX0x6 grants file read, file execute, and the two bits 0x6 names, which is how you reach a right that has no two-letter code without giving up the ones that do:

(A;;FRFX0x6;;;WD)

FILE_ADD_FILE and FILE_ADD_SUBDIRECTORY are the usual reason to need it. Writing the whole mask as 0x1200af is equally correct and tells a reader nothing.

SID codes #

An account field takes either a full S-1-… SID or one of these aliases.

Principals and logon types:

Inheritance placeholders:

Integrity levels:

The BUILTIN groups, S-1-5-32-*. These are absolute despite the name: the RIDs are fixed, not allocated per machine.

SU is worth knowing about: it is the group every token minted for a service logon carries, so it is how you grant something to services as a class rather than naming each one. Membership follows from how a process was started rather than from which account it runs as, so an ordinary user process cannot acquire it.

CO is the one you reach for most often after that. An inheritable ACE naming Creator Owner is rewritten to the new object's owner when a child is created, which is how a container grants each principal rights over what it makes there without granting anything over what anyone else makes.

Two SIDs you might expect have no alias and must be written in full: the null SID S-1-0-0, and the protected-process integrity level S-1-16-20480.

The same two letters mean different things in different fields #

The code tables overlap, and a code is interpreted by the field it appears in rather than by its spelling. The collisions that catch people out:

So in (A;FA;FA;;;WD) the first FA is an ACE flag, the second is a rights mask, and WD is Everyone rather than write-DACL. Each is unambiguous in place, but none of them reads that way at a glance.

Not everything that parses is emitted #

Reading a descriptor and formatting it again does not always return the string you started with, and this is deliberate rather than a defect.

The directory-object rights (CC through CR) and the mandatory-label bits (NW, NR, NX) occupy the same low bit positions as one another. Which of them a bit means depends on the object class and the ACE type. The ACE type settles it for a mandatory label, so an ML entry's mask comes back as NW, NR and NX. Elsewhere the formatter would have to guess, so it accepts the directory-object codes when parsing and emits none of them, falling back to a hexadecimal mask. KX is dropped for a related reason: it shares a mask with KR, so only one of the two can ever come back.

The formatter also prefers composites to their components, emitting FA rather than the eight codes that add up to it.

Domain- and machine-relative aliases #

The codes DA, DG, DU, DD, DC, SA, EA, RO, CA, PA, CN, AP, KA, EK and RS name principals relative to a domain — domain admins, domain users, and so on — and LA and LG name the local administrator and guest accounts relative to a machine. Peios recognises them so that it can reject them with a message that says what is wrong, and it cannot resolve them: there is no domain or machine SID for them to be relative to. Write the SID you mean instead.

RU reads like one of these and is not: it is BUILTIN\Pre-Windows 2000 Compatible Access, S-1-5-32-554, and resolves like any other BUILTIN group.

Reading a descriptor #

sd show normally renders its selected view for a person to read. Its rights column uses a shorthand of its own — a lone f is all file access (0x001F01FF), not the single bit 0xF. To format the queried owner, group, DACL and integrity-label subset as SDDL:

sd show --sddl /usr/bin/login

The command does not query the full SACL. Formatting cannot recover audit ACEs or other components absent from the query: matching strings are not proof of full descriptor equality, and this output is not a complete backup to replay with sd set. See sd show inspection limits.

Where to go next #

• Security descriptors — what the parts of a descriptor do.
• ACLs and ACEs — how the entries you have just learned to spell are evaluated.
• Inheritance — what CI, OI, NP, IO and ID do to a tree.
• Conditional ACEs — the expression language behind the callback types.
• The sd command — reading and writing descriptors on real objects.

A privilege is a system-wide right carried on a token. Where group membership decides "is this principal allowed to do things by virtue of who they are", a privilege decides "is this principal allowed to do this specific operation, regardless of who they are". Loading a kernel module, taking ownership of an object, changing the system clock, reading any file for backup — each is gated by a specific privilege, granted to principals whose role legitimately requires it.

Privileges sit on the token alongside the user SID and group list, but they are evaluated separately from identity. The access check reads a privilege bitmask, not a group membership. An ACE in a DACL cannot match a privilege the way it matches a SID. Privileges are their own axis of authority.

What a privilege is #

A privilege has three properties:

• A name — a specific string like SeBackupPrivilege. Most privilege names start with Se and end with Privilege; the convention is shared across the catalog.
• A LUID — a 64-bit identifier the kernel uses internally to reference the privilege. Privileges occupy specific bit positions in the 64-bit privilege bitmask on every token.
• A specific operation it gates — every privilege has a defined effect: which kernel operation, which AccessCheck pathway, which capability it controls.

Privileges are global. The catalog is fixed at build time; there is no API to define new privileges at runtime. A token either has a specific named privilege or does not. The number of distinct privileges in v0.20 is in the low tens.

Where privileges come from #

A token's privileges are decided at one moment: when the token is minted. That happens either:

• During boot, when the kernel constructs the SYSTEM token (which holds every privilege).
• When authd authenticates a principal and constructs their token, applying the privilege policy authd has loaded for the principal's role.
• When peinit mints a token for a service it is launching.
• When existing code creates a derived token via DuplicateToken (preserves privileges) or FilterToken (removes the listed privileges).

There is no path to gain a privilege after a token is minted. AdjustPrivileges can enable or disable a privilege the token already has, and can permanently remove a privilege, but cannot add one that was not present at creation. A token's privilege bitmask is at most what was put there at the start.

The privilege policy authd consults — which principals get which privileges — is local to the machine, and lives in the registry under Machine\Generic\Authn\Policy, one record per principal. authd reads it at every logon. See assigning privileges for the record format and the rules.

That it is local is the design rather than an implementation detail. A principal source — the local store, or a directory — says who someone is: their SID, their memberships, their POSIX identifiers. It never says how much this machine trusts them, and the protocol it speaks gives it no way to. So a directory can tell this machine that you are a member of Domain Admins; whether that membership carries SeLoadDriverPrivilege here is this machine's answer, not the directory's.

From the kernel's point of view the policy is invisible: it only ever sees the resulting token.

The four states of a privilege #

At any moment, each privilege on a token is in one of four states:

The states layer rather than replace. A privilege that has been used remains in whatever present/enabled state it was in; the "used" bit is recorded alongside, for auditing.

Disabling rather than removing is the common pattern. A service runs most of the time with sensitive privileges present but disabled, enabling them only at the moment they need to be exercised and disabling them afterwards. The reason: the access check ignores disabled privileges entirely, so the service is not at risk of accidentally exercising a privilege it had not meant to use.

The full lifecycle — transitions, AdjustPrivileges semantics, FilterToken-based permanent removal, the "used" bit — lives in Privilege lifecycle.

Privileges in the access check #

Privileges interact with the access check in three ways:

Direct gating #

Some operations are gated directly by a privilege held at the moment of the call, with no DACL involved.

• SeLoadDriverPrivilege gates kernel module loads. No DACL applies; either you have the privilege enabled or the load fails.
• SeSystemtimePrivilege gates settimeofday.
• SeCreateTokenPrivilege gates kacs_create_token.

These privileges are direct. The check is "is this privilege enabled on the calling token" and nothing else.

Influencing the DACL walk #

A handful of privileges, when enabled, change what the DACL walk would conclude. These are the AccessCheck-influencing privileges, covered in Privilege categories:

• SeSecurityPrivilege grants ACCESS_SYSTEM_SECURITY (SACL read/write) regardless of the DACL.
• SeTakeOwnershipPrivilege grants WRITE_OWNER on any object.
• SeBackupPrivilege grants read access to any object (with the backup intent flag set).
• SeRestorePrivilege grants write access and ownership-change rights (with the restore intent flag).
• SeRelabelPrivilege permits raising an object's integrity label above the caller's own.

These privileges produce grants that no DACL would have produced. They are recorded in the access check's audit state so audit events can record "this access was granted by privilege X" rather than appearing as a DACL grant.

Intent-gated privileges #

Two of the influencing privileges — SeBackupPrivilege and SeRestorePrivilege — only fire when the caller passes a specific intent flag to AccessCheck. Without the flag, the privileges might as well not be present. This avoids accidentally exercising a backup privilege when doing a normal read.

The intent model is covered in Intent-gated privileges.

Privileges vs groups #

The split between privileges and group membership is one of the deliberate design decisions of the model:

A user can be in a group and still not hold a privilege the rest of the group has, or vice versa, because the two are managed independently — and, more than that, they are managed by different parties. Memberships come from whoever holds the account; privileges come from this machine.

The classical example: BUILTIN\Administrators is a group, and being in it grants whatever ACEs in DACLs name the group. But the dangerous privileges — SeLoadDriver, SeBackup, SeRestore — are not automatic by group membership. Local policy specifies which administrators get which privileges, and it does so by naming principals: a record for one account's SID can grant it privileges the rest of Administrators does not have, or withhold ones they do.

This separation matters because the failure modes are different. A misconfigured DACL grants too much group access; a misconfigured privilege policy grants too much system-level authority. Both are fixable in different places.

Privileges and inheritance #

Group memberships propagate down through identity (you remain in your groups until your token changes). Privileges work the same way: a token holds the privileges authd minted it with, and the bitmask is preserved through fork, exec, and inheritance into child processes — exactly like the rest of the token.

Privileges do not propagate to ACEs or objects. There is no "privilege-bearing" ACE; no SD can be annotated with a privilege requirement; no object can demand "you must have SeBackup to open me". The privilege model and the SD model do not overlap that way. They interact only through the access check, when an influencing privilege is enabled on the caller's token and the AccessCheck pipeline decides whether to use it.

Where to start #

If you want the lifecycle in detail — the present/enabled/used/removed transitions, what AdjustPrivileges actually does, how FilterToken removes a privilege permanently — read Privilege lifecycle.

If you want to understand intent-gated privileges — why SeBackup and SeRestore require an explicit flag and how that flag is passed — read Intent-gated privileges.

If you want to see how privileges are organised — the kernel-standalone group, the AccessCheck-influencing group, the application-level group, the reserved group — read Privilege categories.

If you want the full catalog of named privileges with their numeric LUIDs and one-line descriptions, that is in the Constants and catalogs reference.

A privilege's state on a token is more than just "yes, the token has it". The four-state model — absent, present-disabled, present-enabled, used — exists so a service can hold a sensitive privilege most of the time without exercising it, enable it briefly when it actually needs it, disable it again afterwards, and have all of those transitions auditable.

This page covers each transition: how privileges get added (only one moment), how they get enabled and disabled (many times), how they get permanently removed (one-way), and what the "used" bit means for auditing.

The four states #

From the Privileges overview:

The bitmask is a 64-bit word. Each privilege occupies a fixed bit position (its LUID determines which). The token actually carries four independent 64-bit words: present, enabled, enabled_by_default, and used. Most code only cares about the first two.

enabled_by_default records the initial state — what was enabled at token creation. The kernel uses it to implement the "reset to defaults" sentinel in AdjustPrivileges.

Adding a privilege: only at creation #

There is exactly one moment when a privilege can be added to a token: when the token is being created. Specifically:

• During boot, the kernel constructs the SYSTEM token with every privilege present and enabled.
• When authd calls kacs_create_token, the wire-format specification names the privileges to include and which of them should start enabled.
• When peinit calls kacs_create_token for a service.

DuplicateToken preserves the privilege bitmask of the source — every present bit, every enabled bit, every used bit copies into the new token. The duplicate has the same privileges as the source.

That is the entire list of paths. There is no syscall, no ioctl, no privileged API to add a privilege to an existing token. A token's present bitmask is at most what it was at creation; it can only shrink over time.

This rule is one of the load-bearing parts of the security model. It is what makes "the principal's authority is fully expressed by their token" true. If a process could acquire new privileges at runtime, the kernel would need to track which privilege-acquisition paths exist and protect each one. By making creation the only entry point and authd the only entity that can use it, the kernel concentrates the privilege-policy decision into one component, audited at one moment.

Enabling and disabling: AdjustPrivileges #

The most common runtime operation on privileges is enabling or disabling them. The syscall is AdjustPrivileges (also reachable as the KACS_IOC_ADJUST_PRIVS ioctl on a token fd).

The caller passes an array of kacs_priv_entry records, each containing:

• A LUID identifying which privilege to adjust.
• An attributes value telling the kernel what to do with it.

The attributes value is one of:

The operation is atomic: every entry in the array is validated first, and if any one is invalid (a LUID for a privilege not present on the token, an unknown attributes value, a duplicate LUID), the entire call fails and no changes are made. There is no partial success.

The call returns the previous state of every privilege touched, as a bitmask. Callers that want to do scoped privilege enable — turn on a privilege, do work, turn it off — read the return value to know what state to restore to. The pattern:

1. Save previous state by calling AdjustPrivileges to enable the desired privilege.
2. Do the work.
3. Call AdjustPrivileges again with the saved state to restore.

If the privilege was already enabled before step 1, step 3 leaves it enabled. If it was disabled, step 3 restores it to disabled. Either way the work runs with the privilege enabled and the original state is preserved.

What AdjustPrivileges cannot do #

AdjustPrivileges cannot:

• Add a privilege. A LUID for a privilege not present on the token is rejected. The token must already have the privilege; AdjustPrivileges only changes its enabled state or removes it.
• Resurrect a removed privilege. Once SE_PRIVILEGE_REMOVED is applied, the privilege is absent. A subsequent attempt to enable it fails (the privilege is no longer present).
• Toggle the used bit. The kernel sets used automatically when a privilege is exercised. Userspace cannot clear it.
• Set enabled without present. The kernel rejects this — a privilege cannot be enabled if it is not present on the token. The "enabled but absent" state is not representable.

The right to call AdjustPrivileges is gated by TOKEN_ADJUST_PRIVILEGES (0x0020) on the target token. A thread can always adjust its own token's privileges (the default token SD grants this right to the token's user identity); adjusting another process's token requires PROCESS_QUERY_INFORMATION on that process, TOKEN_ADJUST_PRIVILEGES on the token, and the appropriate PIP dominance.

The "used" bit and audit #

When AccessCheck or any other kernel path actually exercises a privilege on a token, the kernel sets the corresponding bit in the token's used bitmask. Once set, the bit remains set for the life of the token. Nothing — not AdjustPrivileges, not FilterToken, not DuplicateToken into a fresh token — clears it.

The bit is for auditing. It answers the question "did this token, at some point in its existence, exercise this privilege?". A security audit can read a token's used bitmask to see which privileges have been engaged so far. A privilege that is present but never used is materially different from one that has been used; the used bit records the difference.

This is why removal does not clear used. If a privilege has been exercised, removing it later does not erase the fact. The audit trail remains.

DuplicateToken copies used from the source. A duplicate of a token that has used a privilege is itself marked as having used it, even though the duplicate has never actually exercised it. The rationale: a duplicate inherits the source's audit history; if the source has used a privilege, anything derived from it is suspect of having access to that privilege's effects.

If you need a fresh, audit-clean token, you need a freshly-minted token (a new authentication, or a new kacs_create_token call). Duplicates carry history.

Permanent removal #

SE_PRIVILEGE_REMOVED permanently removes a privilege from a token. After removal:

• present is clear.
• enabled is clear.
• enabled_by_default is clear.
• used remains whatever it was (still set if the privilege was exercised before removal).

The removal is irreversible. There is no syscall to re-add. The only way back to a token with the privilege is to start with a different token — typically by FilterToken from a source that still has the privilege, or by a fresh authentication.

Removal is the right tool for:

• Service hardening. A service that holds privileges by default but only needs them at startup can remove them after the startup phase. Removing rather than disabling makes the privilege unrecoverable for the remainder of the service's lifetime — even if an attacker compromises the service later, the privileges are gone.
• Sandbox launchers. Code that forks a child to run untrusted work removes every dangerous privilege from the child's token before exec. The child has no way to get them back.
• One-way demotion. A process starting with high authority that wants to demote itself to a lower-privileged identity, irrecoverably, removes the privileges it no longer wants. This is stronger than disabling: a disabled privilege can be enabled by code running on the token (assuming TOKEN_ADJUST_PRIVILEGES); a removed privilege cannot.

The one-way nature is the point. The model is built around the assumption that authority shrinks. A removed privilege is gone for the same reason a disabled group can be marked use-for-deny-only and not un-marked: each is a deliberate restriction the kernel will not let userspace undo.

FilterToken and bulk removal #

For removing multiple privileges at once — typically during sandbox creation — FilterToken is the appropriate API. Where AdjustPrivileges with SE_PRIVILEGE_REMOVED removes one privilege from the calling token, FilterToken produces a new token with the listed privileges removed.

The difference matters: FilterToken does not modify an existing token. It creates a copy with the listed adjustments (privileges removed, groups marked use-for-deny-only, restricted SIDs added) and returns the new token. The original is unchanged.

This is the right pattern for sandbox launchers, which want to filter a token down to a restricted version for a child process without affecting their own running identity. AdjustPrivileges with SE_PRIVILEGE_REMOVED is the right pattern for code that wants to demote itself.

FilterToken is covered in Token lifecycle and Restricted and write-restricted tokens.

The reset-to-defaults sentinel #

A token records enabled_by_default separately from enabled. The two diverge as the token's privileges get enabled and disabled at runtime; the default record stays as it was at creation.

The KACS_PRIV_RESET_ALL_DEFAULTS sentinel — a kacs_priv_entry with luid = 0 and the sentinel attributes value — tells AdjustPrivileges to copy enabled_by_default back into enabled. Every privilege that was enabled at creation is now enabled again; every privilege that was disabled at creation is now disabled again.

The sentinel is useful for code that does "enable a few privileges, do work, restore". Instead of saving the prior state and restoring it explicitly, the code can simply reset to defaults — which is the right behaviour as long as nothing else has changed the defaults (which nothing should, since defaults are immutable at creation).

The reset sentinel only affects enabled. It does not bring back removed privileges. It does not clear the used bit. It is a cheap way to "go back to how this token started" within the set of operations that still make sense.

Field mutability summary #

To pin the entire model on one table:

The asymmetric mutability is the model's spine. Authority can decrease at runtime but not increase. State for auditing accumulates. Defaults are fixed. The "easy" mutation — toggle enabled — is the only one that goes both ways, and it does not affect what the token fundamentally is.

Where to go next #

For the two privileges that require an intent flag on top of being enabled, read Intent-gated privileges.

For bulk privilege removal as part of building a sandbox token, read Restricted and write-restricted tokens.

Most privileges work the same way: if they are enabled on the calling token at the moment of the call, the kernel uses them; if not, it does not. AdjustPrivileges manages enabled state; the access check reads it. There is no other input.

Two privileges are special: SeBackupPrivilege and SeRestorePrivilege. Both are present-and-enabled on the tokens of backup-and-restore tools. Both grant access that the DACL alone would not. And both will refuse to do anything unless the calling code passes a specific intent flag to AccessCheck — BACKUP_INTENT for SeBackup, RESTORE_INTENT for SeRestore.

Without the intent flag, the privilege is invisible to the access check. The token has it. The kernel knows it has it. But the privilege does not participate in the access decision. The DACL walk runs as if the privilege were not present.

This page covers why intent gating exists, how the flags are passed, and what each privilege actually does when its intent flag is set.

Why intent gating exists #

The privileges in question grant very broad access. SeBackup grants read on any object regardless of the DACL. SeRestore grants write, ownership change, and SACL access on any object. They are designed for backup-and-restore tools — programs that legitimately need to bypass discretionary access control to do their job.

The problem: if these privileges were always in effect when enabled, every access check on a token holding them would benefit from them. A backup tool that opens a configuration file as part of its initialisation — for entirely ordinary reasons — would silently exercise SeBackup, even though the configuration file's normal DACL would have granted the access anyway. The audit trail would record privilege exercises that were operationally meaningless. Worse, a buggy code path in the tool that did something unintended would silently get backup-level access to the unintended object.

Intent gating solves this by making the privilege opt-in per call. The tool's main backup loop sets BACKUP_INTENT on every AccessCheck call it makes; everything else does not. The privilege fires only where the tool deliberately asked for it. Audit events for privilege exercise are accurate (they only appear where the tool intentionally invoked the privilege), and bugs in non-backup code paths cannot accidentally exercise SeBackup.

The split is between "enabled" (the token can use the privilege) and "intent" (the caller wants to use the privilege right now). Both must be true.

The intent flags #

The flags are passed to AccessCheck as part of the privilege_intent parameter. They are independent bits:

A caller can set both, one, or neither. The flags are not exclusive — a backup-and-restore tool might do a restore-with-verification operation that wants both privileges to fire.

Without either flag, the corresponding privilege is stripped from the access check's view of the token for this call. It is not removed from the token; the token still has it; the next call from the same code can set the flag and use it. The strip happens only for the current AccessCheck.

The flags are at the AccessCheck API surface. Lower-level open and access paths (the file system's open, the registry's read) translate higher-level semantics into AccessCheck calls; whether they pass the flags depends on whether they were told to. Most do not; an opener of a file in the ordinary course of work does not pass BACKUP_INTENT.

What SeBackupPrivilege does #

With BACKUP_INTENT set and SeBackup enabled, AccessCheck grants the caller read-category rights on the object regardless of the DACL:

• For files: FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, and READ_CONTROL.
• For registry keys: the read-category rights on the key (the specific values depend on the registry's GenericMapping).
• For tokens: TOKEN_QUERY and READ_CONTROL.

The grant happens after the DACL walk has run. Specifically, the walk produces a granted mask for whatever the DACL alone would grant; the privilege then adds the read-category bits to that mask without consulting the DACL. If the DACL already granted some of them, the privilege grant is redundant; if the DACL granted nothing, the privilege adds them.

The grant is recorded in the access check's audit state. An audit event for this call records "the read rights came from SeBackupPrivilege", distinguishing privilege-granted access from DACL-granted access. Audit consumers that care about privilege use can filter by this marker.

SeBackup does not grant write access. A backup tool that needs to write its output also reads but cannot use SeBackup for that — write is SeRestore's territory.

What SeRestorePrivilege does #

With RESTORE_INTENT set and SeRestore enabled, AccessCheck grants the caller write-category rights and metadata-modification rights regardless of the DACL:

• Write rights (FILE_WRITE_DATA, FILE_APPEND_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA for files; corresponding rights on other object types).
• DELETE.
• WRITE_OWNER and WRITE_DAC.
• ACCESS_SYSTEM_SECURITY (SACL read/write).

Plus, separately, SeRestore bypasses the "new owner must be self or SE_GROUP_OWNER group" restriction during kacs_set_sd. A restore tool can set the owner of a restored object to any well-formed SID, not just the caller's own. This is what lets a backup restore reconstitute an object's original owner even when the original principal is not present on the running system.

Like SeBackup, the grant is recorded in audit state — write rights granted by SeRestore are distinguished from those granted by the DACL.

The reason SeRestore also grants ACCESS_SYSTEM_SECURITY (which would normally require SeSecurityPrivilege) is the same: a restore operation needs to set the SACL as part of reconstituting the object's policy. Forcing the tool to also hold SeSecurity would be redundant; SeRestore folds that authority in.

What the flags do not do #

Two clarifications:

• The flags do not grant privileges. A token that does not have SeBackup gets nothing from setting BACKUP_INTENT. The flag tells the kernel "use this privilege if I have it"; it cannot conjure a privilege the token lacks.
• The flags do not enable disabled privileges. A token that has SeBackup present but disabled gets nothing from BACKUP_INTENT, just as it would get nothing without the flag. The privilege must be enabled for AccessCheck to consider using it. Intent is on top of enabled, not in place of it.

The state machine is: token has the privilege AND token has the privilege enabled AND caller has set the intent flag = AccessCheck uses the privilege. Any one of the three missing means it does not.

Why only these two privileges #

The intent-gating model exists specifically for privileges that grant broad, blanket access. SeBackup grants read on everything; SeRestore grants write on everything. The risk of accidental exercise is high enough to be worth a per-call gate.

Other privileges that influence the access check — SeSecurityPrivilege (SACL access), SeTakeOwnershipPrivilege (WRITE_OWNER), SeRelabelPrivilege (raising integrity) — are not intent-gated. They are scoped enough that the "just check if enabled" model is appropriate. SeSecurity only fires when accessing the SACL; SeTakeOwnership only when changing the owner; SeRelabel only when changing the integrity label — none of which is done by accident.

The split is between "this privilege only fires when you do something specific anyway" (no intent needed) and "this privilege would fire on every access if we let it" (intent required). SeBackup and SeRestore are the only two privileges in the second class.

Calling pattern #

A typical backup tool's loop:

1. Token at startup has SeBackupPrivilege present and enabled. (Granted by authd's privilege policy to backup-role principals.)
2. For each object to back up:
   • Call AccessCheck with BACKUP_INTENT set in privilege_intent. The kernel grants the read-category rights via SeBackup if the DACL would not.
   • Read the object.
3. Other operations the tool does (reading its own configuration, writing log output, opening its output file) call AccessCheck without BACKUP_INTENT. These run through the DACL like any other access. The privilege is not exercised.

A typical restore tool's loop is the mirror:

1. Token at startup has SeRestorePrivilege present and enabled.
2. For each object to restore:
   • Call AccessCheck with RESTORE_INTENT set. The kernel grants write-category rights via SeRestore.
   • Write the object's contents.
   • Set its SD via kacs_set_sd, including owner. The "any well-formed SID can be the owner" rule is in effect because RESTORE_INTENT was set on the AccessCheck that produced the WRITE_OWNER grant.
3. Other operations run normally without the flag.

The pattern is symmetric. Both privileges work the same way; both follow the same intent rule.

What about privileges in audit events #

Audit events for privilege exercise carry enough information to distinguish:

• The privilege that was exercised.
• The bits it contributed to the final granted mask.
• Whether those bits survived to the final access decision (i.e., were not stripped by some later layer like restricted-token intersection or confinement).

A backup tool with BACKUP_INTENT set on every AccessCheck call produces clean audit events: one privilege-use event per backup-flavoured access, none for incidental accesses. This is the audit trail intent gating was designed to produce. Without the flag, the privilege would fire on every access from the same token, and the audit would be unable to distinguish "I exercised SeBackup because I'm a backup" from "I exercised SeBackup because the file would have been readable to me anyway".

The full audit model lives in Auditing.

Where to go next #

For the four functional categories the rest of the privileges fall into, read Privilege categories.

For exactly where SeBackup and SeRestore fire during a check — and which layers can still strip their grants — read Privileges in the pipeline.

The privileges in Peios fall into four functional categories. Each category has a different relationship to the kernel and to the access check. Knowing which category a privilege is in tells you what it does, where it fires, and whether to expect it to participate in the DACL walk.

This page is organised around the four categories. The full per-privilege catalog — name, LUID bit, one-line description for every privilege — is in Constants and catalogs.

The four categories #

The categorisation is functional, not structural. A token's privilege bitmask does not partition by category; all bits live in the same 64-bit word. The category is a property of how each individual privilege is consumed.

Kernel-standalone privileges #

These are the largest category. A kernel-standalone privilege gates a specific kernel operation: the kernel checks at the entry point whether the caller's effective token has the privilege enabled, and refuses the operation if not. The DACL walk is not involved.

Representative members:

For all of these, the calling pattern is the same: the kernel reads the calling token's privilege bitmask at the entry point of the gated operation; if the privilege is not enabled, the operation fails with the appropriate error.

The privileges in this category are mostly held in narrow ways. The most dangerous of them — SeCreateToken, SeTcb, SeLoadDriver — appear on only a handful of TCB token holders. Most other services hold a small, role-specific subset.

AccessCheck-influencing privileges #

These privileges, when enabled, change what the access check itself decides. They produce grants the DACL alone would not.

These privileges fire at specific points in the access pipeline:

• SeSecurityPrivilege is consulted when AccessCheck sees ACCESS_SYSTEM_SECURITY in the requested mask.
• SeBackupPrivilege and SeRestorePrivilege are consulted near the start of AccessCheck, but only if the corresponding intent flag is set in privilege_intent. See Intent-gated privileges.
• SeTakeOwnershipPrivilege is consulted after the DACL walk: if the walk did not grant WRITE_OWNER and the mandatory policy did not block it, the privilege grants it.
• SeRelabelPrivilege is consulted by kacs_set_sd when the caller is trying to set an integrity label.

When any of these privileges contributes to the final granted mask, the access check records the fact so audit events can attribute the grant correctly. Audit consumers can distinguish "the user got read access because the DACL allowed it" from "the user got read access because they hold SeBackup and asked to use it".

Application-level privileges #

These privileges are defined for authd, the directory, and federation services to interpret. The kernel records them on the token (so authd has somewhere to put them) but does not enforce them itself.

From the kernel's point of view, these are token attributes that no kernel path checks. They appear on the token's privilege bitmask; AdjustPrivileges can enable, disable, or remove them like any other privilege; but no AccessCheck path consults them. Their effect happens entirely in user-space services that read the token and act on its privilege bitmask themselves.

The kernel still enforces the present/enabled/removed/used state machine for these privileges as it does for others — AdjustPrivileges treats them identically. The application-level distinction is about who consumes them, not how they are stored or transitioned.

What SeManageVolumePrivilege is actually worth #

In kernel source 8e0e22de3a59cad506bbbf8873de456e16ad272d, the volume-management gate accepts enabled SeManageVolumePrivilege or SeTcbPrivilege and must successfully mark the privilege as used. Both mount-policy writes and reads use it. This resolves the TCB-only descriptions for that source revision; it does not identify a historical release boundary or test the deployed kernel. The mount diagnostic can still name only TCB. Do not automatically grant TCB or globally remap CAP_SYS_ADMIN in response.

Mounting is an administrative act rather than a TCB one, which is why this privilege exists separately: without it no administrator could mount anything, and peios-install could not run outside a SYSTEM shell.

But be clear about its reach before granting it more widely. Its holder may:

• mount a filesystem whose synthesised security descriptors it chooses (policy=synth-* with --synth-sddl), and
• mount over an existing path.

Together those are enough to author policy on a subtree and to shadow a system path — so in the hands of a determined holder it is a route to authority approaching the TCB's.

This is a deliberate design decision, not an oversight. The narrower alternatives — permitting only filesystems that carry their own descriptors, or constraining synthesis to a fixed system template — were considered and rejected, because the FAT ESP carries no descriptors of its own and must be mounted synth-ephemeral for an installation to work at all.

Treat SeManageVolumePrivilege as sitting beside SeLoadDriverPrivilege in sensitivity, not beside SeChangeNotifyPrivilege.

Mounting passes three separate checks, and the privilege covers all three: may_mount() (may I reshape my namespace), mount_capable() (may this context create a superblock), and KACS's set_mount_policy (may I choose how descriptors are synthesised). They were found one at a time by driving a real image — each fix moved the failure to the next gate — which is worth knowing if a fourth ever appears.

Reserved privileges #

A handful of privileges appear in the catalog for binary compatibility with the spec lineage but have no implementation in v0.20:

A reserved privilege's LUID position in the bitmask is allocated, but no kernel path consults it. They are placeholders that keep the bitmask layout stable for future use. A reserved name is not in the privilege vocabulary at all, so a policy record naming one is dropped with a warning rather than granting anything.

Default-grant privileges #

Two privileges deserve a special note: SeChangeNotifyPrivilege and SeCreateSymbolicLinkPrivilege are granted to every principal on a stock machine. The reason is that they are needed for almost every program to function normally — without SeChangeNotifyPrivilege, a process cannot traverse a directory to reach a file, so a token lacking it cannot so much as start a shell; without SeCreateSymbolicLinkPrivilege, a process cannot create the symlinks that build systems and packaging tools depend on.

They are granted by the shipped policy — a record for Everyone — rather than being built into authd, so both are visible and both can be taken away. See assigning privileges. SeChangeNotifyPrivilege alone is additionally authd's compiled floor, applied when a machine has no policy key at all, because a machine that cannot start a shell cannot be repaired from a console.

Their effect is broad-but-uninteresting: on a stock machine every token has them, so any reasoning about access that does not explicitly involve their absence can ignore them. They are mentioned here for completeness; they will rarely be the answer to a question about who can do what.

A token can have these stripped by FilterToken if a sandbox wants to operate without them. Doing so creates a token that cannot traverse arbitrary directories — useful in a tightly confined sandbox, not useful much elsewhere.

How to find the catalog #

The four-category model on this page is the conceptual structure. The byte-level catalog — every privilege name, its LUID bit position, its one-line effect — lives in Constants and catalogs. Cross-reference between the two when you need to look up a specific privilege.

The naming convention is uniform: every privilege starts with Se and ends with Privilege. The middle is descriptive: SeLoadDriver, SeBackup, SeChangeNotify. There are no privileges outside this convention.

Where to go next #

For the per-privilege reference — every name, LUID bit position, and one-line effect — see the Privilege catalog.

For how the AccessCheck-influencing category actually participates in a check, read Access decisions.

AccessCheck is the function the kernel calls every time something is about to happen to a protected object. The caller has a token; the object has a security descriptor; the caller wants some set of rights. AccessCheck takes all three and produces an answer: which of those rights are granted, which are not, and whether to fire any audit events as a result.

The function is not a single comparison. It is a pipeline of layers, each of which can constrain the result. A right that the DACL would have granted can be removed by a later layer (restricted-token intersection, confinement, central access policy). A right that the DACL would not have granted can be added by an earlier layer (privilege grants). Following an access decision through is following each layer in order.

This page walks the pipeline from start to finish, names every stage, and points each one at the topic that covers it in depth.

The shape of an access check #

flowchart LR
    A["Token (caller)"] --> X["AccessCheck"]
    B["Security descriptor (object)"] --> X
    C["Desired mask (caller asked for)"] --> X
    D["Optional inputs: privilege intent, self SID, local claims, object type list, PIP from PSB"] --> X
    X --> R["Granted mask + audit emissions + continuous audit mask + staging mismatch flag"]

Inputs:

Outputs:

The function does not return a boolean. It returns a granted mask, and the caller is responsible for comparing that mask against what was requested. "Access denied" is what happens when the granted mask does not contain all the requested rights — but partial grants are visible to the caller, and MAXIMUM_ALLOWED callers specifically want to know everything they would have gotten.

The pipeline, step by step #

The pipeline runs in a defined order. Each step either pre-decides bits, modifies the running state, or both. The kernel implements it as a 15-step procedure; this section names each step, says what it does, and points to where it is covered in detail.

The numbering is the kernel's; you will see it in audit and error messages.

Reading the pipeline #

A few observations about the shape that are worth pinning before reading the deeper pages:

Pre-DACL layers can pre-decide bits as denied. MIC and PIP do this for non-dominant callers. A bit pre-decided as denied stays denied; no later step can grant it. The owner of an object that has a high mandatory label cannot read it from a lower-integrity session even though the DACL would grant the read.

Pre-DACL layers can pre-decide bits as granted. Step 4 (privilege grants) does this. Bits granted by privilege are decided before the DACL walk runs; the walk's first-writer-wins applies to undecided bits, so a privilege grant is effectively immune to a later DACL deny.

The DACL walk is the central act. Steps 0–7 set up state for it; steps 9–12 narrow what it produced. The walk itself, governed by DACL evaluation, is where most of the visible policy lives.

Narrowing layers (restricted, confinement, CAAP) only remove access, never add. A right that the DACL plus privileges granted may be lost in steps 10–12. A right that those did not grant cannot be added by the narrowing layers.

Audit fires last and observes everything. By the time the audit walk runs (step 14), the granted mask is final. Audit ACEs can compare against the requested mask, the granted mask, and the difference, and decide whether to emit. Token-forced audit policy can emit even when no SACL ACE matched.

A staging mismatch is informational, not corrective. Step 12 evaluates both the effective CAAP rules (which affect the granted mask) and the staged CAAP rules (which do not). If they would have produced different results, the function reports it; it does not change the granted mask.

Two AccessCheck variants #

The kernel exposes two AccessCheck syscalls. They differ in what they return:

The pipeline is the same for both. The list variant just tracks per-node state through every step, so an object type list with twelve nodes produces twelve granted masks at the end, one per node.

For most objects (files, registry keys, tokens), the regular variant is the right one. Per-property is meaningful only when the object has properties that can be granted independently — for example a directory object with named attributes.

Object type list, briefly #

Object ACEs in a DACL carry a property GUID. When the caller passes an object type list, AccessCheck evaluates each ACE against each node of the tree, propagating per-property grants and denials according to the tree structure (a grant on a parent set flows to its children; a denial flows up; sibling grants intersect).

The tree itself is provided by the caller as a preorder-flat array of kacs_object_type_entry records. The array must be well-formed: starts at level 0, no level gaps, no duplicate GUIDs, and so on. Malformed lists are rejected at step 1.

The full mechanics of object ACEs and the object type list are in ACLs, ACEs, and access masks. Most code never builds an object type list — they exist for the directory-object case specifically.

The decision is made at open, and it stays made #

AccessCheck runs when a handle is created — at open, at connect, at attach — and stamps the granted mask on the handle. Later operations check that mask, not the descriptor. So changing a descriptor narrows what future opens get; it does not reach into handles that already exist, and it never reaches into memory. A mmap(MAP_SHARED) mapping consumes its rights from the descriptor it was made from, and once the pages are mapped, no descriptor edit, kacs_set_sd or token change can take them back: revocation does not extend to established mappings. If a file must become unreadable to a process that already mapped it, the only remedies are the ones that end the mapping — the process exits, or the file is replaced rather than edited in place.

The same holds for every handle-shaped object: a token handle, a process handle, a socket. Peios is deliberately NT-like here. The alternative — re-checking on every read — would make access control a per-page cost and would still be racy against memory that has already been copied.

Where to start #

If you want MIC in depth — what an integrity level actually does to access, how the policy bits work, how the SD's mandatory label drives it — read Mandatory integrity control.

If you want to know exactly which bits each AccessCheck-influencing privilege grants and where in the pipeline that grant happens, read Privileges in the pipeline.

If you want the narrowing layers — restricted-token pass, confinement pass, CAAP — in detail, read Narrowing layers.

If you are debugging an unexpected denial right now, read Debugging a denial.

Mandatory integrity control is the layer of the access check that gates rights based on a numeric trust axis called the integrity level. Where the DACL asks "is this principal allowed?", MIC asks "is the caller trusted enough to do this regardless of the DACL?". A non-dominant caller — one whose integrity is lower than the object's — has certain rights pre-decided as denied, before the DACL is even looked at.

The integrity axis is independent of identity. Two threads, same user, can run at different integrity levels and see different effective access. An interactive shell at Medium and an elevated session at High are the same person, separated by integrity. MIC enforces that separation.

MIC fires in step 5 of the access check pipeline — pre-DACL. Its decisions are immutable from that point. The DACL walk, the restricted-token pass, none of them can undo a MIC denial.

The integrity levels #

In practice there are five standard integrity levels, strictly ordered — treat integrity as an enum even though, technically, it is not one (see below). These five are the levels anyone normally works with (canonical value catalog: Other constants):

The comparison is the obvious one: Untrusted < Low < Medium < High < System. A caller dominates an object if the caller's integrity level is at least the object's level. Otherwise the caller is non-dominant and MIC's policy bits decide what they cannot do.

Technically, though, the level is not an enum. An integrity level is simply the single sub-authority of an S-1-16 mandatory-label SID, read as an unsigned integer, and levels are compared numerically. Any S-1-16-<n> SID with exactly one sub-authority is a valid level; only a SID with the wrong identifier authority (not S-1-16) or more than one sub-authority is malformed and rejected. The kernel does not check a label SID against a hardcoded list — an unusual value is interpreted purely by its numeric position, and the five standard RIDs are spaced by 4096 to leave room between them. This mostly matters for Windows interop, where non-standard levels appear: medium-plus (S-1-16-8448) sits just above Medium, and protected (S-1-16-20480) sits above System. Treat the five named levels as the working model; just don't assume they are the only values a label can carry.

Where the object's label lives #

An object's mandatory integrity label is in its SACL, as a SYSTEM_MANDATORY_LABEL_ACE. The ACE has:

• A SID from the integrity namespace (an S-1-16 SID with one sub-authority — normally one of the five above, occasionally a non-standard level such as medium-plus or protected).
• A mask containing the MIC policy bits.

When the access check looks at an SD, it scans the SACL for SYSTEM_MANDATORY_LABEL_ACE entries that are not inherit-only. The first such ACE is the object's effective label. If there is none, the object's effective label is Medium with NO_WRITE_UP — that is the default for an unlabelled object.

The Medium-with-NO_WRITE_UP default exists to protect default objects from lower-integrity callers without requiring every object to carry an explicit label. An unlabelled file on a standard filesystem is automatically protected against writes from a Low-integrity sandboxed process; the sandbox cannot scribble on system data even though no one explicitly marked the data with a label.

The SACL ACE also lives there for a reason: changing the integrity label is a privileged operation (gated by SeRelabelPrivilege for label-raising and by the standard SACL access rule for label-lowering). Stored as a SACL ACE, the label is automatically under SACL access control — the owner of an object cannot lower its integrity label without SeSecurityPrivilege or SeRestorePrivilege. This is exactly the right gate; a user should not be able to weaken the protections on their object just because they own it.

The MIC policy bits #

The mask of a SYSTEM_MANDATORY_LABEL_ACE contains MIC policy bits that say what non-dominant callers cannot do (canonical values: ACE types and flags):