The machine's certificate

6 min read

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 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): 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 #

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, 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, an absent key skips the transfer and a copy failure is logged without failing the installation. The installation continues, 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.

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.

Edit this page