returning reference pointer on get_ref()
[strongswan.git] / src / charon / config / peer_cfg.h
1 /*
2 * Copyright (C) 2007 Tobias Brunner
3 * Copyright (C) 2005-2007 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 peer_cfg peer_cfg
22 * @{ @ingroup config
23 */
24
25 #ifndef PEER_CFG_H_
26 #define PEER_CFG_H_
27
28 typedef enum cert_policy_t cert_policy_t;
29 typedef enum unique_policy_t unique_policy_t;
30 typedef struct peer_cfg_t peer_cfg_t;
31
32 #include <library.h>
33 #include <utils/identification.h>
34 #include <utils/enumerator.h>
35 #include <config/traffic_selector.h>
36 #include <config/proposal.h>
37 #include <config/ike_cfg.h>
38 #include <config/child_cfg.h>
39 #include <sa/authenticators/authenticator.h>
40 #include <sa/authenticators/eap/eap_method.h>
41 #include <credentials/auth_info.h>
42
43 /**
44 * Certificate sending policy. This is also used for certificate
45 * requests when using this definition for the other peer. If
46 * it is CERT_NEVER_SEND, a certreq is omitted, otherwise its
47 * included.
48 *
49 * @warning These definitions must be the same as in pluto/starter,
50 * as they are sent over the stroke socket.
51 */
52 enum cert_policy_t {
53 /** always send certificates, even when not requested */
54 CERT_ALWAYS_SEND = 0,
55 /** send certificate upon cert request */
56 CERT_SEND_IF_ASKED = 1,
57 /** never send a certificate, even when requested */
58 CERT_NEVER_SEND = 2,
59 };
60
61 /**
62 * enum strings for cert_policy_t
63 */
64 extern enum_name_t *cert_policy_names;
65
66 /**
67 * Uniqueness of an IKE_SA, used to drop multiple connections with one peer.
68 */
69 enum unique_policy_t {
70 /** do not check for client uniqueness */
71 UNIQUE_NO,
72 /** replace unique IKE_SAs if new ones get established */
73 UNIQUE_REPLACE,
74 /** keep existing IKE_SAs, close the new ones on connection attept */
75 UNIQUE_KEEP,
76 };
77
78 /**
79 * enum strings for unique_policy_t
80 */
81 extern enum_name_t *unique_policy_names;
82
83 /**
84 * Configuration of a peer, specified by IDs.
85 *
86 * The peer config defines a connection between two given IDs. It contains
87 * exactly one ike_cfg_t, which is use for initiation. Additionally, it contains
88 * multiple child_cfg_t defining which CHILD_SAs are allowed for this peer.
89 * @verbatim
90
91 +-------------------+ +---------------+
92 +---------------+ | peer_cfg | +---------------+ |
93 | ike_cfg | +-------------------+ | child_cfg | |
94 +---------------+ | - ids | +---------------+ |
95 | - hosts | 1 1 | - cas | 1 n | - proposals | |
96 | - proposals |<------| - auth info |-------->| - traffic sel | |
97 | - ... | | - dpd config | | - ... |-+
98 +---------------+ | - ... | +---------------+
99 +-------------------+
100 ^
101 |
102 +-------------------+
103 | auth_info |
104 +-------------------+
105 | auth_items |
106 +-------------------+
107 @endverbatim
108 * The auth_info_t object associated to the peer_cfg holds additional
109 * authorization constraints. A peer who wants to use a config needs to fullfil
110 * the requirements defined in auth_info.
111 */
112 struct peer_cfg_t {
113
114 /**
115 * Get the name of the peer_cfg.
116 *
117 * Returned object is not getting cloned.
118 *
119 * @return peer_cfg's name
120 */
121 char* (*get_name) (peer_cfg_t *this);
122
123 /**
124 * Get the IKE version to use for initiating.
125 *
126 * @return IKE major version
127 */
128 u_int (*get_ike_version)(peer_cfg_t *this);
129
130 /**
131 * Get the IKE config to use for initiaton.
132 *
133 * @return the IKE config to use
134 */
135 ike_cfg_t* (*get_ike_cfg) (peer_cfg_t *this);
136
137 /**
138 * Attach a CHILD config.
139 *
140 * @param child_cfg CHILD config to add
141 */
142 void (*add_child_cfg) (peer_cfg_t *this, child_cfg_t *child_cfg);
143
144 /**
145 * Detach a CHILD config, pointed to by an enumerator.
146 *
147 * @param enumerator enumerator indicating element position
148 */
149 void (*remove_child_cfg)(peer_cfg_t *this, enumerator_t *enumerator);
150
151 /**
152 * Create an enumerator for all attached CHILD configs.
153 *
154 * @return an enumerator over all CHILD configs.
155 */
156 enumerator_t* (*create_child_cfg_enumerator) (peer_cfg_t *this);
157
158 /**
159 * Select a CHILD config from traffic selectors.
160 *
161 * @param my_ts TS for local side
162 * @param other_ts TS for remote side
163 * @param my_host host to narrow down dynamic TS for local side
164 * @param other_host host to narrow down dynamic TS for remote side
165 * @return selected CHILD config, or NULL if no match found
166 */
167 child_cfg_t* (*select_child_cfg) (peer_cfg_t *this, linked_list_t *my_ts,
168 linked_list_t *other_ts, host_t *my_host,
169 host_t *other_host);
170
171 /**
172 * Get the authentication constraint items.
173 *
174 * @return auth_info object to manipulate requirements
175 */
176 auth_info_t* (*get_auth)(peer_cfg_t *this);
177
178 /**
179 * Get own ID.
180 *
181 * @return own id
182 */
183 identification_t* (*get_my_id)(peer_cfg_t *this);
184
185 /**
186 * Get peers ID.
187 *
188 * @return other id
189 */
190 identification_t* (*get_other_id)(peer_cfg_t *this);
191
192 /**
193 * Should be sent a certificate for this connection?
194 *
195 * @return certificate sending policy
196 */
197 cert_policy_t (*get_cert_policy) (peer_cfg_t *this);
198
199 /**
200 * How to handle uniqueness of IKE_SAs?
201 *
202 * @return unique policy
203 */
204 unique_policy_t (*get_unique_policy) (peer_cfg_t *this);
205
206 /**
207 * Get the authentication method to use to authenticate us.
208 *
209 * @return authentication method
210 */
211 auth_method_t (*get_auth_method) (peer_cfg_t *this);
212
213 /**
214 * Get the EAP type to use for peer authentication.
215 *
216 * If vendor specific types are used, a vendor ID != 0 is returned to
217 * to vendor argument. Then the returned type is specific for that
218 * vendor ID.
219 *
220 * @param vendor receives vendor specifier, 0 for predefined EAP types
221 * @return authentication method
222 */
223 eap_type_t (*get_eap_type) (peer_cfg_t *this, u_int32_t *vendor);
224
225 /**
226 * Get the max number of retries after timeout.
227 *
228 * @return max number retries
229 */
230 u_int32_t (*get_keyingtries) (peer_cfg_t *this);
231
232 /**
233 * Get a time to start rekeying (is randomized with jitter).
234 *
235 * @return time in s when to start rekeying, 0 disables rekeying
236 */
237 u_int32_t (*get_rekey_time)(peer_cfg_t *this);
238
239 /**
240 * Get a time to start reauthentication (is randomized with jitter).
241 *
242 * @return time in s when to start reauthentication, 0 disables it
243 */
244 u_int32_t (*get_reauth_time)(peer_cfg_t *this);
245
246 /**
247 * Get the timeout of a rekeying/reauthenticating SA.
248 *
249 * @return timeout in s
250 */
251 u_int32_t (*get_over_time)(peer_cfg_t *this);
252
253 /**
254 * Use MOBIKE (RFC4555) if peer supports it?
255 *
256 * @return TRUE to enable MOBIKE support
257 */
258 bool (*use_mobike) (peer_cfg_t *this);
259
260 /**
261 * Get the DPD check interval.
262 *
263 * @return dpd_delay in seconds
264 */
265 u_int32_t (*get_dpd) (peer_cfg_t *this);
266
267 /**
268 * Get a virtual IP for the local peer.
269 *
270 * If no virtual IP should be used, NULL is returned. %any means to request
271 * a virtual IP using configuration payloads. A specific address is also
272 * used for a request and may be changed by the server.
273 *
274 * @param suggestion NULL, %any or specific
275 * @return virtual IP, %any or NULL
276 */
277 host_t* (*get_virtual_ip) (peer_cfg_t *this);
278
279 /**
280 * Get the name of the pool to acquire configuration attributes from.
281 *
282 * @return pool name, NULL if none defined
283 */
284 char* (*get_pool)(peer_cfg_t *this);
285
286 #ifdef ME
287 /**
288 * Is this a mediation connection?
289 *
290 * @return TRUE, if this is a mediation connection
291 */
292 bool (*is_mediation) (peer_cfg_t *this);
293
294 /**
295 * Get peer_cfg of the connection this one is mediated through.
296 *
297 * @return the peer_cfg of the mediation connection
298 */
299 peer_cfg_t* (*get_mediated_by) (peer_cfg_t *this);
300
301 /**
302 * Get the id of the other peer at the mediation server.
303 *
304 * This is the leftid of the peer's connection with the mediation server.
305 *
306 * If it is not configured, it is assumed to be the same as the right id
307 * of this connection.
308 *
309 * @return the id of the other peer
310 */
311 identification_t* (*get_peer_id) (peer_cfg_t *this);
312 #endif /* ME */
313
314 /**
315 * Check if two peer configurations are equal.
316 *
317 * This method does not compare associated ike/child_cfg.
318 *
319 * @param other candidate to check for equality against this
320 * @return TRUE if peer_cfg and ike_cfg are equal
321 */
322 bool (*equals)(peer_cfg_t *this, peer_cfg_t *other);
323
324 /**
325 * Increase reference count.
326 *
327 * @return reference to this
328 */
329 peer_cfg_t* (*get_ref) (peer_cfg_t *this);
330
331 /**
332 * Destroys the peer_cfg object.
333 *
334 * Decrements the internal reference counter and
335 * destroys the peer_cfg when it reaches zero.
336 */
337 void (*destroy) (peer_cfg_t *this);
338 };
339
340 /**
341 * Create a configuration object for IKE_AUTH and later.
342 *
343 * name-string gets cloned, ID's not.
344 * Virtual IPs are used if they are != NULL. A %any host means the virtual
345 * IP should be obtained from the other peer.
346 * Lifetimes are in seconds. To prevent to peers to start rekeying at the
347 * same time, a jitter may be specified. Rekeying of an SA starts at
348 * (rekeylifetime - random(0, jitter)).
349 *
350 * @param name name of the peer_cfg
351 * @param ike_version which IKE version we sould use for this peer
352 * @param ike_cfg IKE config to use when acting as initiator
353 * @param my_id identification_t for ourselves
354 * @param other_id identification_t for the remote guy
355 * @param cert_policy should we send a certificate payload?
356 * @param unique uniqueness of an IKE_SA
357 * @param auth_method auth method to use to authenticate us
358 * @param eap_type EAP type to use for peer authentication
359 * @param eap_vendor EAP vendor identifier, if vendor specific type is used
360 * @param keyingtries how many keying tries should be done before giving up
361 * @param rekey_time timeout before starting rekeying
362 * @param reauth_time timeout before starting reauthentication
363 * @param jitter_time timerange to randomly substract from rekey/reauth time
364 * @param over_time maximum overtime before closing a rekeying/reauth SA
365 * @param reauth sould be done reauthentication instead of rekeying?
366 * @param mobike use MOBIKE (RFC4555) if peer supports it
367 * @param dpd DPD check interval, 0 to disable
368 * @param virtual_ip virtual IP for local host, or NULL
369 * @param pool pool name to get configuration attributes from, or NULL
370 * @param mediation TRUE if this is a mediation connection
371 * @param mediated_by peer_cfg_t of the mediation connection to mediate through
372 * @param peer_id ID that identifies our peer at the mediation server
373 * @return peer_cfg_t object
374 */
375 peer_cfg_t *peer_cfg_create(char *name, u_int ikev_version, ike_cfg_t *ike_cfg,
376 identification_t *my_id, identification_t *other_id,
377 cert_policy_t cert_policy, unique_policy_t unique,
378 auth_method_t auth_method, eap_type_t eap_type,
379 u_int32_t eap_vendor,
380 u_int32_t keyingtries, u_int32_t rekey_time,
381 u_int32_t reauth_time, u_int32_t jitter_time,
382 u_int32_t over_time, bool mobike, u_int32_t dpd,
383 host_t *virtual_ip, char *pool,
384 bool mediation, peer_cfg_t *mediated_by,
385 identification_t *peer_id);
386
387 #endif /* PEER_CFG_H_ @} */