Keyboard Interactive Authentication

SSHClient supports keyboard interactive authentication as defined by RFC 4256. Depending on the requirements of the SSH server, it can be used instead of password authentication.

Keyboard interactive is a general purpose authentication method, suitable for interactive authentications where the authentication data is entered via a keyboard or equivalent alphanumeric input device. The major goal of this method is to allow the SSH client to support a whole class of authentication mechanisms without knowing the specifics of the actual authentication mechanisms.

In practical terms, with keyboard interactive authentication, the SSH server sends text prompts to the client. These prompts must be given a text answer to. The client sends the responses back to the server. If accepted, more prompts can be sent to the client for response or the authentication can be declared successful or failed.

The text prompts are arbitrary strings. There are no standard or predefined texts. The server decides the content of the prompts and what the required response is. As such, the SSHClient class cannot parse or process the prompts it receives as part of keyboard interactive authentication. Your application must process the prompts and supply responses programmatically or display the prompts to the end-user for them to type the responses.

To authenticate with keyboard interactive, call Authenticate with a userName and a KeyBoardInteractiveAuthenticationHandler delegate.

The delegate KeyBoardInteractiveAuthenticationHandler is a callback method that will be invoked as part of keyboard interactive authentication. It is defined as follows:

Where:

userName is the user name that was specified in the call to the Authenticate method.

name is a server-supplied string that may indicate a logical name for the series of requests. It can be an empty string, but it will not be null.

instruction is a server-supplied string that may indicate instructions on how to respond to the series of requests. It can be an empty string, but it will not be null.

languageTag is a string that specifies the language of the messages. In most cases, this parameter will be an empty string, and the language will be English.

requests is an array of KeyboardInteractiveRequest objects that specify the information prompts and their responses. The array will not be null. Each element in the array represents a prompt that must be answered. The response for each element is prefilled with an empty string. It is possible that the array will be empty, but it will not be null.

KeyboardInteractiveRequest is a simple class that holds the following properties:

Prompt is the server-supplied string that specifies what information is required. For example, it could be something like "Password:". There are no pre-defined prompt strings. The server can supply any text it wants here.

Echo is a boolean value that specifies whether the response to the prompt should be echoed to the screen. In general, this value will be false when the prompt refers to sensitive information like passwords and true otherwise.

Response is the string that will contain the response to the prompt. Your handler will set the this property's value. The string will then be sent back to the server for authentication. The response can be set to an empty string. If the property is set to null, an empty string will be sent back to the server.

Each request in the requests array represents a prompt. If the prompts are presented to an end-user, each prompt should be displayed to the user one by one and in order. The requests array will typically contain one prompt but it might contain more. The KeyBoardInteractiveAuthenticationHandler might be called again with more prompts. There is no predefined limit on the number of prompts that may be asked.

The KeyBoardInteractiveAuthenticationHandler will be invoked by the component on the same thread that Authenticate() was called on. Authenticate() will therefore block while it waits for the KeyBoardInteractiveAuthenticationHandler to return. The component does not impose any timeout on how long control can stay in the handler. However, be aware that some SSH servers enforce a limit on how long authentication takes. For example, the default limit on the OpenSSH server is 120 seconds.

How to implement KeyBoardInteractiveAuthenticationHandler

If you are certain of the contents and formatting of the prompts you will receive from the server, you may implement a KeyBoardInteractiveAuthenticationHandler method that processes and answers the prompts automatically.

Consider this example for OpenSSH servers that use the ChallengeResponseAuthentication option:

C#
VB.NET

public static void KeyBoardInteractiveAuthenticationHandlerLinuxPAM( string userName, string name, string instruction, string languageTag, KeyboardInteractiveRequest[] requests )
{
  // If we have a request
  if( requests.Length > 0 )
  {
    // If the first request is the string 'Password: '
    if( StringComparer.OrdinalIgnoreCase.Compare( requests[ 0 ].Prompt, "Password: " ) == 0 )
    {
      // Supply our password as the response
      requests[ 0 ].Response = "<your password>";
    }
  }
}

Public Shared Sub KeyBoardInteractiveAuthenticationHandlerLinuxPAM(ByVal userName As String, ByVal name As String, ByVal instruction As String, ByVal languageTag As String, ByVal requests() As KeyboardInteractiveRequest)
  ' If we have a request
  If requests.Length > 0 Then
    ' If the first request is the string 'Password: '
    If StringComparer.OrdinalIgnoreCase.Compare(requests(0).Prompt, "Password: ") = 0 Then
      ' Supply our password as the response
      requests(0).Response = "<your password>"
    End If
  End If
End Sub

Another way to approach this authentication is to display the prompts to the console and accept input for the answers.

C#
VB.NET

public static void KeyBoardInteractiveAuthenticationHandlerConsole( string userName, string name, string instruction, string languageTag, KeyboardInteractiveRequest[] requests )
{
  // If the name is non-empty
  if( !String.IsNullOrEmpty( name ) )
  {
    // Display it
    Console.WriteLine( name );
  }

  // If the instruction is non-empty
  if( !String.IsNullOrEmpty( instruction ) )
  {
    // Display it
    Console.WriteLine( instruction );
  }

  // If we have a request
  if( requests.Length > 0 )
  {
    // Go through each request in order
    foreach( KeyboardInteractiveRequest request in requests )
    {
      // Display the prompt
      Console.Write( request.Prompt );

      // If we can display the response as it is being typed
      if( request.Echo )
      {
        // Read the next line of text from the console
        request.Response = Console.ReadLine();
      }
      // We can't display the response
      else
      {
        StringBuilder response = new StringBuilder();

        // Read a key without displaying it
        ConsoleKeyInfo keyInfo = Console.ReadKey( true );

        // Until <Enter> is pressed
        while( keyInfo.Key != ConsoleKey.Enter )
        {
          // Add it to the response
          response.Append( keyInfo.KeyChar );

          // Read a key without displaying it
          keyInfo = Console.ReadKey( true );
        }

        // Store the response string in the request
        request.Response = response.ToString();
      }
    }
  }
}

Public Shared Sub KeyBoardInteractiveAuthenticationHandlerConsole(ByVal userName As String, ByVal name As String, ByVal instruction As String, ByVal languageTag As String, ByVal requests() As KeyboardInteractiveRequest)
  ' If the name is non-empty
  If (Not String.IsNullOrEmpty(name)) Then
    ' Display it
    Console.WriteLine(name)
  End If

  ' If the instruction is non-empty
  If (Not String.IsNullOrEmpty(instruction)) Then
    ' Display it
    Console.WriteLine(instruction)
  End If

  ' If we have a request
  If requests.Length > 0 Then
    ' Go through each request in order
    For Each request As KeyboardInteractiveRequest In requests
      ' Display the prompt
      Console.Write(request.Prompt)

      ' If we can display the response as it is being typed
      If request.Echo Then
        ' Read the next line of text from the console
        request.Response = Console.ReadLine()
        ' We can't display the response
      Else
        Dim response As New StringBuilder()

        ' Read a key without displaying it
        Dim keyInfo As ConsoleKeyInfo = Console.ReadKey(True)

        ' Until <Enter> is pressed
        Do While keyInfo.Key <> ConsoleKey.Enter
          ' Add it to the response
          response.Append(keyInfo.KeyChar)

          ' Read a key without displaying it
          keyInfo = Console.ReadKey(True)
        Loop

        ' Store the response string in the request
        request.Response = response.ToString()
      End If
    Next request
  End If
End Sub

Here's an example that puts it all together, with the exceptions that Authenticate can throw when called for the keyboard interactive method.

C#
VB.NET

static void Example()
{
  string host = "<host>";
  string username = "<username>";

  using( SSHClient ssh = new SSHClient() )
  {
    ssh.Connect( host );

    KeyBoardInteractiveAuthenticationHandler consoleHandler = new KeyBoardInteractiveAuthenticationHandler( KeyBoardInteractiveAuthenticationHandlerConsole );

    bool retry = false;

    do
    {
      try
      {
        // Authenticate with the keyboard interactive method
        ssh.Authenticate( username, consoleHandler );
      }
      // Authentication was successful but more authentication is required by the server
      catch( SSHAuthenticationPartialSuccessException e )
      {
        // The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
        e.AuthenticationsThatCanContinue.ToString();

        throw;
      }
      // The server rejected one of the keyboard response the user typed. Authentication has failed
      catch( SSHIncorrectResponseException e )
      {
        SSHAuthenticationFailedException authenticationFailedException = e.InnerException as SSHAuthenticationFailedException;

        if( authenticationFailedException != null )
        {
          // The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
          authenticationFailedException.AuthenticationsThatCanContinue.ToString();
        }

        /* TODO: Decide if it is wise to retry the keyboard interactive method, how many times, etc */
        retry = true;

        if( !retry )
        {
          throw;
        }
      }
      catch( SSHUnsupportedAuthenticationMethodException e )
      {
        // The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
        e.AuthenticationsThatCanContinue.ToString();

        throw;
      }
      catch( SSHAuthenticationFailedException e )
      {
        // The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
        e.AuthenticationsThatCanContinue.ToString();

        throw;
      }
    }
    while( retry );

    /* TODO: Perform SSH/SFtp operations */
    using( SFtpSession sftp = new SFtpSession( ssh ) )
    {

    }
  }
}

Private Shared Sub Example()
  Dim host As String = "<host>"
  Dim username As String = "<username>"

  Using ssh As New SSHClient()
    ssh.Connect(host)

    Dim consoleHandler As New KeyBoardInteractiveAuthenticationHandler(AddressOf KeyBoardInteractiveAuthenticationHandlerConsole)

    Dim retry As Boolean = False

    Do
      Try
        ' Authenticate with the keyboard interactive method
        ssh.Authenticate(username, consoleHandler)
        ' Authentication was successful but more authentication is required by the server
      Catch e As SSHAuthenticationPartialSuccessException
        ' The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
        e.AuthenticationsThatCanContinue.ToString()

        Throw
        ' The server rejected one of the keyboard response the user typed. Authentication has failed
      Catch e As SSHIncorrectResponseException
        Dim authenticationFailedException As SSHAuthenticationFailedException = TryCast(e.InnerException, SSHAuthenticationFailedException)

        If authenticationFailedException IsNot Nothing Then
          ' The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
          authenticationFailedException.AuthenticationsThatCanContinue.ToString()
        End If

        ' TODO: Decide if it is wise to retry the keyboard interactive method, how many times, etc 
        retry = True

        If (Not retry) Then
          Throw
        End If
      Catch e As SSHUnsupportedAuthenticationMethodException
        ' The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
        e.AuthenticationsThatCanContinue.ToString()

        Throw
      Catch e As SSHAuthenticationFailedException
        ' The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
        e.AuthenticationsThatCanContinue.ToString()

        Throw
      End Try
    Loop While retry

    ' TODO: Perform SSH/SFtp operations 
    Using sftp As New SFtpSession(ssh)

    End Using
  End Using
End Sub

Some servers require multiple authentications be used to log in. Here is an example that chains different authentications one after the other.

C#
VB.NET

static void ChainingExample()
{
  string host = "<host>";
  string username = "<username>";
  string password = "<password>";

  using( SSHClient ssh = new SSHClient() )
  {
    ssh.Connect( host );

    bool needsMoreAuthentication = false;

    try
    {
      // Authenticate with the username/password method
      ssh.Authenticate( username, password );
    }
    // Authentication was successful but more authentication is required by the server
    catch( SSHAuthenticationPartialSuccessException e )
    {
      /* We have successfully authenticated with username/password, but the server needs us
       * to use additional authentication methods */
      needsMoreAuthentication = true;

      // The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
      e.AuthenticationsThatCanContinue.ToString();
    }
    catch( SSHUnsupportedAuthenticationMethodException e )
    {
      /* The server doesn't support this authentication. We will use additional authentication
        * methods we support */
      needsMoreAuthentication = true;

      // The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
      e.AuthenticationsThatCanContinue.ToString();
    }
    catch( SSHAuthenticationFailedException e )
    {
      // The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
      e.AuthenticationsThatCanContinue.ToString();

      throw;
    }

    // If we need to perform more authentication
    if( needsMoreAuthentication )
    {
      /* We will use the other authentication method we have */

      KeyBoardInteractiveAuthenticationHandler consoleHandler = new KeyBoardInteractiveAuthenticationHandler( KeyBoardInteractiveAuthenticationHandlerConsole );

      bool retry = false;

      do
      {
        try
        {
          // Authenticate with the keyboard interactive method
          ssh.Authenticate( username, consoleHandler );

          // If we reach here, we have used all our authentication methods and they have been successful
          needsMoreAuthentication = false;
        }
        // Authentication was successful but more authentication is required by the server
        catch( SSHAuthenticationPartialSuccessException e )
        {
          /* At this point, we are out of authentication methods... */

          throw new Exception( "Can't authenticate. Used up all authentication methods we support.", e );
        }
        // The server rejected one of the keyboard response the user typed. Authentication has failed
        catch( SSHIncorrectResponseException e )
        {
          SSHAuthenticationFailedException authenticationFailedException = e.InnerException as SSHAuthenticationFailedException;

          if( authenticationFailedException != null )
          {
            // The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
            authenticationFailedException.AuthenticationsThatCanContinue.ToString();
          }

          /* TODO: Decide if it is wise to retry the keyboard interactive method, how many times, etc */
          retry = true;

          if( !retry )
          {
            throw;
          }
        }
        catch( SSHUnsupportedAuthenticationMethodException e )
        {
          // The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
          e.AuthenticationsThatCanContinue.ToString();

          /* At this point, we are out of authentication methods... */

          throw new Exception( "Can't authenticate. Used up all authentication methods we support.", e );
        }
        catch( SSHAuthenticationFailedException e )
        {
          // The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
          e.AuthenticationsThatCanContinue.ToString();

          throw;
        }
      }
      while( retry );
    }

    /* TODO: Perform SSH/SFtp operations */
    using( SFtpSession sftp = new SFtpSession( ssh ) )
    {

    }
  }
}

Private Shared Sub ChainingExample()
  Dim host As String = "<host>"
  Dim username As String = "<username>"
  Dim password As String = "<password>"

  Using ssh As New SSHClient()
    ssh.Connect(host)

    Dim needsMoreAuthentication As Boolean = False

    Try
      ' Authenticate with the username/password method
      ssh.Authenticate(username, password)
      ' Authentication was successful but more authentication is required by the server
    Catch e As SSHAuthenticationPartialSuccessException
      '           We have successfully authenticated with username/password, but the server needs us
      '           * to use additional authentication methods 
      needsMoreAuthentication = True

      ' The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
      e.AuthenticationsThatCanContinue.ToString()
    Catch e As SSHUnsupportedAuthenticationMethodException
      '           The server doesn't support this authentication. We will use additional authentication
      '            * methods we support 
      needsMoreAuthentication = True

      ' The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
      e.AuthenticationsThatCanContinue.ToString()
    Catch e As SSHAuthenticationFailedException
      ' The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
      e.AuthenticationsThatCanContinue.ToString()

      Throw
    End Try

    ' If we need to perform more authentication
    If needsMoreAuthentication Then
      ' We will use the other authentication method we have 

      Dim consoleHandler As New KeyBoardInteractiveAuthenticationHandler(AddressOf KeyBoardInteractiveAuthenticationHandlerConsole)

      Dim retry As Boolean = False

      Do
        Try
          ' Authenticate with the keyboard interactive method
          ssh.Authenticate(username, consoleHandler)

          ' If we reach here, we have used all our authentication methods and they have been successful
          needsMoreAuthentication = False
          ' Authentication was successful but more authentication is required by the server
        Catch e As SSHAuthenticationPartialSuccessException
          ' At this point, we are out of authentication methods... 

          Throw New Exception("Can't authenticate. Used up all authentication methods we support.", e)
          ' The server rejected one of the keyboard response the user typed. Authentication has failed
        Catch e As SSHIncorrectResponseException
          Dim authenticationFailedException As SSHAuthenticationFailedException = TryCast(e.InnerException, SSHAuthenticationFailedException)

          If authenticationFailedException IsNot Nothing Then
            ' The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
            authenticationFailedException.AuthenticationsThatCanContinue.ToString()
          End If

          ' TODO: Decide if it is wise to retry the keyboard interactive method, how many times, etc 
          retry = True

          If (Not retry) Then
            Throw
          End If
        Catch e As SSHUnsupportedAuthenticationMethodException
          ' The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
          e.AuthenticationsThatCanContinue.ToString()

          ' At this point, we are out of authentication methods... 

          Throw New Exception("Can't authenticate. Used up all authentication methods we support.", e)
        Catch e As SSHAuthenticationFailedException
          ' The 'AuthenticationsThatCanContinue' property specifies the authentications methods that can be tried
          e.AuthenticationsThatCanContinue.ToString()

          Throw
        End Try
      Loop While retry
    End If

    ' TODO: Perform SSH/SFtp operations 
    Using sftp As New SFtpSession(ssh)

    End Using
  End Using
End Sub

General information

RFC 4256