ssh-base.h File Reference

#include <libssh/libssh.h>
#include <glib.h>
#include <extcap/extcap-base.h>

Go to the source code of this file.

Classes
struct	_ssh_params
	Holds the connection parameters required to establish an SSH session for an SSH-based extcap capture. More...

Macros
#define	STDERR_FILENO   2
#define	STDOUT_FILENO   1
#define	SSH_BASE_OPTIONS
#define	SSH_BASE_OPTIONS_ENUM
#define	SSH_BASE_PACKET_OPTIONS
#define	SSH_BASE_PACKET_OPTIONS_ENUM

Typedefs
typedef struct _ssh_params	ssh_params_t
	Holds the connection parameters required to establish an SSH session for an SSH-based extcap capture.

Functions
void	ssh_base_list_config (unsigned *count)
	Print SSH base server and authentication configuration options.
void	ssh_base_add_help_options (extcap_parameters *extcap_conf)
	Adds SSH base server and authentication options to the help options.
void	add_libssh_info (extcap_parameters *extcap_conf)
	Adds information about the libssh library version to the extcap parameters.
ssh_session	create_ssh_connection (const ssh_params_t *ssh_params, char **err_info)
	Creates an SSH session based on the provided parameters.
int	ssh_channel_printf (ssh_channel channel, const char *fmt,...)
	Writes a formatted message to an SSH channel.
bool	ssh_base_setup_graceful_shutdown (extcap_parameters *extcap_conf)
	Sets up ssh_async_loop_read to allow graceful shutdown.
int	ssh_async_loop_read (ssh_session sshs, ssh_channel channel, FILE *fp)
	Asynchronously reads the output of a single SSH command.
void	ssh_cleanup (ssh_session *sshs, ssh_channel *channel)
	Cleans up SSH session and channel resources.
ssh_params_t *	ssh_params_new (void)
	Create a new SSH parameters structure.
void	ssh_params_free (ssh_params_t *ssh_params)
	Frees the memory allocated for an ssh_params_t structure.
void	ssh_params_set_log_level (ssh_params_t *ssh_params, enum ws_log_level level)
	Set the log level for SSH parameters.

Detailed Description

ssh-base has base utility functions to connect to hosts via ssh

Copyright 2016, Dario Lombardo

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Macro Definition Documentation

SSH_BASE_OPTIONS

#define SSH_BASE_OPTIONS

Value:

    { "remote-host", ws_required_argument, NULL, OPT_REMOTE_HOST}, \
    { "remote-port", ws_required_argument, NULL, OPT_REMOTE_PORT}, \
    { "remote-username", ws_required_argument, NULL, OPT_REMOTE_USERNAME}, \
    { "remote-password", ws_required_argument, NULL, OPT_REMOTE_PASSWORD}, \
    { "remote-count", ws_required_argument, NULL, OPT_REMOTE_COUNT}, \
    { "sshkey", ws_required_argument, NULL, OPT_SSHKEY}, \
    { "sshkey-passphrase", ws_required_argument, NULL, OPT_SSHKEY_PASSPHRASE}, \
    { "proxycommand", ws_required_argument, NULL, OPT_PROXYCOMMAND}, \
    { "ssh-sha1", ws_no_argument, NULL, OPT_SSH_SHA1}, \
    { "update-known-hosts", ws_no_argument, NULL, OPT_UPDATE_KNOWN_HOSTS}

SSH_BASE_OPTIONS_ENUM

#define SSH_BASE_OPTIONS_ENUM

Value:

    OPT_REMOTE_HOST, \
    OPT_REMOTE_PORT, \
    OPT_REMOTE_USERNAME, \
    OPT_REMOTE_PASSWORD, \
    OPT_SSHKEY, \
    OPT_SSHKEY_PASSPHRASE, \
    OPT_PROXYCOMMAND, \
    OPT_SSH_SHA1, \
    OPT_UPDATE_KNOWN_HOSTS

SSH_BASE_PACKET_OPTIONS

#define SSH_BASE_PACKET_OPTIONS

Value:

    SSH_BASE_OPTIONS, \
    { "remote-interface", ws_required_argument, NULL, OPT_REMOTE_INTERFACE}, \
    { "remote-filter", ws_required_argument, NULL, OPT_REMOTE_FILTER}

SSH_BASE_PACKET_OPTIONS_ENUM

#define SSH_BASE_PACKET_OPTIONS_ENUM

Value:

    SSH_BASE_OPTIONS_ENUM, \
    OPT_REMOTE_INTERFACE, \
    OPT_REMOTE_FILTER

Function Documentation

add_libssh_info()

void add_libssh_info

(

extcap_parameters *

extcap_conf

)

Adds information about the libssh library version to the extcap parameters.

Parameters

extcap_conf

Pointer to the extcap parameters structure.

create_ssh_connection()

ssh_session create_ssh_connection	(	const ssh_params_t *	ssh_params,
		char **	err_info )

Creates an SSH session based on the provided parameters.

Create a ssh connection using all the possible authentication methods

Parameters

ssh_params	Pointer to the SSH parameters structure containing connection details.
err_info	Pointer to a string that will hold error information if the function fails.

Returns

A pointer to the created SSH session, or NULL if an error occurs.

ssh_async_loop_read()

int ssh_async_loop_read	(	ssh_session	sshs,
		ssh_channel	channel,
		FILE *	fp )

Asynchronously reads the output of a single SSH command.

Loops to read the output of a single SSH command and write it to an open FILE pointer. Calls ssh_select to wait on the channel and optionally the graceful shutdown indication, if ssh_base_setup_graceful_shutdown was called (non-Windows only). If the SSH channel's stdout reaches EOF, the function then reads the channel's stderr and writes that to the current process's stderr.

Parameters

sshs	The SSH session
channel	The SSH channel to read
fp	The FILE to write the channel's stdout to

Returns

EXIT_SUCCESS if successful, EXIT_FAILURE otherwise.

ssh_base_add_help_options()

void ssh_base_add_help_options

(

extcap_parameters *

extcap_conf

)

Adds SSH base server and authentication options to the help options.

Parameters

extcap_conf

Pointer to the extcap parameters structure.

ssh_base_list_config()

void ssh_base_list_config

(

unsigned *

count

)

Print SSH base server and authentication configuration options.

Parameters

[in,out]

count

The current option count

ssh_base_setup_graceful_shutdown()

bool ssh_base_setup_graceful_shutdown

(

extcap_parameters *

extcap_conf

)

Sets up ssh_async_loop_read to allow graceful shutdown.

Creates a self-pipe (eventually, on Windows, a SOCKET, but not implemented yet) that allows ssh_async_loop_read to be interrupted when a graceful shutdown is signaled for by the main application. This is useful for, among other things, when SSH has EXEC'd a command like dumpcap and tcpdump that might sit without attempting to read from stdin or write to stdout or stderr indefinitely if, e.g., a capture filter was given that excludes all packets, and thus will not exit unless a SIGHUP is manually issued, such as by ssh_cleanup.

Parameters

extcap_conf

Pointer to the extcap parameters structure.

ssh_channel_printf()

int ssh_channel_printf	(	ssh_channel	channel,
		const char *	fmt,
			... )

Writes a formatted message to an SSH channel.

Parameters

channel	The SSH channel to write to.
fmt	The format string for the message.

Returns

EXIT_SUCCESS if successful, EXIT_FAILURE otherwise.

ssh_cleanup()

void ssh_cleanup	(	ssh_session *	sshs,
		ssh_channel *	channel )

Cleans up SSH session and channel resources.

This function is responsible for properly closing and freeing the SSH session and channel resources.

Parameters

sshs	Pointer to the SSH session to be cleaned up.
channel	Pointer to the SSH channel to be closed.

ssh_params_free()

void ssh_params_free

(

ssh_params_t *

ssh_params

)

Frees the memory allocated for an ssh_params_t structure.

Parameters

ssh_params

Pointer to the ssh_params_t structure to be freed.

ssh_params_new()

ssh_params_t * ssh_params_new

(

void

)

Create a new SSH parameters structure.

Returns

A pointer to the newly created ssh_params_t structure, or NULL on failure.

ssh_params_set_log_level()

void ssh_params_set_log_level	(	ssh_params_t *	ssh_params,
		enum ws_log_level	level )

Set the log level for SSH parameters.

Parameters

ssh_params	Pointer to the SSH parameters structure.
level	The desired log level from the ws_log_level enumeration.