From 1b21919d544e30cec89259cfa9353e10852cfc82 Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Sun, 25 May 2014 00:04:20 +0200 Subject: fastd.h: more documentation --- src/fastd.h | 70 +++++++++++++++++++++++++++++++++++++++++++++---------------- 1 file 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)); } -- cgit v1.2.3