improved IKE_SA uniqueness check
[strongswan.git] / src / charon / sa / ike_sa_manager.h
index 8fc243e..b5c479e 100644 (file)
@@ -1,4 +1,5 @@
 /*
+ * Copyright (C) 2008 Tobias Brunner
  * Copyright (C) 2005-2006 Martin Willi
  * Copyright (C) 2005 Jan Hutter
  * Hochschule fuer Technik Rapperswil
@@ -59,7 +60,7 @@ struct ike_sa_manager_t {
         * Create and check out a new IKE_SA.
         * 
         * @param initiator                     TRUE for initiator, FALSE otherwise
-        * @returns                             created andchecked out IKE_SA
+        * @returns                             created and checked out IKE_SA
         */
        ike_sa_t* (*checkout_new) (ike_sa_manager_t* this, bool initiator);
        
@@ -67,13 +68,13 @@ struct ike_sa_manager_t {
         * Checkout an IKE_SA by a message.
         * 
         * In some situations, it is necessary that the manager knows the
-        * message to use for the checkout. This has the folloing reasons:
+        * message to use for the checkout. This has the following reasons:
         * 
         * 1. If the targeted IKE_SA is already processing a message, we do not
         *    check it out if the message ID is the same.
         * 2. If it is an IKE_SA_INIT request, we have to check if it is a 
         *    retransmission. If so, we have to drop the message, we would
-        *    create another unneded IKE_SA for each retransmitted packet.
+        *    create another unneeded IKE_SA for each retransmitted packet.
         *
         * A call to checkout_by_message() returns a (maybe new created) IKE_SA.
         * If processing the message does not make sense (for the reasons above),
@@ -103,12 +104,17 @@ struct ike_sa_manager_t {
                                                                         peer_cfg_t *peer_cfg);
        
        /**
-        * Check out a duplicate if ike_sa to do uniqueness tests.
-        *
-        * @param ike_sa                        ike_sa to get a duplicate from
-        * @return                                      checked out duplicate
+        * Check for duplicates of the given IKE_SA.
+        * 
+        * Measures are taken according to the uniqueness policy of the IKE_SA.
+        * The return value indicates whether duplicates have been found and if
+        * further measures should be taken (e.g. cancelling an IKE_AUTH exchange).
+        * 
+        * @param ike_sa                        ike_sa to check
+        * @return                                      TRUE, if the given IKE_SA has duplicates and
+        *                                                      should be deleted
         */
-       ike_sa_t* (*checkout_duplicate)(ike_sa_manager_t *this, ike_sa_t *ike_sa);
+       bool (*check_uniqueness)(ike_sa_manager_t *this, ike_sa_t *ike_sa);
        
        /**
         * Check out an IKE_SA a unique ID.
@@ -157,14 +163,12 @@ struct ike_sa_manager_t {
         * 
         * @warning the SA pointer MUST NOT be used after checkin! 
         * The SA must be checked out again!
+        * If the IKE_SA is not registered in the manager, a new entry is created.
         *  
         * @param ike_sa_id                     the SA identifier, will be updated
         * @param ike_sa                        checked out SA
-        * @returns                             
-        *                                                      - SUCCESS if checked in
-        *                                                      - NOT_FOUND when not found (shouldn't happen!)
         */
-       status_t (*checkin) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
+       void (*checkin) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
        
        /**
         * Destroy a checked out SA.
@@ -177,11 +181,8 @@ struct ike_sa_manager_t {
         * risk that another thread can get the SA.
         *
         * @param ike_sa                        SA to delete
-        * @returns                             
-        *                                                      - SUCCESS if found
-        *                                                      - NOT_FOUND when no such SA is available
         */
-       status_t (*checkin_and_destroy) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
+       void (*checkin_and_destroy) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
        
        /**
         * Get the number of IKE_SAs which are in the connecting state.