[hipl-commit] [trunk] Rev 3795: Doxygen for lib/core/getendpointinfo.c

  • From: Miika Komu <miika@xxxxxx>
  • To: hipl-commit@xxxxxxxxxxxxx
  • Date: Thu, 4 Mar 2010 13:12:31 +0200

Committer: Miika Komu <miika@xxxxxx>
Date: Thu Mar 04 13:12:58 2010 +0200
Revision: 3795
Revision-id: miika@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Branch nick: trunk

Log:
  Doxygen for lib/core/getendpointinfo.c

Modified:
  D  lib/core/getendpointinfo.c.doxyme
  M  lib/core/getendpointinfo.c

=== modified file 'lib/core/getendpointinfo.c'
--- lib/core/getendpointinfo.c  2010-02-17 17:38:08 +0000
+++ lib/core/getendpointinfo.c  2010-03-04 11:12:58 +0000
@@ -1,17 +1,34 @@
-/*
- * getendpointinfo: native HIP API resolver
- *
- * Authors:
- * - Miika Komu <miika@xxxxxx>
- * - Anthony D. Joseph <adj@xxxxxxx>
- * Copyright: The Inner Net License v2.00.
- * Notes:     This file uses the code in this directory from Craig Metz.
- *
- * Todo:
- * - there is a lot of redundant code in this file to scan hosts files;
- *   reimplement with for_each() and function pointers
- * Bugs:
- * - xx
+/** @file
+ *
+ * Distributed under <a href="http://www.gnu.org/licenses/gpl2.txt";>GNU/GPL</a>
+ *
+ * This file contains functionality to support a subset of <a
+ * href="http://tools.ietf.org/html/draft-ietf-hip-native-api";> Native
+ * HIP API</a> resolver functionality. The implemented functionality
+ * may be not be completely up-to-date with the specification.
+ *
+ * Functionality beyond the native HIP API is also implemented here,
+ * such as application-specific host identities as described in <a
+ * href="http://www.niksula.cs.hut.fi/~mkomu/docs/f17-komu.pdf";>M. Komu,
+ * S. Tarkoma, J. Kangasharju, A. Gurtov, Applying a Cryptographic
+ * Namespace to Applications, in Proc. of First International ACM
+ * Workshop on Dynamic Interconnection of Networks, September
+ * 2005. </a>.
+ *
+ * You can find test software for the native API in test directory
+ * (all of them have the word "native" in their file name). The use of
+ * the native API requires a small patch to the kernel (from the
+ * patches directory) and a kernel module to be loaded from the
+ * hipsock directory.
+ *
+ * It should be noted that this file can be erased completely if
+ * the support for native HIP API will be ceased.
+ *
+ * @author Miika Komu <miika@xxxxxx>
+ * @author Anthony D. Joseph <adj@xxxxxxx>
+ *
+ * @brief <a href="http://tools.ietf.org/html/draft-ietf-hip-native-api";>
+ *        Native HIP API</a> functionality
  */
 
 /* required for s6_addr32 */
@@ -49,13 +66,19 @@
 #include "debug.h"
 #include "getendpointinfo.h"
 
-//#include <ifaddrs.h>
-
-// needed due to missing system inlcude for openWRT
+/* to compensate for a missing system include in OpenWRT */
 #ifndef HOST_NAME_MAX
 #define HOST_NAME_MAX           64
 #endif
 
+/**
+ * convert a service number (e.g. "http") or port string (e.g. "80") to
+ * a numeric port number
+ *
+ * @param servname the service or port number as a string
+ * @param port the converted numeric port (output argument)
+ * @return zero on success or negative on failure
+ */
 int convert_port_string_to_number(const char *servname, in_port_t *port)
 {
     int err = 0;
@@ -84,6 +107,17 @@
     return err;
 }
 
+/**
+ * Set local endpoint identifier (EID), i.e., exchange a public key (or HIT)
+ * to an EID from the hipsock kernel module
+ *
+ * @param my_eid the EID that the hipsock should assign
+ * @param servname a symbolic service name or port number
+ * @param endpoint a HIT or HI to exchange with hipsock
+ * @param ifaces currently unused
+ * @return zero on success and negative on failure
+ * @todo the EID concept is deprecated
+ */
 int setmyeid(struct sockaddr_eid *my_eid,
              const char *servname,
              const struct endpoint *endpoint,
@@ -235,6 +269,17 @@
     return err;
 }
 
+/**
+ * Set a remote endpoint identifier (EID), i.e., exchange a remote
+ * HIT (or HI) to a EID with hipd
+ *
+ * @param peer_eid the peer EID that the hipsock should assign
+ * @param servname a symbolic service name or port number
+ * @param endpoint the HIT (or HI)
+ * @param addrinfo peer address information from the resolver
+ * @return zero on success and negative on failure
+ * @todo the EID concept is deprecated
+ */
 int setpeereid(struct sockaddr_eid *peer_eid,
                const char *servname,
                const struct endpoint *endpoint,
@@ -393,11 +438,16 @@
     return err;
 }
 
-/*
- * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
- * XX FIXME: grep for public / private word from the filename and
+/**
+ * Load a Host Identity from a file. Used for application-specific
+ * identities in test/conntest-client-native-user-key.c
+ *
+ * @param filename a file name where to load the keys
+ * @param endpoint the corresponding endpoint will be stored here
+ * @return zero on success and negative on failure
+ * @todo grep for public / private word from the filename and
  * call either load_private or load_public correspondingly.
- * Are application specified identities always anonymous?
+ * @todo Are application specified identities always anonymous?
  */
 int load_hip_endpoint_pem(const char *filename,
                           struct endpoint **endpoint)
@@ -474,6 +524,12 @@
     return err;
 }
 
+/**
+ * Deallocated memory for an addrinfo structure
+ *
+ * @param res the addrinfo structure to deallocated
+ * @note this is completely redundant with freeaddrinfo()
+ */
 void free_endpointinfo(struct addrinfo *res)
 {
     struct addrinfo *tmp;
@@ -502,7 +558,8 @@
 }
 
 /**
- * get_localhost_endpointinfo - query endpoint info about the localhost
+ * query endpoint info about the localhost
+ *
  * @param basename the basename for the hip/hosts file (included for easier 
writing
  *            of unit tests)
  * @param servname the service port name (e.g. "http" or "12345")
@@ -519,7 +576,7 @@
  * identities are needed, one needs to call this function multiple times
  * with different basename arguments and link the results together.
  *
- * XX FIX: LOCAL RESOLVER SHOULD RESOLVE PUBLIC KEYS, NOT
+ * @todo LOCAL RESOLVER SHOULD RESOLVE PUBLIC KEYS, NOT
  * PRIVATE. CHECK THAT IT WORKS WITH THE USER-KEY TEST PROGRAM.
  *
  * @return zero on success, or negative error value on failure
@@ -708,7 +765,8 @@
 }
 
 /**
- * get_hipd_peer_list - query hipd for list of known peers
+ * query hipd for list of known peers
+ *
  * @param nodename the name of the peer to be resolved
  * @param servname the service port name (e.g. "http" or "12345")
  * @param hints selects which type of endpoints is going to be resolved
@@ -716,11 +774,9 @@
  * @param alt_flag flag for an alternate query (after a file query has been 
done)
  *             This flag will add entries (if found) to an existing result
  *
- * This function is for libinet6 internal purposes only.
- *
  * @return zero on success, or negative error value on failure
- * @todo: this function is outdated; query for SO_HIP_GET_HA_INFO instead
- *
+ * @todo this function is outdated; query for SO_HIP_GET_HA_INFO instead
+ * @note This function is for libinet6 internal purposes only.
  */
 int get_hipd_peer_list(const char *nodename,
                        const char *servname,
@@ -1036,17 +1092,16 @@
 }
 
 /**
- * get_peer_endpointinfo - query endpoint info about a peer
+ * query endpoint info about a peer
+ *
  * @param hostsfile the filename where the endpoint information is stored
  * @param nodename the name of the peer to be resolved
  * @param servname the service port name (e.g. "http" or "12345")
  * @param hints selects which type of endpoints is going to be resolved
  * @param res the result of the query
  *
- * This function is for libinet6 internal purposes only.
- *
  * @return zero on success, or negative error value on failure
- *
+ * @note This function is for libinet6 internal purposes only.
  */
 int get_peer_endpointinfo(const char *hostsfile,
                           const char *nodename,
@@ -1249,9 +1304,12 @@
     return err;
 }
 
-/*
- * Finds HIP key files from the directory specified by 'path'.
- * Stores the file names into linked list (type listelement).
+/**
+ * Find HIP key files from the directory specified by 'path'.
+ * Store the file names into linked list (type listelement).
+ *
+ * @param path a directory from where to store key files
+ * @param files a list of discovered HIP-related file names
  */
 void findkeyfiles(char *path, List *files)
 {
@@ -1269,17 +1327,16 @@
     }
     ;
 
-    //Loop through all files and directories
+    /* Loop through all files and directories */
     while ((entry = readdir(dir)) != NULL) {
         if ((strcmp(entry->d_name, ".") != 0) &&
             (strcmp(entry->d_name, "..") != 0)) {
-            //Get the status info for the current file
+            /* Get the status info for the current file */
             if (stat(entry->d_name, &file_status) == 0) {
-                //Is this a directory, or a file?
-                //Go through all public key files
+                /* Is this a directory, or a file? */
+                /* Go through all public key files */
                 if (!S_ISDIR(file_status.st_mode) &&
                     findsubstring(entry->d_name, ".pub") &&
-                    //!findsubstring(entry->d_name, ".pub") && original
                     findsubstring(entry->d_name, "hip_host_")) {
                     _HIP_DEBUG("findkeyfiles: Public key file: %s \n",
                                entry->d_name);
@@ -1295,6 +1352,18 @@
     }
 }
 
+/**
+ * Query local or peer endpoint identifiers (EIDs). The interface
+ * is very similar to getaddrinfo()
+ *
+ * @param nodename the remote node name to query or NULL if you want to
+ *                 query local host identifiers
+ * @param servname an optional symbolic service name
+ * @param hints the resolver hints
+ * @param res the result of the query is allocated and stored here (caller 
deallocates)
+ * @return zero on success, or negative error value on failure
+ * @todo the EID concept is deprecated
+ */
 int getendpointinfo(const char *nodename, const char *servname,
                     const struct addrinfo *hints,
                     struct addrinfo **res)
@@ -1433,11 +1502,30 @@
     return err;
 }
 
+/**
+ * convert getendpointinfo error codes to human-readable strings
+ *
+ * @param errcode the error code to convert
+ * @return a symbolic presentation of the error code
+ */
 const char *gepi_strerror(int errcode)
 {
     return "HIP native resolver failed"; /* XX FIXME */
 }
 
+/**
+ * convert a local host id in a file to addrinfo structure (no EIDs)
+ *
+ * @param basename the basename for the RSA encoded public key file
+ * @param servname the service port name (e.g. "http" or "12345")
+ * @param hints selects which type of endpoints is going to be resolved
+ * @param res the result of the query
+ * @param lhi the corresponding LSI
+ *
+ * @return zero on success, or negative error value on failure
+ *
+ * @todo this function contains redundant code with get_localhost_endpoint()
+ */
 int get_localhost_endpoint_no_setmyeid(const char *basename,
                                        const char *servname,
                                        struct addrinfo *hints,
@@ -1492,11 +1580,8 @@
     }
 
     if (algo == HIP_HI_RSA) {
-        //modified according Laura's suggestion
-        //    err = load_rsa_private_key(basename, &rsa);
         err = load_rsa_public_key(basename, &rsa);
     } else {
-        //err = load_dsa_private_key(basename, &dsa);
         err = load_dsa_public_key(basename, &dsa);
     }
     if (err) {
@@ -1528,7 +1613,6 @@
             err = -EFAULT;
             goto out_err;
         }
-        //    err = hip_private_rsa_to_hit(rsa, key_rr, HIP_HIT_TYPE_HASH120, 
&lhi->hit);
         err = hip_public_rsa_to_hit(rsa, key_rr, HIP_HIT_TYPE_HASH100, 
&lhi->hit);
         if (err) {
             HIP_ERROR("Conversion from RSA to HIT failed\n");
@@ -1543,7 +1627,6 @@
             err = -EFAULT;
             goto out_err;
         }
-        //err = hip_private_dsa_to_hit(dsa, key_rr, HIP_HIT_TYPE_HASH120, 
&lhi->hit);
         err = hip_public_dsa_to_hit(dsa, key_rr, HIP_HIT_TYPE_HASH100, 
&lhi->hit);
         if (err) {
             HIP_ERROR("Conversion from DSA to HIT failed\n");
@@ -1602,6 +1685,19 @@
     return err;
 }
 
+/**
+ * convert a local host id in a file to addrinfo structure with EID structures
+ *
+ * @param basename the basename for the RSA encoded public key file
+ * @param servname the service port name (e.g. "http" or "12345")
+ * @param hints selects which type of endpoints is going to be resolved
+ * @param res the result of the query
+ * @param lhi the corresponding LSI
+ *
+ * @return zero on success, or negative error value on failure
+ *
+ * @todo this function contains redundant code with get_localhost_endpoint()
+ */
 int get_localhost_endpoint(const char *basename,
                            const char *servname,
                            struct addrinfo *hints,
@@ -1775,7 +1871,7 @@
 }
 
 /**
- * get_local_hits - Query about local HITs and add the corresponding HIs into
+ * Query about local HITs and add the corresponding HIs into
  * kernel database. This function is used by getaddrinfo() in getaddrinfo.c
  *
  * @param servname the service port name (e.g. "http" or "12345")
@@ -1858,6 +1954,18 @@
     return err;
 }
 
+/**
+ * dig up peer HIT from hosts files
+ *
+ * @param hostsfile the HIP hosts file
+ * @param nodename the node to search for
+ * @param servname symbolic service string to prefill in the result
+ * @param hints hints for filtering the results
+ * @param res The result of the query formatted as a addrinfo structure.
+ *            This function allocated and the caller is responsible of
+ *            deallocation.
+ * @return zero on success, or negative error value on failure
+ */
 int get_peer_addrinfo_hit(const char *hostsfile,
                           const char *nodename,
                           const char *servname,
@@ -1929,8 +2037,18 @@
     return err;
 }
 
-/* getendpointfo() modified for sockaddr_hip instead of sockaddr_eid */
-
+/**
+ * map a node name to a HIT from hosts files
+ *
+ * @param hostsfile the HIP hosts file
+ * @param nodename the node to search for
+ * @param servname symbolic service string to prefill in the result
+ * @param hints hints for filtering the results
+ * @param res The result of the query formatted as a addrinfo structure.
+ *            This function allocated and the caller is responsible of
+ *            deallocation.
+ * @return zero on success, or negative error value on failure
+ */
 int get_hit_addrinfo(const char *nodename, const char *servname,
                      const struct addrinfo *hints,
                      struct addrinfo **res)
@@ -2005,6 +2123,15 @@
     return err;
 }
 
+/**
+ * map a file containing a PEM encoded public key into a addrinfo structure
+ *
+ * @param basename the file where the PEM encoded public key is located
+ * @param servname the service port name (e.g. "http" or "12345")
+ * @param hints selects which type of endpoints is going to be resolved
+ * @param res the result of the query
+ * @return zero on success, or negative error value on failure
+ */
 int get_addrinfo_from_key(const char *basename,
                           const char *servname,
                           struct addrinfo *hints,
@@ -2132,6 +2259,13 @@
     return err;
 }
 
+/**
+ * load a public key from a file and map it into a sockaddr_hip structure
+ *
+ * @param filename the file where the PEM formatted public key is located
+ * @param hit the sockaddr_hip structure
+ * @return zero on success, or negative error value on failure
+ */
 int get_sockaddr_hip_from_key(const char *filename, struct sockaddr_hip **hit)
 {
     int err              = 0;

Other related posts: