Keys and sign in

The Keys screen

Keys lists the SSH keys on this device, newest first, under On this device only. Each key shows:

• its name, its type (Ed25519 or ECDSA P-256, P-384 or P-521) and when it was made or added;
• chips for Secure Enclave and Face ID or Touch ID when they apply;
• its Fingerprint, as ssh-keygen -lf shows it (SHA256: and so on);
• Public key, hidden until you press Show, and Copy Public Key;
• Forget, to delete it.

Only the public half of a key is ever shown or copied. Nothing in Conn copies a private key. A key that requires Face ID or Touch ID asks before its public key is shown or copied too.

Making a new key

Press +, then New Key... Give it a Name, such as "Work Laptop", choose the Algorithm, and press Make Key.

Kind	When to choose it
Secure Enclave (P-256)	The default wherever the device has a Secure Enclave. The key is made inside the chip, so its private half can never be read out or copied, even by Conn.
Ed25519	What a modern OpenSSH expects, for a server that accepts only Ed25519 keys. Kept in the Keychain on this device. The default on a Mac without a Secure Enclave (an Intel Mac without a T2 chip).
ECDSA P-384, P-521	Larger ECDSA, for servers that ask for them. A new key gains nothing from them over Ed25519.
ECDSA P-256	Offered on a device without a Secure Enclave.

Require Face ID or Touch ID (off by default) makes Conn ask before every use of the key, and before it's shown or copied. If the device can't do that for the kind you chose, Conn says so under the switch and doesn't make a different kind instead.

Then add the key's public half to your machines: see Signing in with a key.

Adding a key you already have

Press +, then Add Existing Key..., and either Choose File... (on a Mac it opens in ~/.ssh) or paste the key. Pick the file without .pub on the end, such as ~/.ssh/id_ed25519.

• Accepted: OpenSSH private keys (BEGIN OPENSSH PRIVATE KEY) holding an Ed25519 or ECDSA key, and ECDSA keys in PEM (BEGIN EC PRIVATE KEY) or PKCS#8 (BEGIN PRIVATE KEY).
• Conn keeps a copy in the Keychain on this device, and leaves your file as it is. A pasted key is cleared from the clipboard once it's added.
• The name is filled in from the key's comment, if it has one.

Conn can't use these yet, and says which it met and what to do, usually with the command to fix it:

Key	What to do
A key with a passphrase	Make a new key, or remove the passphrase from a copy with ssh-keygen -p -N '' -f file (which leaves that file unprotected).
A PuTTY .ppk file	Convert it: puttygen file -O private-openssh -o new file.
RSA, DSA, Ed448 or a security key (sk-)	Make an Ed25519 key with ssh-keygen -t ed25519, or in Conn.
An EC key with its curve spelled out (from ssh-keygen -m PEM)	Convert it: ssh-keygen -p -m RFC4716 -f file.
A public key (.pub)	Pick the private key file instead.

Forgetting a key

Forget deletes the key's private half from this device, after asking. A key made here can't be recovered; a key added from a file leaves the file as it was. Hosts that signed in with it need another key chosen in Edit Host, and it's worth removing its public half from your machines too.

How a host signs in

Each host has an SSH sign in (for Terminal and Files) and, separately, a screen sign in. Set them in Edit Host, Sign in, or the first time you connect:

• Username, and Sign in with Password or Key. The key list offers the keys on this device, and Make a Key (or Make Another Key).
• When connecting, Use and Save keeps it; Use Once signs in this time and keeps nothing.
• A saved password is never shown or filled in again. The field says Saved. Type to replace it.
• With both a key and a password saved, Conn signs in with the key (one on this device before one that isn't), and doesn't try the password if the key is refused.

Where passwords are kept

• Saved SSH passwords, a Mac's Screen Sharing password and a screen account password (such as a Raspberry Pi's) are kept in this device's Keychain, set to this device only, and ask for Face ID, Touch ID or the passcode (on a Mac, Touch ID or your login password) each time Conn uses them. One check covers everything one action needs.
• A VNC password is kept in the Keychain too, without the Face ID check.
• Passwords and keys never sync, and are never restored onto another device from a backup.
• To remove a sign in, use Remove Sign In in Edit Host. A password is deleted; a key just stops being used for that host and stays in Keys.

On your other devices

With iCloud sync on, a host's sign in record (its user name and kind) syncs, but its password or key doesn't. On another device the host shows Needs password or Needs key. Connect, and the Sign In sheet says the password or key isn't on this device; enter it, or choose a key, once, and Conn keeps it there. Each device keeps its own.

Connections Conn makes by itself, such as checks in Sessions or a group run, can't ask, so they say to open the host and enter it there once.

Server keys

Every SSH server has a key of its own, which proves it's the machine you meant. Conn checks it every time it connects.

• The first time Conn meets a machine, it remembers its key.
• Reaching a known machine a new way, for example over Tailscale after your home network, or after you change its address or port in Edit Host, Conn shows the key and asks first, unless it already has that key for the host.
• Keys are kept per address and port, in the Keychain on this device only, and never sync. Each device learns a machine's key the first time it connects.

When a key changes

If a machine offers a different key from the one Conn kept, Conn stops before sending anything and shows The host key for the host has changed, with the date Conn first trusted it and both fingerprints.

• Keys change for ordinary reasons: the machine was reinstalled, a container rebuilt, a backup restored. They also change when something is sitting between you and the machine. Conn can't tell these apart; only you know whether the machine changed.
• Replace the Stored Key only if you know the machine was rebuilt or reinstalled. Otherwise choose Do Not Connect, and check the machine from somewhere you trust.
• To check a fingerprint on the machine itself, run ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub there (or ssh_host_ecdsa_key.pub).

Other questions you may see:

Question	Means	Choices
A new kind of host key	Conn trusts this machine, but not this kind of key. It may have gained one in an upgrade.	Record This Key Too, Do Not Connect
Conn has no key for this host here	A known machine reached at a new address or port.	Trust This Key, Do Not Connect
Offered a certificate	The machine proved itself with a certificate. Conn doesn't accept those.	Close

Conn never answers for you. When it reconnects by itself, checks Sessions or runs a group, it refuses a key it doesn't know and says so; open a terminal on the host to answer. There's no way to make Conn forget a stored server key other than replacing it when it asks.

A screen that encrypts itself has a key too; see Screen keys.

What signs in

• Sign in methods: password, and public key.
• Your keys: Ed25519, and ECDSA P-256 (including Secure Enclave keys), P-384 and P-521.
• Server keys: Ed25519 and ECDSA.
• Not yet: RSA keys and servers with only an RSA host key, keyboard-interactive and two-factor sign in, keys with a passphrase, PuTTY files, host certificates and agent forwarding.

Full detail is in What Conn supports.