programs/charon/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 #include <utils/logger.h>
  29
  30
  31 typedef struct ike_sa_manager_t ike_sa_manager_t;
  32
  33 /**
  34  * @brief The IKE_SA-Manager is responsible for managing all initiated and responded IKE_SA's.
  35  *
  36  * To avoid access from multiple threads, IKE_SAs must be checked out from
  37  * the manager, and checked in after usage.
  38  * The manager also handles deletion of SAs.
  39  *
  40  * @todo checking of double-checkouts from the same threads would be nice.
  41  * This could be done by comparing thread-ids via pthread_self()...
  42  *
  43  * @todo Managing of ike_sa_t objects in a hash table instead of linked list.
  44  *
  45  * @b Constructors:
  46  * - ike_sa_manager_create()
  47  *
  48  * @ingroup sa
  49  */
  50 struct ike_sa_manager_t {
  51         /**
  52          * @brief Checkout an IKE_SA, create it when necesarry.
  53          *
  54          * Checks out a SA by its ID. An SA will be created, when:
  55          * - Responder SPI is not set (when received an IKE_SA_INIT from initiator)
  56          * Management of SPIs is the managers job, he will set it.
  57          * This function blocks until SA is available for checkout.
  58          *
  59          * @warning checking out two times without checking in will
  60          * result in a deadlock!
  61          *
  62          * @param this                          the manager object
  63          * @param ike_sa_id[in/out]     the SA identifier, will be updated
  64          * @param ike_sa[out]           checked out SA
  65          * @returns
  66          *                                                      - SUCCESS if checkout successful
  67          *                                                      - NOT_FOUND when no such SA is available
  68          *                                                      - CREATED if a new IKE_SA got created
  69          */
  70         status_t (*checkout) (ike_sa_manager_t* this, ike_sa_id_t *sa_id, ike_sa_t **ike_sa);
  71
  72         /**
  73          * @brief Create and checkout an IKE_SA as original initator.
  74          *
  75          * Creates and checks out a SA as initiator.
  76          * Management of SPIs is the managers job, he will set it.
  77          *
  78          * @param this                          the manager object
  79          * @param ike_sa[out]           checked out SA
  80          */
  81         void (*create_and_checkout) (ike_sa_manager_t* this,ike_sa_t **ike_sa);
  82
  83         /**
  84          * @brief Check out an IKE_SA, defined be the two peers.
  85          *
  86          * Checking out an IKE_SA by their peer addresses may be necessary
  87          * for kernel traps, status querying and so on... one of the hosts
  88          * may be 0.0.0.0 (defaultroute/any), but not both.
  89          *
  90          * @param this                          the manager object
  91          * @param me                            host on local side
  92          * @param other                         host on remote side
  93          * @param ike_sa[out]           checked out SA
  94          * @return
  95          *                                                      - NOT_FOUND, if no such SA found
  96          *                                                      - SUCCESS, if SA found and ike_sa set appropriatly
  97          */
  98         status_t (*checkout_by_hosts) (ike_sa_manager_t* this, host_t *me, host_t *other, ike_sa_t **ike_sa);
  99
 100         /**
 101          * @brief Get a list of all IKE_SA SAs currently set up.
 102          *
 103          * The resulting list with all IDs must be destroyd by
 104          * the caller. There is no guarantee an ike_sa with the
 105          * corrensponding ID really exists, since it may be deleted
 106          * in the meantime by another thread.
 107          *
 108          * @param this                          the manager object
 109          * @return                                      a list with ike_sa_id_t s
 110          */
 111         linked_list_t *(*get_ike_sa_list) (ike_sa_manager_t* this);
 112
 113         /**
 114          * @brief Log the status of the IKE_SA's in the manager.
 115          *
 116          * A informational log is done to the supplied logger. If logger is
 117          * NULL, an internal logger is used. If a name is supplied,
 118          * only connections with the matching name will be logged.
 119          *
 120          * @param this                          the manager object
 121          * @param logger                        logger to do the log, or NULL
 122          * @param name                          name of a connection, or NULL
 123          */
 124         void (*log_status) (ike_sa_manager_t* this, logger_t* logger, char* name);
 125
 126         /**
 127          * @brief Checkin the SA after usage.
 128          *
 129          * @warning the SA pointer MUST NOT be used after checkin!
 130          * The SA must be checked out again!
 131          *
 132          * @param this                          the manager object
 133          * @param ike_sa_id[in/out]     the SA identifier, will be updated
 134          * @param ike_sa[out]           checked out SA
 135          * @returns
 136          *                                                      - SUCCESS if checked in
 137          *                                                      - NOT_FOUND when not found (shouldn't happen!)
 138          */
 139         status_t (*checkin) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
 140
 141         /**
 142          * @brief Delete a SA, which was not checked out.
 143          *
 144          * @warning do not use this when the SA is already checked out, this will
 145          * deadlock!
 146          *
 147          * @param this                          the manager object
 148          * @param ike_sa_id[in/out]     the SA identifier
 149          * @returns
 150          *                                                      - SUCCESS if found
 151          *                                                      - NOT_FOUND when no such SA is available
 152          */
 153         status_t (*delete) (ike_sa_manager_t* this, ike_sa_id_t *ike_sa_id);
 154
 155         /**
 156          * @brief Delete a checked out SA.
 157          *
 158          * @param this                          the manager object
 159          * @param ike_sa                        SA to delete
 160          * @returns
 161          *                                                      - SUCCESS if found
 162          *                                                      - NOT_FOUND when no such SA is available
 163          */
 164         status_t (*checkin_and_delete) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
 165
 166         /**
 167          * @brief Destroys the manager with all associated SAs.
 168          *
 169          * Threads will be driven out, so all SAs can be deleted cleanly.
 170          *
 171          * @param this                           the manager object
 172          */
 173         void (*destroy) (ike_sa_manager_t *this);
 174 };
 175
 176 /**
 177  * @brief Create a manager.
 178  *
 179  * @returns     ike_sa_manager_t object
 180  *
 181  * @ingroup sa
 182  */
 183 ike_sa_manager_t *ike_sa_manager_create();
 184
 185 #endif /*IKE_SA_MANAGER_H_*/