src/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 Get a list of all IKE_SA SAs currently set up specified
 115          * by the connections name.
 116          *
 117          * @param this                          the manager object
 118          * @return                                      a list with ike_sa_id_t s
 119          */
 120         linked_list_t *(*get_ike_sa_list_by_name) (ike_sa_manager_t* this, const char *name);
 121
 122         /**
 123          * @brief Log the status of the IKE_SA's in the manager.
 124          *
 125          * A informational log is done to the supplied logger. If logger is
 126          * NULL, an internal logger is used. If a name is supplied,
 127          * only connections with the matching name will be logged.
 128          *
 129          * @param this                          the manager object
 130          * @param logger                        logger to do the log, or NULL
 131          * @param name                          name of a connection, or NULL
 132          */
 133         void (*log_status) (ike_sa_manager_t* this, logger_t* logger, char* name);
 134
 135         /**
 136          * @brief Checkin the SA after usage.
 137          *
 138          * @warning the SA pointer MUST NOT be used after checkin!
 139          * The SA must be checked out again!
 140          *
 141          * @param this                          the manager object
 142          * @param ike_sa_id[in/out]     the SA identifier, will be updated
 143          * @param ike_sa[out]           checked out SA
 144          * @returns
 145          *                                                      - SUCCESS if checked in
 146          *                                                      - NOT_FOUND when not found (shouldn't happen!)
 147          */
 148         status_t (*checkin) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
 149
 150         /**
 151          * @brief Delete a SA, which was not checked out.
 152          *
 153          * @warning do not use this when the SA is already checked out, this will
 154          * deadlock!
 155          *
 156          * @param this                          the manager object
 157          * @param ike_sa_id[in/out]     the SA identifier
 158          * @returns
 159          *                                                      - SUCCESS if found
 160          *                                                      - NOT_FOUND when no such SA is available
 161          */
 162         status_t (*delete) (ike_sa_manager_t* this, ike_sa_id_t *ike_sa_id);
 163
 164         /**
 165          * @brief Delete a checked out SA.
 166          *
 167          * @param this                          the manager object
 168          * @param ike_sa                        SA to delete
 169          * @returns
 170          *                                                      - SUCCESS if found
 171          *                                                      - NOT_FOUND when no such SA is available
 172          */
 173         status_t (*checkin_and_delete) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
 174
 175         /**
 176          * @brief Destroys the manager with all associated SAs.
 177          *
 178          * Threads will be driven out, so all SAs can be deleted cleanly.
 179          *
 180          * @param this                           the manager object
 181          */
 182         void (*destroy) (ike_sa_manager_t *this);
 183 };
 184
 185 /**
 186  * @brief Create a manager.
 187  *
 188  * @returns     ike_sa_manager_t object
 189  *
 190  * @ingroup sa
 191  */
 192 ike_sa_manager_t *ike_sa_manager_create(void);
 193
 194 #endif /*IKE_SA_MANAGER_H_*/