[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 14:26:37 +0200
Committer: Miika Komu <miika@xxxxxx>
Date: Thu maalis 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:
