Kbd int (#406)

* Added keyboard interactive authentication on native clients and tests - resolves #389
* Added keyboard interactive tests
* Added keyboard interactive option to HostConfig and tests
* Updated changelog
* Updated docstrings

Author: pkittenis

Changelog.rst

@@ -9,6 +9,15 @@ Changes
 
 * Added compression support for all clients via `SSHClient(compress=True)`, `ParallelSSHClient(compress=True)` and
   `HostConfig(compress=True)` - defaults to off. #252
+* Added "keyboard interactive" login support for native clients. This is fully automated username and password
+  authentication via SSH's keyboard interactive authentication mechanism and does not actually require a human at the
+  keyboard. Used in cases where the server does not allow any other authentication mechanism.
+  Note that server configuration may disallow remote command execution via `run_command` when keyboard interactive
+  authentication is required - use interactive shells to run commands with in such cases. See
+  `Interactive Shells <https://parallel-ssh.readthedocs.io/en/latest/advanced.html#running-commands-on-shells>`_
+  documentation. Also supported via `HostConfig` entries. Currently native clients only.
+* Added `pssh.exceptions.InvalidAPIUseError` for errors raised on client initialisation when an invalid API use is
+  detected. For example, keyboard interactive authentication enabled without a password provided.
 * Updated minimum `ssh2-python` and `ssh-python` requirements.
 
 

pssh/clients/base/parallel.py

@@ -23,7 +23,7 @@
 from gevent import joinall, spawn, Timeout as GTimeout
 from gevent.hub import Hub
 
-from ..common import _validate_pkey_path, _validate_pkey
+from ..common import _validate_pkey_path, _validate_pkey, _validate_api
 from ...config import HostConfig
 from ...constants import DEFAULT_RETRIES, RETRY_DELAY
 from ...exceptions import HostArgumentError, Timeout, ShellError, HostConfigError
@@ -56,6 +56,7 @@ def __init__(self, hosts, user=None, password=None, port=None, pkey=None,
                  gssapi_delegate_credentials=False,
                  forward_ssh_agent=False,
                  compress=False,
+                 keyboard_interactive=False,
                  _auth_thread_pool=True,
                  ):
         self.allow_agent = allow_agent
@@ -88,6 +89,8 @@ def __init__(self, hosts, user=None, password=None, port=None, pkey=None,
         self.gssapi_client_identity = gssapi_client_identity
         self.gssapi_delegate_credentials = gssapi_delegate_credentials
         self.compress = compress
+        self.keyboard_interactive = keyboard_interactive
+        _validate_api(self.keyboard_interactive, self.password)
         self._auth_thread_pool = _auth_thread_pool
         self._check_host_config()
 

pssh/clients/base/single.py

@@ -23,14 +23,14 @@
 
 from gevent import sleep, socket, Timeout as GTimeout
 from gevent.hub import Hub
+from gevent.pool import Pool
 from gevent.select import poll, POLLIN, POLLOUT
 from gevent.socket import SHUT_RDWR
-from gevent.pool import Pool
 from ssh2.exceptions import AgentConnectionError, AgentListIdentitiesError, \
     AgentAuthenticationError, AgentGetIdentityError
 from ssh2.utils import find_eol
 
-from ..common import _validate_pkey
+from ..common import _validate_pkey, _validate_api
 from ..reader import ConcurrentRWBuffer
 from ...constants import DEFAULT_RETRIES, RETRY_DELAY
 from ...exceptions import UnknownHostError, AuthenticationError, \
@@ -227,13 +227,15 @@ def __init__(self, host,
                  identity_auth=True,
                  ipv6_only=False,
                  compress=False,
+                 keyboard_interactive=False,
                  ):
         super(PollMixIn, self).__init__()
         self._auth_thread_pool = _auth_thread_pool
         self.host = host
         self.alias = alias
         self.user = user if user else getuser()
         self.password = password
+        self.keyboard_interactive = keyboard_interactive
         self.port = port if port else 22
         self.num_retries = num_retries
         self.timeout = timeout if timeout else None
@@ -247,6 +249,8 @@ def __init__(self, host,
         self._keepalive_greenlet = None
         self.ipv6_only = ipv6_only
         self.compress = compress
+        self.keyboard_interactive = keyboard_interactive
+        _validate_api(self.keyboard_interactive, self.password)
         self._pool = Pool()
         self._init()
 
@@ -439,7 +443,7 @@ def auth(self):
             msg = "No remaining authentication methods"
             logger.error(msg)
             raise AuthenticationError(msg)
-        logger.debug("Private key auth failed, trying password")
+        logger.debug("Private key auth failed or not enabled, trying password")
         self._password_auth()
 
     def _agent_auth(self):

pssh/clients/common.py

@@ -15,9 +15,12 @@
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+import logging
 import os
 
-from ..exceptions import PKeyFileError
+from ..exceptions import PKeyFileError, InvalidAPIUseError
+
+logger = logging.getLogger('pssh')
 
 
 def _validate_pkey_path(pkey):
@@ -39,3 +42,10 @@ def _validate_pkey(pkey):
     if isinstance(pkey, str):
         return _validate_pkey_path(pkey)
     return pkey
+
+
+def _validate_api(keyboard_interactive, password):
+    if keyboard_interactive and not password:
+        msg = "Keyboard interactive authentication is enabled but no password is provided - cannot continue"
+        logger.error(msg)
+        raise InvalidAPIUseError(msg)

pssh/clients/native/parallel.py

@@ -38,6 +38,7 @@ def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
                  keepalive_seconds=60, identity_auth=True,
                  ipv6_only=False,
                  compress=False,
+                 keyboard_interactive=False,
                  ):
         """
         :param hosts: Hosts to connect to
@@ -118,9 +119,15 @@ def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
         :type ipv6_only: bool
         :param compress: Enable/Disable compression on the client. Defaults to off.
         :type compress: bool
+        :param keyboard_interactive: Enable/Disable keyboard interactive authentication with provided username and
+          password. An `InvalidAPIUse` error is raised when keyboard_interactive is enabled without a provided password.
+          Defaults to off.
+        :type keyboard_interactive: bool
 
         :raises: :py:class:`pssh.exceptions.PKeyFileError` on errors finding
           provided private key.
+        :raises: :py:class:`pssh.exceptions.InvalidAPIUseError` when `keyboard_interactive=True` with no password
+          provided.
         """
         BaseParallelSSHClient.__init__(
             self, hosts, user=user, password=password, port=port, pkey=pkey,
@@ -130,6 +137,7 @@ def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
             identity_auth=identity_auth,
             ipv6_only=ipv6_only,
             compress=compress,
+            keyboard_interactive=keyboard_interactive,
         )
         self.proxy_host = proxy_host
         self.proxy_port = proxy_port

pssh/clients/native/single.py

@@ -111,6 +111,7 @@ def __init__(self, host,
                  identity_auth=True,
                  ipv6_only=False,
                  compress=False,
+                 keyboard_interactive=False,
                  ):
         """
         :param host: Host name or IP to connect to.
@@ -161,9 +162,15 @@ def __init__(self, host,
         :type ipv6_only: bool
         :param compress: Enable/Disable compression on the client. Defaults to off.
         :type compress: bool
+        :param keyboard_interactive: Enable/Disable keyboard interactive authentication with provided username and
+          password. An `InvalidAPIUse` error is raised when keyboard_interactive is enabled without a provided password.
+          Defaults to off.
+        :type keyboard_interactive: bool
 
         :raises: :py:class:`pssh.exceptions.PKeyFileError` on errors finding
           provided private key.
+        :raises: :py:class:`pssh.exceptions.InvalidAPIUseError` when `keyboard_interactive=True` with no password
+          provided.
         """
         self.forward_ssh_agent = forward_ssh_agent
         self._forward_requested = False
@@ -186,6 +193,7 @@ def __init__(self, host,
                 keepalive_seconds=keepalive_seconds,
                 identity_auth=identity_auth,
                 compress=compress,
+                keyboard_interactive=keyboard_interactive,
             )
             proxy_host = '127.0.0.1'
         self._chan_stdout_lock = RLock()
@@ -199,6 +207,7 @@ def __init__(self, host,
             identity_auth=identity_auth,
             ipv6_only=ipv6_only,
             compress=compress,
+            keyboard_interactive=keyboard_interactive,
         )
 
     def _shell(self, channel):
@@ -213,6 +222,7 @@ def _connect_proxy(self, proxy_host, proxy_port, proxy_pkey,
                        keepalive_seconds=60,
                        identity_auth=True,
                        compress=False,
+                       keyboard_interactive=False,
                        ):
         assert isinstance(self.port, int)
         try:
@@ -224,6 +234,7 @@ def _connect_proxy(self, proxy_host, proxy_port, proxy_pkey,
                 identity_auth=identity_auth,
                 keepalive_seconds=keepalive_seconds,
                 compress=compress,
+                keyboard_interactive=keyboard_interactive,
                 _auth_thread_pool=False)
         except Exception as ex:
             msg = "Proxy authentication failed. " \
@@ -320,7 +331,9 @@ def _pkey_from_memory(self, pkey_data):
         )
 
     def _password_auth(self):
-        self.session.userauth_password(self.user, self.password)
+        if self.keyboard_interactive:
+            return self.session.userauth_keyboardinteractive(self.user, self.password)
+        return self.session.userauth_password(self.user, self.password)
 
     def _open_session(self):
         chan = self.eagain(self.session.open_session)

pssh/config.py

@@ -18,6 +18,8 @@
 
 """Host specific configuration."""
 
+from .exceptions import InvalidAPIUseError
+
 
 class HostConfig(object):
     """Host configuration for ParallelSSHClient.
@@ -29,7 +31,7 @@ class HostConfig(object):
                  'proxy_host', 'proxy_port', 'proxy_user', 'proxy_password', 'proxy_pkey',
                  'keepalive_seconds', 'ipv6_only', 'cert_file', 'auth_thread_pool', 'gssapi_auth',
                  'gssapi_server_identity', 'gssapi_client_identity', 'gssapi_delegate_credentials',
-                 'forward_ssh_agent', 'compress',
+                 'forward_ssh_agent', 'compress', 'keyboard_interactive',
                  )
 
     def __init__(self, user=None, port=None, password=None, private_key=None,
@@ -47,6 +49,7 @@ def __init__(self, user=None, port=None, password=None, private_key=None,
                  gssapi_delegate_credentials=False,
                  forward_ssh_agent=False,
                  compress=False,
+                 keyboard_interactive=False,
                  ):
         """
         :param user: Username to login as.
@@ -102,6 +105,13 @@ def __init__(self, user=None, port=None, password=None, private_key=None,
         :type gssapi_delegate_credentials: bool
         :param compress: Enable/Disable compression on the client. Defaults to off.
         :type compress: bool
+        :param keyboard_interactive: Enable/Disable keyboard interactive authentication with provided username and
+          password. An `InvalidAPIUse` error is raised when keyboard_interactive is enabled without a provided password.
+          Defaults to off.
+        :type keyboard_interactive: bool
+
+        :raises: :py:class:`pssh.exceptions.InvalidAPIUseError` when `keyboard_interactive=True` with no password
+          provided.
         """
         self.user = user
         self.port = port
@@ -128,6 +138,9 @@ def __init__(self, user=None, port=None, password=None, private_key=None,
         self.gssapi_client_identity = gssapi_client_identity
         self.gssapi_delegate_credentials = gssapi_delegate_credentials
         self.compress = compress
+        self.keyboard_interactive = keyboard_interactive
+        if self.keyboard_interactive and not self.password:
+            raise InvalidAPIUseError("Keyboard interactive authentication is enabled but no password is provided")
         self._sanity_checks()
 
     def _sanity_checks(self):
@@ -187,3 +200,5 @@ def _sanity_checks(self):
             raise ValueError("GSSAPI delegate credentials %s is not a bool", self.gssapi_delegate_credentials)
         if self.compress is not None and not isinstance(self.compress, bool):
             raise ValueError("Compress %s is not a bool", self.compress)
+        if self.keyboard_interactive is not None and not isinstance(self.keyboard_interactive, bool):
+            raise ValueError("keyboard_interactive %s is not a bool", self.keyboard_interactive)

pssh/exceptions.py

@@ -100,3 +100,7 @@ class ShellError(Exception):
 
 class HostConfigError(Exception):
     """Raised on invalid host configuration"""
+
+
+class InvalidAPIUseError(Exception):
+    """Raised on invalid use of library API"""

tests/test_api_use.py

@@ -0,0 +1,75 @@
+# This file is part of parallel-ssh.
+#
+# Copyright (C) 2014-2025 Panos Kittenis and contributors.
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation, version 2.1.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+
+import unittest
+from unittest.mock import patch, MagicMock
+
+from pssh.clients import ParallelSSHClient, SSHClient
+from pssh.exceptions import InvalidAPIUseError, UnknownHostError
+
+
+class APIUseTest(unittest.TestCase):
+
+    @patch('gevent.socket')
+    @patch('pssh.clients.native.single.Session')
+    def test_kbd_interactive_enabled_single_clients(self, mock_sess, mock_sock):
+        self.assertRaises(UnknownHostError, SSHClient,
+                          'fakehost', password='fake_pass', keyboard_interactive=True, num_retries=0,
+                          timeout=.1,
+                          retry_delay=.1,
+                          _auth_thread_pool=False,
+                          allow_agent=False,
+                          )
+        self.assertRaises(InvalidAPIUseError, SSHClient, 'fakehost', keyboard_interactive=True)
+
+    @patch('gevent.socket')
+    @patch('pssh.clients.native.single.Session')
+    def test_kbd_interactive_enabled_parallel_clients(self, mock_sess, mock_sock):
+        client = ParallelSSHClient(
+            ['fakehost'], password='fake_pass', keyboard_interactive=True, num_retries=0,
+            timeout=.1,
+            retry_delay=.1,
+            allow_agent=False,
+        )
+        self.assertRaises(UnknownHostError, client.run_command, 'echo me')
+        self.assertRaises(InvalidAPIUseError, ParallelSSHClient, ['fakehost'], keyboard_interactive=True)
+
+    @patch('gevent.socket.socket')
+    @patch('pssh.clients.native.single.Session')
+    def test_kbd_interactive_enabled_and_used(self, mock_sess, mock_sock):
+        sess = MagicMock()
+        mock_sess.return_value = sess
+        kbd_auth = MagicMock()
+        password_auth = MagicMock()
+        sess.userauth_keyboardinteractive = kbd_auth
+        sess.userauth_password = password_auth
+        my_user = "my_user"
+        my_pass = "fake_pass"
+
+        client = SSHClient(
+            '127.0.0.1', port=1234, user=my_user, password=my_pass, keyboard_interactive=True, num_retries=0,
+            timeout=.1,
+            retry_delay=.1,
+            _auth_thread_pool=False,
+            allow_agent=False,
+            identity_auth=False,
+        )
+        sess.userauth_keyboardinteractive.assert_called_once_with(my_user, my_pass)
+        sess.userauth_password.assert_not_called()
+        self.assertEqual(client.user, my_user)
+        self.assertEqual(client.password, my_pass)

tests/test_host_config.py

@@ -18,6 +18,7 @@
 import unittest
 
 from pssh.config import HostConfig
+from pssh.exceptions import InvalidAPIUseError
 
 
 class TestHostConfig(unittest.TestCase):
@@ -44,6 +45,7 @@ def test_host_config_entries(self):
         gssapi_client_identity = 'some_id'
         gssapi_delegate_credentials = True
         compress = True
+        keyboard_interactive = True
         cfg = HostConfig(
             user=user, port=port, password=password, alias=alias, private_key=private_key,
             allow_agent=allow_agent, num_retries=num_retries, retry_delay=retry_delay,
@@ -58,6 +60,7 @@ def test_host_config_entries(self):
             gssapi_client_identity=gssapi_client_identity,
             gssapi_delegate_credentials=gssapi_delegate_credentials,
             compress=compress,
+            keyboard_interactive=keyboard_interactive,
         )
         self.assertEqual(cfg.user, user)
         self.assertEqual(cfg.port, port)
@@ -79,6 +82,7 @@ def test_host_config_entries(self):
         self.assertEqual(cfg.gssapi_client_identity, gssapi_client_identity)
         self.assertEqual(cfg.gssapi_delegate_credentials, gssapi_delegate_credentials)
         self.assertEqual(cfg.compress, compress)
+        self.assertEqual(cfg.keyboard_interactive, keyboard_interactive)
 
     def test_host_config_bad_entries(self):
         self.assertRaises(ValueError, HostConfig, user=22)
@@ -106,3 +110,5 @@ def test_host_config_bad_entries(self):
         self.assertRaises(ValueError, HostConfig, gssapi_client_identity=1)
         self.assertRaises(ValueError, HostConfig, gssapi_delegate_credentials='')
         self.assertRaises(ValueError, HostConfig, compress='')
+        self.assertRaises(ValueError, HostConfig, password='fake', keyboard_interactive='')
+        self.assertRaises(InvalidAPIUseError, HostConfig, keyboard_interactive=True)