add priority management for kernel policy
[strongswan.git] / src / charon / sa / ike_sa_manager.h
index a608052..db2efe5 100644 (file)
@@ -6,7 +6,8 @@
  */
 
 /*
- * Copyright (C) 2005 Jan Hutter, Martin Willi
+ * 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
@@ -51,8 +52,8 @@ 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)
+        * Checks out a SA by its ID. An SA will be created, when the 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.
         * 
@@ -60,47 +61,52 @@ struct ike_sa_manager_t {
         * 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[in/out] 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 no such IKE_SA available
         */
-       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.
-        * 
+        * @brief Checkout an existing IKE_SA by hosts and identifications.
+        *
+        * Allows the lookup of an IKE_SA by user IDs and hosts. It returns the
+        * first found occurence, if there are multiple candidates. Supplied IDs
+        * may contain wildcards, hosts may be %any. 
+        * If no IKE_SA is found, a new one is created.
+        *
         * @param this                          the manager object
-        * @param ike_sa[out]           checked out SA
+        * @param my_host                       address of our host
+        * @param other_id                      address of remote host
+        * @param my_id                         ID used by us
+        * @param other_id                      ID used by remote
+        * @return                                      checked out/created IKE_SA
         */
-       void (*create_and_checkout) (ike_sa_manager_t* this,ike_sa_t **ike_sa);
+       ike_sa_t* (*checkout_by_id) (ike_sa_manager_t* this,
+                                                                 host_t *my_host, host_t* other_host,
+                                                                 identification_t *my_id, 
+                                                                 identification_t *other_id);
        
        /**
-        * @brief Check out an IKE_SA, defined be the two peers.
-        * 
-        * 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.
-        * 
-        * @param this                          the manager object
-        * @param me                            host on local side
-        * @param other                         host on remote side
-        * @param ike_sa[out]           checked out SA
+        * @brief Check out an IKE_SA by protocol and SPI of one of its CHILD_SA.
+        *
+        * The kernel sends us expire messages for IPsec SAs. To fullfill
+        * this request, we must check out the IKE SA which contains the
+        * CHILD_SA the kernel wants to modify.
+        *
+        * @param this                          the manager object
+        * @param reqid                         reqid of the CHILD_SA
         * @return
-        *                                                      - NOT_FOUND, if no such SA found
-        *                                                      - SUCCESS, if SA found and ike_sa set appropriatly
+        *                                                      - checked out IKE_SA, if found
+        *                                                      - NULL, if not found
         */
-       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_child) (ike_sa_manager_t* this, u_int32_t reqid);
        
        /**
         * @brief Get a list of all IKE_SA SAs currently set up.
         * 
-        * The resulting list with all IDs must be destroyd by 
+        * The resulting list with all IDs must be destroyed 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.
@@ -111,15 +117,6 @@ struct ike_sa_manager_t {
        linked_list_t *(*get_ike_sa_list) (ike_sa_manager_t* this);
        
        /**
-        * @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
-        */
-       linked_list_t *(*get_ike_sa_list_by_name) (ike_sa_manager_t* this, const char *name);
-       
-       /**
         * @brief Log the status of the IKE_SA's in the manager.
         *
         * A informational log is done to the supplied logger. If logger is 
@@ -139,8 +136,8 @@ struct ike_sa_manager_t {
         * The SA must be checked out again!
         *  
         * @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[in/out] ike_sa_id     the SA identifier, will be updated
+        * @param[out] ike_sa           checked out SA
         * @returns                             
         *                                                      - SUCCESS if checked in
         *                                                      - NOT_FOUND when not found (shouldn't happen!)
@@ -151,14 +148,14 @@ struct ike_sa_manager_t {
         * @brief Delete a SA, which was not checked out.
         *
         * If the state allows it, the IKE SA is destroyed immediately. If it is
-        * in the state ike_sa_established or further, a delete message
+        * in the state ESTABLSIHED, a delete message
         * is sent to the remote peer, which has to be acknowledged.
         *
         * @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
+        * @param[in/out] ike_sa_id     the SA identifier
         * @returns                             
         *                                                      - SUCCESS if found
         *                                                      - NOT_FOUND when no such SA is available
@@ -166,6 +163,29 @@ struct ike_sa_manager_t {
        status_t (*delete) (ike_sa_manager_t* this, ike_sa_id_t *ike_sa_id);
        
        /**
+        * @brief Delete a SA identified by its name, which was not checked out.
+        *
+        * Using delete_by_name allows the delete of IKE_SAs and CHILD_SAs.
+        * The supplied name may have one of the following format:
+        *
+        * name{x}              => delete IKE_SA with "name" and unique id "x"
+        * name{}               => delete all IKE_SAs with "name"
+        * name[x]              => delete CHILD_SA with "name" and unique id "x"
+        * name[]               => delete all CHILD_SAs with "name"
+        * name                 => delete all CHILD_SAs or IKE_SAs with "name"
+        *
+        * @warning do not use this when the SA is already checked out, this will
+        * deadlock!
+        *
+        * @param this                          the manager object
+        * @param name                          name in one of the format described above
+        * @returns                             
+        *                                                      - SUCCESS if found
+        *                                                      - NOT_FOUND when no such SA is available
+        */
+       status_t (*delete_by_name) (ike_sa_manager_t* this, char *name);
+       
+       /**
         * @brief Destroy a checked out SA.
         *
         * The IKE SA is destroyed without notification of the remote peer.