Home

Introduction

libssh2 is a cross-platform library implementing the SSH2 protocol. RB-libssh2 is a libssh2 binding for Realbasic and Xojo ("classic" framework) projects.

The minimum supported libssh2 version is 1.7.0. The minimum supported Xojo version is RS2010R4.

Example

This example starts a command ("uptime") on the remote machine and reads from its StdOut stream (More examples):

  Dim sh As SSH.Channel = SSH.OpenChannel("ssh://user:password@public.example.com/")
  Call sh.Execute("uptime")
  Dim result As String
  Do Until sh.EOF
    If sh.PollReadable() Then
      result = result + sh.Read(sh.BytesReadable, 0)
    End If
  Loop
  sh.Close

Hilights

Password, public-key, agent, and interactive¹ authentication.
Known host key verification
Download and upload using SFTP or SCP.
Manage files and directories over SFTP.
Execute commands on the server and read the results.
TCP forwarding and tunneling
Stream-oriented, using Xojo's built-in Readable and Writeable interfaces.
A consistent, high-level API over the full range of libssh2's features.
Interact directly with libssh2 using idiomatic RB/Xojo objects, methods, and events; no shell or plugins required.

¹ Not fully implemented or currently broken

Synopsis

It is strongly recommended that you familiarize yourself with libssh2, as this project preserves the semantics of libssh2's API in an object-oriented, Xojo-flavored wrapper.

For more thorough documentation of individual classes and methods refer to the wiki.

The SSH2 protocol permits an arbitrary number (up to 2³²-1) of simultaneous full-duplex binary data streams to be efficiently and securely multiplexed over a single TCP connection. A data stream can be an upload or download using SFTP or SCP, the input/output of a program being executed on the server, a TCP connection to a third party forwarded through the SSH server, or your own custom protocol.

For simple, one-off operations you can usually use the Get, Put, Execute, or OpenChannel convenience methods in the SSH module. See also the Connect convenience method if you want to perform several such operations on the same connection.

For more complex operations you will need to dig into the libssh2 API a bit more. libssh2 exposes its API through a number of different handle types. Each libssh2 handle or handle equivalent corresponds to an object class implemented in the binding.

Object Class	Comment
`Session`	A secure connection to the server over which one or more data streams can be multiplexed.
`Channel`	A data stream that is multiplexed over a Session.
`KnownHosts`	A list of known hosts and their associated key fingerprints.
`Agent`	A local key management agent.
`SFTPSession`	A SFTP session that is multiplexed over a Session.
`SFTPStream`	A SFTP upload, download, or other operation that is performed over a SFTPSession.
`SFTPDirectory`	A SFTP directory listing that is performed over a SFTPSession.
`SCPStream`	A SCP upload or download that is multiplexed over a Session.
`SSHStream`	An interface which aggregates the Readable and Writeable interfaces, representing a channel or other stream.
`TCPListener`	A listener for accepting forwarded TCP connections from the server.
`TCPTunnel`	A Channel over which a TCP connection is forwarded.

The general order of operations is something like this:

Create a new instance of the Session class.
Call Session.Connect with the address and port of the server, or a Xojo TCPSocket which is already connected to the server.
Optionally use the KnownHosts class to load a list of acceptable server fingerprints, and then compare the newly connected session's fingerprint to that list.
Call Session.SendCredentials to send the user's credentials to the server.
Check the Session.IsAuthenticated property to see if the credentials were accepted.
Create data streams over the session, for example the Channel or SFTPSession classes.
Interact with the created data streams through their Read, Write, etc. methods.
When finished with a data stream call its Close method.
After all data streams are finished and closed, call Session.Close to end the connection.

A note on threading

In many cases it will be advantageous to run SSH and SFTP operations on background thread, and it's safe to do so with one caveat.

Each instance of SSH.Session and all subsequent objects created with it (Channels, SFTP objects, etc.; collectively "the session") are a single resource for threading purposes; they all use the single TCP connection owned by the SSH.Session instance, and that is the resource that threads must contend for.

If the session will be accessed from more than one thread then the entire session should be protected by a single synchronization object, such as a Semaphore or CriticalSection, so that only one thread can access the session at a time. "Access" is pretty much all-inclusive, since even reading the value of a property will in many cases send and receive data on the connection.

How to incorporate libssh2 into your Realbasic/Xojo project

Import the SSH module

Download the RB-libssh2 project either in ZIP archive format or by cloning the repository with your Git client.
Open the RB-libssh2 project in REALstudio or Xojo. Open your project in a separate window.
Copy the SSH module into your project and save.

Ensure the libssh2 shared library is installed

libssh2 is not installed by default on most systems, and will need to be installed separately (or shipped with your app). Pre-built binaries for Windows can be downloaded from the libcurl project. You will also need libcrypto-1_1.dll from the OpenSSL project, also available from libcurl.

RB-libssh2 will raise a PlatformNotSupportedException when used if all required DLLs/SOs/DyLibs are not available at runtime.