5.4 Forwarded command execution

This example application implements a pair of ssh2 clients. The first client requests a TCP port forwarding on a server and uses the forwarded port to let the second client connect to a second server. The second client executes a remote command like in the Remote command execution example.

The two client sessions instantiated in our application are referred as the fwd session and the rexec session. Similarly, the first server host that is used as a proxy is called fwd_host and the second server that executes the remote command is called rexec_host.

From the remote servers point of view, running our application is similar to invocation of the following OpenSSH commands on the localhost terminal:

This approach relies on a direct connection between localhost and rexec_host in order to request execution of the command and fetch its output. This means that fwd_host is only used as a TCP proxy for the rexec connection and never see the content of the rexec session in clear text.

The same goal can be achieved by running the following commands on different hosts:

This second approach is more common but less secure as it does not rely on port forwarding. In this case, the second client runs on bounce_host. This lets bounce_host see what happens as it processes user data in clear text, including any password typed to connect to rexec_host. In the same way, using user keys from bounce_host with this approach requires the use of possibly unsafe ssh agent forwarding.

Instead, our example application implements the first approach as a simple tool that can be invoked like this:

In this example, we rely on the ability of libassh to let the application handle the network streams as buffers. This allows to implement forwarding of the rexec session by the fwd session without piping the network streams of the first through the operating system. That's why we do not rely on system calls for this task.

This means that the application directly generates and processes the network streams of the nested ssh2 sessions. From the operating system point of view, there is a single TCP socket used to connect to fwd_host, as in the other client examples.

The first thing to do in the main function is initialization of the two sessions. A single interactive session state machine is used because it's only needed by the rexec session.

Our main loop just has to run the event loops of the two sessions. The fwd session disconnects when the rexec session terminates.

The main function ends with cleanup of the sessions and context.

We will now focus on the implementation of the event loop of the fwd session.

The port forwarding mechanism in ssh2 is provided by the connection protocol and uses a channel in order to transport the stream of the forwarded TCP connection. This means that our fwd session will need to open such a channel in order to let the application exchange data with rexec_host.

There are many programming constructs that could be used to move data between the channel of the fwd session and the I/O events of the rexec session. In this application, we choose to copy the data directly between libassh buffers in one direction but we use a software fifo in the other direction.

Here is the API of our simple fifo. The fifo_read and fifo_write functions return the actual amount of data transferred.

Exchanging data requires sharing the channel and fifo objects between the two sessions. These are declared here:

Then comes the ssh_loop_fwd function with the usual event loop code construct:

User authentication and key-exchange related events are handled using helper functions as detailed in the previous examples and are not shown here.

Because this session talks to fwd_host through a TCP socket, we just have to rely on the usual helper function in order to handle the network I/O events.

We setup the TCP port forwarding as soon as the connection protocol starts. The asshh_portfwd_open_direct_tcpip function serializes our fwd_rq parameters and calls the assh_channel_open function. This makes the fwd_channel variable point to the opening channel object.

We then need to wait for the channel open reply from fwd_host in order to know if the port forwarding is accepted.

At this point, fwd_host has initiated a TCP connection to rexec_host on behalf of our application. It will start to forward any data transmitted by rexec_host to our fwd session. The library will report this as incoming channel data. When this occurs, we just have to copy as many data as we can to our software fifo, then yield to the event loop of the rexec_session.

We are almost done with the code of the fwd session event loop. We still have to handle the channel close event that will be reported if the connection to rexec_host gets broken.

The code of the event loop ends as usual, with a default event handler. The ssh_loop_fwd function returns 0 when no more events will be reported. The disconnection request code is factored at the end of the function.

We can now focus on the event loop of the rexec session located in the ssh_loop_rexec function.

Reading data from the fifo in order to feed the rexec session with the ssh stream from rexec_host is the easier part. We just take care of yielding to the fwd session event loop when the fifo is empty.

Because we do not use a fifo in the other direction, there is more work to do in order to send the rexec network stream through the port forwarding channel. We first have to make sure that the channel exists and has reached the ASSH_CHANNEL_ST_OPEN state. When this is the case, an outgoing packet is allocated and filled with some of the network stream. We also yield to the fwd session event loop if we were not able to send some data yet.

Other events of the rexec session are handled in the exact same way as in the Remote command execution example application and are not detailed here.

As in the event loop of the fwd session, the function returns 0 when there are no more event to report.

In a real world ssh2 client based on libassh, such a system independent code construct would allow forwarding a session through an arbitrary number hosts with a single user command, replacing unsafe SSH agent forwarding altogether.