- code cleaned up

Source/charon/transforms/diffie_hellman.c

@@ -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.
  */

Source/charon/transforms/diffie_hellman.h

@@ -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

Source/charon/transforms/hmac.c

@@ -28,30 +28,33 @@
 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;
 };

Source/charon/transforms/hmac.h

@@ -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 http://www.faqs.org/rfcs/rfc2104.html for RFC.
- * @see hasher_t, prf_hmac_t
+ * @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
+ * Creates a hasher_t object internally.
- * create a hasher_t internally.
  * 
  * @param hash_algorithm		hash algorithm to use
  * @return
- *								- hmac_t if successfully
+ *								- hmac_t object
- *								- NULL if hash not supported
+ *								- NULL if hash algorithm is not supported
  * 
  * @ingroup transforms
  */
 hmac_t *hmac_create(hash_algorithm_t hash_algorithm);
 
-
 #endif /*HMAC_H_*/

Source/charon/transforms/prf_plus.c

@@ -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)
 {

Source/charon/transforms/prf_plus.h

@@ -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
  */