documentation

include/llarp/address_info.h

@@ -5,12 +5,19 @@
 #include <llarp/net.h>
 #include <stdbool.h>
 
+/**
+ * address_info.h
+ *
+ * utilities for handling addresses on the llarp network
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 #define MAX_AI_DIALECT_SIZE 5
 
+/// address information model
 struct llarp_ai
 {
   uint16_t rank;
@@ -20,52 +27,65 @@ struct llarp_ai
   uint16_t port;
 };
 
+/// convert address information struct to bencoded buffer
 bool
 llarp_ai_bencode(struct llarp_ai *ai, llarp_buffer_t *buff);
 
+/// convert bencoded buffer to address information struct
 bool
 llarp_ai_bdecode(struct llarp_ai *ai, llarp_buffer_t *buff);
 
 struct llarp_ai_list;
 
+/// list of address information initialization
 struct llarp_ai_list *
 llarp_ai_list_new(struct llarp_alloc *mem);
 
+/// list of address information destruction
 void
 llarp_ai_list_free(struct llarp_ai_list *l);
 
+/// copy AI
 void
 llarp_ai_copy(struct llarp_ai *dst, struct llarp_ai *src);
 
+/// convert llarp_ai_list struct to bencoded buffer
 bool
 llarp_ai_list_bencode(struct llarp_ai_list *l, llarp_buffer_t *buff);
 
+/// convert bencoded buffer to llarp_ai_list struct
 bool
 llarp_ai_list_bdecode(struct llarp_ai_list *l, llarp_buffer_t *buff);
 
+/// return and remove first element from ai_list
 struct llarp_ai
 llarp_ai_list_popfront(struct llarp_ai_list *l);
 
-/** pushes a copy of ai to the end of the list */
+/// pushes a copy of ai to the end of the list
 void
 llarp_ai_list_pushback(struct llarp_ai_list *l, struct llarp_ai *ai);
 
+/// get the number of entries in list
 size_t
 llarp_ai_list_size(struct llarp_ai_list *l);
 
+/// does this index exist in list
 bool
 llarp_ai_list_index(struct llarp_ai_list *l, ssize_t idx,
                     struct llarp_ai *result);
 
+/// ai_list iterator configuration
 struct llarp_ai_list_iter
 {
+  /// a customizable pointer to pass data to iteration functor
   void *user;
-  /** set by llarp_ai_list_iterate() */
+  /// set by llarp_ai_list_iterate()
   struct llarp_ai_list *list;
-  /** return false to break iteration */
+  /// return false to break iteration early
   bool (*visit)(struct llarp_ai_list_iter *, struct llarp_ai *);
 };
 
+/// iterator over list and call visit functor
 void
 llarp_ai_list_iterate(struct llarp_ai_list *l, struct llarp_ai_list_iter *iter);
 

include/llarp/bencode.h

@@ -6,6 +6,14 @@
 #include <stdbool.h>
 #include <stdint.h>
 
+/**
+ * bencode.h
+ *
+ * helper functions for handling bencoding
+ * https://en.wikipedia.org/wiki/Bencode for more information on the format
+ * we utilize llarp_buffer which provides memory management
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -127,7 +135,9 @@ bdecode_read_string(llarp_buffer_t* buffer, llarp_buffer_t* result)
 
 struct dict_reader
 {
+  /// makes passing data into on_key easier
   llarp_buffer_t* buffer;
+  /// not currently used, maybe used in the future to pass additional information to on_key
   void* user;
   /**
    * called when we got a key string, return true to continue iteration
@@ -139,21 +149,21 @@ struct dict_reader
 static bool INLINE
 bdecode_read_dict(llarp_buffer_t* buff, struct dict_reader* r)
 {
-  llarp_buffer_t strbuf;
+  llarp_buffer_t strbuf; // temporary buffer for current element
-  r->buffer = buff;
+  r->buffer = buff; // set up dict_reader
-  if(*r->buffer->cur != 'd')
+  if(*r->buffer->cur != 'd') // ensure is a dictionary
     return false;
   r->buffer->cur++;
   while(llarp_buffer_size_left(r->buffer) && *r->buffer->cur != 'e')
   {
     if(bdecode_read_string(r->buffer, &strbuf))
     {
-      if(!r->on_key(r, &strbuf))
+      if(!r->on_key(r, &strbuf)) // check for early abort
         return false;
     }
   }
 
-  if(*r->buffer->cur != 'e')
+  if(*r->buffer->cur != 'e') // make sure we're at dictionary end
     return false;
   r->buffer->cur++;
   return r->on_key(r, 0);
@@ -161,8 +171,14 @@ bdecode_read_dict(llarp_buffer_t* buff, struct dict_reader* r)
 
 struct list_reader
 {
+  /// makes passing data into on_item easier
   llarp_buffer_t* buffer;
+  /// not currently used, maybe used in the future to pass additional information to on_item
   void* user;
+  /**
+   * called when we got an element, return true to continue iteration
+   * called with null item on iteration completion
+   */
   bool (*on_item)(struct list_reader*, bool);
 };
 
@@ -170,16 +186,16 @@ static bool INLINE
 bdecode_read_list(llarp_buffer_t* buff, struct list_reader* r)
 {
   r->buffer = buff;
-  if(*r->buffer->cur != 'l')
+  if(*r->buffer->cur != 'l') // ensure is a list
     return false;
 
   r->buffer->cur++;
   while(llarp_buffer_size_left(r->buffer) && *r->buffer->cur != 'e')
   {
-    if(!r->on_item(r, true))
+    if(!r->on_item(r, true)) // check for early abort
       return false;
   }
-  if(*r->buffer->cur != 'e')
+  if(*r->buffer->cur != 'e') // make sure we're at a list end
     return false;
   r->buffer->cur++;
   return r->on_item(r, false);

include/llarp/buffer.h

@@ -7,6 +7,12 @@
 #include <stdlib.h>
 #include <string.h>
 
+/**
+ * buffer.h
+ *
+ * buffer used for bencoding
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -15,27 +21,35 @@ typedef uint8_t byte_t;
 
 typedef struct llarp_buffer_t
 {
+  /// starting memory address
   byte_t *base;
+  /// memory address of stream position
   byte_t *cur;
+  /// max size of buffer
   size_t sz;
 } llarp_buffer_t;
 
+/// how much room is left in buffer
 size_t
 llarp_buffer_size_left(llarp_buffer_t *buff);
 
+/// write a chunk of data size "sz"
 bool
 llarp_buffer_write(llarp_buffer_t *buff, const void *data, size_t sz);
 
+/// write multiple strings
 bool
 llarp_buffer_writef(llarp_buffer_t *buff, const char *fmt, ...);
 
+/// read from file into buff using allocator "mem"
 bool
 llarp_buffer_readfile(llarp_buffer_t *buff, FILE *f, struct llarp_alloc *mem);
 
+/// read buffer upto character delimiter
 size_t
 llarp_buffer_read_until(llarp_buffer_t *buff, char delim, byte_t *result,
                         size_t resultlen);
-
+/// compare buffers, true if equal else false
 bool
 llarp_buffer_eq(llarp_buffer_t buff, const char *data);
 

include/llarp/config.h

@@ -1,31 +1,43 @@
 #ifndef LLARP_CONFIG_H_
 #define LLARP_CONFIG_H_
 
+/**
+ * config.h
+ *
+ * library configuration utilties
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 struct llarp_config;
 
+/// allocate config
 void
 llarp_new_config(struct llarp_config **conf);
+
+/// deallocate config
 void
 llarp_free_config(struct llarp_config **conf);
 
-/** @brief return -1 on fail otherwiwse 0 */
+/// @brief return -1 on fail otherwiwse 0
 int
 llarp_load_config(struct llarp_config *conf, const char *fname);
 
+/// config iterator configuration
 struct llarp_config_iterator
 {
+  /// a customizable pointer to pass data to iteration functor
   void *user;
-  /** set by llarp_config_iter */
+  /// set by llarp_config_iter
   struct llarp_config *conf;
-  /** visit (self, section, key, value) */
+  /// visit (self, section, key, value)
   void (*visit)(struct llarp_config_iterator *, const char *, const char *,
                 const char *);
 };
 
+/// iterator over "conf" and call visit functor defined in "iter"
 void
 llarp_config_iter(struct llarp_config *conf,
                   struct llarp_config_iterator *iter);

include/llarp/crypto.h

@@ -4,6 +4,14 @@
 #include <llarp/common.h>
 #include <stdbool.h>
 #include <stdint.h>
+
+/**
+ * crypto.h
+ *
+ * libsodium abstraction layer
+ * potentially allow libssl support in the future
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -30,9 +38,11 @@ typedef byte_t llarp_hmacsec_t[HMACSECSIZE];
 typedef byte_t llarp_sig_t[SIGSIZE];
 typedef byte_t llarp_tunnel_nonce_t[TUNNONCESIZE];
 
+/// get public key from secret
 byte_t *
 llarp_seckey_topublic(byte_t *secret);
 
+/// label functors
 typedef bool (*llarp_dh_func)(llarp_sharedkey_t *, llarp_pubkey_t,
                               llarp_tunnel_nonce_t, llarp_seckey_t);
 
@@ -52,6 +62,7 @@ typedef bool (*llarp_sign_func)(byte_t *, const byte_t *, llarp_buffer_t);
 typedef bool (*llarp_verify_func)(const byte_t *, llarp_buffer_t,
                                   const byte_t *);
 
+/// library crypto configuration
 struct llarp_crypto
 {
   llarp_sym_cipher_func xchacha20;
@@ -69,9 +80,11 @@ struct llarp_crypto
   void (*keygen)(byte_t *);
 };
 
+/// allocate crypto
 void
 llarp_crypto_libsodium_init(struct llarp_crypto *c);
 
+/// initialize crypto
 bool
 llarp_crypto_initialized(struct llarp_crypto *c);
 

include/llarp/crypto_async.h

@@ -5,93 +5,118 @@
 #include <llarp/logic.h>
 #include <llarp/threadpool.h>
 
+/**
+ * crypto_async.h
+ *
+ * asynchronous crypto functions
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/// defined in crypto_async.cpp
 struct llarp_async_iwp;
 
+/// allocator
 struct llarp_async_iwp *
 llarp_async_iwp_new(struct llarp_alloc *mem, struct llarp_crypto *crypto,
                     struct llarp_logic *logic, struct llarp_threadpool *worker);
 
+/// deallocator
 void
 llarp_async_iwp_free(struct llarp_async_iwp *iwp);
 
 struct iwp_async_keygen;
 
+/// define functor for keygen
 typedef void (*iwp_keygen_hook)(struct iwp_async_keygen *);
 
+/// key generation request
 struct iwp_async_keygen
 {
+  /// internal wire protocol async configuration
   struct llarp_async_iwp *iwp;
+  /// a customizable pointer to pass data to iteration functor
   void *user;
+  /// destination key buffer
   uint8_t *keybuf;
+  /// iteration functor
   iwp_keygen_hook hook;
 };
 
+/// generate a key by iterating on "iwp" using "keygen" request
 void
 iwp_call_async_keygen(struct llarp_async_iwp *iwp,
                       struct iwp_async_keygen *keygen);
 
 struct iwp_async_intro;
 
+/// iwp_async_intro functor
 typedef void (*iwp_intro_hook)(struct iwp_async_intro *);
 
+/// iwp_async_intro request
 struct iwp_async_intro
 {
   struct llarp_async_iwp *iwp;
   void *user;
   uint8_t *buf;
   size_t sz;
-  /** nonce paramter */
+  /// nonce paramter
   uint8_t *nonce;
-  /** remote public key */
+  /// remote public key
   uint8_t *remote_pubkey;
-  /** local private key */
+  /// local private key
   uint8_t *secretkey;
-  /** callback */
+  /// callback
   iwp_intro_hook hook;
 };
 
+/// introduce internal wire protocol "iwp" using "intro" request
 void
 iwp_call_async_gen_intro(struct llarp_async_iwp *iwp,
                          struct iwp_async_intro *intro);
 
 struct iwp_async_introack;
 
+/// introduction acknowledgement functor
 typedef void (*iwp_introack_hook)(struct iwp_async_introack *);
 
+/// introduction acknowledgement request
 struct iwp_async_introack
 {
   struct llarp_async_iwp *iwp;
   void *user;
   uint8_t *buf;
   size_t sz;
-  /** nonce paramter */
+  /// nonce paramter
   uint8_t *nonce;
-  /** token paramter */
+  /// token paramter
   uint8_t *token;
-  /** remote public key */
+  /// remote public key
   uint8_t *remote_pubkey;
-  /** local private key */
+  /// local private key
   uint8_t *secretkey;
-  /** callback */
+  /// callback
   iwp_introack_hook hook;
 };
 
+/// generate introduction acknowledgement "iwp" using "introack" request
 void
 iwp_call_async_gen_introack(struct llarp_async_iwp *iwp,
                             struct iwp_async_introack *introack);
 
+/// verify introduction acknowledgement "iwp" using "introack" request
 void
 iwp_call_async_verify_introack(struct llarp_async_iwp *iwp,
                                struct iwp_async_introack *introack);
 
 struct iwp_async_session_start;
 
+/// start session functor
 typedef void (*iwp_session_start_hook)(struct iwp_async_session_start *);
 
+/// start session request
 struct iwp_async_session_start
 {
   struct llarp_async_iwp *iwp;
@@ -106,16 +131,19 @@ struct iwp_async_session_start
   iwp_session_start_hook hook;
 };
 
+/// generate session start "iwp" using "start" request
 void
 iwp_call_async_gen_session_start(struct llarp_async_iwp *iwp,
                                  struct iwp_async_session_start *start);
 
+/// verify session start "iwp" using "start" request
 void
 iwp_call_async_verify_session_start(struct llarp_async_iwp *iwp,
                                     struct iwp_async_session_start *start);
 
 struct iwp_async_frame;
 
+/// internal wire protocol frame request
 typedef void (*iwp_async_frame_hook)(struct iwp_async_frame *);
 
 struct iwp_async_frame
@@ -128,10 +156,12 @@ struct iwp_async_frame
   uint8_t buf[1500];
 };
 
+/// decrypt iwp frame "iwp" using "frame" request
 void
 iwp_call_async_frame_decrypt(struct llarp_async_iwp *iwp,
                              struct iwp_async_frame *frame);
 
+/// encrypt iwp frame "iwp" using "frame" request
 void
 iwp_call_async_frame_encrypt(struct llarp_async_iwp *iwp,
                              struct iwp_async_frame *frame);

include/llarp/dht.h

@@ -1,13 +1,23 @@
 #ifndef LLARP_DHT_H_
 #define LLARP_DHT_H_
+
+/**
+ * dht.h
+ *
+ * DHT functions
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 struct llarp_dht_context;
 
+/// allocator
 struct llarp_dht_context*
 llarp_dht_context_new();
+
+/// deallocator
 void
 llarp_dht_context_free(struct llarp_dht_context* dht);
 

include/llarp/dtls.h

@@ -4,10 +4,18 @@
 #include <llarp/link.h>
 #include <llarp/mem.h>
 
+/**
+ * dtls.h
+ *
+ * Datagram TLS functions
+ * https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security for more info on DTLS
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/// DTLS configuration
 struct llarp_dtls_args
 {
   struct llarp_alloc* mem;
@@ -15,6 +23,7 @@ struct llarp_dtls_args
   const char* certfile;
 };
 
+/// allocator
 void
 dtls_link_init(struct llarp_link* link, struct llarp_dtls_args args,
                struct llarp_msg_muxer* muxer);

include/llarp/ev.h

@@ -7,23 +7,35 @@
 #include <stdlib.h>
 #include <sys/socket.h>
 
+/**
+ * ev.h
+ *
+ * event handler (cross platform high performance event system for IO)
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 struct llarp_ev_loop;
 
+/// allocator
 void
 llarp_ev_loop_alloc(struct llarp_ev_loop **ev);
+
+// deallocator
 void
 llarp_ev_loop_free(struct llarp_ev_loop **ev);
 
+/// run main loop
 int
 llarp_ev_loop_run(struct llarp_ev_loop *ev);
-/** stop event loop and wait for it to complete all jobs */
+
+/// stop event loop and wait for it to complete all jobs
 void
 llarp_ev_loop_stop(struct llarp_ev_loop *ev);
 
+/// UDP handling configuration
 struct llarp_udp_io
 {
   struct sockaddr addr;
@@ -34,13 +46,16 @@ struct llarp_udp_io
                    ssize_t);
 };
 
+/// add UDP handler
 int
 llarp_ev_add_udp(struct llarp_ev_loop *ev, struct llarp_udp_io *udp);
 
+/// schedule UDP packet
 int
 llarp_ev_udp_sendto(struct llarp_udp_io *udp, const struct sockaddr *to,
                     const void *data, size_t sz);
 
+/// close UDP handler
 int
 llarp_ev_close_udp(struct llarp_udp_io *udp);
 

include/llarp/exit_info.h

@@ -4,10 +4,17 @@
 #include <llarp/crypto.h>
 #include <llarp/net.h>
 
+/**
+ * exit_info.h
+ *
+ * utilities for handling exits on the llarp network
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/// Exit info model
 struct llarp_xi
 {
   struct in6_addr address;