From b9f329256d5911d9694b44ce1e4545d78fdd5340 Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Tue, 27 May 2014 23:30:48 +0200 Subject: More documentation --- src/handshake.h | 84 ++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 53 insertions(+), 31 deletions(-) (limited to 'src/handshake.h') 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); -- cgit v1.2.3