LobiShell can authenticate your SSH sessions with a FIDO2 security key such as a YubiKey — over NFC or USB-C. This guide walks the complete path: creating the identity, deploying the public key to your server, linking it to a connection, and authenticating. It ends with a troubleshooting table keyed by the exact error codes the app can show.
What you need
A FIDO2 security key. U2F-only keys will not work — Ed25519 credentials require CTAP2.
A phone with NFC, or a USB-C OTG connection to the key. Both are fully supported.
A server running OpenSSH 8.2 or newer. That release introduced the sk-ssh-ed25519@openssh.com key type; older servers cannot accept these keys at all.
Optionally a FIDO2 PIN set on the key. Not required in general, but mandatory if you want to store the credential on the key itself (see below).
How it actually works (read this first)
One misunderstanding causes most of the confusion, so it is worth clearing up before you start.
The private key never leaves your security key, and by default nothing is stored on it either. When you generate a credential, the token derives it from its own built-in master secret and hands back a key handle — an opaque, encrypted reference. That handle is what goes into the key file on your phone. At login time LobiShell passes the handle back to the token, which re-derives the private key internally, signs the challenge, and returns onlyyyyyy the signature.
Two consequences follow directly from this, and both surprise people:
The key file only works with the exact token that created it. Only that token’s master secret can unwrap the handle. Copying the file to another phone is fine — copying it to another YubiKey is meaningless.
The credential will not appear in the Yubico Authenticator app. There is nothing on the key to list. This is normal and identical to what ssh-keygen -t ed25519-sk produces on a desktop. If you want it listed, use the resident-key option described below.
You also cannot transfer an existing SSH key onto the security key. FIDO2 has no import command — credentials only ever come into existence on the token itself. For a second key, you register an additional credential rather than copying the first one.
Step 1 — Create the identity
Open Identities and create a new identity.
Fill in a Label and the Username you will log in with on the server.
Set the authentication type to Security Key (FIDO2 / NFC).
Tap Generate on YubiKey. A configuration dialog appears.
The configuration options
Option
What it does
When to change it
Application
The FIDO2 relying-party ID written into the credential. Defaults to ssh:, the OpenSSH convention.
Leave it alone unless you deliberately want separate credential namespaces, e.g. ssh:work.
Require PIN for every login
Creates the credential with credProtect=3. The token then enforces PIN entry on every single SSH authentication, not just a touch.
Turn on for high-value servers. Note you will type the PIN at every login.
Store the key on the YubiKey
Creates a resident (discoverable) credential. The token really stores it, it shows up in the passkey list, and it can be recovered from the key alone.
Turn on if you want the credential visible and recoverable. Costs one of the token’s limited credential slots and requires a PIN.
Generating
Tap Continue. Then either hold the security key against the back of your phone (NFC), or connect it and tap Use USB.
If your key has a FIDO2 PIN configured, LobiShell asks for it at this point — this is required by the CTAP2 standard as soon as a PIN exists on the token. Enter the PIN and confirm. Over USB the attempt retries immediately; over NFC, hold the key against the phone again.
Touch the key when it flashes. Nothing is created without a physical touch — that is the user-presence check, and it cannot be skipped. On success you get the public key, ready to deploy.
Step 2 — Deploy the public key to your server
The public key looks like this and belongs in ~/.ssh/authorized_keys on the server, on a single line:
On the success screen tap Deploy. Pick a saved connection or type host, port, user and password. LobiShell logs in once with those credentials and appends the key for you.
B — Deploy from an open session
If you are already logged in to the server by password, open the three-dot menu → Deploy public key, select the identity, and confirm. This is the most convenient route when the server is already reachable.
C — Copy it manually
Tap the copy icon next to the public key and paste it into authorized_keys yourself:
Keep a working password login or a second key available until you have confirmed the new key authenticates. Do not lock yourself out.
Step 3 — Link the identity to a connection
Create or edit the connection for your server.
Set Host and Port.
Select the security-key identity you just created. The connection inherits its username and authentication type — you do not set those separately.
Save.
If you deleted the identity that a connection points at, the connection reports a missing identity instead of silently failing. Re-select or remove it.
Step 4 — Authenticate
Open the connection. The terminal shows Waiting for security key and a prompt appears asking for the key over NFC or USB. What happens under the hood:
LobiShell offers your public key to the server.
The server confirms the key is authorised and sends a challenge.
The prompt appears. Hold the key to the phone, or touch the contact if it is plugged in.
If the credential requires verification, LobiShell asks for the PIN and retries.
The token signs the challenge, the signature goes to the server, and the session opens.
If the prompt never appears at all, the failure happened before any signature was requested — the server rejected the offered key, or the key file could not be loaded. See the first two rows of the troubleshooting table.
Troubleshooting
No prompt appears when connecting
The server does not have your key. Compare the line in authorized_keys against the public key shown in the identity, character for character. A line break in the middle of the key silently breaks it.
The key file is passphrase-protected. Encrypted sk key files are not supported. Strip the passphrase on a desktop with ssh-keygen -p -f id_ed25519_sk and re-import.
The key file came from a different token. The handle only resolves on the token that created it. Generate a fresh credential.
The server is older than OpenSSH 8.2 and cannot process this key type.
CTAP2 error codes
Code
Meaning
What to do
0x36
PIN required
Your key has a FIDO2 PIN. Enter it when LobiShell asks. This is expected, not a fault.
0x35
No PIN set on the key
Set a FIDO2 PIN in Yubico Authenticator or YubiKey Manager. Required for resident keys.
0x31
Wrong PIN
Re-enter carefully. The key allows only 8 consecutive wrong PINs before the FIDO2 applet locks and needs a factory reset.
0x32
PIN blocked
Too many wrong attempts. The FIDO2 applet must be reset, which destroys all credentials on it.
0x2E
No credentials
Normal for a verify-required credential before the PIN is supplied — enter the PIN. Otherwise the handle does not belong to this token.
0x2F
Timeout
The touch came too late. Retry and touch the key while it is flashing.
0x2B
Unsupported option
Update LobiShell. Older versions sent an option that non-biometric YubiKey 5 models reject.
The key is not listed in Yubico Authenticator
Expected, unless you enabled Store the key on the YubiKey. Non-resident credentials store nothing on the token, so there is nothing to display. It does not mean the key is missing or fake.
Good practice
Register a backup key. Generate a second credential on a second security key and add both public keys to authorized_keys. You cannot clone a FIDO2 credential, so this is the only way to survive a lost key.
Keep a fallback login until the new key is proven to work.
Back up the key file. It holds no secret on its own, but without it a non-resident credential cannot be used — the token alone is not enough.
Use Require PIN for every login for servers where a stolen, unlocked phone plus the key would be enough to get in.
Free tier and Pro
Security-key authentication is a Pro feature with 5 free logins so you can verify your setup end to end before deciding. The counter only advances on a fully successful login — failed attempts while troubleshooting do not consume it. After that, unlimited security-key authentication requires Pro or the Supporters Edition.