improved IKE_SA uniqueness check
[strongswan.git] / src / charon / sa / ike_sa_manager.h
index d4cd749..b5c479e 100644 (file)
@@ -1,12 +1,7 @@
-/**
- * @file ike_sa_manager.h
- * 
- * @brief Interface of ike_sa_manager_t.
- * 
- */
-
 /*
- * Copyright (C) 2005 Jan Hutter, Martin Willi
+ * Copyright (C) 2008 Tobias Brunner
+ * Copyright (C) 2005-2006 Martin Willi
+ * Copyright (C) 2005 Jan Hutter
  * Hochschule fuer Technik Rapperswil
  *
  * This program is free software; you can redistribute it and/or modify it
  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * for more details.
+ *
+ * $Id$
+ */
+
+/**
+ * @defgroup ike_sa_manager ike_sa_manager
+ * @{ @ingroup sa
  */
 
 #ifndef IKE_SA_MANAGER_H_
 #define IKE_SA_MANAGER_H_
 
-#include <types.h>
-#include <sa/ike_sa.h>
-#include <utils/logger.h>
-
-
 typedef struct ike_sa_manager_t ike_sa_manager_t;
 
+#include <library.h>
+#include <sa/ike_sa.h>
+#include <encoding/message.h>
+#include <config/peer_cfg.h>
+
 /**
- * @brief The IKE_SA-Manager is responsible for managing all initiated and responded IKE_SA's.
+ * The IKE_SA-Manager is responsible for managing all initiated and responded IKE_SA's.
  *
  * To avoid access from multiple threads, IKE_SAs must be checked out from
  * the manager, and checked in after usage. 
@@ -41,154 +43,182 @@ typedef struct ike_sa_manager_t ike_sa_manager_t;
  * This could be done by comparing thread-ids via pthread_self()...
  * 
  * @todo Managing of ike_sa_t objects in a hash table instead of linked list.
- * 
- * @b Constructors:
- * - ike_sa_manager_create()
- * 
- * @ingroup sa
  */
 struct ike_sa_manager_t {
+       
        /**
-        * @brief Checkout an IKE_SA, create it when necesarry.
-        * 
-        * Checks out a SA by its ID. An SA will be created, when:
-        * - Responder SPI is not set (when received an IKE_SA_INIT from initiator)
-        * Management of SPIs is the managers job, he will set it.
-        * This function blocks until SA is available for checkout.
+        * Checkout an existing IKE_SA.
         * 
-        * @warning checking out two times without checking in will
-        * result in a deadlock!
-        * 
-        * @param this                          the manager object
-        * @param ike_sa_id[in/out]     the SA identifier, will be updated
-        * @param ike_sa[out]           checked out SA
+        * @param ike_sa_id                     the SA identifier, will be updated
         * @returns                                     
-        *                                                      - SUCCESS if checkout successful
-        *                                                      - NOT_FOUND when no such SA is available
-        *                                                      - CREATED if a new IKE_SA got created
+        *                                                      - checked out IKE_SA if found
+        *                                                      - NULL, if specified IKE_SA is not found.
         */
-       status_t (*checkout) (ike_sa_manager_t* this, ike_sa_id_t *sa_id, ike_sa_t **ike_sa);
+       ike_sa_t* (*checkout) (ike_sa_manager_t* this, ike_sa_id_t *sa_id);
        
        /**
-        * @brief Create and checkout an IKE_SA as original initator.
-        * 
-        * Creates and checks out a SA as initiator.
-        * Management of SPIs is the managers job, he will set it.
+        * Create and check out a new IKE_SA.
         * 
-        * @param this                          the manager object
-        * @param ike_sa[out]           checked out SA
+        * @param initiator                     TRUE for initiator, FALSE otherwise
+        * @returns                             created and checked out IKE_SA
         */
-       void (*create_and_checkout) (ike_sa_manager_t* this,ike_sa_t **ike_sa);
+       ike_sa_t* (*checkout_new) (ike_sa_manager_t* this, bool initiator);
        
        /**
-        * @brief Check out an IKE_SA, defined be the two peers.
+        * Checkout an IKE_SA by a message.
         * 
-        * Checking out an IKE_SA by their peer addresses may be necessary
-        * for kernel traps, status querying and so on... one of the hosts
-        * may be 0.0.0.0 (defaultroute/any), but not both.
+        * In some situations, it is necessary that the manager knows the
+        * message to use for the checkout. This has the following reasons:
         * 
-        * @param this                          the manager object
-        * @param me                            host on local side
-        * @param other                         host on remote side
-        * @param ike_sa[out]           checked out SA
-        * @return
-        *                                                      - NOT_FOUND, if no such SA found
-        *                                                      - SUCCESS, if SA found and ike_sa set appropriatly
+        * 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 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),
+        * NULL is returned.
+        * 
+        * @param ike_sa_id                     the SA identifier, will be updated
+        * @returns                                     
+        *                                                      - checked out/created IKE_SA
+        *                                                      - NULL to not process message further
+        */
+       ike_sa_t* (*checkout_by_message) (ike_sa_manager_t* this, message_t *message);
+       
+       /**
+        * Checkout an IKE_SA for initiation by a peer_config.
+        *
+        * To initiate, a CHILD_SA may be established within an existing IKE_SA.
+        * This call checks for an existing IKE_SA by comparing the configuration.
+        * If the CHILD_SA can be created in an existing IKE_SA, the matching SA
+        * is returned.
+        * If no IKE_SA is found, a new one is created. This is also the case when
+        * the found IKE_SA is in the DELETING state.
+        *
+        * @param peer_cfg                      configuration used to find an existing IKE_SA
+        * @return                                      checked out/created IKE_SA
         */
-       status_t (*checkout_by_hosts) (ike_sa_manager_t* this, host_t *me, host_t *other, ike_sa_t **ike_sa);
+       ike_sa_t* (*checkout_by_config) (ike_sa_manager_t* this,
+                                                                        peer_cfg_t *peer_cfg);
        
        /**
-        * @brief Get a list of all IKE_SA SAs currently set up.
+        * Check for duplicates of the given IKE_SA.
         * 
-        * The resulting list with all IDs must be destroyd by 
-        * the caller. There is no guarantee an ike_sa with the 
-        * corrensponding ID really exists, since it may be deleted
-        * in the meantime by another thread.
+        * 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 this                          the manager object
-        * @return                                      a list with ike_sa_id_t s
+        * @param ike_sa                        ike_sa to check
+        * @return                                      TRUE, if the given IKE_SA has duplicates and
+        *                                                      should be deleted
         */
-       linked_list_t *(*get_ike_sa_list) (ike_sa_manager_t* this);
+       bool (*check_uniqueness)(ike_sa_manager_t *this, ike_sa_t *ike_sa);
        
        /**
-        * @brief Get a list of all IKE_SA SAs currently set up specified
-        * by the connections name.
-        * 
-        * @param this                          the manager object
-        * @return                                      a list with ike_sa_id_t s
+        * Check out an IKE_SA a unique ID.
+        *
+        * Every IKE_SA and every CHILD_SA is uniquely identified by an ID. 
+        * These checkout function uses, depending
+        * on the child parameter, the unique ID of the IKE_SA or the reqid
+        * of one of a IKE_SAs CHILD_SA.
+        *
+        * @param id                            unique ID of the object
+        * @param child                         TRUE to use CHILD, FALSE to use IKE_SA
+        * @return
+        *                                                      - checked out IKE_SA, if found
+        *                                                      - NULL, if not found
         */
-       linked_list_t *(*get_ike_sa_list_by_name) (ike_sa_manager_t* this, const char *name);
+       ike_sa_t* (*checkout_by_id) (ike_sa_manager_t* this, u_int32_t id,
+                                                                bool child);
        
        /**
-        * @brief Log the status of the IKE_SA's in the manager.
+        * Check out an IKE_SA by the policy/connection name.
         *
-        * A informational log is done to the supplied logger. If logger is 
-        * NULL, an internal logger is used. If a name is supplied,
-        * only connections with the matching name will be logged.
-        * 
-        * @param this                          the manager object
-        * @param logger                        logger to do the log, or NULL
-        * @param name                          name of a connection, or NULL
+        * Check out the IKE_SA by the connections name or by a CHILD_SAs policy
+        * name.
+        *
+        * @param name                          name of the connection/policy
+        * @param child                         TRUE to use policy name, FALSE to use conn name
+        * @return
+        *                                                      - checked out IKE_SA, if found
+        *                                                      - NULL, if not found
+        */
+       ike_sa_t* (*checkout_by_name) (ike_sa_manager_t* this, char *name,
+                                                                  bool child);
+       
+       /**
+        * Create an enumerator over all stored IKE_SAs.
+        *
+        * The avoid synchronization issues, the enumerator locks access
+        * to the manager exclusively, until it gets destroyed.
+        *
+        * @return                                      enumerator over all IKE_SAs.
         */
-       void (*log_status) (ike_sa_manager_t* this, logger_t* logger, char* name);
+       enumerator_t *(*create_enumerator) (ike_sa_manager_t* this);
        
        /**
-        * @brief Checkin the SA after usage.
+        * Checkin the SA after usage.
         * 
         * @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 this                          the manager object
-        * @param ike_sa_id[in/out]     the SA identifier, will be updated
-        * @param ike_sa[out]           checked out SA
-        * @returns                             
-        *                                                      - SUCCESS if checked in
-        *                                                      - NOT_FOUND when not found (shouldn't happen!)
+        * @param ike_sa_id                     the SA identifier, will be updated
+        * @param ike_sa                        checked out SA
         */
-       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);
        
        /**
-        * @brief Delete a SA, which was not checked out.
-        * 
-        * @warning do not use this when the SA is already checked out, this will
-        * deadlock!
-        *  
-        * @param this                          the manager object
-        * @param ike_sa_id[in/out]     the SA identifier
-        * @returns                             
-        *                                                      - SUCCESS if found
-        *                                                      - NOT_FOUND when no such SA is available
+        * Destroy a checked out SA.
+        *
+        * The IKE SA is destroyed without notification of the remote peer.
+        * Use this only if the other peer doesn't respond or behaves not
+        * as predicted.
+        * Checking in and destruction is an atomic operation (for the IKE_SA),
+        * so this can be called if the SA is in a "unclean" state, without the
+        * risk that another thread can get the SA.
+        *
+        * @param ike_sa                        SA to delete
         */
-       status_t (*delete) (ike_sa_manager_t* this, ike_sa_id_t *ike_sa_id);
+       void (*checkin_and_destroy) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
        
        /**
-        * @brief Delete a checked out SA.
+        * Get the number of IKE_SAs which are in the connecting state.
         *
-        * @param this                          the manager object
-        * @param ike_sa                        SA to delete
-        * @returns                             
-        *                                                      - SUCCESS if found
-        *                                                      - NOT_FOUND when no such SA is available
+        * To prevent the server from resource exhaustion, cookies and other
+        * mechanisms are used. The number of half open IKE_SAs is a good
+        * indicator to see if a peer is flooding the server.
+        * If a host is supplied, only the number of half open IKE_SAs initiated
+        * from this IP are counted.
+        * Only SAs for which we are the responder are counted.
+        * 
+        * @param ip                            NULL for all, IP for half open IKE_SAs with IP
+        * @return                                      number of half open IKE_SAs
         */
-       status_t (*checkin_and_delete) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
+       int (*get_half_open_count) (ike_sa_manager_t *this, host_t *ip);
        
        /**
-        * @brief Destroys the manager with all associated SAs.
+        * Delete all existing IKE_SAs and destroy them immediately.
         * 
         * Threads will be driven out, so all SAs can be deleted cleanly.
-        * 
-        * @param this                           the manager object
+        */
+       void (*flush)(ike_sa_manager_t *this);
+       
+       /**
+        * Destroys the manager with all associated SAs.
+        *
+        * A call to flush() is required before calling destroy.
         */
        void (*destroy) (ike_sa_manager_t *this);
 };
 
 /**
- * @brief Create a manager.
- * 
- * @returns    ike_sa_manager_t object
+ * Create a manager.
  * 
- * @ingroup sa
+ * @returns    ike_sa_manager_t object, NULL if initialization fails
  */
 ike_sa_manager_t *ike_sa_manager_create(void);
 
-#endif /*IKE_SA_MANAGER_H_*/
+#endif /*IKE_SA_MANAGER_H_ @} */