Update doc blocks

src/bruteforce_ssh.c

@@ -1,5 +1,5 @@
 /*
-Copyright (c) 2014-2018 Jorge Matricali
+Copyright (c) 2014-2024 Jorge Matricali
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -33,6 +33,21 @@ SOFTWARE.
 
 static pthread_mutex_t bflock = PTHREAD_MUTEX_INITIALIZER;
 
+/**
+ * Attempt to brute-force SSH login using the provided credentials.
+ *
+ * This function tries to log in to the SSH server using the specified hostname,
+ * port, username, and password. It performs the brute-force attempt and handles
+ * any related errors.
+ *
+ * @param context   The context containing options and configurations for brute-force.
+ * @param hostname  The hostname of the SSH server.
+ * @param port      The port of the SSH server.
+ * @param username  The username to use for the login attempt.
+ * @param password  The password to use for the login attempt.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
 int bruteforce_ssh_login(btkg_context_t *context, const char *hostname,
 			 uint16_t port, const char *username,
 			 const char *password)
@@ -116,6 +131,20 @@ int bruteforce_ssh_login(btkg_context_t *context, const char *hostname,
 	return -1;
 }
 
+/**
+ * Try to log in to an SSH server with the specified credentials.
+ *
+ * This function tries a single login attempt using the provided credentials and
+ * returns the result of the attempt.
+ *
+ * @param context   The context containing options and configurations for brute-force.
+ * @param hostname  The hostname of the SSH server.
+ * @param port      The port of the SSH server.
+ * @param username  The username to use for the login attempt.
+ * @param password  The password to use for the login attempt.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
 int bruteforce_ssh_try_login(btkg_context_t *context, const char *hostname,
 			     const uint16_t port, const char *username,
 			     const char *password)
@@ -143,6 +172,16 @@ int bruteforce_ssh_try_login(btkg_context_t *context, const char *hostname,
 	return ret;
 }
 
+/**
+ * Worker function for brute-force SSH login attempts.
+ *
+ * This function is executed by each worker thread to perform brute-force SSH login attempts
+ * on the specified targets using the provided credentials.
+ *
+ * @param ptr  Pointer to the context containing targets, credentials, and options.
+ *
+ * @return NULL when the worker completes its task.
+ */
 static void *btkg_bruteforce_worker(void *ptr)
 {
 	btkg_context_t *context = (btkg_context_t *)ptr;
@@ -198,6 +237,14 @@ static void *btkg_bruteforce_worker(void *ptr)
 	return NULL;
 }
 
+/**
+ * Start the brute-force SSH login process.
+ *
+ * This function initializes and starts the brute-force process, including setting
+ * up necessary threads and handling the brute-force attack.
+ *
+ * @param context   The context containing options and configurations for brute-force.
+ */
 void btkg_bruteforce_start(btkg_context_t *context)
 {
 	btkg_options_t *options = &context->options;

src/bruteforce_ssh.h

@@ -1,5 +1,5 @@
 /*
-Copyright (c) 2014-2018 Jorge Matricali
+Copyright (c) 2014-2024 Jorge Matricali
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -27,14 +27,51 @@ SOFTWARE.
 
 #include "cbrutekrag.h"
 
+/**
+ * Attempt to brute-force SSH login using the provided credentials.
+ *
+ * This function tries to log in to the SSH server using the specified hostname,
+ * port, username, and password. It performs the brute-force attempt and handles
+ * any related errors.
+ *
+ * @param context   The context containing options and configurations for brute-force.
+ * @param hostname  The hostname of the SSH server.
+ * @param port      The port of the SSH server.
+ * @param username  The username to use for the login attempt.
+ * @param password  The password to use for the login attempt.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
 int bruteforce_ssh_login(btkg_context_t *context, const char *hostname,
 			 uint16_t port, const char *username,
 			 const char *password);
 
+/**
+ * Try to log in to an SSH server with the specified credentials.
+ *
+ * This function tries a single login attempt using the provided credentials and
+ * returns the result of the attempt.
+ *
+ * @param context   The context containing options and configurations for brute-force.
+ * @param hostname  The hostname of the SSH server.
+ * @param port      The port of the SSH server.
+ * @param username  The username to use for the login attempt.
+ * @param password  The password to use for the login attempt.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
 int bruteforce_ssh_try_login(btkg_context_t *context, const char *hostname,
 			     const uint16_t port, const char *username,
 			     const char *password);
 
+/**
+ * Start the brute-force SSH login process.
+ *
+ * This function initializes and starts the brute-force process, including setting
+ * up necessary threads and handling the brute-force attack.
+ *
+ * @param context   The context containing options and configurations for brute-force.
+ */
 void btkg_bruteforce_start(btkg_context_t *context);
 
-#endif /* BRUTEFORCE_SSH_H */
+#endif // BRUTEFORCE_SSH_H

src/compat.h

@@ -1,5 +1,5 @@
 /*
-Copyright (c) 2014-2018 Jorge Matricali
+Copyright (c) 2014-2024 Jorge Matricali
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -20,13 +20,49 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 */
 
+/**
+ * @file compat.h
+ * @brief Compatibility layer for systems lacking certain standard library functions.
+ *
+ * This header provides declarations for functions that may not be available
+ * on all platforms. If the functions are not available, they are implemented
+ * elsewhere in the codebase to ensure compatibility across different systems.
+ */
+
 #ifndef COMPAT_H
 #define COMPAT_H
 
+#include <stdio.h>
+
+/**
+ * @brief Read a delimited record from a stream.
+ *
+ * This function reads a line from the specified stream, delimited by the
+ * specified character. It is intended for platforms that do not support
+ * the `getdelim` function.
+ *
+ * @param buf Pointer to the buffer where the line should be stored.
+ * @param bufsiz Pointer to the size of the buffer.
+ * @param delimiter The character that delimits the record.
+ * @param fp The file stream to read from.
+ * @return The number of characters read, or -1 on error or end of file.
+ */
 #if !HAVE_GETDELIM
 ssize_t getdelim(char **buf, size_t *bufsiz, int delimiter, FILE *fp);
 #endif
 
+/**
+ * @brief Read an entire line from a stream.
+ *
+ * This function reads a line from the specified stream, stopping at the end
+ * of the line or the end of the file. It is intended for platforms that do not
+ * support the `getline` function.
+ *
+ * @param buf Pointer to the buffer where the line should be stored.
+ * @param bufsiz Pointer to the size of the buffer.
+ * @param fp The file stream to read from.
+ * @return The number of characters read, or -1 on error or end of file.
+ */
 #if !HAVE_GETLINE
 ssize_t getline(char **buf, size_t *bufsiz, FILE *fp);
 #endif

src/credentials.c

@@ -30,6 +30,14 @@ SOFTWARE.
 
 char *g_blankpass_placeholder = "$BLANKPASS";
 
+/**
+ * @brief Parses a line into a btkg_credentials_t structure.
+ *
+ * @param line The line to parse.
+ * @param dst Pointer to the btkg_credentials_t structure to fill with parsed data.
+ *
+ * @return 0 on success, non-zero on failure.
+ */
 int btkg_credentials_parse(char *line, btkg_credentials_t *dst)
 {
 	dst->username[0] = '\0';
@@ -51,7 +59,9 @@ int btkg_credentials_parse(char *line, btkg_credentials_t *dst)
 }
 
 /**
- * Initialize btkg_credentials_list_t
+ * @brief Initializes a btkg_credentials_list_t structure.
+ *
+ * @param credentials Pointer to the btkg_credentials_list_t structure to initialize.
  */
 void btkg_credentials_list_init(btkg_credentials_list_t *credentials)
 {
@@ -60,8 +70,10 @@ void btkg_credentials_list_init(btkg_credentials_list_t *credentials)
 }
 
 /**
- * Loads credentials from a given file and append them into the given
- * btkg_credentials_list_t
+ * @brief Loads credentials from a given file and appends them into the given btkg_credentials_list_t.
+ *
+ * @param credentials_list Pointer to the btkg_credentials_list_t structure to append the loaded credentials to.
+ * @param filename The name of the file to load the credentials from.
  */
 void btkg_credentials_list_load(btkg_credentials_list_t *credentials_list,
 				char *filename)
@@ -96,7 +108,10 @@ void btkg_credentials_list_load(btkg_credentials_list_t *credentials_list,
 }
 
 /**
- * Append btkg_credentials_t into given btkg_credentials_list_t
+ * @brief Appends a btkg_credentials_t structure into a given btkg_credentials_list_t.
+ *
+ * @param credentials_list Pointer to the btkg_credentials_list_t structure to append the credentials to.
+ * @param new The btkg_credentials_t structure to append.
  */
 void btkg_credentials_list_append(btkg_credentials_list_t *credentials_list,
 				  btkg_credentials_t new)
@@ -117,6 +132,11 @@ void btkg_credentials_list_append(btkg_credentials_list_t *credentials_list,
 	credentials_list->credentials = credentials;
 }
 
+/**
+ * @brief Frees the memory allocated for a btkg_credentials_list_t structure.
+ *
+ * @param credentials_list Pointer to the btkg_credentials_list_t structure to free.
+ */
 void btkg_credentials_list_destroy(btkg_credentials_list_t *credentials_list)
 {
 	free(credentials_list->credentials);

src/credentials.h

@@ -1,5 +1,5 @@
 /*
-Copyright (c) 2014-2018 Jorge Matricali
+Copyright (c) 2014-2024 Jorge Matricali
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -43,31 +43,45 @@ typedef struct {
 } btkg_credentials_list_t;
 
 /**
- * Initialize btkg_credentials_list_t
+ * @brief Initializes a btkg_credentials_list_t structure.
+ *
+ * @param credentials Pointer to the btkg_credentials_list_t structure to initialize.
  */
 void btkg_credentials_list_init(btkg_credentials_list_t *credentials);
 
 /**
- * Parse line into btkg_credentials_t structure
+ * @brief Parses a line into a btkg_credentials_t structure.
+ *
+ * @param line The line to parse.
+ * @param dst Pointer to the btkg_credentials_t structure to fill with parsed data.
+ *
+ * @return 0 on success, non-zero on failure.
  */
 int btkg_credentials_parse(char *line, btkg_credentials_t *dst);
 
 /**
- * Loads credentials from a given file and append them into the given
- * btkg_credentials_list_t
+ * @brief Loads credentials from a given file and appends them into the given btkg_credentials_list_t.
+ *
+ * @param credentials_list Pointer to the btkg_credentials_list_t structure to append the loaded credentials to.
+ * @param filename The name of the file to load the credentials from.
  */
 void btkg_credentials_list_load(btkg_credentials_list_t *credentials_list,
 				char *filename);
 
 /**
- * Append btkg_credentials_t into given btkg_credentials_list_t
+ * @brief Appends a btkg_credentials_t structure into a given btkg_credentials_list_t.
+ *
+ * @param credentials_list Pointer to the btkg_credentials_list_t structure to append the credentials to.
+ * @param new The btkg_credentials_t structure to append.
  */
 void btkg_credentials_list_append(btkg_credentials_list_t *credentials_list,
 				  btkg_credentials_t new);
 
 /**
- * Free btkg_credentials_list_t
+ * @brief Frees the memory allocated for a btkg_credentials_list_t structure.
+ *
+ * @param credentials_list Pointer to the btkg_credentials_list_t structure to free.
  */
 void btkg_credentials_list_destroy(btkg_credentials_list_t *credentials_list);
 
-#endif /* __BTKG_CREDENTIALS_H */
+#endif // __BTKG_CREDENTIALS_H