Docs · Host

Devices and keys.

osewa has no passwords. Every device has its own Ed25519 key, every host has one too, and both sides prove who they are on every connection, over TLS 1.3.

The keys

client.key, on your machine: Your device's private key, created the first time you run osewa login. It never leaves the machine; hosts only see its public half.
server.key, on the host: The host's private key, created when osewa is first set up there.
devices, on the host: The public keys allowed in, one device per line. Like ssh's authorized_keys.
hosts.json, on your machine: The hosts you have logged in to: name, address and the host's public key. Like ssh's known_hosts, but filled in for you.

All four live in ~/.config/osewa/; see Files and environment. osewa refuses to use a key file that others can read, and a devices file that others can write. Keys are stored as plain files with mode 0600, not behind a passphrase or an agent.

Enrollment

osewa login enrolls your device over ssh. It sends your public key and device name to osewa enroll on the host, which adds them to devices and replies with the host's public key. Since that reply comes over an ssh connection you already trust, there is no "trust this host?" prompt, and nobody can stand in the middle of your first osewa connection.

A device name is 1 to 64 bytes. Enrolling a name or a key that is already listed replaces that line, so logging in again from the same device doesn't add duplicates.

Listing devices

On the host, the devices file is the list:

$ cat ~/.config/osewa/devices
{"name":"laptop","key":"pW2xq9R0…"}
{"name":"phone","key":"Zk81dLm3…"}

Revoking a device

Delete that device's line from devices on the host, with any editor or:

grep -v '"name":"phone"' ~/.config/osewa/devices > /tmp/d && cat /tmp/d > ~/.config/osewa/devices

The server reads the file on every new connection and never resumes old TLS sessions, so the device is refused the next time it connects. A connection that is already open isn't cut; to end it now, restart the server (osewa service install again, or systemctl --user restart osewa). Sessions survive the restart.

There is no osewa command to list or revoke devices yet.

A lost or new machine

Lost a device: revoke it on every host it was enrolled on.
New machine: run osewa login from it. It gets its own key, and the other devices keep theirs.
Copying ~/.config/osewa to a new machine works, but then two machines share one key, and revoking one revokes both.

If the host's key changes

If the host's server.key is replaced, your saved pin no longer matches and the connection fails with auth: server key does not match pin. That is either a reinstalled host or someone in the middle. If you know the host was reset, log in again over ssh to enroll and pin the new key.