From f8d943afda1a3f0b69669e739e9ae05514566e53 Mon Sep 17 00:00:00 2001 From: nikhil-nari Date: Mon, 1 Dec 2025 17:53:58 +0530 Subject: [PATCH] Improve doxygen docs Signed-off-by: Nikhil V Reviewed-by: Jakub Jelen --- include/libssh/callbacks.h | 7 +- include/libssh/ed25519.h | 27 ++- include/libssh/libssh.h | 403 +++++++++++++++++++++++++++++++++++++ src/server.c | 1 - 4 files changed, 432 insertions(+), 6 deletions(-) diff --git a/include/libssh/callbacks.h b/include/libssh/callbacks.h index 12d9b706..f507821c 100644 --- a/include/libssh/callbacks.h +++ b/include/libssh/callbacks.h @@ -279,7 +279,6 @@ typedef int (*ssh_auth_pubkey_callback) (ssh_session session, const char *user, * @returns 0 if the request is to be allowed * @returns -1 if the request should not be allowed */ - typedef int (*ssh_service_request_callback) (ssh_session session, const char *service, void *userdata); /** @@ -292,7 +291,7 @@ typedef int (*ssh_service_request_callback) (ssh_session session, const char *se */ typedef ssh_channel (*ssh_channel_open_request_session_callback) (ssh_session session, void *userdata); -/* +/** * @brief handle the beginning of a GSSAPI authentication, server side. * Callback should select the oid and also acquire the server credential. * @param session current session handler @@ -307,7 +306,7 @@ typedef ssh_channel (*ssh_channel_open_request_session_callback) (ssh_session se typedef ssh_string (*ssh_gssapi_select_oid_callback) (ssh_session session, const char *user, int n_oid, ssh_string *oids, void *userdata); -/* +/** * @brief handle the negotiation of a security context, server side. * @param session current session handler * @param[in] input_token input token provided by client @@ -322,7 +321,7 @@ typedef ssh_string (*ssh_gssapi_select_oid_callback) (ssh_session session, const typedef int (*ssh_gssapi_accept_sec_ctx_callback) (ssh_session session, ssh_string input_token, ssh_string *output_token, void *userdata); -/* +/** * @brief Verify and authenticates a MIC, server side. * @param session current session handler * @param[in] mic input mic to be verified provided by client diff --git a/include/libssh/ed25519.h b/include/libssh/ed25519.h index 72a86c0b..0a7d2951 100644 --- a/include/libssh/ed25519.h +++ b/include/libssh/ed25519.h @@ -29,12 +29,37 @@ * @{ */ +/** @internal + * @brief Length of an ED25519 public key in bytes. + */ #define ED25519_PK_LEN 32 + +/** @internal + * @brief Length of an ED25519 private key in bytes. + */ #define ED25519_SK_LEN 64 + +/** @internal + * @brief Length of an ED25519 signature in bytes. + */ #define ED25519_SIG_LEN 64 +/** @internal + * @brief ED25519 public key. + * The public key consists of 32 bytes and can be used for key exchanges. + */ typedef uint8_t ed25519_pubkey[ED25519_PK_LEN]; + +/** @internal + * @brief ED25519 private key. + * The private key consists of 64 bytes and should be kept secret. + */ typedef uint8_t ed25519_privkey[ED25519_SK_LEN]; + +/** @internal + * @brief ED25519 signature. + * Ed25519 signatures consists of 64 bytes. + */ typedef uint8_t ed25519_signature[ED25519_SIG_LEN]; #ifdef __cplusplus @@ -46,7 +71,7 @@ extern "C" { * @param[out] pk generated public key * @param[out] sk generated secret key * @return 0 on success, -1 on error. - * */ + */ int crypto_sign_ed25519_keypair(ed25519_pubkey pk, ed25519_privkey sk); /** @internal diff --git a/include/libssh/libssh.h b/include/libssh/libssh.h index 6dff4d0e..47acf6dd 100644 --- a/include/libssh/libssh.h +++ b/include/libssh/libssh.h @@ -455,9 +455,44 @@ enum ssh_connector_flags_e { SSH_CONNECTOR_BOTH = 3 }; +/** + * @brief Flushes the output buffer of the session, blocking until the buffer is empty or the timeout is reached + * + * @param[in] session The ssh session. + * @param[in] timeout Timeout (milliseconds) + * + * @return SSH_OK on success (0), SSH_ERROR on error (-1). + */ LIBSSH_API int ssh_blocking_flush(ssh_session session, int timeout); + +/** + * @brief Accept an X11 connection from the server. + * + * @param[in] channel The channel . + * @param[in] timeout_ms Timeout (milliseconds). + * + * @return A new X11 channel, or NULL on error. + */ LIBSSH_API ssh_channel ssh_channel_accept_x11(ssh_channel channel, int timeout_ms); + +/** + * @brief Change the size of the terminal . + * + * @param[in] channel The channel . + * @param[in] cols Number of columns. + * @param[in] rows Number of rows. + * + * @return SSH_OK on success (0), SSH_ERROR on error(-1). + */ LIBSSH_API int ssh_channel_change_pty_size(ssh_channel channel,int cols,int rows); + +/** + * @brief Closes a channel. + * + * @param[in] channel The channel. + * + * @return SSH_OK on success(0), SSH_ERROR on error(-1). + */ LIBSSH_API int ssh_channel_close(ssh_channel channel); #define SSH_CHANNEL_FREE(x) \ do { \ @@ -466,23 +501,129 @@ LIBSSH_API int ssh_channel_close(ssh_channel channel); (x) = NULL; \ } \ } while (0) + +/** + * @brief Frees a channel. + * + * @param[in] channel The channel. + */ LIBSSH_API void ssh_channel_free(ssh_channel channel); + +/** + * @brief Get the exit status of a channel . + * + * @param[in] channel The channel . + * @param[out] pexit_code the exit code (can be NULL). + * @param[out] pexit_signal the exit signal string (can be NULL). + * @param[out] pcore_dumped the core dump flag (can be NULL). + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_get_exit_state(ssh_channel channel, uint32_t *pexit_code, char **pexit_signal, int *pcore_dumped); SSH_DEPRECATED LIBSSH_API int ssh_channel_get_exit_status(ssh_channel channel); + +/** + * @brief Used to get the session . + * + * @param[in] channel The channel . + * + * @return The ssh session. + */ LIBSSH_API ssh_session ssh_channel_get_session(ssh_channel channel); + +/** + * @brief Check if the channel is closed. + * + * @param[in] channel The channel . + * + * @return 1 if the channel is closed, 0 otherwise. + */ LIBSSH_API int ssh_channel_is_closed(ssh_channel channel); + +/** + * @brief Check if the remote host has sent an EOF (End Of File). + * + * @param[in] channel The channel . + * + * @return 1 if EOF has been received, 0 otherwise. + */ LIBSSH_API int ssh_channel_is_eof(ssh_channel channel); + +/** + * @brief Check if the channel is open. + * + * @param[in] channel The channel . + * + * @return 1 if the channel is open, 0 otherwise. + */ LIBSSH_API int ssh_channel_is_open(ssh_channel channel); + +/** + * @brief Create a new channel. + * + * @param[in] session The ssh session to use. + * + * @return a new channel, or NULL on error. + */ LIBSSH_API ssh_channel ssh_channel_new(ssh_session session); + +/** + * @brief Open an authentication agent forwarding channel. + * + * @param[in] channel The channel . + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_open_auth_agent(ssh_channel channel); + +/** + * @brief Open a TCP/IP forwarding channel. + * + * @param[in] channel The channel . + * @param[in] remotehost The remote host that connect to. + * @param[in] remoteport The remote port that connect to. + * @param[in] sourcehost The source host from which to connect. + * @param[in] localport The source port from which to connect. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_open_forward(ssh_channel channel, const char *remotehost, int remoteport, const char *sourcehost, int localport); + +/** + * @brief Open a Unix domain socket forwarding channel. + * + * @param[in] channel The channel . + * @param[in] remotepath The remote path of the socket. + * @param[in] sourcehost The source host from which to connect. + * @param[in] localport The source port from which to connect. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_open_forward_unix(ssh_channel channel, const char *remotepath, const char *sourcehost, int localport); + +/** + * @brief Open a session channel . + * + * @param[in] channel The channel . + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_open_session(ssh_channel channel); + +/** + * @brief Open an X11 channel. + * + * @param[in] channel The channel . + * @param[in] orig_addr The source address . + * @param[in] orig_port The source port. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_open_x11(ssh_channel channel, const char *orig_addr, int orig_port); LIBSSH_API int ssh_channel_poll(ssh_channel channel, int is_stderr); LIBSSH_API int ssh_channel_poll_timeout(ssh_channel channel, int timeout, int is_stderr); @@ -490,48 +631,287 @@ LIBSSH_API int ssh_channel_read(ssh_channel channel, void *dest, uint32_t count, LIBSSH_API int ssh_channel_read_timeout(ssh_channel channel, void *dest, uint32_t count, int is_stderr, int timeout_ms); LIBSSH_API int ssh_channel_read_nonblocking(ssh_channel channel, void *dest, uint32_t count, int is_stderr); + +/** + * @brief Set an environment variable on the channel. + * + * @param[in] channel The channel . + * @param[in] name The name of the variable. + * @param[in] value The value to set. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_env(ssh_channel channel, const char *name, const char *value); + +/** + * @brief Run a command on the channel. + * + * @param[in] channel The channel . + * @param[in] cmd The command to run. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_exec(ssh_channel channel, const char *cmd); + +/** + * @brief Request a PTY (pseudo-terminal) on the channel. + * + * @param[in] channel The channel . + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_pty(ssh_channel channel); + +/** + * @brief Request a PTY (pseudo-terminal) size on the channel. + * + * @param[in] channel The channel . + * @param[in] term The terminal type . + * @param[in] cols The number of columns. + * @param[in] rows The number of rows. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_pty_size(ssh_channel channel, const char *term, int cols, int rows); + +/** + * @brief Request a PTY (pseudo-terminal) size and modes on the channel. + * + * @param[in] channel The channel . + * @param[in] term The terminal type. + * @param[in] cols The number of columns. + * @param[in] rows The number of rows. + * @param[in] modes The encoded terminal modes. + * @param[in] modes_len The length of the modes data. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_pty_size_modes(ssh_channel channel, const char *term, int cols, int rows, const unsigned char* modes, size_t modes_len); + +/** + * @brief Request a shell on the channel. + * + * @param[in] channel The channel . + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_shell(ssh_channel channel); + +/** + * @brief Send a signal to the channel. + * + * @param[in] channel The channel . + * @param[in] signum The signal name . + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_send_signal(ssh_channel channel, const char *signum); + +/** + * @brief Send a break signal to the channel. + * + * @param[in] channel The channel . + * @param[in] length The length of the break in ms. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_send_break(ssh_channel channel, uint32_t length); + +/** + * @brief Request the SFTP subsystem on the channel. + * + * @param[in] channel The channel . + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_sftp(ssh_channel channel); + +/** + * @brief Request a subsystem on the channel. + * + * @param[in] channel The channel . + * @param[in] subsystem The subsystem name. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_subsystem(ssh_channel channel, const char *subsystem); LIBSSH_API int ssh_channel_request_x11(ssh_channel channel, int single_connection, const char *protocol, const char *cookie, int screen_number); + +/** + * @brief Request agent forwarding on the channel. + * + * @param[in] channel The channel . + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_request_auth_agent(ssh_channel channel); + +/** + * @brief Send EOF (End Of File) to the channel. + * + * @param[in] channel The channel . + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_send_eof(ssh_channel channel); + +/** + * @brief Set the channel to blocking or non-blocking mode. + * + * @param[in] channel The channel . + * @param[in] blocking Set to 1 for blocking, 0 for non-blocking. + */ LIBSSH_API void ssh_channel_set_blocking(ssh_channel channel, int blocking); + +/** + * @brief Set the counter structure for the channel. + * + * @param[in] channel The channel . + * @param[in] counter The counter to update. + */ LIBSSH_API void ssh_channel_set_counter(ssh_channel channel, ssh_counter counter); + +/** + * @brief Write data to the channel. + * + * @param[in] channel The channel . + * @param[in] data The data to be written. + * @param[in] len The length of the data. + * + * @return The number of bytes written, or SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_write(ssh_channel channel, const void *data, uint32_t len); + +/** + * @brief Write data to the channel's standard error. + * + * @param[in] channel The channel . + * @param[in] data The data to be written. + * @param[in] len The length of the data. + * + * @return The number of bytes written, or SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_write_stderr(ssh_channel channel, const void *data, uint32_t len); + +/** + * @brief Get the current window size of the channel. + * + * @param[in] channel The channel . + * + * @return The window size. + */ LIBSSH_API uint32_t ssh_channel_window_size(ssh_channel channel); +/** + * @brief Get the file name from a path. + * + * @param[in] path The path. + * + * @return The base name, or NULL on error. + */ LIBSSH_API char *ssh_basename (const char *path); + +/** + * @brief Clean up and free a public key hash. + * + * @param[in,out] hash The hash to free. + */ LIBSSH_API void ssh_clean_pubkey_hash(unsigned char **hash); + +/** + * @brief Connects to the ssh server. + * + * @param[in] session The ssh session. + * + * @return SSH_OK on success (0), SSH_ERROR on error (-1). + */ LIBSSH_API int ssh_connect(ssh_session session); +/** + * @brief Create a new connector. + * + * @param[in] session The session . + * + * @return A new connector, or NULL on error. + */ LIBSSH_API ssh_connector ssh_connector_new(ssh_session session); + +/** + * @brief Free a connector. + * + * @param[in] connector The connector to free. + */ LIBSSH_API void ssh_connector_free(ssh_connector connector); + +/** + * @brief Set the input channel for the connector. + * + * @param[in] connector The connector . + * @param[in] channel The channel . + * @param[in] flags Flags for the connector. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_connector_set_in_channel(ssh_connector connector, ssh_channel channel, enum ssh_connector_flags_e flags); + +/** + * @brief Set the output channel for the connector. + * + * @param[in] connector The connector . + * @param[in] channel The channel . + * @param[in] flags Flags for the connector. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_connector_set_out_channel(ssh_connector connector, ssh_channel channel, enum ssh_connector_flags_e flags); + +/** + * @brief Set the input file descriptor for the connector. + * + * @param[in] connector The connector . + * @param[in] fd The file descriptor. + */ LIBSSH_API void ssh_connector_set_in_fd(ssh_connector connector, socket_t fd); + +/** + * @brief Set the output file descriptor for the connector. + * + * @param[in] connector The connector . + * @param[in] fd The file descriptor. + */ LIBSSH_API void ssh_connector_set_out_fd(ssh_connector connector, socket_t fd); +/** + * @brief Get the copyright information. + * + * @return The copyright string. + */ LIBSSH_API const char *ssh_copyright(void); + +/** + * @brief Disconnects from the ssh server. + * + * @param[in] session The ssh session to be disconnected. + */ LIBSSH_API void ssh_disconnect(ssh_session session); + +/** + * @brief Get the directory name from a path. + * + * @param[in] path The path. + * + * @return The directory name, or NULL on error. + */ LIBSSH_API char *ssh_dirname (const char *path); LIBSSH_API int ssh_finalize(void); @@ -544,6 +924,16 @@ LIBSSH_API ssh_channel ssh_channel_open_forward_port(ssh_session session, SSH_DEPRECATED LIBSSH_API ssh_channel ssh_channel_accept_forward(ssh_session session, int timeout_ms, int *destination_port); + +/** + * @brief Cancel a reverse port forwarding. + * + * @param[in] session The ssh session. + * @param[in] address The address bound. + * @param[in] port The port bound. + * + * @return SSH_OK on success, SSH_ERROR on error. + */ LIBSSH_API int ssh_channel_cancel_forward(ssh_session session, const char *address, int port); @@ -552,7 +942,20 @@ LIBSSH_API int ssh_channel_listen_forward(ssh_session session, int port, int *bound_port); +/** + * @brief Free an ssh session. + * + * @param[in] session The session to free. + */ LIBSSH_API void ssh_free(ssh_session session); + +/** + * @brief Get the disconnect message from the server. + * + * @param[in] session The ssh session. + * + * @return The disconnect message, or NULL if none. + */ LIBSSH_API const char *ssh_get_disconnect_message(ssh_session session); LIBSSH_API const char *ssh_get_error(void *error); LIBSSH_API int ssh_get_error_code(void *error); diff --git a/src/server.c b/src/server.c index 58b13253..f1126729 100644 --- a/src/server.c +++ b/src/server.c @@ -80,7 +80,6 @@ * The selection of algorithms and keys used are determined by the * options that are currently set in the given ssh_session structure. */ - int server_set_kex(ssh_session session) { struct ssh_kex_struct *server = &session->next_crypto->server_kex;