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`