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 * @brief Handles an SSH new channel open "auth-agent" request. This happens when the server 129 * sends back an "auth-agent" connection attempt. This is a client-side API 130 * @param session current session handler 131 * @param userdata Userdata to be passed to the callback function. 132 * @returns a valid ssh_channel handle if the request is to be allowed 133 * @returns NULL if the request should not be allowed 134 * @warning The channel pointer returned by this callback must be closed by the application. 135 */ 136 typedef ssh_channel (*ssh_channel_open_request_auth_agent_callback) (ssh_session session, 137 void *userdata); 138 139 /** 140 * The structure to replace libssh functions with appropriate callbacks. 141 */ 142 struct ssh_callbacks_struct { 143 /** DON'T SET THIS use ssh_callbacks_init() instead. */ 144 size_t size; 145 /** 146 * User-provided data. User is free to set anything he wants here 147 */ 148 void *userdata; 149 /** 150 * This functions will be called if e.g. a keyphrase is needed. 151 */ 152 ssh_auth_callback auth_function; 153 /** 154 * This function will be called each time a loggable event happens. 155 */ 156 ssh_log_callback log_function; 157 /** 158 * This function gets called during connection time to indicate the 159 * percentage of connection steps completed. 160 */ 161 void (*connect_status_function)(void *userdata, float status); 162 /** 163 * This function will be called each time a global request is received. 164 */ 165 ssh_global_request_callback global_request_function; 166 /** This function will be called when an incoming X11 request is received. 167 */ 168 ssh_channel_open_request_x11_callback channel_open_request_x11_function; 169 /** This function will be called when an incoming "auth-agent" request is received. 170 */ 171 ssh_channel_open_request_auth_agent_callback channel_open_request_auth_agent_function; 172 }; 173 typedef struct ssh_callbacks_struct *ssh_callbacks; 174 175 /** These are callbacks used specifically in SSH servers. 176 */ 177 178 /** 179 * @brief SSH authentication callback. 180 * @param session Current session handler 181 * @param user User that wants to authenticate 182 * @param password Password used for authentication 183 * @param userdata Userdata to be passed to the callback function. 184 * @returns SSH_AUTH_SUCCESS Authentication is accepted. 185 * @returns SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed. 186 * @returns SSH_AUTH_DENIED Authentication failed. 187 */ 188 typedef int (*ssh_auth_password_callback) (ssh_session session, const char *user, const char *password, 189 void *userdata); 190 191 /** 192 * @brief SSH authentication callback. Tries to authenticates user with the "none" method 193 * which is anonymous or passwordless. 194 * @param session Current session handler 195 * @param user User that wants to authenticate 196 * @param userdata Userdata to be passed to the callback function. 197 * @returns SSH_AUTH_SUCCESS Authentication is accepted. 198 * @returns SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed. 199 * @returns SSH_AUTH_DENIED Authentication failed. 200 */ 201 typedef int (*ssh_auth_none_callback) (ssh_session session, const char *user, void *userdata); 202 203 /** 204 * @brief SSH authentication callback. Tries to authenticates user with the "gssapi-with-mic" method 205 * @param session Current session handler 206 * @param user Username of the user (can be spoofed) 207 * @param principal Authenticated principal of the user, including realm. 208 * @param userdata Userdata to be passed to the callback function. 209 * @returns SSH_AUTH_SUCCESS Authentication is accepted. 210 * @returns SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed. 211 * @returns SSH_AUTH_DENIED Authentication failed. 212 * @warning Implementations should verify that parameter user matches in some way the principal. 213 * user and principal can be different. Only the latter is guaranteed to be safe. 214 */ 215 typedef int (*ssh_auth_gssapi_mic_callback) (ssh_session session, const char *user, const char *principal, 216 void *userdata); 217 218 /** 219 * @brief SSH authentication callback. 220 * @param session Current session handler 221 * @param user User that wants to authenticate 222 * @param pubkey public key used for authentication 223 * @param signature_state SSH_PUBLICKEY_STATE_NONE if the key is not signed (simple public key probe), 224 * SSH_PUBLICKEY_STATE_VALID if the signature is valid. Others values should be 225 * replied with a SSH_AUTH_DENIED. 226 * @param userdata Userdata to be passed to the callback function. 227 * @returns SSH_AUTH_SUCCESS Authentication is accepted. 228 * @returns SSH_AUTH_PARTIAL Partial authentication, more authentication means are needed. 229 * @returns SSH_AUTH_DENIED Authentication failed. 230 */ 231 typedef int (*ssh_auth_pubkey_callback) (ssh_session session, const char *user, struct ssh_key_struct *pubkey, 232 char signature_state, void *userdata); 233 234 235 /** 236 * @brief Handles an SSH service request 237 * @param session current session handler 238 * @param service name of the service (e.g. "ssh-userauth") requested 239 * @param userdata Userdata to be passed to the callback function. 240 * @returns 0 if the request is to be allowed 241 * @returns -1 if the request should not be allowed 242 */ 243 244 typedef int (*ssh_service_request_callback) (ssh_session session, const char *service, void *userdata); 245 246 /** 247 * @brief Handles an SSH new channel open session request 248 * @param session current session handler 249 * @param userdata Userdata to be passed to the callback function. 250 * @returns a valid ssh_channel handle if the request is to be allowed 251 * @returns NULL if the request should not be allowed 252 * @warning The channel pointer returned by this callback must be closed by the application. 253 */ 254 typedef ssh_channel (*ssh_channel_open_request_session_callback) (ssh_session session, void *userdata); 255 256 /* 257 * @brief handle the beginning of a GSSAPI authentication, server side. 258 * @param session current session handler 259 * @param user the username of the client 260 * @param n_oid number of available oids 261 * @param oids OIDs provided by the client 262 * @returns an ssh_string containing the chosen OID, that's supported by both 263 * client and server. 264 * @warning It is not necessary to fill this callback in if libssh is linked 265 * with libgssapi. 266 */ 267 typedef ssh_string (*ssh_gssapi_select_oid_callback) (ssh_session session, const char *user, 268 int n_oid, ssh_string *oids, void *userdata); 269 270 /* 271 * @brief handle the negociation of a security context, server side. 272 * @param session current session handler 273 * @param[in] input_token input token provided by client 274 * @param[out] output_token output of the gssapi accept_sec_context method, 275 * NULL after completion. 276 * @returns SSH_OK if the token was generated correctly or accept_sec_context 277 * returned GSS_S_COMPLETE 278 * @returns SSH_ERROR in case of error 279 * @warning It is not necessary to fill this callback in if libssh is linked 280 * with libgssapi. 281 */ 282 typedef int (*ssh_gssapi_accept_sec_ctx_callback) (ssh_session session, 283 ssh_string input_token, ssh_string *output_token, void *userdata); 284 285 /* 286 * @brief Verify and authenticates a MIC, server side. 287 * @param session current session handler 288 * @param[in] mic input mic to be verified provided by client 289 * @param[in] mic_buffer buffer of data to be signed. 290 * @param[in] mic_buffer_size size of mic_buffer 291 * @returns SSH_OK if the MIC was authenticated correctly 292 * @returns SSH_ERROR in case of error 293 * @warning It is not necessary to fill this callback in if libssh is linked 294 * with libgssapi. 295 */ 296 typedef int (*ssh_gssapi_verify_mic_callback) (ssh_session session, 297 ssh_string mic, void *mic_buffer, size_t mic_buffer_size, void *userdata); 298 299 300 /** 301 * This structure can be used to implement a libssh server, with appropriate callbacks. 302 */ 303 304 struct ssh_server_callbacks_struct { 305 /** DON'T SET THIS use ssh_callbacks_init() instead. */ 306 size_t size; 307 /** 308 * User-provided data. User is free to set anything he wants here 309 */ 310 void *userdata; 311 /** This function gets called when a client tries to authenticate through 312 * password method. 313 */ 314 ssh_auth_password_callback auth_password_function; 315 316 /** This function gets called when a client tries to authenticate through 317 * none method. 318 */ 319 ssh_auth_none_callback auth_none_function; 320 321 /** This function gets called when a client tries to authenticate through 322 * gssapi-mic method. 323 */ 324 ssh_auth_gssapi_mic_callback auth_gssapi_mic_function; 325 326 /** this function gets called when a client tries to authenticate or offer 327 * a public key. 328 */ 329 ssh_auth_pubkey_callback auth_pubkey_function; 330 331 /** This functions gets called when a service request is issued by the 332 * client 333 */ 334 ssh_service_request_callback service_request_function; 335 /** This functions gets called when a new channel request is issued by 336 * the client 337 */ 338 ssh_channel_open_request_session_callback channel_open_request_session_function; 339 /** This function will be called when a new gssapi authentication is attempted. 340 */ 341 ssh_gssapi_select_oid_callback gssapi_select_oid_function; 342 /** This function will be called when a gssapi token comes in. 343 */ 344 ssh_gssapi_accept_sec_ctx_callback gssapi_accept_sec_ctx_function; 345 /* This function will be called when a MIC needs to be verified. 346 */ 347 ssh_gssapi_verify_mic_callback gssapi_verify_mic_function; 348 }; 349 typedef struct ssh_server_callbacks_struct *ssh_server_callbacks; 350 351 /** 352 * @brief Set the session server callback functions. 353 * 354 * This functions sets the callback structure to use your own callback 355 * functions for user authentication, new channels and requests. 356 * 357 * @code 358 * struct ssh_server_callbacks_struct cb = { 359 * .userdata = data, 360 * .auth_password_function = my_auth_function 361 * }; 362 * ssh_callbacks_init(&cb); 363 * ssh_set_server_callbacks(session, &cb); 364 * @endcode 365 * 366 * @param session The session to set the callback structure. 367 * 368 * @param cb The callback structure itself. 369 * 370 * @return SSH_OK on success, SSH_ERROR on error. 371 */ 372 LIBSSH_API int ssh_set_server_callbacks(ssh_session session, ssh_server_callbacks cb); 373 374 /** 375 * These are the callbacks exported by the socket structure 376 * They are called by the socket module when a socket event appears 377 */ 378 struct ssh_socket_callbacks_struct { 379 /** 380 * User-provided data. User is free to set anything he wants here 381 */ 382 void *userdata; 383 /** 384 * This function will be called each time data appears on socket. The data 385 * not consumed will appear on the next data event. 386 */ 387 ssh_callback_data data; 388 /** This function will be called each time a controlflow state changes, i.e. 389 * the socket is available for reading or writing. 390 */ 391 ssh_callback_int controlflow; 392 /** This function will be called each time an exception appears on socket. An 393 * exception can be a socket problem (timeout, ...) or an end-of-file. 394 */ 395 ssh_callback_int_int exception; 396 /** This function is called when the ssh_socket_connect was used on the socket 397 * on nonblocking state, and the connection successed. 398 */ 399 ssh_callback_int_int connected; 400 }; 401 typedef struct ssh_socket_callbacks_struct *ssh_socket_callbacks; 402 403 #define SSH_SOCKET_FLOW_WRITEWILLBLOCK 1 404 #define SSH_SOCKET_FLOW_WRITEWONTBLOCK 2 405 406 #define SSH_SOCKET_EXCEPTION_EOF 1 407 #define SSH_SOCKET_EXCEPTION_ERROR 2 408 409 #define SSH_SOCKET_CONNECTED_OK 1 410 #define SSH_SOCKET_CONNECTED_ERROR 2 411 #define SSH_SOCKET_CONNECTED_TIMEOUT 3 412 413 /** 414 * @brief Initializes an ssh_callbacks_struct 415 * A call to this macro is mandatory when you have set a new 416 * ssh_callback_struct structure. Its goal is to maintain the binary 417 * compatibility with future versions of libssh as the structure 418 * evolves with time. 419 */ 420 #define ssh_callbacks_init(p) do {\ 421 (p)->size=sizeof(*(p)); \ 422 } while(0); 423 424 /** 425 * @internal 426 * @brief tests if a callback can be called without crash 427 * verifies that the struct size if big enough 428 * verifies that the callback pointer exists 429 * @param p callback pointer 430 * @param c callback name 431 * @returns nonzero if callback can be called 432 */ 433 #define ssh_callbacks_exists(p,c) (\ 434 (p != NULL) && ( (char *)&((p)-> c) < (char *)(p) + (p)->size ) && \ 435 ((p)-> c != NULL) \ 436 ) 437 438 /** 439 * @internal 440 * 441 * @brief Iterate through a list of callback structures 442 * 443 * This tests for their validity and executes them. The userdata argument is 444 * automatically passed through. 445 * 446 * @param list list of callbacks 447 * 448 * @param cbtype type of the callback 449 * 450 * @param c callback name 451 * 452 * @param va_args parameters to be passed 453 */ 454 #define ssh_callbacks_execute_list(list, cbtype, c, ...) \ 455 do { \ 456 struct ssh_iterator *i = ssh_list_get_iterator(list); \ 457 cbtype cb; \ 458 while (i != NULL){ \ 459 cb = ssh_iterator_value(cbtype, i); \ 460 if (ssh_callbacks_exists(cb, c)) \ 461 cb-> c (__VA_ARGS__, cb->userdata); \ 462 i = i->next; \ 463 } \ 464 } while(0) 465 466 /** 467 * @internal 468 * 469 * @brief iterate through a list of callback structures. 470 * 471 * This tests for their validity and give control back to the calling code to 472 * execute them. Caller can decide to break the loop or continue executing the 473 * callbacks with different parameters 474 * 475 * @code 476 * ssh_callbacks_iterate(channel->callbacks, ssh_channel_callbacks, 477 * channel_eof_function){ 478 * rc = ssh_callbacks_iterate_exec(session, channel); 479 * if (rc != SSH_OK){ 480 * break; 481 * } 482 * } 483 * ssh_callbacks_iterate_end(); 484 * @endcode 485 */ 486 #define ssh_callbacks_iterate(_cb_list, _cb_type, _cb_name) \ 487 do { \ 488 struct ssh_iterator *_cb_i = ssh_list_get_iterator(_cb_list); \ 489 _cb_type _cb; \ 490 for (; _cb_i != NULL; _cb_i = _cb_i->next) { \ 491 _cb = ssh_iterator_value(_cb_type, _cb_i); \ 492 if (ssh_callbacks_exists(_cb, _cb_name)) 493 494 #define ssh_callbacks_iterate_exec(_cb_name, ...) \ 495 _cb->_cb_name(__VA_ARGS__, _cb->userdata) 496 497 #define ssh_callbacks_iterate_end() \ 498 } \ 499 } while(0) 500 501 /** @brief Prototype for a packet callback, to be called when a new packet arrives 502 * @param session The current session of the packet 503 * @param type packet type (see ssh2.h) 504 * @param packet buffer containing the packet, excluding size, type and padding fields 505 * @param user user argument to the callback 506 * and are called each time a packet shows up 507 * @returns SSH_PACKET_USED Packet was parsed and used 508 * @returns SSH_PACKET_NOT_USED Packet was not used or understood, processing must continue 509 */ 510 typedef int (*ssh_packet_callback) (ssh_session session, uint8_t type, ssh_buffer packet, void *user); 511 512 /** return values for a ssh_packet_callback */ 513 /** Packet was used and should not be parsed by another callback */ 514 #define SSH_PACKET_USED 1 515 /** Packet was not used and should be passed to any other callback 516 * available */ 517 #define SSH_PACKET_NOT_USED 2 518 519 520 /** @brief This macro declares a packet callback handler 521 * @code 522 * SSH_PACKET_CALLBACK(mycallback){ 523 * ... 524 * } 525 * @endcode 526 */ 527 #define SSH_PACKET_CALLBACK(name) \ 528 int name (ssh_session session, uint8_t type, ssh_buffer packet, void *user) 529 530 struct ssh_packet_callbacks_struct { 531 /** Index of the first packet type being handled */ 532 uint8_t start; 533 /** Number of packets being handled by this callback struct */ 534 uint8_t n_callbacks; 535 /** A pointer to n_callbacks packet callbacks */ 536 ssh_packet_callback *callbacks; 537 /** 538 * User-provided data. User is free to set anything he wants here 539 */ 540 void *user; 541 }; 542 543 typedef struct ssh_packet_callbacks_struct *ssh_packet_callbacks; 544 545 /** 546 * @brief Set the session callback functions. 547 * 548 * This functions sets the callback structure to use your own callback 549 * functions for auth, logging and status. 550 * 551 * @code 552 * struct ssh_callbacks_struct cb = { 553 * .userdata = data, 554 * .auth_function = my_auth_function 555 * }; 556 * ssh_callbacks_init(&cb); 557 * ssh_set_callbacks(session, &cb); 558 * @endcode 559 * 560 * @param session The session to set the callback structure. 561 * 562 * @param cb The callback structure itself. 563 * 564 * @return SSH_OK on success, SSH_ERROR on error. 565 */ 566 LIBSSH_API int ssh_set_callbacks(ssh_session session, ssh_callbacks cb); 567 568 /** 569 * @brief SSH channel data callback. Called when data is available on a channel 570 * @param session Current session handler 571 * @param channel the actual channel 572 * @param data the data that has been read on the channel 573 * @param len the length of the data 574 * @param is_stderr is 0 for stdout or 1 for stderr 575 * @param userdata Userdata to be passed to the callback function. 576 * @returns number of bytes processed by the callee. The remaining bytes will 577 * be sent in the next callback message, when more data is available. 578 */ 579 typedef int (*ssh_channel_data_callback) (ssh_session session, 580 ssh_channel channel, 581 void *data, 582 uint32_t len, 583 int is_stderr, 584 void *userdata); 585 586 /** 587 * @brief SSH channel eof callback. Called when a channel receives EOF 588 * @param session Current session handler 589 * @param channel the actual channel 590 * @param userdata Userdata to be passed to the callback function. 591 */ 592 typedef void (*ssh_channel_eof_callback) (ssh_session session, 593 ssh_channel channel, 594 void *userdata); 595 596 /** 597 * @brief SSH channel close callback. Called when a channel is closed by remote peer 598 * @param session Current session handler 599 * @param channel the actual channel 600 * @param userdata Userdata to be passed to the callback function. 601 */ 602 typedef void (*ssh_channel_close_callback) (ssh_session session, 603 ssh_channel channel, 604 void *userdata); 605 606 /** 607 * @brief SSH channel signal callback. Called when a channel has received a signal 608 * @param session Current session handler 609 * @param channel the actual channel 610 * @param signal the signal name (without the SIG prefix) 611 * @param userdata Userdata to be passed to the callback function. 612 */ 613 typedef void (*ssh_channel_signal_callback) (ssh_session session, 614 ssh_channel channel, 615 const char *signal, 616 void *userdata); 617 618 /** 619 * @brief SSH channel exit status callback. Called when a channel has received an exit status 620 * @param session Current session handler 621 * @param channel the actual channel 622 * @param userdata Userdata to be passed to the callback function. 623 */ 624 typedef void (*ssh_channel_exit_status_callback) (ssh_session session, 625 ssh_channel channel, 626 int exit_status, 627 void *userdata); 628 629 /** 630 * @brief SSH channel exit signal callback. Called when a channel has received an exit signal 631 * @param session Current session handler 632 * @param channel the actual channel 633 * @param signal the signal name (without the SIG prefix) 634 * @param core a boolean telling wether a core has been dumped or not 635 * @param errmsg the description of the exception 636 * @param lang the language of the description (format: RFC 3066) 637 * @param userdata Userdata to be passed to the callback function. 638 */ 639 typedef void (*ssh_channel_exit_signal_callback) (ssh_session session, 640 ssh_channel channel, 641 const char *signal, 642 int core, 643 const char *errmsg, 644 const char *lang, 645 void *userdata); 646 647 /** 648 * @brief SSH channel PTY request from a client. 649 * @param channel the channel 650 * @param term The type of terminal emulation 651 * @param width width of the terminal, in characters 652 * @param height height of the terminal, in characters 653 * @param pxwidth width of the terminal, in pixels 654 * @param pxheight height of the terminal, in pixels 655 * @param userdata Userdata to be passed to the callback function. 656 * @returns 0 if the pty request is accepted 657 * @returns -1 if the request is denied 658 */ 659 typedef int (*ssh_channel_pty_request_callback) (ssh_session session, 660 ssh_channel channel, 661 const char *term, 662 int width, int height, 663 int pxwidth, int pwheight, 664 void *userdata); 665 666 /** 667 * @brief SSH channel Shell request from a client. 668 * @param channel the channel 669 * @param userdata Userdata to be passed to the callback function. 670 * @returns 0 if the shell request is accepted 671 * @returns 1 if the request is denied 672 */ 673 typedef int (*ssh_channel_shell_request_callback) (ssh_session session, 674 ssh_channel channel, 675 void *userdata); 676 /** 677 * @brief SSH auth-agent-request from the client. This request is 678 * sent by a client when agent forwarding is available. 679 * Server is free to ignore this callback, no answer is expected. 680 * @param channel the channel 681 * @param userdata Userdata to be passed to the callback function. 682 */ 683 typedef void (*ssh_channel_auth_agent_req_callback) (ssh_session session, 684 ssh_channel channel, 685 void *userdata); 686 687 /** 688 * @brief SSH X11 request from the client. This request is 689 * sent by a client when X11 forwarding is requested(and available). 690 * Server is free to ignore this callback, no answer is expected. 691 * @param channel the channel 692 * @param userdata Userdata to be passed to the callback function. 693 */ 694 typedef void (*ssh_channel_x11_req_callback) (ssh_session session, 695 ssh_channel channel, 696 int single_connection, 697 const char *auth_protocol, 698 const char *auth_cookie, 699 uint32_t screen_number, 700 void *userdata); 701 /** 702 * @brief SSH channel PTY windows change (terminal size) from a client. 703 * @param channel the channel 704 * @param width width of the terminal, in characters 705 * @param height height of the terminal, in characters 706 * @param pxwidth width of the terminal, in pixels 707 * @param pxheight height of the terminal, in pixels 708 * @param userdata Userdata to be passed to the callback function. 709 * @returns 0 if the pty request is accepted 710 * @returns -1 if the request is denied 711 */ 712 typedef int (*ssh_channel_pty_window_change_callback) (ssh_session session, 713 ssh_channel channel, 714 int width, int height, 715 int pxwidth, int pwheight, 716 void *userdata); 717 718 /** 719 * @brief SSH channel Exec request from a client. 720 * @param channel the channel 721 * @param command the shell command to be executed 722 * @param userdata Userdata to be passed to the callback function. 723 * @returns 0 if the exec request is accepted 724 * @returns 1 if the request is denied 725 */ 726 typedef int (*ssh_channel_exec_request_callback) (ssh_session session, 727 ssh_channel channel, 728 const char *command, 729 void *userdata); 730 731 /** 732 * @brief SSH channel environment request from a client. 733 * @param channel the channel 734 * @param env_name name of the environment value to be set 735 * @param env_value value of the environment value to be set 736 * @param userdata Userdata to be passed to the callback function. 737 * @returns 0 if the env request is accepted 738 * @returns 1 if the request is denied 739 * @warning some environment variables can be dangerous if changed (e.g. 740 * LD_PRELOAD) and should not be fulfilled. 741 */ 742 typedef int (*ssh_channel_env_request_callback) (ssh_session session, 743 ssh_channel channel, 744 const char *env_name, 745 const char *env_value, 746 void *userdata); 747 /** 748 * @brief SSH channel subsystem request from a client. 749 * @param channel the channel 750 * @param subsystem the subsystem required 751 * @param userdata Userdata to be passed to the callback function. 752 * @returns 0 if the subsystem request is accepted 753 * @returns 1 if the request is denied 754 */ 755 typedef int (*ssh_channel_subsystem_request_callback) (ssh_session session, 756 ssh_channel channel, 757 const char *subsystem, 758 void *userdata); 759 760 /** 761 * @brief SSH channel write will not block (flow control). 762 * 763 * @param channel the channel 764 * 765 * @param[in] bytes size of the remote window in bytes. Writing as much data 766 * will not block. 767 * 768 * @param[in] userdata Userdata to be passed to the callback function. 769 * 770 * @returns 0 default return value (other return codes may be added in future). 771 */ 772 typedef int (*ssh_channel_write_wontblock_callback) (ssh_session session, 773 ssh_channel channel, 774 size_t bytes, 775 void *userdata); 776 777 struct ssh_channel_callbacks_struct { 778 /** DON'T SET THIS use ssh_callbacks_init() instead. */ 779 size_t size; 780 /** 781 * User-provided data. User is free to set anything he wants here 782 */ 783 void *userdata; 784 /** 785 * This functions will be called when there is data available. 786 */ 787 ssh_channel_data_callback channel_data_function; 788 /** 789 * This functions will be called when the channel has received an EOF. 790 */ 791 ssh_channel_eof_callback channel_eof_function; 792 /** 793 * This functions will be called when the channel has been closed by remote 794 */ 795 ssh_channel_close_callback channel_close_function; 796 /** 797 * This functions will be called when a signal has been received 798 */ 799 ssh_channel_signal_callback channel_signal_function; 800 /** 801 * This functions will be called when an exit status has been received 802 */ 803 ssh_channel_exit_status_callback channel_exit_status_function; 804 /** 805 * This functions will be called when an exit signal has been received 806 */ 807 ssh_channel_exit_signal_callback channel_exit_signal_function; 808 /** 809 * This function will be called when a client requests a PTY 810 */ 811 ssh_channel_pty_request_callback channel_pty_request_function; 812 /** 813 * This function will be called when a client requests a shell 814 */ 815 ssh_channel_shell_request_callback channel_shell_request_function; 816 /** This function will be called when a client requests agent 817 * authentication forwarding. 818 */ 819 ssh_channel_auth_agent_req_callback channel_auth_agent_req_function; 820 /** This function will be called when a client requests X11 821 * forwarding. 822 */ 823 ssh_channel_x11_req_callback channel_x11_req_function; 824 /** This function will be called when a client requests a 825 * window change. 826 */ 827 ssh_channel_pty_window_change_callback channel_pty_window_change_function; 828 /** This function will be called when a client requests a 829 * command execution. 830 */ 831 ssh_channel_exec_request_callback channel_exec_request_function; 832 /** This function will be called when a client requests an environment 833 * variable to be set. 834 */ 835 ssh_channel_env_request_callback channel_env_request_function; 836 /** This function will be called when a client requests a subsystem 837 * (like sftp). 838 */ 839 ssh_channel_subsystem_request_callback channel_subsystem_request_function; 840 /** This function will be called when the channel write is guaranteed 841 * not to block. 842 */ 843 ssh_channel_write_wontblock_callback channel_write_wontblock_function; 844 }; 845 846 typedef struct ssh_channel_callbacks_struct *ssh_channel_callbacks; 847 848 /** 849 * @brief Set the channel callback functions. 850 * 851 * This functions sets the callback structure to use your own callback 852 * functions for channel data and exceptions 853 * 854 * @code 855 * struct ssh_channel_callbacks_struct cb = { 856 * .userdata = data, 857 * .channel_data_function = my_channel_data_function 858 * }; 859 * ssh_callbacks_init(&cb); 860 * ssh_set_channel_callbacks(channel, &cb); 861 * @endcode 862 * 863 * @param channel The channel to set the callback structure. 864 * 865 * @param cb The callback structure itself. 866 * 867 * @return SSH_OK on success, SSH_ERROR on error. 868 * @warning this function will not replace existing callbacks but set the 869 * new one atop of them. 870 */ 871 LIBSSH_API int ssh_set_channel_callbacks(ssh_channel channel, 872 ssh_channel_callbacks cb); 873 874 /** 875 * @brief Add channel callback functions 876 * 877 * This function will add channel callback functions to the channel callback 878 * list. 879 * Callbacks missing from a callback structure will be probed in the next 880 * on the list. 881 * 882 * @param channel The channel to set the callback structure. 883 * 884 * @param cb The callback structure itself. 885 * 886 * @return SSH_OK on success, SSH_ERROR on error. 887 * 888 * @see ssh_set_channel_callbacks 889 */ 890 LIBSSH_API int ssh_add_channel_callbacks(ssh_channel channel, 891 ssh_channel_callbacks cb); 892 893 /** 894 * @brief Remove a channel callback. 895 * 896 * The channel has been added with ssh_add_channel_callbacks or 897 * ssh_set_channel_callbacks in this case. 898 * 899 * @param channel The channel to remove the callback structure from. 900 * 901 * @param cb The callback structure to remove 902 * 903 * @returns SSH_OK on success, SSH_ERROR on error. 904 */ 905 LIBSSH_API int ssh_remove_channel_callbacks(ssh_channel channel, 906 ssh_channel_callbacks cb); 907 908 /** @} */ 909 910 /** @group libssh_threads 911 * @{ 912 */ 913 914 typedef int (*ssh_thread_callback) (void **lock); 915 916 typedef unsigned long (*ssh_thread_id_callback) (void); 917 struct ssh_threads_callbacks_struct { 918 const char *type; 919 ssh_thread_callback mutex_init; 920 ssh_thread_callback mutex_destroy; 921 ssh_thread_callback mutex_lock; 922 ssh_thread_callback mutex_unlock; 923 ssh_thread_id_callback thread_id; 924 }; 925 926 /** 927 * @brief Set the thread callbacks structure. 928 * 929 * This is necessary if your program is using libssh in a multithreaded fashion. 930 * This function must be called first, outside of any threading context (in your 931 * main() function for instance), before you call ssh_init(). 932 * 933 * @param[in] cb A pointer to a ssh_threads_callbacks_struct structure, which 934 * contains the different callbacks to be set. 935 * 936 * @returns Always returns SSH_OK. 937 * 938 * @see ssh_threads_callbacks_struct 939 * @see SSH_THREADS_PTHREAD 940 * @bug libgcrypt 1.6 and bigger backend does not support custom callback. 941 * Using anything else than pthreads here will fail. 942 */ 943 LIBSSH_API int ssh_threads_set_callbacks(struct ssh_threads_callbacks_struct 944 *cb); 945 946 /** 947 * @brief Returns a pointer to the appropriate callbacks structure for the 948 * environment, to be used with ssh_threads_set_callbacks. 949 * 950 * @returns A pointer to a ssh_threads_callbacks_struct to be used with 951 * ssh_threads_set_callbacks. 952 * 953 * @see ssh_threads_set_callbacks 954 */ 955 LIBSSH_API struct ssh_threads_callbacks_struct *ssh_threads_get_default(void); 956 957 /** 958 * @brief Returns a pointer on the pthread threads callbacks, to be used with 959 * ssh_threads_set_callbacks. 960 * 961 * @see ssh_threads_set_callbacks 962 */ 963 LIBSSH_API struct ssh_threads_callbacks_struct *ssh_threads_get_pthread(void); 964 965 /** 966 * @brief Get the noop threads callbacks structure 967 * 968 * This can be used with ssh_threads_set_callbacks. These callbacks do nothing 969 * and are being used by default. 970 * 971 * @return Always returns a valid pointer to the noop callbacks structure. 972 * 973 * @see ssh_threads_set_callbacks 974 */ 975 LIBSSH_API struct ssh_threads_callbacks_struct *ssh_threads_get_noop(void); 976 977 /** 978 * @brief Set the logging callback function. 979 * 980 * @param[in] cb The callback to set. 981 * 982 * @return 0 on success, < 0 on errror. 983 */ 984 LIBSSH_API int ssh_set_log_callback(ssh_logging_callback cb); 985 986 /** 987 * @brief Get the pointer to the logging callback function. 988 * 989 * @return The pointer the the callback or NULL if none set. 990 */ 991 LIBSSH_API ssh_logging_callback ssh_get_log_callback(void); 992 993 /** @} */ 994 #ifdef __cplusplus 995 } 996 #endif 997 998 #endif /*_SSH_CALLBACK_H */ 999 1000 /* @} */ 1001