ec157ab3ad504c57883b2316a2ef7c8c2d292448
[strongswan.git] / 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_ @}*/