libwebsockets
Lightweight C library for HTML5 websockets
lws_ssh_ops Struct Reference

Data Fields

int(* channel_create )(struct lws *wsi, void **priv)
 
int(* channel_destroy )(void *priv)
 
int(* rx )(void *priv, struct lws *wsi, const uint8_t *buf, uint32_t len)
 
int(* tx_waiting )(void *priv)
 
size_t(* tx )(void *priv, int stdch, uint8_t *buf, size_t len)
 
size_t(* get_server_key )(struct lws *wsi, uint8_t *buf, size_t len)
 
size_t(* set_server_key )(struct lws *wsi, uint8_t *buf, size_t len)
 
int(* set_env )(void *priv, const char *name, const char *value)
 
int(* exec )(void *priv, struct lws *wsi, const char *command, lws_ssh_finish_exec finish, void *finish_handle)
 
int(* shell )(void *priv, struct lws *wsi, lws_ssh_finish_exec finish, void *finish_handle)
 
int(* pty_req )(void *priv, struct lws_ssh_pty *pty)
 
int(* child_process_io )(void *priv, struct lws *wsi, struct lws_cgi_args *args)
 
int(* child_process_terminated )(void *priv, struct lws *wsi)
 
void(* disconnect_reason )(uint32_t reason, const char *desc, const char *desc_lang)
 
int(* is_pubkey_authorized )(const char *username, const char *type, const uint8_t *peer, int peer_len)
 
size_t(* banner )(char *buf, size_t max_len, char *lang, size_t max_lang_len)
 
const char * server_string
 
char api_version
 

Field Documentation

◆ api_version

char lws_ssh_ops::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.

◆ banner

size_t(* lws_ssh_ops::banner) (char *buf, size_t max_len, char *lang, size_t max_lang_len)

banner() - copy the connection banner to buffer

Parameters
bufstart of the buffer to copy to
max_lenmaximum number of bytes the buffer can hold
langstart of the buffer to copy language descriptor to
max_lang_lenmaximum 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.

◆ channel_create

int(* lws_ssh_ops::channel_create) (struct lws *wsi, void **priv)

channel_create() - Channel created

Parameters
wsiraw wsi representing this connection
privpointer 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.

◆ channel_destroy

int(* lws_ssh_ops::channel_destroy) (void *priv)

channel_destroy() - Channel is being destroyed

Parameters
privvoid * you set when channel was created (or NULL)

Called when channel destroyed, priv should be freed if you allocated into it.

◆ child_process_io

int(* lws_ssh_ops::child_process_io) (void *priv, struct lws *wsi, struct lws_cgi_args *args)

child_process_io() - Child process has IO

Parameters
privvoid * you set when this channel was created
wsithe struct lws the connection belongs to
argsinformation related to the cgi IO events

Child process has IO

◆ child_process_terminated

int(* lws_ssh_ops::child_process_terminated) (void *priv, struct lws *wsi)

child_process_io() - Child process has terminated

Parameters
privvoid * you set when this channel was created
wsithe struct lws the connection belongs to

Child process has terminated

◆ disconnect_reason

void(* lws_ssh_ops::disconnect_reason) (uint32_t reason, const char *desc, const char *desc_lang)

disconnect_reason() - Optional notification why connection is lost

Parameters
reasonone of the SSH_DISCONNECT_ constants
descUTF-8 description of reason
desc_langRFC3066 language for description

The remote peer may tell us why it's going to disconnect. Handling this is optional.

◆ exec

int(* lws_ssh_ops::exec) (void *priv, struct lws *wsi, const char *command, lws_ssh_finish_exec finish, void *finish_handle)

exec() - spawn command and wire up stdin/out/err to ssh channel

Parameters
privvoid * you set when this channel was created
wsithe struct lws the connection belongs to
commandstring containing path to app and arguments
finishfunction to call to indicate the exec finished
finish_handleopaque handle identifying this exec for use with finish

Client requested to exec something. Return nonzero to fail.

◆ get_server_key

size_t(* lws_ssh_ops::get_server_key) (struct lws *wsi, uint8_t *buf, size_t len)

get_server_key() - retreive the secret keypair for this server

Parameters
wsithe wsi representing the connection to the client
bufstart of the buffer to copy the keypair into
lenlength 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.

◆ is_pubkey_authorized

int(* lws_ssh_ops::is_pubkey_authorized) (const char *username, const char *type, const uint8_t *peer, int peer_len)

is_pubkey_authorized() - check if auth pubkey is valid for user

Parameters
usernameusername the key attempted to authenticate
type"ssh-rsa"
peerstart of Public key peer used to authenticate
peer_lenlength 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

◆ pty_req

int(* lws_ssh_ops::pty_req) (void *priv, struct lws_ssh_pty *pty)

pty_req() - Create a Pseudo-TTY as described in pty

Parameters
privvoid * you set when this channel was created
ptypointer to struct describing the desired pty

Client requested a pty. Return nonzero to fail.

◆ rx

int(* lws_ssh_ops::rx) (void *priv, struct lws *wsi, const uint8_t *buf, uint32_t len)

rx() - receive payload from peer

Parameters
privvoid * you set when this channel was created
wsistruct lws * for the ssh connection
bufpointer to start of received data
lenbytes of received data available at buf

len bytes of payload from the peer arrived and is available at buf

◆ server_string

const char* lws_ssh_ops::server_string

SSH version string sent to client (required) By convention a string like "SSH-2.0-Libwebsockets"

◆ set_env

int(* lws_ssh_ops::set_env) (void *priv, const char *name, const char *value)

set_env() - Set environment variable

Parameters
privvoid * you set when this channel was created
nameenv var name
valuevalue to set env var to

Client requested to set environment var. Return nonzero to fail.

◆ set_server_key

size_t(* lws_ssh_ops::set_server_key) (struct lws *wsi, uint8_t *buf, size_t len)

set_server_key() - store the secret keypair of this server

Parameters
wsithe wsi representing the connection to the client
bufstart of the buffer containing the keypair
lenlength of the keypair in bytes

store the server key in buf, length len, to nonvolatile stg. Return length stored, 0 for fail.

◆ shell

int(* lws_ssh_ops::shell) (void *priv, struct lws *wsi, lws_ssh_finish_exec finish, void *finish_handle)

shell() - Spawn shell that is appropriate for user

Parameters
privvoid * you set when this channel was created
wsithe struct lws the connection belongs to
finishfunction to call to indicate the exec finished
finish_handleopaque handle identifying this exec for use with finish

Spawn the appropriate shell for this user. Return 0 for OK or nonzero to fail.

◆ tx

size_t(* lws_ssh_ops::tx) (void *priv, int stdch, uint8_t *buf, size_t len)

tx() - provide data to send on the channel

Parameters
privvoid * you set when this channel was created
stdchLWS_STDOUT or LWS_STDERR
bufstart of the buffer to copy the transmit data into
lenmax 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().

◆ tx_waiting

int(* lws_ssh_ops::tx_waiting) (void *priv)

tx_waiting() - report if data waiting to transmit on the channel

Parameters
privvoid * 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.


The documentation for this struct was generated from the following file: