# Signing In from a Browser --- # Sign in from a browser _Peios / Using Peios / Signing In from a Browser_ > Reach the GXWI desktop over HTTPS, verify the machine's certificate, and sign in with an account on that machine. The Peios desktop runs on the Peios machine and is displayed in your browser. To open it, you need the machine's address, the port it is configured to listen on, and an account on that machine. If you have just installed Peios with the graphical or text installer, complete [First-boot setup](/peios/using-peios/disks-and-filesystems/first-boot-setup.md) first. On a live installation medium, follow [Install on a PC](/peios/using-peios/installing-peios/on-a-pc.md) instead: the installer and its temporary account are different from a normal sign-in. ## 1. Open the machine's address Open `https://:7780`, replacing `` with the machine's address or name. Use the configured port if an administrator changed it. The desktop service, GXWI, serves HTTPS only. An HTTP request is redirected to HTTPS; it does not serve an unencrypted desktop. > [!NOTE] > The listen setting's built-in default is `127.0.0.1:7780`, which is > reachable only from the Peios machine itself. An image or administrator > must configure a reachable address before another device can connect. > See [Settings for all users](/peios/using-peios/desktop-settings/for-all-users.md#advanced). > Do not change the listen address casually: changing it can disconnect > open desktops when GXWI next starts. ## 2. Verify the certificate before entering credentials Each machine creates its own certificate. A browser does not initially know whether to trust it, so a warning on first use is expected. Follow [The machine's certificate](/peios/using-peios/signing-in-from-a-browser/the-certificate.md) to compare the browser's SHA-256 fingerprint with the fingerprint shown at the machine's own console. Do not use a page received over the connection you are trying to verify as the source of that fingerprint. If the fingerprints differ, do not sign in. That guide also explains importing the certificate, name mismatches, renewal and why a live medium presents a new certificate after each boot. ## 3. Sign in and choose your task Sign in with an account on this machine. The desktop and its tools use that account's authority; machine-wide changes may require an administrator account or specifically delegated access. - [Desktop Settings](/peios/using-peios/desktop-settings/overview.md) changes your wallpaper, clock, dock, shortcuts and default applications. - [Manage the machine](/peios/using-peios/operating-peios/manage-the-machine.md) points to software, services, accounts, networking and storage tasks. - [Troubleshoot a problem](/peios/using-peios/operating-peios/troubleshoot-a-problem.md) covers reachability, refused sign-in and missing records. If the machine shows an installation or setup overlay instead of a sign-in screen, follow that flow's guide. While an overlay is configured, normal sign-in and desktops are unavailable. ## GXWI replaces Atrium GXWI completely replaces Atrium. Use the HTTPS connection and certificate verification steps above; the old Atrium connection and application instructions are retired. --- # The machine's certificate _Peios / Using Peios / Signing In from a Browser_ > GXWI serves the desktop over HTTPS with a certificate each machine makes for itself and renews every year — why the browser warns, how to check the fingerprint before going past the warning, what importing the verified certificate does and does not establish, and where the key is kept. The desktop is reached in a browser at `https://` and the machine's address, port 7780 unless an administrator has chosen another. GXWI serves it over HTTPS alone, with a certificate the machine made for itself the first time GXWI started. No certificate authority has vouched for it, so a browser warns the first time it is opened, until it is told to trust it. Opening `http://` instead is answered with a redirect to the same address under `https://`, and with nothing else: no page is ever served without encryption. ## Check the fingerprint before going past the warning The warning is the browser saying it cannot tell this certificate from one someone between you and the machine made up. You can: every certificate has a SHA-256 fingerprint, and the machine shows you its own. The managed console login banner shows the fingerprint before sign-in when GXWI has made its certificate. Read it on the machine's own trusted console. If the banner says it is unavailable, or to read the current fingerprint after renewal, sign in locally and print the public file, which any account may read: ``` $ cat /var/state/gxwi/certificate.sha256 B8:39:98:AB:E7:F6:64:25:BC:0D:DE:56:F4:78:2E:21:3D:D8:AB:FF:EF:78:8A:81:6E:94:99:17:94:83:73:C3 ``` Read it there, and not from a page in the browser: a page that came over the connection you are checking would show whatever someone in the middle of it wanted. Once you trust the connection, a terminal on the desktop reads the same file. In the browser, open the warning's details and view the certificate. Its SHA-256 fingerprint is the same 32 pairs of hex digits, though some browsers separate them with spaces rather than colons. If the two match, the connection is to this machine and nobody can read it on the way. If they do not, do not sign in. Firefox may still describe a connection with a certificate exception as insecure, even when it uses TLS. That label alone does not establish whether the traffic is encrypted or whether the peer is the right machine. Check the presented certificate against the console fingerprint as above. Importing the verified certificate establishes trust in it; name and validity checks still apply. ## Trust the verified certificate The certificate is in `/var/state/gxwi/certificate.pem`, also readable by anyone. After checking its fingerprint through the trusted console, copy it to the device you browse from and add it to that browser's or system's trusted certificates. This establishes trust in that certificate; it does not remove name-mismatch, expiry or other certificate warnings. The [reviewed certificate generator](https://github.com/peios/gxwi/blob/94103e7d29b6b3287186ed1a0ed023bb64468a7d/gxwid/src/tls.rs#L225-L249) includes the machine name at creation, `localhost`, and the loopback addresses `127.0.0.1` and `::1`. It does not include the machine's other network addresses. An existing certificate may have been generated by an earlier version or under an earlier machine name: inspect the certificate actually presented. Trusting it does not make an address or name absent from that certificate valid. An imported certificate lasts until the machine renews it, once a year (see [Renewal](#renewal)): import the new one then. A certificate only gone past at the warning, not imported, also costs the **waiting page**: GXWI keeps a page in the browser that it shows while the machine is restarting or cannot be reached, and a browser keeps such a page only for a certificate it trusts. Without it, a tab left open while the machine restarts shows the browser's own error, and loads again by hand. ## No HSTS GXWI deliberately sends no `Strict-Transport-Security` header. HSTS tells a browser to refuse any certificate warning for the site from then on, which with a certificate of the machine's own making would leave nobody a way past the first warning, including after the machine's key changes. ## Where the key is kept | File | What it is | Who can read it | |---|---|---| | `/var/state/gxwi/key.pem` | The private key, ECDSA P-256 | SYSTEM alone | | `/var/state/gxwi/certificate.pem` | The certificate | Everyone | | `/var/state/gxwi/certificate.sha256` | Its SHA-256 fingerprint | Everyone | GXWI makes the key once and keeps it. It never replaces a key it cannot read: it stops, and says so. Move the files aside to have a new key made; every browser that trusted the old certificate then warns again. ## Renewal A certificate lasts a year, from the day before it was made. GXWI renews it once fewer than 30 days of it remain, for the same key: the machine is the same machine, but the certificate, and so its fingerprint, is new. Each renewal means one more warning in every browser that went past the old one, and importing the new `certificate.pem` again for anyone who imported the old. Check the new fingerprint as you did the first. Renewal uses the machine's current hostname for the certificate's common name and DNS name, alongside `localhost`, `127.0.0.1` and `::1`. A machine rename is therefore picked up at the next renewal; renaming alone does not renew a certificate that is still within its normal lifetime. GXWI looks when it starts, once a day while it runs, and when it is reloaded: ``` $ svctl reload gxwid ``` Nothing restarts, and nobody signed in is signed out. Connections already open carry on; the next one the browser makes is shown the new certificate. A renewal is recorded as the event [`gxwid.certificate.renewed`](/peios/using-peios/events/gxwid/gxwid-certificate-renewed.md), which carries the old and new fingerprints. ## Installation and first boot On a live medium `/var/state` is in memory, so every boot makes a new key and the warning comes back each time. `installerd` attempts to carry that key and certificate into the installed system, whether you use its console or browser surface. In the [reviewed installer](https://github.com/peios/installer/blob/0b687372ad41132668824216da51558bbfe53c01/installerd/src/real.rs#L567-L600), an absent key skips the transfer and a copy failure is logged without failing the installation. The [installation continues](https://github.com/peios/installer/blob/0b687372ad41132668824216da51558bbfe53c01/installerd/src/real.rs#L1070-L1080), so its completion message does not prove certificate continuity. A failed copy can leave partial state; it does not guarantee a clean new identity or working HTTPS on the next boot. If the installed system presents the same verified certificate, existing trust may continue subject to the browser and address checks above. If its fingerprint changes, verify it again through the installed machine's trusted console before entering credentials. If you cannot do that during first boot, complete setup on the console first, then verify before using browser sign-in. Follow [First-boot setup](/peios/using-peios/disks-and-filesystems/first-boot-setup.md#verify-the-certificate-before-entering-a-password). The older `peios-install` script is a separate path: the installed system makes its own key when GXWI first starts. Do not infer its certificate behavior from `installerd`'s transfer attempt.