improved IKE_SA uniqueness check
[strongswan.git] / src / charon / sa / ike_sa_manager.h
1 /*
2 * Copyright (C) 2008 Tobias Brunner
3 * Copyright (C) 2005-2006 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 * $Id$
18 */
19
20 /**
21 * @defgroup ike_sa_manager ike_sa_manager
22 * @{ @ingroup sa
23 */
24
25 #ifndef IKE_SA_MANAGER_H_
26 #define IKE_SA_MANAGER_H_
27
28 typedef struct ike_sa_manager_t ike_sa_manager_t;
29
30 #include <library.h>
31 #include <sa/ike_sa.h>
32 #include <encoding/message.h>
33 #include <config/peer_cfg.h>
34
35 /**
36 * The IKE_SA-Manager is responsible for managing all initiated and responded IKE_SA's.
37 *
38 * To avoid access from multiple threads, IKE_SAs must be checked out from
39 * the manager, and checked in after usage.
40 * The manager also handles deletion of SAs.
41 *
42 * @todo checking of double-checkouts from the same threads would be nice.
43 * This could be done by comparing thread-ids via pthread_self()...
44 *
45 * @todo Managing of ike_sa_t objects in a hash table instead of linked list.
46 */
47 struct ike_sa_manager_t {
48
49 /**
50 * Checkout an existing IKE_SA.
51 *
52 * @param ike_sa_id the SA identifier, will be updated
53 * @returns
54 * - checked out IKE_SA if found
55 * - NULL, if specified IKE_SA is not found.
56 */
57 ike_sa_t* (*checkout) (ike_sa_manager_t* this, ike_sa_id_t *sa_id);
58
59 /**
60 * Create and check out a new IKE_SA.
61 *
62 * @param initiator TRUE for initiator, FALSE otherwise
63 * @returns created and checked out IKE_SA
64 */
65 ike_sa_t* (*checkout_new) (ike_sa_manager_t* this, bool initiator);
66
67 /**
68 * Checkout an IKE_SA by a message.
69 *
70 * In some situations, it is necessary that the manager knows the
71 * message to use for the checkout. This has the following reasons:
72 *
73 * 1. If the targeted IKE_SA is already processing a message, we do not
74 * check it out if the message ID is the same.
75 * 2. If it is an IKE_SA_INIT request, we have to check if it is a
76 * retransmission. If so, we have to drop the message, we would
77 * create another unneeded IKE_SA for each retransmitted packet.
78 *
79 * A call to checkout_by_message() returns a (maybe new created) IKE_SA.
80 * If processing the message does not make sense (for the reasons above),
81 * NULL is returned.
82 *
83 * @param ike_sa_id the SA identifier, will be updated
84 * @returns
85 * - checked out/created IKE_SA
86 * - NULL to not process message further
87 */
88 ike_sa_t* (*checkout_by_message) (ike_sa_manager_t* this, message_t *message);
89
90 /**
91 * Checkout an IKE_SA for initiation by a peer_config.
92 *
93 * To initiate, a CHILD_SA may be established within an existing IKE_SA.
94 * This call checks for an existing IKE_SA by comparing the configuration.
95 * If the CHILD_SA can be created in an existing IKE_SA, the matching SA
96 * is returned.
97 * If no IKE_SA is found, a new one is created. This is also the case when
98 * the found IKE_SA is in the DELETING state.
99 *
100 * @param peer_cfg configuration used to find an existing IKE_SA
101 * @return checked out/created IKE_SA
102 */
103 ike_sa_t* (*checkout_by_config) (ike_sa_manager_t* this,
104 peer_cfg_t *peer_cfg);
105
106 /**
107 * Check for duplicates of the given IKE_SA.
108 *
109 * Measures are taken according to the uniqueness policy of the IKE_SA.
110 * The return value indicates whether duplicates have been found and if
111 * further measures should be taken (e.g. cancelling an IKE_AUTH exchange).
112 *
113 * @param ike_sa ike_sa to check
114 * @return TRUE, if the given IKE_SA has duplicates and
115 * should be deleted
116 */
117 bool (*check_uniqueness)(ike_sa_manager_t *this, ike_sa_t *ike_sa);
118
119 /**
120 * Check out an IKE_SA a unique ID.
121 *
122 * Every IKE_SA and every CHILD_SA is uniquely identified by an ID.
123 * These checkout function uses, depending
124 * on the child parameter, the unique ID of the IKE_SA or the reqid
125 * of one of a IKE_SAs CHILD_SA.
126 *
127 * @param id unique ID of the object
128 * @param child TRUE to use CHILD, FALSE to use IKE_SA
129 * @return
130 * - checked out IKE_SA, if found
131 * - NULL, if not found
132 */
133 ike_sa_t* (*checkout_by_id) (ike_sa_manager_t* this, u_int32_t id,
134 bool child);
135
136 /**
137 * Check out an IKE_SA by the policy/connection name.
138 *
139 * Check out the IKE_SA by the connections name or by a CHILD_SAs policy
140 * name.
141 *
142 * @param name name of the connection/policy
143 * @param child TRUE to use policy name, FALSE to use conn name
144 * @return
145 * - checked out IKE_SA, if found
146 * - NULL, if not found
147 */
148 ike_sa_t* (*checkout_by_name) (ike_sa_manager_t* this, char *name,
149 bool child);
150
151 /**
152 * Create an enumerator over all stored IKE_SAs.
153 *
154 * The avoid synchronization issues, the enumerator locks access
155 * to the manager exclusively, until it gets destroyed.
156 *
157 * @return enumerator over all IKE_SAs.
158 */
159 enumerator_t *(*create_enumerator) (ike_sa_manager_t* this);
160
161 /**
162 * Checkin the SA after usage.
163 *
164 * @warning the SA pointer MUST NOT be used after checkin!
165 * The SA must be checked out again!
166 * If the IKE_SA is not registered in the manager, a new entry is created.
167 *
168 * @param ike_sa_id the SA identifier, will be updated
169 * @param ike_sa checked out SA
170 */
171 void (*checkin) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
172
173 /**
174 * Destroy a checked out SA.
175 *
176 * The IKE SA is destroyed without notification of the remote peer.
177 * Use this only if the other peer doesn't respond or behaves not
178 * as predicted.
179 * Checking in and destruction is an atomic operation (for the IKE_SA),
180 * so this can be called if the SA is in a "unclean" state, without the
181 * risk that another thread can get the SA.
182 *
183 * @param ike_sa SA to delete
184 */
185 void (*checkin_and_destroy) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
186
187 /**
188 * Get the number of IKE_SAs which are in the connecting state.
189 *
190 * To prevent the server from resource exhaustion, cookies and other
191 * mechanisms are used. The number of half open IKE_SAs is a good
192 * indicator to see if a peer is flooding the server.
193 * If a host is supplied, only the number of half open IKE_SAs initiated
194 * from this IP are counted.
195 * Only SAs for which we are the responder are counted.
196 *
197 * @param ip NULL for all, IP for half open IKE_SAs with IP
198 * @return number of half open IKE_SAs
199 */
200 int (*get_half_open_count) (ike_sa_manager_t *this, host_t *ip);
201
202 /**
203 * Delete all existing IKE_SAs and destroy them immediately.
204 *
205 * Threads will be driven out, so all SAs can be deleted cleanly.
206 */
207 void (*flush)(ike_sa_manager_t *this);
208
209 /**
210 * Destroys the manager with all associated SAs.
211 *
212 * A call to flush() is required before calling destroy.
213 */
214 void (*destroy) (ike_sa_manager_t *this);
215 };
216
217 /**
218 * Create a manager.
219 *
220 * @returns ike_sa_manager_t object, NULL if initialization fails
221 */
222 ike_sa_manager_t *ike_sa_manager_create(void);
223
224 #endif /*IKE_SA_MANAGER_H_ @} */