libwebsockets/READMEs/README.plugin-sshd-base.md

ssh-base Plugin
================

## Introduction

lws-ssh-base is a protcol plugin for libwebsockets that implements a
generic, abstract, ssh server.

 - very small footprint in code and memory, takes up small part of ESP32
 
 - written with security in mind: valgrind and Coverity -clean
 
 - binds to one or more vhosts, that controls listen port(s)
 
 - all IO and settings abstracted through a single "ops" struct from user code
 
 - each instance on a vhost has its own "ops" struct, defining server keys,
   auth method and functions to implement IO and other operations

 - The plugin has no built-in behaviours like check ~/.ssh/authorized_keys,
   treat auth usernames as system usernames, or spawn the user's shell.
   Everything potentially dangerous is left to the user ops code to decide
   how to handle.  It's NOT like sshd where running it implies it will accept
   existing keys for any system user, will spawn a shell, etc, unless you
   implement those parts in the ops callbacks.
   
 - The plugin requires extra code around it in the form of the ops struct
   handlers.  So it's role is something like an abstract base class for an ssh
   server.  All the crypto, protocol sequencing and state machine are inside,
   but all the IO except the network connection is outside.
   
 - Built as part of libwebsockets, like all plugins may be dynamically loaded
   at runtime or built statically.  Test app `libwebsockets-test-sshd` provided
   
 - Uses hash and RSA functions from either mbedTLS or OpenSSL automatically,
   according to which library libwebsockets was built for

To maintain its small size, it implements a single "best of breed" crypto for
the following functions:

|Function|Crypto|
|---|---|
|KEX|curve25519-sha256@libssh.org|
|Server host key|ssh-rsa (4096b)|
|Encryption|chacha20-poly1305@openssh.com|
|Compression|None|

## License

lws-ssh-base is Free Software, available under libwebsockets' MIT license.

The crypto parts are available elsewhere under a BSD license.  But for
simplicity the whole plugin is under MIT.

## Generating your own keys

```
 $ ssh-keygen -t rsa -b 4096 -f mykeys
```

will ask for a passphrase and generate the private key in `mykeys` and the
public key in `mykeys.pub`.  If you already have a suitable RSA key you use
with ssh, you can just use that directly.

lws installs a test keypair in /usr[/local]/share/libwebsockets-test-server
that the test apps will accept.

## Example code

1) There's a working example app `libwebsockets-test-sshd` included that
spawns a bash shell when an ssh client authenticates.  The username used on
the remote ssh has no meaning, it spawns the shell under the credentials of
"lws-test-sshd" was run under.  It accepts the lws ssh test key which is
installed into /usr[/local]/share/libwebsockets-test-server.

Start the server like this (it wants root only because the server key is stored
in /etc)

```
 $ sudo libwebsockets-test-sshd
```

Connect to it using the test private key like this

```
 $ ssh -p 2200 -i /usr/local/share/libwebsockets-test-server/lws-ssh-test-keys anyuser@127.0.0.1
```

2) There's also a working example plugin `lws-sshd-demo` that "subclasses" the
abstract `lws-ssh-base` plugin to make a protocol which can be used from,
eg, lwsws.  For an lwsws vhost that listens on port 2222 and responds with
the lws-sshd-demo ssh server, the related config is:

```
        {
                "name": "sshd",
                "port": "2222",
                "onlyraw": "1",
                "ws-protocols": [{
                        "lws-ssh-base": {
                                "status": "ok",
                                "ops-from": "lws-sshd-demo"
                        },
                        "lws-sshd-demo": {
                                "status": "ok",
                                "raw": "1"
                        }
                }]
        }
```



## Integration to other apps

### Step 0: Build and install libwebsockets

For the `libwebsockets-test-sshd` example, you will need CMake options
`LWS_WITH_CGI`, since it uses lws helpers to spawn a shell.

lws-ssh-base itself doesn't require CGI support in libwebsockets.

### Step 1: make the code available in your app

Include `lws-plugin-ssh-base` in your app, either as a runtime plugin or by using
the lws static include scheme.

To bring in the whole of the ssh-base plugin
into your app in one step, statically, just include
`plugins/ssh-base/include/lws-plugin-sshd-static-build-includes.h`, you can see
an example of this in `./test-apps/test-sshd.c`.

### Step 2: define your `struct lws_ssh_ops`

`plugins/ssh-base/include/lws-plugin-ssh.h` defines
`struct lws_ssh_ops` which is used for all customization and integration
of the plugin per vhost.  Eg,

```
static const struct lws_ssh_ops ssh_ops = {
	.channel_create			= ssh_ops_channel_create,
	.channel_destroy		= ssh_ops_channel_destroy,
	.tx_waiting			= ssh_ops_tx_waiting,
	.tx				= ssh_ops_tx,
	.rx				= ssh_ops_rx,
	.get_server_key			= ssh_ops_get_server_key,
	.set_server_key			= ssh_ops_set_server_key,
	.set_env			= ssh_ops_set_env,
	.pty_req			= ssh_ops_pty_req,
	.child_process_io		= ssh_ops_child_process_io,
	.child_process_terminated	= ssh_ops_child_process_terminated,
	.exec				= ssh_ops_exec,
	.shell				= ssh_ops_shell,
	.is_pubkey_authorized		= ssh_ops_is_pubkey_authorized,
	.banner				= ssh_ops_banner,
	.disconnect_reason		= ssh_ops_disconnect_reason,
	.server_string			= "SSH-2.0-Libwebsockets",
	.api_version			= 1,
};
```
The `ssh_ops_...()` functions are your implementations for the operations
needed by the plugin for your purposes.

### Step 3: enable `lws-ssh-base` protocol to a vhost and configure using pvo

A pointer to your struct lws_ssh_ops is passed into the vhost instance of the
protocol using per-vhost options

```
static const struct lws_protocol_vhost_options pvo_ssh_ops = {
	NULL,
	NULL,
	"ops",
	(void *)&ssh_ops
};

static const struct lws_protocol_vhost_options pvo_ssh = {
	NULL,
	&pvo_ssh_ops,
	"lws-sshd-base",
	"" /* ignored, just matches the protocol name above */
};

...
	info.port = 22;
	info.options = LWS_SERVER_OPTION_ONLY_RAW;
	info.vhost_name = "sshd";
	info.protocols = protocols_sshd;
	info.pvo = &pvo_ssh;

	vh_sshd = lws_create_vhost(context, &info);
```

There are two possible pvos supported, "ops", shown above, directly passes the
ops structure in using the value on the "ops" pvo.

To support other protocols that want to provide ops to lws-ssh-base themselves
for a particular vhost, you can also provide a pvo `"ops-from"` whose value is
the name of the protocol also enabled on this vhost, whose protocol ".user"
pointer points to the ops struct lws-ssh-base should use.

## Integration to other plugins

A worked example of using the abstract `lws-ssh-base` plugin from another
plugin that provides the ops struct is in `./plugins/protocol_lws_sshd_demo`.

The key points to note

 - the plugin sets the ops struct for the vhost instantiation of `lws-ssh-base`
 by passing a pointer to the ops struct in its `lws_protocols` struct `user`
 member.
 
 - the config for the vhost tells `lws-ssh-base` to pick up the ops struct
 pointer using an "ops-from" pvo that indicates the protocol name.
 
```
 			"lws-ssh-base": {
                                "status": "ok",
                                "ops-from": "lws-sshd-demo"
                        },
```

 - the config for the vhost tells lws this vhost only serves RAW (ie, no http)
 
```
         {
                "name": "sshd",
                "port": "2222",
                "onlyraw": "1",
                ...
```

 - the config for the vhost marks the protocol that uses `lws-ssh-base`, not
 `lws-ssh-base` itself, as the protocol to be served for raw connections

```
                        "lws-sshd-demo": {
                                "status": "ok",
                                "raw": "1"
                         ...
```

## Notes

You can have the vhost it binds to listen on a nonstandard port.  The ssh
commandline app cane be told to connect to a non-22 port with
`ssh -p portnum user@hostname`