Source/charon/sa/ike_sa_manager.h

   1 /**
   2  * @file ike_sa_manager.h
   3  *
   4  * @brief Interface of ike_sa_manager_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005 Jan Hutter, Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23 #ifndef _IKE_SA_MANAGER_H_
  24 #define _IKE_SA_MANAGER_H_
  25
  26 #include <types.h>
  27 #include <sa/ike_sa.h>
  28
  29
  30 typedef struct ike_sa_manager_t ike_sa_manager_t;
  31
  32 /**
  33  * @brief The IKE_SA-Manager is responsible for managing all initiated and responded IKE_SA's.
  34  *
  35  * To avoid access from multiple threads, IKE_SAs must be checked out from
  36  * the manager, and checked in after usage.
  37  * The manager also handles deletion of SAs.
  38  *
  39  * @todo checking of double-checkouts from the same threads would be nice.
  40  * This could be done by comparing thread-ids via pthread_self()...
  41  *
  42  * @todo Managing of ike_sa_t objects in a hash table instead of linked list.
  43  *
  44  * @b Constructors:
  45  * - ike_sa_manager_create()
  46  *
  47  * @ingroup sa
  48  */
  49 struct ike_sa_manager_t {
  50         /**
  51          * @brief Checkout an IKE_SA, create it when necesarry.
  52          *
  53          * Checks out a SA by its ID. An SA will be created, when:
  54          * - Responder SPI is not set (when received an IKE_SA_INIT from initiator)
  55          * Management of SPIs is the managers job, he will set it.
  56          * This function blocks until SA is available for checkout.
  57          *
  58          * @warning checking out two times without checking in will
  59          * result in a deadlock!
  60          *
  61          * @param ike_sa_manager        the manager object
  62          * @param ike_sa_id[in/out]     the SA identifier, will be updated
  63          * @param ike_sa[out]           checked out SA
  64          * @returns
  65          *                                                      - SUCCESS if checkout successful
  66          *                                                      - NOT_FOUND when no such SA is available
  67          *                                                      - CREATED if a new IKE_SA got created
  68          */
  69         status_t (*checkout) (ike_sa_manager_t* ike_sa_manager, ike_sa_id_t *sa_id, ike_sa_t **ike_sa);
  70
  71         /**
  72          * @brief Create and checkout an IKE_SA as original initator.
  73          *
  74          * Creates and checks out a SA as initiator.
  75          * Management of SPIs is the managers job, he will set it.
  76          *
  77          * @param ike_sa_manager        the manager object
  78          * @param ike_sa[out]           checked out SA
  79          */
  80         void (*create_and_checkout) (ike_sa_manager_t* ike_sa_manager,ike_sa_t **ike_sa);
  81
  82         /**
  83          * @brief Checkin the SA after usage.
  84          *
  85          * @warning the SA pointer MUST NOT be used after checkin!
  86          * The SA must be checked out again!
  87          *
  88          * @param ike_sa_manager        the manager object
  89          * @param ike_sa_id[in/out]     the SA identifier, will be updated
  90          * @param ike_sa[out]           checked out SA
  91          * @returns
  92          *                                                      - SUCCESS if checked in
  93          *                                                      - NOT_FOUND when not found (shouldn't happen!)
  94          */
  95         status_t (*checkin) (ike_sa_manager_t* ike_sa_manager, ike_sa_t *ike_sa);
  96         /**
  97          * @brief Delete a SA, which was not checked out.
  98          *
  99          * @warning do not use this when the SA is already checked out, this will
 100          * deadlock!
 101          *
 102          * @param ike_sa_manager        the manager object
 103          * @param ike_sa_id[in/out]     the SA identifier
 104          * @returns
 105          *                                                      - SUCCESS if found
 106          *                                                      - NOT_FOUND when no such SA is available
 107          */
 108         status_t (*delete) (ike_sa_manager_t* ike_sa_manager, ike_sa_id_t *ike_sa_id);
 109
 110         /**
 111          * @brief Delete a checked out SA.
 112          *
 113          * @param ike_sa_manager        the manager object
 114          * @param ike_sa                        SA to delete
 115          * @returns
 116          *                                                      - SUCCESS if found
 117          *                                                      - NOT_FOUND when no such SA is available
 118          */
 119         status_t (*checkin_and_delete) (ike_sa_manager_t* ike_sa_manager, ike_sa_t *ike_sa);
 120
 121         /**
 122          * @brief Destroys the manager with all associated SAs.
 123          *
 124          * Threads will be driven out, so all SAs can be deleted cleanly.
 125          *
 126          * @param ike_sa_manager the manager object
 127          */
 128         void (*destroy) (ike_sa_manager_t *ike_sa_manager);
 129 };
 130
 131 /**
 132  * @brief Create a manager.
 133  *
 134  * @returns     ike_sa_manager_t object
 135  *
 136  * @ingroup sa
 137  */
 138 ike_sa_manager_t *ike_sa_manager_create();
 139
 140 #endif /*_IKE_SA_MANAGER_H_*/