From 23e4fd6a2b8d925fb257aabfb6636038f2097191 Mon Sep 17 00:00:00 2001 From: Jonathan Bennett Date: Mon, 11 Apr 2016 11:28:40 -0500 Subject: [PATCH] Adds more Doxygen documentation in preparation for 2.6.9 --- Doxyfile | 2 +- server/access.c | 39 ++++++++++--- server/access.h | 125 +++++++++++++++++++++++++++++++++++++++- server/cmd_cycle.h | 31 ++++++++++ server/cmd_opts.h | 2 +- server/config_init.h | 31 +++++++++- server/extcmd.h | 90 +++++++++++++++++++++++++++++ server/fwknopd.h | 33 +++++++++-- server/fwknopd_common.h | 9 +++ server/fwknopd_errors.h | 12 ++++ server/incoming_spa.h | 10 ++++ server/nfq_capture.c | 12 ++-- server/nfq_capture.h | 12 ++-- 13 files changed, 379 insertions(+), 29 deletions(-) diff --git a/Doxyfile b/Doxyfile index f6fac05b..d81031c9 100644 --- a/Doxyfile +++ b/Doxyfile @@ -38,7 +38,7 @@ PROJECT_NAME = Fwknop # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 2.6.8 +PROJECT_NUMBER = 2.6.9 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/server/access.c b/server/access.c index 76d3e096..872b6c18 100644 --- a/server/access.c +++ b/server/access.c @@ -53,6 +53,17 @@ DECLARE_TEST_SUITE(access, "Access test suite"); #endif +/** + * \brief include keys file + * + * This function loads only the crypto keys from a given file. + * It inserts these keys into the active access stanza. + * + * \param curr_acc pointer to the current access stanza + * \param access_filename Pointer to the file containing the keys + * \param opts fko_srv_options_t Server options struct + * + */ int include_keys_file(acc_stanza_t *, const char *, fko_srv_options_t *); @@ -1051,6 +1062,15 @@ free_acc_stanzas(fko_srv_options_t *opts) return; } +/** + * \brief Frees the final access stanza + * + * This function walks the access stanza list and frees the last member + * + * \param opts pointer to the server options struct + * + */ + void free_last_acc_stanza(fko_srv_options_t *opts) { @@ -1404,11 +1424,7 @@ acc_data_is_valid(fko_srv_options_t *opts, return(1); } -/** - * \brief Parses an access folder - * - * This function processes all the *.conf files in the specified directory. - */ + int parse_access_folder(fko_srv_options_t *opts, char *access_folder, int *depth) { @@ -2049,12 +2065,21 @@ compare_addr_list(acc_int_list_t *ip_list, const uint32_t ip) return(match); } -/* Compare the contents of 2 port lists. Return true on a match. +/** + * \brief Compares port lists + * + * Compare the contents of 2 port lists. Return true on a match. * Match depends on the match_any flag. if match_any is 1 then any * entry in the incoming data need only match one item to return true. * Otherwise all entries in the incoming data must have a corresponding * match in the access port_list. -*/ + * + * \param acc Pointer to the acc_stanza_t struct that holds the access stanzas + * \param port_str pointer to the + * + * \return Returns true on a match + * + */ static int compare_port_list(acc_port_list_t *in, acc_port_list_t *ac, const int match_any) { diff --git a/server/access.h b/server/access.h index 43988bfa..d0cb494c 100644 --- a/server/access.h +++ b/server/access.h @@ -33,26 +33,145 @@ #define PROTO_TCP 6 #define PROTO_UDP 17 -/* Allow strings as large as 123.123.123.123/255.255.255.255 -*/ +/** + * \def ACCESS_BUF_LEN + * + * \brief Allow strings as large as 123.123.123.123/255.255.255.255 + */ #define ACCESS_BUF_LEN 33 -/* We won't recurse more than 3 deep. Access.conf can include a file +/** + * \def MAX_DEPTH + * + * \brief Recursion depth + * + * We won't recurse more than 3 deep. Access.conf can include a file * that includes a file, but that's the limit. */ #define MAX_DEPTH 3 /* Function Prototypes */ + +/** + * \brief Loads an access.conf file + * + * Also handles includes by calling itself recursively, only recurses 3 levels deep + * + * \param opts Pointer to the fko_srv_options_t struct to populate + * \param access_filename Pointer to the filename to load + * \param depth Pointer to the current depth. This starts at 0 and is incremented for each recursion + * + * \return Returns an error status, or EXIT_SUCCESS + * + */ int parse_access_file(fko_srv_options_t *opts, char *access_filename, int *depth); + +/** + * \brief Loads access.conf files in a folder + * + * This function does not recurse into subfolders, but calls parse_access_file + * for each contained file. This function does not increment the depth int. + * + * \param opts Pointer to the fko_srv_options_t struct to populate + * \param access_folder Pointer to the folder name to process + * \param depth Pointer to the current depth. + * + * \return Returns an error status, or EXIT_SUCCESS + * + */ int parse_access_folder(fko_srv_options_t *opts, char *access_folder, int *depth); + +/** + * \brief Basic validation for a access stanzas + * + * This is a basic check to ensure there is at least one access stanza + * with the "source" variable populated, and this function is only + * called after all access.conf files are processed. This allows + * %include_folder processing to proceed against directories that + * have files that are not access.conf files. Additional stronger + * validations are done in acc_data_is_valid(), but this function + * is only called when a "SOURCE" variable has been parsed out of + * the file. + * + * \param acc Pointer to the acc_stanza_t struct that holds the access stanza + * + * \return Returns an error status, or EXIT_SUCCESS + * + */ int valid_access_stanzas(acc_stanza_t *acc); + +/** + * \brief Compares address lists + * + * This function walks a linked list looking for a matching IP address. + * Primarily intended to find a matching access stanza for an + * incoming SPA packet. + * + * \param source_list pointer to linked list to walk + * \param ip Address to compare + * + * \return Returns true on a match + * + */ int compare_addr_list(acc_int_list_t *source_list, const uint32_t ip); + +/** + * \brief Check for a proto-port string + * + * Take a proto/port string (or mulitple comma-separated strings) and check + * them against the list for the given access stanza. + * + * \param acc Pointer to the acc_stanza_t struct that holds the access stanzas + * \param port_str pointer to the port string to look for + * + * \return Returns true if allowed + * + */ int acc_check_port_access(acc_stanza_t *acc, char *port_str); + +/** + * \brief Dumps the current configuration to stdout + * + * \param opts pointer to the server options struct + * + */ void dump_access_list(const fko_srv_options_t *opts); + +/** + * \brief Expands a proto/port string to a list of access proto-port struct. + * + * This takes a single string of comma separated proto/port values and separates + * them into a linked list + * + * \param plist Double pointer to the acc_port_list_t to hold the proto/ports + * \param plist_str Pointer to the list of proto/port values + * + * \return Returns true if successful + * + */ int expand_acc_port_list(acc_port_list_t **plist, char *plist_str); + +/** + * \brief Sets do_acc_stanza_init to true, which enables free_acc_stanzas() + * + */ void enable_acc_stanzas_init(void); + +/** + * \brief Free memory for all access stanzas + * + * \param opts Pointer to fko_srv_options_t that contains the access stanza chain to free + * + */ void free_acc_stanzas(fko_srv_options_t *opts); + +/** + * \brief free a port list + * + * \param plist Pointer to acc_port_list_t to free + * + */ void free_acc_port_list(acc_port_list_t *plist); #ifdef HAVE_C_UNIT_TESTS diff --git a/server/cmd_cycle.h b/server/cmd_cycle.h index 4197c35e..3c2dd71a 100644 --- a/server/cmd_cycle.h +++ b/server/cmd_cycle.h @@ -33,9 +33,40 @@ #define CMD_CYCLE_BUFSIZE 256 +/** + * \brief Main driver for open/close command cycles + * + * This function is called when a valid SPA packet is received that matches + * a stanza containing a command cycle. + * + * \param opts + * \param acc + * \param spadat + * \param stanza_num + * \param res + * + */ int cmd_cycle_open(fko_srv_options_t *opts, acc_stanza_t *acc, spa_data_t *spadat, const int stanza_num, int *res); + +/** + * \brief Launches the command cycle close command + * + * TODO: finish me + * + * \param opts + * + */ void cmd_cycle_close(fko_srv_options_t *opts); + +/** + * \brief frees the command cycle list + * + * TODO: Finish me + * + * \param opts + * + */ void free_cmd_cycle_list(fko_srv_options_t *opts); #endif /* CMD_CYCLE_H */ diff --git a/server/cmd_opts.h b/server/cmd_opts.h index 9986bd09..a2feed5d 100644 --- a/server/cmd_opts.h +++ b/server/cmd_opts.h @@ -150,7 +150,7 @@ static char *config_map[NUMBER_OF_CONFIG_ENTRIES] = { }; -/* Long options values (for those that may not have a short option). +/** Long options values (for those that may not have a short option). */ enum { FW_LIST = 0x200, diff --git a/server/config_init.h b/server/config_init.h index fb958da5..b8f80ecd 100644 --- a/server/config_init.h +++ b/server/config_init.h @@ -35,10 +35,39 @@ /* Function Prototypes */ + +/** + * \brief Initializes the program config + * + * This function sets default config options and loads the config information from the command line. + * + * \param opts fko_srv_options_t struct that is populated with configuration + * \param argc argument count, the number of command line arguments + * \param argv argument vector, an array of the command line arguments + * + */ void config_init(fko_srv_options_t *opts, int argc, char **argv); + +/** + * \brief dumps current config to std out + * + * \param opts Pointer to the program options struct to dump + * + */ void dump_config(const fko_srv_options_t *opts); -void clear_configs(fko_srv_options_t *opts); + +/** + * \brief Frees config memory + * + * \param opts fko_srv_options_t struct that is to be freed + * + */ void free_configs(fko_srv_options_t *opts); + +/** + * \brief Prints program help message to stdout + * + */ void usage(void); #endif /* CONFIG_INIT_H */ diff --git a/server/extcmd.h b/server/extcmd.h index f2375e49..6647779e 100644 --- a/server/extcmd.h +++ b/server/extcmd.h @@ -82,18 +82,108 @@ enum { /* Function prototypes */ + + + +/** + * \brief Runs an external command + * + * This function is actually a wrapper for _run_extcmd(). + * Run an external command returning exit status, and optionally filling + * provided buffer with STDOUT output up to the size provided. + * + * \param cmd Command to run + * \param so_buf Buffer for command output, or null pointer to discard output + * \param so_buf_sz length of so_buf + * \param want_stderr Flag indicating stderr is to be saved + * \param timeout Placeholder, the timeout is not used + * \param pid_status Pointer where the command status is stored + * \param opts Program options struct + * + */ int run_extcmd(const char *cmd, char *so_buf, const size_t so_buf_sz, const int want_stderr, const int timeout, int *pid_status, const fko_srv_options_t * const opts); + +/** + * \brief Runs an external command as a given user and group + * + * This function is actually a wrapper for _run_extcmd(). + * Run an external command returning exit status, and optionally filling + * provided buffer with STDOUT output up to the size provided. + * This function takes a user ID and Group ID to use when running the command. + * + * \param uid User to run as + * \param gid Group to run as + * \param cmd Command to run + * \param so_buf Buffer for command output + * \param so_buf_sz length of so_buf + * \param want_stderr Flag indicating stderr is to be saved + * \param timeout Placeholder, the timeout is not used + * \param pid_status Pointer where the command status is stored + * \param opts Program options struct + * + */ int run_extcmd_as(uid_t uid, gid_t gid, const char *cmd, char *so_buf, const size_t so_buf_sz, const int want_stderr, const int timeout, int *pid_status, const fko_srv_options_t * const opts); + +/** + * \brief Runs an external command, searching for a substring + * + * This function is actually a wrapper for _run_extcmd(). + * Run an external command returning exit status, and optionally filling + * provided buffer with STDOUT output up to the size provided. + * + * \param cmd Command to run + * \param want_stderr Flag indicating stderr is to be saved + * \param timeout Placeholder, the timeout is not used + * \param substr_search The substring to search for + * \param pid_status Pointer where the command status is stored + * \param opts Program options struct + * + * \return Returns line number where the substring was matched, or 0 for no match + */ int search_extcmd(const char *cmd, const int want_stderr, const int timeout, const char *substr_search, int *pid_status, const fko_srv_options_t * const opts); + +/** + * \brief Runs an external command, returning a line of output + * + * This function is actually a wrapper for _run_extcmd(). + * Run an external command returning exit status, and optionally filling + * provided buffer with STDOUT output up to the size provided. + * This function searches the command output for the first match against + * The provided substring, returns the line number that matched, + * and populates so_buf with that line of output. + * + * \param cmd Command to run + * \param so_buf Buffer for command output + * \param so_buf_sz length of so_buf + * \param timeout Placeholder, the timeout is not used + * \param substr_search The substring to search for + * \param pid_status Pointer where the command status is stored + * \param opts Program options struct + * + * \return Returns the line number that matched, or 0 for no match + */ int search_extcmd_getline(const char *cmd, char *so_buf, const size_t so_buf_sz, const int timeout, const char *substr_search, int *pid_status, const fko_srv_options_t * const opts); + +/** + * \brief Runs an external command, and feeds it stdin + * + * This function is actually a wrapper for _run_extcmd_write(). + * Run an external command that expects stdin. + * + * \param cmd Command to run + * \param cmd_write The text to send as stdin + * \param pid_status Pointer where the command status is stored + * \param opts Program options struct + * + */ int run_extcmd_write(const char *cmd, const char *cmd_write, int *pid_status, const fko_srv_options_t * const opts); #endif /* EXTCMD_H */ diff --git a/server/fwknopd.h b/server/fwknopd.h index fc0d1e92..8acfa5af 100644 --- a/server/fwknopd.h +++ b/server/fwknopd.h @@ -43,18 +43,43 @@ * of defining them here. */ #ifndef LOCK_SH - #define LOCK_SH 0x01 /* shared file lock */ + /** + * \def LOCK_SH + * + * \brief Shared file lock + */ + #define LOCK_SH 0x01 #endif #ifndef LOCK_EX - #define LOCK_EX 0x02 /* exclusive file lock */ + /** + * \def LOCK_EX + * + * \brief Exclusive file lock + */ + #define LOCK_EX 0x02 #endif #ifndef LOCK_NB - #define LOCK_NB 0x04 /* do not block when locking */ + /** + * \def LOCK_NB + * + * \brief Do not block when locking + */ + #define LOCK_NB 0x04 #endif #ifndef LOCK_UN - #define LOCK_UN 0x08 /* unlock file */ + /** + * \def LOCK_UN + * + * \brief Unlock file + */ + #define LOCK_UN 0x08 #endif + /** + * \def PID_BUFLEN + * + * \brief Buffer length for PID + */ #define PID_BUFLEN 7 #endif /* FWKNOPD_H */ diff --git a/server/fwknopd_common.h b/server/fwknopd_common.h index 0da28244..97790866 100644 --- a/server/fwknopd_common.h +++ b/server/fwknopd_common.h @@ -732,6 +732,15 @@ typedef struct fko_srv_options */ #define FW_CLEANUP 1 #define NO_FW_CLEANUP 0 + +/** + * \brief Frees all memory and exits + * + * \param opts Program options + * \param fw_cleanup_flag Flag indicates whether firewall needs cleanup + * \param exit_status Exit status to return when closing the program + * + */ void clean_exit(fko_srv_options_t *opts, unsigned int fw_cleanup_flag, unsigned int exit_status); diff --git a/server/fwknopd_errors.h b/server/fwknopd_errors.h index b1a29e9f..58f8685b 100644 --- a/server/fwknopd_errors.h +++ b/server/fwknopd_errors.h @@ -68,7 +68,19 @@ enum { /* Function prototypes */ + +/** + * \brief takes a numeric error code and returns the readable string + * + * \param err_code The integer error code to convert + * + * \return returns a pointer to the error string + */ const char* get_errstr(const int err_code); + +/** + * \brief print all server errors (from server/fwknopd_errors.c) to stdout + */ void dump_server_errors(void); #endif /* FWKNOPD_ERRORS_H */ diff --git a/server/incoming_spa.h b/server/incoming_spa.h index 0f185015..a0f6d20f 100644 --- a/server/incoming_spa.h +++ b/server/incoming_spa.h @@ -32,6 +32,16 @@ /* Prototypes */ + +/** + * \brief Process the SPA packet data + * + * This is the central function for handling incoming SPA data. It is called + * once for each SPA packet to process + * + * \param opts Main program data struct + * + */ void incoming_spa(fko_srv_options_t *opts); #endif /* INCOMING_SPA_H */ diff --git a/server/nfq_capture.c b/server/nfq_capture.c index 11b6eda5..8e95c3ca 100755 --- a/server/nfq_capture.c +++ b/server/nfq_capture.c @@ -1,10 +1,10 @@ +/** + * \file server/nfq_capture.c + * + * \brief Capture routine for fwknopd that uses libnetfilter_queue. + */ + /* - ***************************************************************************** - * - * File: nfq_capture.c - * - * Purpose: Capture routine for fwknopd that uses libnetfilter_queue. - * * Fwknop is developed primarily by the people listed in the file 'AUTHORS'. * Copyright (C) 2009-2014 fwknop developers and contributors. For a full * list of contributors, see the file 'CREDITS'. diff --git a/server/nfq_capture.h b/server/nfq_capture.h index 5d182f0c..3c3b2c69 100755 --- a/server/nfq_capture.h +++ b/server/nfq_capture.h @@ -1,10 +1,10 @@ +/** + * \file server/nfq_capture.h + * + * \brief Header file for nfq_capture.c + */ + /* - ***************************************************************************** - * - * File: nfq_capture.h - * - * Purpose: Header file for nfq_capture.c. - * * Fwknop is developed primarily by the people listed in the file 'AUTHORS'. * Copyright (C) 2009-2014 fwknop developers and contributors. For a full * list of contributors, see the file 'CREDITS'.