The libssh callbacks

Overview

Callback which can be replaced in libssh. More…

// typedefs

typedef int (*ssh_auth_gssapi_mic_callback)(
    ssh_session session,
    const char *user,
    const char *principal,
    void *userdata
    );

typedef int (*ssh_auth_none_callback)(
    ssh_session session,
    const char *user,
    void *userdata
    );

typedef int (*ssh_auth_password_callback)(
    ssh_session session,
    const char *user,
    const char *password,
    void *userdata
    );

typedef int (*ssh_auth_pubkey_callback)(
    ssh_session session,
    const char *user,
    struct ssh_key_struct *pubkey,
    char signature_state,
    void *userdata
    );

typedef int (*ssh_callback_data)(
    const void *data,
    size_t len,
    void *user
    );

typedef void (*ssh_callback_int)(
    int code,
    void *user
    );

typedef void (*ssh_callback_int_int)(
    int code,
    int errno_code,
    void *user
    );

typedef void (*ssh_channel_auth_agent_req_callback)(
    ssh_session session,
    ssh_channel channel,
    void *userdata
    );

typedef int (*ssh_channel_callback_data)(
    ssh_channel channel,
    int code,
    void *data,
    size_t len,
    void *user
    );

typedef int (*ssh_channel_callback_int)(
    ssh_channel channel,
    int code,
    void *user
    );

typedef void (*ssh_channel_close_callback)(
    ssh_session session,
    ssh_channel channel,
    void *userdata
    );

typedef int (*ssh_channel_data_callback)(
    ssh_session session,
    ssh_channel channel,
    void *data,
    uint32_t len,
    int is_stderr,
    void *userdata
    );

typedef int (*ssh_channel_env_request_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *env_name,
    const char *env_value,
    void *userdata
    );

typedef void (*ssh_channel_eof_callback)(
    ssh_session session,
    ssh_channel channel,
    void *userdata
    );

typedef int (*ssh_channel_exec_request_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *command,
    void *userdata
    );

typedef void (*ssh_channel_exit_signal_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *signal,
    int core,
    const char *errmsg,
    const char *lang,
    void *userdata
    );

typedef void (*ssh_channel_exit_status_callback)(
    ssh_session session,
    ssh_channel channel,
    int exit_status,
    void *userdata
    );

typedef ssh_channel (*ssh_channel_open_request_session_callback)(
    ssh_session session,
    void *userdata
    );

typedef ssh_channel (*ssh_channel_open_request_x11_callback)(
    ssh_session session,
    const char *originator_address,
    int originator_port,
    void *userdata
    );

typedef int (*ssh_channel_pty_request_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *term,
    int width,
    int height,
    int pxwidth,
    int pwheight,
    void *userdata
    );

typedef int (*ssh_channel_pty_window_change_callback)(
    ssh_session session,
    ssh_channel channel,
    int width,
    int height,
    int pxwidth,
    int pwheight,
    void *userdata
    );

typedef int (*ssh_channel_shell_request_callback)(
    ssh_session session,
    ssh_channel channel,
    void *userdata
    );

typedef void (*ssh_channel_signal_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *signal,
    void *userdata
    );

typedef int (*ssh_channel_subsystem_request_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *subsystem,
    void *userdata
    );

typedef void (*ssh_channel_x11_req_callback)(
    ssh_session session,
    ssh_channel channel,
    int single_connection,
    const char *auth_protocol,
    const char *auth_cookie,
    uint32_t screen_number,
    void *userdata
    );

typedef void (*ssh_global_request_callback)(
    ssh_session session,
    ssh_message message,
    void *userdata
    );

typedef int (*ssh_gssapi_accept_sec_ctx_callback)(
    ssh_session session,
    ssh_string input_token,
    ssh_string *output_token,
    void *userdata
    );

typedef ssh_string (*ssh_gssapi_select_oid_callback)(
    ssh_session session,
    const char *user,
    int n_oid,
    ssh_string *oids,
    void *userdata
    );

typedef int (*ssh_gssapi_verify_mic_callback)(
    ssh_session session,
    ssh_string mic,
    void *mic_buffer,
    size_t mic_buffer_size,
    void *userdata
    );

typedef void (*ssh_log_callback)(
    ssh_session session,
    int priority,
    const char *message,
    void *userdata
    );

typedef void (*ssh_logging_callback)(
    int priority,
    const char *function,
    const char *buffer,
    void *userdata
    );

typedef int (*ssh_message_callback)(
    ssh_session,
    ssh_message message,
    void *user
    );

typedef int (*ssh_packet_callback)(
    ssh_session session,
    uint8_t type,
    ssh_buffer packet,
    void *user
    );

typedef int (*ssh_service_request_callback)(
    ssh_session session,
    const char *service,
    void *userdata
    );

typedef void (*ssh_status_callback)(
    ssh_session session,
    float status,
    void *userdata
    );

// structs

struct ssh_callbacks_struct;
struct ssh_channel_callbacks_struct;
struct ssh_packet_callbacks_struct;
struct ssh_server_callbacks_struct;
struct ssh_socket_callbacks_struct;

// global functions

LIBSSH_API int
ssh_set_callbacks(
    ssh_session session,
    ssh_callbacks cb
);

LIBSSH_API int
ssh_set_channel_callbacks(
    ssh_channel channel,
    ssh_channel_callbacks cb
);

LIBSSH_API int
ssh_set_server_callbacks(
    ssh_session session,
    ssh_server_callbacks cb
);

// macros

#define SSH_PACKET_CALLBACK(name)
#define SSH_PACKET_NOT_USED
#define SSH_PACKET_USED
#define SSH_SOCKET_CONNECTED_ERROR
#define SSH_SOCKET_CONNECTED_OK
#define SSH_SOCKET_CONNECTED_TIMEOUT
#define SSH_SOCKET_EXCEPTION_EOF
#define SSH_SOCKET_EXCEPTION_ERROR
#define SSH_SOCKET_FLOW_WRITEWILLBLOCK
#define SSH_SOCKET_FLOW_WRITEWONTBLOCK

#define ssh_callbacks_exists( \
    p, \
    c \
)

#define ssh_callbacks_init(p)

Detailed Documentation

Callback which can be replaced in libssh.

Typedefs

typedef int (*ssh_auth_gssapi_mic_callback)(
    ssh_session session,
    const char *user,
    const char *principal,
    void *userdata
    )

SSH authentication callback.

Tries to authenticates user with the “gssapi-with-mic” method

Warning

Implementations should verify that parameter user matches in some way the principal. user and principal can be different. Only the latter is guaranteed to be safe.

Parameters:

session	Current session handler
user	Username of the user (can be spoofed)
principal	Authenticated principal of the user, including realm.
userdata	Userdata to be passed to the callback function.

Returns:

SSH_AUTH_SUCCESS Authentication is accepted.

SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed.

SSH_AUTH_DENIED Authentication failed.

typedef int (*ssh_auth_none_callback)(
    ssh_session session,
    const char *user,
    void *userdata
    )

SSH authentication callback.

Tries to authenticates user with the “none” method which is anonymous or passwordless.

Parameters:

session	Current session handler
user	User that wants to authenticate
userdata	Userdata to be passed to the callback function.

Returns:

SSH_AUTH_SUCCESS Authentication is accepted.

SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed.

SSH_AUTH_DENIED Authentication failed.

typedef int (*ssh_auth_password_callback)(
    ssh_session session,
    const char *user,
    const char *password,
    void *userdata
    )

These are callbacks used specifically in SSH servers.

SSH authentication callback.

Parameters:

session	Current session handler
user	User that wants to authenticate
password	Password used for authentication
userdata	Userdata to be passed to the callback function.

Returns:

SSH_AUTH_SUCCESS Authentication is accepted.

SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed.

SSH_AUTH_DENIED Authentication failed.

typedef int (*ssh_auth_pubkey_callback)(
    ssh_session session,
    const char *user,
    struct ssh_key_struct *pubkey,
    char signature_state,
    void *userdata
    )

SSH authentication callback.

Parameters:

session	Current session handler
user	User that wants to authenticate
pubkey	public key used for authentication
signature_state	SSH_PUBLICKEY_STATE_NONE if the key is not signed (simple public key probe), SSH_PUBLICKEY_STATE_VALID if the signature is valid. Others values should be replied with a SSH_AUTH_DENIED.
userdata	Userdata to be passed to the callback function.

Returns:

SSH_AUTH_SUCCESS Authentication is accepted.

SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed.

SSH_AUTH_DENIED Authentication failed.

typedef void (*ssh_channel_auth_agent_req_callback)(
    ssh_session session,
    ssh_channel channel,
    void *userdata
    )

SSH auth-agent-request from the client.

This request is sent by a client when agent forwarding is available. Server is free to ignore this callback, no answer is expected.

Parameters:

channel	the channel
userdata	Userdata to be passed to the callback function.

typedef void (*ssh_channel_close_callback)(
    ssh_session session,
    ssh_channel channel,
    void *userdata
    )

SSH channel close callback.

Called when a channel is closed by remote peer

Parameters:

session	Current session handler
channel	the actual channel
userdata	Userdata to be passed to the callback function.

typedef int (*ssh_channel_data_callback)(
    ssh_session session,
    ssh_channel channel,
    void *data,
    uint32_t len,
    int is_stderr,
    void *userdata
    )

SSH channel data callback.

Called when data is available on a channel

Parameters:

session	Current session handler
channel	the actual channel
data	the data that has been read on the channel
len	the length of the data
is_stderr	is 0 for stdout or 1 for stderr
userdata	Userdata to be passed to the callback function.

Returns:

number of bytes processed by the callee. The remaining bytes will be sent in the next callback message, when more data is available.

typedef int (*ssh_channel_env_request_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *env_name,
    const char *env_value,
    void *userdata
    )

SSH channel environment request from a client.

Warning

some environment variables can be dangerous if changed (e.g. LD_PRELOAD) and should not be fulfilled.

Parameters:

channel	the channel
env_name	name of the environment value to be set
env_value	value of the environment value to be set
userdata	Userdata to be passed to the callback function.

Returns:

0 if the env request is accepted

1 if the request is denied

typedef void (*ssh_channel_eof_callback)(
    ssh_session session,
    ssh_channel channel,
    void *userdata
    )

SSH channel eof callback.

Called when a channel receives EOF

Parameters:

session	Current session handler
channel	the actual channel
userdata	Userdata to be passed to the callback function.

typedef int (*ssh_channel_exec_request_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *command,
    void *userdata
    )

SSH channel Exec request from a client.

Parameters:

channel	the channel
command	the shell command to be executed
userdata	Userdata to be passed to the callback function.

Returns:

0 if the exec request is accepted

1 if the request is denied

typedef void (*ssh_channel_exit_signal_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *signal,
    int core,
    const char *errmsg,
    const char *lang,
    void *userdata
    )

SSH channel exit signal callback.

Called when a channel has received an exit signal

Parameters:

session	Current session handler
channel	the actual channel
signal	the signal name (without the SIG prefix)
core	a boolean telling wether a core has been dumped or not
errmsg	the description of the exception
lang	the language of the description (format: RFC 3066)
userdata	Userdata to be passed to the callback function.

typedef void (*ssh_channel_exit_status_callback)(
    ssh_session session,
    ssh_channel channel,
    int exit_status,
    void *userdata
    )

SSH channel exit status callback.

Called when a channel has received an exit status

Parameters:

session	Current session handler
channel	the actual channel
userdata	Userdata to be passed to the callback function.

typedef ssh_channel (*ssh_channel_open_request_session_callback)(
    ssh_session session,
    void *userdata
    )

Handles an SSH new channel open session request.

Warning

The channel pointer returned by this callback must be closed by the application.

Parameters:

session	current session handler
userdata	Userdata to be passed to the callback function.

Returns:

a valid ssh_channel handle if the request is to be allowed

NULL if the request should not be allowed

typedef ssh_channel (*ssh_channel_open_request_x11_callback)(
    ssh_session session,
    const char *originator_address,
    int originator_port,
    void *userdata
    )

Handles an SSH new channel open X11 request.

This happens when the server sends back an X11 connection attempt. This is a client-side API

Warning

The channel pointer returned by this callback must be closed by the application.

Parameters:

session	current session handler
userdata	Userdata to be passed to the callback function.

Returns:

a valid ssh_channel handle if the request is to be allowed

NULL if the request should not be allowed

typedef int (*ssh_channel_pty_request_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *term,
    int width,
    int height,
    int pxwidth,
    int pwheight,
    void *userdata
    )

SSH channel PTY request from a client.

Parameters:

channel	the channel
term	The type of terminal emulation
width	width of the terminal, in characters
height	height of the terminal, in characters
pxwidth	width of the terminal, in pixels
pxheight	height of the terminal, in pixels
userdata	Userdata to be passed to the callback function.

Returns:

0 if the pty request is accepted

-1 if the request is denied

typedef int (*ssh_channel_pty_window_change_callback)(
    ssh_session session,
    ssh_channel channel,
    int width,
    int height,
    int pxwidth,
    int pwheight,
    void *userdata
    )

SSH channel PTY windows change (terminal size) from a client.

Parameters:

channel	the channel
width	width of the terminal, in characters
height	height of the terminal, in characters
pxwidth	width of the terminal, in pixels
pxheight	height of the terminal, in pixels
userdata	Userdata to be passed to the callback function.

Returns:

0 if the pty request is accepted

-1 if the request is denied

typedef int (*ssh_channel_shell_request_callback)(
    ssh_session session,
    ssh_channel channel,
    void *userdata
    )

SSH channel Shell request from a client.

Parameters:

channel	the channel
userdata	Userdata to be passed to the callback function.

Returns:

0 if the shell request is accepted

1 if the request is denied

typedef void (*ssh_channel_signal_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *signal,
    void *userdata
    )

SSH channel signal callback.

Called when a channel has received a signal

Parameters:

session	Current session handler
channel	the actual channel
signal	the signal name (without the SIG prefix)
userdata	Userdata to be passed to the callback function.

typedef int (*ssh_channel_subsystem_request_callback)(
    ssh_session session,
    ssh_channel channel,
    const char *subsystem,
    void *userdata
    )

SSH channel subsystem request from a client.

Parameters:

channel	the channel
subsystem	the subsystem required
userdata	Userdata to be passed to the callback function.

Returns:

0 if the subsystem request is accepted

1 if the request is denied

typedef void (*ssh_channel_x11_req_callback)(
    ssh_session session,
    ssh_channel channel,
    int single_connection,
    const char *auth_protocol,
    const char *auth_cookie,
    uint32_t screen_number,
    void *userdata
    )

SSH X11 request from the client.

This request is sent by a client when X11 forwarding is requested(and available). Server is free to ignore this callback, no answer is expected.

Parameters:

channel	the channel
userdata	Userdata to be passed to the callback function.

typedef void (*ssh_global_request_callback)(
    ssh_session session,
    ssh_message message,
    void *userdata
    )

SSH global request callback.

All global request will go through this callback.

Parameters:

session	Current session handler
message	the actual message
userdata	Userdata to be passed to the callback function.

typedef void (*ssh_log_callback)(
    ssh_session session,
    int priority,
    const char *message,
    void *userdata
    )

SSH log callback.

All logging messages will go through this callback

Parameters:

session	Current session handler
priority	Priority of the log, the smaller being the more important
message	the actual message
userdata	Userdata to be passed to the callback function.

typedef void (*ssh_logging_callback)(
    int priority,
    const char *function,
    const char *buffer,
    void *userdata
    )

SSH log callback.

All logging messages will go through this callback.

Parameters:

priority	Priority of the log, the smaller being the more important.
function	The function name calling the the logging fucntions.
message	The actual message
userdata	Userdata to be passed to the callback function.

typedef int (*ssh_packet_callback)(
    ssh_session session,
    uint8_t type,
    ssh_buffer packet,
    void *user
    )

Prototype for a packet callback, to be called when a new packet arrives.

Parameters:

session	The current session of the packet
type	packet type (see ssh2.h)
packet	buffer containing the packet, excluding size, type and padding fields
user	user argument to the callback and are called each time a packet shows up

Returns:

SSH_PACKET_USED Packet was parsed and used

SSH_PACKET_NOT_USED Packet was not used or understood, processing must continue

typedef int (*ssh_service_request_callback)(
    ssh_session session,
    const char *service,
    void *userdata
    )

Handles an SSH service request.

Parameters:

session	current session handler
service	name of the service (e.g. “ssh-userauth”) requested
userdata	Userdata to be passed to the callback function.

Returns:

0 if the request is to be allowed

-1 if the request should not be allowed

typedef void (*ssh_status_callback)(
    ssh_session session,
    float status,
    void *userdata
    )

SSH Connection status callback.

Parameters:

session	Current session handler
status	Percentage of connection status, going from 0.0 to 1.0 once connection is done.
userdata	Userdata to be passed to the callback function.

Global Functions

LIBSSH_API int
ssh_set_callbacks(
    ssh_session session,
    ssh_callbacks cb
)

Set the session callback functions.

This functions sets the callback structure to use your own callback functions for auth, logging and status.

struct ssh_callbacks_struct cb = {
  .userdata = data,
  .auth_function = my_auth_function
};
ssh_callbacks_init(&cb);
ssh_set_callbacks(session, &cb);

Parameters:

session	The session to set the callback structure.
cb	The callback structure itself.

Returns:

SSH_OK on success, SSH_ERROR on error.

LIBSSH_API int
ssh_set_channel_callbacks(
    ssh_channel channel,
    ssh_channel_callbacks cb
)

Set the channel callback functions.

This functions sets the callback structure to use your own callback functions for channel data and exceptions

struct ssh_channel_callbacks_struct cb = {
  .userdata = data,
  .channel_data = my_channel_data_function
};
ssh_callbacks_init(&cb);
ssh_set_channel_callbacks(channel, &cb);

Parameters:

channel	The channel to set the callback structure.
cb	The callback structure itself.

Returns:

SSH_OK on success, SSH_ERROR on error.

LIBSSH_API int
ssh_set_server_callbacks(
    ssh_session session,
    ssh_server_callbacks cb
)

Set the session server callback functions.

This functions sets the callback structure to use your own callback functions for user authentication, new channels and requests.

struct ssh_server_callbacks_struct cb = {
  .userdata = data,
  .auth_password_function = my_auth_function
};
ssh_callbacks_init(&cb);
ssh_set_server_callbacks(session, &cb);

Parameters:

session	The session to set the callback structure.
cb	The callback structure itself.

Returns:

SSH_OK on success, SSH_ERROR on error.

Macros

#define SSH_PACKET_CALLBACK(name)

This macro declares a packet callback handler.

SSH_PACKET_CALLBACK(mycallback){
...
}

#define SSH_PACKET_NOT_USED

Packet was not used and should be passed to any other callback available.

#define SSH_PACKET_USED

return values for a ssh_packet_callback

Packet was used and should not be parsed by another callback

#define ssh_callbacks_init(p)

Initializes an ssh_callbacks_struct A call to this macro is mandatory when you have set a new ssh_callback_struct structure.

Its goal is to maintain the binary compatibility with future versions of libssh as the structure evolves with time.