diff options
Diffstat (limited to 'src/fastd.h')
| -rw-r--r-- | src/fastd.h | 175 |
1 files changed, 91 insertions, 84 deletions
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) |