Public Key Authentication

Public key authentication is the recommended method for SSH connections. ZestSSH supports generating, importing, and managing SSH key pairs across all platforms. Private keys are stored in the platform’s native keychain, never in the app database.

Availability

Platform	Status
Android	Full support
iOS	Full support
Windows	Full support
macOS	Full support
Linux	Full support

Supported Key Types

ZestSSH supports generating and importing the following key types:

Generation

Key Type	Sizes	Recommended
Ed25519	Fixed (256-bit curve)	Yes — fast, compact, modern
RSA	2048-bit, 4096-bit	4096-bit for legacy compatibility
ECDSA	P-256, P-384, P-521	P-256 or P-384 for NIST compliance

Import

ZestSSH can import private keys in the following formats:

• OpenSSH format (-----BEGIN OPENSSH PRIVATE KEY-----) — The modern default for ssh-keygen. Supports Ed25519, RSA, ECDSA, and Ed448.
• PEM/PKCS#8 format (-----BEGIN RSA PRIVATE KEY----- or -----BEGIN EC PRIVATE KEY-----) — Legacy format, widely compatible.
• Encrypted keys — Both OpenSSH and PEM encrypted keys are supported. ZestSSH detects encryption and prompts for the passphrase.

Supported import key types: RSA, Ed25519, Ed448, ECDSA (P-256, P-384, P-521).

Quick Start

Generate a New Key

1. Navigate to Identities and tap + to create a new identity.
2. Select Public Key as the authentication method.
3. Tap Generate Key.
4. Choose the key format (Ed25519, RSA, or ECDSA) and size.
5. Optionally set a passphrase to protect the private key.
6. Optionally set a comment (defaults to user@ZestSSH).
7. Tap Generate. The public key is displayed for copying.
8. Copy the public key and add it to your server’s ~/.ssh/authorized_keys.

Import an Existing Key

1. Navigate to Identities and tap + to create a new identity.
2. Select Public Key as the authentication method.
3. Tap Import Key and paste your PEM-formatted private key.
4. If the key is encrypted, you will be prompted for the passphrase.
5. The public key is automatically derived from the private key.

How It Works

Authentication Flow

1. ZestSSH loads the identity associated with the connection.
2. The private key PEM is retrieved from secure storage.
3. If the key is passphrase-protected:
   • ZestSSH first tries any saved passphrase.
   • If decryption fails (wrong or missing passphrase), an interactive passphrase prompt is displayed.
   • The user can optionally save the passphrase to the keychain.
4. The key pair is parsed into an SSHKeyPair object.
5. During SSH authentication, the client offers the public key. If the server accepts it, the client signs the authentication challenge with the private key.
6. The server verifies the signature against the public key in authorized_keys.

Key Storage

Component	Storage Location
Private key (PEM)	Platform keychain (Flutter Secure Storage)
Passphrase	Platform keychain (Flutter Secure Storage)
Public key metadata	App database (for display purposes)
Key label / username	App database

Private keys are never written to the filesystem, logged, or transmitted except through the SSH protocol’s authentication channel.

Distributing Your Public Key

After generating or importing a key, you need to add the public key to each server you want to access.

Manual Method

1. Copy the public key from the identity detail screen.
2. On the server, append it to ~/.ssh/authorized_keys:

echo "ssh-ed25519 AAAA... user@ZestSSH" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
chmod 700 ~/.ssh

Using ssh-copy-id (from another machine)

If you have the public key file on another machine with SSH access:

ssh-copy-id -i /path/to/key.pub user@server

Server Configuration

Ensure the SSH server allows public key authentication:

# In /etc/ssh/sshd_config
PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys

Passphrase-Protected Keys

Private keys can be protected with a passphrase for an additional layer of security. If the device is compromised, the attacker would need both access to the keychain and knowledge of the passphrase.

• ZestSSH detects encrypted keys automatically during import or connection.
• An interactive prompt appears asking for the passphrase.
• You can choose to save the passphrase to the keychain so it is not requested on every connection.
• If the wrong passphrase is provided, ZestSSH reports a clear error and does not retry automatically.

Limitations

• No key type conversion — Keys cannot be converted between formats within ZestSSH. Use ssh-keygen on a computer to convert if needed.
• No FIDO2/sk- key types — Hardware security key types ([email protected], [email protected]) are not supported. See FIDO2 Hardware Keys.
• No OpenSSH certificates — Certificate-based authentication (*[email protected]) is not currently supported. See OpenSSH Certificates.
• No SSH agent passthrough — ZestSSH uses its own in-memory key agent rather than connecting to the system’s ssh-agent. Keys in your system agent are not automatically available.

Troubleshooting

”SSH key not found in storage”

The private key was not found in the platform keychain. This can happen if:

• The key was deleted from the keychain by the OS or a security app.
• Secure storage was reset (e.g., after a factory reset or app reinstall without backup).
• The key failed to save during the original import.

Re-import the key from your backup or generate a new one.

”Could not decrypt SSH key”

The passphrase is incorrect. Try re-entering it carefully. If you have forgotten the passphrase, you will need to generate a new key pair.

Server rejects the key

• Verify the public key is in ~/.ssh/authorized_keys on the server.
• Check file permissions: ~/.ssh must be 700, authorized_keys must be 600.
• Ensure the server’s sshd_config has PubkeyAuthentication yes.
• Check AllowUsers or AllowGroups directives are not blocking your user.
• Review server logs (/var/log/auth.log or journalctl -u sshd) for details.

Key works on one server but not another

• Different servers may accept different key types. Some very old servers do not support Ed25519 — try RSA 4096.
• Check that the correct public key is deployed on the target server.

FAQ

Q: Which key type should I choose? A: Ed25519 is recommended for most users. It is fast, produces compact keys, and is supported by all modern SSH servers (OpenSSH 6.5+). Use RSA 4096 only if you need compatibility with very old servers.

Q: Can I use the same key for multiple servers? A: Yes. One identity (key pair) can be assigned to multiple connections. The same public key is added to authorized_keys on each server.

Q: Can I export my private key? A: ZestSSH allows sharing the public key for deployment. Private keys are stored in the platform keychain and can be viewed/copied from the identity detail screen for backup purposes.

Q: What happens if I lose my private key? A: If the private key is lost (e.g., app uninstall without backup), you will need to generate a new key pair and redeploy the public key to your servers. There is no way to recover a lost private key.