1ssh-base Plugin 2================ 3 4## Introduction 5 6lws-ssh-base is a protcol plugin for libwebsockets that implements a 7generic, abstract, ssh server. 8 9 - very small footprint in code and memory, takes up small part of ESP32 10 11 - written with security in mind: valgrind and Coverity -clean 12 13 - binds to one or more vhosts, that controls listen port(s) 14 15 - all IO and settings abstracted through a single "ops" struct from user code 16 17 - each instance on a vhost has its own "ops" struct, defining server keys, 18 auth method and functions to implement IO and other operations 19 20 - The plugin has no built-in behaviours like check ~/.ssh/authorized_keys, 21 treat auth usernames as system usernames, or spawn the user's shell. 22 Everything potentially dangerous is left to the user ops code to decide 23 how to handle. It's NOT like sshd where running it implies it will accept 24 existing keys for any system user, will spawn a shell, etc, unless you 25 implement those parts in the ops callbacks. 26 27 - The plugin requires extra code around it in the form of the ops struct 28 handlers. So it's role is something like an abstract base class for an ssh 29 server. All the crypto, protocol sequencing and state machine are inside, 30 but all the IO except the network connection is outside. 31 32 - Built as part of libwebsockets, like all plugins may be dynamically loaded 33 at runtime or built statically. Test app `libwebsockets-test-sshd` provided 34 35 - Uses hash and RSA functions from either mbedTLS or OpenSSL automatically, 36 according to which library libwebsockets was built for 37 38To maintain its small size, it implements a single "best of breed" crypto for 39the following functions: 40 41|Function|Crypto| 42|---|---| 43|KEX|curve25519-sha256@libssh.org| 44|Server host key|ssh-rsa (4096b)| 45|Encryption|chacha20-poly1305@openssh.com| 46|Compression|None| 47 48## License 49 50lws-ssh-base is Free Software, available under libwebsockets' MIT license. 51 52The crypto parts are available elsewhere under a BSD license. But for 53simplicity the whole plugin is under MIT. 54 55## Generating your own keys 56 57``` 58 $ ssh-keygen -t rsa -b 4096 -f mykeys 59``` 60 61will ask for a passphrase and generate the private key in `mykeys` and the 62public key in `mykeys.pub`. If you already have a suitable RSA key you use 63with ssh, you can just use that directly. 64 65lws installs a test keypair in /usr[/local]/share/libwebsockets-test-server 66that the test apps will accept. 67 68## Example code 69 701) There's a working example app `libwebsockets-test-sshd` included that 71spawns a bash shell when an ssh client authenticates. The username used on 72the remote ssh has no meaning, it spawns the shell under the credentials of 73"lws-test-sshd" was run under. It accepts the lws ssh test key which is 74installed into /usr[/local]/share/libwebsockets-test-server. 75 76Start the server like this (it wants root only because the server key is stored 77in /etc) 78 79``` 80 $ sudo libwebsockets-test-sshd 81``` 82 83Connect to it using the test private key like this 84 85``` 86 $ ssh -p 2200 -i /usr/local/share/libwebsockets-test-server/lws-ssh-test-keys anyuser@127.0.0.1 87``` 88 892) There's also a working example plugin `lws-sshd-demo` that "subclasses" the 90abstract `lws-ssh-base` plugin to make a protocol which can be used from, 91eg, lwsws. For an lwsws vhost that listens on port 2222 and responds with 92the lws-sshd-demo ssh server, the related config is: 93 94``` 95 { 96 "name": "sshd", 97 "port": "2222", 98 "onlyraw": "1", 99 "ws-protocols": [{ 100 "lws-ssh-base": { 101 "status": "ok", 102 "ops-from": "lws-sshd-demo" 103 }, 104 "lws-sshd-demo": { 105 "status": "ok", 106 "raw": "1" 107 } 108 }] 109 } 110``` 111 112 113 114## Integration to other apps 115 116### Step 0: Build and install libwebsockets 117 118For the `libwebsockets-test-sshd` example, you will need CMake options 119`LWS_WITH_CGI`, since it uses lws helpers to spawn a shell. 120 121lws-ssh-base itself doesn't require CGI support in libwebsockets. 122 123### Step 1: make the code available in your app 124 125Include `lws-plugin-ssh-base` in your app, either as a runtime plugin or by using 126the lws static include scheme. 127 128To bring in the whole of the ssh-base plugin 129into your app in one step, statically, just include 130`plugins/ssh-base/include/lws-plugin-sshd-static-build-includes.h`, you can see 131an example of this in `./test-apps/test-sshd.c`. 132 133### Step 2: define your `struct lws_ssh_ops` 134 135`plugins/ssh-base/include/lws-plugin-ssh.h` defines 136`struct lws_ssh_ops` which is used for all customization and integration 137of the plugin per vhost. Eg, 138 139``` 140static const struct lws_ssh_ops ssh_ops = { 141 .channel_create = ssh_ops_channel_create, 142 .channel_destroy = ssh_ops_channel_destroy, 143 .tx_waiting = ssh_ops_tx_waiting, 144 .tx = ssh_ops_tx, 145 .rx = ssh_ops_rx, 146 .get_server_key = ssh_ops_get_server_key, 147 .set_server_key = ssh_ops_set_server_key, 148 .set_env = ssh_ops_set_env, 149 .pty_req = ssh_ops_pty_req, 150 .child_process_io = ssh_ops_child_process_io, 151 .child_process_terminated = ssh_ops_child_process_terminated, 152 .exec = ssh_ops_exec, 153 .shell = ssh_ops_shell, 154 .is_pubkey_authorized = ssh_ops_is_pubkey_authorized, 155 .banner = ssh_ops_banner, 156 .disconnect_reason = ssh_ops_disconnect_reason, 157 .server_string = "SSH-2.0-Libwebsockets", 158 .api_version = 1, 159}; 160``` 161The `ssh_ops_...()` functions are your implementations for the operations 162needed by the plugin for your purposes. 163 164### Step 3: enable `lws-ssh-base` protocol to a vhost and configure using pvo 165 166A pointer to your struct lws_ssh_ops is passed into the vhost instance of the 167protocol using per-vhost options 168 169``` 170static const struct lws_protocol_vhost_options pvo_ssh_ops = { 171 NULL, 172 NULL, 173 "ops", 174 (void *)&ssh_ops 175}; 176 177static const struct lws_protocol_vhost_options pvo_ssh = { 178 NULL, 179 &pvo_ssh_ops, 180 "lws-sshd-base", 181 "" /* ignored, just matches the protocol name above */ 182}; 183 184... 185 info.port = 22; 186 info.options = LWS_SERVER_OPTION_ONLY_RAW; 187 info.vhost_name = "sshd"; 188 info.protocols = protocols_sshd; 189 info.pvo = &pvo_ssh; 190 191 vh_sshd = lws_create_vhost(context, &info); 192``` 193 194There are two possible pvos supported, "ops", shown above, directly passes the 195ops structure in using the value on the "ops" pvo. 196 197To support other protocols that want to provide ops to lws-ssh-base themselves 198for a particular vhost, you can also provide a pvo `"ops-from"` whose value is 199the name of the protocol also enabled on this vhost, whose protocol ".user" 200pointer points to the ops struct lws-ssh-base should use. 201 202## Integration to other plugins 203 204A worked example of using the abstract `lws-ssh-base` plugin from another 205plugin that provides the ops struct is in `./plugins/protocol_lws_sshd_demo`. 206 207The key points to note 208 209 - the plugin sets the ops struct for the vhost instantiation of `lws-ssh-base` 210 by passing a pointer to the ops struct in its `lws_protocols` struct `user` 211 member. 212 213 - the config for the vhost tells `lws-ssh-base` to pick up the ops struct 214 pointer using an "ops-from" pvo that indicates the protocol name. 215 216``` 217 "lws-ssh-base": { 218 "status": "ok", 219 "ops-from": "lws-sshd-demo" 220 }, 221``` 222 223 - the config for the vhost tells lws this vhost only serves RAW (ie, no http) 224 225``` 226 { 227 "name": "sshd", 228 "port": "2222", 229 "onlyraw": "1", 230 ... 231``` 232 233 - the config for the vhost marks the protocol that uses `lws-ssh-base`, not 234 `lws-ssh-base` itself, as the protocol to be served for raw connections 235 236``` 237 "lws-sshd-demo": { 238 "status": "ok", 239 "raw": "1" 240 ... 241``` 242 243## Notes 244 245You can have the vhost it binds to listen on a nonstandard port. The ssh 246commandline app cane be told to connect to a non-22 port with 247`ssh -p portnum user@hostname` 248 249 250