SSH client/server common API

Data Structures
struct	ssh_channel_event_channel_request
	Data for SSH_CHANNEL_EVENT_REQUEST event. More...
struct	ssh_channel_event_channel_request_result
	Data for SSH_CHANNEL_EVENT_REQUEST_RESULT event. More...
struct	ssh_channel_event
	SSH channel event information. More...
struct	ssh_transport_event_authenticate_result
	Data for SSH_TRANSPORT_EVENT_AUTHENTICATE_RESULT event. More...
struct	ssh_transport_event_channel_open
	Data for SSH_TRANSPORT_EVENT_CHANNEL_OPEN event. More...
struct	ssh_transport_event
	SSH transport event information. More...
struct	ssh_transport_conf
	SSH transport callback configuration. More...

Macros
#define	SSH_EXTENDED_DATA_STDERR   1
	Extended data type for standard error channel data.

Typedefs
typedef int(*	ssh_channel_event_callback_t) (struct ssh_channel *channel, const struct ssh_channel_event *event, void *user_data)
	SSH channel event callback.
typedef int(*	ssh_transport_event_callback_t) (struct ssh_transport *transport, const struct ssh_transport_event *event, void *user_data)
	SSH transport event callback.
typedef void(*	ssh_service_client_cb_t) (struct ssh_client *ssh, int instance, void *user_data)
	Callback used while iterating over SSH client connections.
typedef void(*	ssh_service_server_cb_t) (struct ssh_server *sshd, int instance, void *user_data)
	Callback used while iterating over SSH server connections.

Enumerations
enum	ssh_auth_type { SSH_AUTH_NONE , SSH_AUTH_PASSWORD , SSH_AUTH_PUBKEY }
	Authentication methods supported by SSH transports. More...
enum	ssh_channel_request_type {   SSH_CHANNEL_REQUEST_UNKNOWN , SSH_CHANNEL_REQUEST_PSEUDO_TERMINAL , SSH_CHANNEL_REQUEST_X11_FORWARD , SSH_CHANNEL_REQUEST_ENV_VAR ,   SSH_CHANNEL_REQUEST_SHELL , SSH_CHANNEL_REQUEST_EXEC , SSH_CHANNEL_REQUEST_SUBSYSTEM , SSH_CHANNEL_REQUEST_WINDOW_CHANGE ,   SSH_CHANNEL_REQUEST_FLOW_CONTROL , SSH_CHANNEL_REQUEST_SIGNAL , SSH_CHANNEL_REQUEST_EXIT_STATUS , SSH_CHANNEL_REQUEST_EXIT_SIGNAL }
	Types of SSH channel requests. More...
enum	ssh_channel_event_type {   SSH_CHANNEL_EVENT_OPEN_RESULT , SSH_CHANNEL_EVENT_REQUEST , SSH_CHANNEL_EVENT_REQUEST_RESULT , SSH_CHANNEL_EVENT_RX_DATA_READY ,   SSH_CHANNEL_EVENT_TX_DATA_READY , SSH_CHANNEL_EVENT_RX_STDERR_DATA_READY , SSH_CHANNEL_EVENT_EOF , SSH_CHANNEL_EVENT_CLOSED }
	Types of events emitted for an SSH channel. More...
enum	ssh_transport_event_type { SSH_TRANSPORT_EVENT_CLOSED , SSH_TRANSPORT_EVENT_SERVICE_ACCEPTED , SSH_TRANSPORT_EVENT_AUTHENTICATE_RESULT , SSH_TRANSPORT_EVENT_CHANNEL_OPEN }
	Types of events emitted for an SSH transport. More...

Functions
const char *	ssh_transport_client_user_name (struct ssh_transport *transport)
	Get the authenticated client username for a transport.
int	ssh_transport_auth_password (struct ssh_transport *transport, const char *user_name, const char *password)
	Authenticate an SSH transport using a password.
int	ssh_transport_channel_open (struct ssh_transport *transport, ssh_channel_event_callback_t callback, void *user_data)
	Open a new channel on an SSH transport.
int	ssh_channel_open_result (struct ssh_channel *channel, bool success, ssh_channel_event_callback_t callback, void *user_data)
	Reply to a channel open request.
int	ssh_channel_request_result (struct ssh_channel *channel, bool success)
	Reply to a channel request.
int	ssh_channel_request_shell (struct ssh_channel *channel)
	Request an interactive shell on a channel.
int	ssh_channel_read (struct ssh_channel *channel, void *data, uint32_t len)
	Read channel data.
int	ssh_channel_write (struct ssh_channel *channel, const void *data, uint32_t len)
	Write channel data.
int	ssh_channel_read_stderr (struct ssh_channel *channel, void *data, uint32_t len)
	Read channel standard error data.
int	ssh_channel_write_stderr (struct ssh_channel *channel, const void *data, uint32_t len)
	Write channel standard error data.
int	ssh_channel_close (struct ssh_channel *channel)
	Close an SSH channel.
void	ssh_client_foreach (ssh_service_client_cb_t cb, void *user_data)
	Go through all SSH client connections.
void	ssh_server_foreach (ssh_service_server_cb_t cb, void *user_data)
	Go through all SSH server connections.
int	ssh_transport_traverse_callbacks (bool is_server, struct ssh_transport *transport, const struct ssh_transport_event *event)
	Call user configured callbacks for a given transport.

Detailed Description

Since

4.5

Version

0.1.0

Macro Definition Documentation

SSH_EXTENDED_DATA_STDERR

#define SSH_EXTENDED_DATA_STDERR   1

#include <common.h>

Extended data type for standard error channel data.

Typedef Documentation

ssh_channel_event_callback_t

typedef int(* ssh_channel_event_callback_t) (struct ssh_channel *channel, const struct ssh_channel_event *event, void *user_data)

#include <common.h>

SSH channel event callback.

Parameters

channel	Pointer to the SSH channel that produced the event.
event	Pointer to channel event data.
user_data	User-provided context pointer.

Returns

0 on success, or a negative error code on failure.

ssh_service_client_cb_t

typedef void(* ssh_service_client_cb_t) (struct ssh_client *ssh, int instance, void *user_data)

#include <common.h>

Callback used while iterating over SSH client connections.

Parameters

ssh	Pointer to the SSH client instance
instance	SSH client instance id
user_data	A valid pointer to user data or NULL

ssh_service_server_cb_t

typedef void(* ssh_service_server_cb_t) (struct ssh_server *sshd, int instance, void *user_data)

#include <common.h>

Callback used while iterating over SSH server connections.

Parameters

sshd	Pointer to the SSH server instance
instance	SSH server instance id
user_data	A valid pointer to user data or NULL

ssh_transport_event_callback_t

typedef int(* ssh_transport_event_callback_t) (struct ssh_transport *transport, const struct ssh_transport_event *event, void *user_data)

#include <common.h>

SSH transport event callback.

Parameters

transport	Pointer to the SSH transport that produced the event.
event	Pointer to transport event data.
user_data	User-provided context pointer.

Returns

0 on success, or a negative error code on failure.

Enumeration Type Documentation

ssh_auth_type

enum ssh_auth_type

#include <common.h>

Authentication methods supported by SSH transports.

Enumerator
SSH_AUTH_NONE	No authentication method selected.
SSH_AUTH_PASSWORD	Username and password authentication.
SSH_AUTH_PUBKEY	Public key authentication.

ssh_channel_event_type

enum ssh_channel_event_type

#include <common.h>

Types of events emitted for an SSH channel.

Enumerator
SSH_CHANNEL_EVENT_OPEN_RESULT	Result of an open request on the client side.
SSH_CHANNEL_EVENT_REQUEST	Incoming channel request on the server side.
SSH_CHANNEL_EVENT_REQUEST_RESULT	Result of a previously sent channel request on the client side.
SSH_CHANNEL_EVENT_RX_DATA_READY	Channel data is available to read.
SSH_CHANNEL_EVENT_TX_DATA_READY	Channel can accept more transmit data.
SSH_CHANNEL_EVENT_RX_STDERR_DATA_READY	Standard error data is available to read.
SSH_CHANNEL_EVENT_EOF	End-of-file received for the channel.
SSH_CHANNEL_EVENT_CLOSED	Channel has been closed.

ssh_channel_request_type

enum ssh_channel_request_type

#include <common.h>

Types of SSH channel requests.

Enumerator
SSH_CHANNEL_REQUEST_UNKNOWN	Unknown or unsupported channel request type.
SSH_CHANNEL_REQUEST_PSEUDO_TERMINAL	Request a pseudo-terminal.
SSH_CHANNEL_REQUEST_X11_FORWARD	Request X11 forwarding.
SSH_CHANNEL_REQUEST_ENV_VAR	Set an environment variable.
SSH_CHANNEL_REQUEST_SHELL	Start an interactive shell.
SSH_CHANNEL_REQUEST_EXEC	Execute a command.
SSH_CHANNEL_REQUEST_SUBSYSTEM	Start a subsystem.
SSH_CHANNEL_REQUEST_WINDOW_CHANGE	Notify of terminal window size changes.
SSH_CHANNEL_REQUEST_FLOW_CONTROL	Request flow control.
SSH_CHANNEL_REQUEST_SIGNAL	Send a signal to the remote process.
SSH_CHANNEL_REQUEST_EXIT_STATUS	Report process exit status.
SSH_CHANNEL_REQUEST_EXIT_SIGNAL	Report process exit signal.

ssh_transport_event_type

enum ssh_transport_event_type

#include <common.h>

Types of events emitted for an SSH transport.

Enumerator
SSH_TRANSPORT_EVENT_CLOSED	Transport has been closed.
SSH_TRANSPORT_EVENT_SERVICE_ACCEPTED	Requested SSH service was accepted by the peer.
SSH_TRANSPORT_EVENT_AUTHENTICATE_RESULT	Authentication attempt result.
SSH_TRANSPORT_EVENT_CHANNEL_OPEN	Server received a request to open a channel.

Function Documentation

ssh_channel_close()

int ssh_channel_close

(

struct ssh_channel *

channel

)

#include <common.h>

Close an SSH channel.

Send a channel close message to the peer and release the channel. On success, the channel handle must no longer be used. The associated channel callback (if any) receives a SSH_CHANNEL_EVENT_CLOSED event.

Parameters

channel

Pointer to the SSH channel.

Returns

0 on success, or a negative error code on failure.

ssh_channel_open_result()

int ssh_channel_open_result	(	struct ssh_channel *	channel,
		bool	success,
		ssh_channel_event_callback_t	callback,
		void *	user_data )

#include <common.h>

Reply to a channel open request.

Parameters

channel	Pointer to the SSH channel.
success	True to accept the open request, false to reject it.
callback	Channel event callback to associate with the opened channel.
user_data	User-provided context pointer passed to callback.

Returns

0 on success, or a negative error code on failure.

ssh_channel_read()

int ssh_channel_read	(	struct ssh_channel *	channel,
		void *	data,
		uint32_t	len )

#include <common.h>

Read channel data.

Parameters

channel	Pointer to the SSH channel.
data	Buffer to store the received data.
len	Maximum number of bytes to read.

Returns

Number of bytes read, or a negative error code on failure.

ssh_channel_read_stderr()

int ssh_channel_read_stderr	(	struct ssh_channel *	channel,
		void *	data,
		uint32_t	len )

#include <common.h>

Read channel standard error data.

Parameters

channel	Pointer to the SSH channel.
data	Buffer to store the received standard error data.
len	Maximum number of bytes to read.

Returns

Number of bytes read, or a negative error code on failure.

ssh_channel_request_result()

int ssh_channel_request_result	(	struct ssh_channel *	channel,
		bool	success )

#include <common.h>

Reply to a channel request.

Parameters

channel	Pointer to the SSH channel.
success	True if the request succeeded, false otherwise.

Returns

0 on success, or a negative error code on failure.

ssh_channel_request_shell()

int ssh_channel_request_shell

(

struct ssh_channel *

channel

)

#include <common.h>

Request an interactive shell on a channel.

Parameters

channel

Pointer to the SSH channel.

Returns

0 on success, or a negative error code on failure.

ssh_channel_write()

int ssh_channel_write	(	struct ssh_channel *	channel,
		const void *	data,
		uint32_t	len )

#include <common.h>

Write channel data.

Parameters

channel	Pointer to the SSH channel.
data	Buffer containing data to send.
len	Number of bytes to write.

Returns

Number of bytes written, or a negative error code on failure.

ssh_channel_write_stderr()

int ssh_channel_write_stderr	(	struct ssh_channel *	channel,
		const void *	data,
		uint32_t	len )

#include <common.h>

Write channel standard error data.

Parameters

channel	Pointer to the SSH channel.
data	Buffer containing standard error data to send.
len	Number of bytes to write.

Returns

Number of bytes written, or a negative error code on failure.

ssh_client_foreach()

void ssh_client_foreach	(	ssh_service_client_cb_t	cb,
		void *	user_data )

#include <common.h>

Go through all SSH client connections.

Parameters

cb	User-supplied callback function to call
user_data	User specified data

ssh_server_foreach()

void ssh_server_foreach	(	ssh_service_server_cb_t	cb,
		void *	user_data )

#include <common.h>

Go through all SSH server connections.

Parameters

cb	User-supplied callback function to call
user_data	User specified data

ssh_transport_auth_password()

int ssh_transport_auth_password	(	struct ssh_transport *	transport,
		const char *	user_name,
		const char *	password )

#include <common.h>

Authenticate an SSH transport using a password.

Parameters

transport	Pointer to the SSH transport.
user_name	Username to authenticate with.
password	Password to authenticate with.

Returns

0 on success, or a negative error code on failure.

ssh_transport_channel_open()

int ssh_transport_channel_open	(	struct ssh_transport *	transport,
		ssh_channel_event_callback_t	callback,
		void *	user_data )

#include <common.h>

Open a new channel on an SSH transport.

Parameters

transport	Pointer to the SSH transport.
callback	Channel event callback for the new channel.
user_data	User-provided context pointer passed to callback.

Returns

0 on success, or a negative error code on failure.

ssh_transport_client_user_name()

const char * ssh_transport_client_user_name

(

struct ssh_transport *

transport

)

#include <common.h>

Get the authenticated client username for a transport.

Parameters

transport

Pointer to the SSH transport.

Returns

Pointer to the username string.

ssh_transport_traverse_callbacks()

int ssh_transport_traverse_callbacks	(	bool	is_server,
		struct ssh_transport *	transport,
		const struct ssh_transport_event *	event )

#include <common.h>

Call user configured callbacks for a given transport.

This function is used to call user configured callbacks for a given transport. It is used by the SSH transport to notify the user of events such as authentication results, channel open requests, and channel data. The function will traverse the list of configured callbacks and call each one with the provided transport and event information. Note that the callbacks must not call the transport register or unregister API as that could lead to a deadlock.

Parameters

is_server	If set to true, then traverse configured server callbacks. If set to false, then traverse configured client callbacks.
transport	Transport to pass to user specified callback.
event	Event information to pass to user callback.

Returns

0 on success, or -EINVAL if the transport role does not match the dispatch role (server vs client).