src/libcharon/sa/ike_sa_manager.h

   1 /*
   2  * Copyright (C) 2008 Tobias Brunner
   3  * Copyright (C) 2005-2008 Martin Willi
   4  * Copyright (C) 2005 Jan Hutter
   5  * Hochschule fuer Technik Rapperswil
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the
   9  * Free Software Foundation; either version 2 of the License, or (at your
  10  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  * for more details.
  16  */
  17
  18 /**
  19  * @defgroup ike_sa_manager ike_sa_manager
  20  * @{ @ingroup sa
  21  */
  22
  23 #ifndef IKE_SA_MANAGER_H_
  24 #define IKE_SA_MANAGER_H_
  25
  26 typedef struct ike_sa_manager_t ike_sa_manager_t;
  27
  28 #include <library.h>
  29 #include <sa/ike_sa.h>
  30 #include <encoding/message.h>
  31 #include <config/peer_cfg.h>
  32
  33 /**
  34  * Manages and synchronizes access to all IKE_SAs.
  35  *
  36  * To synchronize access to thread-unsave IKE_SAs, they are checked out for
  37  * use and checked in afterwards. A checked out SA is exclusively accessible
  38  * by the owning thread.
  39  */
  40 struct ike_sa_manager_t {
  41
  42         /**
  43          * Checkout an existing IKE_SA.
  44          *
  45          * @param ike_sa_id                     the SA identifier, will be updated
  46          * @returns
  47          *                                                      - checked out IKE_SA if found
  48          *                                                      - NULL, if specified IKE_SA is not found.
  49          */
  50         ike_sa_t* (*checkout) (ike_sa_manager_t* this, ike_sa_id_t *sa_id);
  51
  52         /**
  53          * Create and check out a new IKE_SA.
  54          *
  55          * @param initiator                     TRUE for initiator, FALSE otherwise
  56          * @returns                             created and checked out IKE_SA
  57          */
  58         ike_sa_t* (*checkout_new) (ike_sa_manager_t* this, bool initiator);
  59
  60         /**
  61          * Checkout an IKE_SA by a message.
  62          *
  63          * In some situations, it is necessary that the manager knows the
  64          * message to use for the checkout. This has the following reasons:
  65          *
  66          * 1. If the targeted IKE_SA is already processing a message, we do not
  67          *    check it out if the message ID is the same.
  68          * 2. If it is an IKE_SA_INIT request, we have to check if it is a
  69          *    retransmission. If so, we have to drop the message, we would
  70          *    create another unneeded IKE_SA for each retransmitted packet.
  71          *
  72          * A call to checkout_by_message() returns a (maybe new created) IKE_SA.
  73          * If processing the message does not make sense (for the reasons above),
  74          * NULL is returned.
  75          *
  76          * @param ike_sa_id                     the SA identifier, will be updated
  77          * @returns
  78          *                                                      - checked out/created IKE_SA
  79          *                                                      - NULL to not process message further
  80          */
  81         ike_sa_t* (*checkout_by_message) (ike_sa_manager_t* this, message_t *message);
  82
  83         /**
  84          * Checkout an IKE_SA for initiation by a peer_config.
  85          *
  86          * To initiate, a CHILD_SA may be established within an existing IKE_SA.
  87          * This call checks for an existing IKE_SA by comparing the configuration.
  88          * If the CHILD_SA can be created in an existing IKE_SA, the matching SA
  89          * is returned.
  90          * If no IKE_SA is found, a new one is created. This is also the case when
  91          * the found IKE_SA is in the DELETING state.
  92          *
  93          * @param peer_cfg                      configuration used to find an existing IKE_SA
  94          * @return                                      checked out/created IKE_SA
  95          */
  96         ike_sa_t* (*checkout_by_config) (ike_sa_manager_t* this,
  97                                                                          peer_cfg_t *peer_cfg);
  98
  99         /**
 100          * Check for duplicates of the given IKE_SA.
 101          *
 102          * Measures are taken according to the uniqueness policy of the IKE_SA.
 103          * The return value indicates whether duplicates have been found and if
 104          * further measures should be taken (e.g. cancelling an IKE_AUTH exchange).
 105          * check_uniqueness() must be called before the IKE_SA is complete,
 106          * deadlocks occur otherwise.
 107          *
 108          * @param ike_sa                        ike_sa to check
 109          * @param force_replace         replace existing SAs, regardless of unique policy
 110          * @return                                      TRUE, if the given IKE_SA has duplicates and
 111          *                                                      should be deleted
 112          */
 113         bool (*check_uniqueness)(ike_sa_manager_t *this, ike_sa_t *ike_sa,
 114                                                          bool force_replace);
 115
 116         /**
 117          * Check if we already have a connected IKE_SA between two identities.
 118          *
 119          * @param me                            own identity
 120          * @param other                         remote identity
 121          * @param family                        address family to include in uniqueness check
 122          * @return                                      TRUE if we have a connected IKE_SA
 123          */
 124         bool (*has_contact)(ike_sa_manager_t *this, identification_t *me,
 125                                                 identification_t *other, int family);
 126
 127         /**
 128          * Check out an IKE_SA a unique ID.
 129          *
 130          * Every IKE_SA and every CHILD_SA is uniquely identified by an ID.
 131          * These checkout function uses, depending
 132          * on the child parameter, the unique ID of the IKE_SA or the reqid
 133          * of one of a IKE_SAs CHILD_SA.
 134          *
 135          * @param id                            unique ID of the object
 136          * @param child                         TRUE to use CHILD, FALSE to use IKE_SA
 137          * @return
 138          *                                                      - checked out IKE_SA, if found
 139          *                                                      - NULL, if not found
 140          */
 141         ike_sa_t* (*checkout_by_id) (ike_sa_manager_t* this, u_int32_t id,
 142                                                                  bool child);
 143
 144         /**
 145          * Check out an IKE_SA by the policy/connection name.
 146          *
 147          * Check out the IKE_SA by the configuration name, either from the IKE- or
 148          * one of its CHILD_SAs.
 149          *
 150          * @param name                          name of the connection/policy
 151          * @param child                         TRUE to use policy name, FALSE to use conn name
 152          * @return
 153          *                                                      - checked out IKE_SA, if found
 154          *                                                      - NULL, if not found
 155          */
 156         ike_sa_t* (*checkout_by_name) (ike_sa_manager_t* this, char *name,
 157                                                                    bool child);
 158
 159         /**
 160          * Create an enumerator over all stored IKE_SAs.
 161          *
 162          * While enumerating an IKE_SA, it is temporarily checked out and
 163          * automatically checked in after the current enumeration step.
 164          *
 165          * @return                                      enumerator over all IKE_SAs.
 166          */
 167         enumerator_t *(*create_enumerator) (ike_sa_manager_t* this);
 168
 169         /**
 170          * Checkin the SA after usage.
 171          *
 172          * If the IKE_SA is not registered in the manager, a new entry is created.
 173          *
 174          * @param ike_sa_id                     the SA identifier, will be updated
 175          * @param ike_sa                        checked out SA
 176          */
 177         void (*checkin) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
 178
 179         /**
 180          * Destroy a checked out SA.
 181          *
 182          * The IKE SA is destroyed without notification of the remote peer.
 183          * Use this only if the other peer doesn't respond or behaves not
 184          * as predicted.
 185          * Checking in and destruction is an atomic operation (for the IKE_SA),
 186          * so this can be called if the SA is in a "unclean" state, without the
 187          * risk that another thread can get the SA.
 188          *
 189          * @param ike_sa                        SA to delete
 190          */
 191         void (*checkin_and_destroy) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
 192
 193         /**
 194          * Get the number of IKE_SAs which are in the connecting state.
 195          *
 196          * To prevent the server from resource exhaustion, cookies and other
 197          * mechanisms are used. The number of half open IKE_SAs is a good
 198          * indicator to see if a peer is flooding the server.
 199          * If a host is supplied, only the number of half open IKE_SAs initiated
 200          * from this IP are counted.
 201          * Only SAs for which we are the responder are counted.
 202          *
 203          * @param ip                            NULL for all, IP for half open IKE_SAs with IP
 204          * @return                                      number of half open IKE_SAs
 205          */
 206         int (*get_half_open_count) (ike_sa_manager_t *this, host_t *ip);
 207
 208         /**
 209          * Delete all existing IKE_SAs and destroy them immediately.
 210          *
 211          * Threads will be driven out, so all SAs can be deleted cleanly.
 212          * To a flush(), an immediate call to destroy() is mandatory; no other
 213          * method may be used.
 214          */
 215         void (*flush)(ike_sa_manager_t *this);
 216
 217         /**
 218          * Destroys the manager with all associated SAs.
 219          *
 220          * A call to flush() is required before calling destroy.
 221          */
 222         void (*destroy) (ike_sa_manager_t *this);
 223 };
 224
 225 /**
 226  * Create the IKE_SA manager.
 227  *
 228  * @returns     ike_sa_manager_t object, NULL if initialization fails
 229  */
 230 ike_sa_manager_t *ike_sa_manager_create(void);
 231
 232 #endif /** IKE_SA_MANAGER_H_ @}*/