From 5e72359e9a2f4008c408acbd3fe5d389e11a15b4 Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Sun, 25 May 2014 04:59:35 +0200 Subject: Completely document fastd.h --- Doxyfile.in | 4 +- src/capabilities.c | 2 + src/fastd.c | 1 + src/fastd.h | 175 ++++++++++++++++++++++++++++------------------------- src/random.c | 3 + src/receive.c | 2 + src/send.c | 3 + src/socket.c | 4 ++ src/tuntap.c | 12 ++++ src/types.h | 2 +- 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 +/** + 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 */ -- cgit v1.2.3