updated Doxyfile
[strongswan.git] / src / charon / config / child_cfg.h
1 /*
2 * Copyright (C) 2008 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 child_cfg child_cfg
22 * @{ @ingroup config
23 */
24
25 #ifndef CHILD_CFG_H_
26 #define CHILD_CFG_H_
27
28 typedef enum action_t action_t;
29 typedef enum ipcomp_transform_t ipcomp_transform_t;
30 typedef struct child_cfg_t child_cfg_t;
31
32 #include <library.h>
33 #include <config/proposal.h>
34 #include <config/traffic_selector.h>
35 #include <kernel/kernel_ipsec.h>
36
37 /**
38 * Action to take when DPD detected/connection gets closed by peer.
39 */
40 enum action_t {
41 /** No action */
42 ACTION_NONE,
43 /** Route config to reestablish on demand */
44 ACTION_ROUTE,
45 /** Restart config immediately */
46 ACTION_RESTART,
47 };
48
49 /**
50 * enum names for action_t.
51 */
52 extern enum_name_t *action_names;
53
54 /**
55 * IPComp transform IDs, as in RFC 4306
56 */
57 enum ipcomp_transform_t {
58 IPCOMP_NONE = 241,
59 IPCOMP_OUI = 1,
60 IPCOMP_DEFLATE = 2,
61 IPCOMP_LZS = 3,
62 IPCOMP_LZJH = 4,
63 };
64
65 /**
66 * enum strings for ipcomp_transform_t.
67 */
68 extern enum_name_t *ipcomp_transform_names;
69
70 /**
71 * A child_cfg_t defines the config template for a CHILD_SA.
72 *
73 * After creation, proposals and traffic selectors may be added to the config.
74 * A child_cfg object is referenced multiple times, and is not thread save.
75 * Reading from the object is save, adding things is not allowed while other
76 * threads may access the object.
77 * A reference counter handles the number of references hold to this config.
78 *
79 * @see peer_cfg_t to get an overview over the configurations.
80 */
81 struct child_cfg_t {
82
83 /**
84 * Get the name of the child_cfg.
85 *
86 * @return child_cfg's name
87 */
88 char *(*get_name) (child_cfg_t *this);
89
90 /**
91 * Add a proposal to the list.
92 *
93 * The proposals are stored by priority, first added
94 * is the most prefered.
95 * After add, proposal is owned by child_cfg.
96 *
97 * @param proposal proposal to add
98 */
99 void (*add_proposal) (child_cfg_t *this, proposal_t *proposal);
100
101 /**
102 * Get the list of proposals for the CHILD_SA.
103 *
104 * Resulting list and all of its proposals must be freed after use.
105 *
106 * @param strip_dh TRUE strip out diffie hellman groups
107 * @return list of proposals
108 */
109 linked_list_t* (*get_proposals)(child_cfg_t *this, bool strip_dh);
110
111 /**
112 * Select a proposal from a supplied list.
113 *
114 * Returned propsal is newly created and must be destroyed after usage.
115 *
116 * @param proposals list from from wich proposals are selected
117 * @param strip_dh TRUE strip out diffie hellman groups
118 * @return selected proposal, or NULL if nothing matches
119 */
120 proposal_t* (*select_proposal)(child_cfg_t*this, linked_list_t *proposals,
121 bool strip_dh);
122
123 /**
124 * Add a traffic selector to the config.
125 *
126 * Use the "local" parameter to add it for the local or the remote side.
127 * After add, traffic selector is owned by child_cfg.
128 *
129 * @param local TRUE for local side, FALSE for remote
130 * @param ts traffic_selector to add
131 */
132 void (*add_traffic_selector)(child_cfg_t *this, bool local,
133 traffic_selector_t *ts);
134
135 /**
136 * Get a list of traffic selectors to use for the CHILD_SA.
137 *
138 * The config contains two set of traffic selectors, one for the local
139 * side, one for the remote side.
140 * If a list with traffic selectors is supplied, these are used to narrow
141 * down the traffic selector list to the greatest common divisor.
142 * Some traffic selector may be "dymamic", meaning they are narrowed down
143 * to a specific address (host-to-host or virtual-IP setups). Use
144 * the "host" parameter to narrow such traffic selectors to that address.
145 * Resulted list and its traffic selectors must be destroyed after use.
146 *
147 * @param local TRUE for TS on local side, FALSE for remote
148 * @param supplied list with TS to select from, or NULL
149 * @param host address to use for narrowing "dynamic" TS', or NULL
150 * @return list containing the traffic selectors
151 */
152 linked_list_t *(*get_traffic_selectors)(child_cfg_t *this, bool local,
153 linked_list_t *supplied,
154 host_t *host);
155
156 /**
157 * Checks [single] traffic selectors for equality
158 *
159 * @param local TRUE for TS on local side, FALSE for remote
160 * @param ts list with single traffic selector to compare with
161 * @param host address to use for narrowing "dynamic" TS', or NULL
162 * @return TRUE if TS are equal, FALSE otherwise
163 */
164 bool (*equal_traffic_selectors)(child_cfg_t *this, bool local,
165 linked_list_t *ts_list, host_t *host);
166
167 /**
168 * Get the updown script to run for the CHILD_SA.
169 *
170 * @return path to updown script
171 */
172 char* (*get_updown)(child_cfg_t *this);
173
174 /**
175 * Should we allow access to the local host (gateway)?
176 *
177 * @return value of hostaccess flag
178 */
179 bool (*get_hostaccess) (child_cfg_t *this);
180
181 /**
182 * Get the lifetime of a CHILD_SA.
183 *
184 * If "rekey" is set to TRUE, a lifetime is returned before the first
185 * rekeying should be started. If it is FALSE, the actual lifetime is
186 * returned when the CHILD_SA must be deleted.
187 * The rekey time automatically contains a jitter to avoid simlutaneous
188 * rekeying.
189 *
190 * @param rekey TRUE to get rekey time
191 * @return lifetime in seconds
192 */
193 u_int32_t (*get_lifetime) (child_cfg_t *this, bool rekey);
194
195 /**
196 * Get the mode to use for the CHILD_SA.
197 *
198 * The mode is either tunnel, transport or BEET. The peer must agree
199 * on the method, fallback is tunnel mode.
200 *
201 * @return ipsec mode
202 */
203 ipsec_mode_t (*get_mode) (child_cfg_t *this);
204
205 /**
206 * Action to take on DPD.
207 *
208 * @return DPD action
209 */
210 action_t (*get_dpd_action) (child_cfg_t *this);
211
212 /**
213 * Action to take if CHILD_SA gets closed.
214 *
215 * @return close action
216 */
217 action_t (*get_close_action) (child_cfg_t *this);
218
219 /**
220 * Get the DH group to use for CHILD_SA setup.
221 *
222 * @return dh group to use
223 */
224 diffie_hellman_group_t (*get_dh_group)(child_cfg_t *this);
225
226 /**
227 * Check whether IPComp should be used, if the other peer supports it.
228 *
229 * @return TRUE, if IPComp should be used
230 * FALSE, otherwise
231 */
232 bool (*use_ipcomp)(child_cfg_t *this);
233
234 /**
235 * Sets two options needed for Mobile IPv6 interoperability
236 *
237 * @param proxy_mode use IPsec transport proxy mode (default FALSE)
238 * @param install_policy install IPsec kernel policies (default TRUE)
239 */
240 void (*set_mipv6_options)(child_cfg_t *this, bool proxy_mode,
241 bool install_policy);
242
243 /**
244 * Check whether IPsec transport SA should be set up in proxy mode
245 *
246 * @return TRUE, if proxy mode should be used
247 * FALSE, otherwise
248 */
249 bool (*use_proxy_mode)(child_cfg_t *this);
250
251 /**
252 * Check whether IPsec policies should be installed in the kernel
253 *
254 * @return TRUE, if IPsec kernel policies should be installed
255 * FALSE, otherwise
256 */
257 bool (*install_policy)(child_cfg_t *this);
258
259 /**
260 * Increase the reference count.
261 *
262 * @return reference to this
263 */
264 child_cfg_t* (*get_ref) (child_cfg_t *this);
265
266 /**
267 * Destroys the child_cfg object.
268 *
269 * Decrements the internal reference counter and
270 * destroys the child_cfg when it reaches zero.
271 */
272 void (*destroy) (child_cfg_t *this);
273 };
274
275 /**
276 * Create a configuration template for CHILD_SA setup.
277 *
278 * The "name" string gets cloned.
279 * Lifetimes are in seconds. To prevent to peers to start rekeying at the
280 * same time, a jitter may be specified. Rekeying of an SA starts at
281 * (rekeytime - random(0, jitter)). You should specify
282 * lifetime > rekeytime > jitter.
283 * After a call to create, a reference is obtained (refcount = 1).
284 *
285 * @param name name of the child_cfg
286 * @param lifetime lifetime after CHILD_SA expires and gets deleted
287 * @param rekeytime time when rekeying should be initiated
288 * @param jitter range of randomization time to remove from rekeytime
289 * @param updown updown script to execute on up/down event
290 * @param hostaccess TRUE to allow access to the local host
291 * @param mode mode to propose for CHILD_SA, transport, tunnel or BEET
292 * @param dpd_action DPD action
293 * @param close_action close action
294 * @param ipcomp use IPComp, if peer supports it
295 * @return child_cfg_t object
296 */
297 child_cfg_t *child_cfg_create(char *name, u_int32_t lifetime,
298 u_int32_t rekeytime, u_int32_t jitter,
299 char *updown, bool hostaccess, ipsec_mode_t mode,
300 action_t dpd_action, action_t close_action, bool ipcomp);
301
302 #endif /** CHILD_CFG_H_ @}*/