Keys and sign-in methods

Where you choose it

Open a host with Edit (or add one). Sign-in settings live in two places in the host form:

• General tab. Username, Password, Save password to OS keychain, and the Stored in an external secret manager instead? list. A host with nothing else chosen signs in with this password.
• Authentication tab. The How do you sign in? row: SSH Key, SSH Agent, FIDO2, Passkey, PKCS#11 and Interactive. The Add SSH Key, Certificate, or FIDO2 button at the bottom of the General tab jumps here.

The same tab has Use an Identity at the top. Picking an identity hides the method row, because the identity supplies it. See Identities and groups. For signing in with short-lived certificates, see SSH certificates.

Which method should I use?

If you are unsure: generate an Ed25519 key in MangoSSH, put its public half on the server, and use SSH Key → Key Only. Move to FIDO2, PKCS#11 or Passkey when you want the key to be impossible to copy off the machine.

Password

1. On the General tab, fill in Username and Password.

2. Tick Save password to OS keychain to keep it in Windows Credential Manager, the macOS Keychain or the Linux Secret Service. Leave it unticked and the password is discarded on save; MangoSSH asks for it every time you connect.

Leaving the password blank is fine. The connect dialog asks for it, and offers to remember it then.

Key files

1. On the Authentication tab, click SSH Key.

2. Under Which kind of key auth?, choose one:

   • Key Only: the key alone logs you in. Pick this unless the server wants more.
   • Key + Password: MangoSSH offers the key first and, if that does not complete the login, sends the password from the General tab. Use it for servers that require both (AuthenticationMethods publickey,password).
   • Key + Interactive Login: the key, then the server's own prompts (an OTP code, a Duo push). For servers set to AuthenticationMethods publickey,keyboard-interactive. See Keyboard-interactive and TOTP codes.

3. Set Private key file path, or click Browse…. A relative path is resolved from your home folder, so .ssh/id_ed25519 works.

4. If the key is encrypted, enter Passphrase (if encrypted) and tick Save passphrase, or leave it blank to be asked on connect. MangoSSH checks the file first and only asks when the key really is encrypted.

Keys must be in OpenSSH or PEM format (the file starts with -----BEGIN). If you only have a PuTTY .ppk file, export it from PuTTYgen with Conversions → Export OpenSSH key.

For RSA keys, MangoSSH tries the modern rsa-sha2-512 and rsa-sha2-256 signatures first and falls back to legacy ssh-rsa only for servers too old to accept anything else.

Generate and manage keys

Open SSH Keys from the sidebar. The page lists every key MangoSSH has generated or imported, with its type, fingerprint and age. The private halves are kept encrypted with a key held in your OS keychain.

Generate a key

1. Click Generate. Give the key a name and pick Ed25519 (recommended) or RSA 4096. Use RSA only for servers that do not accept Ed25519. The passphrase is optional.

2. Click Generate. Copy the public key (Copy Public Key or Save .pub File) and add it to the server's ~/.ssh/authorized_keys.

3. Click Save Private Key File and save it somewhere stable, such as your .ssh folder. A host needs a real file path, so paste that path into the host's Private key file path.

Lost the file? The key's row in the list has a save private key file button that exports it again. Import adds a key you already have: paste the PEM text or use Browse File…, and add the public key if you want to deploy it later.

Deploy, rotate and remove keys on servers

Manage on Hosts… edits ~/.ssh/authorized_keys on servers you are currently connected to. Connect to the targets first, then open it and tick the hosts.

Rotation warns you if the old key's line carries restrictions (such as from= or command=) that the new key would not inherit. When it finishes, it asks you to save the new private key. Point your hosts' Private key file path at that file; rotation does not edit saved hosts for you.

Age badges help you decide when to rotate: green under 90 days, amber under a year, red after.

SSH agent

With SSH Agent, MangoSSH asks your running agent to sign the login. The private key never touches MangoSSH, which offers each key the agent holds until the server accepts one. The accepted key's algorithm and fingerprint go into the audit log.

• Windows: MangoSSH talks to the Windows OpenSSH agent on \\.\pipe\openssh-ssh-agent. Pageant is not supported. Start the service once, as administrator:

  Get-Service ssh-agent | Set-Service -StartupType Automatic
  Start-Service ssh-agent
  ssh-add $HOME\.ssh\id_ed25519

• macOS and Linux: SSH_AUTH_SOCK must be set in the environment MangoSSH starts from. Desktop sessions usually set it for you.

Run ssh-add -l before connecting to check the agent actually holds your key. To use your agent from inside the remote shell as well, turn on agent forwarding on the host's Session tab.

FIDO2 security keys

FIDO2 keys (sk-ssh-ed25519, sk-ecdsa) are used through your SSH agent. Click FIDO2 on the Authentication tab; the host is saved with the agent method, and the touch prompt happens on the physical key when the server asks for a signature.

1. Create a key on the security key, if you do not have one. A resident key can be loaded again on any machine:

   ssh-keygen -t ed25519-sk -O resident

2. Add the .pub line to the server's ~/.ssh/authorized_keys. The server needs OpenSSH 8.2 or later.

3. Load it into your agent: ssh-add -K loads resident keys from the device; ssh-add ~/.ssh/id_ed25519_sk loads a key file.

4. Connect, and touch the key when it blinks.

Smartcards and YubiKey PIV (PKCS#11)

PKCS#11 signs the login directly on a smartcard, CAC/PIV card or a YubiKey in PIV mode, with no agent in between. The private key never leaves the token.

1. Install a PKCS#11 module. MangoSSH does not bundle one. OpenSC (opensc-pkcs11.dll / .so) works with most cards; Yubico ships ykcs11.

2. Click PKCS#11. Fill in PKCS#11 module path (or Browse…) and the token PIN, and tick Save PIN to OS keychain.

3. Insert the token and click Detect Keys. Pick the key from the Key list; each entry shows its label and slot.

4. Put the token's public key on the server. OpenSSH can read it straight from the module:

   ssh-keygen -D /path/to/opensc-pkcs11.so   # prints one line per key; add the right one to authorized_keys

Windows Hello and the Mac Secure Enclave

Passkey creates an SSH key inside your computer's own security hardware: the TPM through Windows Hello on Windows (RSA 2048), or the Secure Enclave on a Mac (ECDSA P-256). The key cannot be exported, and every connect asks for your Hello PIN, face or fingerprint, or Touch ID. It is not available on Linux.

1. Click Passkey. The status line says whether the hardware is available and whether a key already exists.

2. Click Generate Key and approve the prompt.

3. Click Copy next to Public key and add the line to each server's ~/.ssh/authorized_keys.

There is one such key per computer, shared by every host that uses this method. Generating again replaces it, so every server then needs the new public line.

Keyboard-interactive and TOTP codes

Some servers run their own login conversation (PAM with an OTP module, Duo, RADIUS). Click Interactive for that, or use Key + Interactive Login when the server wants a key first. MangoSSH shows a dialog for each round of questions and stores nothing. An unanswered dialog cancels the connection after three minutes.

Let MangoSSH answer the code

Both interactive modes show TOTP auto-fill (optional). Paste the Base32 secret your authenticator app was set up with (the text usually shown under the QR code) into Secret (Base32), and tick Save secret to OS keychain. MangoSSH then generates the 6-digit code itself.

It only answers a round that asks exactly one hidden question worded like a code prompt ("Verification code", "OTP", "authenticator", "one-time" and similar). A round that asks for a password, or several things at once, still opens the dialog. Leave the secret blank to keep typing codes yourself.

Passwords from a secret manager

If the password already lives in a secret manager, MangoSSH can fetch it at connect time instead of storing a copy. On the General tab, choose the source under Stored in an external secret manager instead?. MangoSSH runs that tool's command line, so the CLI must be installed, on your PATH and signed in.

To go back to a stored password, pick None — use the password above. For passwords kept inside MangoSSH itself, see the Password manager.

Host key verification

Before any credential is sent, MangoSSH checks the server's host key, so you know you are talking to the machine you think you are.

• First connect. An Unknown Host Key dialog shows the key type and SHA256 fingerprint. Compare it with the server's own (ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the server), then click Yes, Trust & Connect or No, Cancel. MangoSSH also looks at your OpenSSH ~/.ssh/known_hosts, and PuTTY's saved keys on Windows. If either holds a different key for this host, or marks this key @revoked, the dialog says so.
• Changed key. If the server later presents a different key, a Host key has changed dialog shows the old and new fingerprints. That can be a reinstalled server or a recycled IP, or it can be an attack. Only click Replace & Connect when you know why it changed.
• Nobody answers. An unanswered prompt counts as No after two minutes.
• Scripts and jump-host hops cannot show a dialog. They trust a brand-new key silently, but refuse a changed one, and refuse a new key that your OpenSSH or PuTTY records contradict.

On the host's Advanced tab, Trusted host key (TOFU) shows the stored fingerprint, and Forget Host Key clears it so the next connect asks again. The same tab has Strict mode (modern algorithms only — no ssh-rsa / SHA-1 / CBC) for servers where you want to rule out legacy algorithms. Revocation lists for certificates are covered in SSH certificates.

Troubleshooting