# 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.

Related content:

- [Settings for all users](/peios/using-peios/desktop-settings/for-all-users.md)
- [Install, upgrade, or repair a disk](/peios/using-peios/disks-and-filesystems/installing-to-disk.md)
- [Complete first-boot setup](/peios/using-peios/disks-and-filesystems/first-boot-setup.md)
- [The trust store](/peios/using-peios/trust/overview.md)