added comments

src/ts3init_cache.h

@@ -1,10 +1,22 @@
 #ifndef _TS3INIT_CACHE_H
 #define _TS3INIT_CACHE_H
 
+/*
+ * Returns the current unix_time from cache, updated once every second.
+ */
 time_t ts3init_get_cached_unix_time(void);
 
+
+/*
+ * Returns the cookie for a packet_index. 
+ * If the cookie is not in the cache, it will be generated using the seed.
+ */
 bool ts3init_get_cookie_for_packet_index(u8 packet_index, const u8* seed, u64 (*cookie)[2]);
 
+/*
+ * Returns the current cookie and packet_index.
+ * If the cookie is not in the cache, it will be generated using the seed.
+ */
 bool ts3init_get_current_cookie(const u8* seed, u64 (*cookie)[2], u8 *packet_index);
                 
 #endif /* _TS3INIT_CACHE_H */

src/ts3init_cookie.h

@@ -16,10 +16,20 @@ struct xt_ts3init_cookie_cache
     };
 };
 
+/*
+ * Returns the cookie that fits current_time and packet_index.
+ * If the cookie is missing in cache it will be generated using 
+ * cookie_seed and current_time
+ */
 __u64* ts3init_get_cookie_seed(time_t current_time, __u8 packet_index, 
                 struct xt_ts3init_cookie_cache* cache,
                 const __u8* cookie_seed);
 
+/* 
+ * Returns the hash of cookie and source/destination address/port.
+ * Ip and udp are the recieved headers from the client, k0 and k1 are the
+ * cookie, and out is the resulting hash.
+ */
 int ts3init_calculate_cookie_ipv6(const struct ipv6hdr *ip, const struct udphdr *udp, 
                                   __u64 k0, __u64 k1, __u64* out);
 int ts3init_calculate_cookie_ipv4(const struct iphdr *ip, const struct udphdr *udp, 

src/ts3init_cookie_seed.h

@@ -6,6 +6,10 @@ enum {
 	COOKIE_PATH_MAX = 256,
 };
 
+/* 
+ * Parses a hexstring into dest.
+ * It is assumed that COOKIE_SEED_LEN bytes are to be parsed.
+ */
 static inline bool hex2int_seed(const char *src, __u8* dst)
 {
     int i, j;
@@ -28,6 +32,9 @@ static inline bool hex2int_seed(const char *src, __u8* dst)
 
 #ifndef __KERNEL__
 
+/* 
+ * Reads a cookie seed from a file.
+ */
 static inline bool read_cookie_seed_from_file(const char *module_name, const char *path, __u8* dst)
 {
 	int n, fd;

src/ts3init_header.h

@@ -1,6 +1,9 @@
 #ifndef _TS3INIT_HEADER_H
 #define _TS3INIT_HEADER_H
 
+/*
+ * Magic number of a TS3INIT packet.
+ */
 struct ts3_init_header_tag
 {
     union
@@ -10,6 +13,9 @@ struct ts3_init_header_tag
     };
 };
 
+/* 
+ * Header of a TS3INIT client packet.
+ */
 struct ts3_init_header
 {
     struct ts3_init_header_tag tag;
@@ -21,6 +27,9 @@ struct ts3_init_header
     __u8   payload[20];
 };
 
+/*
+ * The available TS3INIT commands, both client and server.
+ */
 enum
 {
     COMMAND_GET_COOKIE = 0,

src/ts3init_match.c

@@ -26,6 +26,7 @@
 #include "ts3init_header.h"
 #include "ts3init_cache.h"
 
+/* Magic number of a TS3INIT packet. */
 static const struct ts3_init_header_tag ts3init_header_tag_signature =
     { .tag8 = {'T', 'S', '3', 'I', 'N', 'I', 'T', '1'} };
 
@@ -39,6 +40,10 @@ struct ts3_init_checked_header_data
 static const int header_size = 18;
 static int ts3init_payload_sizes[] = { 16, 20, 20, 244, -1, 1 };
 
+/* 
+ * Check that skb contains a valid TS3INIT client header.
+ * Also initializes header_data, and checks client version.
+ */
 static bool check_header(const struct sk_buff *skb, const struct xt_action_param *par,
     struct ts3_init_checked_header_data* header_data, __u32 min_client_version)
 {
@@ -89,6 +94,9 @@ static bool check_header(const struct sk_buff *skb, const struct xt_action_param
     return true;
 }
 
+/*
+ * Hashes the cookie with source/destination address/port.
+ */
 static int calculate_cookie(const struct sk_buff *skb, const struct xt_action_param *par, 
                        struct udphdr *udp, __u64 k0, __u64 k1, __u64* out)
 {
@@ -127,6 +135,10 @@ static int calculate_cookie(const struct sk_buff *skb, const struct xt_action_pa
     }
 }
 
+/*
+ * The 'ts3init_get_cookie' match handler.
+ * Checks that the packet is a valid COMMAND_GET_COOKIE.
+ */
 static bool
 ts3init_get_cookie_mt(const struct sk_buff *skb, struct xt_action_param *par)
 {
@@ -156,6 +168,9 @@ ts3init_get_cookie_mt(const struct sk_buff *skb, struct xt_action_param *par)
     return true;
 }
 
+/*
+ * Validates matchinfo recieved from userspace.
+ */
 static int ts3init_get_cookie_mt_check(const struct xt_mtchk_param *par)
 {
     struct xt_ts3init_get_cookie_mtinfo *info = par->matchinfo;
@@ -181,6 +196,11 @@ static int ts3init_get_cookie_mt_check(const struct xt_mtchk_param *par)
     return 0;
 }
 
+/*
+ * The 'ts3init_get_cookie' match handler.
+ * Checks that the packet is a valid COMMAND_GET_PUZZLE, and if the replied
+ * with the correct cookie.
+ */
 static bool ts3init_get_puzzle_mt(const struct sk_buff *skb, struct xt_action_param *par)
 {
     const struct xt_ts3init_get_puzzle_mtinfo *info = par->matchinfo;
@@ -218,6 +238,9 @@ static bool ts3init_get_puzzle_mt(const struct sk_buff *skb, struct xt_action_pa
     return true;
 }
 
+/*
+ * Validates matchinfo recieved from userspace.
+ */
 static int ts3init_get_puzzle_mt_check(const struct xt_mtchk_param *par)
 {
     struct xt_ts3init_get_puzzle_mtinfo *info = par->matchinfo;

src/ts3init_target.c

@@ -32,6 +32,9 @@
 #include "ts3init_cache.h"
 
 
+/*
+ * Send a reply back to the client
+ */
 static bool
 ts3init_send_ipv6_reply(struct sk_buff *oldskb, const struct xt_action_param *par, 
                         const struct ipv6hdr *oldip, const struct udphdr *oldudp,
@@ -105,6 +108,9 @@ ts3init_send_ipv6_reply(struct sk_buff *oldskb, const struct xt_action_param *pa
     return false;
 }
 
+/*
+ * Send a reply back to the client
+ */
 static bool
 ts3init_send_ipv4_reply(struct sk_buff *oldskb, const struct xt_action_param *par, 
                         const struct iphdr *oldip, const struct udphdr *oldudp,
@@ -170,8 +176,13 @@ ts3init_send_ipv4_reply(struct sk_buff *oldskb, const struct xt_action_param *pa
     return false;
 }
 
+/* The payload replied by TS3INIT_RESET. */
 static const char ts3init_reset_packet[] = {'T', 'S', '3', 'I', 'N', 'I', 'T', '1', 0x65, 0, 0x88, COMMAND_RESET, 0 };
 
+/* 
+ * The 'TS3INIT_RESET' target handler.
+ * Always replies with COMMAND_RESET and drops the packet
+ */
 static unsigned int
 ts3init_reset_ipv4_tg(struct sk_buff *skb, const struct xt_action_param *par)
 {
@@ -186,6 +197,10 @@ ts3init_reset_ipv4_tg(struct sk_buff *skb, const struct xt_action_param *par)
     return NF_DROP;
 }
 
+/* 
+ * The 'TS3INIT_RESET' target handler.
+ * Always replies with COMMAND_RESET and drops the packet.
+ */
 static unsigned int
 ts3init_reset_ipv6_tg(struct sk_buff *skb, const struct xt_action_param *par)
 {
@@ -200,8 +215,13 @@ ts3init_reset_ipv6_tg(struct sk_buff *skb, const struct xt_action_param *par)
     return NF_DROP;
 }
 
+/* The header replied by TS3INIT_SET_COOKIE. */
 static const char ts3init_set_cookie_packet_header[12] = {'T', 'S', '3', 'I', 'N', 'I', 'T', '1', 0x65, 0, 0x88, COMMAND_SET_COOKIE };
 
+/* 
+ * Returns the current cookie hashed with source/destination address/port,
+ * and the current packet_index.
+ */
 static bool
 ts3init_generate_cookie_ipv4(const struct xt_action_param *par,
                              const struct iphdr *ip, const struct udphdr *udp,
@@ -217,6 +237,10 @@ ts3init_generate_cookie_ipv4(const struct xt_action_param *par,
     return true;
 }
 
+/* 
+ * Returns the current cookie hashed with source/destination address/port,
+ * and the current packet_index.
+ */
 static bool
 ts3init_generate_cookie_ipv6(const struct xt_action_param *par, 
                              const struct ipv6hdr *ip, const struct udphdr *udp,
@@ -232,6 +256,9 @@ ts3init_generate_cookie_ipv6(const struct xt_action_param *par,
     return true;
 }
 
+/*
+ * Fills 'newpayload' with a TS3INIT_SET_COOKIE packet.
+ */
 static bool
 ts3init_fill_set_cookie_payload(const struct sk_buff *skb,
                                 const struct xt_action_param *par, 
@@ -273,6 +300,10 @@ ts3init_fill_set_cookie_payload(const struct sk_buff *skb,
     return true;
 }
 
+/* 
+ * The 'TS3INIT_SET_COOKIE' target handler.
+ * Always replies with TS3INIT_SET_COOKIE and drops the packet.
+ */
 static unsigned int
 ts3init_set_cookie_ipv4_tg(struct sk_buff *skb, const struct xt_action_param *par)
 {
@@ -295,6 +326,10 @@ ts3init_set_cookie_ipv4_tg(struct sk_buff *skb, const struct xt_action_param *pa
     return NF_DROP;
 }
 
+/* 
+ * The 'TS3INIT_SET_COOKIE' target handler.
+ * Always replies with TS3INIT_SET_COOKIE and drops the packet.
+ */
 static unsigned int
 ts3init_set_cookie_ipv6_tg(struct sk_buff *skb, const struct xt_action_param *par)
 {
@@ -317,6 +352,9 @@ ts3init_set_cookie_ipv6_tg(struct sk_buff *skb, const struct xt_action_param *pa
     return NF_DROP;
 }
 
+/*
+ * Validates targinfo recieved from userspace.
+ */
 static int ts3init_set_cookie_tg_check(const struct xt_tgchk_param *par)
 {
     struct xt_ts3init_set_cookie_tginfo *info = par->targinfo;