- comments and cleanups

Source/charon/threads/kernel_interface.h

@@ -33,6 +33,10 @@ typedef struct kernel_interface_t kernel_interface_t;
 /**
  * @brief Interface to the kernel.
  * 
+ * The kernel interface handles the communication with the kernel
+ * for SA and policy management. It allows setup of these, and provides 
+ * further the handling of kernel events.
+ * 
  * @b Constructors:
  *  - kernel_interface_create()
  * 
@@ -41,22 +45,47 @@ typedef struct kernel_interface_t kernel_interface_t;
 struct kernel_interface_t {
 
 	/**
-	 * @brief Get a SPI from the kernel
+	 * @brief Get a SPI from the kernel.
 	 * 
-	 * @todo Fix spi range
+	 * @param this		calling object
+	 * @param src		source address of SA
+	 * @param dst		destination address of SA
+	 * @param protocol	protocol for SA (ESP/AH)
+	 * @param reqid		unique ID for this SA
+	 * @param[out] spi	allocated spi
+	 * @return
+	 * 					- SUCCESS
+	 * 					- FAILED if kernel comm failed
 	 */
 	status_t (*get_spi) (kernel_interface_t *this, 
-				host_t *src, host_t *dest, 
+				host_t *src, host_t *dst, 
 				protocol_id_t protocol, 
 				u_int32_t reqid,
 				u_int32_t *spi);
 	
 	/**
-	 * @brief Create an SA.
+	 * @brief Add an SA to the SAD.
 	 * 
-	 * @todo Fix reqid and replay_window params
+	 * add_sa() may update an already allocated
+	 * SPI (via get_spi). In this case, the replace
+	 * flag must be set. 
+	 * This function does install a single SA for a
+	 * single protocol in one direction.
 	 * 
-	 * @todo Cleanup method params
+	 * @param this		calling object
+	 * @param src		source address for this SA
+	 * @param dst		destination address for this SA
+	 * @param spi		SPI allocated by us or remote peer
+	 * @param protocol	protocol for this SA (ESP/AH)
+	 * @param reqid		unique ID for this SA
+	 * @param enc_alg	Algorithm to use for encryption (ESP only)
+	 * @param enc_key	Key to use for encryption
+	 * @param int_alg	Algorithm to use for integrity protection
+	 * @param int_key	Key for integrity protection
+	 * @param replace	Should an already installed SA be updated?
+	 * @return
+	 * 					- SUCCESS
+	 * 					- FAILED if kernel comm failed
 	 */
 	status_t (*add_sa)(kernel_interface_t *this,
 				host_t *src, host_t *dst,
@@ -64,16 +93,50 @@ struct kernel_interface_t {
 				protocol_id_t protocol,
 				u_int32_t reqid,
 				encryption_algorithm_t enc_alg,
-				chunk_t encryption_key,
+				chunk_t enc_key,
 				integrity_algorithm_t int_alg,
-				chunk_t integrity_key,
+				chunk_t int_key,
 				bool replace);
-	
+	/**
+	 * @brief Delete a previusly installed SA from the SAD.
+	 * 
+	 * @param this		calling object
+	 * @param dst		destination address for this SA
+	 * @param spi		SPI allocated by us or remote peer
+	 * @param protocol	protocol for this SA (ESP/AH)
+	 * @return
+	 * 					- SUCCESS
+	 * 					- FAILED if kernel comm failed
+	 */
 	status_t (*del_sa) (kernel_interface_t *this,
 				host_t *dst,
 				u_int32_t spi,
 				protocol_id_t protocol);
 	
+	/**
+	 * @brief Add a policy to the SPD.
+	 * 
+	 * A policy is always associated to an SA, so
+	 * traffic applied to a policy. Traffic which
+	 * matches a policy is handled by the SA with the same
+	 * reqid.
+	 * 
+	 * @param this			calling object
+	 * @param me			address of local peer
+	 * @param other			address of remote peer
+	 * @param src			src address of traffic this policy applies
+	 * @param dst			dest address of traffic this policy applies
+	 * @param src_hostbits	subnetmask to use for src address
+	 * @param dst_hostbits	subnetmask to use for dst address
+	 * @param direction		direction of traffic, XFRM_POLICY_OUT, XFRM_POLICY_IN, XFRM_POLICY_FWD
+	 * @param upper_proto	upper layer protocol of traffic for this policy (TCP, UDP, ICMP, ...)
+	 * @param ah			protect traffic with AH?
+	 * @param esp			protect traffic with ESP?
+	 * @param reqid			uniqe ID of an SA to use to enforce policy
+	 * @return
+	 * 						- SUCCESS
+	 * 						- FAILED if kernel comm failed
+	 */
 	status_t (*add_policy) (kernel_interface_t *this, 
 				host_t *me, host_t *other, 
 				host_t *src, host_t *dst,
@@ -82,6 +145,22 @@ struct kernel_interface_t {
 				bool ah, bool esp,
 				u_int32_t reqid);
 	
+	/**
+	 * @brief Remove a policy from the SPD.
+	 * 
+	 * @param this			calling object
+	 * @param me			address of local peer
+	 * @param other			address of remote peer
+	 * @param src			src address of traffic this policy applies
+	 * @param dst			dest address of traffic this policy applies
+	 * @param src_hostbits	subnetmask to use for src address
+	 * @param dst_hostbits	subnetmask to use for dst address
+	 * @param direction		direction of traffic, XFRM_POLICY_OUT, XFRM_POLICY_IN, XFRM_POLICY_FWD
+	 * @param upper_proto	upper layer protocol of traffic for this policy (TCP, UDP, ICMP, ...)
+	 * @return
+	 * 						- SUCCESS
+	 * 						- FAILED if kernel comm failed
+	 */
 	status_t (*del_policy) (kernel_interface_t *this, 
 				host_t *me, host_t *other,
 				host_t *src, host_t *dst,