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
32extern "C" {
33#endif
34
35/**
36 * @defgroup libssh_callbacks The libssh callbacks
37 * @ingroup libssh
38 *
39 * Callback which can be replaced in libssh.
40 *
41 * @{
42 */
43
44/** @internal
45 * @brief callback to process simple codes
46 * @param code value to transmit
47 * @param user Userdata to pass in callback
48 */
49typedef void (*ssh_callback_int) (int code, void *user);
50
51/** @internal
52 * @brief callback for data received messages.
53 * @param data data retrieved from the socket or stream
54 * @param len number of bytes available from this stream
55 * @param user user-supplied pointer sent along with all callback messages
56 * @returns number of bytes processed by the callee. The remaining bytes will
57 * be sent in the next callback message, when more data is available.
58 */
59typedef int (*ssh_callback_data) (const void *data, size_t len, void *user);
60
61typedef void (*ssh_callback_int_int) (int code, int errno_code, void *user);
62
63typedef int (*ssh_message_callback) (ssh_session, ssh_message message, void *user);
64typedef int (*ssh_channel_callback_int) (ssh_channel channel, int code, void *user);
65typedef int (*ssh_channel_callback_data) (ssh_channel channel, int code, void *data, size_t len, void *user);
66
67/**
68 * @brief SSH log callback. All logging messages will go through this callback
69 * @param session Current session handler
70 * @param priority Priority of the log, the smaller being the more important
71 * @param message the actual message
72 * @param userdata Userdata to be passed to the callback function.
73 */
74typedef void (*ssh_log_callback) (ssh_session session, int priority,
75 const char *message, void *userdata);
76
77/**
78 * @brief SSH log callback.
79 *
80 * All logging messages will go through this callback.
81 *
82 * @param priority Priority of the log, the smaller being the more important.
83 *
84 * @param function The function name calling the the logging fucntions.
85 *
86 * @param message The actual message
87 *
88 * @param userdata Userdata to be passed to the callback function.
89 */
90typedef void (*ssh_logging_callback) (int priority,
91 const char *function,
92 const char *buffer,
93 void *userdata);
94
95/**
96 * @brief SSH Connection status callback.
97 * @param session Current session handler
98 * @param status Percentage of connection status, going from 0.0 to 1.0
99 * once connection is done.
100 * @param userdata Userdata to be passed to the callback function.
101 */
102typedef void (*ssh_status_callback) (ssh_session session, float status,
103 void *userdata);
104
105/**
106 * @brief SSH global request callback. All global request will go through this
107 * callback.
108 * @param session Current session handler
109 * @param message the actual message
110 * @param userdata Userdata to be passed to the callback function.
111 */
112typedef void (*ssh_global_request_callback) (ssh_session session,
113 ssh_message message, void *userdata);
114
115/**
116 * @brief Handles an SSH new channel open X11 request. This happens when the server
117 * sends back an X11 connection attempt. This is a client-side API
118 * @param session current session handler
119 * @param userdata Userdata to be passed to the callback function.
120 * @returns a valid ssh_channel handle if the request is to be allowed
121 * @returns NULL if the request should not be allowed
122 * @warning The channel pointer returned by this callback must be closed by the application.
123 */
124typedef ssh_channel (*ssh_channel_open_request_x11_callback) (ssh_session session,
125 const char * originator_address, int originator_port, void *userdata);
126
127/**
128 * The structure to replace libssh functions with appropriate callbacks.
129 */
130struct ssh_callbacks_struct {
131 /** DON'T SET THIS use ssh_callbacks_init() instead. */
132 size_t size;
133 /**
134 * User-provided data. User is free to set anything he wants here
135 */
136 void *userdata;
137 /**
138 * This functions will be called if e.g. a keyphrase is needed.
139 */
140 ssh_auth_callback auth_function;
141 /**
142 * This function will be called each time a loggable event happens.
143 */
144 ssh_log_callback log_function;
145 /**
146 * This function gets called during connection time to indicate the
147 * percentage of connection steps completed.
148 */
149 void (*connect_status_function)(void *userdata, float status);
150 /**
151 * This function will be called each time a global request is received.
152 */
153 ssh_global_request_callback global_request_function;
154 /** This function will be called when an incoming X11 request is received.
155 */
156 ssh_channel_open_request_x11_callback channel_open_request_x11_function;
157};
158typedef struct ssh_callbacks_struct *ssh_callbacks;
159
160/** These are callbacks used specifically in SSH servers.
161 */
162
163/**
164 * @brief SSH authentication callback.
165 * @param session Current session handler
166 * @param user User that wants to authenticate
167 * @param password Password used for authentication
168 * @param userdata Userdata to be passed to the callback function.
169 * @returns SSH_AUTH_SUCCESS Authentication is accepted.
170 * @returns SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed.
171 * @returns SSH_AUTH_DENIED Authentication failed.
172 */
173typedef int (*ssh_auth_password_callback) (ssh_session session, const char *user, const char *password,
174 void *userdata);
175
176/**
177 * @brief SSH authentication callback. Tries to authenticates user with the "none" method
178 * which is anonymous or passwordless.
179 * @param session Current session handler
180 * @param user User that wants to authenticate
181 * @param userdata Userdata to be passed to the callback function.
182 * @returns SSH_AUTH_SUCCESS Authentication is accepted.
183 * @returns SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed.
184 * @returns SSH_AUTH_DENIED Authentication failed.
185 */
186typedef int (*ssh_auth_none_callback) (ssh_session session, const char *user, void *userdata);
187
188/**
189 * @brief SSH authentication callback. Tries to authenticates user with the "gssapi-with-mic" method
190 * @param session Current session handler
191 * @param user Username of the user (can be spoofed)
192 * @param principal Authenticated principal of the user, including realm.
193 * @param userdata Userdata to be passed to the callback function.
194 * @returns SSH_AUTH_SUCCESS Authentication is accepted.
195 * @returns SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed.
196 * @returns SSH_AUTH_DENIED Authentication failed.
197 * @warning Implementations should verify that parameter user matches in some way the principal.
198 * user and principal can be different. Only the latter is guaranteed to be safe.
199 */
200typedef int (*ssh_auth_gssapi_mic_callback) (ssh_session session, const char *user, const char *principal,
201 void *userdata);
202
203/**
204 * @brief SSH authentication callback.
205 * @param session Current session handler
206 * @param user User that wants to authenticate
207 * @param pubkey public key used for authentication
208 * @param signature_state SSH_PUBLICKEY_STATE_NONE if the key is not signed (simple public key probe),
209 * SSH_PUBLICKEY_STATE_VALID if the signature is valid. Others values should be
210 * replied with a SSH_AUTH_DENIED.
211 * @param userdata Userdata to be passed to the callback function.
212 * @returns SSH_AUTH_SUCCESS Authentication is accepted.
213 * @returns SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed.
214 * @returns SSH_AUTH_DENIED Authentication failed.
215 */
216typedef int (*ssh_auth_pubkey_callback) (ssh_session session, const char *user, struct ssh_key_struct *pubkey,
217 char signature_state, void *userdata);
218
219
220/**
221 * @brief Handles an SSH service request
222 * @param session current session handler
223 * @param service name of the service (e.g. "ssh-userauth") requested
224 * @param userdata Userdata to be passed to the callback function.
225 * @returns 0 if the request is to be allowed
226 * @returns -1 if the request should not be allowed
227 */
228
229typedef int (*ssh_service_request_callback) (ssh_session session, const char *service, void *userdata);
230
231/**
232 * @brief Handles an SSH new channel open session request
233 * @param session current session handler
234 * @param userdata Userdata to be passed to the callback function.
235 * @returns a valid ssh_channel handle if the request is to be allowed
236 * @returns NULL if the request should not be allowed
237 * @warning The channel pointer returned by this callback must be closed by the application.
238 */
239typedef 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 */
252typedef 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 */
267typedef 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 */
281typedef 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
285/**
286 * This structure can be used to implement a libssh server, with appropriate callbacks.
287 */
288
289struct ssh_server_callbacks_struct {
290 /** DON'T SET THIS use ssh_callbacks_init() instead. */
291 size_t size;
292 /**
293 * User-provided data. User is free to set anything he wants here
294 */
295 void *userdata;
296 /** This function gets called when a client tries to authenticate through
297 * password method.
298 */
299 ssh_auth_password_callback auth_password_function;
300
301 /** This function gets called when a client tries to authenticate through
302 * none method.
303 */
304 ssh_auth_none_callback auth_none_function;
305
306 /** This function gets called when a client tries to authenticate through
307 * gssapi-mic method.
308 */
309 ssh_auth_gssapi_mic_callback auth_gssapi_mic_function;
310
311 /** this function gets called when a client tries to authenticate or offer
312 * a public key.
313 */
314 ssh_auth_pubkey_callback auth_pubkey_function;
315
316 /** This functions gets called when a service request is issued by the
317 * client
318 */
319 ssh_service_request_callback service_request_function;
320 /** This functions gets called when a new channel request is issued by
321 * the client
322 */
323 ssh_channel_open_request_session_callback channel_open_request_session_function;
324 /** This function will be called when a new gssapi authentication is attempted.
325 */
326 ssh_gssapi_select_oid_callback gssapi_select_oid_function;
327 /** This function will be called when a gssapi token comes in.
328 */
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};
334typedef struct ssh_server_callbacks_struct *ssh_server_callbacks;
335
336/**
337 * @brief Set the session server callback functions.
338 *
339 * This functions sets the callback structure to use your own callback
340 * functions for user authentication, new channels and requests.
341 *
342 * @code
343 * struct ssh_server_callbacks_struct cb = {
344 * .userdata = data,
345 * .auth_password_function = my_auth_function
346 * };
347 * ssh_callbacks_init(&cb);
348 * ssh_set_server_callbacks(session, &cb);
349 * @endcode
350 *
351 * @param session The session to set the callback structure.
352 *
353 * @param cb The callback structure itself.
354 *
355 * @return SSH_OK on success, SSH_ERROR on error.
356 */
357LIBSSH_API int ssh_set_server_callbacks(ssh_session session, ssh_server_callbacks cb);
358
359/**
360 * These are the callbacks exported by the socket structure
361 * They are called by the socket module when a socket event appears
362 */
363struct ssh_socket_callbacks_struct {
364 /**
365 * User-provided data. User is free to set anything he wants here
366 */
367 void *userdata;
368 /**
369 * This function will be called each time data appears on socket. The data
370 * not consumed will appear on the next data event.
371 */
372 ssh_callback_data data;
373 /** This function will be called each time a controlflow state changes, i.e.
374 * the socket is available for reading or writing.
375 */
376 ssh_callback_int controlflow;
377 /** This function will be called each time an exception appears on socket. An
378 * exception can be a socket problem (timeout, ...) or an end-of-file.
379 */
380 ssh_callback_int_int exception;
381 /** This function is called when the ssh_socket_connect was used on the socket
382 * on nonblocking state, and the connection successed.
383 */
384 ssh_callback_int_int connected;
385};
386typedef 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
398/**
399 * @brief Initializes an ssh_callbacks_struct
400 * A call to this macro is mandatory when you have set a new
401 * ssh_callback_struct structure. Its goal is to maintain the binary
402 * compatibility with future versions of libssh as the structure
403 * evolves with time.
404 */
405#define ssh_callbacks_init(p) do {\
406 (p)->size=sizeof(*(p)); \
407} while(0);
408
409/**
410 * @internal
411 * @brief tests if a callback can be called without crash
412 * verifies that the struct size if big enough
413 * verifies that the callback pointer exists
414 * @param p callback pointer
415 * @param c callback name
416 * @returns nonzero if callback can be called
417 */
418#define ssh_callbacks_exists(p,c) (\
419 (p != NULL) && ( (char *)&((p)-> c) < (char *)(p) + (p)->size ) && \
420 ((p)-> c != NULL) \
421 )
422
423/** @brief Prototype for a packet callback, to be called when a new packet arrives
424 * @param session The current session of the packet
425 * @param type packet type (see ssh2.h)
426 * @param packet buffer containing the packet, excluding size, type and padding fields
427 * @param user user argument to the callback
428 * and are called each time a packet shows up
429 * @returns SSH_PACKET_USED Packet was parsed and used
430 * @returns SSH_PACKET_NOT_USED Packet was not used or understood, processing must continue
431 */
432typedef int (*ssh_packet_callback) (ssh_session session, uint8_t type, ssh_buffer packet, void *user);
433
434/** return values for a ssh_packet_callback */
435/** Packet was used and should not be parsed by another callback */
436#define SSH_PACKET_USED 1
437/** Packet was not used and should be passed to any other callback
438 * available */
439#define SSH_PACKET_NOT_USED 2
440
441
442/** @brief This macro declares a packet callback handler
443 * @code
444 * SSH_PACKET_CALLBACK(mycallback){
445 * ...
446 * }
447 * @endcode
448 */
449#define SSH_PACKET_CALLBACK(name) \
450 int name (ssh_session session, uint8_t type, ssh_buffer packet, void *user)
451
452struct ssh_packet_callbacks_struct {
453 /** Index of the first packet type being handled */
454 uint8_t start;
455 /** Number of packets being handled by this callback struct */
456 uint8_t n_callbacks;
457 /** A pointer to n_callbacks packet callbacks */
458 ssh_packet_callback *callbacks;
459 /**
460 * User-provided data. User is free to set anything he wants here
461 */
462 void *user;
463};
464
465typedef struct ssh_packet_callbacks_struct *ssh_packet_callbacks;
466
467/**
468 * @brief Set the session callback functions.
469 *
470 * This functions sets the callback structure to use your own callback
471 * functions for auth, logging and status.
472 *
473 * @code
474 * struct ssh_callbacks_struct cb = {
475 * .userdata = data,
476 * .auth_function = my_auth_function
477 * };
478 * ssh_callbacks_init(&cb);
479 * ssh_set_callbacks(session, &cb);
480 * @endcode
481 *
482 * @param session The session to set the callback structure.
483 *
484 * @param cb The callback structure itself.
485 *
486 * @return SSH_OK on success, SSH_ERROR on error.
487 */
488LIBSSH_API int ssh_set_callbacks(ssh_session session, ssh_callbacks cb);
489
490/**
491 * @brief SSH channel data callback. Called when data is available on a channel
492 * @param session Current session handler
493 * @param channel the actual channel
494 * @param data the data that has been read on the channel
495 * @param len the length of the data
496 * @param is_stderr is 0 for stdout or 1 for stderr
497 * @param userdata Userdata to be passed to the callback function.
498 * @returns number of bytes processed by the callee. The remaining bytes will
499 * be sent in the next callback message, when more data is available.
500 */
501typedef 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
508/**
509 * @brief SSH channel eof callback. Called when a channel receives EOF
510 * @param session Current session handler
511 * @param channel the actual channel
512 * @param userdata Userdata to be passed to the callback function.
513 */
514typedef void (*ssh_channel_eof_callback) (ssh_session session,
515 ssh_channel channel,
516 void *userdata);
517
518/**
519 * @brief SSH channel close callback. Called when a channel is closed by remote peer
520 * @param session Current session handler
521 * @param channel the actual channel
522 * @param userdata Userdata to be passed to the callback function.
523 */
524typedef void (*ssh_channel_close_callback) (ssh_session session,
525 ssh_channel channel,
526 void *userdata);
527
528/**
529 * @brief SSH channel signal callback. Called when a channel has received a signal
530 * @param session Current session handler
531 * @param channel the actual channel
532 * @param signal the signal name (without the SIG prefix)
533 * @param userdata Userdata to be passed to the callback function.
534 */
535typedef void (*ssh_channel_signal_callback) (ssh_session session,
536 ssh_channel channel,
537 const char *signal,
538 void *userdata);
539
540/**
541 * @brief SSH channel exit status callback. Called when a channel has received an exit status
542 * @param session Current session handler
543 * @param channel the actual channel
544 * @param userdata Userdata to be passed to the callback function.
545 */
546typedef void (*ssh_channel_exit_status_callback) (ssh_session session,
547 ssh_channel channel,
548 int exit_status,
549 void *userdata);
550
551/**
552 * @brief SSH channel exit signal callback. Called when a channel has received an exit signal
553 * @param session Current session handler
554 * @param channel the actual channel
555 * @param signal the signal name (without the SIG prefix)
556 * @param core a boolean telling wether a core has been dumped or not
557 * @param errmsg the description of the exception
558 * @param lang the language of the description (format: RFC 3066)
559 * @param userdata Userdata to be passed to the callback function.
560 */
561typedef 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
569/**
570 * @brief SSH channel PTY request from a client.
571 * @param channel the channel
572 * @param term The type of terminal emulation
573 * @param width width of the terminal, in characters
574 * @param height height of the terminal, in characters
575 * @param pxwidth width of the terminal, in pixels
576 * @param pxheight height of the terminal, in pixels
577 * @param userdata Userdata to be passed to the callback function.
578 * @returns 0 if the pty request is accepted
579 * @returns -1 if the request is denied
580 */
581typedef 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
588/**
589 * @brief SSH channel Shell request from a client.
590 * @param channel the channel
591 * @param userdata Userdata to be passed to the callback function.
592 * @returns 0 if the shell request is accepted
593 * @returns 1 if the request is denied
594 */
595typedef int (*ssh_channel_shell_request_callback) (ssh_session session,
596 ssh_channel channel,
597 void *userdata);
598/**
599 * @brief SSH auth-agent-request from the client. This request is
600 * sent by a client when agent forwarding is available.
601 * Server is free to ignore this callback, no answer is expected.
602 * @param channel the channel
603 * @param userdata Userdata to be passed to the callback function.
604 */
605typedef void (*ssh_channel_auth_agent_req_callback) (ssh_session session,
606 ssh_channel channel,
607 void *userdata);
608
609/**
610 * @brief SSH X11 request from the client. This request is
611 * sent by a client when X11 forwarding is requested(and available).
612 * Server is free to ignore this callback, no answer is expected.
613 * @param channel the channel
614 * @param userdata Userdata to be passed to the callback function.
615 */
616typedef 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);
623/**
624 * @brief SSH channel PTY windows change (terminal size) from a client.
625 * @param channel the channel
626 * @param width width of the terminal, in characters
627 * @param height height of the terminal, in characters
628 * @param pxwidth width of the terminal, in pixels
629 * @param pxheight height of the terminal, in pixels
630 * @param userdata Userdata to be passed to the callback function.
631 * @returns 0 if the pty request is accepted
632 * @returns -1 if the request is denied
633 */
634typedef 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
640/**
641 * @brief SSH channel Exec request from a client.
642 * @param channel the channel
643 * @param command the shell command to be executed
644 * @param userdata Userdata to be passed to the callback function.
645 * @returns 0 if the exec request is accepted
646 * @returns 1 if the request is denied
647 */
648typedef int (*ssh_channel_exec_request_callback) (ssh_session session,
649 ssh_channel channel,
650 const char *command,
651 void *userdata);
652
653/**
654 * @brief SSH channel environment request from a client.
655 * @param channel the channel
656 * @param env_name name of the environment value to be set
657 * @param env_value value of the environment value to be set
658 * @param userdata Userdata to be passed to the callback function.
659 * @returns 0 if the env request is accepted
660 * @returns 1 if the request is denied
661 * @warning some environment variables can be dangerous if changed (e.g.
662 * LD_PRELOAD) and should not be fulfilled.
663 */
664typedef 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);
669/**
670 * @brief SSH channel subsystem request from a client.
671 * @param channel the channel
672 * @param subsystem the subsystem required
673 * @param userdata Userdata to be passed to the callback function.
674 * @returns 0 if the subsystem request is accepted
675 * @returns 1 if the request is denied
676 */
677typedef int (*ssh_channel_subsystem_request_callback) (ssh_session session,
678 ssh_channel channel,
679 const char *subsystem,
680 void *userdata);
681
682
683struct ssh_channel_callbacks_struct {
684 /** DON'T SET THIS use ssh_callbacks_init() instead. */
685 size_t size;
686 /**
687 * User-provided data. User is free to set anything he wants here
688 */
689 void *userdata;
690 /**
691 * This functions will be called when there is data available.
692 */
693 ssh_channel_data_callback channel_data_function;
694 /**
695 * This functions will be called when the channel has received an EOF.
696 */
697 ssh_channel_eof_callback channel_eof_function;
698 /**
699 * This functions will be called when the channel has been closed by remote
700 */
701 ssh_channel_close_callback channel_close_function;
702 /**
703 * This functions will be called when a signal has been received
704 */
705 ssh_channel_signal_callback channel_signal_function;
706 /**
707 * This functions will be called when an exit status has been received
708 */
709 ssh_channel_exit_status_callback channel_exit_status_function;
710 /**
711 * This functions will be called when an exit signal has been received
712 */
713 ssh_channel_exit_signal_callback channel_exit_signal_function;
714 /**
715 * This function will be called when a client requests a PTY
716 */
717 ssh_channel_pty_request_callback channel_pty_request_function;
718 /**
719 * This function will be called when a client requests a shell
720 */
721 ssh_channel_shell_request_callback channel_shell_request_function;
722 /** This function will be called when a client requests agent
723 * authentication forwarding.
724 */
725 ssh_channel_auth_agent_req_callback channel_auth_agent_req_function;
726 /** This function will be called when a client requests X11
727 * forwarding.
728 */
729 ssh_channel_x11_req_callback channel_x11_req_function;
730 /** This function will be called when a client requests a
731 * window change.
732 */
733 ssh_channel_pty_window_change_callback channel_pty_window_change_function;
734 /** This function will be called when a client requests a
735 * command execution.
736 */
737 ssh_channel_exec_request_callback channel_exec_request_function;
738 /** This function will be called when a client requests an environment
739 * variable to be set.
740 */
741 ssh_channel_env_request_callback channel_env_request_function;
742 /** This function will be called when a client requests a subsystem
743 * (like sftp).
744 */
745 ssh_channel_subsystem_request_callback channel_subsystem_request_function;
746};
747
748typedef struct ssh_channel_callbacks_struct *ssh_channel_callbacks;
749
750/**
751 * @brief Set the channel callback functions.
752 *
753 * This functions sets the callback structure to use your own callback
754 * functions for channel data and exceptions
755 *
756 * @code
757 * struct ssh_channel_callbacks_struct cb = {
758 * .userdata = data,
759 * .channel_data = my_channel_data_function
760 * };
761 * ssh_callbacks_init(&cb);
762 * ssh_set_channel_callbacks(channel, &cb);
763 * @endcode
764 *
765 * @param channel The channel to set the callback structure.
766 *
767 * @param cb The callback structure itself.
768 *
769 * @return SSH_OK on success, SSH_ERROR on error.
770 */
771LIBSSH_API int ssh_set_channel_callbacks(ssh_channel channel,
772 ssh_channel_callbacks cb);
773
774/** @} */
775
776/** @group libssh_threads
777 * @{
778 */
779
780typedef int (*ssh_thread_callback) (void **lock);
781
782typedef unsigned long (*ssh_thread_id_callback) (void);
783struct 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
792/**
793 * @brief Set the thread callbacks structure.
794 *
795 * This is necessary if your program is using libssh in a multithreaded fashion.
796 * This function must be called first, outside of any threading context (in your
797 * main() function for instance), before you call ssh_init().
798 *
799 * @param[in] cb A pointer to a ssh_threads_callbacks_struct structure, which
800 * contains the different callbacks to be set.
801 *
802 * @returns Always returns SSH_OK.
803 *
804 * @see ssh_threads_callbacks_struct
805 * @see SSH_THREADS_PTHREAD
806 * @bug libgcrypt 1.6 and bigger backend does not support custom callback.
807 * Using anything else than pthreads here will fail.
808 */
809LIBSSH_API int ssh_threads_set_callbacks(struct ssh_threads_callbacks_struct
810 *cb);
811
812/**
813 * @brief returns a pointer on the pthread threads callbacks, to be used with
814 * ssh_threads_set_callbacks.
815 * @warning you have to link with the library ssh_threads.
816 * @see ssh_threads_set_callbacks
817 */
818LIBSSH_API struct ssh_threads_callbacks_struct *ssh_threads_get_pthread(void);
819
820/**
821 * @brief Get the noop threads callbacks structure
822 *
823 * This can be used with ssh_threads_set_callbacks. These callbacks do nothing
824 * and are being used by default.
825 *
826 * @return Always returns a valid pointer to the noop callbacks structure.
827 *
828 * @see ssh_threads_set_callbacks
829 */
830LIBSSH_API struct ssh_threads_callbacks_struct *ssh_threads_get_noop(void);
831
832/**
833 * @brief Set the logging callback function.
834 *
835 * @param[in] cb The callback to set.
836 *
837 * @return 0 on success, < 0 on errror.
838 */
839LIBSSH_API int ssh_set_log_callback(ssh_logging_callback cb);
840
841/**
842 * @brief Get the pointer to the logging callback function.
843 *
844 * @return The pointer the the callback or NULL if none set.
845 */
846LIBSSH_API ssh_logging_callback ssh_get_log_callback(void);
847
848/** @} */
849#ifdef __cplusplus
850}
851#endif
852
853#endif /*_SSH_CALLBACK_H */
854
855/* @} */
856