src/libcharon/sa/ike_sa_manager.h

   1 /*
   2  * Copyright (C) 2008-2021 Tobias Brunner
   3  * Copyright (C) 2005-2008 Martin Willi
   4  * Copyright (C) 2005 Jan Hutter
   5  * HSR 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  * Callback called to generate an IKE SPI.
  35  *
  36  * This may be called from multiple threads concurrently.
  37  *
  38  * @param data          data supplied during registration of the callback
  39  * @return                      allocated SPI, 0 on failure
  40  */
  41 typedef uint64_t (*spi_cb_t)(void *data);
  42
  43 /**
  44  * Manages and synchronizes access to all IKE_SAs.
  45  *
  46  * To synchronize access to thread-unsave IKE_SAs, they are checked out for
  47  * use and checked in afterwards. A checked out SA is exclusively accessible
  48  * by the owning thread.
  49  */
  50 struct ike_sa_manager_t {
  51
  52         /**
  53          * Create a new IKE_SA.
  54          *
  55          * @param version                       IKE version of this SA
  56          * @param initiator                     TRUE for initiator, FALSE otherwise
  57          * @returns                             created IKE_SA (not registered/checked out)
  58          */
  59         ike_sa_t *(*create_new)(ike_sa_manager_t* this, ike_version_t version,
  60                                                         bool initiator);
  61
  62         /**
  63          * Register/checkout an IKE_SA created with create_new().
  64          *
  65          * This may be used shortly before calling checkin() for unregistered SAs
  66          * created via create_new() to avoid race conditions so e.g. jobs may
  67          * find the SA and block on it until checkin() is called.
  68          *
  69          * @note There is no check that verifies that the IKE_SA is not yet
  70          * registered.
  71          *
  72          * @note The IKE_SA on the bus is not changed by this method.
  73          *
  74          * @param ike_sa                        IKE_SA to register
  75          */
  76         void (*checkout_new)(ike_sa_manager_t* this, ike_sa_t *ike_sa);
  77
  78         /**
  79          * Checkout an existing IKE_SA.
  80          *
  81          * @param ike_sa_id                     the SA identifier, will be updated
  82          * @returns
  83          *                                                      - checked out IKE_SA if found
  84          *                                                      - NULL, if specified IKE_SA is not found.
  85          */
  86         ike_sa_t* (*checkout) (ike_sa_manager_t* this, ike_sa_id_t *sa_id);
  87
  88         /**
  89          * Checkout an IKE_SA by a message.
  90          *
  91          * In some situations, it is necessary that the manager knows the
  92          * message to use for the checkout. This has the following reasons:
  93          *
  94          * 1. If the targeted IKE_SA is already processing a message, we do not
  95          *    check it out if the message ID is the same.
  96          * 2. If it is an IKE_SA_INIT request, we have to check if it is a
  97          *    retransmission. If so, we have to drop the message, we would
  98          *    create another unneeded IKE_SA for each retransmitted packet.
  99          *
 100          * A call to checkout_by_message() returns a (maybe new created) IKE_SA.
 101          * If processing the message does not make sense (for the reasons above),
 102          * NULL is returned.
 103          *
 104          * @param ike_sa_id                     the SA identifier, will be updated
 105          * @returns
 106          *                                                      - checked out/created IKE_SA
 107          *                                                      - NULL to not process message further
 108          */
 109         ike_sa_t* (*checkout_by_message) (ike_sa_manager_t* this, message_t *message);
 110
 111         /**
 112          * Checkout an IKE_SA for initiation by a peer_config.
 113          *
 114          * To initiate, a CHILD_SA may be established within an existing IKE_SA.
 115          * This call checks for an existing IKE_SA by comparing the configuration.
 116          * If the CHILD_SA can be created in an existing IKE_SA, the matching SA
 117          * is returned.
 118          * If no IKE_SA is found, a new one is created and registered in the
 119          * manager. This is also the case when the found IKE_SA is in an unusable
 120          * state (e.g. DELETING).
 121          *
 122          * @note The peer_config is always set on the returned IKE_SA.
 123          *
 124          * @param peer_cfg                      configuration used to find an existing IKE_SA
 125          * @return                                      checked out/created IKE_SA
 126          */
 127         ike_sa_t *(*checkout_by_config)(ike_sa_manager_t* this, peer_cfg_t *peer_cfg);
 128
 129         /**
 130          * Reset initiator SPI.
 131          *
 132          * Allocate a new initiator SPI for the given IKE_SA in state IKE_CONNECTING
 133          * and update internal data.
 134          *
 135          * @param ike_sa                        IKE_SA to update
 136          * @return                                      TRUE if SPI successfully changed
 137          */
 138         bool (*new_initiator_spi)(ike_sa_manager_t* this, ike_sa_t *ike_sa);
 139
 140         /**
 141          * Check for duplicates of the given IKE_SA.
 142          *
 143          * Measures are taken according to the uniqueness policy of the IKE_SA.
 144          * The return value indicates whether duplicates have been found and if
 145          * further measures should be taken (e.g. cancelling an IKE_AUTH exchange).
 146          * check_uniqueness() must be called before the IKE_SA is complete,
 147          * deadlocks occur otherwise.
 148          *
 149          * @param ike_sa                        ike_sa to check
 150          * @param force_replace         replace existing SAs, regardless of unique policy
 151          * @return                                      TRUE, if the given IKE_SA has duplicates and
 152          *                                                      should be deleted
 153          */
 154         bool (*check_uniqueness)(ike_sa_manager_t *this, ike_sa_t *ike_sa,
 155                                                          bool force_replace);
 156
 157         /**
 158          * Check if we already have a connected IKE_SA between two identities.
 159          *
 160          * @param me                            own identity
 161          * @param other                         remote identity
 162          * @param family                        address family to include in uniqueness check
 163          * @return                                      TRUE if we have a connected IKE_SA
 164          */
 165         bool (*has_contact)(ike_sa_manager_t *this, identification_t *me,
 166                                                 identification_t *other, int family);
 167
 168         /**
 169          * Check out an IKE_SA a unique ID.
 170          *
 171          * Every IKE_SA is uniquely identified by a numerical ID. This checkout
 172          * function uses the unique ID of the IKE_SA to check it out.
 173          *
 174          * @param id                            unique ID of the object
 175          * @return
 176          *                                                      - checked out IKE_SA, if found
 177          *                                                      - NULL, if not found
 178          */
 179         ike_sa_t* (*checkout_by_id) (ike_sa_manager_t* this, uint32_t id);
 180
 181         /**
 182          * Check out an IKE_SA by the policy/connection name.
 183          *
 184          * Check out the IKE_SA by the configuration name, either from the IKE- or
 185          * one of its CHILD_SAs.
 186          *
 187          * @param name                          name of the connection/policy
 188          * @param child                         TRUE to use policy name, FALSE to use conn name
 189          * @return
 190          *                                                      - checked out IKE_SA, if found
 191          *                                                      - NULL, if not found
 192          */
 193         ike_sa_t* (*checkout_by_name) (ike_sa_manager_t* this, char *name,
 194                                                                    bool child);
 195
 196         /**
 197          * Create an enumerator over all stored IKE_SAs.
 198          *
 199          * While enumerating an IKE_SA, it is temporarily checked out and
 200          * automatically checked in after the current enumeration step.
 201          *
 202          * @param wait                          TRUE to wait for checked out SAs, FALSE to skip
 203          * @return                                      enumerator over all IKE_SAs.
 204          */
 205         enumerator_t *(*create_enumerator) (ike_sa_manager_t* this, bool wait);
 206
 207         /**
 208          * Create an enumerator over ike_sa_id_t*, matching peer identities.
 209          *
 210          * The remote peer is identified by its XAuth or EAP identity, if available.
 211          *
 212          * @param me                            local peer identity to match
 213          * @param other                         remote peer identity to match
 214          * @param family                        address family to match, 0 for any
 215          * @return                                      enumerator over ike_sa_id_t*
 216          */
 217         enumerator_t* (*create_id_enumerator)(ike_sa_manager_t *this,
 218                                                                 identification_t *me, identification_t *other,
 219                                                                 int family);
 220
 221         /**
 222          * Checkin the SA after usage.
 223          *
 224          * If the IKE_SA is not registered in the manager, a new entry is created.
 225          *
 226          * @param ike_sa_id                     the SA identifier, will be updated
 227          * @param ike_sa                        checked out SA
 228          */
 229         void (*checkin) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
 230
 231         /**
 232          * Destroy a checked out SA.
 233          *
 234          * The IKE SA is destroyed without notification of the remote peer.
 235          * Use this only if the other peer doesn't respond or behaves not
 236          * as predicted.
 237          * Checking in and destruction is an atomic operation (for the IKE_SA),
 238          * so this can be called if the SA is in a "unclean" state, without the
 239          * risk that another thread can get the SA.
 240          *
 241          * @param ike_sa                        SA to delete
 242          */
 243         void (*checkin_and_destroy) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
 244
 245         /**
 246          * Get the number of IKE_SAs currently registered.
 247          *
 248          * @return                                      number of registered IKE_SAs
 249          */
 250         u_int (*get_count)(ike_sa_manager_t *this);
 251
 252         /**
 253          * Get the number of IKE_SAs which are in the connecting state.
 254          *
 255          * To prevent the server from resource exhaustion, cookies and other
 256          * mechanisms are used. The number of half open IKE_SAs is a good
 257          * indicator to see if a peer is flooding the server.
 258          * If a host is supplied, only the number of half open IKE_SAs with this IP
 259          * are counted.
 260          *
 261          * @param ip                            NULL for all, IP for half open IKE_SAs with IP
 262          * @param responder_only        TRUE to return only the number of responding SAs
 263          * @return                                      number of half open IKE_SAs
 264          */
 265         u_int (*get_half_open_count)(ike_sa_manager_t *this, host_t *ip,
 266                                                                  bool responder_only);
 267
 268         /**
 269          * Set the callback to generate IKE SPIs
 270          *
 271          * @param callback              callback to register
 272          * @param data                  data provided to callback
 273          */
 274         void (*set_spi_cb)(ike_sa_manager_t *this, spi_cb_t callback,
 275                                            void *data);
 276
 277         /**
 278          * Delete all existing IKE_SAs and destroy them immediately.
 279          *
 280          * Threads will be driven out, so all SAs can be deleted cleanly.
 281          * To a flush(), an immediate call to destroy() is mandatory; no other
 282          * method may be used.
 283          */
 284         void (*flush)(ike_sa_manager_t *this);
 285
 286         /**
 287          * Destroys the manager with all associated SAs.
 288          *
 289          * A call to flush() is required before calling destroy.
 290          */
 291         void (*destroy) (ike_sa_manager_t *this);
 292 };
 293
 294 /**
 295  * Create the IKE_SA manager.
 296  *
 297  * @returns     ike_sa_manager_t object, NULL if initialization fails
 298  */
 299 ike_sa_manager_t *ike_sa_manager_create(void);
 300
 301 #endif /** IKE_SA_MANAGER_H_ @}*/