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