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