libwebsockets
Lightweight C library for HTML5 websockets
lws-plugin-ssh.h
Go to the documentation of this file.
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
33 char term[16];
34 char *modes;
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
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
133typedef void (*lws_ssh_finish_exec)(void *handle, int retcode);
134
135struct 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);
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
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 */
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 */
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
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
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
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
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,
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
uint32_t height_ch
uint32_t modes_len
char term[16]
uint32_t height_px
uint32_t width_ch
uint32_t width_px
size_t(* get_server_key)(struct lws *wsi, uint8_t *buf, size_t len)