Completely document fastd.h

10 files changed, 121 insertions, 87 deletions

diff --git a/Doxyfile.in b/Doxyfile.in
index f67c16b..abfca99 100644
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -774,7 +774,7 @@ INPUT_ENCODING         = UTF-8
 # *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
 # *.qsf, *.as and *.js.
 
-FILE_PATTERNS          =
+FILE_PATTERNS          = "*.c" "*.h" "*.h.in"
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -1943,7 +1943,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = __attribute__(x)= VECTOR(x):=VECTOR
+PREDEFINED             = __attribute__(x)= VECTOR(x):=VECTOR WITH_CAPABILITIES __linux__
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
diff --git a/src/capabilities.c b/src/capabilities.c
index 897ca3c..8a7e823 100644
--- a/src/capabilities.c
+++ b/src/capabilities.c
@@ -68,6 +68,7 @@ static void try_cap(cap_value_t cap) {
 	cap_free(name);
 }
 
+/** Tries to acquire the capabilities needed to perform initialization without root privileges */
 void fastd_cap_init(void) {
 	/* interface creation */
 	try_cap(CAP_NET_ADMIN);
@@ -79,6 +80,7 @@ void fastd_cap_init(void) {
 	try_cap(CAP_NET_RAW);
 }
 
+/** Drops all capabilities */
 void fastd_cap_drop(void) {
 	cap_t caps = cap_init();
 
diff --git a/src/fastd.c b/src/fastd.c
index a3c6d14..5542ea8 100644
--- a/src/fastd.c
+++ b/src/fastd.c
@@ -311,6 +311,7 @@ static inline void maintenance(void) {
 }
 
 
+/** Closes all open FDs except stdin, stdout and stderr */
 void fastd_close_all_fds(void) {
 	struct rlimit rl;
 	int fd, maxfd;
diff --git a/src/fastd.h b/src/fastd.h
index 67174cf..f9e8c5a 100644
--- a/src/fastd.h
+++ b/src/fastd.h
@@ -166,134 +166,134 @@ struct fastd_config {
 	fastd_loglevel_t log_syslog_level;	/**< The minimum loglevel of messages to print to syslog (or -1 to not print any messages on syslog) */
 	char *log_syslog_ident;			/**< The identification string for messages sent to syslog (default: "fastd") */
 
-	char *ifname;
+	char *ifname;				/**< The configured interface name */
 
-	size_t n_bind_addrs;
-	fastd_bind_address_t *bind_addrs;
+	size_t n_bind_addrs;			/**< Number of elements in bind_addrs */
+	fastd_bind_address_t *bind_addrs;	/**< Configured bind addresses */
 
-	fastd_bind_address_t *bind_addr_default_v4;
-	fastd_bind_address_t *bind_addr_default_v6;
+	fastd_bind_address_t *bind_addr_default_v4; /**< Pointer to the bind address to be used for IPv4 connections by default */
+	fastd_bind_address_t *bind_addr_default_v6; /**< Pointer to the bind address to be used for IPv6 connections by default */
 
-	uint16_t mtu;
-	fastd_mode_t mode;
+	uint16_t mtu;				/**< The configured MTU */
+	fastd_mode_t mode;			/**< The configured mode of operation */
 
-	uint32_t packet_mark;
-	bool forward;
-	fastd_tristate_t pmtu;
-	bool secure_handshakes;
+	uint32_t packet_mark;			/**< The configured packet mark (or 0) */
+	bool forward;				/**< Specifies if packet forwarding is enable */
+	fastd_tristate_t pmtu;			/**< Can be set to explicitly enable or disable PMTU detection */
+	bool secure_handshakes;			/**< Can be set to false to support connections with fastd versions before v11 */
 
-	fastd_drop_caps_t drop_caps;
+	fastd_drop_caps_t drop_caps;		/**< Specifies if and when to drop capabilities */
 
-	char *user;
-	char *group;
+	char *user;				/**< Specifies which user to switch to after initialization */
+	char *group;				/**< Can specify an alternative group to switch to */
 
-	uid_t uid;
-	gid_t gid;
-	size_t n_groups;
-	gid_t *groups;
+	uid_t uid;				/**< The UID of the configured user */
+	gid_t gid;				/**< The GID of the configured group */
+	size_t n_groups;			/**< The number of supplementary groups of the user */
+	gid_t *groups;				/**< The supplementary groups of the configured user */
 
-	const fastd_protocol_t *protocol;
-	fastd_string_stack_t *method_list;
-	fastd_method_info_t *methods;
+	const fastd_protocol_t *protocol;	/**< The handshake protocol */
+	fastd_string_stack_t *method_list;	/**< The list of configured method names */
+	fastd_method_info_t *methods;		/**< The list of configured methods */
 
-	size_t max_overhead;
-	size_t min_encrypt_head_space;
-	size_t min_decrypt_head_space;
-	size_t min_encrypt_tail_space;
-	size_t min_decrypt_tail_space;
+	size_t max_overhead;			/**< The maximum overhead of all configured methods */
+	size_t min_encrypt_head_space;		/**< The minimum space a configured methods needs a the beginning of a buffer to encrypt */
+	size_t min_decrypt_head_space;		/**< The minimum space a configured methods needs a the beginning of a buffer to decrypt */
+	size_t min_encrypt_tail_space;		/**< The minimum space a configured methods needs a the end of a buffer to encrypt */
+	size_t min_decrypt_tail_space;		/**< The minimum space a configured methods needs a the end of a buffer to decrypt */
 
-	char *secret;
+	char *secret;				/**< The configured secret key */
 
-	const fastd_cipher_t **ciphers;
-	const fastd_mac_t **macs;
+	const fastd_cipher_t **ciphers;		/**< All supported ciphers */
+	const fastd_mac_t **macs;		/**< All supported message authentication codes */
 
-	fastd_peer_group_config_t *peer_group;
-	fastd_peer_config_t *peers;
+	fastd_peer_group_config_t *peer_group;	/**< The root peer group configuration */
+	fastd_peer_config_t *peers;		/**< The configured peers */
 
-	bool has_floating;
+	bool has_floating;			/**< Specifies if any of the configured peers have floating remotes */
 
-	fastd_protocol_config_t *protocol_config;
+	fastd_protocol_config_t *protocol_config; /**< The protocol-specific configuration */
 
-	fastd_shell_command_t on_pre_up;
-	fastd_shell_command_t on_up;
-	fastd_shell_command_t on_down;
-	fastd_shell_command_t on_post_down;
-	fastd_shell_command_t on_connect;
-	fastd_shell_command_t on_establish;
-	fastd_shell_command_t on_disestablish;
+	fastd_shell_command_t on_pre_up;	/**< The command to execute before the initialization of the tunnel interface */
+	fastd_shell_command_t on_up;		/**< The command to execute after the initialization of the tunnel interface */
+	fastd_shell_command_t on_down;		/**< The command to execute before the destruction of the tunnel interface */
+	fastd_shell_command_t on_post_down;	/**< The command to execute after the destruction of the tunnel interface */
+	fastd_shell_command_t on_connect;	/**< The command to execute before a handshake is sent to establish a new connection */
+	fastd_shell_command_t on_establish;	/**< The command to execute when a new connection has been established */
+	fastd_shell_command_t on_disestablish;	/**< The command to execute when a connection has been disestablished */
 #ifdef WITH_VERIFY
-	fastd_shell_command_t on_verify;
+	fastd_shell_command_t on_verify;	/**< The command to execute to check if a connection from an unknown peer should be allowed */
 #endif
 
-	bool daemon;
-	char *pid_file;
+	bool daemon;				/**< Set to make fastd fork to the background after initialization */
+	char *pid_file;				/**< A filename to write fastd's PID to */
 
-	bool hide_ip_addresses;
-	bool hide_mac_addresses;
+	bool hide_ip_addresses;			/**< Tells fastd to hide peers' IP address in the log output */
+	bool hide_mac_addresses;		/**< Tells fastd to hide peers' MAC address in the log output */
 
-	bool machine_readable;
-	bool generate_key;
-	bool show_key;
-	bool verify_config;
+	bool machine_readable;			/**< Supresses explanatory messages in the generate_key and show_key commands */
+	bool generate_key;			/**< Makes fastd generate a new keypair and exit */
+	bool show_key;				/**< Makes fastd output the public key for the configured secret and exit */
+	bool verify_config;			/**< Does basic verification of the configuration and exits */
 };
 
 /** The dynamic state of \em fastd */
 struct fastd_context {
-	bool log_initialized;
+	bool log_initialized;			/**< true if the logging facilities have been properly initialized */
 
-	char *ifname;
+	char *ifname;				/**< The actual interface name */
 
-	struct timespec now;
+	struct timespec now;			/**< The current monotonous timestamp */
 
-	fastd_peer_group_t *peer_group;
+	fastd_peer_group_t *peer_group;		/**< The root peer group */
 
-	uint64_t next_peer_id;
-	VECTOR(fastd_peer_t*) peers;
+	uint64_t next_peer_id;			/**< An monotonously increasing ID peers are identified with in some components */
+	VECTOR(fastd_peer_t*) peers;		/**< The currectly active peers */
 
 #ifdef USE_EPOLL
-	int epoll_fd;
+	int epoll_fd;				/**< The file descriptor for the epoll facility */
 #else
-	VECTOR(struct pollfd) pollfds;
+	VECTOR(struct pollfd) pollfds;		/**< The vector of pollfds for all file descriptors */
 #endif
 
-	uint32_t peer_addr_ht_seed;
-	VECTOR(fastd_peer_t*) *peer_addr_ht;
+	uint32_t peer_addr_ht_seed;		/**< The hash seed used for peer_addr_ht */
+	VECTOR(fastd_peer_t*) *peer_addr_ht;	/**< An array of hash buckets for the peer hash table */
 
-	fastd_dlist_head_t handshake_queue;
-	struct timespec next_maintenance;
+	fastd_dlist_head_t handshake_queue;	/**< A doubly linked list of the peers currently queued for handshakes (ordered by the time of the next handshake) */
+	struct timespec next_maintenance;	/**< The time of the next maintenance call */
 
-	VECTOR(pid_t) async_pids;
-	int async_rfd;
-	int async_wfd;
+	VECTOR(pid_t) async_pids;		/**< PIDs of asynchronously executed commands which still have to be reaped */
+	int async_rfd;				/**< The read side of the pipe used to send data from other thread to the main thread */
+	int async_wfd;				/**< The write side of the pipe used to send data from other thread to the main thread */
 
-	int tunfd;
+	int tunfd;				/**< The file descriptor of the tunnel interface */
 
-	size_t n_socks;
-	fastd_socket_t *socks;
+	size_t n_socks;				/**< The number of sockets in socks */
+	fastd_socket_t *socks;			/**< Array of all sockets */
 
-	fastd_socket_t *sock_default_v4;
-	fastd_socket_t *sock_default_v6;
+	fastd_socket_t *sock_default_v4;	/**< Points to the socket that is used for new outgoing IPv4 connections */
+	fastd_socket_t *sock_default_v6;	/**< Points to the socket that is used for new outgoing IPv6 connections */
 
-	fastd_stats_t rx;
+	fastd_stats_t rx;			/**< Reception statistics */
 
-	fastd_stats_t tx;
-	fastd_stats_t tx_dropped;
-	fastd_stats_t tx_error;
+	fastd_stats_t tx;			/**< Transmission statistics (OK) */
+	fastd_stats_t tx_dropped;		/**< Transmission statistics (dropped because of full queues) */
+	fastd_stats_t tx_error;			/**< Transmission statistics (other errors) */
 
-	VECTOR(fastd_peer_eth_addr_t) eth_addrs;
+	VECTOR(fastd_peer_eth_addr_t) eth_addrs; /**< Sorted vector of all known ethernet addresses with associated peers and timeouts */
 
-	unsigned int randseed;
+	unsigned int randseed;			/**< Random seed for non-cryptographic random numbers */
 
-	size_t unknown_handshake_pos;
-	fastd_handshake_timeout_t unknown_handshakes[8];
+	size_t unknown_handshake_pos;		/**< Current start position in the ring buffer unknown_handshakes */
+	fastd_handshake_timeout_t unknown_handshakes[8]; /**< Ring buffer of unknown addresses handshakes have been received from */
 
-	fastd_protocol_state_t *protocol_state;
+	fastd_protocol_state_t *protocol_state;	/**< Protocol-specific state */
 };
 
 /** A stack of strings */
 struct fastd_string_stack {
-	fastd_string_stack_t *next;
-	char str[];
+	fastd_string_stack_t *next;		/**< The next element of the stack */
+	char str[];				/**< Zero-terminated character data */
 };
 
 
@@ -302,10 +302,10 @@ extern fastd_config_t conf;	/**< The global configuration */
 
 
 void fastd_send(const fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, fastd_peer_t *peer, fastd_buffer_t buffer, size_t stat_size);
-void fastd_send_all(fastd_peer_t *source_peer, fastd_buffer_t buffer);
 void fastd_send_handshake(const fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, fastd_peer_t *peer, fastd_buffer_t buffer);
-void fastd_receive(fastd_socket_t *sock);
+void fastd_send_all(fastd_peer_t *source_peer, fastd_buffer_t buffer);
 
+void fastd_receive(fastd_socket_t *sock);
 void fastd_handle_receive(fastd_peer_t *peer, fastd_buffer_t buffer);
 
 void fastd_close_all_fds(void);
@@ -476,7 +476,11 @@ static inline int timespec_diff(const struct timespec *tp1, const struct timespe
 }
 
 /**
-   Returns true if the given timespec is before or equal to the current time
+   Checks if a timeout has occured
+
+   @param timeout the time the timeout should occur
+
+   @return true if the given timeout is before or equal to the current time
 
    \note The current time is updated only once per main loop iteration, after waiting for input.
 */
@@ -508,7 +512,10 @@ static inline bool fastd_allow_verify(void) {
 /**
    Checks if two strings are equal
 
-   The strings may be NULL.
+   @param str1 The first string (may be NULL)
+   @param str2 The second string (may be NULL)
+
+   @return True if both strings are NULL or both strings are not NULL and equal
 */
 static inline bool strequal(const char *str1, const char *str2) {
 	if (str1 && str2)
diff --git a/src/random.c b/src/random.c
index d8c06d2..71a3ad1 100644
--- a/src/random.c
+++ b/src/random.c
@@ -29,6 +29,9 @@
 #include <sys/stat.h>
 
 
+/**
+   Provides a given amount of cryptographic random data
+*/
 void fastd_random_bytes(void *buffer, size_t len, bool secure) {
 	int fd;
 	size_t read_bytes = 0;
diff --git a/src/receive.c b/src/receive.c
index 9a528fe..e5c1aeb 100644
--- a/src/receive.c
+++ b/src/receive.c
@@ -179,6 +179,7 @@ static inline void handle_socket_receive(fastd_socket_t *sock, const fastd_peer_
 	}
 }
 
+/** Reads a packet from a socket */
 void fastd_receive(fastd_socket_t *sock) {
 	size_t max_len = fastd_max_outer_packet();
 	fastd_buffer_t buffer = fastd_buffer_alloc(max_len, conf.min_decrypt_head_space, conf.min_decrypt_tail_space);
@@ -241,6 +242,7 @@ static inline void handle_forward(fastd_peer_t *source_peer, fastd_buffer_t buff
 	fastd_send_all(source_peer, buffer);
 }
 
+/** Handles a received and decrypted payload packet */
 void fastd_handle_receive(fastd_peer_t *peer, fastd_buffer_t buffer) {
 	if (conf.mode == MODE_TAP) {
 		if (buffer.len < ETH_HLEN) {
diff --git a/src/send.c b/src/send.c
index 3e346ec..aec58db 100644
--- a/src/send.c
+++ b/src/send.c
@@ -168,14 +168,17 @@ static void send_type(const fastd_socket_t *sock, const fastd_peer_address_t *lo
 	fastd_buffer_free(buffer);
 }
 
+/** Sends a payload packet to a peer */
 void fastd_send(const fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, fastd_peer_t *peer, fastd_buffer_t buffer, size_t stat_size) {
 	send_type(sock, local_addr, remote_addr, peer, PACKET_DATA, buffer, stat_size);
 }
 
+/** Sends a handshake packet to a peer */
 void fastd_send_handshake(const fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, fastd_peer_t *peer, fastd_buffer_t buffer) {
 	send_type(sock, local_addr, remote_addr, peer, PACKET_HANDSHAKE, buffer, 0);
 }
 
+/** Encrypts and sends a payload packet to all peers */
 void fastd_send_all(fastd_peer_t *source_peer, fastd_buffer_t buffer) {
 	size_t i;
 	for (i = 0; i < VECTOR_LEN(ctx.peers); i++) {
diff --git a/src/socket.c b/src/socket.c
index 340967c..49752fc 100644
--- a/src/socket.c
+++ b/src/socket.c
@@ -180,6 +180,7 @@ static bool set_bound_address(fastd_socket_t *sock) {
 	return true;
 }
 
+/** Tries to initialize sockets for all configured bind addresses */
 bool fastd_socket_handle_binds(void) {
 	size_t i;
 
@@ -214,6 +215,7 @@ bool fastd_socket_handle_binds(void) {
 	return true;
 }
 
+/** Opens a single unbound socket for the given address family */
 fastd_socket_t* fastd_socket_open(fastd_peer_t *peer, int af) {
 	const fastd_bind_address_t any_address = { .addr.sa.sa_family = af };
 
@@ -237,6 +239,7 @@ fastd_socket_t* fastd_socket_open(fastd_peer_t *peer, int af) {
 	return sock;
 }
 
+/** Closes a socket */
 void fastd_socket_close(fastd_socket_t *sock) {
 	if (sock->fd >= 0) {
 		if(close(sock->fd))
@@ -251,6 +254,7 @@ void fastd_socket_close(fastd_socket_t *sock) {
 	}
 }
 
+/** Handles an error that occured on a socket */
 void fastd_socket_error(fastd_socket_t *sock) {
 	if (sock->addr->bindtodev)
 		pr_warn("socket bind %I on `%s' lost", &sock->addr->addr, sock->addr->bindtodev);
diff --git a/src/tuntap.c b/src/tuntap.c
index d30a392..ddb93b1 100644
--- a/src/tuntap.c
+++ b/src/tuntap.c
@@ -55,6 +55,7 @@ static const bool multiaf_tun = true;
 
 #if defined(__linux__)
 
+/** Opens the TUN/TAP device */
 void fastd_tuntap_open(void) {
 	struct ifreq ifr = {};
 
@@ -108,6 +109,7 @@ void fastd_tuntap_open(void) {
 
 #elif defined(__FreeBSD__) || defined(__OpenBSD__)
 
+/** Sets the MTU of the TUN/TAP device */
 static void set_tun_mtu(void) {
 	struct tuninfo tuninfo;
 
@@ -123,6 +125,7 @@ static void set_tun_mtu(void) {
 
 #ifdef __FreeBSD__
 
+/** Sets the MTU of the TAP device */
 static void set_tap_mtu(void) {
 	struct tapinfo tapinfo;
 
@@ -135,6 +138,7 @@ static void set_tap_mtu(void) {
 		exit_errno("TAPSIFINFO ioctl failed");
 }
 
+/** Sets up the TUN device */
 static void setup_tun(void) {
 	int one = 1;
 	if (ioctl(ctx.tunfd, TUNSIFHEAD, &one) < 0)
@@ -143,6 +147,7 @@ static void setup_tun(void) {
 	set_tun_mtu();
 }
 
+/** Sets up the TAP device */
 static void setup_tap(void) {
 	struct ifreq ifr = {};
 
@@ -155,6 +160,7 @@ static void setup_tap(void) {
 	set_tap_mtu();
 }
 
+/** Opens the TUN/TAP device */
 void fastd_tuntap_open(void) {
 	pr_debug("initializing tun/tap device...");
 
@@ -233,16 +239,19 @@ static void set_link0(bool set) {
 		pr_error_errno("close");
 }
 
+/** Sets up the TUN device */
 static void setup_tun(void) {
 	set_link0(false);
 	set_tun_mtu();
 }
 
+/** Sets up the TAP device */
 static void setup_tap(void) {
 	set_link0(true);
 	set_tun_mtu();
 }
 
+/** Opens the TUN/TAP device */
 void fastd_tuntap_open(void) {
 	char ifname[5+IFNAMSIZ] = "/dev/";
 	if (!conf.ifname)
@@ -286,6 +295,7 @@ void fastd_tuntap_open(void) {
 #endif
 
 
+/** Reads a packet from the TUN/TAP device */
 fastd_buffer_t fastd_tuntap_read(void) {
 	size_t max_len = fastd_max_inner_packet();
 
@@ -313,6 +323,7 @@ fastd_buffer_t fastd_tuntap_read(void) {
 	return buffer;
 }
 
+/** Writes a packet to the TUN/TAP device */
 void fastd_tuntap_write(fastd_buffer_t buffer) {
 	if (multiaf_tun && conf.mode == MODE_TUN) {
 		uint8_t version = *((uint8_t*)buffer.data) >> 4;
@@ -340,6 +351,7 @@ void fastd_tuntap_write(fastd_buffer_t buffer) {
 		pr_warn_errno("write");
 }
 
+/** Closes the TUN/TAP device */
 void fastd_tuntap_close(void) {
 	if (close(ctx.tunfd))
 		pr_warn_errno("closing tun/tap: close");
diff --git a/src/types.h b/src/types.h
index 4915573..7f9f86e 100644
--- a/src/types.h
+++ b/src/types.h
@@ -45,7 +45,7 @@
 /** A tri-state with the values \em true, \em false and \em undefined */
 typedef struct fastd_tristate {
 	bool set : 1;		/**< Specifies if the tri-state is set (\em true or \em false) or not (\em undefined) */
-	bool state : 1;		/**< Speficies if the tri-state is \em true or \em false */
+	bool state : 1;		/**< Specifies if the tri-state is \em true or \em false */
 } fastd_tristate_t;
 
 /** A fastd_tristate_t instance representing the value \em true */