1 /* 2 * libwebsockets - small server side websockets and web server implementation 3 * 4 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com> 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 22 * IN THE SOFTWARE. 23 */ 24 25 #if !defined(__LWS_PLUGIN_SSH_H__) 26 #define __LWS_PLUGIN_SSH_H__ 27 28 #define LWS_CALLBACK_SSH_UART_SET_RXFLOW (LWS_CALLBACK_USER + 800) 29 30 #define LWS_SSH_OPS_VERSION 2 31 32 struct lws_ssh_pty { 33 char term[16]; 34 char *modes; 35 uint32_t width_ch; 36 uint32_t height_ch; 37 uint32_t width_px; 38 uint32_t height_px; 39 uint32_t modes_len; 40 }; 41 42 #define SSHMO_TTY_OP_END 0 /* Indicates end of options. */ 43 #define SSHMO_VINTR 1 /* Interrupt character; 255 if none. Similarly 44 * for the other characters. Not all of these 45 * characters are supported on all systems. */ 46 #define SSHMO_VQUIT 2 /* The quit character (sends SIGQUIT signal on 47 * POSIX systems). */ 48 #define SSHMO_VERASE 3 /* Erase the character to left of the cursor. */ 49 #define SSHMO_VKILL 4 /* Kill the current input line. */ 50 #define SSHMO_VEOF 5 /* End-of-file character (sends EOF from the 51 * terminal). */ 52 #define SSHMO_VEOL 6 /* End-of-line character in addition to 53 * carriage return and/or linefeed. */ 54 #define SSHMO_VEOL2 7 /* Additional end-of-line character. */ 55 #define SSHMO_VSTART 8 /* Continues paused output (normally 56 * control-Q). */ 57 #define SSHMO_VSTOP 9 /* Pauses output (normally control-S). */ 58 #define SSHMO_VSUSP 10 /* Suspends the current program. */ 59 #define SSHMO_VDSUSP 11 /* Another suspend character. */ 60 #define SSHMO_VREPRINT 12 /* Reprints the current input line. */ 61 #define SSHMO_VWERASE 13 /* Erases a word left of cursor. */ 62 #define SSHMO_VLNEXT 14 /* Enter the next character typed literally, 63 * even if it is a special character */ 64 #define SSHMO_VFLUSH 15 /* Character to flush output. */ 65 #define SSHMO_VSWTCH 16 /* Switch to a different shell layer. */ 66 #define SSHMO_VSTATUS 17 /* Prints system status line (load, command, 67 * pid, etc). */ 68 #define SSHMO_VDISCARD 18 /* Toggles the flushing of terminal output. */ 69 #define SSHMO_IGNPAR 30 /* The ignore parity flag. The parameter 70 * SHOULD be 0 if this flag is FALSE, 71 * and 1 if it is TRUE. */ 72 #define SSHMO_PARMRK 31 /* Mark parity and framing errors. */ 73 #define SSHMO_INPCK 32 /* Enable checking of parity errors. */ 74 #define SSHMO_ISTRIP 33 /* Strip 8th bit off characters. */ 75 #define SSHMO_INLCR 34 /* Map NL into CR on input. */ 76 #define SSHMO_IGNCR 35 /* Ignore CR on input. */ 77 #define SSHMO_ICRNL 36 /* Map CR to NL on input. */ 78 #define SSHMO_IUCLC 37 /* Translate uppercase characters to lowercase. */ 79 #define SSHMO_IXON 38 /* Enable output flow control. */ 80 #define SSHMO_IXANY 39 /* Any char will restart after stop. */ 81 #define SSHMO_IXOFF 40 /* Enable input flow control. */ 82 #define SSHMO_IMAXBEL 41 /* Ring bell on input queue full. */ 83 #define SSHMO_ISIG 50 /* Enable signals INTR, QUIT, [D]SUSP. */ 84 #define SSHMO_ICANON 51 /* Canonicalize input lines. */ 85 #define SSHMO_XCASE 52 /* Enable input and output of uppercase 86 * characters by preceding their lowercase 87 * equivalents with "\". */ 88 #define SSHMO_ECHO 53 /* Enable echoing. */ 89 #define SSHMO_ECHOE 54 /* Visually erase chars. */ 90 #define SSHMO_ECHOK 55 /* Kill character discards current line. */ 91 #define SSHMO_ECHONL 56 /* Echo NL even if ECHO is off. */ 92 #define SSHMO_NOFLSH 57 /* Don't flush after interrupt. */ 93 #define SSHMO_TOSTOP 58 /* Stop background jobs from output. */ 94 #define SSHMO_IEXTEN 59 /* Enable extensions. */ 95 #define SSHMO_ECHOCTL 60 /* Echo control characters as ^(Char). */ 96 #define SSHMO_ECHOKE 61 /* Visual erase for line kill. */ 97 #define SSHMO_PENDIN 62 /* Retype pending input. */ 98 #define SSHMO_OPOST 70 /* Enable output processing. */ 99 #define SSHMO_OLCUC 71 /* Convert lowercase to uppercase. */ 100 #define SSHMO_ONLCR 72 /* Map NL to CR-NL. */ 101 #define SSHMO_OCRNL 73 /* Translate carriage return to newline (out). */ 102 #define SSHMO_ONOCR 74 /* Translate newline to CR-newline (out). */ 103 #define SSHMO_ONLRET 75 /* Newline performs a carriage return (out). */ 104 #define SSHMO_CS7 90 /* 7 bit mode. */ 105 #define SSHMO_CS8 91 /* 8 bit mode. */ 106 #define SSHMO_PARENB 92 /* Parity enable. */ 107 #define SSHMO_PARODD 93 /* Odd parity, else even. */ 108 #define SSHMO_TTY_OP_ISPEED 128 /* Specifies the input baud rate in 109 * bits per second. */ 110 #define SSHMO_TTY_OP_OSPEED 129 /* Specifies the output baud rate in 111 * bits per second. */ 112 113 /*! \defgroup ssh-base plugin: lws-ssh-base 114 * \ingroup Protocols-and-Plugins 115 * 116 * ##Plugin lws-ssh-base 117 * 118 * This is the interface to customize the ssh server per-vhost. A pointer 119 * to your struct lws_ssh_ops with the members initialized is passed in using 120 * pvo when you create the vhost. The pvo is attached to the protocol name 121 * 122 * - "lws-ssh-base" - the ssh serving part 123 * 124 * - "lws-telnetd-base" - the telnet serving part 125 * 126 * This way you can have different instances of ssh servers wired up to 127 * different IO and server keys per-vhost. 128 * 129 * See also ./READMEs/README-plugin-sshd-base.md 130 */ 131 ///@{ 132 133 typedef void (*lws_ssh_finish_exec)(void *handle, int retcode); 134 135 struct lws_ssh_ops { 136 /** 137 * channel_create() - Channel created 138 * 139 * \param wsi: raw wsi representing this connection 140 * \param priv: pointer to void * you can allocate and attach to the 141 * channel 142 * 143 * Called when new channel created, *priv should be set to any 144 * allocation your implementation needs 145 * 146 * You probably want to save the wsi inside your priv struct. Calling 147 * lws_callback_on_writable() on this wsi causes your ssh server 148 * instance to call .tx_waiting() next time you can write something 149 * to the client. 150 */ 151 int (*channel_create)(struct lws *wsi, void **priv); 152 153 /** 154 * channel_destroy() - Channel is being destroyed 155 * 156 * \param priv: void * you set when channel was created (or NULL) 157 * 158 * Called when channel destroyed, priv should be freed if you allocated 159 * into it. 160 */ 161 int (*channel_destroy)(void *priv); 162 163 /** 164 * rx() - receive payload from peer 165 * 166 * \param priv: void * you set when this channel was created 167 * \param wsi: struct lws * for the ssh connection 168 * \param buf: pointer to start of received data 169 * \param len: bytes of received data available at buf 170 * 171 * len bytes of payload from the peer arrived and is available at buf 172 */ 173 int (*rx)(void *priv, struct lws *wsi, const uint8_t *buf, uint32_t len); 174 175 /** 176 * tx_waiting() - report if data waiting to transmit on the channel 177 * 178 * \param priv: void * you set when this channel was created 179 * 180 * returns a bitmask of LWS_STDOUT and LWS_STDERR, with the bits set 181 * if they have tx waiting to send, else 0 if nothing to send 182 * 183 * You should use one of the lws_callback_on_writable() family to 184 * trigger the ssh protocol to ask if you have any tx waiting. 185 * 186 * Returning -1 from here will close the tcp connection to the client. 187 */ 188 int (*tx_waiting)(void *priv); 189 190 /** 191 * tx() - provide data to send on the channel 192 * 193 * \param priv: void * you set when this channel was created 194 * \param stdch: LWS_STDOUT or LWS_STDERR 195 * \param buf: start of the buffer to copy the transmit data into 196 * \param len: max length of the buffer in bytes 197 * 198 * copy and consume up to len bytes into *buf, 199 * return the actual copied count. 200 * 201 * You should use one of the lws_callback_on_writable() family to 202 * trigger the ssh protocol to ask if you have any tx waiting. If you 203 * do you will get calls here to fetch it, for each of LWS_STDOUT or 204 * LWS_STDERR that were reported to be waiting by tx_waiting(). 205 */ 206 size_t (*tx)(void *priv, int stdch, uint8_t *buf, size_t len); 207 208 /** 209 * get_server_key() - retreive the secret keypair for this server 210 * 211 * \param wsi: the wsi representing the connection to the client 212 * \param buf: start of the buffer to copy the keypair into 213 * \param len: length of the buffer in bytes 214 * 215 * load the server key into buf, max len len. Returns length of buf 216 * set to key, or 0 if no key or other error. If there is no key, 217 * the error isn't fatal... the plugin will generate a random key and 218 * store it using *get_server_key() for subsequent times. 219 */ 220 size_t (*get_server_key)(struct lws *wsi, uint8_t *buf, size_t len); 221 222 /** 223 * set_server_key() - store the secret keypair of this server 224 * 225 * \param wsi: the wsi representing the connection to the client 226 * \param buf: start of the buffer containing the keypair 227 * \param len: length of the keypair in bytes 228 * 229 * store the server key in buf, length len, to nonvolatile stg. 230 * Return length stored, 0 for fail. 231 */ 232 size_t (*set_server_key)(struct lws *wsi, uint8_t *buf, size_t len); 233 234 /** 235 * set_env() - Set environment variable 236 * 237 * \param priv: void * you set when this channel was created 238 * \param name: env var name 239 * \param value: value to set env var to 240 * 241 * Client requested to set environment var. Return nonzero to fail. 242 */ 243 int (*set_env)(void *priv, const char *name, const char *value); 244 245 /** 246 * exec() - spawn command and wire up stdin/out/err to ssh channel 247 * 248 * \param priv: void * you set when this channel was created 249 * \param wsi: the struct lws the connection belongs to 250 * \param command: string containing path to app and arguments 251 * \param finish: function to call to indicate the exec finished 252 * \param finish_handle: opaque handle identifying this exec for use with \p finish 253 * 254 * Client requested to exec something. Return nonzero to fail. 255 */ 256 int (*exec)(void *priv, struct lws *wsi, const char *command, lws_ssh_finish_exec finish, void *finish_handle); 257 258 /** 259 * shell() - Spawn shell that is appropriate for user 260 * 261 * \param priv: void * you set when this channel was created 262 * \param wsi: the struct lws the connection belongs to 263 * \param finish: function to call to indicate the exec finished 264 * \param finish_handle: opaque handle identifying this exec for use with \p finish 265 * 266 * Spawn the appropriate shell for this user. Return 0 for OK 267 * or nonzero to fail. 268 */ 269 int (*shell)(void *priv, struct lws *wsi, lws_ssh_finish_exec finish, void *finish_handle); 270 271 /** 272 * pty_req() - Create a Pseudo-TTY as described in pty 273 * 274 * \param priv: void * you set when this channel was created 275 * \param pty: pointer to struct describing the desired pty 276 * 277 * Client requested a pty. Return nonzero to fail. 278 */ 279 int (*pty_req)(void *priv, struct lws_ssh_pty *pty); 280 281 /** 282 * child_process_io() - Child process has IO 283 * 284 * \param priv: void * you set when this channel was created 285 * \param wsi: the struct lws the connection belongs to 286 * \param args: information related to the cgi IO events 287 * 288 * Child process has IO 289 */ 290 int (*child_process_io)(void *priv, struct lws *wsi, 291 struct lws_cgi_args *args); 292 293 /** 294 * child_process_io() - Child process has terminated 295 * 296 * \param priv: void * you set when this channel was created 297 * \param wsi: the struct lws the connection belongs to 298 * 299 * Child process has terminated 300 */ 301 int (*child_process_terminated)(void *priv, struct lws *wsi); 302 303 /** 304 * disconnect_reason() - Optional notification why connection is lost 305 * 306 * \param reason: one of the SSH_DISCONNECT_ constants 307 * \param desc: UTF-8 description of reason 308 * \param desc_lang: RFC3066 language for description 309 * 310 * The remote peer may tell us why it's going to disconnect. Handling 311 * this is optional. 312 */ 313 void (*disconnect_reason)(uint32_t reason, const char *desc, 314 const char *desc_lang); 315 316 /** 317 * is_pubkey_authorized() - check if auth pubkey is valid for user 318 * 319 * \param username: username the key attempted to authenticate 320 * \param type: "ssh-rsa" 321 * \param peer: start of Public key peer used to authenticate 322 * \param peer_len: length of Public key at peer 323 * 324 * We confirmed the client has the private key for this public key... 325 * but is that keypair something authorized for this username on this 326 * server? 0 = OK, 1 = fail 327 * 328 * Normally this checks for a copy of the same public key stored 329 * somewhere out of band, it's the same procedure as openssh does 330 * when looking in ~/.ssh/authorized_keys 331 */ 332 int (*is_pubkey_authorized)(const char *username, 333 const char *type, const uint8_t *peer, int peer_len); 334 335 /** 336 * banner() - copy the connection banner to buffer 337 * 338 * \param buf: start of the buffer to copy to 339 * \param max_len: maximum number of bytes the buffer can hold 340 * \param lang: start of the buffer to copy language descriptor to 341 * \param max_lang_len: maximum number of bytes lang can hold 342 * 343 * Copy the text banner to be returned to client on connect, 344 * before auth, into buf. The text should be in UTF-8. 345 * if none wanted then leave .banner as NULL. 346 * 347 * lang should have a RFC3066 language descriptor like "en/US" 348 * copied to it. 349 * 350 * Returns the number of bytes copies to buf. 351 */ 352 size_t (*banner)(char *buf, size_t max_len, char *lang, 353 size_t max_lang_len); 354 355 /** 356 * SSH version string sent to client (required) 357 * By convention a string like "SSH-2.0-Libwebsockets" 358 */ 359 const char *server_string; 360 361 /** 362 * set to the API version you support (current is in 363 * LWS_SSH_OPS_VERSION) You should set it to an integer like 1, 364 * that reflects the latest api at the time your code was written. If 365 * the ops api_version is not equal to the LWS_SSH_OPS_VERSION of the 366 * plugin, it will error out at runtime. 367 */ 368 char api_version; 369 }; 370 ///@} 371 372 #endif 373 374