plugin: lws-ssh-base

Collaboration diagram for plugin: lws-ssh-base:

Data Structures
struct	lws_ssh_ops

Typedefs
typedef void(*	lws_ssh_finish_exec) (void *handle, int retcode)

Detailed Description

Plugin lws-ssh-base

This is the interface to customize the ssh server per-vhost. A pointer to your struct lws_ssh_ops with the members initialized is passed in using pvo when you create the vhost. The pvo is attached to the protocol name

• "lws-ssh-base" - the ssh serving part
• "lws-telnetd-base" - the telnet serving part

This way you can have different instances of ssh servers wired up to different IO and server keys per-vhost.

See also ./READMEs/README-plugin-sshd-base.md

---

Data Structure Documentation

lws_ssh_ops

struct lws_ssh_ops

Definition at line 121 of file lws-plugin-ssh.h.

Collaboration diagram for lws_ssh_ops:

Data Fields
int(*)(struct lws *wsi, void **priv)	channel_create	channel_create() - Channel created Parameters wsi raw wsi representing this connection priv pointer to void * you can allocate and attach to the channel Called when new channel created, *priv should be set to any allocation your implementation needs You probably want to save the wsi inside your priv struct. Calling lws_callback_on_writable() on this wsi causes your ssh server instance to call .tx_waiting() next time you can write something to the client.
int(*)(void *priv)	channel_destroy	channel_destroy() - Channel is being destroyed Parameters priv void * you set when channel was created (or NULL) Called when channel destroyed, priv should be freed if you allocated into it.
int(*)(void *priv, struct lws *wsi, const uint8_t *buf, uint32_t len)	rx	rx() - receive payload from peer Parameters priv void * you set when this channel was created wsi struct lws * for the ssh connection buf pointer to start of received data len bytes of received data available at buf len bytes of payload from the peer arrived and is available at buf
int(*)(void *priv)	tx_waiting	tx_waiting() - report if data waiting to transmit on the channel Parameters priv void * you set when this channel was created returns a bitmask of LWS_STDOUT and LWS_STDERR, with the bits set if they have tx waiting to send, else 0 if nothing to send You should use one of the lws_callback_on_writable() family to trigger the ssh protocol to ask if you have any tx waiting. Returning -1 from here will close the tcp connection to the client.
size_t(*)(void *priv, int stdch, uint8_t *buf, size_t len)	tx	tx() - provide data to send on the channel Parameters priv void * you set when this channel was created stdch LWS_STDOUT or LWS_STDERR buf start of the buffer to copy the transmit data into len max length of the buffer in bytes copy and consume up to len bytes into *buf, return the actual copied count. You should use one of the lws_callback_on_writable() family to trigger the ssh protocol to ask if you have any tx waiting. If you do you will get calls here to fetch it, for each of LWS_STDOUT or LWS_STDERR that were reported to be waiting by tx_waiting().
size_t(*)(struct lws *wsi, uint8_t *buf, size_t len)	get_server_key	get_server_key() - retreive the secret keypair for this server Parameters wsi the wsi representing the connection to the client buf start of the buffer to copy the keypair into len length of the buffer in bytes load the server key into buf, max len len. Returns length of buf set to key, or 0 if no key or other error. If there is no key, the error isn't fatal... the plugin will generate a random key and store it using *get_server_key() for subsequent times.
size_t(*)(struct lws *wsi, uint8_t *buf, size_t len)	set_server_key	set_server_key() - store the secret keypair of this server Parameters wsi the wsi representing the connection to the client buf start of the buffer containing the keypair len length of the keypair in bytes store the server key in buf, length len, to nonvolatile stg. Return length stored, 0 for fail.
int(*)(void *priv, const char *name, const char *value)	set_env	set_env() - Set environment variable Parameters priv void * you set when this channel was created name env var name value value to set env var to Client requested to set environment var. Return nonzero to fail.
int(*)(void *priv, struct lws *wsi, const char *command, lws_ssh_finish_exec finish, void *finish_handle)	exec	exec() - spawn command and wire up stdin/out/err to ssh channel Parameters priv void * you set when this channel was created wsi the struct lws the connection belongs to command string containing path to app and arguments finish function to call to indicate the exec finished finish_handle opaque handle identifying this exec for use with finish Client requested to exec something. Return nonzero to fail.
int(*)(void *priv, struct lws *wsi, lws_ssh_finish_exec finish, void *finish_handle)	shell	shell() - Spawn shell that is appropriate for user Parameters priv void * you set when this channel was created wsi the struct lws the connection belongs to finish function to call to indicate the exec finished finish_handle opaque handle identifying this exec for use with finish Spawn the appropriate shell for this user. Return 0 for OK or nonzero to fail.
int(*)(void *priv, struct lws_ssh_pty *pty)	pty_req	pty_req() - Create a Pseudo-TTY as described in pty Parameters priv void * you set when this channel was created pty pointer to struct describing the desired pty Client requested a pty. Return nonzero to fail.
int(*)(void *priv, struct lws *wsi, struct lws_cgi_args *args)	child_process_io	child_process_io() - Child process has IO Parameters priv void * you set when this channel was created wsi the struct lws the connection belongs to args information related to the cgi IO events Child process has IO
int(*)(void *priv, struct lws *wsi)	child_process_terminated	child_process_io() - Child process has terminated Parameters priv void * you set when this channel was created wsi the struct lws the connection belongs to Child process has terminated
void(*)(uint32_t reason, const char *desc, const char *desc_lang)	disconnect_reason	disconnect_reason() - Optional notification why connection is lost Parameters reason one of the SSH_DISCONNECT_ constants desc UTF-8 description of reason desc_lang RFC3066 language for description The remote peer may tell us why it's going to disconnect. Handling this is optional.
int(*)(const char *username, const char *type, const uint8_t *peer, int peer_len)	is_pubkey_authorized	is_pubkey_authorized() - check if auth pubkey is valid for user Parameters username username the key attempted to authenticate type "ssh-rsa" peer start of Public key peer used to authenticate peer_len length of Public key at peer We confirmed the client has the private key for this public key... but is that keypair something authorized for this username on this server? 0 = OK, 1 = fail Normally this checks for a copy of the same public key stored somewhere out of band, it's the same procedure as openssh does when looking in ~/.ssh/authorized_keys
size_t(*)(char *buf, size_t max_len, char *lang, size_t max_lang_len)	banner	banner() - copy the connection banner to buffer Parameters buf start of the buffer to copy to max_len maximum number of bytes the buffer can hold lang start of the buffer to copy language descriptor to max_lang_len maximum number of bytes lang can hold Copy the text banner to be returned to client on connect, before auth, into buf. The text should be in UTF-8. if none wanted then leave .banner as NULL. lang should have a RFC3066 language descriptor like "en/US" copied to it. Returns the number of bytes copies to buf.
const char *	server_string	SSH version string sent to client (required) By convention a string like "SSH-2.0-Libwebsockets"
char	api_version	set to the API version you support (current is in LWS_SSH_OPS_VERSION) You should set it to an integer like 1, that reflects the latest api at the time your code was written. If the ops api_version is not equal to the LWS_SSH_OPS_VERSION of the plugin, it will error out at runtime.

Typedef Documentation

lws_ssh_finish_exec

typedef void(* lws_ssh_finish_exec) (void *handle, int retcode)

#include <plugins/ssh-base/include/lws-plugin-ssh.h>

Definition at line 119 of file lws-plugin-ssh.h.