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, and agent-mediated 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.
• 64-bit ready
• Interact directly with libssh2 using idiomatic RB/Xojo objects, methods, and events; no shell or plugins required.

Use of this project in GUI or Web applications

This project does not yet support being used directly in Xojo desktop or web applications (see Issue #1). Instead, you should use this project in a console application, such as a Xojo Worker, that is invoked from your desktop or web application.

Synopsis

The SSH2 protocol permits an arbitrary number (up to 2³²) 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.

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

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 key management service running on the user's system.
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:

1. Create a new instance of the Session class.
2. Call Session.Connect with the address and port of the server, or a Xojo TCPSocket which is already connected to the server.
3. 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.
4. Call Session.SendCredentials to send the user's credentials to the server.
5. Check the Session.IsAuthenticated property to see if the credentials were accepted.
6. Create data streams over the session, for example the Channel or SFTPSession classes.
7. Interact with the created data streams through their Read, Write, etc. methods.
8. When finished with a data stream call its Close method.
9. After all data streams are finished and closed, call Session.Close to end the connection.

Refer to the SSH Connection Example for further information.

How to incorporate libssh2 into your Realbasic/Xojo project

Import the SSH module

1. Download the RB-libssh2 project either in ZIP archive format or by cloning the repository with your Git client.
2. Open the RB-libssh2 project in REALstudio or Xojo. Open your project in a separate window.
3. 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 (libssh2 <= 1.9.0) or libcrypto-3.dll (libssh2 >= 1.10.0) 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.

Examples

• SSH
  • Establishing a connection
  • Checking the server's fingerprint
  • Authenticating to the server
  • Execute a command line
• SFTP
  • Download
  • Recursive download
  • Upload
  • Recursive upload
  • Directory listing
  • Get file permissions
  • Set file permissions
• TCP tunneling
  • Connect
  • Listen (single connection)
  • Listen (multiple connections)
• SCP
  • Download
  • Upload