From 9931f158e010672f20d4f931ad7017256a19f0d1 Mon Sep 17 00:00:00 2001 From: Norbert Pocs Date: Tue, 3 Jan 2023 14:15:05 +0100 Subject: [PATCH] server: Add documentation to some functions Signed-off-by: Norbert Pocs Reviewed-by: Jakub Jelen --- include/libssh/server.h | 11 +++++-- src/server.c | 65 +++++++++++++++++++++++++++++++++++------ 2 files changed, 64 insertions(+), 12 deletions(-) diff --git a/include/libssh/server.h b/include/libssh/server.h index fb7132df..80f74e1a 100644 --- a/include/libssh/server.h +++ b/include/libssh/server.h @@ -296,7 +296,7 @@ LIBSSH_API const char *ssh_message_auth_user(ssh_message msg); * * @see ssh_message_get() * @see ssh_message_type() - * @warning This function should not be used anymore as there is a + * @deprecated This function should not be used anymore as there is a * callback based server implementation now auth_password_function. */ SSH_DEPRECATED LIBSSH_API const char *ssh_message_auth_password(ssh_message msg); @@ -314,14 +314,19 @@ SSH_DEPRECATED LIBSSH_API const char *ssh_message_auth_password(ssh_message msg) * @see ssh_key_cmp() * @see ssh_message_get() * @see ssh_message_type() - * @warning This function should not be used anymore as there is a + * @deprecated This function should not be used anymore as there is a * callback based server implementation auth_pubkey_function. */ SSH_DEPRECATED LIBSSH_API ssh_key ssh_message_auth_pubkey(ssh_message msg); LIBSSH_API int ssh_message_auth_kbdint_is_response(ssh_message msg); -/* Replaced by callback based server implementation auth_pubkey_function */ +/** + * @param[in] msg The message to get the public key state from. + * + * @deprecated This function should not be used anymore as there is a + * callback based server implementation auth_pubkey_function + */ SSH_DEPRECATED LIBSSH_API enum ssh_publickey_state_e ssh_message_auth_publickey_state(ssh_message msg); LIBSSH_API int ssh_message_auth_reply_success(ssh_message msg,int partial); diff --git a/src/server.c b/src/server.c index 0bc612eb..9ed2b0c8 100644 --- a/src/server.c +++ b/src/server.c @@ -728,6 +728,15 @@ int ssh_message_service_reply_success(ssh_message msg) { return rc; } +/** + * @brief Send a global request success message + * + * @param msg The message + * + * @param bound_port The remote bind port + * + * @returns SSH_OK on success, otherwise SSH_ERROR + */ int ssh_message_global_request_reply_success(ssh_message msg, uint16_t bound_port) { int rc; @@ -844,7 +853,6 @@ ssh_key ssh_message_auth_pubkey(ssh_message msg) { return msg->auth_request.pubkey; } -/* Get the publickey of an auth request */ ssh_public_key ssh_message_auth_publickey(ssh_message msg){ if (msg == NULL) { return NULL; @@ -853,13 +861,6 @@ ssh_public_key ssh_message_auth_publickey(ssh_message msg){ return ssh_pki_convert_key_to_publickey(msg->auth_request.pubkey); } -/** - * @brief Get the state of the public key authentication process - * - * @param msg The message - * - * @returns state of the authentication - */ enum ssh_publickey_state_e ssh_message_auth_publickey_state(ssh_message msg){ if (msg == NULL) { return -1; @@ -867,6 +868,13 @@ enum ssh_publickey_state_e ssh_message_auth_publickey_state(ssh_message msg){ return msg->auth_request.signature_state; } +/** + * @brief Check if the message is a keyboard-interactive response + * + * @param msg The message to check + * + * @returns 1 if the message is a response, otherwise 0 + */ int ssh_message_auth_kbdint_is_response(ssh_message msg) { if (msg == NULL) { return -1; @@ -876,6 +884,17 @@ int ssh_message_auth_kbdint_is_response(ssh_message msg) { } /* FIXME: methods should be unsigned */ +/** + * @brief Sets the supported authentication methods to a message + * + * @param msg The message + * + * @param methods Methods to set to the message. + * The supported methods are listed in ssh_set_auth_methods + * @see ssh_set_auth_methods + * + * @returns 0 on success, otherwise -1 + */ int ssh_message_auth_set_methods(ssh_message msg, int methods) { if (msg == NULL || msg->session == NULL) { return -1; @@ -995,6 +1014,17 @@ int ssh_message_auth_interactive_request(ssh_message msg, const char *name, return rc; } +/** + * @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 + */ int ssh_auth_reply_success(ssh_session session, int partial) { struct ssh_crypto_struct *crypto = NULL; @@ -1044,7 +1074,17 @@ int ssh_message_auth_reply_success(ssh_message msg, int partial) { return ssh_auth_reply_success(msg->session, partial); } -/* Answer OK to a pubkey auth request */ +/** + * @brief Answer SSH2_MSG_USERAUTH_PK_OK to a pubkey authentication request + * + * @param msg The message + * + * @param algo The algorithm of the accepted public key + * + * @param pubkey The accepted public key + * + * @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; if (msg == NULL) { @@ -1065,6 +1105,13 @@ int ssh_message_auth_reply_pk_ok(ssh_message msg, ssh_string algo, ssh_string pu return rc; } +/** + * @brief Answer SSH2_MSG_USERAUTH_PK_OK to a pubkey authentication request + * + * @param msg The message + * + * @returns SSH_OK on success, otherwise SSH_ERROR + */ int ssh_message_auth_reply_pk_ok_simple(ssh_message msg) { ssh_string algo; ssh_string pubkey_blob = NULL;