- code cleaned up
authorJan Hutter <jhutter@hsr.ch>
Tue, 6 Dec 2005 15:10:11 +0000 (15:10 -0000)
committerJan Hutter <jhutter@hsr.ch>
Tue, 6 Dec 2005 15:10:11 +0000 (15:10 -0000)
Source/charon/transforms/diffie_hellman.c
Source/charon/transforms/diffie_hellman.h
Source/charon/transforms/hmac.c
Source/charon/transforms/hmac.h
Source/charon/transforms/prf_plus.c
Source/charon/transforms/prf_plus.h

index 266c4b3..e45b0b3 100644 (file)
@@ -313,12 +313,12 @@ typedef struct modulus_info_entry_t modulus_info_entry_t;
  */
 struct modulus_info_entry_t {
        /**
-        * Group number as it is defined in transform_substructure.h.
+        * Group number as it is defined in file transform_substructure.h.
         */
        diffie_hellman_group_t group;
        
        /**
-        * Pointer to first byte of modulus in (network order).
+        * Pointer to first byte of modulus (network order).
         */
        u_int8_t *modulus;
        
@@ -491,7 +491,6 @@ static void compute_shared_secret (private_diffie_hellman_t *this)
        this->shared_secret_is_computed = TRUE;
 }
 
-
 /**
  * Implementation of private_diffie_hellman_t.compute_public_value.
  */
@@ -549,7 +548,6 @@ static void destroy(private_diffie_hellman_t *this)
        allocator_free(this);
 }
 
-
 /*
  * Described in header.
  */
index f7a3b6a..2c0f948 100644 (file)
@@ -33,7 +33,9 @@ typedef enum diffie_hellman_group_t diffie_hellman_group_t;
  * 
  * The modulus (or group) to use for a Diffie-Hellman calculation.
  * 
- * @see IKEv2 draft 3.3.2 and RFC 3526.
+ * See IKEv2 draft 3.3.2 and RFC 3526.
+ * 
+ * @warning Use of big modulus sizes can be cpu consuming.
  * 
  * @ingroup transforms
  */
@@ -50,7 +52,7 @@ enum diffie_hellman_group_t {
 };
 
 /** 
- * string mappings for diffie_hellman_group_t
+ * String mappings for diffie_hellman_group_t.
  */
 extern mapping_t diffie_hellman_group_m[];
 
@@ -60,6 +62,9 @@ typedef struct diffie_hellman_t diffie_hellman_t;
 /**
  * @brief Implementation of the widely used Diffie-Hellman algorithm.
  * 
+ * @b Constructors:
+ *  - diffie_hellman_create()
+ * 
  * @ingroup transforms
  */
 struct diffie_hellman_t {
@@ -73,7 +78,7 @@ struct diffie_hellman_t {
         * @param this                  calling diffie_hellman_t object
         * @param[out] secret   shared secret will be written into this chunk
         * @return                              
-        *                                              - SUCCESS, or
+        *                                              - SUCCESS
         *                                              - FAILED if not both DH values are set
         */
        status_t (*get_shared_secret) (diffie_hellman_t *this, chunk_t *secret);
@@ -81,7 +86,7 @@ struct diffie_hellman_t {
        /**
         * @brief Sets the public value of partner.
         *      
-        * @warning chunk gets copied
+        * chunk gets cloned and can be destroyed afterwards.
         * 
         * @param this                  calling diffie_hellman_t object
         * @param public_value  public value of partner
@@ -91,12 +96,13 @@ struct diffie_hellman_t {
        /**
         * @brief Gets the public value of partner.
         *      
-        * @warning chunk gets copied
+        * @warning Space for returned chunk is allocated and must be 
+        * freed by the caller.
         * 
         * @param this                          calling diffie_hellman_t object
         * @param[out] public_value public value of partner is stored at this location
         * @return                              
-        *                                                      - SUCCESS, or
+        *                                                      - SUCCESS
         *                                                      - FAILED if other public value not set
         */
        status_t (*get_other_public_value) (diffie_hellman_t *this, chunk_t *public_value);
@@ -104,7 +110,8 @@ struct diffie_hellman_t {
        /**
         * @brief Gets the public value of caller
         *      
-        * @warning chunk gets copied
+        * @warning Space for returned chunk is allocated and must be 
+        * freed by the caller.
         * 
         * @param this                          calling diffie_hellman_t object
         * @param[out]                          public_value public value of caller is stored at this location
index c7847ad..dc31af3 100644 (file)
 typedef struct private_hmac_t private_hmac_t;
 
 /**
- * Private data of an hmac_t object.
+ * Private data of a hmac_t object.
+ * 
+ * The variable names are the same as in the RFC.
  */
 struct private_hmac_t {
        /**
-        * hmac_t interface
+        * Public hmac_t interface.
         */
        hmac_t hmac;
        
        /**
-        * block size, as in RFC
+        * Block size, as in RFC.
         */
        u_int8_t b;
        
        /**
-        * hash function
+        * Hash function.
         */
        hasher_t *h;
        
        /**
-        * previously xor'ed key using opad
+        * Previously xor'ed key using opad.
         */
        chunk_t opaded_key;
+       
        /**
-        * previously xor'ed key using ipad
+        * Previously xor'ed key using ipad.
         */
        chunk_t ipaded_key;
 };
index d415ace..efc96ef 100644 (file)
@@ -35,8 +35,13 @@ typedef struct hmac_t hmac_t;
  * described in RFC2104. It uses a hash function, wich must
  * be implemented as a hasher_t class.
  * 
- * @see http://www.faqs.org/rfcs/rfc2104.html
- * @see hasher_t, prf_hmac_t
+ * See http://www.faqs.org/rfcs/rfc2104.html for RFC.
+ * @see        
+ *                     - hasher_t
+ *                     - prf_hmac_t
+ * 
+ * @b Constructors:
+ *  - hmac_create()
  * 
  * @ingroup transforms
  */
@@ -45,11 +50,11 @@ struct hmac_t {
         * @brief Generate message authentication code.
         * 
         * If buffer is NULL, no result is given back. A next call will
-        * append the data to already supplied. If buffer is not NULL, 
+        * append the data to already supplied data. If buffer is not NULL, 
         * the mac of all apended data is calculated, returned and the
-        * state of the hmac_t reset;
+        * state of the hmac_t is reseted.
         * 
-        * @param this                  calling hmac
+        * @param this                  calling object
         * @param data                  chunk of data to authenticate
         * @param[out] buffer   pointer where the generated bytes will be written
         */
@@ -64,34 +69,34 @@ struct hmac_t {
         * the mac of all apended data is calculated, returned and the
         * state of the hmac_t reset;
         * 
-        * @param this                  calling hmac
+        * @param this                  calling object
         * @param data                  chunk of data to authenticate
         * @param[out] chunk    chunk which will hold generated bytes
         */
        void (*allocate_mac) (hmac_t *this, chunk_t data, chunk_t *chunk);
        
        /**
-        * @brief Get the block size of this hmac.
+        * @brief Get the block size of this hmac_t object.
         * 
-        * @param this                  calling hmac
+        * @param this                  calling object
         * @return                              block size in bytes
         */
        size_t (*get_block_size) (hmac_t *this);        
        
        /**
-        * @brief Set the key for this hmac.
+        * @brief Set the key for this hmac_t object.
         * 
         * Any key length is accepted.
         * 
-        * @param this                  calling hmac
+        * @param this                  calling object
         * @param key                   key to set
         */
        void (*set_key) (hmac_t *this, chunk_t key);
        
        /**
-        * @brief Destroys a hmac object.
+        * @brief Destroys a hmac_t object.
         *
-        * @param this                  hmac_t object to destroy
+        * @param this                  calling object
         */
        void (*destroy) (hmac_t *this);
 };
@@ -99,17 +104,15 @@ struct hmac_t {
 /**
  * @brief Creates a new hmac_t object.
  * 
- * Creates a new hmac_t object using hash_algorithm to
- * create a hasher_t internally.
+ * Creates a hasher_t object internally.
  * 
  * @param hash_algorithm               hash algorithm to use
  * @return
- *                                                             - hmac_t if successfully
- *                                                             - NULL if hash not supported
+ *                                                             - hmac_t object
+ *                                                             - NULL if hash algorithm is not supported
  * 
  * @ingroup transforms
  */
 hmac_t *hmac_create(hash_algorithm_t hash_algorithm);
 
-
 #endif /*HMAC_H_*/
index 553a348..f0f4a11 100644 (file)
@@ -34,39 +34,38 @@ typedef struct private_prf_plus_t private_prf_plus_t;
  */
 struct private_prf_plus_t {
        /**
-        * public prf_plus_t interface
+        * Public interface of prf_plus_t.
         */
        prf_plus_t public;
        
        /**
-        * prf to use
+        * PRF to use.
         */
        prf_t *prf;
        
        /**
-        * initial seed
+        * Initial seed.
         */
        chunk_t seed;
        
        /**
-        * buffer to store current prf result
+        * Buffer to store current PRF result.
         */
        chunk_t buffer;
                
        /**
-        * already given out bytes in current buffer
+        * Already given out bytes in current buffer.
         */
        size_t given_out;
        
        /**
-        * octet which will be appended to the seed
+        * Octet which will be appended to the seed.
         */
        u_int8_t appending_octet;
 };
 
-
 /**
- * implementation of prf_plus_t.get_bytes
+ * Implementation of prf_plus_t.get_bytes.
  */
 static void get_bytes(private_prf_plus_t *this, size_t length, u_int8_t *buffer)
 {      
@@ -99,7 +98,7 @@ static void get_bytes(private_prf_plus_t *this, size_t length, u_int8_t *buffer)
 }
 
 /**
- * implementation of prf_plus_t.allocate_bytes
+ * Implementation of prf_plus_t.allocate_bytes.
  */    
 static void allocate_bytes(private_prf_plus_t *this, size_t length, chunk_t *chunk)
 {
@@ -109,7 +108,7 @@ static void allocate_bytes(private_prf_plus_t *this, size_t length, chunk_t *chu
 }
 
 /**
- * implementation of prf_plus_t.destroy
+ * Implementation of prf_plus_t.destroy.
  */
 static void destroy(private_prf_plus_t *this)
 {
@@ -119,7 +118,7 @@ static void destroy(private_prf_plus_t *this)
 }
 
 /*
- * Description in header
+ * Description in header.
  */
 prf_plus_t *prf_plus_create(prf_t *prf, chunk_t seed)
 {
index 812af05..538724c 100644 (file)
@@ -32,10 +32,13 @@ typedef struct prf_plus_t prf_plus_t;
 /**
  * @brief Implementation of the prf+ function described in IKEv2 draft.
  *
- * This class implements the prf+ algorithm. Internalliy it uses a pseudo random
+ * This class implements the prf+ algorithm. Internally it uses a pseudo random
  * function, which implements the prf_t interface.
- *
- * @see IKEv2 draft 2.13
+ * 
+ * See IKEv2 draft 2.13.
+ * 
+ * @b Constructors:
+ *  - prf_plus_create()
  * 
  * @ingroup transforms
  */
@@ -46,7 +49,7 @@ struct prf_plus_t {
         * Get the next few bytes of the prf+ output. Space
         * must be allocated by the caller.
         * 
-        * @param this                  calling prf_plus
+        * @param this                  calling object
         * @param length                number of bytes to get
         * @param[out] buffer   pointer where the generated bytes will be written
         */
@@ -58,7 +61,7 @@ struct prf_plus_t {
         * Get the next few bytes of the prf+ output. This function
         * will allocate the required space.
         * 
-        * @param this                  calling prf_plus
+        * @param this                  calling object
         * @param length                number of bytes to get
         * @param[out] chunk    chunk which will hold generated bytes
         */
@@ -67,7 +70,7 @@ struct prf_plus_t {
        /**
         * @brief Destroys a prf_plus_t object.
         *
-        * @param this                  prf_plus_t object to destroy
+        * @param this                  calling object
         */
        void (*destroy) (prf_plus_t *this);
 };
@@ -77,11 +80,11 @@ struct prf_plus_t {
  * 
  * Seed will be cloned. prf will
  * not be cloned, must be destroyed outside after
- * prf_plus usage.
+ * prf_plus_t usage.
  * 
  * @param prf                          prf object to use
  * @param seed                         input seed for prf
- * @return                                     created prf_plus_t
+ * @return                                     prf_plus_t object
  * 
  * @ingroup transforms
  */