# Signing In --- # Signing in _Peios / Peios Security Fundamentals / Signing In_ > How a sign-in works on Peios — the conversation with the authority on /run/logon.sock, the roles involved, and why authentication and derivation are separate. 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 [managing local principals](/peios/security-fundamentals/managing-local-principals/overview.md). ## 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](/peios/security-fundamentals/managing-local-principals/creating-accounts.md) and console autologon. A connection carries exactly one conversation, so the connection is the conversation's identity. There is no correlation identifier to forge. ## 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 `exec`s 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](/peios/security-fundamentals/privileges/overview.md) 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](/peios/security-fundamentals/logon-sessions/logon-types.md). **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](/peios/security-fundamentals/managing-local-principals/resolving-names.md). ## Where to start - [The `login` command](/peios/security-fundamentals/signing-in/the-login-command.md) — the terminal client, and how a live image signs in without being asked anything. - [Logon sessions](/peios/security-fundamentals/logon-sessions/overview.md) — the kernel object a successful sign-in creates. - [Managing local principals](/peios/security-fundamentals/managing-local-principals/overview.md) — the accounts being signed in to. The protocol is specified rather than merely documented: [PGSS §2](/peios/advanced-peios/pgss/logon/scope-and-roles.md) is Logon, and [PSPU §2](/peios/advanced-peios/pspu/principal-source-interface/scope-and-roles.md) is PSI, the interface principal sources speak. Read those if you are writing a client or a source of your own. --- # The login command _Peios / Peios Security Fundamentals / Signing In_ > login is the terminal client for PGSS Logon — it collects an identifier and whatever credentials the authority asks for, and starts your shell. `login` is the terminal client for [signing in](/peios/security-fundamentals/signing-in/overview.md). It collects an identifier, renders whatever credential prompts the authority sends, installs the token it is granted, and replaces itself with your shell. ``` login [name] [options] login --try [options] login --try-no-password [options] ``` It does not know what a password is. It renders the prompts it is asked to render and returns the answers, so adding a new credential type — a one-time code, a smartcard — changes the authority and leaves `login` alone. ## Naming a principal, or not With no name, `login` asks for one: ``` Username: alice Logging in as alice Password: ``` With a name, the first prompt is skipped. The `Logging in as` line comes from the authority rather than from `login`, so it will gain a realm once authorities have them. A principal who needs no credential is signed in immediately, with no prompt at all — see [passwordless accounts](/peios/security-fundamentals/managing-local-principals/creating-accounts.md). ## `--try` and `--try-no-password` Both attempt a named principal and fall back to an ordinary prompt rather than failing. They differ in what they offer to collect. **`--try `** attempts the principal with `login`'s full capabilities. A passwordless principal is signed in immediately; one with a password is prompted for it. **`--try-no-password `** attempts the principal while declaring that it can collect nothing, so only a principal who needs no credential can succeed. This is what a console autologon uses. Neither flag asserts that anyone is authenticated. The authority still decides, and understating what you can collect only denies you prompts you could have rendered — so running either by hand gains you nothing you did not already have. | | Passwordless | Has a password | No such principal | |---|---|---|---| | `login alice` | signed in | prompts | `user alice does not exist` | | `login --try alice` | signed in | prompts, then falls back if wrong | falls back silently | | `login --try-no-password alice` | signed in | falls back silently | falls back silently | A fallback restarts the sign-in from `Username:`, so you are never locked to the principal that was attempted. ### When a fallback explains itself `login` says why it fell back only if something was already on your terminal. A `--try` that reached a password prompt has interrupted you, and dropping to `Username:` without a word would read as a fault — you typed a password and got asked for a name. So it reports first: ``` $ login --try alice Logging in as alice Password: login: Password incorrect Username: ``` A `--try-no-password` that was refused before anything was rendered has interrupted nobody, and stays quiet. That is what keeps a line about a failed autologon off the console of every machine where the principal simply has a password. Falling back is limited to denials another principal could survive. A failure of the authority itself is reported and `login` exits, because offering a prompt that cannot work either would spin a console. ### Where existence is checked `login` asks `/run/ident.sock` whether a principal exists, not the logon socket. The logon socket will not tell it — an authority never distinguishes an unknown principal from a bad credential — while the identity socket answers plainly, which is what it is for. If that lookup cannot be answered, `login` attempts the sign-in anyway rather than reporting an absence. An unreachable source reported as "no such user" would turn an outage into a fact. ## Autologon on a console A console that signs in on its own is a passwordless principal plus `--try-no-password`. On a live image, `peinit` starts: ``` /bin/login --try-no-password peios ``` The same service definition suits an image where `peios` has a password: the attempt is refused before anything is rendered, and an ordinary prompt appears. No second seed, and no conditional configuration. To turn autologon off, give the principal a password with [`lps password`](/peios/security-fundamentals/managing-local-principals/lps-command.md). To move the prompt to another terminal, change the service's `TTYPath` — see [controlling services](/peios/using-peios/services-and-jobs/controlling-services.md). ## Options | Option | Effect | |---|---| | `--try ` | Attempt `name`, falling back to a full prompt. | | `--try-no-password ` | Attempt `name` collecting nothing, falling back to a full prompt. | | `-p` | Keep the inherited environment instead of building a fresh one. | | `-h ` | Record the remote peer for a sign-in originated on its behalf. Unverified. | | `-H` | Accepted and ignored. Suppresses the hostname banner on other systems. | | `--` | Treat everything after as a name, not an option. | `-f` is **not** implemented. On Linux it means "trust me, they are already authenticated", gated only by the caller being root. On Peios that decision belongs to the authority, taken from the verified peer, so accepting a flag here would put an authentication bypass in an unprivileged process. ## The environment your shell starts in Without `-p`, `login` builds a fresh environment: `HOME`, `SHELL`, `USER`, `LOGNAME`, `PATH=/bin`, and `TERM` carried through from its own. The shell's `argv[0]` gets a leading dash, which every shell reads as "this is a login shell, run the profile files". The home directory comes from the profile the authority sent, and **a missing one is not fatal**. `login` reports it and starts you in `/`. Refusing to proceed over an absent directory would turn a cosmetic problem into being locked out, and creating it would put directory provisioning inside the one program that has to keep working when everything else is broken. ## Exit status `login` does not return on success — it replaces itself with your shell, so what you see afterwards is the shell's exit status. | Code | Meaning | |---|---| | `1` | A usage error, a denied sign-in, or the shell could not be started. |