split connections with different virtual IPs in different peer_cfgs
[strongswan.git] / src / charon / sa / ike_sa_manager.h
1 /**
2 * @file ike_sa_manager.h
3 *
4 * @brief Interface of ike_sa_manager_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2005-2006 Martin Willi
10 * Copyright (C) 2005 Jan Hutter
11 * Hochschule fuer Technik Rapperswil
12 *
13 * This program is free software; you can redistribute it and/or modify it
14 * under the terms of the GNU General Public License as published by the
15 * Free Software Foundation; either version 2 of the License, or (at your
16 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
17 *
18 * This program is distributed in the hope that it will be useful, but
19 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
20 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21 * for more details.
22 */
23
24 #ifndef IKE_SA_MANAGER_H_
25 #define IKE_SA_MANAGER_H_
26
27 typedef struct ike_sa_manager_t ike_sa_manager_t;
28
29 #include <library.h>
30 #include <sa/ike_sa.h>
31 #include <encoding/message.h>
32 #include <config/peer_cfg.h>
33
34 /**
35 * @brief The IKE_SA-Manager is responsible for managing all initiated and responded IKE_SA's.
36 *
37 * To avoid access from multiple threads, IKE_SAs must be checked out from
38 * the manager, and checked in after usage.
39 * The manager also handles deletion of SAs.
40 *
41 * @todo checking of double-checkouts from the same threads would be nice.
42 * This could be done by comparing thread-ids via pthread_self()...
43 *
44 * @todo Managing of ike_sa_t objects in a hash table instead of linked list.
45 *
46 * @b Constructors:
47 * - ike_sa_manager_create()
48 *
49 * @ingroup sa
50 */
51 struct ike_sa_manager_t {
52
53 /**
54 * @brief Checkout an existing IKE_SA.
55 *
56 * @param this the manager object
57 * @param ike_sa_id the SA identifier, will be updated
58 * @returns
59 * - checked out IKE_SA if found
60 * - NULL, if specified IKE_SA is not found.
61 */
62 ike_sa_t* (*checkout) (ike_sa_manager_t* this, ike_sa_id_t *sa_id);
63
64 /**
65 * @brief Create and check out a new IKE_SA.
66 *
67 * @param this the manager object
68 * @param initiator TRUE for initiator, FALSE otherwise
69 * @returns created andchecked out IKE_SA
70 */
71 ike_sa_t* (*checkout_new) (ike_sa_manager_t* this, bool initiator);
72
73 /**
74 * @brief Checkout an IKE_SA by a message.
75 *
76 * In some situations, it is necessary that the manager knows the
77 * message to use for the checkout. This has the folloing reasons:
78 *
79 * 1. If the targeted IKE_SA is already processing a message, we do not
80 * check it out if the message ID is the same.
81 * 2. If it is an IKE_SA_INIT request, we have to check if it is a
82 * retransmission. If so, we have to drop the message, we would
83 * create another unneded IKE_SA for each retransmitted packet.
84 *
85 * A call to checkout_by_message() returns a (maybe new created) IKE_SA.
86 * If processing the message does not make sense (for the reasons above),
87 * NULL is returned.
88 *
89 * @param this the manager object
90 * @param ike_sa_id the SA identifier, will be updated
91 * @returns
92 * - checked out/created IKE_SA
93 * - NULL to not process message further
94 */
95 ike_sa_t* (*checkout_by_message) (ike_sa_manager_t* this, message_t *message);
96
97 /**
98 * @brief Checkout an IKE_SA for initiation by a peer_config.
99 *
100 * To initiate, a CHILD_SA may be established within an existing IKE_SA.
101 * This call checks for an existing IKE_SA by comparing the configuration.
102 * If the CHILD_SA can be created in an existing IKE_SA, the matching SA
103 * is returned.
104 * If no IKE_SA is found, a new one is created. This is also the case when
105 * the found IKE_SA is in the DELETING state.
106 *
107 * @param this the manager object
108 * @param peer_cfg configuration used to find an existing IKE_SA
109 * @return checked out/created IKE_SA
110 */
111 ike_sa_t* (*checkout_by_config) (ike_sa_manager_t* this,
112 peer_cfg_t *peer_cfg);
113
114 /**
115 * @brief Check out an IKE_SA a unique ID.
116 *
117 * Every IKE_SA and every CHILD_SA is uniquely identified by an ID.
118 * These checkout function uses, depending
119 * on the child parameter, the unique ID of the IKE_SA or the reqid
120 * of one of a IKE_SAs CHILD_SA.
121 *
122 * @param this the manager object
123 * @param id unique ID of the object
124 * @param child TRUE to use CHILD, FALSE to use IKE_SA
125 * @return
126 * - checked out IKE_SA, if found
127 * - NULL, if not found
128 */
129 ike_sa_t* (*checkout_by_id) (ike_sa_manager_t* this, u_int32_t id,
130 bool child);
131
132 /**
133 * @brief Check out an IKE_SA by the policy/connection name.
134 *
135 * Check out the IKE_SA by the connections name or by a CHILD_SAs policy
136 * name.
137 *
138 * @param this the manager object
139 * @param name name of the connection/policy
140 * @param child TRUE to use policy name, FALSE to use conn name
141 * @return
142 * - checked out IKE_SA, if found
143 * - NULL, if not found
144 */
145 ike_sa_t* (*checkout_by_name) (ike_sa_manager_t* this, char *name,
146 bool child);
147
148 /**
149 * @brief Create an iterator over all stored IKE_SAs.
150 *
151 * The avoid synchronization issues, the iterator locks access
152 * to the manager exclusively, until it gets destroyed.
153 * This iterator is for reading only! Writing will corrupt the manager.
154 *
155 * @param this the manager object
156 * @return iterator over all IKE_SAs.
157 */
158 iterator_t *(*create_iterator) (ike_sa_manager_t* this);
159
160 /**
161 * @brief Checkin the SA after usage.
162 *
163 * @warning the SA pointer MUST NOT be used after checkin!
164 * The SA must be checked out again!
165 *
166 * @param this the manager object
167 * @param ike_sa_id the SA identifier, will be updated
168 * @param ike_sa checked out SA
169 * @returns
170 * - SUCCESS if checked in
171 * - NOT_FOUND when not found (shouldn't happen!)
172 */
173 status_t (*checkin) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
174
175 /**
176 * @brief Destroy a checked out SA.
177 *
178 * The IKE SA is destroyed without notification of the remote peer.
179 * Use this only if the other peer doesn't respond or behaves not
180 * as predicted.
181 * Checking in and destruction is an atomic operation (for the IKE_SA),
182 * so this can be called if the SA is in a "unclean" state, without the
183 * risk that another thread can get the SA.
184 *
185 * @param this the manager object
186 * @param ike_sa SA to delete
187 * @returns
188 * - SUCCESS if found
189 * - NOT_FOUND when no such SA is available
190 */
191 status_t (*checkin_and_destroy) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
192
193 /**
194 * @brief 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 this the manager object
204 * @param ip NULL for all, IP for half open IKE_SAs with IP
205 * @return number of half open IKE_SAs
206 */
207 int (*get_half_open_count) (ike_sa_manager_t *this, host_t *ip);
208
209 /**
210 * @brief Destroys the manager with all associated SAs.
211 *
212 * Threads will be driven out, so all SAs can be deleted cleanly.
213 *
214 * @param this the manager object
215 */
216 void (*destroy) (ike_sa_manager_t *this);
217 };
218
219 /**
220 * @brief Create a manager.
221 *
222 * @returns ike_sa_manager_t object
223 *
224 * @ingroup sa
225 */
226 ike_sa_manager_t *ike_sa_manager_create(void);
227
228 #endif /*IKE_SA_MANAGER_H_*/