FlowSshC/Cpp/Net's Interfaces

Thematically, the interface of FlowSshC/Cpp/Net can be divided into three functional groups.

At first there is a group of functions that deal with public-keys and keypairs.
Then there is another group that handles client connections with SSH servers. Proxy settings and port forwarding scenarios are set up and accessed though this group of functions too.
Finally there is the important group of channel related functions. While you will use client functions to setup a connection with a server, you will then always end up using channels to accomplish various SSH tasks of your choice.

The following subsections describe these groups in more detail.

Public-key cryptography

The interface for manipulating public-keys and keypairs:

Public-key cryptography is a cryptographic approach that involves the use of two related keys:

A private-key, which is known only to its owner.
A public-key, which is known to everyone the owner wants to communicate with and can be widely distributed.

Public-key cryptography has two main branches of use, namely public-key encryption and digital signatures. Digital signatures themselves can be used for authentication of the remote sender, and this is what the SSH protocol uses it for. When using public-key authentication the owner of the private-key signs a message. This signature can be verified by anyone with access to the owner's public-key, thereby proving that the sender had access to the matching private-key and is thus the entity (person or computer) it claims to be. SSH uses public-key authentication:

To authenticate the server host.
Note that before establishing a connection, a client must always confirm that the presented public-key indeed belongs to his remote server. And only his server maintains a copy of the matching private-key which was used to sign parts of the sent data.
(Optionally) For user authentication.
In a similar way, a user can try to authenticate to the remote server with his own private-key. If the server knows the matching public-key, the user can log on without specifying a password. In general, public-key authentication is considered more secure than password authentication. Imagine a situation where the server has been tampered. In this case password authentication would reveal a valid user name/password combination to the attacker. Public-key authentication on the other side reveals no useful information. And if one applies passphrases on his private-keys, the risk of stealing user private-keys on the client system is also mitigated.

FlowSshC/Cpp/Net supports SSH-RSA and SSH-DSS public-key authentications for both, server host authentication and user authentication. One can create keypairs for user accounts with Bitvise SSH Client, with the OpenSSH "ssh-keygen" utility, or directly through the FlowSshC/Cpp/Net API. Of course, to make the magic work, one must also import and associate generated public-keys with related user accounts on the server itself.

Clients and SSH connections

The interface for manipulating clients:

Client

Before using any SSH functionality, obviously a secure encrypted connection with an SSH server must be established. This is where our client interface comes in handy. It enables one to:

Specify SSH server parameters (host name and port number).
Specify user parameters (user name, password, and keypair).
Specify proxy settings.
Register handlers that are called while the client is connecting or when it disconnects.
Establish the actual connection.
Initiate C2S or S2C port forwarding.

What are proxy servers? Sometimes you might find yourself with reduced connectivity, because you are:

behind a restricting firewall, or
at a public wireless hotspot that severely restricts possible connections, for example to the HTTP and HTTPS protocols only.

Not really the best situation for one relying on SSH, you might think. Fortunately, we can often take advantage of existing proxies to tunnel our SSH connection out in such situations. This is where FlowSshC/Cpp/Net's support for the SOCKS and HTTP CONNECT proxy protocols comes in handy. Under the hood both, SOCKS and HTTP CONNECT, are similar. In both cases, a TCP connection is established between the SSH client and the given proxy server; and in both cases, the proxy server communicates with the destination SSH server over another TCP connection.

What is SSH port forwarding? SSH port forwarding, or TCP/IP connection tunneling, is a process whereby a TCP/IP connection that would otherwise be insecure is tunneled through a secure SSH link, thus protecting the tunneled connection from network attacks. Port forwarding can be used to establish a form of a virtual private network (VPN). As the theory of port forwarding is extensively covered in our Guide to SSH port forwarding, we will only briefly recall some important information here. Port forwarding comes in two variants:

C2S (client-to-server)

In this case, the SSH client binds to a specified port and waits for an incoming TCP connection, which, once established, gets securely forwarded to the SSH server. The SSH server in turn connects and communicates with the requested end-destination.
Essentially with C2S a port from the server is made available on the client host; applications there can access it as any other local port.
In SSH terms this is also called local port forwarding or direct-tcpip.

S2C (server-to-client)

In this case, the SSH server binds to a specified port and waits for an incoming TCP connection, which, once established, gets securely forwarded to the SSH client. The SSH client in turn connects and communicates with the requested end-destination.
Essentially with S2C a port from the client is made available on the server host; applications there can access it as any other local port.
In SSH terms this is also called remote port forwarding or forwarded-tcpip.

Channels

The interface for manipulating SSH channels:

In the SSH world, requests to services are made over channels. Each interactive shell and each forwarded connection for example is a channel. A single SSH connection can host multiple channels at the same time, each of them transferring data in both directions. Of course, under the hood all these channels share a single TCP connection and thus (their packets) are funneled into this one connection.

SSH specifies the following channel types:

session: used for exec requests, interactive shells, and the SFTP subsystem
direct-tcpip: for C2S port forwarding
forwarded-tcpip: for S2C port forwarding
x11: for x11 display forwarding

Here we are only really interested about the session channel, while other channel types are listed for the sake of completeness. You probably remember mentioning direct-tcpip and forwarded-tcpip; both channel types are used for port forwarding and are part of the client interface which we discussed in the previous section. x11 channels are not supported by FlowSshC/Cpp/Net.

Session channels. If you execute an application remotely, start an interactive shell, or do something with the SFTP subsystem, you will internally end up using a session channel. Session channels can allocate a PTY (pseudo terminal). Without a PTY the channel is transparent and can be used to safely transfer binary data. Interactive shells are part of the ClientSessionChannel interface, and SFTP is accessed through the ClientSftpChannel interface. Although SFTP uses a session channel to transfer its binary protocol and file data, it is actually a subsystem and protocol of its own on top of it.