implemented IKE_SA uniqueness using ipsec.conf uniqueids paramater
[strongswan.git] / src / charon / sa / ike_sa_manager.h
1 /*
2 * Copyright (C) 2005-2006 Martin Willi
3 * Copyright (C) 2005 Jan Hutter
4 * Hochschule fuer Technik Rapperswil
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 *
16 * $Id$
17 */
18
19 /**
20 * @defgroup ike_sa_manager ike_sa_manager
21 * @{ @ingroup sa
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 * 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 struct ike_sa_manager_t {
47
48 /**
49 * Checkout an existing IKE_SA.
50 *
51 * @param ike_sa_id the SA identifier, will be updated
52 * @returns
53 * - checked out IKE_SA if found
54 * - NULL, if specified IKE_SA is not found.
55 */
56 ike_sa_t* (*checkout) (ike_sa_manager_t* this, ike_sa_id_t *sa_id);
57
58 /**
59 * Create and check out a new IKE_SA.
60 *
61 * @param initiator TRUE for initiator, FALSE otherwise
62 * @returns created andchecked out IKE_SA
63 */
64 ike_sa_t* (*checkout_new) (ike_sa_manager_t* this, bool initiator);
65
66 /**
67 * Checkout an IKE_SA by a message.
68 *
69 * In some situations, it is necessary that the manager knows the
70 * message to use for the checkout. This has the folloing reasons:
71 *
72 * 1. If the targeted IKE_SA is already processing a message, we do not
73 * check it out if the message ID is the same.
74 * 2. If it is an IKE_SA_INIT request, we have to check if it is a
75 * retransmission. If so, we have to drop the message, we would
76 * create another unneded IKE_SA for each retransmitted packet.
77 *
78 * A call to checkout_by_message() returns a (maybe new created) IKE_SA.
79 * If processing the message does not make sense (for the reasons above),
80 * NULL is returned.
81 *
82 * @param ike_sa_id the SA identifier, will be updated
83 * @returns
84 * - checked out/created IKE_SA
85 * - NULL to not process message further
86 */
87 ike_sa_t* (*checkout_by_message) (ike_sa_manager_t* this, message_t *message);
88
89 /**
90 * Checkout an IKE_SA for initiation by a peer_config.
91 *
92 * To initiate, a CHILD_SA may be established within an existing IKE_SA.
93 * This call checks for an existing IKE_SA by comparing the configuration.
94 * If the CHILD_SA can be created in an existing IKE_SA, the matching SA
95 * is returned.
96 * If no IKE_SA is found, a new one is created. This is also the case when
97 * the found IKE_SA is in the DELETING state.
98 *
99 * @param peer_cfg configuration used to find an existing IKE_SA
100 * @return checked out/created IKE_SA
101 */
102 ike_sa_t* (*checkout_by_config) (ike_sa_manager_t* this,
103 peer_cfg_t *peer_cfg);
104
105 /**
106 * Check out a duplicate if ike_sa to do uniqueness tests.
107 *
108 * @param ike_sa ike_sa to get a duplicate from
109 * @return checked out duplicate
110 */
111 ike_sa_t* (*checkout_duplicate)(ike_sa_manager_t *this, ike_sa_t *ike_sa);
112
113 /**
114 * Check out an IKE_SA a unique ID.
115 *
116 * Every IKE_SA and every CHILD_SA is uniquely identified by an ID.
117 * These checkout function uses, depending
118 * on the child parameter, the unique ID of the IKE_SA or the reqid
119 * of one of a IKE_SAs CHILD_SA.
120 *
121 * @param id unique ID of the object
122 * @param child TRUE to use CHILD, FALSE to use IKE_SA
123 * @return
124 * - checked out IKE_SA, if found
125 * - NULL, if not found
126 */
127 ike_sa_t* (*checkout_by_id) (ike_sa_manager_t* this, u_int32_t id,
128 bool child);
129
130 /**
131 * Check out an IKE_SA by the policy/connection name.
132 *
133 * Check out the IKE_SA by the connections name or by a CHILD_SAs policy
134 * name.
135 *
136 * @param name name of the connection/policy
137 * @param child TRUE to use policy name, FALSE to use conn name
138 * @return
139 * - checked out IKE_SA, if found
140 * - NULL, if not found
141 */
142 ike_sa_t* (*checkout_by_name) (ike_sa_manager_t* this, char *name,
143 bool child);
144
145 /**
146 * Create an enumerator over all stored IKE_SAs.
147 *
148 * The avoid synchronization issues, the enumerator locks access
149 * to the manager exclusively, until it gets destroyed.
150 *
151 * @return enumerator over all IKE_SAs.
152 */
153 enumerator_t *(*create_enumerator) (ike_sa_manager_t* this);
154
155 /**
156 * Checkin the SA after usage.
157 *
158 * @warning the SA pointer MUST NOT be used after checkin!
159 * The SA must be checked out again!
160 *
161 * @param ike_sa_id the SA identifier, will be updated
162 * @param ike_sa checked out SA
163 * @returns
164 * - SUCCESS if checked in
165 * - NOT_FOUND when not found (shouldn't happen!)
166 */
167 status_t (*checkin) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
168
169 /**
170 * Destroy a checked out SA.
171 *
172 * The IKE SA is destroyed without notification of the remote peer.
173 * Use this only if the other peer doesn't respond or behaves not
174 * as predicted.
175 * Checking in and destruction is an atomic operation (for the IKE_SA),
176 * so this can be called if the SA is in a "unclean" state, without the
177 * risk that another thread can get the SA.
178 *
179 * @param ike_sa SA to delete
180 * @returns
181 * - SUCCESS if found
182 * - NOT_FOUND when no such SA is available
183 */
184 status_t (*checkin_and_destroy) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
185
186 /**
187 * Get the number of IKE_SAs which are in the connecting state.
188 *
189 * To prevent the server from resource exhaustion, cookies and other
190 * mechanisms are used. The number of half open IKE_SAs is a good
191 * indicator to see if a peer is flooding the server.
192 * If a host is supplied, only the number of half open IKE_SAs initiated
193 * from this IP are counted.
194 * Only SAs for which we are the responder are counted.
195 *
196 * @param ip NULL for all, IP for half open IKE_SAs with IP
197 * @return number of half open IKE_SAs
198 */
199 int (*get_half_open_count) (ike_sa_manager_t *this, host_t *ip);
200
201 /**
202 * Destroys the manager with all associated SAs.
203 *
204 * Threads will be driven out, so all SAs can be deleted cleanly.
205 */
206 void (*destroy) (ike_sa_manager_t *this);
207 };
208
209 /**
210 * Create a manager.
211 *
212 * @returns ike_sa_manager_t object, NULL if initialization fails
213 */
214 ike_sa_manager_t *ike_sa_manager_create(void);
215
216 #endif /*IKE_SA_MANAGER_H_ @} */