Password Authentication
Password authentication is the simplest method for connecting to SSH servers. ZestSSH sends the configured password to the server during the SSH handshake and securely stores credentials using the platform’s native keychain.
Availability
Section titled “Availability”| Platform | Status |
|---|---|
| Android | Full support (Android Keystore) |
| iOS | Full support (iOS Keychain) |
| Windows | Full support (Windows Credential Manager) |
| macOS | Full support (macOS Keychain) |
| Linux | Full support (libsecret / GNOME Keyring) |
Quick Start
Section titled “Quick Start”- Navigate to Identities and tap + to create a new identity.
- Enter a label (e.g., “My Server Login”), username, and select Password as the auth method.
- Enter your password. It is stored in the platform keychain, not in the app’s database.
- Assign this identity to a connection, then connect.
Alternatively, when connecting without a saved identity, ZestSSH prompts for a password interactively with an option to save it.
How It Works
Section titled “How It Works”Saved Password Flow
Section titled “Saved Password Flow”- When a connection starts, ZestSSH loads the associated identity from the database.
- If the identity uses password authentication, the password is retrieved from Flutter Secure Storage (which delegates to the platform’s native keychain).
- The password is supplied to the SSH client via the
onPasswordRequestcallback during authentication. - If the server also sends keyboard-interactive prompts, ZestSSH responds to password-like prompts automatically (see Keyboard-Interactive).
Interactive Password Prompt
Section titled “Interactive Password Prompt”When no password is saved for a connection, ZestSSH shows an interactive password dialog:
- A dialog appears with the host and username pre-filled.
- You enter the password.
- Optionally check “Save password” to store it in the keychain for future connections.
- If saved, a new identity is created (or the existing one is updated) with the password in secure storage.
- The prompt has a 2-minute timeout to prevent indefinite hangs if the dialog fails to display.
Secure Storage
Section titled “Secure Storage”Passwords are never stored in the SQLite database or in plaintext files. ZestSSH uses Flutter Secure Storage, which maps to:
| Platform | Backend |
|---|---|
| Android | Android Keystore (AES-256 encrypted SharedPreferences) |
| iOS | iOS Keychain Services |
| Windows | Windows Credential Manager (DPAPI) |
| macOS | macOS Keychain Services |
| Linux | libsecret (GNOME Keyring or KDE Wallet) |
Security Notes
Section titled “Security Notes”- Password-based SSH authentication is less secure than public key authentication. If your server supports it, consider switching to Public Key Authentication.
- Passwords are transmitted over the encrypted SSH channel but are sent in cleartext within the encrypted tunnel. A compromised server can capture your password.
- ZestSSH does not log, cache, or transmit passwords outside of the SSH authentication flow. Debug logs from the SSH library are filtered to exclude credential data.
- On Windows, secure storage may occasionally fail (e.g., after a Windows update or profile migration). If this happens, ZestSSH falls back to prompting for the password interactively.
Limitations
Section titled “Limitations”- If the platform keychain is unavailable or corrupt, password retrieval will fail. ZestSSH will fall back to an interactive prompt.
- Password authentication must be enabled on the server (
PasswordAuthentication yesinsshd_config). Many hardened servers disable it. - There is no support for automatically rotating or expiring saved passwords.
Troubleshooting
Section titled “Troubleshooting””Authentication failed” with a correct password
Section titled “”Authentication failed” with a correct password”- Confirm the server allows password authentication in its
sshd_config. - Check if the server uses PAM, which may require keyboard-interactive instead of direct password auth. ZestSSH handles this automatically, but some PAM configurations may present unexpected prompts.
- Verify there are no leading/trailing spaces in the saved password.
Password prompt does not appear
Section titled “Password prompt does not appear”- The prompt dialog is displayed by the terminal screen. If you navigate away from the terminal before the prompt appears, it may not show. Return to the terminal screen.
- The prompt times out after 2 minutes. If the connection is very slow, you may need to retry.
”Failed to read identity credentials from secure storage”
Section titled “”Failed to read identity credentials from secure storage””- The platform keychain may be locked or unavailable. On Linux, ensure GNOME Keyring or a compatible secret service is running.
- On Windows, this can occur after profile migration. ZestSSH will prompt for the password interactively as a fallback.
Q: Is my password stored in plaintext? A: No. Passwords are stored in the platform’s native keychain, which encrypts them at rest. They are never written to the app database or log files.
Q: Can I see my saved password? A: ZestSSH does not provide a way to view saved passwords. You can update or delete them through the identity editor.
Q: What happens if I enter the wrong password? A: The SSH server will reject the authentication attempt. ZestSSH reports the error and you can retry the connection.