• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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