From bc69bf64c7fc0e1c3dfeb6bc47ad3878464a9b6b Mon Sep 17 00:00:00 2001 From: ashutoshsao Date: Wed, 10 Dec 2025 05:14:15 +0530 Subject: [PATCH 1/9] auth.c: Improve doxygen documentation Signed-off-by: ashutoshsao --- src/auth.c | 484 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 300 insertions(+), 184 deletions(-) diff --git a/src/auth.c b/src/auth.c index ef3ef1aca..9966ef362 100644 --- a/src/auth.c +++ b/src/auth.c @@ -60,11 +60,18 @@ * * @brief Ask for access to the ssh-userauth service. * - * @param[in] session The SSH session handle. + * Initiates a "ssh-userauth" service request after establishing + * the SSH transport, before any user authentication. * - * @returns SSH_OK on success, SSH_ERROR on error. - * @returns SSH_AGAIN on nonblocking mode, if calling that function - * again is necessary + * @param[in] session The SSH session handle. + * + * @returns + * - `SSH_OK`: on success + * - `SSH_AGAIN`: in nonblocking mode, if calling the function + * again is necessary. + * - `SSH_ERROR`: on error + * + * @note This function is called by ssh_connect() before any user authentication. */ static int ssh_userauth_request_service(ssh_session session) { @@ -79,6 +86,21 @@ static int ssh_userauth_request_service(ssh_session session) return rc; } + +/** + * @internal + * + * @brief Check if the authentication state is terminal. + * + * This function checks if the authentication state is terminal, meaning that + * the authentication process has completed or failed. + * + * @param[in] user The SSH session handle. + * + * @returns + * - `SSH_OK`: The authentication state is not terminal. + * - `SSH_ERROR`: The authentication state is terminal. + */ static int ssh_auth_response_termination(void *user) { ssh_session session = (ssh_session)user; @@ -98,6 +120,17 @@ static int ssh_auth_response_termination(void *user) } } +/** + * @internal + * + * @brief Get the current authentication method. + * + * This function returns the current authentication method. + * + * @param[in] session The SSH session handle. + * + * @returns The current authentication method. + */ static const char *ssh_auth_get_current_method(ssh_session session) { const char *method = "unknown"; @@ -130,16 +163,20 @@ static const char *ssh_auth_get_current_method(ssh_session session) /** * @internal + * * @brief Wait for a response of an authentication function. * - * @param[in] session The SSH session. + * This function waits for a response of an authentication function. * - * @returns SSH_AUTH_SUCCESS Authentication success, or pubkey accepted - * SSH_AUTH_PARTIAL Authentication succeeded but another mean - * of authentication is needed. - * SSH_AUTH_INFO Data for keyboard-interactive - * SSH_AUTH_AGAIN In nonblocking mode, call has to be made again - * SSH_AUTH_ERROR Error during the process. + * @param[in] session The SSH session. + * + * @returns + * - `SSH_AUTH_SUCCESS`: Authentication success, or pubkey accepted + * - `SSH_AUTH_PARTIAL`: Authentication succeeded but another mean + * of authentication is needed. + * - `SSH_AUTH_INFO`: Data for keyboard-interactive + * - `SSH_AUTH_AGAIN`: In nonblocking mode, call has to be made again + * - `SSH_AUTH_ERROR`: Error during the process. */ static int ssh_userauth_get_response(ssh_session session) { @@ -194,6 +231,8 @@ static int ssh_userauth_get_response(ssh_session session) * @brief Handles a SSH_USERAUTH_BANNER packet. * * This banner should be shown to user prior to authentication + * + * @returns `SSH_PACKET_USED` The packet was used. */ SSH_PACKET_CALLBACK(ssh_packet_userauth_banner) { @@ -222,6 +261,8 @@ SSH_PACKET_CALLBACK(ssh_packet_userauth_banner) * @brief Handles a SSH_USERAUTH_FAILURE packet. * * This handles the complete or partial authentication failure. + * + * @returns `SSH_PACKET_USED` The packet was used. */ SSH_PACKET_CALLBACK(ssh_packet_userauth_failure) { const char *current_method = ssh_auth_get_current_method(session); @@ -286,6 +327,8 @@ end: * @brief Handles a SSH_USERAUTH_SUCCESS packet. * * It is also used to communicate the new to the upper levels. + * + * @returns `SSH_PACKET_USED` The packet was used. */ SSH_PACKET_CALLBACK(ssh_packet_userauth_success) { @@ -327,6 +370,8 @@ SSH_PACKET_CALLBACK(ssh_packet_userauth_success) * * Since the two types of packets share the same code, additional work is done * to understand if we are in a public key or keyboard-interactive context. + * + * @returns `SSH_PACKET_USED` The packet was used. */ SSH_PACKET_CALLBACK(ssh_packet_userauth_pk_ok) { int rc; @@ -364,15 +409,14 @@ SSH_PACKET_CALLBACK(ssh_packet_userauth_pk_ok) { * methods are available. The server MAY return a list of methods that may * continue. * - * @param[in] session The SSH session. + * @param[in] session The SSH session. + * @param[in] username Deprecated, set to NULL. * - * @param[in] username Deprecated, set to NULL. - * - * @returns A bitfield of the following values: - * - SSH_AUTH_METHOD_PASSWORD - * - SSH_AUTH_METHOD_PUBLICKEY - * - SSH_AUTH_METHOD_HOSTBASED - * - SSH_AUTH_METHOD_INTERACTIVE + * @returns A bitfield of the following values: + * - `SSH_AUTH_METHOD_PASSWORD` + * - `SSH_AUTH_METHOD_PUBLICKEY` + * - `SSH_AUTH_METHOD_HOSTBASED` + * - `SSH_AUTH_METHOD_INTERACTIVE` * * @warning Other reserved flags may appear in future versions. * @see ssh_userauth_none() @@ -391,17 +435,17 @@ int ssh_userauth_list(ssh_session session, const char *username) /** * @brief Try to authenticate through the "none" method. * - * @param[in] session The ssh session to use. - * - * @param[in] username The username, this SHOULD be NULL. + * @param[in] session The ssh session to use. + * @param[in] username The username, this SHOULD be NULL. * - * @returns SSH_AUTH_ERROR: A serious error happened.\n - * SSH_AUTH_DENIED: Authentication failed: use another method\n - * SSH_AUTH_PARTIAL: You've been partially authenticated, you still - * have to use another method\n - * SSH_AUTH_SUCCESS: Authentication success\n - * SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again - * later. + * @returns + * - `SSH_AUTH_ERROR`: A serious error happened. + * - `SSH_AUTH_DENIED`: Authentication failed: use another method. + * - `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method. + * - `SSH_AUTH_SUCCESS`: Authentication success. + * - `SSH_AUTH_AGAIN`: In nonblocking mode, you've got to call this again + * later. * * @note Most server implementations do not permit changing the username during * authentication. The username should only be set with ssh_options_set() only @@ -472,9 +516,9 @@ fail: * extension is enabled. It export the server's public key and adds it to the * authentication buffer. * - * @param[in] session The SSH session. + * @param[in] session The SSH session. * - * @returns SSH_OK on success, SSH_ERROR if an error occurred. + * @returns `SSH_OK` on success, `SSH_ERROR` if an error occurred. */ static int add_hostbound_pubkey(ssh_session session) { @@ -518,14 +562,14 @@ error: * key authentication and adds the server's public key if the hostbound * extension is enabled. * - * @param[in] session The SSH session. - * @param[in] username The username, may be NULL. - * @param[in] auth_type Authentication type (0 for key offer, 1 for actual - * auth). - * @param[in] sig_type_c The signature algorithm name. - * @param[in] pubkey_s The public key string. + * @param[in] session The SSH session. + * @param[in] username The username, may be NULL. + * @param[in] auth_type Authentication type (`0` for key offer, `1` for actual + * auth). + * @param[in] sig_type_c The signature algorithm name. + * @param[in] pubkey_s The public key string. * - * @return SSH_OK on success, SSH_ERROR if an error occurred. + * @return `SSH_OK` on success, `SSH_ERROR` if an error occurred. */ static int build_pubkey_auth_request(ssh_session session, const char *username, @@ -572,22 +616,21 @@ static int build_pubkey_auth_request(ssh_session session, * is provided for querying whether authentication using the 'pubkey' would * be possible. * - * @param[in] session The SSH session. - * - * @param[in] username The username, this SHOULD be NULL. - * - * @param[in] pubkey The public key to try. - * - * @return SSH_AUTH_ERROR: A serious error happened.\n - * SSH_AUTH_DENIED: The server doesn't accept that public key as an - * authentication token. Try another key or another - * method.\n - * SSH_AUTH_PARTIAL: You've been partially authenticated, you still - * have to use another method.\n - * SSH_AUTH_SUCCESS: The public key is accepted, you want now to use - * ssh_userauth_publickey().\n - * SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again - * later. + * @param[in] session The SSH session. + * @param[in] username The username, this SHOULD be NULL. + * @param[in] pubkey The public key to try. + * + * @return + * - `SSH_AUTH_ERROR`: A serious error happened. + * - `SSH_AUTH_DENIED`: The server doesn't accept that public key as an + * authentication token. Try another key or another + * method. + * - `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method. + * - `SSH_AUTH_SUCCESS`: The public key is accepted, you want now to use + * ssh_userauth_publickey(). + * - `SSH_AUTH_AGAIN`: In nonblocking mode, you've got to call this again + * later. * * @note Most server implementations do not permit changing the username during * authentication. The username should only be set with ssh_options_set() only @@ -702,21 +745,20 @@ fail: /** * @brief Authenticate with public/private key or certificate. * - * @param[in] session The SSH session. - * - * @param[in] username The username, this SHOULD be NULL. - * - * @param[in] privkey The private key for authentication. - * - * @return SSH_AUTH_ERROR: A serious error happened.\n - * SSH_AUTH_DENIED: The server doesn't accept that public key as an - * authentication token. Try another key or another - * method.\n - * SSH_AUTH_PARTIAL: You've been partially authenticated, you still - * have to use another method.\n - * SSH_AUTH_SUCCESS: The public key is accepted.\n - * SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again - * later. + * @param[in] session The SSH session. + * @param[in] username The username, this SHOULD be NULL. + * @param[in] privkey The private key for authentication. + * + * @return + * - `SSH_AUTH_ERROR`: A serious error happened. + * - `SSH_AUTH_DENIED`: The server doesn't accept that public key as an + * authentication token. Try another key or another + * method. + * - `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method. + * - `SSH_AUTH_SUCCESS`: The public key is accepted. + * - `SSH_AUTH_AGAIN`: In nonblocking mode, you've got to call this again + * later. * * @note Most server implementations do not permit changing the username during * authentication. The username should only be set with ssh_options_set() only @@ -848,7 +890,29 @@ fail: return SSH_AUTH_ERROR; } - +/** + * @brief Try to do public key authentication with ssh agent. + * + * @param[in] `session` The SSH session. + * + * @param[in] `username` The username, this SHOULD be NULL. + * + * @param[in] `pubkey` The public key to try. + * + * @return `SSH_AUTH_ERROR`: A serious error happened.\n + * `SSH_AUTH_DENIED`: The server doesn't accept that public key as an + * authentication token. Try another key or another + * method.\n + * `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method.\n + * `SSH_AUTH_SUCCESS`: The public key is accepted.\n + * `SSH_AUTH_AGAIN`: In nonblocking mode, you've got to call this again + * later. + * + * @note Most server implementations do not permit changing the username during + * authentication. The username should only be set with ssh_options_set() only + * before you connect to the server. + */ static int ssh_userauth_agent_publickey(ssh_session session, const char *username, ssh_key pubkey) @@ -974,7 +1038,13 @@ struct ssh_agent_state_struct { char *comment; }; -/* Internal function */ +/** + * @internal + * + * @brief Free the ssh agent state. + * + * @param[in] data Pointer to the struct ssh_agent_state_struct to be freed. + */ void ssh_agent_state_free(void *data) { struct ssh_agent_state_struct *state = data; @@ -989,20 +1059,20 @@ void ssh_agent_state_free(void *data) /** * @brief Try to do public key authentication with ssh agent. * - * @param[in] session The ssh session to use. - * - * @param[in] username The username, this SHOULD be NULL. - * - * @return SSH_AUTH_ERROR: A serious error happened.\n - * SSH_AUTH_DENIED: The server doesn't accept that public key as an - * authentication token. Try another key or another - * method.\n - * SSH_AUTH_PARTIAL: You've been partially authenticated, you still - * have to use another method.\n - * SSH_AUTH_SUCCESS: The public key is accepted, you want now to use - * ssh_userauth_publickey().\n - * SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again - * later. + * @param[in] session The ssh session to use. + * @param[in] username The username, this SHOULD be NULL. + * + * @return + * - `SSH_AUTH_ERROR`: A serious error happened. + * - `SSH_AUTH_DENIED`: The server doesn't accept that public key as an + * authentication token. Try another key or another + * method. + * - `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method. + * - `SSH_AUTH_SUCCESS`: The public key is accepted, you want now to use + * ssh_userauth_publickey(). + * - `SSH_AUTH_AGAIN`: In nonblocking mode, you've got to call this again + * later. * * @note Most server implementations do not permit changing the username during * authentication. The username should only be set with ssh_options_set() only @@ -1298,14 +1368,13 @@ struct ssh_auth_auto_state_struct { * callback might want to know which key a passphrase is needed for, * for example. * - * @param[in] session The SSH session. - * - * @param[out] value The value to get into. As a char**, space will be - * allocated by the function for the value, it is - * your responsibility to free the memory using - * ssh_string_free_char(). + * @param[in] session The SSH session. + * @param[out] value The value to get into. As a `char**`, space will be + * allocated by the function for the value, it is + * your responsibility to free the memory using + * `ssh_string_free_char()`. * - * @return SSH_OK on success, SSH_ERROR on error. + * @return `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_userauth_publickey_auto_get_current_identity(ssh_session session, char** value) @@ -1345,23 +1414,22 @@ int ssh_userauth_publickey_auto_get_current_identity(ssh_session session, * It may fail, for instance it doesn't ask for a password and uses a default * asker for passphrases (in case the private key is encrypted). * - * @param[in] session The SSH session. - * - * @param[in] username The username, this SHOULD be NULL. - * - * @param[in] passphrase Use this passphrase to unlock the privatekey. Use NULL - * if you don't want to use a passphrase or the user - * should be asked. - * - * @return SSH_AUTH_ERROR: A serious error happened.\n - * SSH_AUTH_DENIED: The server doesn't accept that public key as an - * authentication token. Try another key or another - * method.\n - * SSH_AUTH_PARTIAL: You've been partially authenticated, you still - * have to use another method.\n - * SSH_AUTH_SUCCESS: Authentication success\n - * SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again - * later. + * @param[in] session The SSH session. + * @param[in] username The username, this SHOULD be NULL. + * @param[in] passphrase Use this passphrase to unlock the privatekey. Use NULL + * if you don't want to use a passphrase or the user + * should be asked. + * + * @return + * - `SSH_AUTH_ERROR`: A serious error happened. + * - `SSH_AUTH_DENIED`: The server doesn't accept that public key as an + * authentication token. Try another key or another + * method. + * - `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method. + * - `SSH_AUTH_SUCCESS`: Authentication success. + * - `SSH_AUTH_AGAIN`: In nonblocking mode, you've got to call this again + * later. * * @note Most server implementations do not permit changing the username during * authentication. The username should only be set with ssh_options_set() only @@ -1693,19 +1761,18 @@ int ssh_userauth_publickey_auto(ssh_session session, * However, if you read the password in some other encoding, you MUST convert * the password to UTF-8. * - * @param[in] session The ssh session to use. - * - * @param[in] username The username, this SHOULD be NULL. - * - * @param[in] password The password to authenticate in UTF-8. + * @param[in] session The ssh session to use. + * @param[in] username The username, this SHOULD be NULL. + * @param[in] password The password to authenticate in UTF-8. * - * @returns SSH_AUTH_ERROR: A serious error happened.\n - * SSH_AUTH_DENIED: Authentication failed: use another method\n - * SSH_AUTH_PARTIAL: You've been partially authenticated, you still - * have to use another method\n - * SSH_AUTH_SUCCESS: Authentication success\n - * SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again - * later. + * @returns + * - `SSH_AUTH_ERROR`: A serious error happened. + * - `SSH_AUTH_DENIED`: Authentication failed: use another method. + * - `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method. + * - `SSH_AUTH_SUCCESS`: Authentication success. + * - `SSH_AUTH_AGAIN`: In nonblocking mode, you've got to call this again + * later. * * @note Most server implementations do not permit changing the username during * authentication. The username should only be set with ssh_options_set() only @@ -1815,7 +1882,15 @@ int ssh_userauth_agent_pubkey(ssh_session session, return rc; } - +/** + * @internal + * + * @brief Create a new keyboard-interactive object. + * + * @return + * - `ssh_kbdint`: The keyboard-interactive object was created. + * - `NULL`: If an error occurred. + */ ssh_kbdint ssh_kbdint_new(void) { ssh_kbdint kbd; @@ -1828,7 +1903,13 @@ ssh_kbdint ssh_kbdint_new(void) return kbd; } - +/** + * @internal + * + * @brief Free the keyboard-interactive object. + * + * @param[in] kbd The keyboard-interactive object to free. + */ void ssh_kbdint_free(ssh_kbdint kbd) { size_t i, n; @@ -1866,6 +1947,13 @@ void ssh_kbdint_free(ssh_kbdint kbd) SAFE_FREE(kbd); } +/** + * @internal + * + * @brief Clean the keyboard-interactive object. + * + * @param[in] kbd The keyboard-interactive object to clean. + */ void ssh_kbdint_clean(ssh_kbdint kbd) { size_t i, n; @@ -1901,8 +1989,22 @@ void ssh_kbdint_clean(ssh_kbdint kbd) kbd->nanswers = 0; } -/* - * This function sends the first packet as explained in RFC 3066 section 3.1. +/** + * @internal + * + * @brief Send the first Keyboard-interactive packet as explained in RFC 3066 section 3.1. + * + * @param[in] session The ssh session to use. + * @param[in] username The username to authenticate. + * @param[in] submethods The submethods to use. + * + * @return + * - `SSH_AUTH_AGAIN`: In nonblocking mode, you've got to call this again + * later. + * - `SSH_AUTH_SUCCESS`: The authentication was successful. + * - `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method. + * - `SSH_AUTH_ERROR`: A serious error happened. */ static int ssh_userauth_kbdint_init(ssh_session session, const char *username, @@ -1968,10 +2070,12 @@ fail: * @brief Send the current challenge response and wait for a reply from the * server. * - * @returns SSH_AUTH_INFO if more info is needed - * @returns SSH_AUTH_SUCCESS - * @returns SSH_AUTH_FAILURE - * @returns SSH_AUTH_PARTIAL + * @returns + * - `SSH_AUTH_INFO`: if more info is needed + * - `SSH_AUTH_SUCCESS`: The authentication was successful. + * - `SSH_AUTH_FAILURE`: The authentication failed. + * - `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method. */ static int ssh_userauth_kbdint_send(ssh_session session) { @@ -2026,9 +2130,20 @@ fail: /** * @internal + * * @brief handles a SSH_USERAUTH_INFO_REQUEST packet, as used in * keyboard-interactive authentication, and changes the * authentication state. + * + * @param[in] session The ssh session to use. + * @param[in] type The type of the packet. + * @param[in] packet The packet to handle. + * @param[in] user The user to authenticate. + * + * @return + * - `SSH_PACKET_USED`: The packet was used. + * - `SSH_PACKET_NOT_USED`: The packet was not used. + * - `SSH_PACKET_ERROR`: An error occurred. */ SSH_PACKET_CALLBACK(ssh_packet_userauth_info_request) { ssh_string tmp = NULL; @@ -2120,23 +2235,22 @@ SSH_PACKET_CALLBACK(ssh_packet_userauth_info_request) { /** * @brief Try to authenticate through the "keyboard-interactive" method. * - * @param[in] session The ssh session to use. - * - * @param[in] user The username to authenticate. You can specify NULL if - * ssh_option_set_username() has been used. You cannot try - * two different logins in a row. - * - * @param[in] submethods Undocumented. Set it to NULL. - * - * @returns SSH_AUTH_ERROR: A serious error happened\n - * SSH_AUTH_DENIED: Authentication failed : use another method\n - * SSH_AUTH_PARTIAL: You've been partially authenticated, you still - * have to use another method\n - * SSH_AUTH_SUCCESS: Authentication success\n - * SSH_AUTH_INFO: The server asked some questions. Use - * ssh_userauth_kbdint_getnprompts() and such.\n - * SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again - * later. + * @param[in] session The ssh session to use. + * @param[in] user The username to authenticate. You can specify NULL if + * ssh_option_set_username() has been used. You cannot try + * two different logins in a row. + * @param[in] submethods Undocumented. Set it to NULL. + * + * @returns + * - `SSH_AUTH_SUCCESS`: Authentication success. + * - `SSH_AUTH_DENIED`: Authentication failed : use another method. + * - `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method. + * - `SSH_AUTH_INFO`: The server asked some questions. Use + * ssh_userauth_kbdint_getnprompts() and such. + * - `SSH_AUTH_AGAIN`: In nonblocking mode, you've got to call this again + * later. + * - `SSH_AUTH_ERROR`: A serious error happened. * * @see ssh_userauth_kbdint_getnprompts() * @see ssh_userauth_kbdint_getname() @@ -2184,9 +2298,11 @@ int ssh_userauth_kbdint(ssh_session session, const char *user, * code, this function can be used to retrieve information about the keyboard * interactive authentication questions sent by the remote host. * - * @param[in] session The ssh session to use. + * @param[in] session The ssh session to use. * - * @returns The number of prompts. + * @returns + * - `session->kbdint->nprompts`: The number of prompts. + * - `SSH_ERROR`: If an error occurred. */ int ssh_userauth_kbdint_getnprompts(ssh_session session) { @@ -2207,9 +2323,9 @@ int ssh_userauth_kbdint_getnprompts(ssh_session session) * code, this function can be used to retrieve information about the keyboard * interactive authentication questions sent by the remote host. * - * @param[in] session The ssh session to use. + * @param[in] session The ssh session to use. * - * @returns The name of the message block. Do not free it. + * @returns The name of the message block. Do not free it. */ const char *ssh_userauth_kbdint_getname(ssh_session session) { @@ -2230,9 +2346,9 @@ const char *ssh_userauth_kbdint_getname(ssh_session session) * code, this function can be used to retrieve information about the keyboard * interactive authentication questions sent by the remote host. * - * @param[in] session The ssh session to use. + * @param[in] session The ssh session to use. * - * @returns The instruction of the message block. + * @returns The instruction of the message block. Do not free it. */ const char *ssh_userauth_kbdint_getinstruction(ssh_session session) @@ -2253,15 +2369,15 @@ const char *ssh_userauth_kbdint_getinstruction(ssh_session session) * code, this function can be used to retrieve information about the keyboard * interactive authentication questions sent by the remote host. * - * @param[in] session The ssh session to use. + * @param[in] session The ssh session to use. * - * @param[in] i The index number of the i'th prompt. + * @param[in] i The index number of the i'th prompt. * - * @param[out] echo This is an optional variable. You can obtain a - * boolean if the user input should be echoed or - * hidden. For passwords it is usually hidden. + * @param[out] echo This is an optional variable. You can obtain a + * boolean if the user input should be echoed or + * hidden. For passwords it is usually hidden. * - * @returns A pointer to the prompt. Do not free it. + * @returns A pointer to the prompt. Do not free it. * * @code * const char prompt; @@ -2296,9 +2412,9 @@ ssh_userauth_kbdint_getprompt(ssh_session session, unsigned int i, char *echo) /** * @brief Get the number of answers the client has given. * - * @param[in] session The ssh session to use. + * @param[in] session The ssh session to use. * - * @returns The number of answers. + * @returns The number of answers. */ int ssh_userauth_kbdint_getnanswers(ssh_session session) { @@ -2311,12 +2427,11 @@ int ssh_userauth_kbdint_getnanswers(ssh_session session) /** * @brief Get the answer to a question from a message block. * - * @param[in] session The ssh session to use. - * - * @param[in] i index The number of the ith answer. + * @param[in] session The ssh session to use. + * @param[in] i The number of the ith answer. * - * @return The answer string, or NULL if the answer is not - * available. Do not free the string. + * @returns The answer string, or NULL if the answer is not + * available. Do not free the string. */ const char *ssh_userauth_kbdint_getanswer(ssh_session session, unsigned int i) { @@ -2338,17 +2453,17 @@ const char *ssh_userauth_kbdint_getanswer(ssh_session session, unsigned int i) * If you have called ssh_userauth_kbdint() and got SSH_AUTH_INFO, this * function returns the questions from the server. * - * @param[in] session The ssh session to use. - * - * @param[in] i index The number of the ith prompt. - * - * @param[in] answer The answer to give to the server. The answer MUST be - * encoded UTF-8. It is up to the server how to interpret - * the value and validate it. However, if you read the - * answer in some other encoding, you MUST convert it to - * UTF-8. - * - * @return 0 on success, < 0 on error. + * @param[in] session The ssh session to use. + * @param[in] i The number of the ith prompt. + * @param[in] answer The answer to give to the server. The answer MUST be + * encoded UTF-8. It is up to the server how to interpret + * the value and validate it. However, if you read the + * answer in some other encoding, you MUST convert it to + * UTF-8. + * + * @returns + * - `SSH_OK`: On success. + * - `SSH_ERROR`: On error. */ int ssh_userauth_kbdint_setanswer(ssh_session session, unsigned int i, @@ -2389,15 +2504,16 @@ ssh_userauth_kbdint_setanswer(ssh_session session, unsigned int i, /** * @brief Try to authenticate through the "gssapi-with-mic" method. * - * @param[in] session The ssh session to use. + * @param[in] session The ssh session to use. * - * @returns SSH_AUTH_ERROR: A serious error happened\n - * SSH_AUTH_DENIED: Authentication failed : use another method\n - * SSH_AUTH_PARTIAL: You've been partially authenticated, you still - * have to use another method\n - * SSH_AUTH_SUCCESS: Authentication success\n - * SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again - * later. + * @returns + * - `SSH_AUTH_ERROR`: A serious error happened. + * - `SSH_AUTH_DENIED`: Authentication failed : use another method. + * - `SSH_AUTH_PARTIAL`: You've been partially authenticated, you still + * have to use another method. + * - `SSH_AUTH_SUCCESS`: Authentication success. + * - `SSH_AUTH_AGAIN`: In nonblocking mode, you've got to call this again + * later. */ int ssh_userauth_gssapi(ssh_session session) { -- GitLab From 465e56031b4f5184821cddf16c859a2c5fb8e6d1 Mon Sep 17 00:00:00 2001 From: ashutoshsao Date: Wed, 10 Dec 2025 21:04:40 +0530 Subject: [PATCH 2/9] buffer.c: Improve doxygen documentation Signed-off-by: ashutoshsao --- src/buffer.c | 305 ++++++++++++++++++++++++++------------------------- 1 file changed, 156 insertions(+), 149 deletions(-) diff --git a/src/buffer.c b/src/buffer.c index dffdaa4f0..95b9df5ee 100644 --- a/src/buffer.c +++ b/src/buffer.c @@ -72,7 +72,7 @@ struct ssh_buffer_struct { * * @brief Check that preconditions and postconditions are valid. * - * @param[in] buf The buffer to check. + * @param[in] buf The buffer to check. */ static void buffer_verify(ssh_buffer buf) { @@ -115,7 +115,7 @@ static void buffer_verify(ssh_buffer buf) /** * @brief Create a new SSH buffer. * - * @return A newly initialized SSH buffer, NULL on error. + * @returns A newly initialized SSH buffer, NULL on error. */ struct ssh_buffer_struct *ssh_buffer_new(void) { @@ -145,7 +145,7 @@ struct ssh_buffer_struct *ssh_buffer_new(void) /** * @brief Deallocate a SSH buffer. * - * \param[in] buffer The buffer to free. + * @param[in] buffer The buffer to free. */ void ssh_buffer_free(struct ssh_buffer_struct *buffer) { @@ -178,7 +178,16 @@ void ssh_buffer_set_secure(ssh_buffer buffer) { buffer->secure = true; } - +/** + * @brief Realloc the buffer. + * + * This function reallocates the buffer to the given size. + * + * @param[in] buffer The buffer to realloc. + * @param[in] needed The size to realloc to. + * + * @returns `SSH_OK` on success, `SSH_ERROR` on error. + */ static int realloc_buffer(struct ssh_buffer_struct *buffer, uint32_t needed) { uint32_t smallest = 1; @@ -220,9 +229,16 @@ static int realloc_buffer(struct ssh_buffer_struct *buffer, uint32_t needed) return 0; } -/** @internal +/** + * @internal + * * @brief shifts a buffer to remove unused data in the beginning - * @param buffer SSH buffer + * + * This function shifts the buffer to remove unused data in the beginning. + * + * @param[in] buffer SSH buffer + * + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ static void buffer_shift(ssh_buffer buffer) { @@ -253,9 +269,9 @@ static void buffer_shift(ssh_buffer buffer) * In case the buffer has exceeded 64K in size, the buffer will be reallocated * to 64K. * - * @param[in] buffer The buffer to reinitialize. + * @param[in] buffer The buffer to reinitialize. * - * @return 0 on success, < 0 on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_buffer_reinit(struct ssh_buffer_struct *buffer) { @@ -290,13 +306,11 @@ int ssh_buffer_reinit(struct ssh_buffer_struct *buffer) /** * @brief Add data at the tail of a buffer. * - * @param[in] buffer The buffer to add the data. - * - * @param[in] data A pointer to the data to add. + * @param[in] buffer The buffer to add the data. + * @param[in] data A pointer to the data to add. + * @param[in] len The length of the data to add. * - * @param[in] len The length of the data to add. - * - * @return 0 on success, < 0 on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_buffer_add_data(struct ssh_buffer_struct *buffer, const void *data, uint32_t len) { @@ -332,11 +346,10 @@ int ssh_buffer_add_data(struct ssh_buffer_struct *buffer, const void *data, uint /** * @brief Ensure the buffer has at least a certain preallocated size. * - * @param[in] buffer The buffer to enlarge. - * - * @param[in] len The length to ensure as allocated. + * @param[in] buffer The buffer to enlarge. + * @param[in] len The length to ensure as allocated. * - * @return 0 on success, < 0 on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_buffer_allocate_size(struct ssh_buffer_struct *buffer, uint32_t len) @@ -362,12 +375,10 @@ int ssh_buffer_allocate_size(struct ssh_buffer_struct *buffer, * * @brief Allocate space for data at the tail of a buffer. * - * @param[in] buffer The buffer to add the data. + * @param[in] buffer The buffer to add the data. + * @param[in] len The length of the data to add. * - * @param[in] len The length of the data to add. - * - * @return Pointer on the allocated space - * NULL on error. + * @returns A pointer to the allocated space, NULL on error. */ void *ssh_buffer_allocate(struct ssh_buffer_struct *buffer, uint32_t len) { @@ -401,11 +412,10 @@ void *ssh_buffer_allocate(struct ssh_buffer_struct *buffer, uint32_t len) * * @brief Add a SSH string to the tail of a buffer. * - * @param[in] buffer The buffer to add the string. - * - * @param[in] string The SSH String to add. + * @param[in] buffer The buffer to add the string. + * @param[in] string The SSH String to add. * - * @return 0 on success, < 0 on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_buffer_add_ssh_string(struct ssh_buffer_struct *buffer, @@ -434,11 +444,10 @@ ssh_buffer_add_ssh_string(struct ssh_buffer_struct *buffer, * * @brief Add a 32 bits unsigned integer to the tail of a buffer. * - * @param[in] buffer The buffer to add the integer. + * @param[in] buffer The buffer to add the integer. + * @param[in] data The 32 bits integer to add. * - * @param[in] data The 32 bits integer to add. - * - * @return 0 on success, -1 on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_buffer_add_u32(struct ssh_buffer_struct *buffer,uint32_t data) { @@ -457,11 +466,10 @@ int ssh_buffer_add_u32(struct ssh_buffer_struct *buffer,uint32_t data) * * @brief Add a 16 bits unsigned integer to the tail of a buffer. * - * @param[in] buffer The buffer to add the integer. - * - * @param[in] data The 16 bits integer to add. + * @param[in] buffer The buffer to add the integer. + * @param[in] data The 16 bits integer to add. * - * @return 0 on success, -1 on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_buffer_add_u16(struct ssh_buffer_struct *buffer,uint16_t data) { @@ -480,11 +488,10 @@ int ssh_buffer_add_u16(struct ssh_buffer_struct *buffer,uint16_t data) * * @brief Add a 64 bits unsigned integer to the tail of a buffer. * - * @param[in] buffer The buffer to add the integer. - * - * @param[in] data The 64 bits integer to add. + * @param[in] buffer The buffer to add the integer. + * @param[in] data The 64 bits integer to add. * - * @return 0 on success, -1 on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_buffer_add_u64(struct ssh_buffer_struct *buffer, uint64_t data) { @@ -503,11 +510,10 @@ int ssh_buffer_add_u64(struct ssh_buffer_struct *buffer, uint64_t data) * * @brief Add a 8 bits unsigned integer to the tail of a buffer. * - * @param[in] buffer The buffer to add the integer. + * @param[in] buffer The buffer to add the integer. + * @param[in] data The 8 bits integer to add. * - * @param[in] data The 8 bits integer to add. - * - * @return 0 on success, -1 on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_buffer_add_u8(struct ssh_buffer_struct *buffer,uint8_t data) { @@ -526,13 +532,11 @@ int ssh_buffer_add_u8(struct ssh_buffer_struct *buffer,uint8_t data) * * @brief Add data at the head of a buffer. * - * @param[in] buffer The buffer to add the data. - * - * @param[in] data The data to prepend. - * - * @param[in] len The length of data to prepend. + * @param[in] buffer The buffer to add the data. + * @param[in] data The data to prepend. + * @param[in] len The length of data to prepend. * - * @return 0 on success, -1 on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_buffer_prepend_data(struct ssh_buffer_struct *buffer, const void *data, uint32_t len) { @@ -568,12 +572,11 @@ int ssh_buffer_prepend_data(struct ssh_buffer_struct *buffer, const void *data, * * @brief Append data from a buffer to the tail of another buffer. * - * @param[in] buffer The destination buffer. - * - * @param[in] source The source buffer to append. It doesn't take the + * @param[in] buffer The destination buffer. + * @param[in] source The source buffer to append. It doesn't take the * position of the buffer into account. * - * @return 0 on success, -1 on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_buffer_add_buffer(struct ssh_buffer_struct *buffer, struct ssh_buffer_struct *source) @@ -593,9 +596,9 @@ int ssh_buffer_add_buffer(struct ssh_buffer_struct *buffer, /** * @brief Get a pointer to the head of a buffer at the current position. * - * @param[in] buffer The buffer to get the head pointer. + * @param[in] buffer The buffer to get the head pointer. * - * @return A pointer to the data from current position. + * @returns A pointer to the data from current position. * * @see ssh_buffer_get_len() */ @@ -606,9 +609,9 @@ void *ssh_buffer_get(struct ssh_buffer_struct *buffer){ /** * @brief Get the length of the buffer from the current position. * - * @param[in] buffer The buffer to get the length from. + * @param[in] buffer The buffer to get the length from. * - * @return The length of the buffer. + * @returns The length of the buffer. * * @see ssh_buffer_get() */ @@ -625,10 +628,10 @@ uint32_t ssh_buffer_get_len(struct ssh_buffer_struct *buffer){ * Creates a new ssh_buffer and copies all data from the source buffer. * The new buffer preserves the secure flag setting of the source. * - * @param[in] buffer The buffer to duplicate. Can be NULL. + * @param[in] buffer The buffer to duplicate. Can be NULL. * - * @return A new buffer containing a copy of the data on success, - * NULL on failure or if buffer is NULL. + * @returns A new buffer containing a copy of the data on success, + * NULL on failure or if buffer is NULL. * * @see ssh_buffer_free() */ @@ -671,11 +674,10 @@ ssh_buffer ssh_buffer_dup(const ssh_buffer buffer) * * This has effect to "eat" bytes at head of the buffer. * - * @param[in] buffer The buffer to advance the position. - * - * @param[in] len The number of bytes to eat. + * @param[in] buffer The buffer to advance the position. + * @param[in] len The number of bytes to eat. * - * @return The new size of the buffer. + * @returns The new size of the buffer. */ uint32_t ssh_buffer_pass_bytes(struct ssh_buffer_struct *buffer, uint32_t len){ buffer_verify(buffer); @@ -699,11 +701,10 @@ uint32_t ssh_buffer_pass_bytes(struct ssh_buffer_struct *buffer, uint32_t len){ * * @brief Cut the end of the buffer. * - * @param[in] buffer The buffer to cut. - * - * @param[in] len The number of bytes to remove from the tail. + * @param[in] buffer The buffer to cut. + * @param[in] len The number of bytes to remove from the tail. * - * @return The new size of the buffer. + * @returns The new size of the buffer. */ uint32_t ssh_buffer_pass_bytes_end(struct ssh_buffer_struct *buffer, uint32_t len){ buffer_verify(buffer); @@ -720,13 +721,11 @@ uint32_t ssh_buffer_pass_bytes_end(struct ssh_buffer_struct *buffer, uint32_t le /** * @brief Get the remaining data out of the buffer and adjust the read pointer. * - * @param[in] buffer The buffer to read. + * @param[in] buffer The buffer to read. + * @param[in] data The data buffer where to store the data. + * @param[in] len The length to read from the buffer. * - * @param[in] data The data buffer where to store the data. - * - * @param[in] len The length to read from the buffer. - * - * @returns 0 if there is not enough data in buffer, len otherwise. + * @returns `0` if there is not enough data in buffer, `len` otherwise. */ uint32_t ssh_buffer_get_data(struct ssh_buffer_struct *buffer, void *data, uint32_t len) { @@ -751,11 +750,10 @@ uint32_t ssh_buffer_get_data(struct ssh_buffer_struct *buffer, void *data, uint3 * @brief Get a 8 bits unsigned int out of the buffer and adjust the read * pointer. * - * @param[in] buffer The buffer to read. + * @param[in] buffer The buffer to read. + * @param[in] data A pointer to a uint8_t where to store the data. * - * @param[in] data A pointer to a uint8_t where to store the data. - * - * @returns 0 if there is not enough data in buffer, 1 otherwise. + * @returns `0` if there is not enough data in buffer, `1` otherwise. */ uint32_t ssh_buffer_get_u8(struct ssh_buffer_struct *buffer, uint8_t *data){ return ssh_buffer_get_data(buffer,data,sizeof(uint8_t)); @@ -766,11 +764,10 @@ uint32_t ssh_buffer_get_u8(struct ssh_buffer_struct *buffer, uint8_t *data){ * * @brief gets a 32 bits unsigned int out of the buffer. Adjusts the read pointer. * - * @param[in] buffer The buffer to read. - * - * @param[in] data A pointer to a uint32_t where to store the data. + * @param[in] buffer The buffer to read. + * @param[in] data A pointer to a uint32_t where to store the data. * - * @returns 0 if there is not enough data in buffer, 4 otherwise. + * @returns `0` if there is not enough data in buffer, `4` otherwise. */ uint32_t ssh_buffer_get_u32(struct ssh_buffer_struct *buffer, uint32_t *data){ return ssh_buffer_get_data(buffer,data,sizeof(uint32_t)); @@ -781,11 +778,10 @@ uint32_t ssh_buffer_get_u32(struct ssh_buffer_struct *buffer, uint32_t *data){ * @brief Get a 64 bits unsigned int out of the buffer and adjusts the read * pointer. * - * @param[in] buffer The buffer to read. + * @param[in] buffer The buffer to read. + * @param[in] data A pointer to a uint64_t where to store the data. * - * @param[in] data A pointer to a uint64_t where to store the data. - * - * @returns 0 if there is not enough data in buffer, 8 otherwise. + * @returns `0` if there is not enough data in buffer, `8` otherwise. */ uint32_t ssh_buffer_get_u64(struct ssh_buffer_struct *buffer, uint64_t *data){ return ssh_buffer_get_data(buffer,data,sizeof(uint64_t)); @@ -794,11 +790,10 @@ uint32_t ssh_buffer_get_u64(struct ssh_buffer_struct *buffer, uint64_t *data){ /** * @brief Validates that the given length can be obtained from the buffer. * - * @param[in] buffer The buffer to read from. - * - * @param[in] len The length to be checked. + * @param[in] buffer The buffer to read from. + * @param[in] len The length to be checked. * - * @return SSH_OK if the length is valid, SSH_ERROR otherwise. + * @returns `SSH_OK` if the length is valid, `SSH_ERROR` otherwise. */ int ssh_buffer_validate_length(struct ssh_buffer_struct *buffer, size_t len) { @@ -815,9 +810,9 @@ int ssh_buffer_validate_length(struct ssh_buffer_struct *buffer, size_t len) * * @brief Get an SSH String out of the buffer and adjust the read pointer. * - * @param[in] buffer The buffer to read. + * @param[in] buffer The buffer to read. * - * @returns The SSH String, NULL on error. + * @returns The SSH String, `NULL` on error. */ struct ssh_string_struct * ssh_buffer_get_ssh_string(struct ssh_buffer_struct *buffer) @@ -858,15 +853,12 @@ ssh_buffer_get_ssh_string(struct ssh_buffer_struct *buffer) * This makes sure that enough memory is allocated for packing the buffer and * we only have to do one memory allocation. * - * @param[in] buffer The buffer to allocate - * - * @param[in] format A format string of arguments. + * @param[in] buffer The buffer to allocate + * @param[in] format A format string of arguments. + * @param[in] argc The number of arguments. + * @param[in] ap The va_list of arguments. * - * @param[in] argc The number of arguments. - * - * @param[in] ap The va_list of arguments. - * - * @return SSH_OK on success, SSH_ERROR on error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ static int ssh_buffer_pack_allocate_va(struct ssh_buffer_struct *buffer, const char *format, @@ -970,13 +962,17 @@ static int ssh_buffer_pack_allocate_va(struct ssh_buffer_struct *buffer, return SSH_OK; } -/** @internal +/** + * @internal + * * @brief Add multiple values in a buffer on a single function call - * @param[in] buffer The buffer to add to - * @param[in] format A format string of arguments. - * @param[in] ap A va_list of arguments. - * @returns SSH_OK on success - * SSH_ERROR on error + * + * @param[in] buffer The buffer to add to + * @param[in] format A format string of arguments. + * @param[in] ap A va_list of arguments. + * + * @returns `SSH_OK` on success, `SSH_ERROR` on error. + * * @see ssh_buffer_add_format() for format list values. */ static int @@ -1112,27 +1108,30 @@ ssh_buffer_pack_va(struct ssh_buffer_struct *buffer, return rc; } -/** @internal +/** + * @internal + * * @brief Add multiple values in a buffer on a single function call - * @param[in] buffer The buffer to add to - * @param[in] format A format string of arguments. This string contains single - * letters describing the order and type of arguments: - * 'b': uint8_t (pushed in network byte order) - * 'w': uint16_t (pushed in network byte order) - * 'd': uint32_t (pushed in network byte order) - * 'q': uint64_t (pushed in network byte order) - * 'S': ssh_string - * 's': char * (C string, pushed as SSH string) - * 't': char * (C string, pushed as free text) - * 'P': size_t, void * (len of data, pointer to data) - * only pushes data. - * 'B': bignum (pushed as SSH string) - * 'F': bignum, size_t (bignum, padded to fixed length, - * pushed as SSH string) - * @returns SSH_OK on success - * SSH_ERROR on error - * @warning when using 'P' with a constant size (e.g. 8), do not - * forget to cast to (size_t). + * + * @param[in] buffer The buffer to add to + * @param[in] format A format string of arguments. This string contains single + * letters describing the order and type of arguments: + * 'b': uint8_t (pushed in network byte order) + * 'w': uint16_t (pushed in network byte order) + * 'd': uint32_t (pushed in network byte order) + * 'q': uint64_t (pushed in network byte order) + * 'S': ssh_string + * 's': char * (C string, pushed as SSH string) + * 't': char * (C string, pushed as free text) + * 'P': size_t, void * (len of data, pointer to data) + * only pushes data. + * 'B': bignum (pushed as SSH string) + * 'F': bignum, size_t (bignum, padded to fixed length, + * pushed as SSH string) + * + * @returns `SSH_OK` on success, `SSH_ERROR` on error. + * + * @warning when using 'P' with a constant size (e.g. 8), do not forget to cast to (size_t). */ int _ssh_buffer_pack(struct ssh_buffer_struct *buffer, const char *format, @@ -1161,13 +1160,17 @@ int _ssh_buffer_pack(struct ssh_buffer_struct *buffer, return rc; } -/** @internal +/** + * @internal + * * @brief Get multiple values from a buffer on a single function call - * @param[in] buffer The buffer to get from - * @param[in] format A format string of arguments. - * @param[in] ap A va_list of arguments. - * @returns SSH_OK on success - * SSH_ERROR on error + * + * @param[in] buffer The buffer to get from + * @param[in] format A format string of arguments. + * @param[in] ap A va_list of arguments. + * + * @returns `SSH_OK` on success, `SSH_ERROR` on error. + * * @see ssh_buffer_get_format() for format list values. */ int ssh_buffer_unpack_va(struct ssh_buffer_struct *buffer, @@ -1414,24 +1417,28 @@ cleanup: return rc; } -/** @internal +/** + * @internal + * * @brief Get multiple values from a buffer on a single function call - * @param[in] buffer The buffer to get from - * @param[in] format A format string of arguments. This string contains single - * letters describing the order and type of arguments: - * 'b': uint8_t * (pulled in network byte order) - * 'w': uint16_t * (pulled in network byte order) - * 'd': uint32_t * (pulled in network byte order) - * 'q': uint64_t * (pulled in network byte order) - * 'S': ssh_string * - * 's': char ** (C string, pulled as SSH string) - * 'P': size_t, void ** (len of data, pointer to data) - * only pulls data. - * 'B': bignum * (pulled as SSH string) - * @returns SSH_OK on success - * SSH_ERROR on error - * @warning when using 'P' with a constant size (e.g. 8), do not - * forget to cast to (size_t). + * + * @param[in] buffer The buffer to get from + * @param[in] format A format string of arguments. This string contains single + * letters describing the order and type of arguments: + * 'b': uint8_t * (pulled in network byte order) + * 'w': uint16_t * (pulled in network byte order) + * 'd': uint32_t * (pulled in network byte order) + * 'q': uint64_t * (pulled in network byte order) + * 'S': ssh_string * + * 's': char ** (C string, pulled as SSH string) + * 'P': size_t, void ** (len of data, pointer to data) + * only pulls data. + * 'B': bignum * (pulled as SSH string) + * + * @returns `SSH_OK` on success, `SSH_ERROR` on error. + * + * @warning when using 'P' with a constant size (e.g. 8), do not forget + * to cast to (size_t). */ int _ssh_buffer_unpack(struct ssh_buffer_struct *buffer, const char *format, -- GitLab From 5b7be70c7834150c655bbea0d88d1f105fdad3da Mon Sep 17 00:00:00 2001 From: ashutoshsao Date: Wed, 10 Dec 2025 21:20:51 +0530 Subject: [PATCH 3/9] error.c: Improve doxygen documentation Signed-off-by: ashutoshsao --- src/error.c | 43 +++++++++++++++++++------------------------ 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/src/error.c b/src/error.c index 3f8d78cd8..af8d606a5 100644 --- a/src/error.c +++ b/src/error.c @@ -42,13 +42,10 @@ * * @brief Registers an error with a description. * - * @param error The place to store the error. - * - * @param code The class of error. - * - * @param descr The description, which can be a format string. - * - * @param ... The arguments for the format string. + * @param error The place to store the error. + * @param code The class of error. + * @param descr The description, which can be a format string. + * @param ... The arguments for the format string. */ void _ssh_set_error(void *error, int code, @@ -75,8 +72,7 @@ void _ssh_set_error(void *error, * * @brief Registers an out of memory error * - * @param error The place to store the error. - * + * @param error The place to store the error. */ void _ssh_set_error_oom(void *error, const char *function) { @@ -92,10 +88,8 @@ void _ssh_set_error_oom(void *error, const char *function) * * @brief Registers an invalid argument error * - * @param error The place to store the error. - * - * @param function The function the error happened in. - * + * @param error The place to store the error. + * @param function The function the error happened in. */ void _ssh_set_error_invalid(void *error, const char *function) { @@ -108,7 +102,7 @@ void _ssh_set_error_invalid(void *error, const char *function) * * @brief Reset the error code and message * - * @param error The place to reset the error. + * @param error The place to reset the error. */ void ssh_reset_error(void *error) { @@ -121,9 +115,9 @@ void ssh_reset_error(void *error) /** * @brief Retrieve the error text message from the last error. * - * @param error An ssh_session or ssh_bind. + * @param error An ssh_session or ssh_bind. * - * @return A static string describing the error. + * @returns A static string describing the error. */ const char *ssh_get_error(void *error) { struct error_struct *err = error; @@ -134,16 +128,17 @@ const char *ssh_get_error(void *error) { /** * @brief Retrieve the error code from the last error. * - * @param error An ssh_session or ssh_bind. + * @param error An ssh_session or ssh_bind. * - * \return SSH_NO_ERROR No error occurred\n - * SSH_REQUEST_DENIED The last request was denied but situation is - * recoverable\n - * SSH_FATAL A fatal error occurred. This could be an unexpected - * disconnection\n + * @returns + * - `SSH_NO_ERROR`: No error occurred + * - `SSH_REQUEST_DENIED`: The last request was denied but situation is + * recoverable + * - `SSH_FATAL`: A fatal error occurred. This could be an unexpected + * disconnection * - * Other error codes are internal but can be considered the same as - * SSH_FATAL. + * @note Other error codes are internal but can be considered the same as + * `SSH_FATAL`. */ int ssh_get_error_code(void *error) { struct error_struct *err = error; -- GitLab From fcf3c323210de27277a38f3bf14bbad96c336498 Mon Sep 17 00:00:00 2001 From: ashutoshsao Date: Wed, 10 Dec 2025 21:29:04 +0530 Subject: [PATCH 4/9] init.c: Improve doxygen documentation Signed-off-by: ashutoshsao --- src/init.c | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/init.c b/src/init.c index e516c3318..efedf8c4d 100644 --- a/src/init.c +++ b/src/init.c @@ -149,7 +149,7 @@ void libssh_constructor(void) * If the library is already initialized, increments the _ssh_initialized * counter and return the error code cached in _ssh_init_ret. * - * @returns SSH_OK on success, SSH_ERROR if an error occurred. + * @returns `SSH_OK` on success, `SSH_ERROR` if an error occurred. * * @see ssh_finalize() */ @@ -234,7 +234,7 @@ void libssh_destructor(void) * When called, decrements the counter _ssh_initialized. If the counter reaches * zero, then the libssh and cryptographic data structures are cleaned up. * - * @returns 0 on success, -1 if an error occurred. + * @returns `SSH_OK` on success, `SSH_ERROR` if an error occurred. * * @see ssh_init() */ @@ -275,9 +275,10 @@ BOOL WINAPI DllMain(HINSTANCE hinstDLL, /** * @internal + * * @brief Return whether the library is initialized * - * @returns true if the library is initialized; false otherwise. + * @returns `true` if the library is initialized; `false` otherwise. * * @see ssh_init() */ -- GitLab From 0240b8140b8e036b9141c824935fac185db655ff Mon Sep 17 00:00:00 2001 From: ashutoshsao Date: Wed, 10 Dec 2025 21:45:18 +0530 Subject: [PATCH 5/9] log.c: Improve doxygen documentation Signed-off-by: ashutoshsao --- src/log.c | 45 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 10 deletions(-) diff --git a/src/log.c b/src/log.c index 8bc8ccabd..8f726c621 100644 --- a/src/log.c +++ b/src/log.c @@ -109,6 +109,13 @@ static void ssh_log_custom(ssh_logging_callback log_fn, log_fn(verbosity, function, buf, ssh_get_log_userdata()); } +/** + * @brief Log a function with a given verbosity and buffer. + * + * @param verbosity The verbosity of the log. + * @param function The function name. + * @param buffer The buffer to log. + */ void ssh_log_function(int verbosity, const char *function, const char *buffer) @@ -123,6 +130,14 @@ void ssh_log_function(int verbosity, ssh_log_stderr(verbosity, function, buffer); } +/** + * @brief Log a function with a given verbosity and buffer. + * + * @param verbosity The verbosity of the log. + * @param function The function name. + * @param format The format string of the log. + * @param va The va_list of the log. + */ void ssh_vlog(int verbosity, const char *function, const char *format, @@ -134,6 +149,13 @@ void ssh_vlog(int verbosity, ssh_log_function(verbosity, function, buffer); } +/** + * @brief Log a function with a given verbosity and format. + * + * @param verbosity The verbosity of the log. + * @param function The function name. + * @param format The format string of the log. + */ void _ssh_log(int verbosity, const char *function, const char *format, ...) @@ -162,11 +184,14 @@ void ssh_log(ssh_session session, } } -/** @internal +/** + * @internal + * * @brief log a SSH event with a common pointer - * @param common The SSH/bind session. - * @param verbosity The verbosity of the event. - * @param format The format string of the log entry. + * + * @param common The SSH/bind session. + * @param verbosity The verbosity of the event. + * @param format The format string of the log entry. */ void ssh_log_common(struct ssh_common_struct *common, int verbosity, @@ -188,9 +213,9 @@ void ssh_log_common(struct ssh_common_struct *common, /** * @brief Set the log level of the library. * - * @param[in] level The level to set. + * @param[in] level The level to set. * - * @return SSH_OK on success, SSH_ERROR on error. + * @return `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_set_log_level(int level) { if (level < 0) { @@ -205,7 +230,7 @@ int ssh_set_log_level(int level) { /** * @brief Get the log level of the library. * - * @return The value of the log level. + * @returns The value of the log level. */ int ssh_get_log_level(void) { return ssh_log_level; @@ -234,7 +259,7 @@ ssh_logging_callback ssh_get_log_callback(void) { /** * @brief Get the userdata of the logging function. * - * @return The userdata if set or NULL. + * @returns The userdata if set or `NULL`. */ void *ssh_get_log_userdata(void) { @@ -248,9 +273,9 @@ void *ssh_get_log_userdata(void) /** * @brief Set the userdata for the logging function. * - * @param[in] data The userdata to set. + * @param[in] data The userdata to set. * - * @return SSH_OK on success. + * @returns `SSH_OK` on success. */ int ssh_set_log_userdata(void *data) { -- GitLab From 49f216e8f4df691eba3072044fbf13e1137b02cf Mon Sep 17 00:00:00 2001 From: ashutoshsao Date: Wed, 10 Dec 2025 05:14:15 +0530 Subject: [PATCH 6/9] auth.c: Improve doxygen documentation Signed-off-by: ashutoshsao --- src/auth.c | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/src/auth.c b/src/auth.c index 9966ef362..2383b87d1 100644 --- a/src/auth.c +++ b/src/auth.c @@ -417,6 +417,7 @@ SSH_PACKET_CALLBACK(ssh_packet_userauth_pk_ok) { * - `SSH_AUTH_METHOD_PUBLICKEY` * - `SSH_AUTH_METHOD_HOSTBASED` * - `SSH_AUTH_METHOD_INTERACTIVE` + * - `SSH_AUTH_METHOD_GSSAPI_MIC` * * @warning Other reserved flags may appear in future versions. * @see ssh_userauth_none() @@ -1372,9 +1373,10 @@ struct ssh_auth_auto_state_struct { * @param[out] value The value to get into. As a `char**`, space will be * allocated by the function for the value, it is * your responsibility to free the memory using - * `ssh_string_free_char()`. + * ssh_string_free_char(). * * @return `SSH_OK` on success, `SSH_ERROR` on error. + * @see ssh_string_free_char() */ int ssh_userauth_publickey_auto_get_current_identity(ssh_session session, char** value) @@ -1887,9 +1889,7 @@ int ssh_userauth_agent_pubkey(ssh_session session, * * @brief Create a new keyboard-interactive object. * - * @return - * - `ssh_kbdint`: The keyboard-interactive object was created. - * - `NULL`: If an error occurred. + * @return The keyboard-interactive object was created or `NULL` if an error occurred. */ ssh_kbdint ssh_kbdint_new(void) { @@ -2300,9 +2300,7 @@ int ssh_userauth_kbdint(ssh_session session, const char *user, * * @param[in] session The ssh session to use. * - * @returns - * - `session->kbdint->nprompts`: The number of prompts. - * - `SSH_ERROR`: If an error occurred. + * @returns The number of prompts or `SSH_ERROR` if an error occurred. */ int ssh_userauth_kbdint_getnprompts(ssh_session session) { @@ -2350,7 +2348,6 @@ const char *ssh_userauth_kbdint_getname(ssh_session session) * * @returns The instruction of the message block. Do not free it. */ - const char *ssh_userauth_kbdint_getinstruction(ssh_session session) { if (session == NULL) @@ -2461,9 +2458,7 @@ const char *ssh_userauth_kbdint_getanswer(ssh_session session, unsigned int i) * answer in some other encoding, you MUST convert it to * UTF-8. * - * @returns - * - `SSH_OK`: On success. - * - `SSH_ERROR`: On error. + * @returns `SSH_OK` on success, `SSH_ERROR` on error. */ int ssh_userauth_kbdint_setanswer(ssh_session session, unsigned int i, -- GitLab From d0a1ac28c4dcfbff9e304043730be20d84425f34 Mon Sep 17 00:00:00 2001 From: ashutoshsao Date: Wed, 10 Dec 2025 21:04:40 +0530 Subject: [PATCH 7/9] buffer.c: Improve doxygen documentation Signed-off-by: ashutoshsao --- src/buffer.c | 45 ++++++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/src/buffer.c b/src/buffer.c index 95b9df5ee..f24235dee 100644 --- a/src/buffer.c +++ b/src/buffer.c @@ -179,6 +179,8 @@ void ssh_buffer_set_secure(ssh_buffer buffer) buffer->secure = true; } /** + * @internal + * * @brief Realloc the buffer. * * This function reallocates the buffer to the given size. @@ -1116,18 +1118,17 @@ ssh_buffer_pack_va(struct ssh_buffer_struct *buffer, * @param[in] buffer The buffer to add to * @param[in] format A format string of arguments. This string contains single * letters describing the order and type of arguments: - * 'b': uint8_t (pushed in network byte order) - * 'w': uint16_t (pushed in network byte order) - * 'd': uint32_t (pushed in network byte order) - * 'q': uint64_t (pushed in network byte order) - * 'S': ssh_string - * 's': char * (C string, pushed as SSH string) - * 't': char * (C string, pushed as free text) - * 'P': size_t, void * (len of data, pointer to data) - * only pushes data. - * 'B': bignum (pushed as SSH string) - * 'F': bignum, size_t (bignum, padded to fixed length, - * pushed as SSH string) + * - 'b': uint8_t (pushed in network byte order) + * - 'w': uint16_t (pushed in network byte order) + * - 'd': uint32_t (pushed in network byte order) + * - 'q': uint64_t (pushed in network byte order) + * - 'S': ssh_string + * - 's': char * (C string, pushed as SSH string) + * - 't': char * (C string, pushed as free text) + * - 'P': size_t, void * (len of data, pointer to data) only pushes data. + * - 'B': bignum (pushed as SSH string) + * - 'F': bignum, size_t (bignum, padded to fixed length, pushed as SSH string) + * @param[in] ... The arguments for the format string. * * @returns `SSH_OK` on success, `SSH_ERROR` on error. * @@ -1425,15 +1426,17 @@ cleanup: * @param[in] buffer The buffer to get from * @param[in] format A format string of arguments. This string contains single * letters describing the order and type of arguments: - * 'b': uint8_t * (pulled in network byte order) - * 'w': uint16_t * (pulled in network byte order) - * 'd': uint32_t * (pulled in network byte order) - * 'q': uint64_t * (pulled in network byte order) - * 'S': ssh_string * - * 's': char ** (C string, pulled as SSH string) - * 'P': size_t, void ** (len of data, pointer to data) - * only pulls data. - * 'B': bignum * (pulled as SSH string) + * - 'b': uint8_t * (pulled in network byte order) + * - 'w': uint16_t * (pulled in network byte order) + * - 'd': uint32_t * (pulled in network byte order) + * - 'q': uint64_t * (pulled in network byte order) + * - 'S': ssh_string * + * - 's': char ** (C string, pulled as SSH string) + * - 'P': size_t, void ** (len of data, pointer to data) + * only pulls data. + * - 'B': bignum * (pulled as SSH string) + * @param[in] argc Number of pointers following this argument + * @param[in] ... The pointers to receive the parsed values * * @returns `SSH_OK` on success, `SSH_ERROR` on error. * -- GitLab From 67eda54dc05bea638cd2befa3a2382a8a305d59c Mon Sep 17 00:00:00 2001 From: ashutoshsao Date: Wed, 10 Dec 2025 21:45:18 +0530 Subject: [PATCH 8/9] log.c: Improve doxygen documentation Signed-off-by: ashutoshsao --- src/log.c | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/log.c b/src/log.c index 8f726c621..96af34f03 100644 --- a/src/log.c +++ b/src/log.c @@ -110,6 +110,8 @@ static void ssh_log_custom(ssh_logging_callback log_fn, } /** + * @internal + * * @brief Log a function with a given verbosity and buffer. * * @param verbosity The verbosity of the log. @@ -155,6 +157,7 @@ void ssh_vlog(int verbosity, * @param verbosity The verbosity of the log. * @param function The function name. * @param format The format string of the log. + * @param ... Arguments for format specification. */ void _ssh_log(int verbosity, const char *function, @@ -192,6 +195,7 @@ void ssh_log(ssh_session session, * @param common The SSH/bind session. * @param verbosity The verbosity of the event. * @param format The format string of the log entry. + * @param ... Arguments for format specification. */ void ssh_log_common(struct ssh_common_struct *common, int verbosity, -- GitLab From 214eaf24a8cb7a9827596b2750e9d8b2f7900bc1 Mon Sep 17 00:00:00 2001 From: ashutoshsao Date: Fri, 12 Dec 2025 11:32:12 +0530 Subject: [PATCH 9/9] log.c: Fix return value in ssh_set_log_userdata Change return 0 to SSH_OK for consistency with other functions. Signed-off-by: ashutoshsao --- src/log.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/log.c b/src/log.c index 96af34f03..51a282700 100644 --- a/src/log.c +++ b/src/log.c @@ -285,7 +285,7 @@ int ssh_set_log_userdata(void *data) { ssh_log_userdata = data; - return 0; + return SSH_OK; } /** @} */ -- GitLab