ike-sa-manager: Add a method to register/check out new IKE_SAs
[strongswan.git] / 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_ @}*/