Keyboard-Interactive Authentication

Keyboard-interactive authentication (RFC 4256) is an SSH authentication method where the server sends arbitrary text prompts and the client responds. ZestSSH handles this method automatically, enabling compatibility with two-factor authentication systems, PAM modules, and non-standard login flows.

Availability

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

Quick Start

Keyboard-interactive authentication is handled automatically. No special configuration is needed. When a server uses this method:

1. Connect normally with your identity configured.
2. If the server sends prompts that look like password requests, ZestSSH responds automatically with your saved password.
3. If the server sends prompts that ZestSSH does not recognize (e.g., a TOTP code), the prompt currently receives an empty response.

How It Works

Many SSH servers — particularly those using PAM (Pluggable Authentication Modules) or running on macOS — use keyboard-interactive authentication instead of (or in addition to) direct password authentication. The server sends one or more prompts, and the client must respond to each.

Prompt Handling

When ZestSSH receives a keyboard-interactive request, it processes each prompt individually:

1. Password-like prompts — If the prompt text contains “password” or “passcode” (case-insensitive), ZestSSH responds with the saved password. This covers the vast majority of keyboard-interactive scenarios.
2. Unrecognized prompts — For prompts that do not match the password pattern, ZestSSH sends an empty string. This is a security measure: a malicious server could present arbitrary prompts designed to harvest credentials, and responding with the password to every prompt would be dangerous.

The request metadata (name, number of prompts) is logged for debugging purposes, but prompt text is not included in user-visible logs to avoid exposing sensitive information.

Typical Server Scenarios

Server Configuration	Behavior
Standard PAM password	ZestSSH responds automatically with the saved password
macOS sshd	Uses keyboard-interactive by default; ZestSSH handles it transparently
TOTP/OTP after password	Password prompt answered automatically; TOTP prompt receives empty response
Custom banner + password	Banner is displayed; password prompt answered automatically
Multi-prompt (password + OTP)	Password prompt answered; OTP prompt receives empty response

Authentication Method Negotiation

SSH servers can advertise multiple authentication methods. ZestSSH’s SSH client handles both password and keyboard-interactive methods:

• The onPasswordRequest callback handles direct SSH_MSG_USERAUTH_REQUEST with method password.
• The onUserInfoRequest callback handles SSH_MSG_USERAUTH_INFO_REQUEST messages from the keyboard-interactive method.

Both callbacks are set when a password is available, ensuring compatibility regardless of which method the server chooses.

Two-Factor Authentication (2FA)

Many organizations require a second authentication factor beyond a password. Common 2FA configurations with SSH include:

• TOTP (Time-based One-Time Password) — Google Authenticator, Authy, or similar apps generate a 6-digit code.
• Push notification — Duo Security or similar services send a push to your phone.
• Hardware token — YubiKey OTP or other token-generated codes.

Current 2FA Behavior

ZestSSH currently handles the password portion of keyboard-interactive authentication automatically. For prompts it does not recognize as password requests (such as a TOTP code prompt), it sends an empty response, which will cause the authentication to fail if a second factor is required.

Workaround for 2FA Servers

If your server requires 2FA via keyboard-interactive:

1. Use public key authentication as the primary method, which may bypass the password + TOTP flow depending on server configuration.
2. Configure the server to accept public key auth without requiring keyboard-interactive 2FA.
3. If TOTP is mandatory, contact your server administrator about alternative authentication methods compatible with automated clients.

Security Design

ZestSSH’s keyboard-interactive handling includes deliberate security measures:

• Selective response — Only prompts containing “password” or “passcode” receive the stored password. All other prompts receive an empty string. This prevents a malicious server from using arbitrary prompts to harvest your password.
• No credential logging — The password is never written to logs. Only the prompt count and request name are logged.
• Prompt inspection — The prompt text is checked case-insensitively, covering variations like “Password:”, “Enter your password:”, “PASSCODE:”, etc.

Limitations

• No interactive prompt UI for 2FA — ZestSSH does not currently display unknown keyboard-interactive prompts to the user for manual input. This means TOTP and similar challenges that the server presents as keyboard-interactive prompts cannot be answered interactively.
• Single password response — All password-like prompts in a single request receive the same password. If a server sends multiple password prompts expecting different credentials, this will not work correctly.
• No prompt retry — If a keyboard-interactive prompt is answered incorrectly (e.g., wrong password), the server typically disconnects. ZestSSH does not retry keyboard-interactive within the same connection attempt.

Troubleshooting

Authentication fails on macOS server

macOS sshd uses keyboard-interactive authentication by default. Ensure:

• The password is saved correctly in the identity.
• The identity is assigned to the connection.
• The server’s sshd_config has ChallengeResponseAuthentication yes (or KbdInteractiveAuthentication yes on newer macOS versions).

Server requires 2FA and connection fails

If the server sends a TOTP or verification code prompt that ZestSSH does not recognize:

• Switch to public key authentication if the server accepts it without 2FA.
• Check if the server can be configured to exempt public key auth from the 2FA requirement.

”Unknown prompt” appears in debug logs

This means the server sent a keyboard-interactive prompt that ZestSSH did not recognize as a password request. The prompt was answered with an empty string. Check the server’s authentication log for the actual prompt text to understand what was expected.

FAQ

Q: Does ZestSSH support Google Authenticator / TOTP? A: ZestSSH handles the password portion of keyboard-interactive automatically. Interactive TOTP entry is not yet supported — ZestSSH sends an empty response to non-password prompts, which will fail if a TOTP code is required.

Q: Why not respond with the password to all prompts? A: This is a security measure. A malicious SSH server could present prompts like “Enter your email password:” or “Enter your bank PIN:” to trick clients into revealing credentials. By only responding to prompts that explicitly ask for a password or passcode, ZestSSH avoids leaking credentials to arbitrary server-controlled prompts.

Q: Can I use public key auth to avoid keyboard-interactive entirely? A: In most cases, yes. If the server accepts public key authentication, it typically does not fall through to keyboard-interactive. Configure your identity with a key pair and ensure the public key is deployed on the server.