authd

The authentication subsystem is built from a privileged broker and one or more unprivileged principal sources.

§2.1.1 authd (the broker)

authd is the authentication broker. It is signed at TCB level and runs PIP-protected. Its responsibilities are:

• Own the client-facing socket and accept logon and source-transparent requests (§6.1, §6.3).
• Route each request to the correct principal source (§2.2).
• Apply system policy after a source verifies a principal — group merge, privilege assignment, the logon-rights gate, integrity level, and token shaping (§5.2).
• Mint logon sessions and tokens via the KACS syscalls (§5.3).

authd MUST hold SeTcbPrivilege and SeCreateTokenPrivilege. authd MUST be the only userspace process that calls kacs_create_logon_session, kacs_create_token, and kacs_destroy_empty_logon_session in normal operation. authd MUST NOT store accounts. authd MUST NOT persist credential material, stored verifiers, or any reversible secret; any transient credential it handles is subject to §6.2.5.

authd does own one persistent store: the idmap (§3.6) — the SID↔id projection cache plus the authoritative id assignments for ephemeral, non-directory SIDs (service SIDs, virtual and orphan identities). The idmap holds neither accounts nor secrets, so the prohibitions above are unaffected, and it is low-criticality (rebuildable from the sources).

§2.1.2 lpsd (the local principal source)

lpsd is the Local Principal Store: a SQLite-backed database of the local users, groups, and credentials of a standalone system (§3). lpsd is the reference principal source and the local analogue of a domain directory.

lpsd MUST NOT mint tokens or sessions and does not require SeCreateTokenPrivilege or SeTcbPrivilege. lpsd is, in the token-minting sense, "just a database with a protocol." It is nonetheless security-critical: it is the sole holder of the system's password verifiers, and §3.5 and §6.1 constrain its protection accordingly.

lpsd exposes two interfaces on two sockets (§6.1):

• a verify/resolve interface, callable only by authd, that authenticates a principal and returns a resolved principal (§4); and
• an administration interface, gated by an account-admin privilege, for the source-shaped account operations (§7.2).

§2.1.3 Principal sources and the structural role

A principal source is any process that authoritatively verifies credentials for, and resolves the identity of, a set of principals. lpsd is one source; the deferred domain source adpsd is another, occupying the same structural role behind the broker.

All sources MUST answer the same source-neutral contract: the verify/resolve request and the resolved-principal response of §4. The broker treats every source identically and MUST NOT branch its policy or minting logic on which source answered. A source's internal design (storage engine, credential format, namespace) is private to it and is not constrained by this contract — only the resolved principal it returns is.

§2.1.4 Built-in and well-known principals

Well-known principals (SYSTEM S-1-5-18, Anonymous S-1-5-7, Everyone, Authenticated Users, LocalService, NetworkService, the S-1-5-32 BUILTIN aliases, and so on) are defined by PSD-004 and a static catalogue. They are NOT stored in any source. authd resolves them from the static catalogue, not by querying a source.

Two boundaries govern the subsystem: the seam between a source and the broker (what each side is authoritative for), and the routing rule (which side of the broker a given operation flows through).

§2.2.1 The source/broker seam

The seam partitions authority between a principal source and the broker. It is not a matter of preference: it is dictated by how a domain directory works, so that lpsd and a future AD source can be interchangeable.

A source MUST be authoritative for:

• Credential verification. The stored verifier and its format live in the source and are checked in the source. A verifier MUST NOT cross the seam.
• Account state. Whether an account is disabled, locked, or expired is enforced by the source during verification.
• The principal's intrinsic identity: its SID, and its group memberships expanded within the source's own namespace.
• Source-native claims and account attributes.

The broker (authd) MUST be authoritative for:

• Merging group contributions across sources (e.g. local groups that contain a domain principal — §5.2).
• Privilege and user-rights assignment — local/system policy that applies in both the local and domain cases.
• The logon-type rights gate — whether a principal may perform this logon type on this machine (§5.2).
• Integrity level determination and token shaping.
• All KACS session and token minting (§5.3).

§2.2.1.1 The group-expansion guardrail

Group-membership expansion MUST remain in the source and MUST NOT be performed by the broker. lpsd walks its own membership graph (§3.2); a domain source obtains an already-expanded, signed membership set from its directory. The broker re-deriving group membership would be both expensive and incompatible with how a directory federates trust, so it is forbidden. The broker only merges the membership sets that sources return; it never computes them.

§2.2.2 The routing rule

Whether an operation passes through the broker or goes directly to a source is decided by one criterion: source transparency.

• Source-transparent operations — operations that MUST behave identically regardless of which source backs the principal — go through authd, which forwards them to the correct source. These are: authentication (Logon), ChangePassword, and self-service operations on the caller's own principal. A caller MUST be able to perform these without knowing whether it is a local or a domain principal.
• Source-shaped operations — operations whose form legitimately differs between a flat local store and a directory — go directly to a source. These are account and group administration (create, modify, delete users and groups; manage membership) and policy management. Forcing these through a common broker surface would misrepresent backends that genuinely differ.

Routing to a source (whether by the broker for a transparent operation, or by an administration client for a source-shaped one) is determined by the principal's namespace: a bare or machine-qualified name routes to lpsd; a domain-qualified name routes to the domain source. Administration clients perform this routing through a shared client library so the rule is implemented once.

§2.2.3 Principal-name grammar

authd parses the principal name to choose a source and namespace. Three forms are accepted; the qualifier is matched case-insensitively (folded per §3.5), and the bare form is the default:

• Down-level QUALIFIER\name — MACHINE\name (the local machine name) and a bare name resolve to the local source (lpsd); a domain QUALIFIER resolves to that domain's source.
• UPN name@SUFFIX — the local machine suffix resolves to lpsd; a domain suffix resolves to that domain's source.
• Bare name — resolves to the local source.

A name MUST NOT contain both \ and @; a name with both, or an empty name or qualifier, is INVALID_REQUEST (§6.4). A bare name always resolves to the local source; an unqualified name is never broadcast to multiple registered sources (§6.1).

§2.2.4 Audit

Because identity use (logon) is brokered by authd while identity change (administration) is performed at a source, audit MUST be centralised at the KMES sink (PSD-003), not at a single emitter. authd emits logon and session events; a source emits account-change events; both target the same audit pipeline with a common schema, yielding one audit stream. No daemon is required to proxy another's audit.

lpsd is a flat, RID-keyed store. It holds three kinds of entity: the domain object, users, and groups. It is not a directory: it has no hierarchy of containers, no distinguished names, and no replication metadata.

§3.1.1 The domain object

lpsd holds exactly one domain object, the root of the local namespace. It records:

• machine_sid — the S-1-5-21-X-Y-Z identifier that is the prefix of every local principal's SID. Generated once per installed instance (§7.1); its three sub-authorities are drawn from a seeded CSPRNG — generation MUST block on available entropy (e.g. getrandom without GRND_NONBLOCK) — each non-zero (§9). The same seeded-CSPRNG requirement applies to object_guids and argon2id salts.
• rid_counter — the next RID to allocate for a new principal; RIDs are allocated monotonically and are never reused (§9).
• the password and lockout policy — minimum length, complexity, history depth, maximum age, lockout threshold, and lockout duration (§3.4).
• creation metadata.

The domain object is the analogue of the SAM/AD "domain" object. There is exactly one; lpsd MUST refuse to operate without it (§7.1, §7.3).

§3.1.2 Users and groups

Users are the account records (§3.2). Groups are local security groups (aliases) with a membership list (§3.2). Both are security principals identified by a SID.

Computer/machine accounts and managed service accounts are domain-join and later concerns and are out of scope for this version (§8).

§3.1.3 The SID namespace

A standalone machine's namespace root is its machine SID (S-1-5-21-X-Y-Z). This is structurally identical to a domain SID: a local principal's SID is machine_sid + a relative identifier (RID).

lpsd MUST allocate RIDs for new principals from rid_counter, starting at 1000. RIDs below 1000 are reserved for well-known and built-in principals and MUST follow the established conventions:

The S-1-5-32 BUILTIN aliases (Administrators 544, Users 545, and the rest defined by PSD-004) are represented in lpsd as group entities so that membership can be recorded against them, but their SIDs are the fixed well-known values, not machine_sid-relative.

§3.1.4 SID generalisation

A shipped system image MUST NOT contain a machine SID or any machine_sid-relative principal. The machine SID is generated on first boot, per installed instance (§7.1). This avoids SID collisions across clones of the same image, which would break local-principal identity and (later) domain trust.

This section defines the fields of the user and group records. Storage encoding is §3.5; the credential portion of the user record is §3.3.

§3.2.1 The user record

A user record is a superset of the source-provided columns of the resolved principal (§4); it adds the material that does not cross the seam (credentials and raw memberships) and bookkeeping.

The user SID, object_guid, and rid are immutable once assigned. The sam_account_name MAY be changed; object_guid is the stable handle that makes such a change safe.

§3.2.2 The group record

§3.2.3 Membership

Membership MUST be stored as forward member links on the group, not as back-links on principals. member is the single source of truth. A member entry MAY reference:

• a local user,
• another local group (nested membership), or
• a foreign SID (e.g. a domain principal placed into a local group).

lpsd computes a principal's expanded group set at resolution time (§4, §5.1) by walking the member graph transitively. The walk MUST detect and break cycles (e.g. group A a member of group B and B a member of A) and MUST terminate. The result MUST be the full transitive closure and MUST be identical regardless of traversal order; breaking a cycle MUST NOT drop any principal reachable along it. Foreign-SID members are included as-is (lpsd does not resolve them). Each expanded group carries SE_GROUP_MANDATORY | SE_GROUP_ENABLED | SE_GROUP_ENABLED_BY_DEFAULT (PSD-004).

A user's credentials field is a set of typed credential factors. This is structurally the multi-valued credential store of a directory; its contents are defined here and are private to lpsd (they never cross the seam — §2.2).

§3.3.1 Credential factors

Each credential factor is:

{ type, version, params, public_part, secret_part }

• type — the factor kind. This version defines password. Later versions MAY add webauthn (passkey), x509 (smartcard), and recovery_code; they reuse this shape and require no new machinery.
• version — the factor's format version, allowing the verifier scheme to evolve.
• params — verifier parameters (for password, the argon2id cost parameters and salt).
• public_part — non-secret material (e.g. a passkey credential id and public key); empty for password.
• secret_part — the stored verifier; a wrappable blob (§3.5).

A principal MAY hold more than one factor. For this version, exactly the password factor participates in Logon.

§3.3.2 The password factor

The password factor's verifier MUST be an argon2id hash:

{ type: password, params: { m, t, p, salt }, secret_part: argon2id(params, password) }

lpsd MUST NOT store the NT hash, a Kerberos key, or any reversible or unsalted password representation. The choice of argon2id (rather than the Windows NT hash) is permitted precisely because the verifier never crosses the seam: the broker is credential-agnostic, so the source's verifier scheme is its own concern.

The default argon2id cost parameters and the salt and output lengths are given in §9; lpsd MUST use the current policy parameters for new verifiers, and the dummy verifier of the enumeration-resistance path (below) MUST use those same parameters.

§3.3.3 Verification

On a verify request (§5.1), lpsd MUST:

1. select the password factor for the named principal;
2. compute argon2id(params, presented_password) and compare it to secret_part in constant time;
3. on success, optionally re-wrap the verifier if params are older than the current policy (lazy upgrade — §3.4); and
4. on failure, apply the lockout accounting of §3.4.

lpsd MUST reject an empty or absent presented credential outright; the password-not-required account flag (§9) MUST NOT permit a credential-free logon in this version (lpsd refuses it, or — only where a deployment explicitly opts in — loudly audits).

The transient credential MUST be zeroized in lpsd immediately after the comparison and MUST NOT be logged or persisted.

§3.3.4 Resistance to user enumeration

When the named principal does not exist, lpsd MUST still perform an argon2id computation — over the presented credential against a real, precomputed dummy verifier that uses the current policy parameters (recomputed whenever those parameters change) — before returning failure, so that the response time of "no such principal" is indistinguishable from "wrong password." The failure returned to the broker MUST be the same in both cases (§5.1).

The password and lockout policy governs how credentials may be set and how repeated failures are handled. The policy is held on the domain object (§3.1); this section defines its fields and where they are enforced. There is one policy per local namespace.

§3.4.1 Policy fields

The domain object's policy (§3.1) MUST define at least:

• minimum length and complexity requirements for a new password;
• history depth — how many prior verifiers are retained and refused on change (reuse prevention, via the pw_history records of §3.2);
• maximum age — after which a password is expired and MUST be changed before a token is minted (the must_change_password flow of §5.1);
• lockout threshold — the number of consecutive failed verifications that locks an account; and
• lockout duration — how long a locked account stays locked.

The normative default value for every field above is given in §9. For this version there are no composition rules — strength is length- and breach-list-based only — and the lockout counter resets on a successful verification or once the lockout duration has elapsed.

§3.4.2 Enforcement points

Policy is enforced at two points.

At set-password time (administrative SetPassword or self-service ChangePassword — §7.2). lpsd MUST reject (POLICY_VIOLATION) a new password that violates the length/complexity requirements, matches any retained pw_history verifier within the history depth, or appears in the deployment's configured common/breached-password list (which MAY be empty). On acceptance, lpsd records the new verifier, appends the previous one to pw_history (evicting entries beyond the depth), and stamps pw_last_set.

At verify time (the logon path — §5.1). lpsd MUST:

• treat a password older than the maximum age as expired and return must_change_password (§5.1) rather than ok;
• refuse verification for an account whose lockout_until is in the future, returning denied (§5.1); and
• maintain the lockout accounting: on a failed verification, increment bad_pw_count and stamp last_bad_pw_time; when bad_pw_count reaches the lockout threshold, set lockout_until to the current time plus the lockout duration; on a successful verification, reset bad_pw_count and clear lockout_until.

The built-in Administrator (RID 500) and any account on the recovery path MUST be exempt from remote-induced lockout, so an attacker cannot deny the recovery surface by failing logons against it (§8.2); local-console attempts MAY still count.

§3.4.3 argon2id parameters and lazy upgrade

The argon2id cost parameters (§3.3) are themselves policy. When the policy's parameters are stronger than those recorded in a stored verifier, lpsd SHOULD lazily re-wrap the verifier — recompute it with the current parameters — on the next successful verification (§5.1), so verifiers strengthen over time without forcing a password reset. Re-wrap MUST NOT change the password; it changes only the stored representation.

§3.5.1 Engine

lpsd MUST store its data in a transactional, crash-safe, single-file database. lpsd is specified against SQLite in WAL mode: WAL provides the atomic, durable writes the logon path needs (lockout counters and last-logon are written during authentication — §5.1), and SQLite's online backup, PRAGMA integrity_check, and dump facilities back the recovery tooling of §7.3.

The engine is private to lpsd and does not cross the seam (§2.2); the choice does not affect interoperability with other sources.

CREATE TABLE domain (
    id              INTEGER PRIMARY KEY CHECK (id = 0),
    machine_sid     BLOB NOT NULL,
    rid_counter     INTEGER NOT NULL,
    policy          BLOB NOT NULL,        -- password/lockout policy
    created_at      INTEGER NOT NULL
);
CREATE TABLE users (
    rid             INTEGER PRIMARY KEY,
    object_guid     BLOB NOT NULL UNIQUE,
    name            TEXT NOT NULL,
    name_folded     TEXT NOT NULL UNIQUE,
    display_name    TEXT,
    upn             TEXT,
    account_flags   INTEGER NOT NULL,
    primary_group_rid INTEGER NOT NULL,
    pw_last_set     INTEGER,
    last_logon      INTEGER,
    account_expires INTEGER,              -- NULL = never
    bad_pw_count    INTEGER NOT NULL DEFAULT 0,
    last_bad_pw_time INTEGER,
    lockout_until   INTEGER,              -- NULL = not locked
    posix_uid       INTEGER NOT NULL,
    posix_gid       INTEGER NOT NULL,
    created_at      INTEGER NOT NULL,
    modified_at     INTEGER NOT NULL,
    version         INTEGER NOT NULL
);
CREATE TABLE credentials (
    rid             INTEGER NOT NULL REFERENCES users(rid),
    type            INTEGER NOT NULL,
    version         INTEGER NOT NULL,
    params          BLOB,
    public_part     BLOB,
    secret_part     BLOB,                 -- wrappable (see below)
    PRIMARY KEY (rid, type)
);
CREATE TABLE pw_history ( rid INTEGER, seq INTEGER, verifier BLOB, PRIMARY KEY (rid, seq) );
CREATE TABLE groups (
    rid             INTEGER PRIMARY KEY,  -- or well-known SID for BUILTIN
    sid             BLOB NOT NULL UNIQUE,
    object_guid     BLOB NOT NULL UNIQUE,
    name            TEXT NOT NULL,
    name_folded     TEXT NOT NULL UNIQUE,
    group_type      INTEGER NOT NULL,
    posix_gid       INTEGER NOT NULL,
    created_at INTEGER, modified_at INTEGER, version INTEGER
);
CREATE TABLE members ( group_sid BLOB NOT NULL, member_sid BLOB NOT NULL, PRIMARY KEY (group_sid, member_sid) );
CREATE TABLE claims ( rid INTEGER, name TEXT, value BLOB, PRIMARY KEY (rid, name) );
CREATE TABLE schema_version ( version INTEGER NOT NULL );

§3.5.2 At-rest protection

A secret_part MUST be stored as a wrappable blob carrying a protection descriptor:

{ scheme, key_id, ciphertext_or_plaintext }

This version defines two schemes and a staged adoption:

• scheme = none (this version). The verifier is stored in the clear. At-rest protection is provided by full-disk encryption of the volume holding the database. lpsd MUST NOT implement a SYSKEY-style local-key obfuscation: a key stored beside its ciphertext adds no real protection and is forbidden as security theatre.
• scheme = tpm-sealed (deferred — §8). The verifier is encrypted under a key sealed to the platform's measured boot, optionally with a server-side pepper mixed into argon2id. Adopting it is a re-wrap pass over existing rows, requiring no schema change.

The wrappable-blob shape is mandated now so the later transition is a data migration, not a format change.

§3.5.3 The database file and volume

The database MUST reside on a writable, security-descriptor-bearing volume — not on a read-only or SD-less root filesystem (per the KACS mount-policy requirements of PSD-004). lpsd MUST create the database file with a tight SD granting full access to SYSTEM, the Administrators group, and lpsd's own identity, and denying all others, since the file holds the system's verifiers.

§3.5.4 Secret memory hygiene

lpsd MUST mlock buffers holding transient credentials and stored verifiers, MUST zeroize them after use via a pinned/zeroizing buffer (not a plain heap allocation that may be reallocated or moved), and MUST disable core dumps (PR_SET_DUMPABLE = 0) and restrict ptrace-attach to the TCB. authd MUST do the same for its transient-credential buffers (§6.2.5). This complements, and does not replace, the at-rest protection above.

Every principal that can own or access a Linux-visible object projects to a single POSIX integer id. The projection exists only for Linux application and filesystem compatibility: uid/gid carry no authority in Peios — KACS decides access by SID (PSD-004). The id is the value Linux apps see via getuid()/stat() and the owner stored on Linux filesystems; the compatibility layer maps an inbound id back to a SID to apply KACS. Because ownership is stored as a SID in the security descriptor, the id is a cosmetic projection — the authoritative owner is always the SID.

§3.6.1 The unified id invariant

The id space is unified: an integer identifies at most one principal and is used as a uid xor a gid — never both, and never for two different principals. A single rid_counter (§3.1) makes every base + rid id unique across users and groups, and the well-known and allocated assignments are likewise disjoint. An implementation MUST NOT maintain separate uid and gid counters. The benefit is context-free reverse mapping: an integer resolves to one SID regardless of the slot it appeared in. (This matches a Samba autorid member's unified-xid model.) Peios therefore does not use Linux user-private-groups: a user's primary gid is its real primary group's id, not a copy of its uid.

§3.6.2 Three allocators, one address space

The bands of §9 are a shared allocation contract. Three allocators assign ids within it, each authoritative for, and storing, its own part; they never collide because each draws only from its assigned bands:

• lpsd — local accounts and groups. lpsd assigns the id in the local band at creation and stores it on the principal record (posix_uid/posix_gid, §3.5). lpsd is the source of truth for local principals and returns their ids in the resolved principal (§4).
• adpsd / AD (deferred — §8) — domain principals. The directory is authoritative (an explicit uidNumber-style attribute, or an autorid-style per-domain computation); adpsd returns the id.
• authd — the ephemeral / sourceless SIDs that are not directory accounts: service SIDs (S-1-5-80-…), virtual identities, and orphan/foreign SIDs. authd allocates these next-free in their bands and persists them in its idmap store (§2.1). SIDs on the no-id list (§9) are not object-owning principals and are never allocated an id — they are omitted from the projection entirely. authd also caches the mappings the directories report, so its idmap is the single point the compatibility layer queries to reverse-resolve any id.
• well-known SIDs are computed by arithmetic (§9), need no storage, and are seeded into the idmap on demand.

Assignment happens at a SID's first projection (commonly token-mint, also file-ownership assignment), performed by the owning allocator, and is frozen thereafter. Forward (SID → id) and reverse (id → SID) are both served from authd's idmap; on a miss in a computable band the id is derived arithmetically and backfilled.

authd's idmap is low-criticality: the cached directory mappings rebuild from the directories, and a lost ephemeral assignment only causes a service's files to show a different cosmetic uid (the SID-native owner is unchanged). It holds no accounts and no secrets (§2.1).

Reverse-resolution is not cosmetic on the setuid-bit transition path (PSD-004 — a setuid binary's id → SID lookup decides which principal it becomes): for any id that can be a setuid target, the mapping MUST be authoritative and stable. The 0xFFFFFFFF wire sentinel (§6.4) means "the source assigns no id"; authd MUST resolve it to a real allocated id before minting — 0xFFFFFFFF MUST NOT appear in a token spec or be treated as a literal uid/gid (it equals (uid_t)-1, the "no-change" sentinel).

§3.6.3 Bands and reverse mapping

The full band layout is §9. Reverse-resolution is a range check:

All ids MUST be below 2³¹ (2,147,483,648). Within a namespace, rid MUST be < 5,000,000 (the slice width). 65534 is the overflow/unmapped sentinel (S-1-0-0); 65535 is reserved. Any id with no assignment — a reserved hole (e.g. 18) or an unallocated gap — also reverse-maps to S-1-0-0. A namespace whose slice would reach 2³¹ MUST be refused at join (domain support is deferred — §8).

A principal's stored projection is a single id. Supplementary gids are not stored — they are the projection of the principal's expanded group set (§3.2, §5.2) to gids at token-mint time.

The resolved principal is the record a source returns to the broker on successful verification. It is the single source-neutral contract of the subsystem: every source MUST produce it, and the broker MUST accept it identically regardless of source (§2.1).

§4.1.1 Design: PAC-isomorphic

The contract is modelled on the Windows PAC (PAC_LOGON_INFO plus the claims blobs): the same authorization information a directory hands a broker for token assembly. It is information-isomorphic to the PAC but is a clean, versioned format, not the literal MS-PAC NDR encoding and without the PAC's KDC/server signatures. The local source/broker hop is a trusted IPC (§6.2), so no on-wire signature is needed. A domain source MUST verify a real PAC's signatures and then translate the verified contents into this format; lpsd synthesises the format directly from its store.

§4.1.2 Fields

A source MUST populate the following on success.

A source MUST NOT include credential material or any verifier in the resolved principal. A source MUST NOT include the logon SID: the kernel injects it at mint (§5.3). The on-wire encoding of the resolved-principal record — field order, widths, and how denied(reason) carries its audit-only reason — is defined normatively in §6.4.

§4.1.3 What the broker adds

The resolved principal is the source's half of the eventual token. The broker adds the rest in the policy phase (§5.2) and never expects the source to supply it: merged local groups, the privilege set, the integrity level, token shaping, and the auth_id linking the token to the session it creates. The clean division is "who you are and what you belong to" (source) versus "what that entitles you to on this machine" (broker).

A logon turns a presented credential into a token. This section defines the end-to-end flow for an interactive local password logon — the core case. The policy phase is detailed in §5.2 and the mint in §5.3.

§5.1.1 Sequence

1. A client (e.g. a login frontend) collects the principal name and password and sends a Logon request to authd (§6.3), naming the logon type (Interactive).
2. authd captures the caller's peer token (§6.2) for authorization and audit, and routes by the principal's namespace (§2.2) to a source.
3. authd forwards the principal name and the transient credential, unmodified, to the source's verify/resolve interface (§6.1). authd does not hash, salt, or otherwise transform the credential (credential pass-through — §6.2.5).
4. The source verifies and resolves (below) and returns a resolved principal (§4) with a tri-valued status.
5. On status = ok, authd runs the policy phase (§5.2), then mints the session and token (§5.3), and returns the token to the client (§6.3).
6. authd emits a logon audit event (§5.1 below) for every outcome.

§5.1.2 What the source does (verify and resolve)

On a verify/resolve request the source MUST, in order:

1. Look up the named principal. If absent, perform the dummy verification of §3.3 and return the uniform denied of step 4 below.
2. Check account state — disabled, locked (lockout_until), expired (account_expires). If any fails, return denied(reason).
3. Verify the credential (argon2id, constant-time — §3.3).
4. Update logon-path state (a write): on failure, increment bad_pw_count, stamp last_bad_pw_time, and set lockout_until if the threshold is reached; on success, reset bad_pw_count, clear lockout_until, stamp last-logon, and optionally re-wrap the verifier (§3.4).
5. Resolve identity — expand groups within the namespace (cycle-guarded — §3.2), gather claims, flags, primary group, and the POSIX projection, and build the resolved principal (§4).

§5.1.3 Check precedence and atomicity

When more than one condition applies, the source MUST resolve them in this precedence (first match wins): account locked > account disabled or account-expired > wrong credential > password expired (must_change_password). Thus a wrong credential on an otherwise-valid account is denied, while a correct credential on an account whose password has exceeded its maximum age — and which is not locked, disabled, or account-expired — is must_change_password. A correct credential MUST reset lockout state (step 4) even when the result is must_change_password.

All denied paths — including those decided by account state before the credential is checked — MUST be timing-equalized per §3.3: where the real verification was skipped, the source computes the argon2id dummy over the presented credential and then zeroizes it, so that neither account existence nor account state is observable via timing.

The logon-path state update (step 4) MUST be a single atomic transaction (§3.5) committed before the source returns, so that concurrent failed verifications cannot lose increments and a returned denied reflects committed lockout state.

§5.1.4 Tri-valued status

The source's status MUST be one of:

• ok — verified; the resolved principal is complete.
• denied(reason) — not verified, or account state forbids logon. The reason is for audit and frontends; the failure presented to the caller MUST NOT distinguish "no such principal" from "wrong password" (§3.3).
• must_change_password — the credential is valid but the password is expired and must be changed. The broker MUST NOT mint a token for this status. The client must complete a ChangePassword (§7.2) — which the broker forwards source-transparently (§2.2) — and then retry the logon.

§5.1.5 Timing and enumeration

The source MUST equalise the timing of the denied paths so that account existence is not observable (§3.3). The broker MUST NOT add a side channel (e.g. a different error for unknown principal) of its own.

§5.1.6 Audit

authd MUST emit a KMES audit event for every logon attempt, carrying at least: the target principal, the logon type, the source, the captured caller identity, the outcome, and (on success) the session id. The event MUST NOT contain the cleartext credential.

After a source returns status = ok, and before minting, authd runs the policy phase: it layers local/system policy onto the source's resolved principal (§4). The policy phase MAY still deny the logon even though the credential was valid.

§5.2.1 The assignment model

Privileges and logon rights are assigned to SIDs (users or, far more commonly, groups) by a machine-local rights-assignment policy — the analogue of Windows User Rights Assignment, applied by authd (the seam of §2.2 keeps assignment in the broker, not the source). Two rules define how an assignment becomes a token property:

• Privileges accumulate by union. A token's present privileges are the union of the privileges assigned to every SID in the token — the user SID plus all group SIDs after the merge of step 2 below. There is no "deny privilege": a privilege is present iff it is assigned to some SID present, otherwise absent.
• Logon rights are allow/deny, deny overriding. Each logon type has an allow right and a deny right. A principal may perform a logon type iff some SID in its set holds the allow right and no SID in its set holds the deny right. Deny overrides allow.

The rights-assignment data is machine-local system policy; populating and editing that store is tied to the deferred policy-distribution work (§8). Until it is wired, authd MUST apply the default assignment table of §9 (the shipped defaults, analogous to a Windows security template) and MUST mark tokens minted under it as default-derived in audit. The default table is a stub to be replaced by the real store; the union and deny-override rules above are permanent.

Reserved privileges. SeCreateTokenPrivilege, SeTcbPrivilege, and SeAssignPrimaryTokenPrivilege MUST NOT appear in any rights-assignment (default or otherwise) — they are held only by authd and peinit via their own identity, preserving "authd is the sole minter" (§2.1). SeLoadDriverPrivilege is likewise reserved and peinit-exclusive: PSD-004 MUST-strips it from every non-peinit token, so it appears in no assignment (not even SYSTEM's), and driver loading routes through peinit.

§5.2.2 Validating the resolved principal

The kernel mints whatever authd assembles — it checks structure, not authority (PSD-004) — so authd is the authorization boundary and MUST NOT blindly trust a source. Before the steps below, authd MUST validate the resolved principal (§4):

• The user_sid MUST lie within the answering source's namespace — for lpsd, machine_sid-relative; for a domain source, that domain's SID. authd MUST reject (and audit) a resolved principal whose user_sid is a well-known or built-in SID (SYSTEM S-1-5-18, any S-1-5-32 alias, …) or belongs to a different source. A source can thus never assert SYSTEM or Administrators as the principal it authenticated.
• The source's group SIDs are accepted only as memberships. authd derives privileges solely from its own rights-assignment table keyed by SID (the union rule above), never from any field of the resolved principal — so a malicious membership cannot inject a reserved (or any) privilege.
• authd SHOULD bound the group count a source returns; the kernel's 1024 limit is the hard ceiling (§5.3).

This validation is what contains a compromised source: it can mis-state its own principals, but cannot mint SYSTEM, cross namespaces, or inject privileges.

§5.2.3 Steps

authd MUST perform these steps in order:

1. Logon-type rights gate. Evaluate the allow/deny logon rights (above, per the table in §9) for the principal's SID set against this logon type. If not permitted, the logon fails with LOGON_TYPE_DENIED (§6.4) — distinct from a credential failure, because it occurs only after the credential is already valid — and authd emits a denied audit event.
2. Merge groups. Query lpsd for the local groups that contain any of the principal's SIDs (including a domain principal's SIDs — §3.2) and merge them into the group set. Then add the implicit groups for this logon type per §9 (Everyone, Authenticated Users, Local, the logon-type SID such as Interactive S-1-5-4, This Organization S-1-5-15), each with the SE_GROUP_* attributes given there. The kernel does NOT add these; authd MUST (PSD-004 §4.4).
3. Privilege assignment. Compute the token's present privileges as the union over the full SID set, per the default assignment table (§9). Set each present privilege's enabled-state per §9 (only SeChangeNotifyPrivilege enabled by default; all others present but disabled).
4. Integrity level. Determine the integrity level by the predicate of §9 (first match wins): user SID = SYSTEM → System; carries S-1-5-32-544 → High; user SID = local Guest (RID 501) or Anonymous (S-1-5-7) → Low; otherwise Medium.
5. Token shaping. For this version, a single primary token; linked/filtered elevation pairs are deferred (§8).
6. Assemble the token spec (§5.3): user SID, the merged-and-implicit group set with attributes, the union privilege set with enabled-states, integrity level, primary group, default DACL, owner, claims, mandatory policy, and the POSIX projection. The assembled group set MUST be sorted in ascending binary-SID order (§6.4) before minting, and owner_sid_index / primary_group_index (PSD-004) index into that sorted array. The logon SID is NOT supplied; the kernel injects it (§5.3).

With the token spec assembled (§5.2), authd mints the logon session and the token via the KACS syscalls of PSD-004. Only authd performs these calls (§2.1).

§5.3.1 Order: session before token

authd MUST create the session before the token, because the token references the session:

1. kacs_create_logon_session with { logon_type, auth_package, user_sid } (lpsd's auth_package is "Peios.Local" — §9). This requires SeTcbPrivilege. The kernel allocates a session id (LUID), derives the logon SID, and returns the session id. The session begins at token-reference-count zero, protected by the kernel's creation grace period (PSD-004).
2. authd sets the token spec's auth_id to the new session id.
3. kacs_create_token with the assembled spec. This requires SeCreateTokenPrivilege. The kernel validates the spec, injects the logon SID into the group list, assigns the token id, and returns a token fd. The first token referencing the session takes its reference count positive, ending the grace period.

authd MUST NOT supply the logon SID in the token spec; the kernel injects it.

§5.3.2 Rollback

If kacs_create_token fails after kacs_create_logon_session has succeeded, authd MUST roll the session back with kacs_destroy_empty_logon_session so that no empty session is leaked. authd MUST treat the logon as failed and audit it accordingly.

§5.3.3 Token spec defaults

Unless overridden by the resolved principal or policy, authd MUST set the following on the token spec (values consolidated in §9): default_dacl = ACCESS_ALLOWED ACEs (each AceFlags = 0) in the order owner, SYSTEM, then Administrators — the last only when the token carries S-1-5-32-544 — each granting GENERIC_ALL; the DACL sets only SE_DACL_PRESENT (no other control flags, notably not SE_DACL_PROTECTED); owner = the user SID; primary_group from the principal's primary_group_rid; and mandatory_policy = NO_WRITE_UP. The privilege set and its enabled-states come from §5.2, the integrity level from §5.2/§9, and the POSIX projection from the idmap (§3.6): projected_uid = the principal's id; projected_gid = the primary group's id; and projected_supplementary_gids = the projection to ids of the token's group SIDs only — the primary group, the resolved principal's groups, and the local and implicit groups authd added in §5.2 step 2 — and never the user SID. That list is de-duplicated, sorted ascending by id, includes the primary group's id, and omits any SID on the no-id list (§9) (no-id SIDs never receive a fallback id). If the assembled group set — the token's group SIDs excluding the kernel-injected logon SID — exceeds 1023 (PSD-004's 1024-entry limit less the kernel's reserved logon-SID slot), authd MUST fail the logon with TOKEN_TOO_LARGE (§6.4) before calling kacs_create_logon_session (so no session is created or rolled back), and MUST NOT silently truncate it.

§5.3.4 Returning the token; the requester launches

authd MUST return the token to the client as a token fd passed over the client socket (SCM_RIGHTS), together with the session id and any advisory fields (e.g. must_change_password is handled earlier; a password-expiry warning MAY be returned alongside ok). The returned fd carries TOKEN_ALL_ACCESS (PSD-004); the requester MUST install it promptly, close its own copy, and MUST NOT pass it across a privilege boundary.

The requester, not authd, installs the token and launches: a login frontend installs the returned token as the primary token of the user's first process and execs it; peinit installs a service's token on the service it launches. authd MUST NOT launch processes itself. After handing off the fd, authd drops its own reference; the running process's attachment is what keeps the session alive.

§5.3.5 Session-scoped state

For a local password logon authd holds no per-session secret. authd MUST nonetheless subscribe to the logon-session-destroyed event (PSD-004) so that the uniform per-session cleanup hook exists; for a local logon the handler is effectively empty. (Domain sessions, which hold Kerberos tickets, are deferred — §8.)

The subsystem exposes three Unix-domain sockets. All three MUST be SOCK_SEQPACKET: this is required for the kernel peer-token capture (§6.2) — datagram and socketpair sockets yield no peer token — and it provides message framing and SCM_RIGHTS fd passing.

The connect-access column lists the allow-ACE SIDs; the exact security descriptor for each socket — allow-ACEs by SID, deny by absence — and for the /run/authd/sources/ directory is given in §9. Sockets are created so that access is governed by the SD, not by POSIX permission bits.

§6.1.1 The source registry

/run/authd/sources/ is a source registry: each principal source registers by creating its verify/resolve socket there. authd discovers the available sources by enumerating this directory and connects to each. A domain source registers as /run/authd/sources/adpsd.sock. Because authd connects out to whatever sockets appear here and then trusts the identities they resolve (§5.2), this channel MUST be protected in both directions:

• The directory's own SD (defined in §9) MUST restrict entry creation to the specific trusted source identities (e.g. only lpsd's service SID may create lpsd.sock), and socket creation MUST be exclusive so an impostor cannot pre-create or recreate a source's socket (e.g. in the window before the source starts or after it crashes).
• authd MUST authenticate every source it connects to: obtain the source socket's owner identity and verify it against an expected-identity allowlist (the mirror of the source checking the peer is authd), and refuse any source socket not owned by its expected identity.

Without the second control, a rogue process that won the race to create a source socket would become a source — minting arbitrary identities and harvesting every cleartext credential authd forwards (§6.2.5). The verify/resolve sockets MUST also be connectable only by authd (per-request peer-token check of §6.2). All of these are mandatory.

§6.1.2 Two-layer authorization

Access is enforced in two layers:

1. The connect SD on each socket (the table above) — coarse control over who may connect() at all.
2. Per-request authorization against the peer token (§6.2) — the fine-grained gate that actually decides each request (§6.3).

The per-request gate is the real enforcement; the connect SD is defence-in-depth. In particular, the verify/resolve interface MUST additionally check that the connected peer is authd, not rely on the connect SD alone.

The trust model answers "who may ask the subsystem for what." It rests on the kernel peer-token primitives of PSD-004, which let a server learn the token of the process that connected to it, race-free.

§6.2.1 Identifying the caller

On each connection, a server (authd, or a source/admin interface) MUST obtain the caller's identity with kacs_open_peer_token (PSD-004), which returns a token fd for the peer-identity snapshot captured at connect(). The returned token carries TOKEN_QUERY | TOKEN_IMPERSONATE. A server MUST treat -EACCES (no captured peer token — e.g. a datagram/socketpair socket) as a hard reject, and MUST NOT fall back to SO_PEERCRED/SCM_CREDENTIALS, which are forgeable.

A server MUST authorize each request against this peer token, never against identity claims carried in the request body.

The snapshot is captured at connect(), so it is immune to PID reuse. This immunity is load-bearing; PSD-004 §13.1 implies but does not yet normatively guarantee it, so PSD-010 takes it as an explicit dependency on KACS (to be asserted normatively there). A TCB client MUST NOT pass a live authd connection across a privilege boundary — doing so would make authd treat the channel as that TCB client (an fd-handoff confused deputy).

§6.2.2 The governing principle

authd holds TCB power and MUST use the minimum of it:

• authd uses its own (TCB) authority only to mint sessions and tokens.
• For work that must be bounded by the caller's rights (e.g. an identity query that should reveal only what the caller may see), authd MUST impersonate the caller with kacs_impersonate_peer (PSD-004), perform the work under the caller's identity, and then revert with kacs_revert. This prevents authd from acting as a confused deputy. All caller-bounded work MUST occur strictly between the impersonate and the revert, and authd MUST check the kacs_impersonate_peer result: if the kernel silently capped the level below IMPERSONATION, authd MUST fail the request rather than fall back to acting under its own TCB authority.

§6.2.3 Client-set impersonation level

A client MAY cap how far a server may impersonate it by calling kacs_set_impersonation_level before connect() (PSD-004; default IMPERSONATION). Servers MUST honour the cap the kernel enforces. (No Rust wrapper for this syscall exists yet; clients that need to cap the level will require one — see §8.)

§6.2.4 Local IPC is trusted

The source/broker hop and the admin hop are local IPC between kernel-authenticated endpoints; there is no network adversary on these paths. Accordingly the resolved principal carries no signature (§4) and the credential crosses in the clear (§6.2.5 below). This trust assumption is specific to the local sockets and does not extend to any future network hop, which a source handles internally (§8).

§6.2.5 Credential handling

For an interactive logon the cleartext password necessarily reaches authd (the client holds it and must get it to the verifier). authd MUST forward it unmodified to the source (credential pass-through — the source owns all hashing/derivation), MUST hold it in mlock'd memory, MUST zeroize it immediately after forwarding, and MUST NOT log or persist it. A challenge–response scheme, where used at all, belongs only to a source's remote hop (e.g. a domain source to its KDC), never to the local broker/source hop.

This section defines the request taxonomy and the authorization gate for each. Every gate is evaluated against the peer token (§6.2). Wire framing is §6.3 below.

§6.3.1 authd client requests (/run/authd.sock)

The dividing line is: credential-backed requests are gated by knowledge and are open; credential-less requests are gated by SeTcbPrivilege. This mirrors the Windows boundary between logon-with-credentials and acting as part of the TCB.

§6.3.2 Credential-backed Logon is open by design

Any peer that may connect to /run/authd.sock MAY attempt a Logon; authd MUST NOT require a special privilege to attempt one. Knowledge of the credential is the authorization, the resulting token's use is still gated by the kernel, and online guessing is bounded by lockout (§3.4), rate-limiting, and audit. An unprivileged caller that obtains a token via Logon cannot necessarily assign it as a process's primary token; the secondary-logon launch helper for that case is deferred (§8).

§6.3.3 Throttling

Per-account lockout (§3.4) bounds hammering of a single account but not password-spray (one guess each across many accounts), and the mandatory argon2id per attempt — including the dummy for unknown principals (§3.3) — makes unthrottled Logon a CPU/memory DoS on the source. authd MUST therefore throttle in addition to lockout:

• a per-caller (peer-SID) attempt budget and a global attempt budget over a sliding window; once a budget is exceeded authd returns RATE_LIMITED (§6.4) without calling the source (so no argon2id is spent);
• both budgets are policy, with the defaults in §9.

Throttling is the bound on spray, the argon2id DoS, and lockout-induced victim denial of service (§8.2).

§6.3.4 Source verify/resolve (/run/authd/sources/*.sock)

A single request — verify-and-resolve (§4, §5.1) — gated by the peer being authd. No other caller may use this interface.

§6.3.5 Wire framing (overview)

Client and verify/resolve messages are versioned, typed, binary (not JSON), consistent with the KACS wire formats and the PAC-isomorphic contract (§4). Each message is a self-delimiting SOCK_SEQPACKET datagram with an envelope { version, type, body }; responses carry { version, status, body } and MAY carry a token fd via SCM_RIGHTS. The exact byte layout of every message — the envelope, the type and status enums, and each body including the resolved-principal record — is defined normatively in §6.4.

This section defines the byte-level encoding of every message on the three sockets (§6.1). It is normative: two independent implementations MUST produce identical bytes for the same logical message, so that third-party clients, sources, and administration tools interoperate.

§6.4.1 Framing and primitives

• Every message is exactly one SOCK_SEQPACKET datagram. There is no stream framing; the datagram boundary delimits the message.
• All integers are unsigned little-endian unless stated. u8/u16/ u32/u64 denote width; i64 is a signed little-endian 64-bit value.
• Strings are encoded as [len: u16][bytes: UTF-8] (no NUL terminator). A length-prefixed string is written str.
• SIDs are encoded as [len: u16][sid: binary SID per PSD-004 §2]. A length-prefixed SID is written sid.
• Timestamps are i64 Unix nanoseconds; the sentinel -1 means "none"/"never".
• A token or other file descriptor is never in the datagram body; it is carried as ancillary data via SCM_RIGHTS (§6.1) and is described per message below.
• The total datagram length (12-byte envelope + body) MUST NOT exceed AUTHD_MSG_MAX = 65536 bytes; therefore body_len MUST equal datagram_length − 12 and MUST NOT exceed 65524. A datagram violating either MUST be rejected with INVALID_REQUEST (§6.4.4) without partial processing.

§6.4.2 Envelope

Every request begins with a fixed 12-byte header:

struct request_header {
    u32 magic;       // 0x41555448  ("AUTH")
    u16 version;     // protocol version; this document defines 1
    u16 type;        // message type (§6.4.3)
    u32 body_len;    // bytes of body following the header
}

Every response begins with a fixed 12-byte header:

struct response_header {
    u32 magic;       // 0x41555448
    u16 version;     // echoes the request version
    u16 status;      // outcome (§6.4.4)
    u32 body_len;    // bytes of body following the header
}

magic is the u32 value 0x41555448 (bytes 48 54 55 41 on the wire, little-endian); it is compared as an integer, not as a byte string. A server MUST reject a request whose magic is wrong, whose version it does not implement (UNSUPPORTED_VERSION), or whose body_len disagrees with the datagram length (INVALID_REQUEST).

§6.4.3 Message types

type values are partitioned by interface. A server MUST reject a type that is not valid for the socket it arrived on with INVALID_REQUEST.

§6.4.4 Status and reason codes

status (response header, u16) is the client-visible outcome:

A reason code is recorded for audit only and MUST NOT be sent to the client when the status is DENIED. It is carried in the audit event (§5.1), never in the response body:

NO_SUCH_PRINCIPAL=0, BAD_CREDENTIAL=1, ACCOUNT_DISABLED=2, ACCOUNT_EXPIRED=3, ACCOUNT_LOCKED=4 (carried as the trailing u16 reason on a source DENIED). Collapsing all of these to a single client-visible DENIED with no reason is what closes the account-enumeration and account-state oracles (§3.3, §5.1).

§6.4.5 Client message bodies

LOGON request:

u8   logon_type            // PSD-004 logon type (Interactive=2, …)
str  principal             // name in the grammar of §2.2
u16  cred_type             // 1 = password
u16  cred_len
u8[cred_len] credential    // raw credential bytes (for password, the UTF-8 password); length is the preceding cred_len, not separately prefixed

A cred_type not defined by this version (only 1 = password) MUST be rejected with INVALID_REQUEST before any source call.

LOGON response: on OK, body =

u64  session_id
i64  pw_expiry_warning     // -1 if none; else nanoseconds until expiry

and the minted token fd is attached via SCM_RIGHTS. On any non-OK status the body is empty and no fd is attached.

CHANGE_PASSWORD request (forwarded by authd to the source — §2.2, §7.2):

str  principal
u16  old_len
u8[] old_password          // old_len bytes; may be 0 if caller holds account-admin privilege
u16  new_len
u8[] new_password

Response: OK, or POLICY_VIOLATION (rejected by §3.4), or DENIED (old password wrong), or NOT_AUTHORIZED. Body empty.

LOGON_ON_BEHALF, QUERY, SESSION_MANAGE: the request bodies for these are defined when their features land; for this version a server MUST accept the type, enforce the gate of §6.3, and — for LOGON_ON_BEHALF and SESSION_MANAGE beyond service-token mint — MAY return INVALID_REQUEST for unimplemented sub-operations. The gates themselves (§6.3) are normative now.

§6.4.6 Source verify/resolve body

VERIFY_RESOLVE request (authd → source) has the same field layout as the LOGON request body above.

VERIFY_RESOLVE response: status is one of OK, DENIED, MUST_CHANGE_PASSWORD, SOURCE_UNAVAILABLE, INTERNAL_ERROR. The source includes the audit reason (above) in a trailing u16 reason field of the response body only when status is DENIED (authd forwards it to the audit event and strips it from the client response). On SOURCE_UNAVAILABLE and INTERNAL_ERROR the body is empty. On OK (and on MUST_CHANGE_PASSWORD, which still resolves identity for the change flow) the body is the resolved-principal record:

sid   user_sid
u32   projected_uid          // the principal's id (§3.6); 0xFFFFFFFF if the source assigns none
u32   primary_group_rid
str   account_name
str   display_name         // empty string if none
str   upn                  // empty string if none
u32   account_flags        // §9
i64   pw_last_set
i64   pw_must_change        // -1 if not required
i64   account_expires       // -1 if never
u32   group_count
group_entry[group_count]   // each: { sid sid; u32 attributes; u32 gid }  (SE_GROUP_* per PSD-004; gid = the group's id, 0xFFFFFFFF if the source assigns none — authd resolves)
u32   claim_count
claim_entry[claim_count]   // each: { str name; u16 value_type; u16 value_len; u8[] value }
str   auth_package          // §5.3
str   logon_domain_name
sid   logon_domain_sid

The record carries no credential material and no signature (§4). The groups array MUST be sorted in ascending binary-SID order — the unsigned byte-wise memcmp of the binary SID encoding (PSD-004 §2) with the [len] prefix excluded, the shorter encoding sorting first on a prefix tie — and the claims array in ascending order of the UTF-8 bytes of name, so the encoding is byte-identical across implementations. For this version claim_count MUST be 0 (claims are deferred — §8); the value_type enum is defined when claims land.

§6.4.7 Administration bodies

Administration requests (/run/lpsd.sock) share the envelope. Their bodies are:

CREATE_USER and CREATE_GROUP responses return, on OK, the assigned sid of the new principal in the body. All administration responses use the status codes of §6.4.4; a privilege-gate failure is NOT_AUTHORIZED.

§6.4.8 Versioning

A server MUST reject version values it does not implement with UNSUPPORTED_VERSION rather than guessing. New fields are added by incrementing version; within a version the layouts above are frozen.

A freshly installed system has an empty principal store and no users. This section defines how the first administrator comes to exist without an existing administrator to authorize it.

§7.1.1 The bootstrap authority

The apparent paradox — account creation requires an administrator — dissolves because the SYSTEM bootstrap token exists before any user (it is kernel-constructed and inherited through peinit; PSD-004, PSD-007). First-admin seeding therefore runs in the SYSTEM-everywhere window, before authd is even serving, with full authority. No circular dependency exists.

§7.1.2 Generalised images

A shipped image MUST NOT contain a machine SID or any machine_sid-relative principal (§3.1). Identity is personalised per installed instance on first boot. This prevents SID collisions across clones of one image.

§7.1.3 First-boot setup

On first boot, in setup mode, on the SYSTEM token:

1. lpsd opens its database; finding it uninitialised and setup mode in effect, lpsd initialises the template:
   • generate the machine_sid (S-1-5-21-X-Y-Z);
   • initialise rid_counter and the password/lockout policy;
   • seed the built-ins: Administrator (RID 500, disabled), Guest (RID 501, disabled), and the S-1-5-32 BUILTIN alias groups;
   • create the database file with the tight SD of §3.5.
2. authd starts, connects to lpsd, and signals readiness (§7.1 below). CAAP population is deferred (§8); authd applies the default policy of §5.2 in the meantime.
3. Because no usable administrator exists yet, the system enters an out-of-box (OOBE) setup rather than normal login. A SYSTEM setup agent uses lpsd's administration interface (§7.2) to create the first administrator as a new user (RID ≥ 1000) added to Administrators, and sets its password. The agent obtains the first-admin details interactively, or non-interactively from an unattended answer file — one agent, two input modes.
4. Setup mode ends; login frontends are enabled; normal multi-user login begins.

lpsd MUST generate the machine SID only in setup mode. An uninitialised or missing database on a normal boot MUST be a hard error that triggers recovery (§7.3), never a silent re-generation of the machine SID — silent regeneration would orphan every existing principal if the real database were later restored.

§7.1.4 Setup mode and "usable administrator"

Setup mode is signalled to lpsd by peinit via a kernel-attested capability — peinit's SeTcbPrivilege-bearing token, which lpsd verifies by checking the signaller's peer token (§6.2) is peinit — never a forgeable flag/file/env, and never inferred from the database being absent or empty. lpsd MUST generate the machine SID and seed the template only when this attested signal is present, and only once. On a normal boot (no setup signal), an uninitialised or missing database is a hard error that routes to recovery (§7.3).

A usable administrator is at least one enabled principal that is a member of Administrators (S-1-5-32-544) and holds a password credential factor. The system enters OOBE (step 3 above) iff no usable administrator exists; otherwise it proceeds to normal login. The built-in Administrator (RID 500), shipped disabled, does not by itself satisfy this predicate.

§7.1.5 Startup ordering and readiness

peinit launches lpsd, then authd, early in boot (PSD-007). authd's startup obligations are: verify its own state (PIP-protected, expected token), connect to its sources, and signal readiness to peinit, which blocks until then before launching dependent services. (In a version with CAAP, authd populates the policy cache before signalling readiness; that step is deferred here — §8.)

Account administration is source-shaped and therefore goes directly to a source (§2.2), except for the source-transparent self-service verbs that the broker forwards. For lpsd, administration is served on /run/lpsd.sock (§6.1).

§7.2.1 Administration operations

lpsd's administration interface MUST provide at least:

• CreateUser — allocate a RID from rid_counter, assign an object_guid and POSIX projection, write the user record (§3.2).
• SetPassword (administrative reset) — set the password factor without the old password, subject to the password policy (§3.4).
• CreateGroup, AddMember, RemoveMember — manage groups and membership (§3.2).
• EnableAccount / DisableAccount — toggle account_flags.

Each operation is gated against the peer token (§6.2) by an account-admin privilege. Administration clients route between sources by namespace via a shared client library (§2.2); a domain source serves the corresponding directory operations, which need not match lpsd's shape.

§7.2.2 ChangePassword (self-service, forwarded)

ChangePassword is source-transparent and is forwarded by authd (§2.2, §6.3). lpsd's self-service ChangePassword verb MUST be authorized by one of:

• knowledge of the old password — the request carries old and new passwords; lpsd verifies the old before applying the new (open to any caller, consistent with the knowledge-gates model of §6.3); or
• an account-admin privilege — administrative reset without the old password.

This single verb serves both ordinary password changes and the must_change_password flow (§5.1): a TCB login frontend relays the user's old and new passwords after a must_change_password result, and lpsd's verification of the old password is the authorization — no special privilege is required.

§7.2.3 Propagation

Administrative changes take effect at the principal's next logon: a token reflects logon-time identity and is immutable (PSD-004). Live sessions are unaffected until re-logon or forced logout (§6.3). authd and the administration interface therefore need no coupling for propagation.

Recovery is the inverse of seeding (§7.1): a path back to a usable administrator when the only one is lost, and a way to repair or restore a damaged store.

§7.3.1 Lost administrator

If no usable administrator remains, the system MUST be able to re-enter a SYSTEM-authority setup path (the bootstrap authority of §7.1) under which a new administrator can be created via lpsd's administration interface. This MUST require local, SYSTEM-level access, consistent with the bootstrap trust model — it is not a remote or unprivileged operation.

§7.3.2 Database repair and restore

lpsd MUST provide offline inspection and restore tooling backed by the SQLite facilities of §3.5:

• an inspector mode (lpsd --inspector or equivalent) that opens the database read-only for examination and PRAGMA integrity_check;
• a restore-from-backup mode that replaces the live database from a known-good backup produced by SQLite's online backup.

A missing or uninitialised database on a normal boot is a hard error that routes here, never a silent re-initialisation (§7.1).

§7.3.3 What recovery does not do

Recovery MUST NOT regenerate the machine SID for an existing instance (§3.1, §7.1): doing so would orphan every principal whose SID is machine_sid-relative. Machine-SID generation happens once, in first-boot setup mode.

This chapter is informative. It records features that are part of the subsystem's intended scope but are deliberately deferred to later versions, so that the core (interactive local password logon and its administration) can be specified and built first. Nothing here is normative for this version; each item names the contracts already shaped to accommodate it.

§8.1.1 CAAP distribution

authd is intended to read central access policies from the directory and push them into the kernel policy cache before signalling readiness, and to re-push on change. This is deferred. The policy phase (§5.2) runs on a declared default policy until the rights-assignment/CAAP policy store is wired.

§8.1.2 Domain join (adpsd, Active Directory, Kerberos)

The domain principal source (adpsd) fronting Active Directory via Kerberos/NTLM is deferred. The seam (§2.2), the resolved-principal contract (§4, PAC-isomorphic), the source registry (§6.1), and the namespace-based routing (§2.2) are all shaped so that adpsd drops into lpsd's structural position. adpsd is responsible for verifying a real PAC's signatures and translating into the §4 contract, and for any challenge–response on its remote hop (§6.2).

§8.1.3 Elevation and linked tokens

UAC-style Full/Limited linked-token pairs and filtered tokens are deferred. Token shaping (§5.2 step 5) is the hook; this version mints a single primary token.

§8.1.4 Claims and Dynamic Access Control

Source-native claims already flow through the resolved principal (§4) and onto the token; claim-transformation policy and the broader DAC story are deferred.

§8.1.5 Forced logout / revocation tooling

The userspace forced-logout pattern (walking /proc/*/token by auth_id and signalling holders; PSD-004) is a session-management request (§6.3) gated by SeTcbPrivilege. The tooling around it is deferred.

Security limitation (not merely deferred tooling). KACS provides no token-revocation primitive: tokens do not expire, a token fd passed via SCM_RIGHTS to a process outside the session survives forced logout, and account disable/delete takes effect only at the principal's next logon (§7.2). "Log this user out now" is therefore best-effort, and the /proc/*/token walk is racy — a holder may fork or pass its fd between enumeration and signalling, so the walk MUST re-scan until no holder remains. A real revocation guarantee depends on a future KACS dead-logon-session facility, which this subsystem treats as a dependency.

§8.1.6 Additional credential factors

webauthn/passkey, x509/smartcard, and recovery_code factors reuse the credential shape of §3.3 and are deferred.

§8.1.7 TPM-sealed at-rest protection

The tpm-sealed scheme and the optional argon2id pepper (§3.5) are deferred until the platform's measured-boot story is solid enough to seal against without brittle reseal-on-update failures. The wrappable secret_part shape is mandated now so adoption is a re-wrap pass.

§8.1.8 Secondary-logon launch helper

A helper that lets an unprivileged caller launch a process on a token it obtained via Logon (the runas/seclogon analogue) is deferred. Until then, installing a returned token as a primary token requires the appropriate privilege, which login frontends and peinit hold (§5.3).

§8.1.9 A Rust wrapper for kacs_set_impersonation_level

The client-side impersonation-level cap (§6.2) has no Rust binding yet. Clients that need to cap the level below the default will require one.

This appendix consolidates the subsystem's enumerable artifacts. For constants and default-policy tables the values here are normative (the cited section defines their semantics and use); for syscalls, sockets, and message types this appendix is an index into the normative section.

§9.1.1 KACS syscalls used by authd

All are defined by PSD-004; numbers are from the generated UAPI constants. authd is the only normal-operation caller (§2.1).

§9.1.2 Sockets

Connect access is enforced by an explicit SD (§6.1) and by the per-request gate (§6.3).

The /run/authd/sources/ directory SD MUST allow entry creation only by the specific trusted source identities (e.g. lpsd's service SID may create lpsd.sock; adpsd's may create adpsd.sock); creation MUST be exclusive, and authd MUST verify each source socket is owned by its expected identity before connecting (§6.1).

§9.1.3 Protocol message types and status codes

Normatively defined in §6.4. Message types: LOGON=1, CHANGE_PASSWORD=2, QUERY=3, LOGON_ON_BEHALF=4, SESSION_MANAGE=5, VERIFY_RESOLVE=16, CREATE_USER=32, SET_PASSWORD=33, CREATE_GROUP=34, ADD_MEMBER=35, REMOVE_MEMBER=36, ENABLE_ACCOUNT=37, DISABLE_ACCOUNT=38, CHANGE_PASSWORD_SS=39. Status codes: OK=0, DENIED=1, MUST_CHANGE_PASSWORD=2, LOGON_TYPE_DENIED=3, NOT_AUTHORIZED=4, INVALID_REQUEST=5, UNSUPPORTED_VERSION=6, SOURCE_UNAVAILABLE=7, POLICY_VIOLATION=8, INTERNAL_ERROR=9, RATE_LIMITED=10, TOKEN_TOO_LARGE=11. Audit-only reason codes (never sent to the client on DENIED): NO_SUCH_PRINCIPAL=0, BAD_CREDENTIAL=1, ACCOUNT_DISABLED=2, ACCOUNT_EXPIRED=3, ACCOUNT_LOCKED=4 (§6.4).

§9.1.4 Request types and gates

§9.1.5 Default privilege-assignment table

Normative MVP default (§5.2). A token's present privileges are the union over all its SIDs. Reserved (never assigned to anyone): SeCreateTokenPrivilege, SeTcbPrivilege, SeAssignPrimaryTokenPrivilege, and SeLoadDriverPrivilege (peinit-exclusive — PSD-004 MUST-strips it from all non-peinit tokens; driver loading routes through peinit).

Enabled-by-default: SeChangeNotifyPrivilege only; every other present privilege is present-but-disabled (§5.2).

§9.1.6 Default logon-rights table

Normative MVP default (§5.2). A principal may perform a logon type iff some SID holds the allow right and no SID holds the deny right (deny overrides). Deny lists are empty by default.

§9.1.7 Implicit token groups by logon type

Normative (§5.2 step 2). Added by authd (not the kernel). Attribute set M = SE_GROUP_MANDATORY | SE_GROUP_ENABLED | SE_GROUP_ENABLED_BY_DEFAULT (per PSD-004).

§9.1.8 Integrity-level predicate

Normative MVP default (§5.2 step 4). Levels per PSD-004 §10.3.

§9.1.9 Constants and defaults

§9.1.10 account_flags bits

Normative (§3.2). Bit positions in the account_flags u32.

Unassigned bits MUST be zero. EnableAccount/DisableAccount (§7.2) toggle bit 0.

§9.1.11 POSIX id layout

Normative scheme in §3.6; all ids below 2³¹. The bands are the shared allocation contract; the Allocator column names who assigns+stores in each.

Well-known S-1-5-N (band 1–999, → N): 1 Dialup, 2 Network, 3 Batch, 4 Interactive, 6 Service, 7 Anonymous Logon, 8 Proxy, 9 Enterprise DCs, 10 Self, 11 Authenticated Users, 12 Restricted Code, 13 Terminal Server User, 14 Remote Interactive, 15 This Organization, 17 IUSR, 18 SYSTEM (→ 0; 18 reserved), 19 LocalService, 20 NetworkService, 113 Local account, 114 Local account & Administrator. (5 is the logon-session family S-1-5-5-X-Y, not single-RID; 21/32/64/65/80/83/84/90/96 are family prefixes, not principals.)

S-1-5-32-N BUILTIN aliases (band 1000–1999, → 1000+N): the full 544–580 set (Administrators 544→1544, Users 545, Guests 546, Power Users 547, Account/Server/Print/Backup Operators 548–551, Replicators 552, Pre-Windows2000 554, Remote Desktop Users 555, … Remote Management Users 580). The arithmetic rule covers every alias.

Domain-relative RIDs (Administrator 500, Guest 501, krbtgt 502, Domain Admins 512, Domain Users 513 … 527) are not a well-known band — they are namespace base + RID: local 500/501 fall in the local band, domain RIDs in the domain band.

§9.1.12 SID families with no id

These are omitted from the uid/gid projection entirely — they are never object owners and KACS handles them SID-natively. A Linux view simply does not show them.

• S-1-3-* — Creator Owner/Group/Server, Owner Rights (ACE placeholders).
• S-1-4 and bare authority/domain prefixes (S-1-5-21-… with no RID, S-1-5-32, S-1-5-80, …) — identifier authorities/domains, not principals.
• S-1-5-5-X-Y — logon-session SIDs (per-session; isolation is SID-native — revisit only if a per-session Linux gid is ever needed).
• S-1-5-64-* (auth packages: NTLM/SChannel/Digest), S-1-18-* (asserted identity), S-1-5-1000 (Other Organization) — authorization-context markers, never owners.
• S-1-16-* — mandatory integrity labels (not principals).

§9.1.13 group_type values

Other Windows scopes/types are reserved; clients SHOULD send 0.

§9.1.14 Reserved and well-known RIDs

S-1-5-32 BUILTIN aliases (Administrators 544, Users 545, …) and other well-known SIDs are defined by PSD-004 and represented as group entities in lpsd (§3.1).

§9.1.15 secret_part protection schemes

§9.1.16 lpsd database tables

The principal-store schema (illustrative DDL, normative content) is defined in §3.5: domain, users, credentials, pw_history, groups, members, claims, schema_version.