libssh: include/libssh/callbacks.h Source File

libssh 0.7.4

callbacks.h
1 /*
2 * This file is part of the SSH Library
3 *
4 * Copyright (c) 2009 Aris Adamantiadis <aris@0xbadc0de.be>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
21 /* callback.h
22 * This file includes the public declarations for the libssh callback mechanism
23 */
24
25 #ifndef _SSH_CALLBACK_H
26 #define _SSH_CALLBACK_H
27
28 #include <libssh/libssh.h>
29 #include <string.h>
30
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
49 typedef void (*ssh_callback_int) (int code, void *user);
50
59 typedef int (*ssh_callback_data) (const void *data, size_t len, void *user);
60
61 typedef void (*ssh_callback_int_int) (int code, int errno_code, void *user);
62
63 typedef int (*ssh_message_callback) (ssh_session, ssh_message message, void *user);
64 typedef int (*ssh_channel_callback_int) (ssh_channel channel, int code, void *user);
65 typedef int (*ssh_channel_callback_data) (ssh_channel channel, int code, void *data, size_t len, void *user);
66
74 typedef void (*ssh_log_callback) (ssh_session session, int priority,
75 const char *message, void *userdata);
76
90 typedef void (*ssh_logging_callback) (int priority,
91 const char *function,
92 const char *buffer,
93 void *userdata);
94
102 typedef void (*ssh_status_callback) (ssh_session session, float status,
103 void *userdata);
104
112 typedef void (*ssh_global_request_callback) (ssh_session session,
113 ssh_message message, void *userdata);
114
124 typedef ssh_channel (*ssh_channel_open_request_x11_callback) (ssh_session session,
125 const char * originator_address, int originator_port, void *userdata);
126
130 struct ssh_callbacks_struct {
132 size_t size;
136 void *userdata;
140 ssh_auth_callback auth_function;
144 ssh_log_callback log_function;
149 void (*connect_status_function)(void *userdata, float status);
153 ssh_global_request_callback global_request_function;
156 ssh_channel_open_request_x11_callback channel_open_request_x11_function;
157 };
158 typedef struct ssh_callbacks_struct *ssh_callbacks;
159
173 typedef int (*ssh_auth_password_callback) (ssh_session session, const char *user, const char *password,
174 void *userdata);
175
186 typedef int (*ssh_auth_none_callback) (ssh_session session, const char *user, void *userdata);
187
200 typedef int (*ssh_auth_gssapi_mic_callback) (ssh_session session, const char *user, const char *principal,
201 void *userdata);
202
216 typedef int (*ssh_auth_pubkey_callback) (ssh_session session, const char *user, struct ssh_key_struct *pubkey,
217 char signature_state, void *userdata);
218
219
229 typedef int (*ssh_service_request_callback) (ssh_session session, const char *service, void *userdata);
230
239 typedef ssh_channel (*ssh_channel_open_request_session_callback) (ssh_session session, void *userdata);
240
241 /*
242 * @brief handle the beginning of a GSSAPI authentication, server side.
243 * @param session current session handler
244 * @param user the username of the client
245 * @param n_oid number of available oids
246 * @param oids OIDs provided by the client
247 * @returns an ssh_string containing the chosen OID, that's supported by both
248 * client and server.
249 * @warning It is not necessary to fill this callback in if libssh is linked
250 * with libgssapi.
251 */
252 typedef ssh_string (*ssh_gssapi_select_oid_callback) (ssh_session session, const char *user,
253 int n_oid, ssh_string *oids, void *userdata);
254
255 /*
256 * @brief handle the negociation of a security context, server side.
257 * @param session current session handler
258 * @param[in] input_token input token provided by client
259 * @param[out] output_token output of the gssapi accept_sec_context method,
260 * NULL after completion.
261 * @returns SSH_OK if the token was generated correctly or accept_sec_context
262 * returned GSS_S_COMPLETE
263 * @returns SSH_ERROR in case of error
264 * @warning It is not necessary to fill this callback in if libssh is linked
265 * with libgssapi.
266 */
267 typedef int (*ssh_gssapi_accept_sec_ctx_callback) (ssh_session session,
268 ssh_string input_token, ssh_string *output_token, void *userdata);
269
270 /*
271 * @brief Verify and authenticates a MIC, server side.
272 * @param session current session handler
273 * @param[in] mic input mic to be verified provided by client
274 * @param[in] mic_buffer buffer of data to be signed.
275 * @param[in] mic_buffer_size size of mic_buffer
276 * @returns SSH_OK if the MIC was authenticated correctly
277 * @returns SSH_ERROR in case of error
278 * @warning It is not necessary to fill this callback in if libssh is linked
279 * with libgssapi.
280 */
281 typedef int (*ssh_gssapi_verify_mic_callback) (ssh_session session,
282 ssh_string mic, void *mic_buffer, size_t mic_buffer_size, void *userdata);
283
284
289 struct ssh_server_callbacks_struct {
291 size_t size;
295 void *userdata;
299 ssh_auth_password_callback auth_password_function;
300
304 ssh_auth_none_callback auth_none_function;
305
309 ssh_auth_gssapi_mic_callback auth_gssapi_mic_function;
310
314 ssh_auth_pubkey_callback auth_pubkey_function;
315
319 ssh_service_request_callback service_request_function;
323 ssh_channel_open_request_session_callback channel_open_request_session_function;
326 ssh_gssapi_select_oid_callback gssapi_select_oid_function;
329 ssh_gssapi_accept_sec_ctx_callback gssapi_accept_sec_ctx_function;
330 /* This function will be called when a MIC needs to be verified.
331 */
332 ssh_gssapi_verify_mic_callback gssapi_verify_mic_function;
333 };
334 typedef struct ssh_server_callbacks_struct *ssh_server_callbacks;
335
357 LIBSSH_API int ssh_set_server_callbacks(ssh_session session, ssh_server_callbacks cb);
358
363 struct ssh_socket_callbacks_struct {
367 void *userdata;
372 ssh_callback_data data;
376 ssh_callback_int controlflow;
380 ssh_callback_int_int exception;
384 ssh_callback_int_int connected;
385 };
386 typedef struct ssh_socket_callbacks_struct *ssh_socket_callbacks;
387
388 #define SSH_SOCKET_FLOW_WRITEWILLBLOCK 1
389 #define SSH_SOCKET_FLOW_WRITEWONTBLOCK 2
390
391 #define SSH_SOCKET_EXCEPTION_EOF 1
392 #define SSH_SOCKET_EXCEPTION_ERROR 2
393
394 #define SSH_SOCKET_CONNECTED_OK 1
395 #define SSH_SOCKET_CONNECTED_ERROR 2
396 #define SSH_SOCKET_CONNECTED_TIMEOUT 3
397
405 #define ssh_callbacks_init(p) do {\
406 (p)->size=sizeof(*(p)); \
407 } while(0);
408
418 #define ssh_callbacks_exists(p,c) (\
419 (p != NULL) && ( (char *)&((p)-> c) < (char *)(p) + (p)->size ) && \
420 ((p)-> c != NULL) \
421 )
422
432 typedef int (*ssh_packet_callback) (ssh_session session, uint8_t type, ssh_buffer packet, void *user);
433
436 #define SSH_PACKET_USED 1
437
439 #define SSH_PACKET_NOT_USED 2
440
441
449 #define SSH_PACKET_CALLBACK(name) \
450 int name (ssh_session session, uint8_t type, ssh_buffer packet, void *user)
451
452 struct ssh_packet_callbacks_struct {
454 uint8_t start;
456 uint8_t n_callbacks;
458 ssh_packet_callback *callbacks;
462 void *user;
463 };
464
465 typedef struct ssh_packet_callbacks_struct *ssh_packet_callbacks;
466
488 LIBSSH_API int ssh_set_callbacks(ssh_session session, ssh_callbacks cb);
489
501 typedef int (*ssh_channel_data_callback) (ssh_session session,
502 ssh_channel channel,
503 void *data,
504 uint32_t len,
505 int is_stderr,
506 void *userdata);
507
514 typedef void (*ssh_channel_eof_callback) (ssh_session session,
515 ssh_channel channel,
516 void *userdata);
517
524 typedef void (*ssh_channel_close_callback) (ssh_session session,
525 ssh_channel channel,
526 void *userdata);
527
535 typedef void (*ssh_channel_signal_callback) (ssh_session session,
536 ssh_channel channel,
537 const char *signal,
538 void *userdata);
539
546 typedef void (*ssh_channel_exit_status_callback) (ssh_session session,
547 ssh_channel channel,
548 int exit_status,
549 void *userdata);
550
561 typedef void (*ssh_channel_exit_signal_callback) (ssh_session session,
562 ssh_channel channel,
563 const char *signal,
564 int core,
565 const char *errmsg,
566 const char *lang,
567 void *userdata);
568
581 typedef int (*ssh_channel_pty_request_callback) (ssh_session session,
582 ssh_channel channel,
583 const char *term,
584 int width, int height,
585 int pxwidth, int pwheight,
586 void *userdata);
587
595 typedef int (*ssh_channel_shell_request_callback) (ssh_session session,
596 ssh_channel channel,
597 void *userdata);
605 typedef void (*ssh_channel_auth_agent_req_callback) (ssh_session session,
606 ssh_channel channel,
607 void *userdata);
608
616 typedef void (*ssh_channel_x11_req_callback) (ssh_session session,
617 ssh_channel channel,
618 int single_connection,
619 const char *auth_protocol,
620 const char *auth_cookie,
621 uint32_t screen_number,
622 void *userdata);
634 typedef int (*ssh_channel_pty_window_change_callback) (ssh_session session,
635 ssh_channel channel,
636 int width, int height,
637 int pxwidth, int pwheight,
638 void *userdata);
639
648 typedef int (*ssh_channel_exec_request_callback) (ssh_session session,
649 ssh_channel channel,
650 const char *command,
651 void *userdata);
652
664 typedef int (*ssh_channel_env_request_callback) (ssh_session session,
665 ssh_channel channel,
666 const char *env_name,
667 const char *env_value,
668 void *userdata);
677 typedef int (*ssh_channel_subsystem_request_callback) (ssh_session session,
678 ssh_channel channel,
679 const char *subsystem,
680 void *userdata);
681
682
683 struct ssh_channel_callbacks_struct {
685 size_t size;
689 void *userdata;
693 ssh_channel_data_callback channel_data_function;
697 ssh_channel_eof_callback channel_eof_function;
701 ssh_channel_close_callback channel_close_function;
705 ssh_channel_signal_callback channel_signal_function;
709 ssh_channel_exit_status_callback channel_exit_status_function;
713 ssh_channel_exit_signal_callback channel_exit_signal_function;
717 ssh_channel_pty_request_callback channel_pty_request_function;
721 ssh_channel_shell_request_callback channel_shell_request_function;
725 ssh_channel_auth_agent_req_callback channel_auth_agent_req_function;
729 ssh_channel_x11_req_callback channel_x11_req_function;
733 ssh_channel_pty_window_change_callback channel_pty_window_change_function;
737 ssh_channel_exec_request_callback channel_exec_request_function;
741 ssh_channel_env_request_callback channel_env_request_function;
745 ssh_channel_subsystem_request_callback channel_subsystem_request_function;
746 };
747
748 typedef struct ssh_channel_callbacks_struct *ssh_channel_callbacks;
749
771 LIBSSH_API int ssh_set_channel_callbacks(ssh_channel channel,
772 ssh_channel_callbacks cb);
773
780 typedef int (*ssh_thread_callback) (void **lock);
781
782 typedef unsigned long (*ssh_thread_id_callback) (void);
783 struct ssh_threads_callbacks_struct {
784 const char *type;
785 ssh_thread_callback mutex_init;
786 ssh_thread_callback mutex_destroy;
787 ssh_thread_callback mutex_lock;
788 ssh_thread_callback mutex_unlock;
789 ssh_thread_id_callback thread_id;
790 };
791
809 LIBSSH_API int ssh_threads_set_callbacks(struct ssh_threads_callbacks_struct
810 *cb);
811
818 LIBSSH_API struct ssh_threads_callbacks_struct *ssh_threads_get_pthread(void);
819
830 LIBSSH_API struct ssh_threads_callbacks_struct *ssh_threads_get_noop(void);
831
839 LIBSSH_API int ssh_set_log_callback(ssh_logging_callback cb);
840
846 LIBSSH_API ssh_logging_callback ssh_get_log_callback(void);
847
849 #ifdef __cplusplus
850 }
851 #endif
852
853 #endif /*_SSH_CALLBACK_H */
854
855 /* @} */
ssh_callbacks_struct::auth_function
ssh_auth_callback auth_function
This functions will be called if e.g.
Definition: callbacks.h:140
ssh_status_callback
void(* ssh_status_callback)(ssh_session session, float status, void *userdata)
SSH Connection status callback.
Definition: callbacks.h:102
ssh_channel_auth_agent_req_callback
void(* ssh_channel_auth_agent_req_callback)(ssh_session session, ssh_channel channel, void *userdata)
SSH auth-agent-request from the client.
Definition: callbacks.h:605
ssh_socket_callbacks_struct
These are the callbacks exported by the socket structure They are called by the socket module when a ...
Definition: callbacks.h:363
ssh_channel_pty_window_change_callback
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.
Definition: callbacks.h:634
ssh_callbacks_struct
The structure to replace libssh functions with appropriate callbacks.
Definition: callbacks.h:130
ssh_channel_data_callback
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.
Definition: callbacks.h:501
ssh_server_callbacks_struct::auth_password_function
ssh_auth_password_callback auth_password_function
This function gets called when a client tries to authenticate through password method.
Definition: callbacks.h:299
ssh_callbacks_struct::connect_status_function
void(* connect_status_function)(void *userdata, float status)
This function gets called during connection time to indicate the percentage of connection steps compl...
Definition: callbacks.h:149
ssh_service_request_callback
int(* ssh_service_request_callback)(ssh_session session, const char *service, void *userdata)
Handles an SSH service request.
Definition: callbacks.h:229
ssh_callbacks_struct::userdata
void * userdata
User-provided data.
Definition: callbacks.h:136
ssh_auth_none_callback
int(* ssh_auth_none_callback)(ssh_session session, const char *user, void *userdata)
SSH authentication callback.
Definition: callbacks.h:186
ssh_auth_password_callback
int(* ssh_auth_password_callback)(ssh_session session, const char *user, const char *password, void *userdata)
These are callbacks used specifically in SSH servers.
Definition: callbacks.h:173
ssh_server_callbacks_struct::userdata
void * userdata
User-provided data.
Definition: callbacks.h:295
ssh_channel_pty_request_callback
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.
Definition: callbacks.h:581
ssh_server_callbacks_struct::auth_none_function
ssh_auth_none_callback auth_none_function
This function gets called when a client tries to authenticate through none method.
Definition: callbacks.h:304
ssh_packet_callback
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.
Definition: callbacks.h:432
ssh_set_callbacks
LIBSSH_API int ssh_set_callbacks(ssh_session session, ssh_callbacks cb)
Set the session callback functions.
Definition: callbacks.c:45
ssh_server_callbacks_struct::auth_gssapi_mic_function
ssh_auth_gssapi_mic_callback auth_gssapi_mic_function
This function gets called when a client tries to authenticate through gssapi-mic method.
Definition: callbacks.h:309
ssh_threads_get_noop
LIBSSH_API struct ssh_threads_callbacks_struct * ssh_threads_get_noop(void)
Get the noop threads callbacks structure.
Definition: threads.c:55
ssh_callbacks_struct::global_request_function
ssh_global_request_callback global_request_function
This function will be called each time a global request is received.
Definition: callbacks.h:153
ssh_callbacks_struct::size
size_t size
DON&#39;T SET THIS use ssh_callbacks_init() instead.
Definition: callbacks.h:132
ssh_channel_open_request_session_callback
ssh_channel(* ssh_channel_open_request_session_callback)(ssh_session session, void *userdata)
Handles an SSH new channel open session request.
Definition: callbacks.h:239
ssh_channel_env_request_callback
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.
Definition: callbacks.h:664
ssh_global_request_callback
void(* ssh_global_request_callback)(ssh_session session, ssh_message message, void *userdata)
SSH global request callback.
Definition: callbacks.h:112
ssh_set_channel_callbacks
LIBSSH_API int ssh_set_channel_callbacks(ssh_channel channel, ssh_channel_callbacks cb)
Set the channel callback functions.
Definition: callbacks.c:67
ssh_set_server_callbacks
LIBSSH_API int ssh_set_server_callbacks(ssh_session session, ssh_server_callbacks cb)
Set the session server callback functions.
Definition: callbacks.c:85
ssh_server_callbacks_struct
This structure can be used to implement a libssh server, with appropriate callbacks.
Definition: callbacks.h:289
ssh_logging_callback
void(* ssh_logging_callback)(int priority, const char *function, const char *buffer, void *userdata)
SSH log callback.
Definition: callbacks.h:90
ssh_channel_x11_req_callback
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.
Definition: callbacks.h:616
ssh_channel_eof_callback
void(* ssh_channel_eof_callback)(ssh_session session, ssh_channel channel, void *userdata)
SSH channel eof callback.
Definition: callbacks.h:514
ssh_channel_shell_request_callback
int(* ssh_channel_shell_request_callback)(ssh_session session, ssh_channel channel, void *userdata)
SSH channel Shell request from a client.
Definition: callbacks.h:595
ssh_get_log_callback
LIBSSH_API ssh_logging_callback ssh_get_log_callback(void)
Get the pointer to the logging callback function.
Definition: log.c:207
ssh_socket_callbacks_struct::userdata
void * userdata
User-provided data.
Definition: callbacks.h:367
ssh_server_callbacks_struct::size
size_t size
DON&#39;T SET THIS use ssh_callbacks_init() instead.
Definition: callbacks.h:291
ssh_auth_pubkey_callback
int(* ssh_auth_pubkey_callback)(ssh_session session, const char *user, struct ssh_key_struct *pubkey, char signature_state, void *userdata)
SSH authentication callback.
Definition: callbacks.h:216
ssh_server_callbacks_struct::channel_open_request_session_function
ssh_channel_open_request_session_callback channel_open_request_session_function
This functions gets called when a new channel request is issued by the client.
Definition: callbacks.h:323
ssh_channel_close_callback
void(* ssh_channel_close_callback)(ssh_session session, ssh_channel channel, void *userdata)
SSH channel close callback.
Definition: callbacks.h:524
ssh_channel_exit_signal_callback
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.
Definition: callbacks.h:561
ssh_set_log_callback
LIBSSH_API int ssh_set_log_callback(ssh_logging_callback cb)
Set the logging callback function.
Definition: log.c:197
ssh_log_callback
void(* ssh_log_callback)(ssh_session session, int priority, const char *message, void *userdata)
SSH log callback.
Definition: callbacks.h:74
ssh_channel_subsystem_request_callback
int(* ssh_channel_subsystem_request_callback)(ssh_session session, ssh_channel channel, const char *subsystem, void *userdata)
SSH channel subsystem request from a client.
Definition: callbacks.h:677
ssh_channel_signal_callback
void(* ssh_channel_signal_callback)(ssh_session session, ssh_channel channel, const char *signal, void *userdata)
SSH channel signal callback.
Definition: callbacks.h:535
ssh_channel_exit_status_callback
void(* ssh_channel_exit_status_callback)(ssh_session session, ssh_channel channel, int exit_status, void *userdata)
SSH channel exit status callback.
Definition: callbacks.h:546
ssh_threads_set_callbacks
LIBSSH_API int ssh_threads_set_callbacks(struct ssh_threads_callbacks_struct *cb)
Set the thread callbacks structure.
Definition: threads.c:184
ssh_auth_gssapi_mic_callback
int(* ssh_auth_gssapi_mic_callback)(ssh_session session, const char *user, const char *principal, void *userdata)
SSH authentication callback.
Definition: callbacks.h:200
ssh_server_callbacks_struct::service_request_function
ssh_service_request_callback service_request_function
This functions gets called when a service request is issued by the client.
Definition: callbacks.h:319
ssh_channel_open_request_x11_callback
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.
Definition: callbacks.h:124
ssh_callbacks_struct::log_function
ssh_log_callback log_function
This function will be called each time a loggable event happens.
Definition: callbacks.h:144
ssh_callbacks_struct::channel_open_request_x11_function
ssh_channel_open_request_x11_callback channel_open_request_x11_function
This function will be called when an incoming X11 request is received.
Definition: callbacks.h:156
ssh_channel_exec_request_callback
int(* ssh_channel_exec_request_callback)(ssh_session session, ssh_channel channel, const char *command, void *userdata)
SSH channel Exec request from a client.
Definition: callbacks.h:648
ssh_server_callbacks_struct::auth_pubkey_function
ssh_auth_pubkey_callback auth_pubkey_function
this function gets called when a client tries to authenticate or offer a public key.
Definition: callbacks.h:314