[hipl-commit] [trunk] Rev 3999: Doxygen for oppdb.c

  • From: Miika Komu <miika@xxxxxx>
  • To: hipl-commit@xxxxxxxxxxxxx
  • Date: Thu, 18 Mar 2010 12:01:25 +0200

Committer: Miika Komu <miika@xxxxxx>
Date: 18/03/2010 at 12:01:25
Revision: 3999
Revision-id: miika@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Branch nick: trunk

Log:
  Doxygen for oppdb.c

Modified:
  D  hipd/oppdb.c.doxyme
  M  hipd/oppdb.c

=== modified file 'hipd/oppdb.c'
--- hipd/oppdb.c        2010-03-17 18:46:11 +0000
+++ hipd/oppdb.c        2010-03-18 10:01:23 +0000
@@ -1,10 +1,40 @@
-/*
- * hipd oppdb.c
- *
- * Licence: GNU/GPL
+/**
+ * @file
+ *
+ * Distributed under <a href="http://www.gnu.org/licenses/gpl2.txt";>GNU/GPL</a>
+ *
+ * Opportunistic mode databases for lib/opphip and HIP registration. The 
system-based
+ * opportunistic mode in the firewall uses also this functionality to trigger 
an
+ * opportunistic base base exchange. See the following publication on the 
details:
+ *
+ * <a href="http://www.iki.fi/miika/docs/ccnc09.pdf";>
+ * Miika Komu and Janne Lindqvist, Leap-of-Faith Security is Enough
+ * for IP Mobility, 6th Annual IEEE Consumer
+ * Communications & Networking Conference IEEE CCNC 2009, Las Vegas,
+ * Nevada, January 2009</a>
+ *
+ * The pseudo HIT is mentioned on multiple places in this file. When hipd sends
+ * the opportunistic I1, the destination HIT is NULL. For this reason, we don't
+ * know the Responder HIT until receiving the R2. During this unawareness 
period,
+ * we use a "pseudo HIT" to denote the Responder. It is calculated by 
extracting
+ * part of the IP address of the Responder and prefixing it with HIT prefix 
and some
+ * additional zeroes. Once the R1 received, the opportunistic database entry 
can
+ * be removed and the pseudo HIT becomes unnecessary. Consequtive opportunistic
+ * mode connections with the same Responder are cached and the pseudo HIT is 
not needed.
+ *
+ * The opportunistic mode supports also "fallback" which occurs with
+ * peers that do not support HIP. When the peer does not support HIP,
+ * hipd notices it after a certain time out in maintenance.c loop
+ * because there was no R1 response. The handlers in this function
+ * then send a "reject" message to the blocked opportunistic library
+ * process which means that it should proceed without HIP. Consequtive
+ * rejects are faster because they are cached.
+ *
+ * See firewall/opptcp.c extension on how the initial timeout can be
+ * reduced to a single round-trip time.
+ *
  * Authors:
  * - Bing Zhou <bingzhou@xxxxxxxxx>
- *
  */
 
 /* required for s6_addr32 */
@@ -50,6 +80,12 @@
                               hip_portpair_t *msg_info);
 static int hip_force_opptcp_fallback(hip_opp_block_t *entry, void *ips);
 
+/**
+ * hashing function for the hashtable implementation
+ *
+ * @param a pointer to a hip_opp_block_t structure
+ * @return the calculated hash
+ */
 static unsigned long hip_oppdb_hash_hit(const void *ptr)
 {
     hip_opp_block_t *entry = (hip_opp_block_t *) ptr;
@@ -62,17 +98,30 @@
     return *((unsigned long *) (void *) hash);
 }
 
+/**
+ * matching function for the hashtable implementation
+ *
+ * @param ptr1 a pointer to a hip_opp_block_t structure
+ * @param ptr2 a pointer to a hip_opp_block_t structure
+ * @return zero on match or non-zero otherwise
+ */
 static int hip_oppdb_match_hit(const void *ptr1, const void *ptr2)
 {
     return hip_hash_hit(ptr1) != hip_hash_hit(ptr2);
 }
 
+/**
+ * expire an opportunistic connection
+ *
+ * @param opp_entry the entry to be expired
+ * @return zero on success or negative on error
+ */
 int hip_oppdb_entry_clean_up(hip_opp_block_t *opp_entry)
 {
     int err = 0;
 
-    /* XX FIXME: this does not support multiple multiple opp
-     * connections: a better solution might be trash collection  */
+    /** @todo this does not support multiple multiple opp
+        connections: a better solution might be trash collection  */
 
     HIP_ASSERT(opp_entry);
     err = hip_del_peer_info(&opp_entry->peer_phit,
@@ -82,6 +131,13 @@
     return err;
 }
 
+/**
+ * a for-each iterator function for the opportunistic database
+ *
+ * @param func a callback iterator function
+ * @param opaque an extra parameter to be passed to the callback
+ * @return zero on success and non-zero on error
+ */
 int hip_for_each_opp(int (*func)(hip_opp_block_t *entry, void *opaq), void 
*opaque)
 {
     int i = 0, fail = 0;
@@ -109,7 +165,11 @@
     return fail;
 }
 
-//void hip_hadb_delete_hs(struct hip_hit_spi *hs)
+/**
+ * delete an opportunistic database entry
+ *
+ * @param entry the entry to be deleted
+ */
 static void hip_oppdb_del_entry_by_entry(hip_opp_block_t *entry)
 {
     hip_opp_block_t *deleted;
@@ -122,12 +182,22 @@
     //HIP_FREE(entry);
 }
 
+/**
+ * an iterator function for uninitializing the opportunistic database
+ *
+ * @param entry the entry to be uninitialized
+ * @param unused unused
+ * @return zero
+ */
 static int hip_oppdb_uninit_wrap(hip_opp_block_t *entry, void *unused)
 {
     hip_oppdb_del_entry_by_entry(entry);
     return 0;
 }
 
+/**
+ * uninitialize the whole opportunistic database
+ */
 void hip_oppdb_uninit(void)
 {
     hip_for_each_opp(hip_oppdb_uninit_wrap, NULL);
@@ -135,6 +205,15 @@
     oppdb = NULL;
 }
 
+/**
+ * Unblock a caller from the opportunistic library
+ *
+ * @param app_id the UDP port of the local library process
+ * @param opp_info information related to the opportunistic connection
+ * @param reject Zero if Responder supports HIP or one if Responder
+ *               did not respond within a certain timeout (should fallback to 
TCP/IP).
+ * @return zero on success or negative on failure
+ */
 static int hip_opp_unblock_app(const struct sockaddr_in6 *app_id, 
hip_opp_info_t *opp_info,
                                int reject)
 {
@@ -214,6 +293,13 @@
     return err;
 }
 
+/**
+ * unblock all opportunistic connections with a certain remote host
+ *
+ * @param entry the opportunistic mode connection
+ * @param ptr the pseudo HIT denoting the remote host
+ * @return zero on success or negative on error
+ */
 static int hip_oppdb_unblock_group(hip_opp_block_t *entry, void *ptr)
 {
     hip_opp_info_t *opp_info = (hip_opp_info_t *) ptr;
@@ -232,6 +318,11 @@
     return err;
 }
 
+/**
+ * create a opportunistic mode database entry
+ *
+ * @return the created databased entry (caller deallocates)
+ */
 static hip_opp_block_t *hip_create_opp_block_entry(void)
 {
     hip_opp_block_t *entry = NULL;
@@ -244,17 +335,23 @@
 
     memset(entry, 0, sizeof(*entry));
 
-//INIT_LIST_HEAD(&entry->next_entry);
-
     HIP_LOCK_OPP_INIT(entry);
-    //atomic_set(&entry->refcnt,0);
     time(&entry->creation_time);
     HIP_UNLOCK_OPP_INIT(entry);
 
     return entry;
 }
 
-//int hip_hadb_add_peer_info(hip_hit_t *peer_hit, struct in6_addr *peer_addr)
+/**
+ * add an opportunistic mode connection entry to the database
+ *
+ * @param phit_peer the pseudo HIT of peer
+ * @param hit_our local HIT
+ * @param ip_peer remote IP address
+ * @param ip_our local IP address
+ * @param caller the UDP port of the local library process
+ * @return zero on success or negative on failure
+ */
 static int hip_oppdb_add_entry(const hip_hit_t *phit_peer,
                                const hip_hit_t *hit_our,
                                const struct in6_addr *ip_peer,
@@ -289,11 +386,17 @@
     return err;
 }
 
+/**
+ * initialize the opportunistic database
+ */
 void hip_init_opp_db(void)
 {
     oppdb = hip_ht_init(hip_oppdb_hash_hit, hip_oppdb_match_hit);
 }
 
+/**
+ * dump the contents of the database
+ */
 static void hip_oppdb_dump(void)
 {
     int i;
@@ -318,6 +421,14 @@
     HIP_DEBUG("end oppdb dump\n");
 }
 
+/**
+ * fetch an hadb entry corresponding to a pseudo HIT
+ *
+ * @param init_hit the local HIT of the Initiator
+ * @param resp_addr the remote IP address of the Responder from
+ *                  which to calculate the pseudo HIT
+ * @return a host assocition or NULL if not found
+ */
 hip_ha_t *hip_oppdb_get_hadb_entry(hip_hit_t *init_hit,
                                    struct in6_addr *resp_addr)
 {
@@ -338,6 +449,15 @@
     return entry_tmp;
 }
 
+/**
+ * find a host association based on I1 or R1 message
+ *
+ * @param msg the I1 or R2 message
+ * @param src_addr the source address of the message
+ * @param dst_addr the destination address of the message
+ * @param msg_info the transport layer port numbers (UDP tunnel)
+ * @return the host association or NULL if not found
+ */
 hip_ha_t *hip_oppdb_get_hadb_entry_i1_r1(struct hip_common *msg,
                                          struct in6_addr *src_addr,
                                          struct in6_addr *dst_addr,
@@ -362,6 +482,16 @@
     return entry;
 }
 
+/**
+ * process an incoming R1 packet
+ *
+ * @param msg the R1 packet
+ * @param src_addr the source address of the message
+ * @param dst_addr the destination address of the message
+ * @param opp_entry the opportunistic database entry
+ * @param msg_info the transport layer port numbers (UDP tunnel)
+ * @return zero on success or negative on failure
+ */
 static int hip_receive_opp_r1(struct hip_common *msg,
                               struct in6_addr *src_addr,
                               struct in6_addr *dst_addr,
@@ -442,6 +572,15 @@
     return err;
 }
 
+/**
+ * add an entry to the opportunistic mode dabase and host association
+ * database (with pseudo HIT)
+ *
+ * @param dst_ip the remote IP address of the Responder
+ * @param hit_our the local HIT of the Initiator
+ * @param caller the UDP port of the local library process
+ * @return the created host association
+ */
 hip_ha_t *hip_opp_add_map(const struct in6_addr *dst_ip,
                           const struct in6_addr *hit_our,
                           const struct sockaddr_in6 *caller)
@@ -498,7 +637,13 @@
 }
 
 /**
- * No description.
+ * Trigger opportunistic I1 to obtain the HIT of the Responder.
+ * The TCP optimization may also be used if it is requested.
+ *
+ * @param msg contains information on the Responder's IP address
+ *            and on the use of the TCP optimization
+ * @param src the UDP port number of the calling library process
+ * @return zero on success or negative on failure
  */
 int hip_opp_get_peer_hit(struct hip_common *msg,
                          const struct sockaddr_in6 *src)
@@ -737,10 +882,14 @@
     return err;
 }
 
-/*
+/**
  * Used by opportunistic tcp option to force an application fallback
  * immediately (without timeout) to non-hip communications. This occurs
  * when the firewall detects that peer does not support HIP.
+ *
+ * @param entry the opportunistic mode connection entry
+ * @param data in6_addr the IP address of the Responder
+ * @return zero on success or negative on failure
  */
 static int hip_force_opptcp_fallback(hip_opp_block_t *entry, void *data)
 {
@@ -766,6 +915,14 @@
     return err;
 }
 
+/**
+ * check if it is time for an opportunistic connection to
+ * time out and make it happen when needed
+ *
+ * @param entry the database entry for the opportunistic connection
+ * @param current_time the current time
+ * @return zero on success or negative on failure
+ */
 int hip_handle_opp_fallback(hip_opp_block_t *entry,
                             void *current_time)
 {
@@ -804,6 +961,13 @@
     return err;
 }
 
+/**
+ * reject an opportunistic mode connection
+ *
+ * @param entry the connection to reject
+ * @param data the remote IP address of the Responder
+ * @return zero on success or negative on failure
+ */
 int hip_handle_opp_reject(hip_opp_block_t *entry, void *data)
 {
     int err                  = 0;
@@ -825,13 +989,12 @@
 }
 
 /**
- * hip_oppdb_find_byip:
- * Seeks an ip within the oppdb hash table.
- * If the ip is found in the table, that host is not HIP capable.
+ * check if a remote host is not capable of HIP
  *
  * @param ip_peer: pointer to the ip of the host to check whether
- *                 it is HIP capable
- * @return pointer to the entry if the ip is found in the table; NULL otherwise
+ *                 it is HIP capable or not
+ * @return pointer to the entry if the remote host does not definitely support 
HIP or
+ *         NULL if it is potentially HIP capable
  */
 hip_opp_block_t *hip_oppdb_find_by_ip(const struct in6_addr *ip_peer)
 {

Other related posts:

  • » [hipl-commit] [trunk] Rev 3999: Doxygen for oppdb.c - Miika Komu