[hipl-commit] [trunk] Rev 3954: Doxygen for blind.c

  • From: Miika Komu <miika@xxxxxx>
  • To: hipl-commit@xxxxxxxxxxxxx
  • Date: Tue, 16 Mar 2010 15:38:04 +0200

Committer: Miika Komu <miika@xxxxxx>
Date: 16/03/2010 at 15:38:04
Revision: 3954
Revision-id: miika@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Branch nick: trunk

Log:
  Doxygen for blind.c

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

=== modified file 'hipd/blind.c'
--- hipd/blind.c        2010-03-08 22:07:59 +0000
+++ hipd/blind.c        2010-03-16 13:38:03 +0000
@@ -1,8 +1,10 @@
 /** @file
  * This file defines tools of  blind extension for the Host Identity Protocol
+ * See <a 
href="http://lib.tkk.fi/Diss/2008/isbn9789512295319/article6.pdf";>Ylitalo et 
al, BLIND: a Complete Identity Protection Framework for End-hosts, April 
2004</a> and the corresponding IETF draft <a 
href="http://tools.ietf.org/html/draft-zhang-hip-privacy-protection";>Zhang et 
al,
+An Extension of HIP Base Exchange to Support Identity Privacy, IETF draft, 
Work in Progress, March 2010</a>.
  *
  * @author  Laura Takkinen
- * @note    Distributed under <a 
href="http://www.gnu.org/licenses/gpl2.txt";>GNU/GPL</a>.
+ * @note Distributed under <a 
href="http://www.gnu.org/licenses/gpl2.txt";>GNU/GPL</a>.
  */
 
 /* required for s6_addr32 */
@@ -13,6 +15,15 @@
 
 static int hip_blind_fingerprints(hip_ha_t *entry);
 
+/**
+ * test whether we should use blind or not based on an inbound packet
+ *
+ * @param msg a HIP control message
+ * @param entry related host association
+ * @param use_blind An output argument where the result will be written
+ *                  One if blind should be used or zero otherwise.
+ * @return zero on success or negative on error
+o */
 int hip_check_whether_to_use_blind(hip_common_t *msg, hip_ha_t *entry,  int 
*use_blind)
 {
     /* Check for error conditions. */
@@ -48,7 +59,13 @@
     }
 }
 
-/* For internal use only */
+/**
+ * enable blind for a given host assocation
+ *
+ * @param entry a host association
+ * @param not_used not used
+ * @return zero
+ */
 static int hip_set_blind_on_sa(hip_ha_t *entry, void *not_used)
 {
     int err = 0;
@@ -60,7 +77,13 @@
     return err;
 }
 
-/* For internal use only */
+/**
+ * disable blind for a given host assocation
+ *
+ * @param entry a host association
+ * @param not_used not used
+ * @return zero
+ */
 static int hip_set_blind_off_sa(hip_ha_t *entry, void *not_used)
 {
     int err = 0;
@@ -72,9 +95,12 @@
     return err;
 }
 
-/* This functions is used to set the blind on.
- * "blind" entry of all existing associations is set to 1
- * and hip_blind_status is set to 1.
+/**
+ * Enable blind globally for all host associations
+ *
+ * @return zero
+ * @note this function has no effect if host association
+ *       is in established state
  */
 int hip_set_blind_on(void)
 {
@@ -88,9 +114,12 @@
     return err;
 }
 
-/* This functions is used to set the blind off.
- * "blind" entry of all existing associations is set to 0
- * and hip_blind_status is set to 0.
+/**
+ * Disable blind globally for all host associations
+ *
+ * @return zero
+ * @note this function has no effect if host association
+ *       is in established state
  */
 int hip_set_blind_off(void)
 {
@@ -105,7 +134,7 @@
 }
 
 /**
- * @brief This functions is used to query if the blind is in use.
+ * This functions is used to query if the blind is in use.
  *
  * @return Zero if blind is off and 1 if blind is on.
  */
@@ -114,10 +143,12 @@
     return hip_blind_status;
 }
 
-/* Extracts the uint16_t type nonce from the message.
- * @msg Message from where the nonce is extracted
- * @msg_nonce The nonce that the message included
- * Returns 0 in success, otherwise returns -1.
+/**
+ * Extract uint16_t type blind nonce from HIP control message
+ *
+ * @param msg message the message from where the nonce is extracted
+ * @param msg_nonce the nonce will be written here
+ * @return zero on success or negative on error
  */
 int hip_blind_get_nonce(struct hip_common *msg, uint16_t *msg_nonce)
 {
@@ -133,12 +164,12 @@
 }
 
 /**
- * @brief Forms a plain HIT from a blinded one.
+ * Forms a plain HIT from a blinded one.
  *
  * @param  nonce     Nonce that is used to calculate the plain HIT.
  * @param  blind_hit Blinded HIT from where the plain HIT is formed.
  * @param  plain_hit Calculated plain HIT
- * @return           Zero in success, otherwise -1.
+ * @return zero on success or negative on error
  */
 int hip_plain_fingerprint(uint16_t *nonce,  struct in6_addr *blind_hit,
                           struct in6_addr *plain_hit)
@@ -153,12 +184,13 @@
     return err;
 }
 
-/* Forms the blinded HIT from the key (SHA1 hash from the key).
- * For internal purposes.
- * @key Key from where the hash is calculated
- * @key_len Length of the key
- * @blind_hit Calculated blind HIT (hash)
- * Returns 0 in success, otherwise returns -1.
+/**
+ * Form the blinded HIT from the key (SHA1 hash from the key).
+ *
+ * @param key Key from where the hash is calculated
+ * @param key_len Length of the key
+ * @param blind_hit Calculated blind HIT (hash)
+ * @return zero on success or negative on error
  */
 int hip_do_blind(char *key, unsigned int key_len, struct in6_addr *blind_hit)
 {
@@ -186,10 +218,11 @@
     return err;
 }
 
-/* Sets nonce and calculates the blinded
- * fingerprints for the hip_ha_t entry.
- * @entry hip_ha_t entry which blind fields are adjusted
- * Returns 0 in success, otherwise returns -1.
+/**
+ * Sets nonce and calculates the blinded fingerprints for the hip_ha_t entry.
+ *
+ * @param entry hip_ha_t entry which blind fields are adjusted
+ * @return zero on success or negative on error
  */
 static int hip_blind_fingerprints(hip_ha_t *entry)
 {
@@ -224,7 +257,15 @@
     return err;
 }
 
-/* Tests if @plain_hit blinded with nonce is same as @blind_hit*/
+/**
+ * Tests if plain_hit blinded with nonce is same as @blind_hit
+ *
+ * @param nonce the nonce used for blinding the hit
+ * @param plain_hit the plain HIT to be tested
+ * @param blind_hit the blinded HIT
+ *
+ * @return zero on success or negative on error
+ */
 int hip_blind_verify(uint16_t *nonce, struct in6_addr *plain_hit,
                      struct in6_addr *blind_hit)
 {
@@ -269,7 +310,12 @@
     }
     return ret == 0;
 }
-
+/**
+ * build a blinded i1 message
+ *
+ * @param entry the related host association
+ * @param mask a mask template for I1 packet without blind
+ */
 struct hip_common *hip_blind_build_i1(hip_ha_t *entry, uint16_t *mask)
 {
     struct hip_common *i1;
@@ -307,7 +353,16 @@
     return i1;
 }
 
-/* Fills the r2 message with required blind parameters*/
+/**
+ * Fill in the r2 message with required blind parameters
+ *
+ * @param i2 the receive I2 message
+ * @param r2 message to be sent
+ * @param entry the related host association
+ * @param the default control flags mask template
+ *
+ * @return zero on success or negative on error
+ */
 int hip_blind_build_r2(struct hip_common *i2, struct hip_common *r2, hip_ha_t 
*entry, uint16_t *mask)
 {
     int err           = 0, host_id_in_enc_len = 0;
@@ -386,6 +441,14 @@
     return err;
 }
 
+/**
+ * verify a blinded R2 message
+ *
+ * @param r2 the R2 control message
+ * @param entry the related host association
+ *
+ * @return zero if the message was ok or negative otherwise
+ */
 int hip_blind_verify_r2(struct hip_common *r2, hip_ha_t *entry)
 {
     int err                            = 0;
@@ -476,7 +539,7 @@
 }
 
 /**
- * Constructs a new R1 packet payload.
+ * Constructs a new blinde R1 packet payload
  *
  * @param src_hit      a pointer to the source host identity tag used in the
  *                     packet.
@@ -660,6 +723,16 @@
     return NULL;
 }
 
+/**
+ * recreate a blind spool of R1 messages
+ *
+ * @param r1table the R1 table to fill
+ * @param hit the local HIT
+ * @param sign the signature function pointer
+ * @param privkey the private key for signing
+ * @param pubkey the corresponding public key
+ * @return zero on success or negative on error
+ */
 int hip_blind_precreate_r1(struct hip_r1entry *r1table, struct in6_addr *hit,
                            int (*sign)(void *key, struct hip_common *m),
                            void *privkey, struct hip_host_id *pubkey)

Other related posts:

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