SSH connection protocol - multiplexed session channels (RFC 4254). More...

#include "network_drivers/presentation/ssh/connection/ssh_channel.h"
#include "network_drivers/presentation/ssh/transport/ssh_packet.h"
#include <string.h>

Classes
struct	SshChannelCtx

Functions
void	pc_ssh_channel_set_data_cb (SshChannelDataCb cb)
	Install the inbound-data callback (session channels).

void	pc_ssh_channel_set_forward_open_cb (SshForwardOpenCb cb)
	Install the direct-tcpip forward open-policy callback (opt-in).

void	pc_ssh_channel_set_forward_data_cb (SshForwardDataCb cb)
	Install the direct-tcpip forward inbound-data callback.

void	pc_ssh_channel_set_rforward_open_cb (SshRemoteForwardOpenCb cb)
	Install the remote-forward (ssh -R) open-policy callback (opt-in).

void	pc_ssh_channel_set_rforward_cancel_cb (SshRemoteForwardCancelCb cb)
	Install the remote-forward (ssh -R) cancel callback (opt-in).

void	pc_ssh_channel_set_forward_confirm_cb (SshForwardConfirmCb cb)
	Install the forwarded-tcpip open-confirmation callback (opt-in, ssh -R).

void	pc_ssh_channel_init (uint8_t i)
	Reset channel state for slot `i`.

int	ssh_global_request_handle (uint8_t i, const uint8_t payload, size_t len, uint8_t out, size_t *out_len, size_t cap)
	Handle SSH_MSG_GLOBAL_REQUEST (RFC 4254 §4).

int	pc_ssh_channel_open_forwarded (uint8_t i, const char conn_addr, uint16_t conn_port, const char orig_addr, uint16_t orig_port, uint8_t out, size_t out_len, size_t cap)
	Open a server-initiated "forwarded-tcpip" channel (RFC 4254 §7.2, ssh -R).

int	pc_ssh_channel_handle_open_confirm (uint8_t i, const uint8_t *payload, size_t len)
	Handle SSH_MSG_CHANNEL_OPEN_CONFIRMATION for a channel we opened (ssh -R).

int	pc_ssh_channel_handle_open_failure (uint8_t i, const uint8_t *payload, size_t len)
	Handle SSH_MSG_CHANNEL_OPEN_FAILURE for a channel we opened (ssh -R).

int	pc_ssh_channel_handle_open (uint8_t i, const uint8_t payload, size_t len, uint8_t out, size_t *out_len, size_t cap)
	Handle SSH_MSG_CHANNEL_OPEN and emit CHANNEL_OPEN_CONFIRMATION.

int	pc_ssh_channel_handle_request (uint8_t i, const uint8_t payload, size_t len, uint8_t out, size_t *out_len, size_t cap)
	Handle SSH_MSG_CHANNEL_REQUEST.

int	pc_ssh_channel_handle_data (uint8_t i, const uint8_t payload, size_t len, uint8_t out, size_t *out_len, size_t cap)
	Handle SSH_MSG_CHANNEL_DATA: bounds-check, update the window, and invoke the data callback. If the local window is exhausted a CHANNEL_WINDOW_ADJUST is written to `out` (*`out_len` > 0).

int	pc_ssh_channel_build_data (uint8_t i, uint32_t channel, const uint8_t data, size_t len, uint8_t out, size_t *out_len, size_t cap)
	Build an SSH_MSG_CHANNEL_DATA message carrying `data` to the client on channel `channel` (a local channel id from a prior open).

int	pc_ssh_channel_handle_window_adjust (uint8_t i, const uint8_t *payload, size_t len)
	Handle SSH_MSG_CHANNEL_WINDOW_ADJUST (grows the peer window).

int	pc_ssh_channel_build_close (uint8_t i, uint32_t channel, uint8_t out, size_t out_len, size_t cap)
	Build SSH_MSG_CHANNEL_EOF + SSH_MSG_CHANNEL_CLOSE for channel `channel` and mark it closed.

int	pc_ssh_channel_handle_close (uint8_t i, const uint8_t payload, size_t len, uint8_t out, size_t *out_len, size_t cap)
	Handle an inbound SSH_MSG_CHANNEL_CLOSE: route to the recipient channel, reply with EOF + CLOSE, and mark it closed.

Variables
SshChannel	ssh_chan [MAX_SSH_CONNS][PC_SSH_MAX_CHANNELS]
	Channel pool: PC_SSH_MAX_CHANNELS channels per SSH connection (BSS). Owned by this layer; src/ code routes through the functions below, never the array (tests inspect it white-box). Index: [connection slot][channel slot].

Detailed Description

SSH connection protocol - multiplexed session channels (RFC 4254).

The channel table is owned here; inbound messages are routed to a channel by the recipient channel id they carry, and the local channel id is the channel's slot index in its connection's pool (unique per connection, which is all RFC 4254 requires). Other layers go through these functions, never the table.

Definition in file ssh_channel.cpp.

Function Documentation

◆ pc_ssh_channel_set_data_cb()

void pc_ssh_channel_set_data_cb ( SshChannelDataCb cb )

Install the inbound-data callback (session channels).

Definition at line 42 of file ssh_channel.cpp.

References SshChannelCtx::data_cb.

◆ pc_ssh_channel_set_forward_open_cb()

void pc_ssh_channel_set_forward_open_cb ( SshForwardOpenCb cb )

Install the direct-tcpip forward open-policy callback (opt-in).

Definition at line 69 of file ssh_channel.cpp.

References SshChannelCtx::forward_open_cb.

◆ pc_ssh_channel_set_forward_data_cb()

void pc_ssh_channel_set_forward_data_cb ( SshForwardDataCb cb )

Install the direct-tcpip forward inbound-data callback.

Definition at line 74 of file ssh_channel.cpp.

References SshChannelCtx::forward_data_cb.

◆ pc_ssh_channel_set_rforward_open_cb()

void pc_ssh_channel_set_rforward_open_cb ( SshRemoteForwardOpenCb cb )

Install the remote-forward (ssh -R) open-policy callback (opt-in).

Definition at line 79 of file ssh_channel.cpp.

References SshChannelCtx::rfwd_open_cb.

◆ pc_ssh_channel_set_rforward_cancel_cb()

void pc_ssh_channel_set_rforward_cancel_cb ( SshRemoteForwardCancelCb cb )

Install the remote-forward (ssh -R) cancel callback (opt-in).

Definition at line 84 of file ssh_channel.cpp.

References SshChannelCtx::rfwd_cancel_cb.

◆ pc_ssh_channel_set_forward_confirm_cb()

void pc_ssh_channel_set_forward_confirm_cb ( SshForwardConfirmCb cb )

Install the forwarded-tcpip open-confirmation callback (opt-in, ssh -R).

Definition at line 89 of file ssh_channel.cpp.

References SshChannelCtx::forward_confirm_cb.

◆ pc_ssh_channel_init()

void pc_ssh_channel_init ( uint8_t i )

Reset channel state for slot i.

Definition at line 94 of file ssh_channel.cpp.

References MAX_SSH_CONNS, and ssh_chan.

Referenced by pc_ssh_conn_accept().

◆ ssh_global_request_handle()

int ssh_global_request_handle	(	uint8_t	i,
		const uint8_t *	payload,
		size_t	len,
		uint8_t *	out,
		size_t *	out_len,
		size_t	cap
	)

Handle SSH_MSG_GLOBAL_REQUEST (RFC 4254 §4).

Parses the request name and want_reply flag. "tcpip-forward" / "cancel-tcpip-forward" are routed to the remote-forward seam above (accepted only when a callback is installed); a "tcpip-forward" that bound port 0 gets its allocated port echoed in the reply (RFC 4254 §7.1). Any other request name is unrecognized: per §4 it is answered with SSH_MSG_REQUEST_FAILURE when want_reply is set, and silently ignored otherwise (never SSH_MSG_UNIMPLEMENTED - GLOBAL_REQUEST is a known message type; only the request name is unknown).

Returns: 0 on success (a reply is in out with *out_len bytes, or *out_len is 0 when no reply is due), -1 if the message is malformed.

Definition at line 222 of file ssh_channel.cpp.

References MAX_SSH_CONNS, SshChannelCtx::rfwd_cancel_cb, SshChannelCtx::rfwd_open_cb, SSH_MSG_GLOBAL_REQUEST, SSH_MSG_REQUEST_FAILURE, and SSH_MSG_REQUEST_SUCCESS.

Referenced by pc_ssh_server_dispatch().

◆ pc_ssh_channel_open_forwarded()

int pc_ssh_channel_open_forwarded	(	uint8_t	i,
		const char *	conn_addr,
		uint16_t	conn_port,
		const char *	orig_addr,
		uint16_t	orig_port,
		uint8_t *	out,
		size_t *	out_len,
		size_t	cap
	)

Open a server-initiated "forwarded-tcpip" channel (RFC 4254 §7.2, ssh -R).

Allocates a local channel on connection i (state = pending, awaiting the client's confirmation) and builds the SSH_MSG_CHANNEL_OPEN in out. conn_addr / conn_port are the forward's bound address/port (the "address that was connected"); orig_addr / orig_port are the peer that connected.

Returns: the local channel id (>= 0) on success, or -1 (pool full, or out too small). On success the caller emits out and, on the eventual confirm, bridges bytes on the returned channel.

Definition at line 328 of file ssh_channel.cpp.

References SshChannel::local_id, SshChannel::local_window, MAX_SSH_CONNS, SshChannel::open, SshChannel::peer_id, SshChannel::peer_max_pkt, SshChannel::peer_window, SshChannel::pending, ssh_chan, SSH_CHAN_FORWARDED_TCPIP, SSH_CHAN_MAX_PACKET, SSH_CHAN_WINDOW, SSH_MSG_CHANNEL_OPEN, and SshChannel::type.

Referenced by pc_ssh_conn_open_forwarded().

◆ pc_ssh_channel_handle_open_confirm()

int pc_ssh_channel_handle_open_confirm	(	uint8_t	i,
		const uint8_t *	payload,
		size_t	len
	)

Handle SSH_MSG_CHANNEL_OPEN_CONFIRMATION for a channel we opened (ssh -R).

Matches the pending channel by our recipient id, records the peer's channel id / window / max-packet, and marks it open. Fires the confirm callback (ok = true).

Returns: 0 on success, -1 if malformed or no matching pending channel.

Definition at line 386 of file ssh_channel.cpp.

References SshChannelCtx::forward_confirm_cb, SshChannel::local_id, MAX_SSH_CONNS, SshChannel::open, SshChannel::peer_id, SshChannel::peer_max_pkt, SshChannel::peer_window, SshChannel::pending, and SSH_MSG_CHANNEL_OPEN_CONFIRM.

Referenced by pc_ssh_server_dispatch().

◆ pc_ssh_channel_handle_open_failure()

int pc_ssh_channel_handle_open_failure	(	uint8_t	i,
		const uint8_t *	payload,
		size_t	len
	)

Handle SSH_MSG_CHANNEL_OPEN_FAILURE for a channel we opened (ssh -R).

Frees the pending channel and fires the confirm callback (ok = false).

Returns: 0 on success, -1 if malformed or no matching pending channel.

Definition at line 410 of file ssh_channel.cpp.

References SshChannelCtx::forward_confirm_cb, SshChannel::local_id, MAX_SSH_CONNS, SshChannel::open, SshChannel::pending, and SSH_MSG_CHANNEL_OPEN_FAILURE.

Referenced by pc_ssh_server_dispatch().

◆ pc_ssh_channel_handle_open()

int pc_ssh_channel_handle_open	(	uint8_t	i,
		const uint8_t *	payload,
		size_t	len,
		uint8_t *	out,
		size_t *	out_len,
		size_t	cap
	)

Handle SSH_MSG_CHANNEL_OPEN and emit CHANNEL_OPEN_CONFIRMATION.

Accepts a "session" channel; any other type yields CHANNEL_OPEN_FAILURE.

Returns: 0 if a response was produced, -1 if malformed.

Definition at line 432 of file ssh_channel.cpp.

References SshChannelCtx::forward_open_cb, SshChannel::local_id, SshChannel::local_window, MAX_SSH_CONNS, SshChannel::open, SshChannel::peer_id, SshChannel::peer_max_pkt, SshChannel::peer_window, ssh_chan, SSH_CHAN_DIRECT_TCPIP, SSH_CHAN_SESSION, SSH_CHAN_WINDOW, SSH_MSG_CHANNEL_OPEN, and SshChannel::type.

Referenced by pc_ssh_server_dispatch().

◆ pc_ssh_channel_handle_request()

int pc_ssh_channel_handle_request	(	uint8_t	i,
		const uint8_t *	payload,
		size_t	len,
		uint8_t *	out,
		size_t *	out_len,
		size_t	cap
	)

Handle SSH_MSG_CHANNEL_REQUEST.

"shell", "exec", "pty-req", and "env" are accepted; anything else is refused - except that when PC_ENABLE_SSH_SFTP is set a subsystem "sftp" is accepted (the channel is tagged SSH_CHAN_SFTP and the sftp-open callback fires), and when PC_ENABLE_SSH_SCP is set an exec "scp …" is additionally tagged SSH_CHAN_SCP (the scp-open callback fires with the command). When want_reply is set, CHANNEL_SUCCESS / CHANNEL_FAILURE is written to out and *out_len > 0; otherwise *out_len is 0.

Returns: 0 on success, -1 if malformed.

Definition at line 560 of file ssh_channel.cpp.

References MAX_SSH_CONNS, SshChannel::peer_id, SSH_MSG_CHANNEL_FAILURE, SSH_MSG_CHANNEL_REQUEST, and SSH_MSG_CHANNEL_SUCCESS.

Referenced by pc_ssh_server_dispatch().

◆ pc_ssh_channel_handle_data()

int pc_ssh_channel_handle_data	(	uint8_t	i,
		const uint8_t *	payload,
		size_t	len,
		uint8_t *	out,
		size_t *	out_len,
		size_t	cap
	)

Handle SSH_MSG_CHANNEL_DATA: bounds-check, update the window, and invoke the data callback. If the local window is exhausted a CHANNEL_WINDOW_ADJUST is written to out (*out_len > 0).

Returns: 0 on success, -1 if malformed or channel not open.

Definition at line 621 of file ssh_channel.cpp.

References SshChannelCtx::data_cb, SshChannelCtx::forward_data_cb, SshChannel::local_id, SshChannel::local_window, MAX_SSH_CONNS, SshChannel::peer_id, SSH_CHAN_DIRECT_TCPIP, SSH_CHAN_FORWARDED_TCPIP, SSH_CHAN_SCP, SSH_CHAN_SFTP, SSH_CHAN_WINDOW, SSH_MSG_CHANNEL_DATA, SSH_MSG_CHANNEL_WINDOW_ADJUST, and SshChannel::type.

Referenced by pc_ssh_server_dispatch().

◆ pc_ssh_channel_build_data()

int pc_ssh_channel_build_data	(	uint8_t	i,
		uint32_t	channel,
		const uint8_t *	data,
		size_t	len,
		uint8_t *	out,
		size_t *	out_len,
		size_t	cap
	)

Build an SSH_MSG_CHANNEL_DATA message carrying data to the client on channel channel (a local channel id from a prior open).

Returns: 0 on success, -1 if the channel is closed/unknown, the peer window is too small, or out is too small.

Definition at line 710 of file ssh_channel.cpp.

References MAX_SSH_CONNS, SshChannel::peer_id, SshChannel::peer_max_pkt, SshChannel::peer_window, and SSH_MSG_CHANNEL_DATA.

Referenced by pc_ssh_conn_send().

◆ pc_ssh_channel_handle_window_adjust()

int pc_ssh_channel_handle_window_adjust	(	uint8_t	i,
		const uint8_t *	payload,
		size_t	len
	)

Handle SSH_MSG_CHANNEL_WINDOW_ADJUST (grows the peer window).

Returns: 0 on success, -1 if malformed.

Definition at line 740 of file ssh_channel.cpp.

References MAX_SSH_CONNS, SshChannel::peer_window, and SSH_MSG_CHANNEL_WINDOW_ADJUST.

Referenced by pc_ssh_server_dispatch().

◆ pc_ssh_channel_build_close()

int pc_ssh_channel_build_close	(	uint8_t	i,
		uint32_t	channel,
		uint8_t *	out,
		size_t *	out_len,
		size_t	cap
	)

Build SSH_MSG_CHANNEL_EOF + SSH_MSG_CHANNEL_CLOSE for channel channel and mark it closed.

Returns: 0 on success, -1 if the channel is closed/unknown or out is too small.

Definition at line 780 of file ssh_channel.cpp.

References MAX_SSH_CONNS.

Referenced by pc_ssh_conn_close_channel().

◆ pc_ssh_channel_handle_close()

int pc_ssh_channel_handle_close	(	uint8_t	i,
		const uint8_t *	payload,
		size_t	len,
		uint8_t *	out,
		size_t *	out_len,
		size_t	cap
	)

Handle an inbound SSH_MSG_CHANNEL_CLOSE: route to the recipient channel, reply with EOF + CLOSE, and mark it closed.

Returns: 0 if a response was produced, -1 if malformed or the channel is unknown.

Definition at line 789 of file ssh_channel.cpp.

References MAX_SSH_CONNS, and SSH_MSG_CHANNEL_CLOSE.

Referenced by pc_ssh_server_dispatch().

Variable Documentation

◆ ssh_chan

SshChannel ssh_chan[MAX_SSH_CONNS][PC_SSH_MAX_CHANNELS]

Channel pool: PC_SSH_MAX_CHANNELS channels per SSH connection (BSS). Owned by this layer; src/ code routes through the functions below, never the array (tests inspect it white-box). Index: [connection slot][channel slot].

Definition at line 18 of file ssh_channel.cpp.

Referenced by pc_ssh_channel_handle_open(), pc_ssh_channel_init(), and pc_ssh_channel_open_forwarded().

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ pc_ssh_channel_set_data_cb()

◆ pc_ssh_channel_set_forward_open_cb()

◆ pc_ssh_channel_set_forward_data_cb()

◆ pc_ssh_channel_set_rforward_open_cb()

◆ pc_ssh_channel_set_rforward_cancel_cb()

◆ pc_ssh_channel_set_forward_confirm_cb()

◆ pc_ssh_channel_init()

◆ ssh_global_request_handle()

◆ pc_ssh_channel_open_forwarded()

◆ pc_ssh_channel_handle_open_confirm()

◆ pc_ssh_channel_handle_open_failure()

◆ pc_ssh_channel_handle_open()

◆ pc_ssh_channel_handle_request()

◆ pc_ssh_channel_handle_data()

◆ pc_ssh_channel_build_data()

◆ pc_ssh_channel_handle_window_adjust()

◆ pc_ssh_channel_build_close()

◆ pc_ssh_channel_handle_close()

Variable Documentation

◆ ssh_chan