summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorMatthias Schiffer <mschiffer@universe-factory.net>2014-05-25 04:59:35 +0200
committerMatthias Schiffer <mschiffer@universe-factory.net>2014-05-25 04:59:35 +0200
commit5e72359e9a2f4008c408acbd3fe5d389e11a15b4 (patch)
tree5f1aede16a3b1e6985d4b7a309c6999416a638a3 /src
parentf34e51a1c3b98df2b7c8c7d7eb415a33f42f2d75 (diff)
downloadfastd-5e72359e9a2f4008c408acbd3fe5d389e11a15b4.tar
fastd-5e72359e9a2f4008c408acbd3fe5d389e11a15b4.zip
Completely document fastd.h
Diffstat (limited to 'src')
-rw-r--r--src/capabilities.c2
-rw-r--r--src/fastd.c1
-rw-r--r--src/fastd.h175
-rw-r--r--src/random.c3
-rw-r--r--src/receive.c2
-rw-r--r--src/send.c3
-rw-r--r--src/socket.c4
-rw-r--r--src/tuntap.c12
-rw-r--r--src/types.h2
9 files changed, 119 insertions, 85 deletions
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 */