summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMatthias Schiffer <mschiffer@universe-factory.net>2014-05-27 23:30:48 +0200
committerMatthias Schiffer <mschiffer@universe-factory.net>2014-05-27 23:30:48 +0200
commitb9f329256d5911d9694b44ce1e4545d78fdd5340 (patch)
tree91c498a4690acda8bb53e8be202a34994cf946e5
parent64c79271c75987d94975cc3855617898b332b5a0 (diff)
downloadfastd-b9f329256d5911d9694b44ce1e4545d78fdd5340.tar
fastd-b9f329256d5911d9694b44ce1e4545d78fdd5340.zip
More documentation
-rw-r--r--src/async.c2
-rw-r--r--src/async.h24
-rw-r--r--src/buffer.h2
-rw-r--r--src/compat.h2
-rw-r--r--src/crypto.h6
-rw-r--r--src/dlist.h2
-rw-r--r--src/fastd.h2
-rw-r--r--src/handshake.h84
-rw-r--r--src/log.h2
-rw-r--r--src/method.h2
-rw-r--r--src/peer.c2
-rw-r--r--src/peer.h2
-rw-r--r--src/poll.c2
-rw-r--r--src/poll.h2
-rw-r--r--src/resolve.c2
-rw-r--r--src/sha256.c2
-rw-r--r--src/sha256.h2
-rw-r--r--src/shell.c2
-rw-r--r--src/shell.h2
-rw-r--r--src/types.h2
-rw-r--r--src/vector.c2
-rw-r--r--src/vector.h2
22 files changed, 90 insertions, 62 deletions
diff --git a/src/async.c b/src/async.c
index 6025ef3..fb1af41 100644
--- a/src/async.c
+++ b/src/async.c
@@ -24,7 +24,7 @@
*/
/**
- \file async.c
+ \file src/async.c
Asynchronous notifications
*/
diff --git a/src/async.h b/src/async.h
index ee81b73..4622c3c 100644
--- a/src/async.h
+++ b/src/async.h
@@ -24,7 +24,7 @@
*/
/**
- \file async.h
+ \file src/async.h
Asynchronous notifications
*/
@@ -45,26 +45,26 @@ typedef enum fastd_async_type {
/** A DNS resolver response */
typedef struct fastd_async_resolve_return {
- uint64_t peer_id;
- size_t remote;
+ uint64_t peer_id; /**< The ID of the peer the resolved remote belongs to */
+ size_t remote; /**< The index of the resolved remote */
- size_t n_addr;
- fastd_peer_address_t addr[];
+ size_t n_addr; /**< The number of addresses returned */
+ fastd_peer_address_t addr[]; /**< The resolved addresses */
} fastd_async_resolve_return_t;
/** A on-verify response */
typedef struct fastd_async_verify_return {
- bool ok;
+ bool ok; /**< true if the verification was successful */
- uint64_t peer_id;
+ uint64_t peer_id; /**< The ID of the verified peer */
- const fastd_method_info_t *method;
- fastd_socket_t *sock;
+ const fastd_method_info_t *method; /**< The method supplied in the handshake causing the verification */
+ fastd_socket_t *sock; /**< The socket the handshake causing the verification was received on */
- fastd_peer_address_t local_addr;
- fastd_peer_address_t remote_addr;
+ fastd_peer_address_t local_addr; /**< The local address the handshake was received on */
+ fastd_peer_address_t remote_addr; /**< The address the handshake was received from */
- uint8_t protocol_data[] __attribute__((aligned(8)));
+ uint8_t protocol_data[] __attribute__((aligned(8))); /**< Protocol-specific data */
} fastd_async_verify_return_t;
diff --git a/src/buffer.h b/src/buffer.h
index ac1df3d..afd18d5 100644
--- a/src/buffer.h
+++ b/src/buffer.h
@@ -24,7 +24,7 @@
*/
/**
- \file buffer.h
+ \file src/buffer.h
Buffer management
*/
diff --git a/src/compat.h b/src/compat.h
index 1e857a0..25e6be5 100644
--- a/src/compat.h
+++ b/src/compat.h
@@ -24,7 +24,7 @@
*/
/**
- \file compat.h
+ \file src/compat.h
Portablity definitions
*/
diff --git a/src/crypto.h b/src/crypto.h
index de2bddf..a228f5a 100644
--- a/src/crypto.h
+++ b/src/crypto.h
@@ -23,6 +23,12 @@
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
+/**
+ \file src/crypto.h
+
+ Cyptographic algorithm API and utilities
+*/
+
#pragma once
diff --git a/src/dlist.h b/src/dlist.h
index d1fc40c..a8118f0 100644
--- a/src/dlist.h
+++ b/src/dlist.h
@@ -24,7 +24,7 @@
*/
/**
- \file dlist.h
+ \file src/dlist.h
Doubly-linked lists
*/
diff --git a/src/fastd.h b/src/fastd.h
index 68a9f5b..50f90a9 100644
--- a/src/fastd.h
+++ b/src/fastd.h
@@ -24,7 +24,7 @@
*/
/**
- \file fastd.h
+ \file src/fastd.h
\em fastd main header file defining most data structures
*/
diff --git a/src/handshake.h b/src/handshake.h
index 7b5ebf3..34597ed 100644
--- a/src/handshake.h
+++ b/src/handshake.h
@@ -23,57 +23,72 @@
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
+/**
+ \file src/handshake.h
+
+ Functions and structures for composing and decomposing handshake packets
+*/
+
#pragma once
#include "fastd.h"
+/**
+ The type field of a handshake TLV record
+
+ In the handshake packet, the type field will be 2 bytes wide and big endian
+*/
typedef enum fastd_handshake_record_type {
- RECORD_HANDSHAKE_TYPE = 0,
- RECORD_REPLY_CODE,
- RECORD_ERROR_DETAIL,
- RECORD_FLAGS,
- RECORD_MODE,
- RECORD_PROTOCOL_NAME,
- RECORD_PROTOCOL1,
- RECORD_PROTOCOL2,
- RECORD_PROTOCOL3,
- RECORD_PROTOCOL4,
- RECORD_PROTOCOL5,
- RECORD_MTU,
- RECORD_METHOD_NAME,
- RECORD_VERSION_NAME,
- RECORD_METHOD_LIST,
- RECORD_TLV_MAC,
- RECORD_MAX,
+ RECORD_HANDSHAKE_TYPE = 0, /**< the handshake type (initial, response or finish) */
+ RECORD_REPLY_CODE, /**< The reply code */
+ RECORD_ERROR_DETAIL, /**< The error detail code */
+ RECORD_FLAGS, /**< The flags field */
+ RECORD_MODE, /**< The mode field */
+ RECORD_PROTOCOL_NAME, /**< The handshake protocol */
+ RECORD_PROTOCOL1, /**< Protocol-specific value 1 */
+ RECORD_PROTOCOL2, /**< Protocol-specific value 2 */
+ RECORD_PROTOCOL3, /**< Protocol-specific value 3 */
+ RECORD_PROTOCOL4, /**< Protocol-specific value 4 */
+ RECORD_PROTOCOL5, /**< Protocol-specific value 5 */
+ RECORD_MTU, /**< MTU field */
+ RECORD_METHOD_NAME, /**< The default/chosen method */
+ RECORD_VERSION_NAME, /**< The fastd version */
+ RECORD_METHOD_LIST, /**< Zero-separated list of supported methods */
+ RECORD_TLV_MAC, /**< Message authentication code of the TLV records */
+ RECORD_MAX, /**< (Number of defined record types) */
} fastd_handshake_record_type_t;
+/** The reply codes */
typedef enum fastd_reply_code {
- REPLY_SUCCESS = 0,
- REPLY_MANDATORY_MISSING,
- REPLY_UNACCEPTABLE_VALUE,
- REPLY_MAX,
+ REPLY_SUCCESS = 0, /**< The handshake was sucessfull */
+ REPLY_MANDATORY_MISSING, /**< A required TLV field is missing */
+ REPLY_UNACCEPTABLE_VALUE, /**< A TLV field has an invalid value */
+ REPLY_MAX, /**< (Number of defined reply codes */
} fastd_reply_code_t;
+/** The handshake packet structure (not including the initial packet type byte) */
typedef struct __attribute__((__packed__)) fastd_handshake_packet {
- uint8_t rsv;
- uint16_t tlv_len;
- uint8_t tlv_data[];
+ uint8_t rsv; /**< Reserved (must be 0) */
+ uint16_t tlv_len; /**< Length of the TLV records (before fastd v11 this was always 0, which is interpreted as "the whole packet") */
+ uint8_t tlv_data[]; /**< TLV record data */
} fastd_handshake_packet_t;
+/** A record descriptor */
typedef struct fastd_handshake_record {
- size_t length;
- uint8_t *data;
+ size_t length; /**< The length of the value */
+ uint8_t *data; /**< Points to the value of the TLV record */
} fastd_handshake_record_t;
+/** Describes a handshake packet */
struct fastd_handshake {
- uint8_t type;
- const char *peer_version;
- fastd_handshake_record_t records[RECORD_MAX];
- uint16_t tlv_len;
- void *tlv_data;
+ uint8_t type; /**< The handshake type */
+ const char *peer_version; /**< The fastd version of the peer */
+ fastd_handshake_record_t records[RECORD_MAX]; /**< The TLV records of the handshake */
+ uint16_t tlv_len; /**< The length of the TLV record data */
+ void *tlv_data; /**< TLV record data */
};
@@ -83,16 +98,19 @@ fastd_buffer_t fastd_handshake_new_reply(uint8_t type, const fastd_method_info_t
void fastd_handshake_handle(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);
+/** Returns the TLV data of a handshake packet in a given buffer */
static inline void* fastd_handshake_tlv_data(const fastd_buffer_t *buffer) {
fastd_handshake_packet_t *packet = buffer->data;
return packet->tlv_data;
}
+/** Returns the length the TLV data of a handshake packet in a given buffer */
static inline uint16_t fastd_handshake_tlv_len(const fastd_buffer_t *buffer) {
fastd_handshake_packet_t *packet = buffer->data;
return ntohs(packet->tlv_len);
}
+/** Adds an uninitialized TLV record of given type and length to a handshake buffer */
static inline uint8_t* fastd_handshake_extend(fastd_buffer_t *buffer, fastd_handshake_record_type_t type, size_t len) {
uint8_t *dst = buffer->data + buffer->len;
@@ -112,12 +130,14 @@ static inline uint8_t* fastd_handshake_extend(fastd_buffer_t *buffer, fastd_hand
return dst+4;
}
+/** Adds an TLV record of given type and length initialized with arbitraty data to a handshake buffer */
static inline void fastd_handshake_add(fastd_buffer_t *buffer, fastd_handshake_record_type_t type, size_t len, const void *data) {
uint8_t *dst = fastd_handshake_extend(buffer, type, len);
memcpy(dst, data, len);
}
+/** Adds an TLV record of given type and length initialized with zeros to a handshake buffer */
static inline uint8_t* fastd_handshake_add_zero(fastd_buffer_t *buffer, fastd_handshake_record_type_t type, size_t len) {
uint8_t *dst = fastd_handshake_extend(buffer, type, len);
@@ -125,12 +145,14 @@ static inline uint8_t* fastd_handshake_add_zero(fastd_buffer_t *buffer, fastd_ha
return dst;
}
+/** Adds an uint8 TLV record of given type and value to a handshake buffer */
static inline void fastd_handshake_add_uint8(fastd_buffer_t *buffer, fastd_handshake_record_type_t type, uint8_t value) {
uint8_t *dst = fastd_handshake_extend(buffer, type, 1);
dst[0] = value;
}
+/** Adds an uint16 TLV record of given type and value to a handshake buffer */
static inline void fastd_handshake_add_uint16(fastd_buffer_t *buffer, fastd_handshake_record_type_t type, uint16_t value) {
uint8_t *dst = fastd_handshake_extend(buffer, type, 2);
diff --git a/src/log.h b/src/log.h
index 8cfee16..ec11299 100644
--- a/src/log.h
+++ b/src/log.h
@@ -24,7 +24,7 @@
*/
/**
- \file log.h
+ \file src/log.h
Logging functions and macros
*/
diff --git a/src/method.h b/src/method.h
index 32b5b5c..da70a7b 100644
--- a/src/method.h
+++ b/src/method.h
@@ -24,7 +24,7 @@
*/
/**
- \file method.h
+ \file src/method.h
Management of encryption methods
*/
diff --git a/src/peer.c b/src/peer.c
index 63e0b2f..924d4b0 100644
--- a/src/peer.c
+++ b/src/peer.c
@@ -24,7 +24,7 @@
*/
/**
- \file peer.c
+ \file src/peer.c
Implementations of functions for peer management
*/
diff --git a/src/peer.h b/src/peer.h
index cd5bb15..5eb8b87 100644
--- a/src/peer.h
+++ b/src/peer.h
@@ -24,7 +24,7 @@
*/
/**
- \file peer.h
+ \file src/peer.h
Structures and functions for peer management
*/
diff --git a/src/poll.c b/src/poll.c
index 911fc2e..f10e619 100644
--- a/src/poll.c
+++ b/src/poll.c
@@ -24,7 +24,7 @@
*/
/**
- \file poll.c
+ \file src/poll.c
Portable polling API implementations
*/
diff --git a/src/poll.h b/src/poll.h
index ae9c8cd..456ee68 100644
--- a/src/poll.h
+++ b/src/poll.h
@@ -24,7 +24,7 @@
*/
/**
- \file poll.h
+ \file src/poll.h
Portable polling API
*/
diff --git a/src/resolve.c b/src/resolve.c
index 0415852..0635ddf 100644
--- a/src/resolve.c
+++ b/src/resolve.c
@@ -24,7 +24,7 @@
*/
/**
- \file resolve.c
+ \file src/resolve.c
DNS resolver functions
*/
diff --git a/src/sha256.c b/src/sha256.c
index c05adbc..bed55fd 100644
--- a/src/sha256.c
+++ b/src/sha256.c
@@ -24,7 +24,7 @@
*/
/**
- \file sha256.c
+ \file src/sha256.c
Small SHA256 and HMAC-SHA256 implementation
*/
diff --git a/src/sha256.h b/src/sha256.h
index a0b8805..2d45b2d 100644
--- a/src/sha256.h
+++ b/src/sha256.h
@@ -24,7 +24,7 @@
*/
/**
- \file sha256.h
+ \file src/sha256.h
Small SHA256 and HMAC-SHA256 implementation
*/
diff --git a/src/shell.c b/src/shell.c
index d8f044b..524d38e 100644
--- a/src/shell.c
+++ b/src/shell.c
@@ -25,7 +25,7 @@
/**
- \file shell.c
+ \file src/shell.c
Execution of shell commands and management of environment variables
*/
diff --git a/src/shell.h b/src/shell.h
index 9c2b8ab..3a402f7 100644
--- a/src/shell.h
+++ b/src/shell.h
@@ -24,7 +24,7 @@
*/
/**
- \file shell.h
+ \file src/shell.h
Execution of shell commands and management of environment variables
*/
diff --git a/src/types.h b/src/types.h
index 2dae259..6854a7c 100644
--- a/src/types.h
+++ b/src/types.h
@@ -24,7 +24,7 @@
*/
/**
- \file types.h
+ \file src/types.h
Basic enums and typedefs for common types
*/
diff --git a/src/vector.c b/src/vector.c
index 4bf5853..4b451b1 100644
--- a/src/vector.c
+++ b/src/vector.c
@@ -24,7 +24,7 @@
*/
/**
- \file vector.c
+ \file src/vector.c
Typesafe dynamically sized arrays
*/
diff --git a/src/vector.h b/src/vector.h
index 0a61341..526dfaf 100644
--- a/src/vector.h
+++ b/src/vector.h
@@ -24,7 +24,7 @@
*/
/**
- \file vector.h
+ \file src/vector.h
Typesafe dynamically sized arrays
*/