Improve doxygen documentation

Signed-off-by: Nikhil V <nikhilgreyshines@gmail.com>
Reviewed-by: Jakub Jelen <jjelen@redhat.com>

src/server.c

@@ -72,13 +72,21 @@
  * @{
  */
 
-/** @internal
+/**
+ * @internal
+ * @brief Sets the server's key exchange, encryption, MAC, and compression
+ * algorithms.
  *
- * @brief initialize the set of key exchange, hostkey, ciphers, MACs, and
- *        compression algorithms for the given ssh_session
+ * Prepares the server key exchange (KEX) proposals by prioritizing the
+ * available host keys (Ed25519, ECDSA, RSA)  based on their strength and fills
+ * in the KEX method lists based on session options or defaults. This is
+ * essential for negotiating secure communication parameters in the SSH
+ * handshake.
  *
- * The selection of algorithms and keys used are determined by the
- * options that are currently set in the given ssh_session structure.
+ * @param[in] session The SSH session to set up.
+ *
+ * @return `SSH_OK` on success, `SSH_ERROR` on failure (e.g., no host keys
+ * available, random number generation error, or memory allocation failure).
  */
 int server_set_kex(ssh_session session)
 {
@@ -210,6 +218,23 @@ int ssh_server_init_kex(ssh_session session) {
     return server_set_kex(session);
 }
 
+/**
+ * @internal
+ *
+ * @brief Sends SSH extension information from the server to client.
+ *
+ * A server may send this message (`SSH_MSG_EXT_INFO`) after its first
+ * `SSH_MSG_NEWKEYS` message or just before sending `SSH_MSG_USERAUTH_SUCCESS`
+ * to provide additional extensions support that are not meant for an
+ * unauthenticated client.
+ *
+ * If any error occurs during the packing or sending of the packet, the function
+ * aborts to avoid partial or corrupted sends.
+ *
+ * @param[in] session The SSH session.
+ *
+ * @return `SSH_OK` on success, `SSH_ERROR` on failure.
+ */
 static int ssh_server_send_extensions(ssh_session session)
 {
     int rc;
@@ -275,6 +300,22 @@ SSH_PACKET_CALLBACK(ssh_packet_kexdh_init){
   return SSH_PACKET_NOT_USED;
 }
 
+/**
+ * @brief Prepares server host key parameters for the key exchange process.
+ *
+ * Selects the appropriate private host key (RSA, ECDSA, or Ed25519) based on
+ * the session's configured host key type, sets the corresponding @p digest
+ * algorithm, and imports the public key blob into the Diffie-Hellman key
+ * exchange state.
+ *
+ * @param[in]  session  The SSH session to which we are preparing host key
+ * parameters.
+ * @param[out] privkey  Pointer to receive the selected private host key.
+ * @param[out] digest   Pointer to receive the host key digest algorithm.
+ *
+ * @return `SSH_OK` on success; `SSH_ERROR` on failure (invalid key type, export
+ * failure, or DH import error).
+ */
 int
 ssh_get_key_params(ssh_session session,
                    ssh_key *privkey,
@@ -668,6 +709,20 @@ int ssh_auth_reply_default(ssh_session session,int partial) {
   return rc;
 }
 
+/**
+ * @internal
+ *
+ * @brief Sends default refusal for a channel open request.
+ *
+ * Default handler that rejects incoming SSH channel open requests by sending
+ * a `SSH2_MSG_CHANNEL_OPEN_FAILURE` packet with "administratively prohibited"
+ * reason code. Used when no custom channel open handler is registered.
+ *
+ * @param[in] msg The SSH message containing the channel open request details.
+ *
+ * @return `SSH_OK` on successful packet send; `SSH_ERROR` on buffer allocation
+ *         or packet send failure.
+ */
 static int ssh_message_channel_request_open_reply_default(ssh_message msg) {
     int rc;
 
@@ -689,6 +744,21 @@ static int ssh_message_channel_request_open_reply_default(ssh_message msg) {
     return rc;
 }
 
+/**
+ * @internal
+ *
+ * @brief Sends default refusal for a channel request.
+ *
+ * Default handler that rejects incoming SSH channel requests. If the client
+ * requested a reply (`want_reply`), sends `SSH2_MSG_CHANNEL_FAILURE` to the
+ * specific channel. If no reply requested, logs the refusal and returns
+ * success.
+ *
+ * @param[in] msg The SSH message containing the channel request details.
+ *
+ * @return `SSH_OK` on success; `SSH_ERROR` if buffer allocation or packet send
+ * fails.
+ */
 static int ssh_message_channel_request_reply_default(ssh_message msg) {
   uint32_t channel;
   int rc;
@@ -722,11 +792,11 @@ static int ssh_message_service_request_reply_default(ssh_message msg) {
 }
 
 /**
- * @brief   Sends SERVICE_ACCEPT to the client
+ * @brief   Sends `SSH2_MSG_SERVICE_ACCEPT` to the client
  *
  * @param msg The message to reply to
  *
- * @returns SSH_OK when success otherwise SSH_ERROR
+ * @returns `SSH_OK` when success otherwise `SSH_ERROR`
  */
 int ssh_message_service_reply_success(ssh_message msg)
 {
@@ -760,7 +830,7 @@ int ssh_message_service_reply_success(ssh_message msg)
  *
  * @param bound_port The remote bind port
  *
- * @returns SSH_OK on success, otherwise SSH_ERROR
+ * @returns `SSH_OK` on success, otherwise `SSH_ERROR`
  */
 int ssh_message_global_request_reply_success(ssh_message msg, uint16_t bound_port) {
     int rc;
@@ -796,6 +866,20 @@ error:
     return SSH_ERROR;
 }
 
+/**
+ * @internal
+ *
+ * @brief Sends default refusal for a global request.
+ *
+ * Default handler that rejects incoming SSH global requests. If the client
+ * requested a reply (`want_reply`), sends `SSH2_MSG_REQUEST_FAILURE`. If no
+ * reply requested, logs the refusal and returns success immediately.
+ *
+ * @param[in] msg The SSH message containing the global request details.
+ *
+ * @return `SSH_OK` on success; `SSH_ERROR` if buffer allocation or packet send
+ * fails.
+ */
 static int ssh_message_global_request_reply_default(ssh_message msg) {
     SSH_LOG(SSH_LOG_FUNCTIONS, "Refusing a global request");
 
@@ -934,6 +1018,28 @@ int ssh_message_auth_set_methods(ssh_message msg, int methods) {
   return 0;
 }
 
+/**
+ * @brief Sends an interactive authentication request message.
+ *
+ * Builds and sends an `SSH2_MSG_USERAUTH_INFO_REQUEST` packet containing the
+ * given name and @p instruction, followed by a number of @p prompts with
+ * associated @p echo flags to control whether user input is echoed.
+ * It initializes the keyboard-interactive state in the session.
+ *
+ * @param[in]  msg          The SSH message representing the client
+ *                          authentication request.
+ * @param[in]  name         The name of the authentication request.
+ * @param[in]  instruction  Instruction string with information for the user.
+ * @param[in]  num_prompts  Number of prompts to send. The arrays prompts and
+ *                          echo must both have num_prompts elements.
+ * @param[in]  prompts      Array of @p num_prompts prompt strings to display.
+ * @param[in]  echo         Array of num_prompts boolean values (0 or 1). A
+ *                          non-zero value means the user input for that prompt
+ *                          is echoed (visible); 0 means the input is hidden
+ *                          (typically for passwords).
+ *
+ * @return `SSH_OK` on successful send; `SSH_ERROR` on failure.
+ */
 int ssh_message_auth_interactive_request(ssh_message msg, const char *name,
                             const char *instruction, unsigned int num_prompts,
                             const char **prompts, char *echo) {
@@ -1040,15 +1146,15 @@ int ssh_message_auth_interactive_request(ssh_message msg, const char *name,
 }
 
 /**
- * @brief Sends SSH2_MSG_USERAUTH_SUCCESS or SSH2_MSG_USERAUTH_FAILURE message
- * depending on the success of the authentication method
+ * @brief Sends `SSH2_MSG_USERAUTH_SUCCESS` or `SSH2_MSG_USERAUTH_FAILURE`
+ * message depending on the success of the authentication method
  *
  * @param session The session to reply to
  *
  * @param partial Denotes if the authentication process was partially completed
  * (unsuccessful)
  *
- * @returns SSH_OK on success, otherwise SSH_ERROR
+ * @returns `SSH_OK` on success, otherwise `SSH_ERROR`
  */
 int ssh_auth_reply_success(ssh_session session, int partial)
 {
@@ -1072,9 +1178,9 @@ int ssh_auth_reply_success(ssh_session session, int partial)
 
     /*
      * Consider the session as having been authenticated only after sending
-     * the USERAUTH_SUCCESS message.  Setting these flags after ssh_packet_send
-     * ensures that a rekey is not triggered prematurely, causing the message
-     * to be queued.
+     * the `USERAUTH_SUCCESS` message.  Setting these flags after
+     * ssh_packet_send ensures that a rekey is not triggered prematurely,
+     * causing the message to be queued.
      */
     session->session_state = SSH_SESSION_STATE_AUTHENTICATED;
     session->flags |= SSH_SESSION_FLAG_AUTHENTICATED;
@@ -1093,6 +1199,18 @@ int ssh_auth_reply_success(ssh_session session, int partial)
     return r;
 }
 
+/**
+ * @brief Replies to an authentication request with success.
+ *
+ * Sends an authentication success message (`SSH2_MSG_USERAUTH_SUCCESS`) to the
+ * client, or a partial success if further authentication steps are required.
+ *
+ * @param[in] msg     The SSH authentication message being handled.
+ * @param[in] partial Set to nonzero if partial success (more auth needed), zero
+ * for full success.
+ *
+ * @return `SSH_OK` on success, `SSH_ERROR` if msg is NULL or on send failure.
+ */
 int ssh_message_auth_reply_success(ssh_message msg, int partial) {
 	if(msg == NULL)
 		return SSH_ERROR;
@@ -1100,7 +1218,7 @@ int ssh_message_auth_reply_success(ssh_message msg, int partial) {
 }
 
 /**
- * @brief Answer SSH2_MSG_USERAUTH_PK_OK to a pubkey authentication request
+ * @brief Answer `SSH2_MSG_USERAUTH_PK_OK` to a pubkey authentication request
  *
  * @param msg The message
  *
@@ -1108,7 +1226,7 @@ int ssh_message_auth_reply_success(ssh_message msg, int partial) {
  *
  * @param pubkey The accepted public key
  *
- * @returns SSH_OK on success, otherwise SSH_ERROR
+ * @returns `SSH_OK` on success, otherwise `SSH_ERROR`
  */
 int ssh_message_auth_reply_pk_ok(ssh_message msg, ssh_string algo, ssh_string pubkey) {
     int rc;
@@ -1131,11 +1249,11 @@ int ssh_message_auth_reply_pk_ok(ssh_message msg, ssh_string algo, ssh_string pu
 }
 
 /**
- * @brief Answer SSH2_MSG_USERAUTH_PK_OK to a pubkey authentication request
+ * @brief Answer `SSH2_MSG_USERAUTH_PK_OK` to a pubkey authentication request
  *
  * @param msg The message
  *
- * @returns SSH_OK on success, otherwise SSH_ERROR
+ * @returns `SSH_OK` on success, otherwise `SSH_ERROR`
  */
 int ssh_message_auth_reply_pk_ok_simple(ssh_message msg)
 {
@@ -1162,83 +1280,271 @@ int ssh_message_auth_reply_pk_ok_simple(ssh_message msg)
     return ret;
 }
 
-
+/**
+ * @brief Get the originator address from the channel open message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The originator address, or NULL.
+ */
 const char *ssh_message_channel_request_open_originator(ssh_message msg){
     return msg->channel_request_open.originator;
 }
 
+/**
+ * @brief Get the originator port from the channel open message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The originator port.
+ */
 int ssh_message_channel_request_open_originator_port(ssh_message msg){
     return msg->channel_request_open.originator_port;
 }
 
+/**
+ * @brief Get the destination address from the channel open message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The destination address, or NULL.
+ */
 const char *ssh_message_channel_request_open_destination(ssh_message msg){
     return msg->channel_request_open.destination;
 }
 
+/**
+ * @brief Get the destination port from the channel open message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The destination port.
+ */
 int ssh_message_channel_request_open_destination_port(ssh_message msg){
     return msg->channel_request_open.destination_port;
 }
 
+/**
+ * @brief Get the channel associated with the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The channel associated with the message.
+ */
 ssh_channel ssh_message_channel_request_channel(ssh_message msg){
     return msg->channel_request.channel;
 }
 
+/**
+ * @brief Get the terminal type from the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The terminal type (e.g. "xterm"), or NULL.
+ *
+ * @deprecated This function should not be used anymore as there is a
+ * callback based server implementation function channel_pty_request_function.
+ *
+ * @see channel_pty_request_function.
+ */
 const char *ssh_message_channel_request_pty_term(ssh_message msg){
     return msg->channel_request.TERM;
 }
 
+/**
+ * @brief Get the terminal width from the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The terminal width in characters.
+ *
+ * @deprecated This function should not be used anymore as there is a
+ * callback based server implementation function channel_pty_request_function.
+ *
+ * @see channel_pty_request_function.
+ */
 int ssh_message_channel_request_pty_width(ssh_message msg){
     return msg->channel_request.width;
 }
 
+/**
+ * @brief Get the terminal height from the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The terminal height in characters.
+ *
+ * @deprecated This function should not be used anymore as there is a
+ * callback based server implementation function channel_pty_request_function.
+ *
+ * @see channel_pty_request_function.
+ */
 int ssh_message_channel_request_pty_height(ssh_message msg){
     return msg->channel_request.height;
 }
 
+/**
+ * @brief Get the terminal pixel width from the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The pixel width.
+ *
+ * @deprecated This function should not be used anymore as there is a
+ * callback based server implementation function channel_pty_request_function.
+ *
+ * @see channel_pty_request_function.
+ */
 int ssh_message_channel_request_pty_pxwidth(ssh_message msg){
     return msg->channel_request.pxwidth;
 }
 
+/**
+ * @brief Get the terminal pixel height from the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The pixel height.
+ *
+ * @deprecated This function should not be used anymore as there is a
+ * callback based server implementation function channel_pty_request_function.
+ *
+ * @see channel_pty_request_function.
+ */
 int ssh_message_channel_request_pty_pxheight(ssh_message msg){
     return msg->channel_request.pxheight;
 }
 
+/**
+ * @brief Get the name of the environment variable from the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The variable name, or NULL.
+ */
 const char *ssh_message_channel_request_env_name(ssh_message msg){
     return msg->channel_request.var_name;
 }
 
+/**
+ * @brief Get the value of the environment variable from the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The variable value, or NULL.
+ */
 const char *ssh_message_channel_request_env_value(ssh_message msg){
     return msg->channel_request.var_value;
 }
 
+/**
+ * @brief Get the command from a channel request message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The command, or NULL.
+ */
 const char *ssh_message_channel_request_command(ssh_message msg){
     return msg->channel_request.command;
 }
 
+/**
+ * @brief Get the subsystem from a channel request message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The subsystem, or NULL.
+ */
 const char *ssh_message_channel_request_subsystem(ssh_message msg){
     return msg->channel_request.subsystem;
 }
 
+/**
+ * @brief Check if the X11 request is for a single connection.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               1 if single connection, 0 otherwise.
+ *
+ * @deprecated This function should not be used anymore as there is a
+ * callback based server implementation function
+ * channel_open_request_x11_function.
+ *
+ * @see channel_open_request_x11_function.
+ */
 int ssh_message_channel_request_x11_single_connection(ssh_message msg){
     return msg->channel_request.x11_single_connection ? 1 : 0;
 }
 
+/**
+ * @brief Get the X11 authentication protocol from the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The authentication protocol, or NULL.
+ *
+ * @deprecated This function should not be used anymore as there is a
+ * callback based server implementation function
+ * channel_open_request_x11_function.
+ *
+ * @see channel_open_request_x11_function.
+ */
 const char *ssh_message_channel_request_x11_auth_protocol(ssh_message msg){
     return msg->channel_request.x11_auth_protocol;
 }
 
+/**
+ * @brief Get the X11 authentication cookie from the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The authentication cookie, or NULL.
+ *
+ * @deprecated This function should not be used anymore as there is a
+ * callback based server implementation function
+ * channel_open_request_x11_function.
+ *
+ * @see channel_open_request_x11_function.
+ */
 const char *ssh_message_channel_request_x11_auth_cookie(ssh_message msg){
     return msg->channel_request.x11_auth_cookie;
 }
 
+/**
+ * @brief Get the X11 screen number from the message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The screen number.
+ *
+ * @deprecated This function should not be used anymore as there is a
+ * callback based server implementation function
+ * channel_open_request_x11_function.
+ *
+ * @see channel_open_request_x11_function.
+ */
 int ssh_message_channel_request_x11_screen_number(ssh_message msg){
     return msg->channel_request.x11_screen_number;
 }
 
+/**
+ * @brief Get the bind address from the global request message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The bind address, or NULL.
+ */
 const char *ssh_message_global_request_address(ssh_message msg){
     return msg->global_request.bind_address;
 }
 
+/**
+ * @brief Get the bind port from the global request message.
+ *
+ * @param[in] msg        The message.
+ *
+ * @return               The bind port.
+ */
 int ssh_message_global_request_port(ssh_message msg){
     return msg->global_request.bind_port;
 }
@@ -1258,6 +1564,13 @@ void ssh_set_message_callback(ssh_session session,
   session->ssh_message_callback_data = data;
 }
 
+/**
+ * @brief Execute callbacks for the messages in the queue.
+ *
+ * @param[in] session    The session.
+ *
+ * @return               `SSH_OK` on success, `SSH_ERROR` on error.
+ */
 int ssh_execute_message_callbacks(ssh_session session){
   ssh_message msg=NULL;
   int ret;
@@ -1293,7 +1606,7 @@ int ssh_execute_message_callbacks(ssh_session session){
  *
  * @param session   The session to send the message to
  *
- * @returns SSH_OK
+ * @returns `SSH_OK`
  */
 int ssh_send_keepalive(ssh_session session)
 {