SSH package for U++
--------------------
SSH package is a feautre-rich, flexible yet very easy to use libssh2 wrapper for Ultimate++.
It supports both console and GUI-based applications on POSIX-compliant operating systems and
MS Windows (tm).

Currently it is in beta (version 1) stage.

Classes:
--------------------

- Base (core) class  -> Ssh
  - Ssh session        -----> SshSession
  - Sftp subsystem     -----> SFtp
  - Ssh channel        -----> SshChannel
      - Scp channel                 -----> Scp
      - Exec channel                -----> SshExec
      - Real-time interactive shell -----> SshShell
      - X11 forwarding              -----> SshShell (as operation mode)      
      - Tcp/IP and port forwarding  -----> SshTunnel

- Known hosts manager -> SshHosts

Features and Highlights:
--------------------

- Ssh-derived classes have pick semantics, based on RAII principle, support RTTI, and allow
  polymorphism (i.e. different classes can be stored in the same arrays, etc.) through a common
  interface. 
- Uses U++ memory allocators (Native allocators is also a compile-time option)
- Uses OpenSSL by default. 
- Supports time-constrained, blocking and non-blocking operation modes.
- Supoorts multithreaded file transfers and remote command execution (exec), using worker threads.
- Supports 3rd-party network proxies. (Such as NetProxy)
- Supports known hosts verification mechanism.
- Supports password, public key, host-based, and keyboard-interactive authentication methods.
- Supports ssh-agents.
- Supports real-time interactive command line (shell) interface with both console and GUI integration (works on Windows and Posix-compliant OS'es)
- Supports multiple X11 connection forwarding.
- Supports Tcp/IP and port forwarding.
- Supports detailed (full) debug logging.

Todo:
--------------------
- Add more high level methods.
- Refactor Ssh (core) class.
- Improve documentation.

Reference examples:
-------------------

- SFtpGet:           Demonstrates basic SFtp file download in blocking mode.
- SFtpGetNB:         Demonstrates basic SFtp file download in non-blocking mode.
- SFtpGetMT:         Demonstrates basic SFtp file download, using a worker thread.
- SFtpGUI:           Demonstrates a basic SFtp browser with GUI (with upload, download, mkdir, rename, delete commands).
- SFtpMultiGetMT:    Demonstrates SFtp dir listing and concurrent file transfers, using worker threads.
- SFtpConsumerGet:   Demonstrates the usage of a consumer function for SFtp download in blocking mode.
- SFtpConsumerGetMT: Demonstrates the usage of a consumer function for SFtp download, using a worker thread.
- SshExec:           Demonstrates basic Ssh remote command execution in blocking mode.
- SshExecNB:         Demonstrates basic Ssh remote command execution in non-blocking mode.
- SshExecMT:         Demonstrates basic Ssh remote command execution, using a worker thread.
- SshKeyboardAuth:   Demonstrates basic Ssh interactive (challenge-response) authentication method in blocking mode.
- SshLoggingExample: Demonstrates the logging capabilities of SSH package.
- SshOverTor:        Demonstrates a basic Ssh connection over TOR, using a third-party network proxy adapter.
- SshPolymorphismNB: Demonstrates the polymorphism capability of SSH channels in non-blocking mode.
- SshShell:          Demonstrates a basic, real-time SSH shell console in blocking mode.
- SshShellNB:        Demonstrates a basic, real-time SSH shell console in non-blocking mode.    
- SshShellX11:       Demonstrates a basic, real-time SSH shell console with multiple X11 forwarding.
- SshShellGUI:       Demonstrates the basic GUI integration of SshShell class with multiple X11 forwarding, in non-blocking mode.
- SshTunnelExample:  Demonstrates the basic SSH tunneling (as tunnel/server) in blocking mode.


History:
--------------------
2018-06-15:  Critical fix: SshChannel and SFtp data read and write methods fixed: The recently introduced
             socket wait mechanism was causing a constant I/O blocking. This is now fixed.   
             Cosmetics & cleanup.

2018-06-06:  SshShell: Console loop fixed.

2018-05-04:  Ssh::GetWaitEvents() fixed.
             SshTunnel::Validate() fixed.
             SshTunnelExample is added to the reference examples.

2018-04-21:  AsyncConsumerGet() methods are added to SFtp and Scp classes. 
             License file udated.

2018-04-15:  Consumer function support added to SFtp and SshChannel classes.
             GetWaitStep() method is added to Ssh class.
             Multithreaded methods rewritten.

2018-04-06:  Blocking and non-blocking behaviour is aligned with TcpSocket.
             WhenDo replaced with WhenWait, and WaitStep() method is added.

2018-02-23:  SshShell: Console mode is now properly restored on failure.

2018-01-28:  X11 forwarding support  added as an operation mode for shell.
             From now a signle  SshShells can forward multiple X11 connections.
             X11 examples (for both console and GUI) are added to the examples directory.

2018-01-26:  SshChannel::Lock() and SShChannel::Unlock() methods are added.
             These methods allow serialized access to desired SShChannel methods while keeping
             their non-blocking state. That is, it is now possible to open multiple non-blocking
             exec, and shell channels (per-session) concurrently in a single-threaded environment.
             
2018-01-25:  Stream close correctly handled in ReadString and ReadStream.

2018-01-19:  Alpha version 2.
             SshChannel reworked. It is now more flexible, and more analogous to a tcp socket. 
             Scp class gained a new Put method (and its corresponding operator overload).
             NEW: SShShell is added to the package. It allows GUI integration and  has a
                  "console mode"  that supports both POSIX consoles and Windows command prompt.
             NEW: SshTunnel class is added to the package. It allows TCP/IP and port forwarding
                  over SSH protocol.
             Various bug fixes, and improvements.  

2017-12-19:  It is now possible to use encryption keys loaded into memory.
             ssh_session_libtrace() function added: This function allows full-level logging 
             (redirection) of libsssh2 diagnostic messages.
             Hostbased authentication mechanism added.
             Documentation updated.

2017-11-24:  Connect() method overload added. This variant takes a secure shell URL string.
             Multithreaded functions are improved.
             Documentation updated.

2017-11-19:  GetCurrentDir() and GetParentDir() methods are added to SFtp class.
             libssh2, session.c (line: 177-8), banner_receive() method patched to 
             prevent a  memory leak which is caused by accidentally trying to connect to a 
             non-ssh2 server.

2017-11-12:  Basic multithreading support added for SFtp, Scp, and Exec classes.

2017-11-10:  GetWaitEvents() and AddTo() methods addet to Ssh class.
             Scp, SshChannel, SshExec, SshHosts classes are added to the package.
             Documentation added for Ssh, SshSession, SFtp, Scp, SshExec, and SshHosts classes.

2017-10-21:  Ssh agents support added. A ToXml() method added to SFtp::DirEntry class.
             Timeouts error code is from now on -1000. This is to prevent unnecessary cleanup 
             rounds when the server is not responding.

2017-10-20:  Known hosts support is re-added via SshHosts class. Docs are updated accordingly.

2017-10-17:  Class names finalized:
             Core class       -> Ssh
             Session class    -> SshSession
             SFtp class       -> SFtp
             Channel class    -> SshChannel
             Scp class        -> Scp
             Exec class       -> SshExec
             Knownhosts class -> SshHosts
             SshAgents        -> (will be added as such)

             CreateSFtp(), CreateExec(), CreateScp(), CreateChannel() methods added to SshSession
             class. 
             Logging further refined.
             Error management further refined.
  
2017-10-15:  Second iteration of SSH package.

             1) This version brings a major redesign of overall components. SSH package's classes
                are redesigned around a core class named Ssh. Ssh allows a uniform 
                interface for both blocking and non-blocking modes of operation. Visible result
                of this new design is a single set of methods for both modes of operation for 
                each class. Methods starting with "Start" prefix are removed in favor of a 
                simple "NonBlocking()" switch.

             2) In accordance with this behaviour, a sort of "feature parity" is successfully 
                kept, thanks to the new design. Namely, in non-blocking mode, any result can be
                gathered using the new GetResult() method, which returns Value.

             3) All SSH package classes now has pick semantics.
            
             4) New design allows creation of higher-level ("complex") SFTP methods where needed.
                Unlike the simple SFTP methods, which work on file handles, Complex methods take 
                care of (allocate/free) file handles internally.
            
             5) Experimental multithreading support is added (using AsyncWork). This is still
                at a primitive stage. 
    
             6) Network proxy support is added. This new feature uses NetProxy (Http/Socks4/4a/5)
                package It works through a plugin, provided via SshSession::WhenProxy callback.
                And it is completely optional. 

             7) Cancellation mechanism is added. Any operation can be cancelled at any time using
                the Cancel() method.

             8) SFtp::DirEntry class now has a ToString() method. (It will also gain an ToXml()
                method.) This method will give an output similar to Unix ls command.

             9) LibSsh2 configured to use OpenSSL by default (WinCNG will be made a compile-time
                option in the next release).
            
2017-08-11:  Initial api reference docs for Ssh, Ssh::SubSystem, SFtp, Scp, Exec, Knownhosts, are added.
2017-07-31:  It is now possible to query, get, and set the possible transportation methods and exchange 
             algorithms. Added Ssh::Method(), Ssh::Methods(), Ssh::GetMethod(), Ssh::GetMethods() methods. 
             Ssh::Host class is from now on KnownHosts class.

2017-07-21:  Authentication methods (password, public key, keyboard interaction) are properly implemented.
             From now on it is possible to choose between authentication methods both on initialization,
             and on-the-fly (i.e. while logging in, using WhenAuth callback). 
             Ssh::Host class is added to the package. This class provides basic known hosts support.
             It is now possible to verify and trust servers.
             SshAlloc named as SshMalloc, and made into a general-purpose memory allocator (needed for keyboard callback).
             SshSubsystem class is now Ssh::Subsystem.

2017-07-04:  Credits should go to Koldo and Tom (Tom1). I am grateful for their feedback. Thanks!
             Include paths fixes. 

2017-07-03:  libssh2 config: Newer diffie-hellman-group-exchange-sha1 syntax enabled.
2017-07-02:  Initial MSC support added.
             Due to a name clash on MSC environment, addrinfo changed to ip_addrinfo.

2017-06-30:  The source code of libssh2 is added to the SSH package. 
             Exec::operator()() made inline.          

2017-06-29:  SshSubsystem::To(): reinterpret_csst() replaced with dynamic_cast().

2017-06-28:  EAGAIN is now properly handled across the subsystems.
             WhenWrite and WhenRead callbacks are removed in favour of parametrized gates.

2017-06-27:  SFtp::StartStop: fixed.

2017-06-27:  CleanUp() methods are added to the classes Ssh, SFtp, and Channel.
             This method utilizes JobQueue's WhenCleanup event.

2017-06-26:  U++ memory [de/re]allocators added and made default.
             initial support for ssh shell, and terminal added.
             Subsystems now perform a clean up on failure to prevent possible heap leaks.   
       
2017-06-22:  Initial release.
