runtime/kioslave/sftp/ksshprocess.h

   1 /***************************************************************************
   2                           ksshprocess.h  -  description
   3                              -------------------
   4     begin                : Tue Jul 31 2001
   5     copyright            : (C) 2001 by Lucas Fisher
   6     email                : ljfisher@purdue.edu
   7  ***************************************************************************/
   8
   9 /***************************************************************************
  10  *                                                                         *
  11  *   This program is free software; you can redistribute it and/or modify  *
  12  *   it under the terms of the GNU General Public License as published by  *
  13  *   the Free Software Foundation; either version 2 of the License, or     *
  14  *   (at your option) any later version.                                   *
  15  *                                                                         *
  16  ***************************************************************************/
  17
  18 #ifndef KSSHPROCESS_H
  19 #define KSSHPROCESS_H
  20
  21 #include <sys/types.h>
  22 #include <sys/wait.h>
  23 #include <signal.h>
  24 #include <unistd.h>
  25
  26
  27
  28 #include <kdebug.h>
  29
  30 #include "process.h"
  31
  32 #define KSSHPROC 7120
  33
  34 /**
  35  * Provides version independent access to ssh. Currently supported
  36  * versions of SSH are:
  37  *   OpenSSH 2.9p1
  38  *   OpenSSH 2.9p2
  39  *   OpenSSH 3.0
  40  *   OpenSSH 3.1
  41  *   Commercial SSH 3.0.0
  42  * Other versions of OpenSSH and commercial SSH will probably work also.
  43  *
  44  * To setup a SSH connection first create a list of options to use and tell
  45  * KSshProcess about your options. Then start the ssh connection. Once the
  46  * connection is setup use the  stdin, stdout, stderr, and pty file descriptors
  47  * to communicate with ssh. For a detailed example of how to use, see
  48  * ksshprocesstest.cpp.
  49  *
  50  * @author Lucas Fisher
  51  *
  52  * Example: Connect to ssh server on localhost
  53  *   KSshProcess::SshOpt opt;
  54  *   KSshProcess::SshOptList options;
  55  *
  56  *   opt.opt = KSshProcess::SSH_HOST;
  57  *   opt.str = "localhost";
  58  *   options.append(opt);
  59  *
  60  *   opt.opt = KSshProcess::SSH_USERNAME;
  61  *   opt.str = "me";
  62  *   options.append(opt);
  63  *
  64  *   KSshProcess ssh;
  65  *   if( !ssh.setOptions(options) ) {
  66  *       int err = ssh.error();
  67  *       // process error
  68  *        return false;
  69  *   }
  70  *
  71  *   int err;
  72  *   QString errMsg;
  73  *   while( !ssh.connect() ) {
  74  *       err = ssh.error(errMsg);
  75  *
  76  *       switch( err ) {
  77  *       case KSshProcess::ERR_NEW_HOST_KEY:
  78  *       case KSshProcess::ERR_DIFF_HOST_KEY:
  79  *           // ask user to accept key
  80  *           if( acceptHostKey ) {
  81  *               ssh.acceptKey(true);
  82  *           }
  83  *           break;
  84  *
  85  *       case KSshProcess::ERR_NEED_PASSWORD:
  86  *           // ask user for password
  87  *           ssh.password(userPassword);
  88  *           break;
  89  *
  90  *       case KSshProcess::ERR_NEED_KEY_PASSPHRASE:
  91  *           // ask user for their key passphrase
  92  *           ssh.keyPassphrase(keyPassphrase);
  93  *           break;
  94  *
  95  *       default:
  96  *           // somethings wrong, alert user
  97  *           return;
  98  *       }
  99  *   }
 100  *   // We have an open ssh connection to localhost
 101  *
 102  */
 103
 104 class KSshProcess {
 105 public:
 106     /**
 107      * SSH Option
 108      *
 109      * Stores SSH options for use with KSshProcess.
 110      *
 111      * SSH options are configured much like UDS entries.
 112      * Each option is assigned a constant and a string, bool,
 113      * or number is assigned based on the option.
 114      *
 115      * @author Lucas Fisher (ljfisher@iastate.edu)
 116      */
 117     class SshOpt {
 118     public:
 119         quint32 opt;
 120         QString  str;
 121         qint32  num;
 122         bool     boolean;
 123     };
 124
 125     /**
 126      * List of SshOptions and associated iterators
 127      */
 128     typedef QList<SshOpt> SshOptList;
 129     typedef QList<SshOpt>::Iterator SshOptListIterator;
 130     typedef QList<SshOpt>::ConstIterator SshOptListConstIterator;
 131
 132     /**
 133      * Ssh versions supported by KSshProcess. Subject to change
 134      * at any time.
 135      */
 136     enum SshVersion {
 137         OPENSSH_3_6,
 138         OPENSSH,
 139         SSH,
 140         PLINK,
 141         SSH_VER_MAX,
 142         UNKNOWN_VER
 143     };
 144
 145     /**
 146      * SSH options supported by KSshProcess.  Set SshOpt::opt to one of these
 147      * values.
 148      */
 149     // we cannot do this like UDSAtomType (ORing the type with the name) because
 150     // we have too many options for ssh and not enough bits.
 151     enum SshOptType {
 152         /**
 153          * Request server to invoke subsystem. (str)
 154          */
 155         SSH_SUBSYSTEM,
 156         /**
 157          * Connect to port on the server. (num)
 158          */
 159         SSH_PORT,
 160         /**
 161          * Connect to host. (str)
 162          */
 163         SSH_HOST,
 164         /**
 165          * connect using this username. (str)
 166          */
 167         SSH_USERNAME,
 168         /**
 169          * connect using this password. (str)
 170          */
 171         SSH_PASSWD,
 172         /**
 173          * connect using this version of the SSH protocol. num == 1 or 2
 174          */
 175         SSH_PROTOCOL,
 176         /**
 177          * whether to forward X11 connections. (boolean)
 178          */
 179         SSH_FORWARDX11,
 180         /**
 181          * whether to do agent forwarding. (boolean)
 182          */
 183         SSH_FORWARDAGENT,
 184         /**
 185          * use as escape character. 0 for none  (num)
 186          */
 187         SSH_ESCAPE_CHAR,
 188         /**
 189          * command for ssh to perform once it is connected (str)
 190          */
 191         SSH_COMMAND,
 192         /**
 193          * Set ssh verbosity. This may be added multiple times. It may also cause KSSHProcess
 194          * to fail since we don't understand all the debug messages.
 195          */
 196         SSH_VERBOSE,
 197         /**
 198          * Set a ssh option as one would find in the ssh_config file
 199          * The str member should be set to 'optName value'
 200          */
 201         SSH_OPTION,
 202         /**
 203          * Set some other option not supported by KSSHProcess. The option should
 204          * be specified in the str member of SshOpt. Careful with this since
 205          * not all versions of SSH support the same options.
 206          */
 207         SSH_OTHER,
 208         SSH_OPT_MAX // always last
 209     }; // that's all for now
 210
 211     /**
 212      * Errors that KSshProcess can encounter.  When a member function returns
 213      * false, call error() to retrieve one of these error codes.
 214      */
 215     enum SshError {
 216         /**
 217          * Don't recognize the ssh version
 218          */
 219         ERR_UNKNOWN_VERSION,
 220         /**
 221          * Cannot lauch ssh client
 222          */
 223         ERR_CANNOT_LAUNCH,
 224         /**
 225          * Interaction with the ssh client failed. This happens when we can't
 226          * find the password prompt or something similar
 227          */
 228         ERR_INTERACT,
 229         /**
 230          * Arguments for both a remotely executed subsystem and command were provide.
 231          * Only one or the other may be used
 232          */
 233         ERR_CMD_SUBSYS_CONFLICT,
 234         /**
 235          * No password was supplied
 236          */
 237         ERR_NEED_PASSWD,
 238         /**
 239          * No passphrase was supplied.
 240          */
 241         ERR_NEED_PASSPHRASE,
 242         /**
 243          * No usename was supplied
 244          */
 245         ERR_NEED_USERNAME,
 246         /**
 247          * Timed out waiting for a response from ssh or the server
 248          */
 249         ERR_TIMED_OUT,
 250         /**
 251          * Internal error, probably from a system call
 252          */
 253         ERR_INTERNAL,
 254         /**
 255          * ssh was disconnect from the host
 256          */
 257         ERR_DISCONNECTED,
 258         /**
 259          * No ssh options have been set. Call setArgs() before calling connect.
 260          */
 261         ERR_NO_OPTIONS,
 262         /**
 263          * A host key was received from an unknown host.
 264          * Call connect() with the acceptHostKey argument to accept the key.
 265          */
 266         ERR_NEW_HOST_KEY,
 267         /**
 268          * A host key different from what is stored in the user's known_hosts file
 269          * has be received. This is an indication of an attack
 270          */
 271         ERR_DIFF_HOST_KEY,
 272         /**
 273          * A new or different host key was rejected by the caller. The ssh
 274          * connection was terminated and the ssh process killed.
 275          */
 276         ERR_HOST_KEY_REJECTED,
 277         /**
 278          * An invalid option was found in the SSH option list
 279          */
 280         ERR_INVALID_OPT,
 281         /**
 282          * SSH accepted host key without prompting user.
 283          */
 284         ERR_ACCEPTED_KEY,
 285         /**
 286          * Authentication failed
 287          */
 288         ERR_AUTH_FAILED,
 289         /**
 290          * Authentication failed because a new host key was detected and
 291          * SSH is configured with strict host key checking enabled.
 292          */
 293         ERR_AUTH_FAILED_NEW_KEY,
 294         /**
 295          * Authentication failed because a changed host key was detected and
 296          * SSH is configured with strict host key checking enabled.
 297          */
 298         ERR_AUTH_FAILED_DIFF_KEY,
 299         /**
 300          * The remote host closed the connection for unknown reasons.
 301          */
 302         ERR_CLOSED_BY_REMOTE_HOST,
 303         /**
 304          * We have no idea what happened
 305          */
 306         ERR_UNKNOWN,
 307         /**
 308          * The connect state machine entered an invalid state.
 309          */
 310         ERR_INVALID_STATE,
 311         ERR_MAX
 312     };
 313
 314     /**
 315      * Initialize a SSH process using the first SSH binary found in the PATH
 316      */
 317     KSshProcess();
 318
 319     /**
 320      * Initialize a SSH process using the specified SSH binary.
 321      * @param pathToSsh The fully qualified path name of the ssh binary
 322      *                  KSshProcess should use to setup a SSH connection.
 323      */
 324     KSshProcess(QString pathToSsh);
 325     ~KSshProcess();
 326
 327     /**
 328      * Set the ssh binary KSshProcess should use. This will only affect the
 329      * next ssh connection attempt using this instance.
 330      *
 331      * @param pathToSsh Full path to the ssh binary.
 332      *
 333      * @return True if the ssh binary is found and KSshProcess
 334      *         recognizes the version.
 335      *
 336      */
 337      bool setSshPath(QString pathToSsh);
 338
 339     /**
 340      * Get the ssh version.
 341      *
 342      * @return  The ssh version or -1 if KSshProcess does not recognize
 343      *          the ssh version. The returned value corresponds to the
 344      *          member of the SshVersion enum.
 345      */
 346     SshVersion version();
 347
 348     /**
 349      * Get a string describing the ssh version
 350      *
 351      * @return A string describing the ssh version recognized by KSshProcess
 352      */
 353     //QString versionStr();
 354
 355     /**
 356      * Get the last error encountered by KSshProcess.
 357      *
 358      * @param msg Set to the error message, if any, outputted by ssh when it is run.
 359      *
 360      * @return The error number. See SshError for descriptions.
 361      */
 362     int error(QString& msg);
 363
 364     /**
 365      * Get the last error encountered by KSshProcess.
 366      * @return The error number. See SshError for descriptions.
 367      */
 368     int error() { return mError; }
 369
 370     QString errorMsg() { return mErrorMsg; }
 371
 372     /**
 373      * Send a signal to the ssh process. Do not use this to end the
 374      * ssh connection as it will not correctly reset the internal
 375      * state of the KSshProcess object.  Use KSshProcess::disconnect()
 376      * instead.
 377      *
 378      * @param signal The signal to send to the ssh process. See 'kill -l'
 379      *               for a list of possible signals.
 380      *               The default signal is SIGKILL which kills ssh.
 381      *
 382      */
 383     void kill(int signal = SIGKILL);
 384
 385     /**
 386      * The pid of the ssh process started by this instance of KSshProcess.
 387      * Only valid if KSshProcess::running() returns true;
 388      *
 389      * @return The pid of the running ssh process.
 390      */
 391     int pid() { return ssh.pid(); }
 392
 393     /**
 394      * Whether a ssh connection has been  established with a
 395      * remote host.  A establish connection means ssh has successfully
 396      * authenticated with the remote host and user data can be transfered
 397      * between the local and remote host.  This cannot return
 398      * true unless the most recent call to KSshProccess::connect() returned true.
 399      *
 400      * @return True if a ssh connection has been established with a remote
 401      *         host. False otherwise.
 402      */
 403     bool connected() { return mConnected; }
 404
 405     /**
 406      * Whether a ssh process is currently running.  This  only indicates
 407      * if a ssh process has been started and is still running.  It does not
 408      * tell if authentication has been successful.  This may return true
 409      * even if the most recent call to KSshProcess::connect() returned false.
 410      *
 411      * @return True if a ssh process started by this instance of KSshProcess
 412      *         is running. False otherwise.
 413      */
 414     bool running() { return mRunning; }
 415
 416     /**
 417      * Print the command line arguments ssh is run with using kDebug.
 418      */
 419     void printArgs();
 420
 421     /**
 422      * Set the SSH options.
 423      * This must be called before connect().  See SshOptType for a list of
 424      * supported ssh options.  The required options are SSH_USERNAME
 425      * and SSH_HOST.
 426      *
 427      * To reset the saved options, just recall setOptions() again with
 428      * a different options list.
 429      *
 430      * @param opts A list of SshOpt objects specifying the ssh options.
 431      *
 432      * @return True if all options are valid. False if unrecognized options
 433      *         or a required option is missing. Call error()
 434      *         for details.
 435      *
 436      */
 437     bool setOptions(const SshOptList& opts);
 438
 439     /**
 440      * Create a ssh connection based on the options provided by setOptions().
 441      * Sets one of the following error codes on failure:
 442      * <ul>
 443      * <li>ERR_NO_OPTIONS</li>
 444      * <li>ERR_CANNOT_LAUNCH</li>
 445      * <li>ERR_INVALID_STATE</li>
 446      * <li>ERR_NEED_PASSWD</li>
 447      * <li>ERR_AUTH_FAILED</li>
 448      * <li>ERR_NEW_HOST_KEY</li>
 449      * <li>ERR_KEY_ACCEPTED</li>
 450      * <li>ERR_DIFF_HOST_KEY</li>
 451      * <li>ERR_INTERNAL</li>
 452      * <li>ERR_INTERACT</li>
 453      * </ul>
 454      *
 455      * @param acceptHostKey When true KSshProcess will automatically accept
 456      *                      unrecognized or changed host keys.
 457      *
 458      * @return True if the ssh connection is successful. False if the connection
 459      *         fails.  Call error() to get the reason for the failure.
 460      */
 461     bool connect();
 462
 463
 464     /**
 465      * Disconnect ssh from the host.  This kills the ssh process and
 466      * resets the internal state of this KSshProcess object. After a
 467      * disconnect, the same KSshProcess can be used to connect to a
 468      * host.
 469      */
 470     void disconnect();
 471
 472     /**
 473      * Call to respond to a ERR_NEW_HOST_KEY or ERR_DIFF_HOST_KEY error.
 474      *
 475      * @param accept True to accept the host key, false to not accept the
 476      *               host key and kill ssh.
 477      *
 478      */
 479     void acceptHostKey(bool accept);
 480
 481     /**
 482      * Call to respond to a ERR_NEED_PASSWD or ERR_NEED_PASSPHRASE error.
 483      *
 484      * @param password The user password to give ssh.
 485      */
 486     void setPassword(QString password);
 487
 488     /**
 489      * Access to standard in and out of the ssh process.
 490      *
 491      * @return The file description for stdin and stdout of the ssh process.
 492      */
 493     int stdioFd() { return ssh.stdioFd(); }
 494
 495     /**
 496      * Access to standard error of the ssh process.
 497      *
 498      * @return The file descriptior for stderr of the ssh process.
 499      */
 500     int stderrFd() { return ssh.stderrFd(); }
 501
 502     /**
 503      * Access the pty to which the ssh process is attached.
 504      *
 505      * @return The file descriptor of pty to which ssh is attached.
 506      */
 507 #ifndef Q_WS_WIN
 508     int pty() { return ssh.fd(); }
 509 #else
 510     KProcess *pty() { return ssh.fd(); }
 511 #endif
 512 private:
 513     /**
 514      * Path to the ssh binary.
 515      */
 516     QString mSshPath;
 517
 518     /**
 519      * SSH version.  This is an index into the supported SSH
 520      * versions array, and the various messages arrays.
 521      */
 522     SshVersion mVersion;
 523
 524     /**
 525      * User's password.  Zero this out when it is no longer needed.
 526      */
 527     QString mPassword;
 528
 529     /**
 530      * User's username.
 531      */
 532     QString mUsername;
 533
 534     /**
 535      * Name of host we are connecting to.
 536      */
 537     QString mHost;
 538
 539     /**
 540      * Accept new or changed host keys if true.
 541      */
 542     bool mAcceptHostKey;
 543
 544     /**
 545      * Flag to tell use if we have an open, authenticated ssh
 546      * session going.
 547      */
 548     bool mConnected;
 549
 550     /**
 551      * Flag to tell us if we have started a ssh process, we use this
 552      * to make sure we kill ssh before going away.
 553      */
 554     bool mRunning;
 555
 556     /**
 557      * Save any key fingerprint msg from ssh so we can present
 558      * it to the caller.
 559      */
 560     QString mKeyFingerprint;
 561
 562     /**
 563      * The location of the known host key file. We grab this from
 564      * any error messages ssh prints out.
 565      */
 566     QString mKnownHostsFile;
 567
 568     /**
 569      * The state of our connect state machine.
 570      */
 571     int mConnectState;
 572
 573     /**
 574      * Port on on which the target ssh server is listening.
 575      */
 576     int mPort;
 577
 578     /**
 579      * The last error number encountered. This is only valid for the
 580      * last error.
 581      */
 582     SshError mError;
 583
 584     /**
 585      * An error message that corresponds to the error number set in
 586      * mError.  Optional.
 587      */
 588     QString mErrorMsg;
 589
 590     /**
 591      * Interface to the SSH process we ceate.  Handles communication
 592      * to and from the SSH process using stdin, stdout, stderr, and
 593      * pty.
 594      */
 595     MyPtyProcess ssh;
 596
 597     /**
 598      * List of arguments we start SSH with.
 599      */
 600     QCStringList mArgs;
 601     void init();
 602
 603     /**
 604       * Handler to clean up when ssh process terminates.
 605       */
 606     static void SIGCHLD_handler(int signo);
 607     void installSignalHandlers();
 608     void removeSignalHandlers();
 609
 610     QString getLine();
 611
 612     static QRegExp versionStrs[];
 613     static const char * const passwordPrompt[];
 614     static const char * const passphrasePrompt[];
 615     static const char * const authSuccessMsg[];
 616     static const char * const authFailedMsg[];
 617     static QRegExp hostKeyMissingMsg[];
 618     static const char * const hostKeyChangedMsg[];
 619     static const char * const continuePrompt[];
 620     static const char * const hostKeyAcceptedMsg[];
 621     static const char * const tryAgainMsg[];
 622     static QRegExp hostKeyVerifyFailedMsg[];
 623     static const char * const connectionClosedMsg[];
 624     static const char * const changeHostKeyOnDiskPrompt[];
 625     static QRegExp keyFingerprintMsg[];
 626     static QRegExp knownHostsFileMsg[];
 627 };
 628 #endif