KSshProcess Class Reference

#include <ksshprocess.h>

List of all members.

Classes

class  SshOpt

Public Types

enum  SshVersion {
  OPENSSH_3_6, OPENSSH, SSH, SSH_VER_MAX,
  UNKNOWN_VER
}
enum  SshOptType {
  SSH_SUBSYSTEM, SSH_PORT, SSH_HOST, SSH_USERNAME,
  SSH_PASSWD, SSH_PROTOCOL, SSH_FORWARDX11, SSH_FORWARDAGENT,
  SSH_ESCAPE_CHAR, SSH_COMMAND, SSH_VERBOSE, SSH_OPTION,
  SSH_OTHER, SSH_OPT_MAX
}
enum  SshError {
  ERR_UNKNOWN_VERSION, ERR_CANNOT_LAUNCH, ERR_INTERACT, ERR_CMD_SUBSYS_CONFLICT,
  ERR_NEED_PASSWD, ERR_NEED_PASSPHRASE, ERR_NEED_USERNAME, ERR_TIMED_OUT,
  ERR_INTERNAL, ERR_DISCONNECTED, ERR_NO_OPTIONS, ERR_NEW_HOST_KEY,
  ERR_DIFF_HOST_KEY, ERR_HOST_KEY_REJECTED, ERR_INVALID_OPT, ERR_ACCEPTED_KEY,
  ERR_AUTH_FAILED, ERR_AUTH_FAILED_NEW_KEY, ERR_AUTH_FAILED_DIFF_KEY, ERR_CLOSED_BY_REMOTE_HOST,
  ERR_UNKNOWN, ERR_INVALID_STATE, ERR_MAX
}
typedef TQValueList< SshOptSshOptList
typedef TQValueListIterator
< SshOpt
SshOptListIterator
typedef
TQValueListConstIterator
< SshOpt
SshOptListConstIterator

Public Member Functions

 KSshProcess ()
 KSshProcess (TQString pathToSsh)
bool setSshPath (TQString pathToSsh)
SshVersion version ()
int error (TQString &msg)
int error ()
TQString errorMsg ()
void kill (int signal=SIGKILL)
int pid ()
bool connected ()
bool running ()
void printArgs ()
bool setOptions (const SshOptList &opts)
bool connect ()
void disconnect ()
void acceptHostKey (bool accept)
void setPassword (TQString password)
int stdioFd ()
int stderrFd ()
int pty ()

Detailed Description

Provides version independent access to ssh. Currently supported versions of SSH are: OpenSSH 2.9p1 OpenSSH 2.9p2 OpenSSH 3.0 OpenSSH 3.1 Commercial SSH 3.0.0 Other versions of OpenSSH and commerical SSH will probably work also.

To setup a SSH connection first create a list of options to use and tell KSshProcess about your options. Then start the ssh connection. Once the connection is setup use the stdin, stdout, stderr, and pty file descriptors to communicate with ssh. For a detailed example of how to use, see ksshprocesstest.cpp.

Author:
Lucas Fisher

Example: Connect to ssh server on localhost KSshProcess::SshOpt opt; KSshProcess::SshOptList options;

opt.opt = KSshProcess::SSH_HOST; opt.str = "localhost"; options.append(opt);

opt.opt = KSshProcess::SSH_USERNAME; opt.str = "me"; options.append(opt);

KSshProcess ssh; if( !ssh.setOptions(options) ) { int err = ssh.error(); // process error return false; }

int err; TQString errMsg; while( !ssh.connect() ) { err = ssh.error(errMsg);

switch( err ) { case KSshProcess::ERR_NEW_HOST_KEY: case KSshProcess::ERR_DIFF_HOST_KEY: // ask user to accept key if( acceptHostKey ) { ssh.acceptKey(true); } break;

case KSshProcess::ERR_NEED_PASSWORD: // ask user for password ssh.password(userPassword); break;

case KSshProcess::ERR_NEED_KEY_PASSPHRASE: // ask user for their key passphrase ssh.keyPassphrase(keyPassphrase); break;

default: // somethings wrong, alert user return; } } // We have an open ssh connection to localhost


Member Typedef Documentation

typedef TQValueList<SshOpt> KSshProcess::SshOptList

List of SshOptions and associated iterators


Member Enumeration Documentation

Errors that KSshProcess can encounter. When a member function returns false, call error() to retrieve one of these error codes.

Enumerator:
ERR_UNKNOWN_VERSION 

Don't recognize the ssh version

ERR_CANNOT_LAUNCH 

Cannot lauch ssh client

ERR_INTERACT 

Interaction with the ssh client failed. This happens when we can't find the password prompt or something similar

ERR_CMD_SUBSYS_CONFLICT 

Arguments for both a remotely executed subsystem and command were provide. Only one or the other may be used

ERR_NEED_PASSWD 

No password was supplied

ERR_NEED_PASSPHRASE 

No passphrase was supplied.

ERR_NEED_USERNAME 

No usename was supplied

ERR_TIMED_OUT 

Timed out waiting for a response from ssh or the server

ERR_INTERNAL 

Internal error, probably from a system call

ERR_DISCONNECTED 

ssh was disconnect from the host

ERR_NO_OPTIONS 

No ssh options have been set. Call setArgs() before calling connect.

ERR_NEW_HOST_KEY 

A host key was received from an unknown host. Call connect() with the acceptHostKey argument to accept the key.

ERR_DIFF_HOST_KEY 

A host key different from what is stored in the user's known_hosts file has be received. This is an indication of an attack

ERR_HOST_KEY_REJECTED 

A new or different host key was rejected by the caller. The ssh connection was terminated and the ssh process killed.

ERR_INVALID_OPT 

An invalid option was found in the SSH option list

ERR_ACCEPTED_KEY 

SSH accepted host key without prompting user.

ERR_AUTH_FAILED 

Authentication failed

ERR_AUTH_FAILED_NEW_KEY 

Authentication failed because a new host key was detected and SSH is configured with strict host key checking enabled.

ERR_AUTH_FAILED_DIFF_KEY 

Authentication failed because a changed host key was detected and SSH is configured with strict host key checking enabled.

ERR_CLOSED_BY_REMOTE_HOST 

The remote host closed the connection for unknown reasons.

ERR_UNKNOWN 

We have no idea what happened

ERR_INVALID_STATE 

The connect state machine entered an invalid state.

SSH options supported by KSshProcess. Set SshOpt::opt to one of these values.

Enumerator:
SSH_SUBSYSTEM 

Request server to invoke subsystem. (str)

SSH_PORT 

Connect to port on the server. (num)

SSH_HOST 

Connect to host. (str)

SSH_USERNAME 

connect using this username. (str)

SSH_PASSWD 

connect using this password. (str)

SSH_PROTOCOL 

connect using this version of the SSH protocol. num == 1 or 2

SSH_FORWARDX11 

whether to forward X11 connections. (boolean)

SSH_FORWARDAGENT 

whether to do agent forwarding. (boolean)

SSH_ESCAPE_CHAR 

use as escape character. 0 for none (num)

SSH_COMMAND 

command for ssh to perform once it is connected (str)

SSH_VERBOSE 

Set ssh verbosity. This may be added multiple times. It may also cause KSSHProcess to fail since we don't understand all the debug messages.

SSH_OPTION 

Set a ssh option as one would find in the ssh_config file The str member should be set to 'optName value'

SSH_OTHER 

Set some other option not supported by KSSHProcess. The option should be specified in the str member of SshOpt. Careful with this since not all versions of SSH support the same options.

Ssh versions supported by KSshProcess. Subject to change at any time.


Constructor & Destructor Documentation

KSshProcess::KSshProcess (  ) 

Initialize a SSH process using the first SSH binary found in the PATH

KSshProcess::KSshProcess ( TQString  pathToSsh  ) 

Initialize a SSH process using the specified SSH binary.

Parameters:
pathToSsh The fully qualified path name of the ssh binary KSshProcess should use to setup a SSH connection.

Member Function Documentation

void KSshProcess::acceptHostKey ( bool  accept  ) 

Call to respond to a ERR_NEW_HOST_KEY or ERR_DIFF_HOST_KEY error.

Parameters:
accept True to accept the host key, false to not accept the host key and kill ssh.

Try to open an ssh connection. SSH prints certain messages to certain file descriptiors: passwordPrompt - pty passphrasePrompt - pty authSuccessMsg - stderr (OpenSSH), authFailedMsg - stderr hostKeyMissing - stderr hostKeyChanged - stderr continuePrompt - stderr

We will use a select to wait for a line on each descriptor. Then get each line that available and take action based on it. The type of messages we are looking for and the action we take on each message are: passwordPrompt - Return false, set error to ERR_NEED_PASSWD. On the next call to connect() we expect a password to be available.

passpharsePrompt - Return false, set error to ERR_NEED_PASSPHRASE. On the next call to connect() we expect a passphrase to be available.

authSuccessMsg - Return true, as we have successfully established a ssh connection.

authFailedMsg - Return false, set error to ERR_AUTH_FAILED. We were unable to authenticate the connection given the available authentication information.

hostKeyMissing - Return false, set error to ERR_NEW_HOST_KEY. Caller must call KSshProcess.acceptHostKey(bool) to accept or reject the key before calling connect() again.

hostKeyChanged - Return false, set error to ERR_DIFF_HOST_KEY. Caller must call KSshProcess.acceptHostKey(bool) to accept or reject the key before calling connect() again.

continuePrompt - Send 'yes' or 'no' to accept or reject a key, respectively.

bool KSshProcess::connect (  ) 

Create a ssh connection based on the options provided by setOptions(). Sets one of the following error codes on failure:

  • ERR_NO_OPTIONS
  • ERR_CANNOT_LAUNCH
  • ERR_INVALID_STATE
  • ERR_NEED_PASSWD
  • ERR_AUTH_FAILED
  • ERR_NEW_HOST_KEY
  • ERR_KEY_ACCEPTED
  • ERR_DIFF_HOST_KEY
  • ERR_INTERNAL
  • ERR_INTERACT
Parameters:
acceptHostKey When true KSshProcess will automatically accept unrecognized or changed host keys.
Returns:
True if the ssh connection is successful. False if the connection fails. Call error() to get the reason for the failure.
bool KSshProcess::connected (  )  [inline]

Whether a ssh connection has been established with a remote host. A establish connection means ssh has successfully authenticated with the remote host and user data can be transfered between the local and remote host. This cannot return true unless the most recent call to KSshProccess::connect() returned true.

Returns:
True if a ssh connection has been established with a remote host. False otherwise.
void KSshProcess::disconnect (  ) 

Disconnect ssh from the host. This kills the ssh process and resets the internal state of this KSshProcess object. After a disconnect, the same KSshProcess can be used to connect to a host.

int KSshProcess::error (  )  [inline]

Get the last error encountered by KSshProcess.

Returns:
The error number. See SshError for descriptions.
int KSshProcess::error ( TQString &  msg  ) 

Get a string describing the ssh version

Returns:
A string describing the ssh version recognized by KSshProcess Get the last error encountered by KSshProcess.
Parameters:
msg Set to the error message, if any, outputted by ssh when it is run.
Returns:
The error number. See SshError for descriptions.
void KSshProcess::kill ( int  signal = SIGKILL  ) 

Send a signal to the ssh process. Do not use this to end the ssh connection as it will not correctly reset the internal state of the KSshProcess object. Use KSshProcess::disconnect() instead.

Parameters:
signal The signal to send to the ssh process. See 'kill -l' for a list of possible signals. The default signal is SIGKILL which kills ssh.
int KSshProcess::pid (  )  [inline]

The pid of the ssh process started by this instance of KSshProcess. Only valid if KSshProcess::running() returns true;

Returns:
The pid of the running ssh process.
void KSshProcess::printArgs (  ) 

Print the command line arguments ssh is run with using kdDebug.

int KSshProcess::pty (  )  [inline]

Access the pty to which the ssh process is attached.

Returns:
The file descriptor of pty to which ssh is attached.
bool KSshProcess::running (  )  [inline]

Whether a ssh process is currently running. This only indicates if a ssh process has been started and is still running. It does not tell if authentication has been successful. This may return true even if the most recent call to KSshProcess::connect() returned false.

Returns:
True if a ssh process started by this instance of KSshProcess is running. False otherwise.
bool KSshProcess::setOptions ( const SshOptList opts  ) 

Set the SSH options. This must be called before connect(). See SshOptType for a list of supported ssh options. The required options are SSH_USERNAME and SSH_HOST.

To reset the saved options, just recall setOptions() again with a different options list.

Parameters:
opts A list of SshOpt objects specifying the ssh options.
Returns:
True if all options are valid. False if unrecognized options or a required option is missing. Call error() for details.
void KSshProcess::setPassword ( TQString  password  ) 

Call to respond to a ERR_NEED_PASSWD or ERR_NEED_PASSPHRASE error.

Parameters:
password The user password to give ssh.
bool KSshProcess::setSshPath ( TQString  pathToSsh  ) 

Set the ssh binary KSshProcess should use. This will only affect the next ssh connection attempt using this instance.

Parameters:
pathToSsh Full path to the ssh binary.
Returns:
True if the ssh binary is found and KSshProcess recognizes the version.
int KSshProcess::stderrFd (  )  [inline]

Access to standard error of the ssh process.

Returns:
The file descriptior for stderr of the ssh process.
int KSshProcess::stdioFd (  )  [inline]

Access to standard in and out of the ssh process.

Returns:
The file description for stdin and stdout of the ssh process.
KSshProcess::SshVersion KSshProcess::version (  ) 

Get the ssh version.

Returns:
The ssh version or -1 if KSshProcess does not recognize the ssh version. The returned value corresponds to the member of the SshVersion enum.

The documentation for this class was generated from the following files:

Generated on Sat Oct 2 23:00:25 2010 by  doxygen 1.6.1