From d5da100c55d80391d2e941a41c0e0dccf2a6e33e Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Wed, 28 May 2014 04:52:58 +0200 Subject: Still more documentation --- src/methods/common.c | 9 +++++++++ src/methods/common.h | 53 ++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 56 insertions(+), 6 deletions(-) (limited to 'src/methods') diff --git a/src/methods/common.c b/src/methods/common.c index 3fb8561..d26f009 100644 --- a/src/methods/common.c +++ b/src/methods/common.c @@ -23,10 +23,17 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + \file + + Definitions for the common packet format used by most methods +*/ + #include "common.h" +/** Common initialization for a new session */ void fastd_method_common_init(fastd_method_common_t *session, bool initiator) { memset(session, 0, sizeof(*session)); @@ -42,6 +49,7 @@ void fastd_method_common_init(fastd_method_common_t *session, bool initiator) { } } +/** Checks if a received nonce is valid */ bool fastd_method_is_nonce_valid(const fastd_method_common_t *session, const uint8_t nonce[COMMON_NONCEBYTES], int64_t *age) { if ((nonce[0] & 1) != (session->receive_nonce[0] & 1)) return false; @@ -67,6 +75,7 @@ bool fastd_method_is_nonce_valid(const fastd_method_common_t *session, const uin return true; } +/** Checks if a possibly reordered packet should be accepted */ bool fastd_method_reorder_check(fastd_peer_t *peer, fastd_method_common_t *session, const uint8_t nonce[COMMON_NONCEBYTES], int64_t age) { if (age < 0) { size_t shift = age < (-64) ? 64 : ((size_t)-age); diff --git a/src/methods/common.h b/src/methods/common.h index 7b0a4ff..7a06f92 100644 --- a/src/methods/common.h +++ b/src/methods/common.h @@ -23,26 +23,37 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + \file + + Definitions for the common packet format used by most methods +*/ + #pragma once #include "../fastd.h" +/** The length of the nonce in the common method packet header */ #define COMMON_NONCEBYTES 6 +/** The length of the flags in the common method packet header */ #define COMMON_FLAGBYTES 1 +/** The length of the common method packet header */ #define COMMON_HEADBYTES (COMMON_NONCEBYTES+COMMON_FLAGBYTES) + +/** Common method session state */ typedef struct fastd_method_common { - struct timespec valid_till; - struct timespec refresh_after; + struct timespec valid_till; /**< How long the session is valid */ + struct timespec refresh_after; /**< When to try refreshing the session */ - uint8_t send_nonce[COMMON_NONCEBYTES]; - uint8_t receive_nonce[COMMON_NONCEBYTES]; + uint8_t send_nonce[COMMON_NONCEBYTES]; /**< The next nonce to use */ + uint8_t receive_nonce[COMMON_NONCEBYTES]; /**< The hightest nonce received to far for this session */ - struct timespec reorder_timeout; - uint64_t receive_reorder_seen; + struct timespec reorder_timeout; /**< How long to packets with a lower sequence number (nonce) than the newest received */ + uint64_t receive_reorder_seen; /**< Bitmap specifying which of the 64 sequence numbers (nonces) before \a receive_nonce have bit seen */ } fastd_method_common_t; @@ -51,6 +62,11 @@ bool fastd_method_is_nonce_valid(const fastd_method_common_t *session, const uin bool fastd_method_reorder_check(fastd_peer_t *peer, fastd_method_common_t *session, const uint8_t nonce[COMMON_NONCEBYTES], int64_t age); +/** + The common \a session_is_valid implementation + + A session is valid when session->valid_till has not timeouted, unless almost all nonces have been used up (which \b should be impossible) +*/ static inline bool fastd_method_session_common_is_valid(const fastd_method_common_t *session) { if (session->send_nonce[0] == 0xff && session->send_nonce[1] == 0xff) return false; @@ -58,10 +74,20 @@ static inline bool fastd_method_session_common_is_valid(const fastd_method_commo return (!fastd_timed_out(&session->valid_till)); } +/** + The common \a session_is_initiator implementation + + The initiator of a session uses the odd nonces, the responder the even ones. +*/ static inline bool fastd_method_session_common_is_initiator(const fastd_method_common_t *session) { return (session->send_nonce[COMMON_NONCEBYTES-1] & 1); } +/** + The common \a session_want_refresh implementation + + A session wants to be refreshed when session->refresh_after has timeouted, or if lots of nonces have been used up +*/ static inline bool fastd_method_session_common_want_refresh(const fastd_method_common_t *session) { if (session->send_nonce[0] == 0xff) return true; @@ -72,6 +98,7 @@ static inline bool fastd_method_session_common_want_refresh(const fastd_method_c return false; } +/** The common \a session_superseded implementation */ static inline void fastd_method_session_common_superseded(fastd_method_common_t *session) { struct timespec valid_max = fastd_in_seconds(KEY_VALID_OLD); @@ -79,6 +106,12 @@ static inline void fastd_method_session_common_superseded(fastd_method_common_t session->valid_till = valid_max; } +/** + Increments the send nonce + + As one side of a connection uses the even nonces and the other side the odd ones, + the nonce is always incremented by 2. +*/ static inline void fastd_method_increment_nonce(fastd_method_common_t *session) { session->send_nonce[COMMON_NONCEBYTES-1] += 2; @@ -91,22 +124,30 @@ static inline void fastd_method_increment_nonce(fastd_method_common_t *session) } } +/** Adds the common header to a packet buffer */ static inline void fastd_method_put_common_header(fastd_buffer_t *buffer, const uint8_t nonce[COMMON_NONCEBYTES], uint8_t flags) { fastd_buffer_pull_head_from(buffer, nonce, COMMON_NONCEBYTES); fastd_buffer_pull_head_from(buffer, &flags, 1); } +/** Removes the common header from a packet buffer */ static inline void fastd_method_take_common_header(fastd_buffer_t *buffer, uint8_t nonce[COMMON_NONCEBYTES], uint8_t *flags) { fastd_buffer_push_head_to(buffer, flags, 1); fastd_buffer_push_head_to(buffer, nonce, COMMON_NONCEBYTES); } +/** Handles the common header of a packet */ static inline bool fastd_method_handle_common_header(const fastd_method_common_t *session, fastd_buffer_t *buffer, uint8_t nonce[COMMON_NONCEBYTES], uint8_t *flags, int64_t *age) { fastd_method_take_common_header(buffer, nonce, flags); return fastd_method_is_nonce_valid(session, nonce, age); } +/** + Expands a nonce from COMMON_NONCEBYTES to a buffer of arbitrary length + + The last byte of the buffer is set to 1 as many cryptographic algorithms are specified to have a counter starting with 1 concatenated to the nonce +*/ static inline void fastd_method_expand_nonce(uint8_t *buf, const uint8_t nonce[COMMON_NONCEBYTES], size_t len) { if (!len) return; -- cgit v1.2.3