summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorMatthias Schiffer <mschiffer@universe-factory.net>2014-05-25 00:04:20 +0200
committerMatthias Schiffer <mschiffer@universe-factory.net>2014-05-25 00:04:20 +0200
commit1b21919d544e30cec89259cfa9353e10852cfc82 (patch)
tree701f5eda64ee3059c05c4e8ef6f4d6ff482e0f7c /src
parent52017c3919aa9f9573cea226b0be45f0947e893f (diff)
downloadfastd-1b21919d544e30cec89259cfa9353e10852cfc82.tar
fastd-1b21919d544e30cec89259cfa9353e10852cfc82.zip
fastd.h: more documentation
Diffstat (limited to 'src')
-rw-r--r--src/fastd.h70
1 files changed, 52 insertions, 18 deletions
diff --git a/src/fastd.h b/src/fastd.h
index 6580458..8726cd0 100644
--- a/src/fastd.h
+++ b/src/fastd.h
@@ -64,72 +64,106 @@ struct __attribute__((__packed__)) fastd_eth_addr {
Currently, only one such protocol, \em ec25519-fhmqvc, is defined.
*/
struct fastd_protocol {
+ /** The name of the procotol */
const char *name;
+ /** Performs one-time initialization tasks for the protocol */
fastd_protocol_config_t* (*init)(void);
+
+ /** Does some basic checks for the validity of a peer configuration */
void (*peer_verify)(fastd_peer_config_t *peer_conf);
+
+ /** Initializes protocol-specific parts of a peer configuration */
void (*peer_configure)(fastd_peer_config_t *peer_conf);
+
+ /** Checks if a peer configuration is valid and a connection may be established */
bool (*peer_check)(fastd_peer_config_t *peer_conf);
+
+ /** Checks if a temporary peer is valid and a connection may be established */
bool (*peer_check_temporary)(fastd_peer_t *peer);
+
+ /** Sends a handshake to the given peer */
void (*handshake_init)(fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, fastd_peer_t *peer);
+
+ /** Handles a handshake for the given peer */
void (*handshake_handle)(fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, fastd_peer_t *peer, const fastd_handshake_t *handshake, const fastd_method_info_t *method);
+
#ifdef WITH_VERIFY
+ /** Handles an asynchrounous on-verify command return */
void (*handle_verify_return)(fastd_peer_t *peer, fastd_socket_t *sock, const fastd_peer_address_t *local_addr, const fastd_peer_address_t *remote_addr, const fastd_method_info_t *method, const void *protocol_data, bool ok);
#endif
+
+ /** Handles a received payload packet (performs decryption and validity check, etc.) */
void (*handle_recv)(fastd_peer_t *peer, fastd_buffer_t buffer);
+
+ /** Sends a payload data packet to the given peer */
void (*send)(fastd_peer_t *peer, fastd_buffer_t buffer);
+ /** Initializes the protocol state for a peer */
void (*init_peer_state)(fastd_peer_t *peer);
+
+ /** Resets the protocol state for a peer (resets active sessions etc.) */
void (*reset_peer_state)(fastd_peer_t *peer);
+
+
+ /** Frees the protocol state for a peer */
void (*free_peer_state)(fastd_peer_t *peer);
+ /** Generates a new keypair and outputs it */
void (*generate_key)(void);
+
+ /** Outputs the public key for the configured secret */
void (*show_key)(void);
+
+
+ /** Adds peer-specific environment variables to env */
void (*set_shell_env)(fastd_shell_env_t *env, const fastd_peer_t *peer);
+
+ /** Creates a human-readable representation of the peer */
bool (*describe_peer)(const fastd_peer_t *peer, char *buf, size_t len);
};
/** An union storing an IPv4 or IPv6 address */
union fastd_peer_address {
- struct sockaddr sa;
- struct sockaddr_in in;
- struct sockaddr_in6 in6;
+ struct sockaddr sa; /**< A generic sockaddr union field of the address (for access to sa_family) */
+ struct sockaddr_in in; /**< An IPv4 address */
+ struct sockaddr_in6 in6; /**< An IPv6 address */
};
/** A linked list of addresses to bind to */
struct fastd_bind_address {
- fastd_bind_address_t *next;
- fastd_peer_address_t addr;
- char *bindtodev;
+ fastd_bind_address_t *next; /**< The next address in the list */
+ fastd_peer_address_t addr; /**< The address to bind to */
+ char *bindtodev; /**< May contain an interface name to limit the bind to */
};
/** A socket descriptor */
struct fastd_socket {
- int fd;
- const fastd_bind_address_t *addr;
- fastd_peer_address_t *bound_addr;
- fastd_peer_t *peer;
+ int fd; /**< The file descriptor for the socket */
+ const fastd_bind_address_t *addr; /**< The address this socket is supposed to be bound to (or NULL) */
+ fastd_peer_address_t *bound_addr; /**< The actual address that was bound to (may differ from addr when addr has a random port) */
+ fastd_peer_t *peer; /**< If the socket belongs to a single peer (as it was create dynamically when sending a handshake), contains that peer */
};
/** Some kind of network transfer stratistics */
struct fastd_stats {
- uint64_t packets;
- uint64_t bytes;
+ uint64_t packets; /**< The number of packets transferred */
+ uint64_t bytes; /**< The number of bytes transferred */
};
/** A data structure keeping track of an unknown addresses that a handshakes was received from recently */
struct fastd_handshake_timeout {
- fastd_peer_address_t address;
- struct timespec timeout;
+ fastd_peer_address_t address; /**< An address a handshake was received from */
+ struct timespec timeout; /**< Timeout until handshakes from this address are ignored */
};
/** The static configuration of \em fastd */
struct fastd_config {
- fastd_loglevel_t log_stderr_level;
- fastd_loglevel_t log_syslog_level;
- char *log_syslog_ident;
+ fastd_loglevel_t log_stderr_level; /**< The minimum loglevel of messages to print to stderr (or -1 to not print any messages on stderr) */
+ 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") */
unsigned maintenance_interval;
unsigned keepalive_timeout;
@@ -405,7 +439,7 @@ static inline size_t fastd_max_outer_packet(void) {
return 1 + fastd_max_inner_packet() + conf.max_overhead;
}
-/** Checks if a fastd_peer_address is an IPv6 link-local address */
+/** Checks if a fastd_peer_address_t is an IPv6 link-local address */
static inline bool fastd_peer_address_is_v6_ll(const fastd_peer_address_t *addr) {
return (addr->sa.sa_family == AF_INET6 && IN6_IS_ADDR_LINKLOCAL(&addr->in6.sin6_addr));
}