libssh  0.7.3
Data Structures | Macros | Typedefs | Functions
The libssh callbacks

Callback which can be replaced in libssh. More...

Collaboration diagram for The libssh callbacks:

Data Structures

struct  ssh_callbacks
 The structure to replace libssh functions with appropriate callbacks. More...
 
struct  ssh_server_callbacks
 This structure can be used to implement a libssh server, with appropriate callbacks. More...
 
struct  ssh_socket_callbacks
 These are the callbacks exported by the socket structure They are called by the socket module when a socket event appears. More...
 

Macros

#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. More...
 
#define SSH_PACKET_CALLBACK(name)   int name (ssh_session session, uint8_t type, ssh_buffer packet, void *user)
 This macro declares a packet callback handler. More...
 
#define SSH_PACKET_NOT_USED   2
 Packet was not used and should be passed to any other callback available.
 
#define SSH_PACKET_USED   1
 return values for a ssh_packet_callback More...
 

Typedefs

typedef int(* ssh_auth_gssapi_mic_callback) (ssh_session session, const char *user, const char *principal, void *userdata)
 SSH authentication callback. More...
 
typedef int(* ssh_auth_none_callback) (ssh_session session, const char *user, void *userdata)
 SSH authentication callback. More...
 
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. More...
 
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. More...
 
typedef void(* ssh_channel_auth_agent_req_callback) (ssh_session session, ssh_channel channel, void *userdata)
 SSH auth-agent-request from the client. More...
 
typedef void(* ssh_channel_close_callback) (ssh_session session, ssh_channel channel, void *userdata)
 SSH channel close callback. More...
 
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. More...
 
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. More...
 
typedef void(* ssh_channel_eof_callback) (ssh_session session, ssh_channel channel, void *userdata)
 SSH channel eof callback. More...
 
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. More...
 
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. More...
 
typedef void(* ssh_channel_exit_status_callback) (ssh_session session, ssh_channel channel, int exit_status, void *userdata)
 SSH channel exit status callback. More...
 
typedef ssh_channel(* ssh_channel_open_request_session_callback) (ssh_session session, void *userdata)
 Handles an SSH new channel open session request. More...
 
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. More...
 
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. More...
 
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. More...
 
typedef int(* ssh_channel_shell_request_callback) (ssh_session session, ssh_channel channel, void *userdata)
 SSH channel Shell request from a client. More...
 
typedef void(* ssh_channel_signal_callback) (ssh_session session, ssh_channel channel, const char *signal, void *userdata)
 SSH channel signal callback. More...
 
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. More...
 
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. More...
 
typedef void(* ssh_global_request_callback) (ssh_session session, ssh_message message, void *userdata)
 SSH global request callback. More...
 
typedef void(* ssh_log_callback) (ssh_session session, int priority, const char *message, void *userdata)
 SSH log callback. More...
 
typedef void(* ssh_logging_callback) (int priority, const char *function, const char *buffer, void *userdata)
 SSH log callback. More...
 
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. More...
 
typedef int(* ssh_service_request_callback) (ssh_session session, const char *service, void *userdata)
 Handles an SSH service request. More...
 
typedef void(* ssh_status_callback) (ssh_session session, float status, void *userdata)
 SSH Connection status callback. More...
 

Functions

LIBSSH_API int ssh_set_callbacks (ssh_session session, ssh_callbacks cb)
 Set the session callback functions. More...
 
LIBSSH_API int ssh_set_channel_callbacks (ssh_channel channel, ssh_channel_callbacks cb)
 Set the channel callback functions. More...
 
LIBSSH_API int ssh_set_server_callbacks (ssh_session session, ssh_server_callbacks cb)
 Set the session server callback functions. More...
 

Detailed Description

Callback which can be replaced in libssh.

Macro Definition Documentation

#define ssh_callbacks_init (   p)
Value:
do {\
(p)->size=sizeof(*(p)); \
} while(0);

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.

#define SSH_PACKET_CALLBACK (   name)    int name (ssh_session session, uint8_t type, ssh_buffer packet, void *user)

This macro declares a packet callback handler.

1 SSH_PACKET_CALLBACK(mycallback){
2 ...
3 }

Referenced by ssh_channel_accept_x11(), ssh_channel_new(), ssh_channel_set_blocking(), ssh_gssapi_get_creds(), ssh_message_free(), and ssh_userauth_password().

#define SSH_PACKET_USED   1

return values for a ssh_packet_callback

Packet was used and should not be parsed by another callback

Referenced by ssh_channel_accept_x11(), ssh_channel_new(), ssh_channel_set_blocking(), ssh_gssapi_get_creds(), ssh_message_auth_pubkey(), ssh_message_free(), and ssh_userauth_password().

Typedef Documentation

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

Parameters
sessionCurrent session handler
userUsername of the user (can be spoofed)
principalAuthenticated principal of the user, including realm.
userdataUserdata 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.
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.
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
sessionCurrent session handler
userUser that wants to authenticate
userdataUserdata 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
sessionCurrent session handler
userUser that wants to authenticate
passwordPassword used for authentication
userdataUserdata 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
sessionCurrent session handler
userUser that wants to authenticate
pubkeypublic key used for authentication
signature_stateSSH_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.
userdataUserdata 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
channelthe channel
userdataUserdata 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
sessionCurrent session handler
channelthe actual channel
userdataUserdata 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
sessionCurrent session handler
channelthe actual channel
datathe data that has been read on the channel
lenthe length of the data
is_stderris 0 for stdout or 1 for stderr
userdataUserdata 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.

Parameters
channelthe channel
env_namename of the environment value to be set
env_valuevalue of the environment value to be set
userdataUserdata to be passed to the callback function.
Returns
0 if the env request is accepted
1 if the request is denied
Warning
some environment variables can be dangerous if changed (e.g. LD_PRELOAD) and should not be fulfilled.
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
sessionCurrent session handler
channelthe actual channel
userdataUserdata 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
channelthe channel
commandthe shell command to be executed
userdataUserdata 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
sessionCurrent session handler
channelthe actual channel
signalthe signal name (without the SIG prefix)
corea boolean telling wether a core has been dumped or not
errmsgthe description of the exception
langthe language of the description (format: RFC 3066)
userdataUserdata 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
sessionCurrent session handler
channelthe actual channel
userdataUserdata 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.

Parameters
sessioncurrent session handler
userdataUserdata 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
Warning
The channel pointer returned by this callback must be closed by the application.
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

Parameters
sessioncurrent session handler
userdataUserdata 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
Warning
The channel pointer returned by this callback must be closed by the application.
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
channelthe channel
termThe type of terminal emulation
widthwidth of the terminal, in characters
heightheight of the terminal, in characters
pxwidthwidth of the terminal, in pixels
pxheightheight of the terminal, in pixels
userdataUserdata 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
channelthe channel
widthwidth of the terminal, in characters
heightheight of the terminal, in characters
pxwidthwidth of the terminal, in pixels
pxheightheight of the terminal, in pixels
userdataUserdata 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
channelthe channel
userdataUserdata 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
sessionCurrent session handler
channelthe actual channel
signalthe signal name (without the SIG prefix)
userdataUserdata 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
channelthe channel
subsystemthe subsystem required
userdataUserdata 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
channelthe channel
userdataUserdata 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
sessionCurrent session handler
messagethe actual message
userdataUserdata 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
sessionCurrent session handler
priorityPriority of the log, the smaller being the more important
messagethe actual message
userdataUserdata 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
priorityPriority of the log, the smaller being the more important.
functionThe function name calling the the logging fucntions.
messageThe actual message
userdataUserdata 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
sessionThe current session of the packet
typepacket type (see ssh2.h)
packetbuffer containing the packet, excluding size, type and padding fields
useruser 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
sessioncurrent session handler
servicename of the service (e.g. "ssh-userauth") requested
userdataUserdata 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
sessionCurrent session handler
statusPercentage of connection status, going from 0.0 to 1.0 once connection is done.
userdataUserdata to be passed to the callback function.

Function Documentation

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.

1 struct ssh_callbacks_struct cb = {
2  .userdata = data,
3  .auth_function = my_auth_function
4 };
5 ssh_callbacks_init(&cb);
6 ssh_set_callbacks(session, &cb);
Parameters
sessionThe session to set the callback structure.
cbThe callback structure itself.
Returns
SSH_OK on success, SSH_ERROR on error.

References ssh_get_log_callback(), ssh_set_log_callback(), and ssh_set_log_userdata().

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

1 struct ssh_channel_callbacks_struct cb = {
2  .userdata = data,
3  .channel_data = my_channel_data_function
4 };
5 ssh_callbacks_init(&cb);
6 ssh_set_channel_callbacks(channel, &cb);
Parameters
channelThe channel to set the callback structure.
cbThe 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.

1 struct ssh_server_callbacks_struct cb = {
2  .userdata = data,
3  .auth_password_function = my_auth_function
4 };
5 ssh_callbacks_init(&cb);
6 ssh_set_server_callbacks(session, &cb);
Parameters
sessionThe session to set the callback structure.
cbThe callback structure itself.
Returns
SSH_OK on success, SSH_ERROR on error.