5.2 Simple loopback server

This simple server application accepts all interactive session open messages from a connecting client and sends back any data received over open channels. When connecting using a standard client, this has the effect of echoing any character typed.

Unlike code of the previous example that handles connection protocol related events using helper functions, those events are handled directly by the application here. This example also shows how to take control of the underlying channel flow control mechanism provided by the ssh2 protocol.

In this server application, we use a single struct assh_context_s object and different struct assh_session_s objects for connecting clients. A single client can connect at the same time. The context is initialized as shown previously:

A server context needs to have some host keys registered. We try to load host keys from standard locations using an helper function. This may however require root privileges. That's why we fallback to creating an ephemeral host key by calling the assh_key_create function:

We can then start waiting for a client connection and initialize an struct assh_session_s object when this occurs:

Then comes the event loop:

Some events are handled using helper functions, as detailed in the previous example:

When the client sends an SSH_MSG_CHANNEL_OPEN packet to our server, this ends up reporting the ASSH_EVENT_CHANNEL_OPEN event to the application. In our case, we want to allow the client to open channels of the session type. Other types of channel will be rejected by our server:

The ssh2 connection protocol provides a flow control mechanism for channels. This allows limiting the amount of data that the remote host is allowed to send through a channel. This amount is the window size. When the remote host has consumed a part of the window by sending data, the local side has to grant more window space again. This mechanism is implemented separately in both directions.

Instead of letting the library manage the window size for us, we chose here to take control of the window size in the application. This is a wise choice in the case of a loopback server because we have to make sure that we will be able to send back any received data immediately. We do not want to be limited by the window size with some data that we would have to store until we are granted more window space. We need to have the window sizes synchronized between the two directions. That's why we grant the same initial window size and packet size that is granted by the remote host in the opposite direction:

When a channel open is acknowledged, the struct assh_channel_s object pointed by ev->ch lives until a close event is reported. In our simple example, we have no private context to attach and we do not need to keep track of it because further events will provide the pointer to the struct assh_channel_s instance again.

Setting the initial window size is not enough, we have to keep the window sizes of both directions in sync when data is exchanged over a channel. Because we disabled automatic window adjustment, we need to handle the ASSH_EVENT_CHANNEL_WINDOW event and call the assh_channel_window_adjust function. We want to increase our window size by the same amount that was granted by the remote side. This occurs when the event is reported:

Note that we have to acknowledge the event before increasing the window size because most functions of the library can not be called between the pair of calls to assh_event_get and assh_event_done.

A connecting client will request execution of a shell process on the server. Even if we only want to implement a loopback server, we need to fake acceptance of this request or the client may disconnect. This requires replying to channel related requests of the shell type:

Then comes handling of the data transferred over the channels. When incoming data is reported by the library, we need to allocate a buffer in order to send the same amount of data back to the client. However, the current window size of the channel may not allow sending all the data, that's why the assh_channel_data_alloc function is able adjust the size. In our case though, the function is guaranteed to let us allocate the requested size because of the control we have over the window size.

We must then update the event with the amount of incoming data we were able to consume. Again, we have to acknowledge the event before sending the data back.

We are almost done with our loopback server. We still need to acknowledge other events:

When the connection closes, we cleanup the session and we are ready to wait for an other connecting client: