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 | |
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 | */ |
49 | typedef 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 | */ |
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 | |
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 | */ |
74 | typedef 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 | */ |
90 | typedef 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 | */ |
102 | typedef 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 | */ |
112 | typedef 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 | */ |
124 | typedef 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 | */ |
130 | struct 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 | }; |
158 | typedef 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 | */ |
173 | typedef 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 | */ |
186 | typedef 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 | */ |
200 | typedef 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 | */ |
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 | |
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 | |
229 | typedef 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 | */ |
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 | |
285 | /** |
286 | * This structure can be used to implement a libssh server, with appropriate callbacks. |
287 | */ |
288 | |
289 | struct 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 | }; |
334 | typedef 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 | */ |
357 | LIBSSH_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 | */ |
363 | struct 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 | }; |
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 | |
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 | */ |
432 | typedef 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 | |
452 | struct 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 | |
465 | typedef 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 | */ |
488 | LIBSSH_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 | */ |
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 | |
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 | */ |
514 | typedef 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 | */ |
524 | typedef 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 | */ |
535 | typedef 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 | */ |
546 | typedef 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 | */ |
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 | |
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 | */ |
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 | |
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 | */ |
595 | typedef 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 | */ |
605 | typedef 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 | */ |
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); |
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 | */ |
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 | |
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 | */ |
648 | typedef 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 | */ |
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); |
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 | */ |
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 { |
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 | |
748 | typedef 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 | */ |
771 | LIBSSH_API int ssh_set_channel_callbacks(ssh_channel channel, |
772 | ssh_channel_callbacks cb); |
773 | |
774 | /** @} */ |
775 | |
776 | /** @group libssh_threads |
777 | * @{ |
778 | */ |
779 | |
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 | |
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 | */ |
809 | LIBSSH_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 | */ |
818 | LIBSSH_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 | */ |
830 | LIBSSH_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 | */ |
839 | LIBSSH_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 | */ |
846 | LIBSSH_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 | |